API Reference¶

pystreamgraph ¶

A compact Matplotlib streamgraph helper with:

sorted or unsorted ordering, and optional global ordering helpers
vertical margins (gaps) between streams
optional value smoothing (moving-average)
boundary curve smoothing with shape-preserving PCHIP splines (default)
optional Catmull–Rom boundary curves
flexible label placement: peak, start, end, max-width, balanced, sliding-window
colormap selection via names, sequences, or label->color mappings

Author: Max Noichl & 🦖

catmull_rom_interpolate ¶

catmull_rom_interpolate(x, y, samples_per_seg=12)

Return dense x_s, y_s that pass through all control points using Catmull–Rom splines. samples_per_seg >= 1. When 1, each segment contributes one interior sample and the end point of the final segment is appended once.

moving_average ¶

moving_average(a, window)

Centered moving average with reflection at the edges. window must be odd and at least 1. When window <= 1 no smoothing is applied.

order_bestfirst ¶

order_bestfirst(X, Y)

Return (center_out_top, center_out_bottom) lists of layer indices. Greedy bipartition that adds the layer/side with lowest incremental L1 midline wiggle.

Reference: Di Bartolomeo & Hu (2016), BestFirst stage.

order_twoopt ¶

order_twoopt(X, Y, repeats=8, scans=3, rng=None)

Build BestFirst bipartition, then improve each side with inside-out scans, repeating from shuffled starts to avoid bad bipartitions. Returns a global order.

Reference: Di Bartolomeo & Hu (2016), TwoOpt stage.

pchip_interpolate ¶

pchip_interpolate(x, y, samples_per_seg=12)

Return dense (xp, yp) sampled using a shape-preserving cubic (PCHIP).

Uses SciPy's PchipInterpolator when available for numerical robustness.
Falls back to a pure NumPy Fritsch–Carlson implementation otherwise.

place_label_fast_on_layer ¶

place_label_fast_on_layer(ax, Xp, bottom, top, text, min_fontsize=6, max_fontsize=18, fontfamily=None, fontweight='bold', shrink=0.9, color='black', sigma_override=None)

Try to place text inside the stream using the paper's O(m log W) scheme. Returns True if placed.

plot_streamgraph ¶

plot_streamgraph(X, Y, labels=None, sorted_streams=False, margin_frac=0.08, smooth_window=1, cmap=None, linewidth=0.0, alpha=1.0, label_placement=True, label_position='balanced', label_color=None, label_fontsize=10, label_weight='bold', curve_samples=200, curve_method='pchip', baseline='center', wiggle_reduction='weighted', global_order=None, pad_frac=0.05, label_min_gap_frac=0.02, label_edge_offset_frac=0.02, label_connectors=False, label_connector_color=None, label_connector_alpha=0.6, label_connector_linewidth=0.8, ax=None, label_kwargs=None, label_anchor='center', label_plot_anchors=False, label_point_kwargs=None, label_balanced_inset_frac=0.05, label_fontsize_min=None, label_fontsize_max=None, label_fontsize_by='sum', label_balanced_progress=False, label_balanced_fit_tolerance_px=2.0, label_balanced_debug_segments=False, label_balanced_debug_kwargs=None, label_balanced_candidates_per_layer=60, label_balanced_restarts=2, label_balanced_T0=2.5, label_balanced_T_min=0.0005, label_balanced_alpha=0.94, label_balanced_iters_per_T=240, label_balanced_min_thickness_q=0.5)

Plot a configurable streamgraph.

Parameters:

X ((ndarray, shape(n))) –

Monotonic x-coordinates.
Y ((ndarray, shape(k, n))) –

Non-negative series (rows are layers) to be stacked.
labels (list of str, default: None ) –

Per-layer label texts. If provided and label_placement=True, labels are rendered using label_position.
sorted_streams (bool, default: False ) –

If True, sort layers by value at each time step; otherwise keep order. If global_order is provided, that fixed order takes precedence.
margin_frac (float, default: 0.08 ) –

Fraction of column sum reserved for gaps between layers.
smooth_window (int, default: 1 ) –

Centered moving-average window applied to values per layer (odd >= 1).
cmap (str | sequence | mapping | Colormap, default: None ) –

Color specification for layers. Strings/Colormap sample evenly; a sequence is cycled/truncated to length k; a mapping uses labels as keys. None defers to Matplotlib's property cycle.
linewidth (float, default: 0.0 ) –

Edge line width passed to fill_between.
alpha (float, default: 1.0 ) –

Face alpha for fill_between.
label_placement (bool, default: True ) –

Whether to place labels.
label_position (('peak', 'start', 'end', 'max_width', 'balanced', 'sliding_window'), default: 'peak','start','end','max_width','balanced','sliding_window' ) –

Labeling strategy. sliding_window uses a fast in-stream algorithm (Di Bartolomeo & Hu, 2016). balanced runs a small simulated annealing to reduce overlap and improve placement.
label_color (str | list[str] | tuple[str] | None, default: None ) –

Label colors. Single string applies to all; list/tuple must match k.
label_fontsize (int, default: 10 ) –

Base font size when no scaling is requested.
label_weight (str, default: 'bold' ) –

Font weight for labels.
curve_samples (int, default: 200 ) –

Samples per original segment for boundary interpolation. If <= 1, no boundary curve interpolation is applied.
curve_method (('pchip', 'catmull_rom'), default: 'pchip','catmull_rom' ) –

Boundary curve interpolation method.
baseline (str, default: 'center' ) –

