arista.viz

Publication figure builders. Sprint 8.

class arista.viz.AdaptationTaus(cell_types=('CC', 'HC'), log_tau=True, figsize=(12, 5), dpi=200, strains=None, rng_seed=19, min_r_squared=None)[source]

Bases: object

Callable wrapper holding default styling.

Parameters:
cell_types: tuple[str, ...] = ('CC', 'HC')
dpi: int = 200
figsize: tuple[float, float] = (12, 5)
log_tau: bool = True
min_r_squared: float | None = None
plot(data, *, stimulus_name=None, title=None, **overrides)[source]
Parameters:
Return type:

Figure

rng_seed: int = 19
save(fig, path, *, dpi=None, close=True)[source]

Save fig as PNG. SVG sibling is written automatically.

Parameters:

  • fig (Figure)

  • path (Path | str)

  • dpi (int | None)

  • close (bool)

Return type:

Path

strains: tuple[str, ...] | None = None
class arista.viz.GainComparison(cell_types=('CC', 'HC'), abs_gain=False, figsize=(12, 5), dpi=200, strains=None, rng_seed=13, min_steps=3)[source]

Bases: object

Callable wrapper holding default styling.

Mirrors arista.viz.response_curves.ResponseCurves so the same orchestration pattern carries over to gain figures.

Parameters:
abs_gain: bool = False
cell_types: tuple[str, ...] = ('CC', 'HC')
dpi: int = 200
figsize: tuple[float, float] = (12, 5)
min_steps: int = 3
plot(data, *, stimulus_name=None, title=None, **overrides)[source]
Parameters:
Return type:

Figure

rng_seed: int = 13
save(fig, path, *, dpi=None, close=True)[source]

Save fig as PNG. SVG sibling is written automatically.

Parameters:

  • fig (Figure)

  • path (Path | str)

  • dpi (int | None)

  • close (bool)

Return type:

Path

strains: tuple[str, ...] | None = None
class arista.viz.NompCDosage(cell_types=('CC', 'HC'), stimulus_names=('ascAmp', 'descAmp', 'ascAmpFlip', 'descAmpFlip'), abs_gain=True, figsize=(12, 5.5), dpi=200, rng_seed=23, connect_tiers=True)[source]

Bases: object

Callable wrapper for batch reuse.

Parameters:
abs_gain: bool = True
cell_types: tuple[str, ...] = ('CC', 'HC')
connect_tiers: bool = True
dpi: int = 200
figsize: tuple[float, float] = (12, 5.5)
plot(data, *, title=None, **overrides)[source]
Parameters:
Return type:

Figure

rng_seed: int = 23
save(fig, path, *, dpi=None, close=True)[source]

Save fig as PNG. SVG sibling is written automatically.

Parameters:

  • fig (Figure)

  • path (Path | str)

  • dpi (int | None)

  • close (bool)

Return type:

Path

stimulus_names: tuple[str, ...] = ('ascAmp', 'descAmp', 'ascAmpFlip', 'descAmpFlip')
class arista.viz.ResponseCurves(cell_types=('CC', 'HC'), by_x='delta_target_c', error='ci', figsize=(10, 5), dpi=200, strains=None)[source]

Bases: object

Callable wrapper holding default styling.

Useful when rendering many figures (one per stimulus protocol) with consistent kwargs:

plotter = ResponseCurves(figsize=(12, 5))
for stim in ("ascAmp", "descAmp"):
    fig = plotter(conn, stimulus_name=stim)
    plotter.save(fig, output_dir / f"resp_{stim}.png")
Parameters:
by_x: str = 'delta_target_c'
cell_types: tuple[str, ...] = ('CC', 'HC')
dpi: int = 200
error: Literal['ci', 'iqr', 'sem', 'none'] = 'ci'
figsize: tuple[float, float] = (10, 5)
plot(data, *, stimulus_name=None, title=None, **overrides)[source]
Parameters:
Return type:

Figure

save(fig, path, *, dpi=None, close=True)[source]

Save fig as PNG. SVG sibling is written automatically.

Parameters:

  • fig (Figure)

  • path (Path | str)

  • dpi (int | None)

  • close (bool)

Return type:

Path

strains: tuple[str, ...] | None = None
class arista.viz.SessionOverview(figsize=(10, 5), use_drift_corrected=True, show_target=True, show_sensor=True, sensor_alpha=0.55, cell_linewidth=1.0, dpi=200)[source]

Bases: object

Callable wrapper around plot_session_overview().

Useful when many sessions are rendered with the same styling (e.g. a batch script or the future DB-backed display layer):

plotter = SessionOverview(figsize=(12, 6), use_drift_corrected=True)
for session_name, cells in sessions.items():
    fig = plotter(cells, title=session_name)
    plotter.save(fig, output_dir / f"{session_name}.png")

