Plotting

Figure object.

class storylines.plot.Plot(width=None, height=None, margin=None, xyaxes=True, style=None, rounded=True, **more)[source]

Plot object.

Parameters:

widthfloat, default None: Figure width in cm. A negative value is interpreted as the inner width (without left and right margins). If zero, the x-axis scale is set equal to the y-axis scale and the width is inferred from the height. By default, the single-column width for the chosen style is used.
heightfloat, default None: Figure height in cm. A negative value is interpreted as the inner height (without bottom and top margins). If zero, the y-axis scale is set equal to the x-axis scale and the height is inferred from the width. By default, it is inferred from width for a 4:3 aspect ratio.
marginfloat, default None: Default margin in cm. If None, margins are set automatically. This is not always the best option.
xyaxesbool, default True: Draw x and y axes?
stylestr, default None: Predefined style. Possible values are 'APS', 'NanoLett', 'NatCommun', and 'Nature'. This changes some of the below default values.
roundedbool, default True: Use round as default value for line cap and line join? Otherwise the TikZ initial values miter and butt are used.
**more: Initial values of attributes (see below) or global TikZ options.

Attributes:

leftfloat, default margin: Left margin in cm.
rightfloat, default margin: Right margin in cm.
bottomfloat, default margin: Bottom margin in cm.
topfloat, default margin: Top margin in cm.
margminfloat, default 0.15: Minimum automatic margin in cm.
ratiofloat, default None: Figure width divided by figure height. The desired aspect ratio is obtained by adding extra margins as needed.
alignfloat, default 0.5: If ratio is used, this value aligns the original plot relative to the new viewport. A value of 0.0, 0.5, and 1.0 moves it to the lower side, to the center, and to the upper side, respectively.
xlabel, ylabel, zlabelstr, default None: Axis labels.
xticks, yticks, ztickslist, default None: List of ticks, e.g., [0, (0.5, '$\\frac12$'), 1]. If the label is None, the tick mark is not drawn (but possibe grid lines are). If it otherwise evaluates to False, the tick mark but no label is drawn.
xmarks, ymarks, zmarksbool, default True: Show tick marks and labels?
xlabels, ylabels, zlabelsbool, default True: Show tick labels?
xspacing, yspacing, zspacingfloat, default 1.0: Approximate tick spacing in cm.
xstep, ystep, zstepfloat, default None: Exact tick increment.
xminorticks, yminortickslist, default None: List of minor-tick positions. There is currently no intelligent way to set the minor ticks depending on the major ticks. However, minor ticks that fall on major ticks are omitted.
xminormarks, yminormarksbool, default False: Show minor tick marks?
xminorspacing, yminorspacingfloat, default None: Approximate minor-tick spacing in cm.
xminorstep, yminorstepfloat, default None: Exact minor-tick increment.
xmin, ymin, zminfloat, default None: Lower axis limit.
xmax, ymax, zmaxfloat, default None: Upper axis limit.
dleft, dright, dbottom, dtopfloat, default 0.0: Protrusion of x- and y-axis limits into margins in cm.
xpadding, ypadding, zpaddingfloat, default 0.0: Padding between data and axes in data units.
xclose, yclose, zclosebool, default False: Place axis labels in space reserved for tick labels.
xformat, yformat, zformatfunction: Tick formatter. Takes tick position as argument.
lowerstr, default ‘blue’: Lower color of colorbar. Can also be of type Color as long as upper has the same type.
upperstr, default ‘red’: Upper color of colorbar. Can also be of type Color as long as lower has the same type.
cmapfunction, default None: Colormap for colorbar used instead of lower and upper.
titlestr, default None: Plot title.
labelstr, default None: Subfigure label, e.g., 'a'.
labelsizeint, default None: Different font size for subfigure label in pt.
labelformatfunction, default None: Formatter for subfigure label. Takes label as argument.
labeloptstr, default ‘inner sep=0pt, below right’: Label options, e.g., for orientation.
labelposstr, default ‘LT’: Label position, a combination of lcrbmtLCRBMT or a tuple of data coordinates.
lalistr, default ‘center’: Alignment of legend entries.
lblsstr, default ‘\\baselineskip’: Line height of legend entries.
lboxbool, default False: Draw box around legend?
lcolint, default 1: Number of columns in legend.
llenstr, default ‘4mm’: Length of example lines next to labels.
loptstr, default None: Legend options, e.g., for orientation.
lposstr, default ‘cm’: Legend position, a combination of lcrbmtLCRBMT or a tuple of data coordinates.
lputbool, default True: Draw legend?
lrowint, default 0: Number of rows in legend.
lsepstr, default None: Space between legend title and entries, e.g., '6pt'.
ltopstr, default None: Legend title. If lbox is used, you might want to prevent that TikZ pictures in the legend inherit the rounded corners of the box by prepending \tikzset{sharp corners} to this value.
lwidfloat, default 4.0: Width of legend columns in units of llen.
tickfloat, default 0.07: Length of tick marks in cm.
minortickfloat, default 0.04: Length of minor tick marks in cm.
gapfloat, default 0.15: Gap between plot area and colorbar in cm.
barfloat, default 0.15: Width of color bar in cm.
tipfloat, default 0.1: Overlap of axis tips in cm.
xaxisbool, default xyaxes: Draw x axis?
yaxisbool, default xyaxes: Draw y axis?
xoriginfloat, default None: Horizontal position of y axis in data coordinates. A reasonable value could be zero. By default, the y axis is shown on the left.
yoriginfloat, default None: Vertical position of x axis in data coordinates. A reasonable value could be zero. By default, the x axis is shown on the bottom.
framebool, default xyaxes: Draw frame around plot area?
gridbool, default False: Add grid lines at tick positions?
minorgridbool, default False: Add grid lines at minor-tick positions?
colorbarbool or str, default None: Draw colorbar? If None, the colorbar is drawn if any line is given a z value or if both zmin and zmax are given. Alternatively, the path to an image with a color gradient can be specified. Here, an image width of one pixel is sufficient.
outlinebool, default False: Draw dashed figure outline?
canvasstr, default None: Background color of whole document.
backgroundstr, default None: Path to background image.
preamblestr, default ‘’: Definitions for standalone figures.
inputencstr, default None: Text encoding, e.g., 'utf8'.
fontencstr, default None: Font encoding. The default is 'T1' if font is specified, none otherwise.
fontstr, default None: Predefined font selection. Imitates well-known fonts. Possible values are 'Gill Sans', 'Helvetica', 'Iwona', 'Latin Modern', 'Times', and 'Utopia'.
fontsizeint, default 10: Font size for standalone figures in pt.
singlefloat, default 8.0: Single-column width for the chosen style.
doublefloat, default 17.0: Full textwidth for the chosen style.
resolutionfloat, default 1e-3: Smallest distance in cm expected to be discernible when looking at the plot. The default is acceptable when the plot is viewed or printed in its original size. For zooming, smaller values may be necessary. This parameter determines the number of vertices used to render a line and thus affects the file size.
epsfloat, default 1e-4: Distance from plot boundary in cm beyond which a mark or grid line is considered to lie outside of the plot area (and is potentially cut off). This tolerance is meant to make up for the limited numerical precision. For example, using double preicision, 3 * 0.1 > 0.3.
lineslist: List of all line objects.
optionsdict: Global TikZ options.

