Sample Code Blue Documentation

[Nickie Koskinen]

Anintroduction to the pyplot interface. Please also seeQuick start guide for an overview of how Matplotlibworks and Matplotlib Application Interfaces (APIs) for an explanation of the trade-offs between thesupported user APIs.

matplotlib.pyplot is a collection of functions that make matplotlibwork like MATLAB. Each pyplot function makes some change to a figure:e.g., creates a figure, creates a plotting area in a figure, plots some linesin a plotting area, decorates the plot with labels, etc.

In matplotlib.pyplot various states are preservedacross function calls, so that it keeps track of things likethe current figure and plotting area, and the plottingfunctions are directed to the current Axes (please note that we use uppercaseAxes to refer to the Axes concept, which is a centralpart of a figureand not only the plural of axis).

The implicit pyplot API is generally less verbose but also not as flexible as theexplicit API. Most of the function calls you see here can also be calledas methods from an Axes object. We recommend browsing the tutorialsand examples to see how this works. See Matplotlib Application Interfaces (APIs) for anexplanation of the trade-off of the supported user APIs.

You may be wondering why the x-axis ranges from 0-3 and the y-axisfrom 1-4. If you provide a single list or array toplot, matplotlib assumes it is asequence of y values, and automatically generates the x values foryou. Since python ranges start with 0, the default x vector has thesame length as y but starts with 0; therefore, the x data are[0, 1, 2, 3].

For every x, y pair of arguments, there is an optional third argumentwhich is the format string that indicates the color and line type ofthe plot. The letters and symbols of the format string are fromMATLAB, and you concatenate a color string with a line style string.The default format string is 'b-', which is a solid blue line. Forexample, to plot the above with red circles, you would issue

If matplotlib were limited to working with lists, it would be fairlyuseless for numeric processing. Generally, you will use numpy arrays. In fact, all sequences areconverted to numpy arrays internally. The example below illustratesplotting several lines with different format styles in one function callusing arrays.

Use the setter methods of a Line2D instance. plot returns a listof Line2D objects; e.g., line1, line2 = plot(x1, y1, x2, y2). In the codebelow we will suppose that we have onlyone line so that the list returned is of length 1. We use tuple unpacking withline, to get the first element of that list:

Use setp. The example belowuses a MATLAB-style function to set multiple propertieson a list of lines. setp works transparently with a list of objectsor a single object. You can either use python keyword arguments orMATLAB-style string/value pairs:

MATLAB, and pyplot, have the concept of the current figureand the current Axes. All plotting functions apply to the currentAxes. The function gca returns the current Axes (amatplotlib.axes.Axes instance), and gcf returns the currentfigure (a matplotlib.figure.Figure instance). Normally, you don't have toworry about this, because it is all taken care of behind the scenes. Belowis a script to create two subplots.

The figure call here is optional because a figure will be createdif none exists, just as an Axes will be created (equivalent to an explicitsubplot() call) if none exists.The subplot call specifies numrows,numcols, plot_number where plot_number ranges from 1 tonumrows*numcols. The commas in the subplot call areoptional if numrows*numcols

You can create an arbitrary number of subplotsand Axes. If you want to place an Axes manually, i.e., not on arectangular grid, use axes,which allows you to specify the location as axes([left, bottom,width, height]) where all values are in fractional (0 to 1)coordinates. See Axes Demo for an example ofplacing Axes manually and Multiple subplots for anexample with lots of subplots.

You can clear the current figure with clfand the current Axes with cla. If you findit annoying that states (specifically the current image, figure and Axes)are being maintained for you behind the scenes, don't despair: this is just a thinstateful wrapper around an object-oriented API, which you can useinstead (see Artist tutorial)

If you are making lots of figures, you need to be aware of onemore thing: the memory required for a figure is not completelyreleased until the figure is explicitly closed withclose. Deleting all references to thefigure, and/or using the window manager to kill the window in whichthe figure appears on the screen, is not enough, because pyplotmaintains internal references until closeis called.

