plot.points¶

The lines of a curve over the points of the dimensions of a scan.

A curve names the dimensions of its data it draws one line per point of (over); after broadcasting by name its data must leave at most one more dimension, the axis a line is drawn along: the time of a timecourse, the points of a ragged result, the rows of a dataset or the dimension of the values a scan sets (a value per simulation over a dimension). The lines are in the order of the labels of the over dimensions, the last one fastest. Their colours follow the first over dimension, their line styles the second; a legend entry names its point by the value and unit of the target its dimension changes, else by its label. Everything of a point is found by its label in the dimension, so a curve of selected points (Data(sel=...)) names and colours the points it draws. The colour of a point is the colour map at its value, through the norm of the colour bar (logarithmic for positive values spanning more than a factor of LOG_RATIO); a dimension which does not change one target is coloured by position, with the labels on a discrete colour bar. A band reduces a dimension of draws to two quantiles and the median, computed when the figure is drawn; it needs a common grid of times, and its legend entry is its area, <name> (<low>-<high> %).

Line `dataclass` ¶

Line(point, index, x, y, xerr=None, yerr=None)

One line of a curve, see curve_lines.

Attributes:

Name	Type	Description
`point`	`tuple[Any, ...]`	the label of every `over` dimension, in their order.
`index`	`tuple[int, ...]`	the position of the point along every `over` dimension.
`x`	`Any`	the x values along the axis, without the padding.
`y`	`Any`	the y values.
`xerr`	`Any`	the x errors, `None` without.
`yerr`	`Any`	the y errors, `None` without.

BandLine `dataclass` ¶

BandLine(point, index, x, low, median, high)

One band, see band_lines.

Attributes:

Name	Type	Description
`point`	`tuple[Any, ...]`	the label of every `over` dimension, in their order.
`index`	`tuple[int, ...]`	the position of the point along every `over` dimension.
`x`	`Any`	the x values along the axis.
`low`	`Any`	the lower quantile.
`median`	`Any`	the median.
`high`	`Any`	the upper quantile.

PointStyle `dataclass` ¶

PointStyle(
    colors,
    linestyles,
    labels,
    colorbar,
    values,
    title,
    norm,
    colormap,
    ticks,
)

How the lines of a curve over scan points look, see point_styles.

Attributes:

Name	Type	Description
`colors`	`list[str]`	the colour of every point of the first dimension.
`linestyles`	`list[str] \| None`	the line style of every point of the second, `None` with one.
`labels`	`list[list[str]]`	the legend label of every point of every dimension.
`colorbar`	`bool`	whether the first dimension gets a colour bar.
`values`	`ndarray`	the values of the points of the first dimension, their positions without a single target.
`title`	`str`	the label of the colour bar, `<target> [<unit>]` or the dimension.
`norm`	`Normalize`	the norm of the colours and the colour bar: linear or logarithmic over the values, a boundary per point over the positions.
`colormap`	`Colormap`	the colour map the norm maps onto.
`ticks`	`list[str] \| None`	the tick labels of a discrete colour bar (the labels of the points), `None` for a colour bar of values.

middle `property` ¶

middle

Get the colour of the middle of the colour map, of the legend entry of a curve.

curve_lines ¶

curve_lines(sid, over, x, y, xerr=None, yerr=None)

Split the data of a curve into one line per point of its over dimensions.

Parameters:

Name	Type	Description	Default
`sid`	`str`	the id of the curve, for the errors.	required
`over`	`Sequence[str]`	the dimensions with a line per point, in the order of the lines.	required
`x`	`DataArray`	the x data.	required
`y`	`DataArray`	the y data.	required
`xerr`	`DataArray \| None`	the x errors, `None` without.	`None`
`yerr`	`DataArray \| None`	the y errors, `None` without.	`None`

Returns:

Type	Description
`list[Line]`	The lines, without the padding of a ragged result.

Raises:

Type	Description
`ValueError`	if two arrays have different coordinates of a dimension, an `over` dimension is not one of the data, or more than one other dimension is left.

band_label ¶

band_label(name, quantiles)

Get the legend label of a band, its name and its quantiles in percent.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	the name of the band, of a point of it with `over`; none or empty for a band without a name.	required
`quantiles`	`tuple[float, float]`	the lower and the upper quantile.	required

Returns:

Type	Description
`str`	`<name> (<low>-<high> %)`, e.g. `C (5-95 %)`, or `<low>-<high> %`
`str`	without a name.

band_lines ¶

band_lines(sid, over, across, quantiles, x, y)

Reduce the dimension across of the data of a band to quantiles and the median.

Parameters:

Name	Type	Description	Default
`sid`	`str`	the id of the band, for the errors.	required
`over`	`Sequence[str]`	the dimensions with a band per point.	required
`across`	`str`	the dimension of the draws, which is reduced.	required
`quantiles`	`tuple[float, float]`	the lower and the upper quantile, in `[0, 1]`.	required
`x`	`DataArray`	the x data.	required
`y`	`DataArray`	the y data.	required