Defaults stored on the instance are forwarded to every call unless overridden in the call’s kwargs.

Parameters:
cell_linewidth: float = 1.0
dpi: int = 200
figsize: tuple[float, float] = (10, 5)
plot(recordings, *, title=None, **overrides)[source]

Build the figure. overrides win over instance defaults.

Parameters:
Return type:

Figure

save(fig, path, *, dpi=None, close=True)[source]

Save the figure as a PNG (smallest disk size for a line plot).

Parameters:

  • fig (Figure) – Figure returned by plot().

  • path (Path | str) – Output path (extension forced to .png).

  • dpi (int | None) – Override the instance default DPI for this save.

  • close (bool) – Close the figure after saving to free memory.

Returns:

The resolved output path.

Return type:

Path

sensor_alpha: float = 0.55
show_sensor: bool = True
show_target: bool = True
use_drift_corrected: bool = True
class arista.viz.SigmoidFits(cell_types=('CC', 'HC'), figsize=(10, 5), dpi=200, strains=None, n_curve=200, scatter_alpha=0.18, scatter_size=8.0)[source]

Bases: object

Callable wrapper holding default styling.

Mirrors arista.viz.response_curves.ResponseCurves.

Parameters:
cell_types: tuple[str, ...] = ('CC', 'HC')
dpi: int = 200
figsize: tuple[float, float] = (10, 5)
n_curve: int = 200
plot(data, *, stimulus_name=None, title=None, **overrides)[source]
Parameters:
Return type:

Figure

save(fig, path, *, dpi=None, close=True)[source]

Save fig as PNG. SVG sibling is written automatically.

Parameters:

  • fig (Figure)

  • path (Path | str)

  • dpi (int | None)

  • close (bool)

Return type:

Path

scatter_alpha: float = 0.18
scatter_size: float = 8.0
strains: tuple[str, ...] | None = None
arista.viz.aggregate_response_data(df, *, by_x='delta_target_c', n_bootstrap=2000, confidence_level=0.95, rng_seed=42)[source]

Per (strain, cell_type, x) compute centre + spread + n.

The output carries enough columns to render any of the four supported error bands (ci / iqr / sem / none) without re-aggregating:

  • median, ci_low, ci_high — non-parametric default. CI is the percentile bootstrap CI of the median at confidence_level (default 0.95). Resampled n_bootstrap times (default 2000) from a seeded np.random.Generator.

  • q25, q75 — interquartile range (legacy error="iqr" mode).

  • mean, sem — for the parametric error="sem" mode.

  • shapiro_p — per-group Shapiro-Wilk p (NaN when n<3); used by the plot layer to gate error="sem".

  • n — recordings contributing to this (strain, cell_type, x) bucket.

Parameters:

  • df (pandas.DataFrame) – Output of fetch_response_data().

  • by_x (str) – "delta_target_c" (default, Kossen-style relative amplitude) or "target_temp_c" (absolute temperature).

  • n_bootstrap (int) – Number of bootstrap resamples for the median CI.

  • confidence_level (float) – CI coverage (default 0.95).

  • rng_seed (int) – Seed for the bootstrap RNG (reproducibility).

Return type:

pandas.DataFrame

arista.viz.discover_adaptation_stimuli(conn)[source]

Stimuli that produced adaptation_fits rows.

Parameters:

conn (Connection)

Return type:

list[str]

arista.viz.fetch_adaptation_taus(conn, *, stimulus_name=None, cell_types=('CC', 'HC'), strains=None, min_r_squared=None)[source]

Per-recording τ values joined with v_recordings metadata.

Parameters:

  • conn (Connection) – Open SQLite connection to a populated arista.db.

  • stimulus_name (str | None) – Optional stimulus filter (one figure per stimulus in the typical batch workflow).

  • cell_types (tuple[str, ...]) – Cell types to include.

  • strains (tuple[str, ...] | None) – Optional strain whitelist.

  • min_r_squared (float | None) – Drop fits below this quality threshold; None keeps every fit.

Returns:

DataFrame with one row per recording carrying recording_id, researcher_name, strain_name, cell_type, hemisphere, stimulus_name, tau_s, amplitude, asymptote, r_squared, n_points.

Return type:

pandas.DataFrame

arista.viz.fetch_dosage_gains(conn, *, stimulus_names=('ascAmp', 'descAmp', 'ascAmpFlip', 'descAmpFlip'), cell_types=('CC', 'HC'))[source]

Per-recording gains pooled across stimuli, canonicalised + dosage-tagged.

Parameters:

  • conn (Connection) – Open SQLite connection to a populated arista.db.

  • stimulus_names (tuple[str, ...]) – Thermal_step protocols to pool. Defaults to all four ramp stimuli.

  • cell_types (tuple[str, ...]) – Cell types to include.

Returns:

DataFrame with one row per (recording, stimulus) carrying the original gain columns plus canonical_strain and dosage. Rows whose strain has no entry in NOMPC_DOSAGE are dropped.

Return type:

pandas.DataFrame

arista.viz.fetch_recording_gains(conn, *, stimulus_name, cell_types=('CC', 'HC'), strains=None, min_steps=3)[source]

Per-recording gains from a populated arista.db.

Returns:

DataFrame with one row per (recording, strain, cell_type, hemisphere) carrying slope, intercept, r_squared, n_points.

Parameters:
Return type:

pandas.DataFrame

arista.viz.fetch_response_data(conn, *, stimulus_name, cell_types=('CC', 'HC'), strains=None, min_frames_in_window=50)[source]

JOIN stimulus_responses with v_recordings and filter.

Parameters:

  • conn (Connection) – Open SQLite connection to a populated arista.db.

  • stimulus_name (str) – Canonical stimulus protocol name ("ascAmp", "descAmp", …).

  • cell_types (tuple[str, ...]) – Which cell types to include.

  • strains (tuple[str, ...] | None) – Optional whitelist of canonical strain names; None means “every strain that has matching responses”.

  • min_frames_in_window (int) – Drop rows that medianed over fewer than this many frames — filters Alex’s protocol-mismatch cases where the sensor barely touched a step’s target window.

Returns:

DataFrame with one row per (recording, step).

Return type:

pandas.DataFrame

arista.viz.plot_adaptation_taus(data, *, stimulus_name=None, cell_types=('CC', 'HC'), strains=None, log_tau=True, figsize=(12, 5), title=None, rng_seed=19, min_r_squared=None)[source]

Raincloud of adaptation τ per strain × cell-type.

Parameters:

  • data (pd.DataFrame | sqlite3.Connection) – Either an already-fetched τ frame (output of fetch_adaptation_taus()) or a live SQLite connection.

  • stimulus_name (str | None) – Mandatory when data is a connection.

  • cell_types (tuple[str, ...]) – Cell types to plot, one panel per.

  • strains (tuple[str, ...] | None) – Optional strain whitelist (display order).

  • log_tau (bool) – Plot τ on a log y-axis (default). τ is positively skewed and bounded below at zero so log is the natural view; toggle off for a linear inspection.

  • figsize (tuple[float, float]) – (width, height) inches.

  • title (str | None) – Optional figure suptitle.

  • rng_seed (int) – Seed for the jitter RNG (reproducibility).

  • min_r_squared (float | None) – Forwarded to fetch_adaptation_taus().

Returns:

matplotlib.figure.Figure. Caller owns I/O.

Return type:

Figure

arista.viz.plot_gain_comparison(data, *, stimulus_name=None, cell_types=('CC', 'HC'), strains=None, abs_gain=False, min_steps=3, figsize=(12, 5), title=None, rng_seed=13)[source]

Raincloud comparison of per-recording gain across strains.

Parameters:

  • data (pd.DataFrame | sqlite3.Connection) – Either an already-computed gain frame (output of fetch_recording_gains() / compute_gains_table()) or a live SQLite connection.

  • stimulus_name (str | None) – Stimulus protocol (mandatory when data is a connection).

  • cell_types (tuple[str, ...]) – Cell types to plot, one panel per.

  • strains (tuple[str, ...] | None) – Optional strain whitelist (in display order). When None, every strain present in data is plotted in sorted order.

  • abs_gain (bool) – When True plot |slope| instead of signed slope — useful for direct cross-cell-type comparison.

  • min_steps (int) – Forwarded to compute_gains_table() when data is a connection.

  • figsize (tuple[float, float]) – (width, height) inches.

  • title (str | None) – Optional figure suptitle.

  • rng_seed (int) – Seed for the jitter RNG (reproducibility).

Returns:

matplotlib.figure.Figure. Caller owns I/O.

Return type:

Figure

arista.viz.plot_nompc_dosage(data, *, stimulus_names=('ascAmp', 'descAmp', 'ascAmpFlip', 'descAmpFlip'), cell_types=('CC', 'HC'), abs_gain=True, figsize=(12, 5.5), title=None, rng_seed=23, connect_tiers=True)[source]

One panel per cell type, raincloud per strain at its NompC dosage.

Parameters:

  • data (pd.DataFrame | sqlite3.Connection) – Either an already-fetched dosage-gain frame (output of fetch_dosage_gains()) or a live SQLite connection.

  • stimulus_names (tuple[str, ...]) – Thermal-step protocols to pool when fetching from a connection.

  • cell_types (tuple[str, ...]) – Cell types to plot, one panel per.

  • abs_gain (bool) – Plot |slope| (default, makes CC and HC comparable and reads as “how much does the cell care about temperature change”). Set False to preserve sign.

  • figsize (tuple[float, float]) – (width, height) inches.

  • title (str | None) – Optional suptitle.

  • rng_seed (int) – Seed for the raincloud jitter RNG.

  • connect_tiers (bool) – When True, overlays a thin median-vs-dosage line connecting tier centres so the dose-response trend is visible at a glance.