Only 'center' is supported in this version.
wiggle_reduction (('none', 'unweighted', 'weighted', 'l1_weighted'), default: 'none','unweighted','weighted','l1_weighted' ) –

Baseline strategy used when computing envelopes. 'weighted' is the Streamgraph baseline (Byron–Wattenberg, L2); 'l1_weighted' follows Di Bartolomeo & Hu (2016).
global_order (sequence of int, default: None ) –

Fixed center-out order of layers to use across all time steps. When provided, overrides sorted_streams.
pad_frac (float, default: 0.05 ) –

Extra vertical padding added to the y-limits.
label_min_gap_frac (float, default: 0.02 ) –

Minimum vertical gap between start/end labels as a fraction of y-range.
label_edge_offset_frac (float, default: 0.02 ) –

Horizontal x-offset for start/end labels as a fraction of x-range.
label_connectors (bool, default: False ) –

If True, draw connectors from start/end labels to the stream edge.
label_connector_color (str, default: None ) –

Color for label connectors (defaults to label color).
label_connector_alpha (float, default: 0.6 ) –

Alpha for label connectors.
label_connector_linewidth (float, default: 0.8 ) –

Line width for label connectors.
ax (Axes, default: None ) –

Target axes. Created if None.
label_kwargs (Mapping[str, Any], default: None ) –

Extra matplotlib.text.Text kwargs applied to labels.
label_anchor (str, default: 'center' ) –

Anchor point used for in-stream labels ('peak', 'max_width', 'balanced').
label_plot_anchors (bool, default: False ) –

If True, plot the anchor points used for label placement.
label_point_kwargs (Mapping[str, Any], default: None ) –

Extra kwargs for plotting anchor points when label_plot_anchors.
label_balanced_inset_frac (float, default: 0.05 ) –

Fraction of x-span kept as inset where labels cannot be centered.
label_fontsize_min (float, default: None ) –

Minimum label font size when scaling by layer magnitude.
label_fontsize_max (float, default: None ) –

Maximum label font size when scaling by layer magnitude.
label_fontsize_by (('sum', 'max', 'mean'), default: 'sum','max','mean' ) –

Statistic used when scaling label sizes.
label_balanced_progress (bool, default: False ) –

If True and tqdm is available, show progress during annealing.
label_balanced_fit_tolerance_px (float, default: 2.0 ) –

Vertical tolerance (in px) when checking if text fits inside a stream.
label_balanced_debug_segments (bool, default: False ) –

If True, plot candidate midlines considered for placement.
label_balanced_debug_kwargs (Mapping[str, Any], default: None ) –

Extra line kwargs for debug segments.
label_balanced_candidates_per_layer (int, default: 60 ) –

Number of candidate positions per layer for balanced placement.
label_balanced_restarts (int, default: 2 ) –

Number of random annealing restarts.
label_balanced_T0 (float, default: 2.5 ) –

Initial temperature for annealing.
label_balanced_T_min (float, default: 5e-4 ) –

Minimum temperature for annealing.
label_balanced_alpha (float, default: 0.94 ) –

Cooling factor per temperature step.
label_balanced_iters_per_T (int, default: 240 ) –

Iterations per temperature step.
label_balanced_min_thickness_q (float, default: 0.5 ) –

Quantile threshold of per-segment thickness used to filter candidates.

Returns:	`Axes` – The axes the streamgraph was drawn on.

Notes

Y must be non-negative.
If global_order is provided, it is used as a fixed order; otherwise the order is either the input order (sorted_streams=False) or sorted by value at each time step (sorted_streams=True).
Boundary curve interpolation is applied to both bottom and top envelopes per layer after stacking on the original grid.

Examples:

>>> import numpy as np
>>> X = np.arange(50)
>>> rng = np.random.default_rng(0)
>>> Y = np.clip(rng.normal(0.6, 0.2, size=(5, 50)), 0, None)
>>> ax = plot_streamgraph(X, Y, labels=list("ABCDE"), label_position='balanced')

smooth_series ¶

smooth_series(Y, window=1)

Apply moving average along time for each row of Y. Returns new array.

streamgraph_envelopes ¶

streamgraph_envelopes(Y, margin_frac=0.0, order_mode='by_value', X=None, wiggle_reduction='none', global_order=None)

Compute bottom and top envelopes for each layer.

Parameters:

Y ((array, shape(k, n))) –

Non-negative series as rows.
margin_frac (float, default: 0.0 ) –

Fraction of the column sum reserved for gaps between layers.
order_mode (('by_value', 'none', 'global'), default: 'by_value','none','global' ) –

Sorting at each time step, not at all, or use a fixed global order.
X (array - like or None, default: None ) –

Required when wiggle_reduction in {'weighted','l1_weighted'}. Ignored otherwise.
wiggle_reduction (('none', 'unweighted', 'weighted', 'l1_weighted'), default: 'none','unweighted','weighted','l1_weighted' ) –

Baseline strategy to reduce wiggle. 'none' uses the classic centered silhouette. 'unweighted' uses the closed-form deviation-minimizing baseline. 'weighted' uses the Streamgraph baseline (Byron–Wattenberg, L2). 'l1_weighted' uses the Di Bartolomeo & Hu (2016) L1 baseline via weighted median of (-A_i) per x, then integrates and centers.
global_order (sequence of int, default: None ) –

When order_mode='global', the fixed order of layer indices to use at all time steps. Length must match the number of rows in Y.

Returns:	`bottoms, tops : arrays of shape (k, n)` –