Returns:

Type	Description
`list[BandLine]`	One band per point of `over`.

Raises:

Type	Description
`ValueError`	if the data is ragged, has not the dimension `across`, or leaves more than one dimension besides `over` and `across`.

point_colors ¶

point_colors(n, color)

Get the colours of the points of a dimension.

Parameters:

Name	Type	Description	Default
`n`	`int`	the number of points.	required
`color`	`str \| None`	the colour of the style of the curve, `None` without.	required

Returns:

Type	Description
`list[str]`	Shades of the colour from light to the colour itself, or colours of the
`list[str]`	colour map `COLORMAP`, as hex strings; one point keeps the colour.

point_colormap ¶

point_colormap(color)

Get the colour map of the colour bar of a dimension, see point_colors.

cycle_color ¶

cycle_color(position)

Get the colour of the colour cycle of matplotlib at a position, as a hex string.

It is the colour of a band without a colour, by its position among the bands of its plot, in both backends.

point_linestyles ¶

point_linestyles(n)

Get the line styles of the points of a second over dimension.

Raises:

Type	Description
`ValueError`	for more than `len(LINE_STYLES)` points.

point_values ¶

point_values(dimension, units, labels=None)

Get the target, the values and the unit of a dimension which changes one target.

Parameters:

Name	Type	Description	Default
`dimension`	`Dimension \| None`	the dimension of the scan, `None` if it is not known.	required
`units`	`Mapping[str, str]`	the units of the symbols of the model, for values without a unit.	required
`labels`	`Sequence[Any] \| None`	the labels of the points, in their order, every point of the dimension by default; a point is found by its label.	`None`

Returns:

Type	Description
`tuple[str, ndarray, str] \| None`	The target, the values of the points and their unit, `None` for a
`tuple[str, ndarray, str] \| None`	dimension which changes no or several targets or has not every label.

point_labels ¶

point_labels(dim, labels, dimension, units)

Get the legend label of every point of a dimension.

Parameters:

Name	Type	Description	Default
`dim`	`str`	the id of the dimension.	required
`labels`	`Sequence[Any]`	the labels of the points, in their order.	required
`dimension`	`Dimension \| None`	the dimension of the scan, `None` if it is not known.	required
`units`	`Mapping[str, str]`	the units of the symbols of the model, see `point_values`.	required

Returns:

Type	Description
`list[str]`	`<target> = <value> <unit>` for a dimension which changes one target,
`list[str]`	else `<dim> = <label>`.

point_norm ¶

point_norm(values)

Get the norm which maps the values of the points of a dimension onto a colour map.

Returns:

Type	Description
`Normalize \| None`	A logarithmic norm when all values are positive and the largest is
`Normalize \| None`	more than `LOG_RATIO` times the smallest, else a linear one from the
`Normalize \| None`	smallest to the largest value; `None` if the values do not span a
`Normalize \| None`	range (a single value, equal values or a value which is not finite).

format_value ¶

format_value(value)

Format a value of a dimension: six significant digits, a short exponent.

label_text ¶

label_text(label)

Get the text of a label of a dimension, a float formatted as a value.

tick_positions ¶

tick_positions(n)

Get the positions of the points of a discrete colour bar which get a tick.

Every point up to MAX_TICKS points, else every k-th from the first.

point_styles ¶

point_styles(lines, over, color, dimensions, units)

Get the colours, line styles, labels and colour bar of the lines of a curve.

The points are the ones the lines draw, i.e. the labels left after the sel of the data, each found by its label in its dimension.

Parameters:

Name	Type	Description	Default
`lines`	`Sequence[Line \| BandLine]`	the lines of the curve or band.	required
`over`	`Sequence[str]`	the ids of the dimensions it is drawn over.	required
`color`	`str \| None`	the colour of the style of the curve, `None` without.	required
`dimensions`	`Sequence[Dimension \| None]`	the dimension of the scan of every one of `over`, `None` where it is not known.	required
`units`	`Mapping[str, str]`	the units of the symbols of the model, see `point_values`.	required

Returns:

Type	Description
`PointStyle`	The style shared by the serializers.

Raises:

Type	Description
`ValueError`	for more points of a second dimension than line styles.

plot.points¶

Line dataclass ¶

BandLine dataclass ¶

PointStyle dataclass ¶

middle property ¶

curve_lines ¶

band_label ¶

band_lines ¶

point_colors ¶

point_colormap ¶

cycle_color ¶

point_linestyles ¶

point_values ¶

point_labels ¶

point_norm ¶

format_value ¶

label_text ¶

tick_positions ¶

point_styles ¶

Line `dataclass` ¶

BandLine `dataclass` ¶

PointStyle `dataclass` ¶

middle `property` ¶