• (left, bottom), where these correspond to relative coordinates mapping out the plot area as (0.0, 1.0). NOTE: smaller and larger values than 0.0 and 1.0 are supported and will put the annotation outside the plot area.
• (x, y) where x and y are values in the scale of the data being plotted. This is useful if the annotation is to be placed relative to specific data points. NOTE: for a discrete axis data scale is not well defined, thus we fall back to relative scaling on that axis!

In principle you can mix and match left/x and bottom/y! If both are given the former will be prioritized.

NOTE: using rotate together with a background is currently broken.

NOTE: When using a different position than identity, be careful reading the plot! If N classes are stacked and an intermediate class has no entries, it will be drawn on top of the previous value!

Possible LineTypes are:

ltNone, ltSolid, ltDashed, ltDotted, ltDotDash, ltLongDash, ltTwoDash

Possible ErrorBarKind are:

ebLines, ebLinesT

Draws a smooth line that is a filtered version of the x and y data given as the aes of the plot (or to this geom).

Note: if the input data is considered to be discrete (either manually or automatically if it's an integer column), a ValueError will be raised at runtime as smoothing is incompatible with a discrete plot and thus would lead to an undesirable outcome.

Applies all calculations to the GgPlot object required to draw the plot with the selected backend (either determined via filetype in ggsave, handed manually to ggplot) and returns a PlotView.

The PlotView contains the final Scales built from the GgPlot object and all its geoms plus the final ginger.Viewport which only has to be drawn to produce the plot.

This proc is useful to investigate the data structure that results before actually producing an output file or to combine multiple plots into a combined viewport.

Creates a simple multi plot in a grid. Currently no smart layouting. If widths and heights is given, expects a sequence of numbers of the length of given plots. It will use the width/height of the same index for the corresponding plot.

For an explanaiton of the TeX arguments, see the ggsave docstring.

Generates the plot and saves it as fname with the given width and height.

Possible file types:

• png
• svg
• pdf
• tex

The backend argument can be used to overwrite the logic that is normally used to determine the backend used to save the figures. Note that different backends only support different file types. Currently there are no safeguards for mismatching backends and file types! Available backends:

• bkCairo: default backend, supports png, pdf, svg, jpg
• bkTikZ: TikZ backend to generate native LaTeX files or PDFs from TeX
• bkPixie: pure Nim backend supporting png
• bkVega:: Vega-Lite backend for interactive graphs in the browser

If the output file is to be stored as a pdf, useTeX decides whether to create the file using Cairo or a local LaTeX installation (by default system xelatex if available, with pdflatex as the fallback). In case useTeX is true, standalone is always taken to be true (unless a texTemplate is given).

If the File type is tex, onlyTikZ determines whether to output only the TikZ code to a file or create a full TeX document (that can be directly compiled).

Further, standalone decides what kind of document is created in case onlyTikZ is false. standalone means it's meant as a TeX file that only contains the plot and produces a cropped plot upon compilation. If standalone is false the document is an article.

The priority of onlyTikZ, standalone and texTemplate is as follows:

1. texTemplate: if given will be used regardless of the others
2. onlyTikZ: higher precedence than standalone
3. standalone: only chosen if above two are false / empty

Further, if a texTemplate is given that template is used to embed the TikZ code. The template must contain a single $# for the location at which the TikZ code is to be embeded.

Finally, if a caption and / or label are given, the output will wrap the tikzpicture in a figure environment, with placement options placement.

The default TeX templates are found here: https://github.com/Vindaar/ginger/blob/master/src/ginger/backendTikZ.nim#L244-L274

The required TeX packages are thus: inputenc, geometry, unicode-math, amsmath, siunitx, tikz.

Note: unicode-math is incompatible with pdflatex!

Note 2: Placing text on the TikZ backend comes with some quirks:

1. text placement may be slightly different than on the Cairo backend, as we currently

use a hack to determine string widths / heights based on font size alone. ginger needs an overhaul to handle embedding of coordinates into viewports to keep string width / height information until the locations are written to the output file (so that we can make use of text size information straight from TeX)

2. Text is placed into TikZ node elements. These have some quirky behavior for more

complex LaTeX constructs. E.g. it is not really possible to use an equation environment in them (leads to "Missing $ inserted" errors).

3. because of hacky string width / height determination placing a non transparent background

for annotations leads to background rectangles that are too small. Keep the background color transparent for the time being.

4. Do not include line breaks \n in your annotations if you wish to

let LaTeX handle line breaks for you. Any manual line break \n will be handled by ginger. Due to the string height hack, this can give somewhat ugly results.

This is the same as the ggsave proc below for the use case of calling it directly on a GgPlot object using a possible TeX options object.

See the docstring there.

This is the same as the ggsave proc below for the use case of calling it directly on a GgPlot object with the possible TeX options.

See the docstring below.

Generates two versions of of the given plot. The filename should not contain any extension. We will generate a .tex file and a .json file.

The TeX file is suppposed to be inserted (using \input) into the LaTeX file.

The JSON file should be stored as a GitHub gist from which it can be imported into the Vega-Lite viewer.

NOTE: The width and height arguments don't have any purpose at this time.

Adds major grid lines to a plot

If width != Inf will use the value, else default of 1pt.

The color may also be changed with this proc if multiple changes are to be made.

If onlyAxes is true and enable is false, we will only draw the actual axes and no grid lines.

• cm: margin quantity in centimeter
• in, inch: margin quantity in inch
• pt, point, px, pixel: margin quantity in points
• r, rel, relative: margin quantity as relative values

Adds minor grid lines to a plot (i.e. between the major grid lines of half width)

If width is != Inf will use the given width. Else will compute to half the width of the major lines.

Allows to customize the color gradient used for the color aesthetic.

Either call one of:

• viridis(), magma(), plasma(), inferno()

as an argument to the scale argument or hand your own custom color scale (as uint32 colors).

Construction of uint32 colors can be done "by hand": Assuming alpha, r, g, b are uint8 values:

let c = alpha shl 24 or r shl 16 or g shl 8 or b

or by constructing it as a hex color directly:

let c = 0xaa_ff_00_ff'u32 # hex color "#FF00FF" with AA alpha

or finally by converting from a chroma or a stdlib/colors color.

Note: chroma does not have a type that stores uint32 colors, so the conversion must be done by hand. The stdlib / colors module uses int64 values for whatever reason. For those you can just convert them to uint32. Both of these options provide your typical "named CSS-like" colors.

The name argumnet is only used in case a seq[uint32] is given and is not particularly important.

Forces the fill scale to be continuous.

If a scale is given, the fill scale range will be drawn in the given range.

Allows to customize the color gradient used for the color aesthetic.

Either call one of:

• viridis(), magma(), plasma(), inferno()

as an argument to the scale argument or hand your own custom color scale (as uint32 colors).

Construction of uint32 colors can be done "by hand": Assuming alpha, r, g, b are uint8 values:

let c = alpha shl 24 or r shl 16 or g shl 8 or b

or by constructing it as a hex color directly:

let c = 0xaa_ff_00_ff'u32 # hex color "#FF00FF" with AA alpha

or finally by converting from a chroma or a stdlib/colors color.

Note: chroma does not have a type that stores uint32 colors, so the conversion must be done by hand. The stdlib / colors module uses int64 values for whatever reason. For those you can just convert them to uint32. Both of these options provide your typical "named CSS-like" colors.

The name argumnet is only used in case a seq[uint32] is given and is not particularly important.

Creates a continuous x axis with a possible secondary axis. labels allows to hand a procedure, which maps the values found on the x axis to the tick label that should be shown for it.

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

Creates a continuous x axis that generates labels according to the desired date time information.

If breaks is given as a sequence of unix timestamps, these will be used over those computed via dateSpacing.

isTimestamp means the corresponding x column of the input data is a unix timestamp, either as an integer or a floating value.

parseDate is required if the data is not a timestamp. It needs to handle the parsing of the stored string data in the x column to convert it to DateTime objects.

dateSpacing is the desired distance between each tick. It is used as a reference taking into account the given formatString. Of all possible ticks allowed by formatString those ticks are used that have the closest distance to dateSpacing, starting with the first tick in the date range that can be represented by formatString.

The dateAlgo argument is an experimental argument that should not be required. It changes the algorithm that is used to determine sensible tick labels based on the given dateSpacing. In the case of dtaFilter (default) we compute the parsed dates for all elements in the date time column first and then attempt to filter out all values to leave those that match the dateSpacing. This works well for densely packed timestamps in a column and deals better with rounding of e.g. 52 weeks =~= 1 year like tick labels. dateAlgo is overwritten if breaks is given.

For sparser time data, use the dtaAddDuration algoritm, which simply determines the first suitable date based on the format string and adds the dateSpacing to each of these. The next matching date based on the formatString is used. This does not handle rounding of dates well (4 weeks =~= 1 month will produce mismatches at certain points for example), but should be more robust.

Sets the X scale of the plot to a log2 scale.

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

Sets the X scale of the plot to a log10 scale.

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

Creates a continuous y axis with a possible secondary axis. labels allows to hand a procedure, which maps the values found on the y axis to the tick label that should be shown for it.

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

Creates a continuous y axis that generates labels according to the desired date time information.

If breaks is given as a sequence of unix timestamps, these will be used over those computed via dateSpacing.

isTimestamp means the corresponding y column of the input data is a unix timestamp, either as an integer or a floating value.

parseDate is required if the data is not a timestamp. It needs to handle the parsing of the stored string data in the y column to convert it to DateTime objects.

dateSpacing is the desired distance between each tick. It is used as a reference taking into account the given formatString. Of all possible ticks allowed by formatString those ticks are used that have the closest distance to dateSpacing, starting with the first tick in the date range that can be represented by formatString.

The dateAlgo argument is an experimental argument that should not be required. It changes the algorithm that is used to determine sensible tick labels based on the given dateSpacing. In the case of dtaFilter (default) we compute the parsed dates for all elements in the date time column first and then attempt to filter out all values to leave those that match the dateSpacing. This works well for densely packed timestamps in a column and deals better with rounding of e.g. 52 weeks =~= 1 year like tick labels. dateAlgo is overwritten if breaks is given.

For sparser time data, use the dtaAddDuration algoritm, which simply determines the first suitable date based on the format string and adds the dateSpacing to each of these. The next matching date based on the formatString is used. This does not handle rounding of dates well (4 weeks =~= 1 month will produce mismatches at certain points for example), but should be more robust.

Sets the Y scale of the plot to a log2 scale

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

Sets the Y scale of the plot to a log10 scale.

breaks allows to specify either the number of ticks desired (in case an integer is given) or the exact locations of the ticks given in units of the data space belonging to this axis.

Note that the exact number of desired ticks is usually not respected, rather a close number that yields "nice" tick labels is chosen.

• white background
• no grid lines
• no ticks
• no tick labels
• no labels

Sets the limits of the plot range in data scale. This overrides the calculation of the data range, which by default is just (min(dataX), max(dataX)) while ignoring inf values. If the given range is smaller than the actual underlying data range, outsideRange decides how data outside the range is treated.

Supported values are "clip", "drop" and "none":

• "clip": clip all larger values (e.g. inf or all values larger than a user defined xlim) to limit + xMargin (see below).
• "drop": remove all values larger than range
• "none": leave as is. Might result in values outside the plot area. Also -inf values may be shown as large positive values. This is up to the drawing backend!

It defaults to "clip".

Be aware however that the given limit is still subject to calculation of sensible tick values. The algorithm tries to make the plot start and end at "nice" values (either 1/10 or 1/4 steps). Setting the limit to some arbitrary number may not result in the expected plot. If a limit is to be forced, combine this with xMargin! (Note: if for some reason you want more control over the precise limits, please open an issue).

NOTE: for a discrete axis the "data scale" is (0.0, 1.0). You can change it here, but it will probably result in an ugly plot!

• "clip": clip all larger values (e.g. inf or all values larger than a user defined xlim) to limit + xMargin.
• "drop": remove all values larger than range
• "none": leave as is. Might result in values outside the plot area. Also -inf values may be shown as large positive values. This is up to the drawing backend!

It defaults to "clip".

NOTE: negative margins are not supported at the moment! They would result in ticks and labels outside the plot area.

Sets the limits of the plot range in data scale. This overrides the calculation of the data range, which by default is just (min(dataY), max(dataY)) while ignoring inf values. If the given range is smaller than the actual underlying data range, outsideRange decides how data outside the range is treated.

Supported values are "clip", "drop" and "none":

• "clip": clip all larger values (e.g. inf or all values larger than a user defined ylim) to limit + yMargin (see below).
• "drop": remove all values larger than range
• "none": leave as is. Might result in values outside the plot area. Also -inf values may be shown as large positive values. This is up to the drawing backend!

It defaults to "clip".

Be aware however that the given limit is still subject to calculation of sensible tick values. The algorithm tries to make the plot start and end at "nice" values (either 1/10 or 1/4 steps). Setting the limit to some arbitrary number may not result in the expected plot. If a limit is to be forced, combine this with yMargin! (Note: if for some reason you want more control over the precise limits, please open an issue).

NOTE: for a discrete axis the "data scale" is (0.0, 1.0). You can change it here, but it will probably result in an ugly plot!

• "clip": clip all larger values (e.g. inf or all values larger than a user defined ylim) to limit + yMargin.
• "drop": remove all values larger than range
• "none": leave as is. Might result in values outside the plot area. Also -inf values may be shown as large positive values. This is up to the drawing backend!

It defaults to "clip".

NOTE: negative margins are not supported at the moment! They would result in ticks and labels outside the plot area.

• named / unnamed arguments:
  • for named arguments, the name must be a valid field of the Aesthetics object
  • unnamed arguments are supported. The macro picks the field corresponding to the index of each field in the order of the fields of Aesthetics fields

  In principle unnamed arguments can follow named ones, but better do not abuse that...

• Different types are supported for the values
  • literals: string, int, float. Will be treated as constant FormulaNode values for the associated scale (useful for e.g. width = 0.5)
  • formula nodes: formula nodes are simply assigned as the columns for the generated scale. Can refer to a column or a complicated expression.
  • idents: raw idents are supported. If the identifier refers to something declared, the value of that is used. Else the identifier is treated as a string. Be careful with this feature!