Layers: 1-D, scatter and aggregation
This chapter explains the settings and caveats of each kind of layer used in 1-D plots and 2-D plots. Adding, deleting and reordering layers work as in Layers: maps and sections. The order is the drawing order and the legend order. Examples of the figures you can draw are in the Gallery. The definitions of the statistics (standard deviation, whiskers, KDE, bins) are summarized in Computational conventions.
| Plot mode | Available layers |
|---|---|
| 1-D plot | Line, line bundle, line fill, stack plot, bar chart |
| 1-D plot (aggregation) | Histogram, ECDF and line when the plot type is "Histogram / ECDF"; box plot and violin when it is "Box / violin" |
| 2-D plot | Scatter, bubble chart |
| 2-D plot (aggregation) | 2-D histogram, hexbin |
Items common to all layers.
- Legend label: when empty, the layer is left out of the legend. The default is the variable name (empty for scatter and bubble chart). Changing the variable resets it to the default.
- Value transform (unit conversion etc.): "Scale a" and "Offset b" transform the values to a × original value + b. Scatter, bubble chart and 2-D aggregation take separate transforms for x / y (/ z). Ranges and thresholds are entered in the transformed units.
- Fixing dimensions and range means: in the layers of a 1-D plot, each dimension other than the x-axis and time takes "Fixed value" or "Range mean" (latitude also offers "cos(lat)-weighted"). Time is handled in the "Time" section of the panel (Data handling).
- Draw on the secondary (right) axis: draws on the right y-axis when overlaying quantities with different units. The label and range of the secondary axis are set under "Axes, labels & legend" → "Secondary axis (right)" (Plot modes).
Line
| Item | Content | Default |
|---|---|---|
| Variable | A variable with the x-axis dimension | |
| Automatic color (color cycle) | When off, "Line color" | on |
| Line width | 0.5 to 4.0 | 1.5 |
| Line style | solid / dashed / dotted / dash-dot / none (markers only) | solid |
| Marker | none / ○ / ■ / ▲ / × / • / + | none |
| Draw on the secondary (right) axis | off |
There is no error bar item. To add a band, use line fill or the summary lines of a line bundle.
A line can also be overlaid in a 1-D plot (aggregation) with "Histogram / ECDF" (e.g. the curve of a theoretical distribution). In that case the x-axis is not the panel's axis but the coordinate values of the dimension chosen as "Dim used as x-axis" (make its units the same as the value axis of the histogram).
Line bundle
Overlays all slices along one dimension, such as ensemble members, with the same color, line style and opacity, and merges them into a single legend entry.
| Item | Content | Default |
|---|---|---|
| Variable | A variable with a dimension to bundle besides the x-axis and time | |
| Dimension to bundle | Chosen from "{dim} ({n} lines)". The time dimension cannot be chosen | |
| Line color | All lines share the same color | #808080 |
| Line width | 0.0 to 4.0. 0 draws no bundle lines (to show only the band) | 0.8 |
| Opacity (alpha) | With many lines, a smaller value shows the density of overlaps | 0.5 |
| Line style, marker, secondary axis, legend label | Same as line |
Summary lines
Turning on "Summary lines (overlay statistics of the bundle)" overlays lines aggregated along the bundled dimension on top of the bundle. "Number of summary lines" (1 to 6) sets how many "Summary line {n}" items appear. NaN is excluded from the aggregation.
| Statistic | Content |
|---|---|
| Mean, Median, Minimum, Maximum | 1 line |
| Min and max (2 lines) | |
| Percentile (1 line) | "Percentile (%)" (default 95) |
| Percentile range (2 lines) | "Lower (%)" and "Upper (%)" (default 5 and 95) |
| Mean ± std. dev. (2 lines) | "Std. dev. multiplier k" (default 1). The standard deviation is the sample standard deviation (divided by N − 1) |
Two-line statistics have "Draw style": "Lines (2)", "Band (filled)" or "Band + edge lines". You set "Line color" (default black), "Line width" (default 2.0, 0 for no line), "Line style" and the "Opacity (alpha)" of the band (default 0.3). The default "Legend label" is a short name such as mean, median, min-max, p95, p5-p95 or mean±1σ; when empty, the line is left out of the legend.
line fill
Fills the area between two lines, or between a line and a reference value.
| Item | Content | Default |
|---|---|---|
| Variable (first) | Also set the fixed dimensions and range means | |
| Second value | "From a variable": "Variable (second)" (its fixed dimensions are independent of the first; e.g. a band of the difference between 500 hPa and 850 hPa). "Constant (baseline)": "Baseline value" (in transformed units) | From a variable |
| Different colors above/below the baseline | For a constant. Fills with "Upper color" and "Lower color" (default #1f77b4 and #d62728) | off |
| Color | The color when not split above/below | #1f77b4 |
| Opacity (alpha) | 0.3 | |
| Legend label | The default with a variable is "first–second" |
The value transform applies the same coefficients to both variables.
Stack plot
| Item | Content | Default |
|---|---|---|
| Variables (order = stacking order, bottom to top) | Multiple selection | the first 2 variables |
| Opacity (alpha) | 0.8 | |
| Baseline | zero (stacked) / sym (symmetric around 0) / wiggle (minimizes the wiggle) / weighted_wiggle (streamgraph) | zero |
| Show variable names in the legend | on | |
| Set each variable's color manually | When on, "Color of {var}" per variable. When off, the color cycle | off |
The fixed dimensions and range means are set on the dimensions of the first variable and shared by all variables. There is no normalization to a total of 100 %.
Bar chart
| Item | Content | Default |
|---|---|---|
| Orientation | Vertical bars (ax.bar) / Horizontal bars (ax.barh) | Vertical bars |
| Color, Opacity (alpha) | #1f77b4, 0.8 | |
| Set bar width manually | When off, 0.8 times the median of the differences between adjacent x. When on, "Width (data units)" | off |
| Show edges | Edge color and width | off |
| Apply hatching | Hatch pattern (/ \ - + x o . etc.), density (1 to 6), color. When edges are on, the hatch color becomes the edge color (a matplotlib limitation) | off |
| Show error bars | "Error amount" given by a variable or a constant (symmetric). Color, width, cap size | off |
| Draw on the secondary (right) axis | Vertical bars only | off |
With several bar chart layers, "Bar placement" at the end of the "Layers" section selects Overlap / Side by side / Stacked (Plot modes). The value transform is not applied to the error amount, whether it is a variable or a constant. Provide it in the units shown in the figure (after the value transform) (Computational conventions).
Histogram
A layer of a 1-D plot (aggregation) first selects "Dim to aggregate" (automatic when there is only one dimension), narrows the period or interval with "Set aggregation range", and fixes the remaining dimensions with "Fix: {dim}". Only finite values are aggregated.
| Item | Content | Default |
|---|---|---|
| Use equal-width bins | When on: "Set value range" (off: equal division between the data minimum and maximum; on: enter Min and Max) and "Number of bins" (2 to 200). When off: enter "Bin edges (comma-separated)" directly (uneven spacing allowed) | on, 20 |
| y-axis | Count / Probability density (density; the total area is 1) | Count |
| Cumulative | off | |
| Draw style | Filled (bar) / Step (line only) / Step-filled (stepfilled). Without edges, bar and stepfilled look nearly identical; with edges, bar also adds vertical lines between bins | Filled (bar) |
| Automatic color (color cycle) | When off, "Color" | on |
| Opacity (alpha) | Semi-transparent, assuming overlays | 0.7 |
| Show edges | Edge color and width | off |
When the axis labels are empty, x gets "variable name [units]" and y gets count / probability density / cumulative count / cumulative probability automatically.
ECDF (empirical cumulative distribution)
The data are taken as for the histogram. "Complementary (1 − CDF)" draws the exceedance probability (the fraction of values at or above a threshold). You set "Automatic color (color cycle)" (when off, "Line color"), "Line width" (default 1.5), "Line style" and "Draw on the secondary (right) axis" (when overlaying on a count histogram). The automatic y label is cumulative probability, or exceedance probability for the complementary distribution.
Box plot
One layer is one series (one box); add layers for more series. The x position follows the layer order. "Orientation" below "Plot type" switches between vertical and horizontal.
| Item | Content | Default |
|---|---|---|
| Series name (shown as x tick) | variable name | |
| Include in legend | To distinguish series by color | off |
| Box width | 0.1 to 1.0 | 0.5 |
| Whisker definition | IQR multiplier ("Whisker length (whis, IQR multiplier)", default 1.5; points beyond it are outliers) / Percentile range ("Lower (%)" and "Upper (%)", default 5 and 95) | IQR multiplier |
| Notch (median confidence-interval indent) | The notch width is about 1.57 × IQR / √N. Non-overlapping notches of two series hint at a significant difference in medians | off |
| Show outliers, Whisker end bars (caps) | The cap width can also be set with "Set cap width" | on, on |
| Show boxes | When off, only whiskers and the median | on |
| Show the mean | A marker (▲) unless "Draw the mean as a line (meanline)" is on | off |
| Fill boxes | Fill color | off (white) |
| Overlay raw data points (strip) | "Jitter width" (default 0.2, reproducible with a fixed seed), "Point size (s)", "Point color", "Point opacity". They overlap the outliers, so turning "Show outliers" off is recommended | off |
"Appearance details" sets the color and width of the lines (box, whiskers, caps), of the median line (default #d62728, 1.5) and of the mean, and the kind, size and color of the outlier markers. The value axis gets "variable name [units]" automatically, and the series axis shows the series names as ticks.
Violin
Series and orientation are handled as in the box plot.
| Item | Content | Default |
|---|---|---|
| Series name (shown as x tick), Include in legend | variable name, off | |
| Width | 0.1 to 1.0 | 0.7 |
| Median / Mean / Extrema (whiskers) | Lines to show | on / off / on |
| Draw quantile lines | "Quantiles (0-1, comma-separated)" (default 0.05, 0.95) | off |
| KDE bandwidth | Auto (scott) / silverman / Numeric value ("Bandwidth factor", default 0.3). Smaller values show finer detail | Auto (scott) |
| KDE evaluation points | 20 to 1000. The resolution of the shape | 100 |
| Shape | Both sides / Left half / Right half. Half violins compare two series facing each other at the same position | Both sides |
| Automatic color | When off, "Color" | on |
| Opacity (alpha) | Opacity of the body (the KDE shape) | 0.5 |
| Overlay raw data points (strip) | Same items as the box plot | off |
Scatter
The x and y variables are selected in the panel's "Plot variables"; the layer sets the following.
| Item | Content | Default |
|---|---|---|
| Dim to draw along | A dimension with coordinates shared by x and y. Points are placed along it. "Range of {dim}" narrows it | |
| Dims to fix for x-axis / y-axis variable | Dimensions other than the one drawn along are fixed independently for x and y. The initial value is the middle index | |
| Color | Single color | #1f77b4 |
| Opacity (alpha) | 0.7 | |
| Marker | ○ / ■ / ▲ / × / • / + / ◇ / * | ○ |
| Marker size (s, area pt²) | 1 to 200 | 20 |
| Show edges | Edge color and width | off |
| Legend label | empty |
Selecting "x-error variable" and "y-error variable" under "Error bars" (symmetric ± errors; cropped with the same fixed dimensions and range as the main data; the value transform is not applied, so provide them in the units shown in the figure) draws error bars with the given color, width and cap width. Points whose x or y is NaN are excluded. To color by a third variable, use the bubble chart. There is no regression line or correlation coefficient.
Bubble chart
In addition to x and y, "z-axis variable (for bubble chart, optional)" in the panel's "Plot variables" selects the variable used for the size.
| Item | Content | Default |
|---|---|---|
| Dim to draw along, dims to fix | Same as scatter (z is also fixed independently) | |
| Marker | ○ | |
| Min size / Max size (pt²) | The areas corresponding to the minimum and maximum of z. The transformed z values are normalized linearly onto this range | 10 / 200 |
| Show edges | off | |
| Color by z value (cmap) | When on: colormap, reversal, value range, color discretization (number of levels / specify directly), white near zero, extend, Colorbar. When off, "Color" | off |
| Opacity (alpha) | 0.6 |
Error bars and the value transform (x / y / z independent) are the same as for scatter. There is no size legend.
2-D histogram
A 2-D plot (aggregation) aggregates all pairs of samples along the dimensions shared by x and y; dimensions not shared are fixed with "Fix dims of x variable" and "Fix dims of y variable". Pairs containing NaN are excluded.
| Item | Content | Default |
|---|---|---|
| Bins (x) / Bins (y) | 2 to 200 | 20 / 20 |
| Set aggregation range | When off, equal division between the data minimum and maximum. When on, enter the minimum and maximum of x and y | off |
| Aggregation | Count / Probability density (density; the total integral is 1) | Count |
| Do not fill empty (zero) bins | on | |
| Log-scale counts (LogNorm) | To see bins differing by orders of magnitude at once. Cannot be combined with color discretization (for log-like classes use "Specify levels directly" of the discretization, e.g. 1, 2, 5, 10, 20, 50) | off |
| Colormap, value range, color discretization, extend | Same items as fill | |
| Show bin edges | Width and color. Unfilled bins get no edges | off |
| Colorbar | The default label is count | shown |
hexbin (hexagonal bin density)
The data are taken as for the 2-D histogram. Only the number of points is aggregated; there is no reduction of a third variable per hexagon.
| Item | Content | Default |
|---|---|---|
| Hexagon count (gridsize) | The number of bins in the x direction (5 to 60). Larger is finer | 20 |
| Log-scale counts (bins='log') | Cannot be combined with color discretization | off |
| Fill empty bins too (mincnt=None) | When off, only bins with at least "Minimum count (mincnt)" points are drawn | off, 1 |
| Colormap, value range, color discretization, extend | Same items as fill | |
| Show bin edges | Only on bins where points are drawn | off |
| Colorbar | The default label is count | shown |