The r preceding the title string is important -- it signifiesthat the string is a raw string and not to treat backslashes aspython escapes. matplotlib has a built-in TeX expression parser andlayout engine, and ships its own math fonts -- for details seeWriting mathematical expressions. Thus, you can use mathematical text acrossplatforms without requiring a TeX installation. For those who have LaTeXand dvipng installed, you can also use LaTeX to format your text andincorporate the output directly into your display figures or savedpostscript -- see Text rendering with LaTeX.

The uses of the basic text function aboveplace text at an arbitrary position on the Axes. A common use fortext is to annotate some feature of the plot, and theannotate method provides helperfunctionality to make annotations easy. In an annotation, there aretwo points to consider: the location being annotated represented bythe argument xy and the location of the text xytext. Both ofthese arguments are (x, y) tuples.

In this basic example, both the xy (arrow tip) and xytextlocations (text location) are in data coordinates. There are avariety of other coordinate systems one can choose -- seeBasic annotation and Advanced annotation fordetails. More examples can be found inAnnotating Plots.

C# provides a mechanism for programmers to document their code using a comment syntax that contains XML text. In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Comments using such syntax are called documentation comments. They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method). The XML generation tool is called the documentation generator. (This generator could be, but need not be, the C# compiler itself.) The output produced by the documentation generator is called the documentation file. A documentation file is used as input to a documentation viewer; a tool intended to produce some sort of visual display of type information and its associated documentation.

This specification suggests a set of standard tags to be used in documentation comments, but use of these tags is not required, and other tags may be used if desired, as long as the rules of well-formed XML are followed. For C# implementations targeting the CLI, it also provides information about the documentation generator and the format of the documentation file. No information is provided about the documentation viewer.

Comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements that they precede. Such comments are Single_Line_Comments (6.3.3) that start with three slashes (///), or Delimited_Comments (6.3.3) that start with a slash and two asterisks (/**). They must immediately precede a user-defined type or a member that they annotate. Attribute sections (22.3) are considered part of declarations, so documentation comments must precede attributes applied to a type or member.

For expository purposes, the format of document comments is shown below as two grammar rules: Single_Line_Doc_Comment and Delimited_Doc_Comment. However, these rules are not part of the C# grammar, but rather, they represent particular formats of Single_Line_Comment and Delimited_Comment lexer rules, respectively.

In a Single_Line_Doc_Comment, if there is a Whitespace character following the /// characters on each of the Single_Line_Doc_Comments adjacent to the current Single_Line_Doc_Comment, then that Whitespace character is not included in the XML output.

In a Delimited_Doc_Comment, if the first non-Whitespace character on the second line is an ASTERISK and the same pattern of optional Whitespace characters and an ASTERISK character is repeated at the beginning of each of the lines within the Delimited_Doc_Comment, then the characters of the repeated pattern are not included in the XML output. The pattern can include Whitespace characters after, as well as before, the ASTERISK character.

The text within documentation comments must be well formed according to the rules of XML ( -xml). If the XML is ill formed, a warning is generated and the documentation file will contain a comment saying that an error was encountered.

The tag is used to describe parameters. If such a tag is used, the documentation generator must verify that the specified parameter exists and that all parameters are described in documentation comments. If such verification fails, the documentation generator issues a warning.

Note carefully that the documentation file does not provide full information about the type and members (for example, it does not contain any type information). To get such information about a type or member, the documentation file must be used in conjunction with reflection on the type or member.

The documentation generator must accept and process any tag that is valid according to the rules of XML. The following tags provide commonly used functionality in user documentation. (Of course, other tags are possible.)

This tag allows including information from an XML document that is external to the source code file. The external file must be a well-formed XML document, and an XPath expression is applied to that document to specify what XML from that document to include. The tag is then replaced with the selected XML from the external document.

3a8082e126