Computational conventions
ClimCanvas is a tool that draws exactly what it is told to draw; checking that a figure shows what you intended (which level or time was selected, which range was averaged and how, how missing values were handled) is the user's responsibility. This chapter collects in one place the numerical assumptions needed for that check. The operating instructions are in the respective chapters, linked from each item. The pre-submission checklist is in Output and reproduction scripts, and known bugs that affect figure values are in KNOWN_ISSUES.md in the repository.
Selecting coordinate values
- Fixing a dimension (level, time, etc.) is an exact match against the actual coordinate values shown in the choices. No rounding to the nearest value is done. The selected value is written as is into
.sel(...)in the reproduction script (Fixing dimensions). - The exception is the range input fields of the 1-D plot: a time entered in ISO format is rounded to the nearest time, and a numeric input is used as the range as is (Specifying ranges).
- The result is the same when the coordinate is in descending order. The axis direction follows the coordinate automatically.
Cropping the region
- For the longitude/latitude range of a horizontal map, the display follows the setting exactly, but the data crop is widened by one grid cell on each side so that shading is not cut at the boundary. The automatic color range is based on this widened crop (Specifying ranges).
- When the data cover the full longitude circle, the longitude direction is not cropped even if a region is specified.
- Layer range means are computed over exactly the specified range (the one-cell margin is not included).
- On a 2-D coordinate grid, the crop is the bounding rectangle of the grid points that fall inside the range (2-D coordinates).
Range means
- The default is the arithmetic mean: the grid points in the range are averaged with equal weights. For latitude only, "cos(lat)-weighted" can be selected, which multiplies each grid point by cos(latitude). Differences in grid spacing along longitude and the cell areas of non-uniform grids are not taken into account (Fixing dimensions).
- NaN is excluded from the mean (the same as xarray's
mean). If the whole range is NaN, the result is NaN. - Longitude ranges are normalized to the data's convention (0 to 360 / -180 to 180), and a range crossing the date line is joined across both sides before averaging. When the data contain both 0° and 360°, one of them is dropped so that it is not counted twice.
- The vertical (height/pressure) and string coordinates accept fixed values only; there is no averaging.
Missing values
- ClimCanvas does not detect missing values on its own. Only the values that xarray turned into NaN from the netCDF
_FillValueormissing_valueare skipped;valid_rangeand the like are ignored. A -9999 or 1e20 without such an attribute is drawn as a value and enters the mean (Missing values). - Fill (contourf) shades only up to the centers of the valid grid points.
- Scatter, bubble chart, scatter (points), and track drop the points whose x or y is NaN. The aggregation layers (histogram, ECDF, box plot, violin, 2-D histogram, hexbin) use only finite values (NaN and infinities are excluded).
Value transform and mask-out
- The value transform is linear only (value × scale + offset); no automatic unit conversion (K → °C, Pa → hPa, etc.) is done. The computation keeps the original data type (float32 data stay float32). Value ranges, levels, the colorbar, and mask-out thresholds are specified in the transformed values (Value transform and mask-out).
- The value transform is not applied to the error amounts (error variable or constant) of bar charts, scatter plots, and bubble charts. When you change units with a scale factor, prepare the errors in the converted units as well (for example, if specific humidity was converted from kg/kg to g/kg with a scale factor of 1000, the error variable must also be in g/kg). Up to v1.00.1 the transform was applied (KI-1 in
KNOWN_ISSUES.mdin the repository). - The mask-out options "Hide at or below this value" and "Hide at or above this value" hide the boundary value as well (only the values strictly greater than, or strictly less than, the threshold remain). When the condition uses another variable, the threshold is specified in that variable's raw (untransformed) values.
Definitions of statistics
- Summary lines of a line bundle: mean, median, min, max, and percentiles use numpy's
nanmean/nanmedian/nanmin/nanmax/nanpercentile(linear interpolation), aggregated along the bundle direction with NaN excluded. The standard deviation in "mean ± k × standard deviation" is the sample standard deviation (divided by N − 1) (Line bundle). - Box plot: the median and quartiles follow the definition of matplotlib's
boxplot(numpy's percentile, linear interpolation). Whiskers are specified either by an IQR multiplier (default 1.5) or by a percentile range. With a percentile range, the whiskers end not at the boundary itself but at the outermost actual data point inside the boundary. Outliers are the points beyond the whiskers (Box plot). - Violin: the Gaussian kernel density estimate of matplotlib's
violinplot; the bandwidth is scott (default) / silverman / a coefficient (Violin). - Histogram: "density" is a density whose total area is 1, and "cumulative" is the cumulative count. Bins follow the definition of matplotlib's
hist(only the last bin includes its right edge) (Histogram). - ECDF: for each x, the "fraction at or below x"; complementary is 1 − F (ECDF).
- 2-D histogram and hexbin: the number of points (or the density) is counted per bin. "Do not fill empty (zero) bins" is on by default. The log scale is used only for assigning colors (2-D histogram, hexbin).
- The values used by the aggregation layers are all elements of the dimensions other than the fixed ones, flattened into one dimension. The range of "Dim to aggregate" narrows the period or interval.
Longitude conventions and cyclic points
- Both the 0 to 360 and the -180 to 180 conventions give the same figure. Ranges can be entered in either convention, and a longitude range whose min is greater than its max is treated as crossing the date line.
- A 1-D grid covering the full circle gets a cyclic point that closes the seam between 0° and 360° (fill, hatch, and contours only). See Cyclic longitude for details.
2-D coordinate grids
- Vector and streamline components are drawn as eastward and northward components. Grid-relative components (such as U / V of WRF) are not rotated, so they must be rotated to eastward and northward components beforehand.
- Time sections and longitude/latitude range means are not available (2-D coordinates).
- Vertical cross-sections can follow a grid row or column (no interpolation), or a parallel, a meridian, or the great circle between two points. For the latter, points are placed along the path at roughly the grid spacing, and each point is bilinearly interpolated from the 4 surrounding grid points (no knowledge of the map projection is used; positions come from the grid's longitudes and latitudes alone). A point is missing if any corner with a positive weight is missing, and points outside the grid are missing (Interpolation of sections along a path).
Time axis and calendar
- The calendar is determined by the file's
calendarattribute. standard / gregorian / proleptic_gregorian / noleap are converted to datetime; 360_day / all_leap become a numeric axis of days counted from the start year. Other calendars are not converted (Time axis and calendar). - Time selection, stepping forward and backward, animation, and time sections work on a numeric axis too, but date formats and ISO-format input are available only with datetime.
Dimension alignment across files
- When several files are loaded, only the dimensions that have the latitude, longitude, vertical, or time role have their names aligned (lat and latitude, for example). Other dimensions are not aligned, so align their names beforehand (Automatic detection of coordinate roles).
Plotting assumptions
- Fill (contourf) and contours locate the contour lines by linear interpolation between grid-point values. pcolormesh fills cells centered on the grid points (Fill).
- Streamlines require equally spaced, ascending coordinates, so on a non-uniform coordinate (such as pressure levels) the data are linearly interpolated onto an equally spaced grid with the same end points and the same number of points before drawing (Streamlines).
- The log axis of a section is a display transform only; the data are not interpolated.
- Track lines are drawn as great circles and break at missing positions (Track).
- In-app rendering and the reproduction script are tested to produce identical images in the same environment (Reproduction script). The assumptions in this chapter apply to both.