Notes

In all textual attributes and parameters, numbers in angle brackets are interpreted as values in y data units, e.g., line_width='<0.1>'. For the parameters line_width and mark_size this is also the case if an integer or float is passed instead of a string.

axes(**options)[source]: Draw axes at current z index.

clear()[source]: Remove all lines from plot.

code(data, **options)[source]

Insert literal TikZ code.

Parameters:

datastr: TikZ code. Positions and distances in data coordinates and units can be specified using angle brackets, e.g., (<x=1>, <y=2>) or +(<dx=1>, <dy=2>).
**options: Options passed to line.

compline(x, y, weights=1.0, colors=True, threshold=0.0, **options)[source]

Represent points of multiple weights as composite fatband.

Parameters:

x, ylist of float: Coordinates of line vertices.
weightslist of tuple of float, list of float, or float, default 1.0: Weights of vertices. The corresponding linewidth is always measured perpendicular to the direction of the line; This ensures that lines of the same weight have the same thickness regardless of direction.
colorslist of str or str, default True: Colors of different components. Any objects whose representations as a string are valid LaTeX colors can be used. If True, the fill color is the same as the stroke color.
thresholdfloat, default 0.0: Minimum displayed weight.
**options: Further line options.

cut(x=0.0, y=0.0)[source]

Indicate broken axis.

Parameters:

x, yfloat: Position of the break symbol.

fatband(x, y, weights=1.0, shifts=0.0, fill=True, draw='none', **options)[source]

Draw fatband.

Parameters:

x, ylist: Vertices of linear spline.
weightslist of float or float, default 1.0: Weights of x and y.
shiftslist of float or float, default 0.0: Displacements in weight direction.
fill, drawstr or Color: TikZ line options (filled without outline by default).
**options: Options passed to line function.