Returns:

matplotlib.figure.Figure. Caller owns I/O.

Return type:

Figure

arista.viz.plot_response_curves(data, *, stimulus_name=None, strains=None, cell_types=('CC', 'HC'), by_x='delta_target_c', error='ci', figsize=(10, 5), title=None, shapiro_alpha=0.05)[source]

Two-panel response curve figure: one panel per cell type.

Parameters:

  • data (pd.DataFrame | sqlite3.Connection) – Either an already-fetched DataFrame (output of fetch_response_data()) or a live SQLite connection. When a connection is passed stimulus_name becomes mandatory.

  • stimulus_name (str | None) – Stimulus protocol name (when fetching from DB).

  • strains (tuple[str, ...] | None) – Optional strain whitelist.

  • cell_types (tuple[str, ...]) – Cell types to plot, one panel per.

  • by_x (str) – "delta_target_c" (Kossen’s relative-amplitude axis, default) or "target_temp_c" (absolute).

  • error (ErrorBand) – Error band mode. "ci" (default, median + 95% bootstrap CI of the median), "iqr" (median + IQR), "sem" (mean + SEM, gated by per-x Shapiro-Wilk; falls back to "ci" with a warning on non-normality), or "none".

  • figsize (tuple[float, float]) – (width, height) inches.

  • title (str | None) – Figure suptitle. Auto-generated from stimulus_name when None.

  • shapiro_alpha (float) – Normality rejection threshold for the "sem" mode (default 0.05).

Returns:

matplotlib.figure.Figure. The caller owns I/O.

Return type:

Figure

arista.viz.plot_session_overview(recordings, *, title=None, figsize=(10, 5), use_drift_corrected=True, show_target=True, show_sensor=True, sensor_alpha=0.55, cell_linewidth=1.0)[source]

Plot one recording session as a dual-y-axis figure.

Parameters:

  • recordings (dict[str, Recording]) – Mapping cell_label → Recording. The label is the Fiji ROI filename stem (e.g. "l_CC01", "HC02"), used both for the legend and for inferring the cell type via arista.constants.infer_cell_type_from_filename().

  • title (str | None) – Figure suptitle. Typically the recording-directory path.

  • figsize (tuple[float, float]) – (width, height) in inches.

  • use_drift_corrected (bool) – If True (default) and a recording carries dfbf_drift_corrected, plot that; otherwise fall back to the raw dfbf.

  • show_target (bool) – Plot the target (set-point) temperature trace.

  • show_sensor (bool) – Overlay the measured sensor temperature trace.

  • sensor_alpha (float) – Opacity of the sensor overlay.

  • cell_linewidth (float) – Stroke width of each cell’s ΔF/F trace.

Returns:

The matplotlib.figure.Figure. The caller is responsible for savefig / plt.close — keeping I/O out of this function lets the same code run in batch scripts, notebooks, and the future GUI layer.

Raises:

ValueError – If recordings is empty.

Return type:

Figure

arista.viz.plot_sigmoid_fits(data, *, stimulus_name=None, cell_types=('CC', 'HC'), strains=None, figsize=(10, 5), title=None, n_curve=200, scatter_alpha=0.18, scatter_size=8.0)[source]

One panel per cell type; one fitted sigmoid per strain.

Parameters:

  • data (pd.DataFrame | sqlite3.Connection) – Either an already-fetched response frame (output of fetch_response_data()) or a live SQLite connection.

  • stimulus_name (str | None) – Mandatory when data is a connection.

  • cell_types (tuple[str, ...]) – Cell types to plot, one panel per.

  • strains (tuple[str, ...] | None) – Optional strain whitelist.

  • figsize (tuple[float, float]) – (width, height) inches.

  • title (str | None) – Optional figure suptitle (auto from stimulus_name).

  • n_curve (int) – Number of x-samples in each plotted sigmoid line.

  • scatter_alpha (float) – Per-point alpha for the underlying scatter.

  • scatter_size (float) – Per-point marker area for the scatter.

Returns:

matplotlib.figure.Figure. Caller owns I/O.

Return type:

Figure

Modules

adaptation_taus

Adaptation time-constant rainclouds.

gain_comparison

Compare ΔF/F-per-°C gain across strains and cell types.

nompc_dosage

Phase 7d headline figure — |gain| (or signed gain) vs NompC dosage.

recording_overview

Plot a multi-cell recording session as a dual-y-axis figure.

response_curves

Reproduce Kossen 2019 Fig 19 / 22-23: response curves per strain × cell-type.

sigmoid_fits

Sigmoid-fit overlay of the response curves.