spacr.figures.spread

Compute and label uncertainty or dispersion for bar charts.

The standard deviation (SD) describes variation among observations, whereas the standard error of the mean (SEM) describes precision of the estimated mean and decreases with sample size. Variance is SD squared and therefore has squared units. Shared helpers keep these definitions and their plot labels consistent across graph-building surfaces.

Functions

spread_label(→ str)	Return an axis label that identifies the whisker statistic.
spread_of(→ float)	Return the whisker half-length for a sequence of observations.
summarise(→ Dict[str, Dict[str, float]])	Summarize grouped observations for a bar chart.

Module Contents

spacr.figures.spread.spread_label(kind: str, *, unit: str = '') → str

Return an axis label that identifies the whisker statistic.

Parameters:

• kind – one of SPREAD_CHOICES’ values; none produces an empty label and any unrecognised value raises ValueError.

• unit – measurement unit. Variance labels append a squared unit.

spacr.figures.spread.spread_of(values: Sequence[float], kind: str) → float

Return the whisker half-length for a sequence of observations.

Parameters:

• values – the observations behind one bar.

• kind – one of SPREAD_CHOICES’ values.

Returns:

the spread, or nan when it is not defined.

SD and variance use the sample definition (ddof=1). Fewer than two finite observations return nan because their spread is not measurable; a zero would incorrectly claim that no variation was found.

spacr.figures.spread.summarise(groups: Dict[str, Sequence[float]], kind: str) → Dict[str, Dict[str, float]]

Summarize grouped observations for a bar chart.

Parameters:

• groups – group labels mapped to the observations behind each bar.

• kind – whisker statistic requested from spread_of().

Returns:

{level: {"mean", "spread", "n"}}. Groups without finite observations are omitted rather than drawn as zero-valued bars.