image(filename, x1, y1, x2, y2, **options)[source]

Insert image between given data coordinates.

Parameters:

filenamestr: File name of image.
x1, y1float: Position of bottom-left corner in data coordinates.
x2, y2float: Position of top-right corner in data coordinates.
**options: Options passed to line.

line(x=[], y=[], z=None, axes=False, code=None, cut=False, frame=False, grid=False, join=None, jump=0, label=None, miter=False, nib=None, omit=None, protrusion=0, sgn=1, shifts=None, shortcut=0, shortcut_rel=0.5, thickness=0.05, weights=None, xref=None, yref=None, zindex=None, **options)[source]

Add line/curve.

Parameters:

x, ylist or float: Coordinates of data points.
zfloat, default None: z value for entire line, represented by color.
axesbool, default False: Draw axes at current z index? By default, the axes are drawn first, i.e., below all data.
codestr, default None: Literal TikZ code to be inserted at current position.
cutbool or tuple, default False: Cut off line segments beyond plotting range? It is also possible to pass the clipping window as a tuple (xmin, xmax, ymin, ymax) in data coordinates, where None is replaced by the plot bounds.
framebool, default False: Draw frame at current z index? By default, the frame is drawn just below the axes.
gridbool, default False: Add grid lines (at positions of major and possibly minor ticks) at current z index? By default, the grid is drawn just below the frame.
joinbool, default None: Join cut-up line segments along edge of plotting range? By default, this is True if any fill is specified, False otherwise.
jumpfloat, default 0: Shortest distance between consecutive data points that is considered as a discontinuity.
labelstr, default None: Label for legend entry. The special label *next* adds a second example line with the current line style to the next legend entry.
miterbool, default False: Draw fatbands using miter_butt function? If False, the fatband function is used.
nibfloat, default None: Angle of broad pen nib. If None, the nib is held perpendicular to the direction of the current line segment.
omitbool, default None: Remove irrelevant vertices of linear spline? The default is False if the TikZ option mark is set, True otherwise.
protrusionfloat, default 0: Extend curve linearly at both ends? This may improve the appearance of fatbands ending at the edge of the plotting range.
sgninteger, default +1: Direction of fatband outline. Coinciding outlines should be drawn in the same direction if omit is True.
shiftslist of float: Displacements in weight direction of fatband.
shortcutfloat, default 0: Maximum length of loop to be cut off.
shortcut_relfloat, default 0.5: Maximum length of loop to be cut off relative to the total length of the curve. This is only used if shortcut is nonzero.
thicknessfloat, default 0.05: Fatband linewidth in cm.
weightslist of float: Fatband weights.
xref, yreffloat, default None: Reference values for filled curves. This is useful to visualize integrands such as a density of states.
zindexint, default None: Index of list of lines where new line is inserted. By default, the new line is appended to the list, i.e., has the highest zindex.
**options: Local TikZ options.

node(x, y, content, name=None, **options)[source]

Draw (text) node at given position.

Parameters:

x, yfloat: Node position in data coordinates.
contentstr: Node content.
namestr: Name/label to refer back to the node.
**options: TikZ options of the node, e.g., above left=True.

nolabel()[source]: Pass empty entry to legend (as spacer between entries).

point(x, y, name)[source]

Define point.

Parameters:

x, yfloat: Point position in data coordinates.
namestr: Name/label to refer back to the point.

save(filename, external=False, standalone=False, pdf=False, png=False, dpi=300.0, width=0, height=0, rewrite=False, engine='pdflatex')[source]

Save plot to file.

Parameters:

filenamestr: File name. If no period is contained, the .tex extension may be omitted.
externalbool, default False: Provide file name to TikZ library external.
standalonebool, default False: Create file that can be typeset with pdflatex, i.e., include document header etc.?
pdfbool, default False: Typeset TeX file via pdflatex? This implies standalone. Automatically set to True if filename ends with .pdf.
pngbool, default False: Rasterize PDF file via pdftoppm? This implies pdf. Automatically set to True if filename ends with .png.
dpifloat, default 300.0: Image resolution in dots per inch.
width, heightint: Image dimensions in pixels. If either width or height is zero, it will be determined by the aspect ratio of the image. If both are zero, they will also be determined by dpi.
rewritebool, default False: Rewrite resulting PNG file using StoryLines? This will remove possible metadata and may reduce the file size but currently is quite slow.
enginestr, default ‘pdflatex’: TeX typesetting engine.