spacr.regression_panels

Publication panel packages for regression and permutation results.

One call writes exactly four files for one manuscript panel: a vector PDF with its narrative legend, a plot-only PNG, a point-level data CSV, and a key-value statistics CSV. The numerical result table remains the source of truth; this module only applies a declared call rule and renders it.

Classes

PanelNarrative

Text placed below a panel in its PDF deliverable.

PanelStyle

Visual settings shared by all manuscript panels.

Functions

apply_primary_call(→ pandas.DataFrame)

Attach the common BH-plus-positive-gRNA-cut call fields.

build_manifest_packages(→ dict[str, Any])

Validate a declared run manifest, then write every panel and figure.

compose_vector_figure(→ pathlib.Path)

Compose one vector page and transform every URI link rectangle.

guide_control_threshold(→ tuple[float, dict[str, ...)

Return arithmetic mean + multiplier sample SD of NT gRNAs.

shared_limits(→ tuple[tuple[float, float], ...)

Return finite padded limits shared by a set of matched panels.

write_box_jitter_package(→ dict[str, pathlib.Path])

Write one deterministic box-and-jitter four-file panel package.

write_panel_package(→ dict[str, pathlib.Path])

Write the PDF, PNG, stats CSV, and plotted-data CSV for one panel.

Module Contents

class spacr.regression_panels.PanelNarrative[source]

Text placed below a panel in its PDF deliverable.

Parameters:

  • legend (str) – Panel-specific opening of the legend. The writer appends the shared palette and statistical-threshold explanations.

  • purpose (str) – Scientific question or comparison the panel was designed to address.

  • shows (str) – Direct visual result a reader should be able to find in the panel.

  • implications (str) – Interpretation supported by the displayed data, kept distinct from the observation in shows.

class spacr.regression_panels.PanelStyle[source]

Visual settings shared by all manuscript panels.

Parameters:

  • point_size (float) – Scatter-marker area in squared typographic points; must be positive.

  • point_alpha (float) – Marker and box opacity in the interval (0, 1].

  • line_width (float) – Width in points for threshold lines, spines, ticks, and box outlines.

  • line_color (str) – Matplotlib-compatible color for those lines and outlines.

  • figure_width (float) – Width in inches shared by raster, vector, and PDF deliverables.

  • plot_height (float) – Height in inches of the standalone PNG and SVG plot canvas.

  • pdf_height (float) – Height in inches of the PDF page containing plot and narrative text.

  • png_dpi (int) – Raster resolution in dots per inch used for the PNG deliverable.

  • axes_left (float) – Left edge of the plotting axes in normalized figure coordinates.

  • axes_width (float) – Width of the plotting axes as a fraction of the figure width.

  • pdf_axes_bottom (float) – Bottom edge of the PDF plotting axes in normalized figure coordinates.

  • pdf_axes_height (float) – Height of the PDF plotting axes as a fraction of the page height.

spacr.regression_panels.apply_primary_call(results: pandas.DataFrame, *, effect_column: str, bh_column: str, effect_threshold: float) → pandas.DataFrame[source]

Attach the common BH-plus-positive-gRNA-cut call fields.

Parameters:

  • results – regression results; the frame is copied, not modified.

  • effect_column – column of numeric effect sizes compared with effect_threshold; a non-numeric value raises.

  • bh_column – column whose truth value (after astype(bool)) marks rows that pass Benjamini-Hochberg correction.

  • effect_threshold – effect-size cut; primary_call is true where the BH flag is set and the effect is strictly greater than this.

spacr.regression_panels.build_manifest_packages(manifest: Mapping[str, object] | str | pathlib.Path, artifacts: Mapping[str, Mapping[str, object]], destination: str | pathlib.Path, *, style: PanelStyle = DEFAULT_PANEL_STYLE) → dict[str, Any][source]

Validate a declared run manifest, then write every panel and figure.

Parameters:

  • manifest – the figure manifest, a mapping or the path of a JSON file, with a filename-safe figure_id, an optional columns count and a non-empty panels list.

  • artifacts – run artifacts keyed by the source names the panels use; each declares level ('grna' or 'gene'), phenotype and exactly one of data (a DataFrame) or path.

  • destination – output folder; each panel is written to its own <panel_id> subfolder and the composed figure to <figure_id>.pdf.

spacr.regression_panels.compose_vector_figure(panel_pdfs: Sequence[str | pathlib.Path], destination: str | pathlib.Path, *, columns: int = 2) → pathlib.Path[source]

Compose one vector page and transform every URI link rectangle.

Parameters:

  • panel_pdfs – single-page panel PDFs, placed row by row on a grid of equal tiles; at least one is required.

  • destination – path of the composed PDF; its parent folder is created and the file is replaced atomically.

spacr.regression_panels.guide_control_threshold(guide_results: pandas.DataFrame, *, effect_column: str, guide_column: str = 'grna', multiplier: float = 3.0) → tuple[float, dict[str, float | int]][source]

Return arithmetic mean + multiplier sample SD of NT gRNAs.

Parameters:

  • guide_results – per-gRNA results; non-targeting controls are the rows whose normalised guide name starts with 000000_, and at least two are required.

  • effect_column – column of numeric control effects whose mean and sample SD define the threshold.

spacr.regression_panels.shared_limits(frames: Sequence[pandas.DataFrame], *, x_column: str, y_column: str, x_padding: float = 0.05, y_padding: float = 0.06) → tuple[tuple[float, float], tuple[float, float]][source]

Return finite padded limits shared by a set of matched panels.

Parameters:

  • frames – the panels’ data frames; at least one is required and every value in both columns must be finite.

  • x_column – column giving horizontal positions.

  • y_column – column giving vertical positions; the lower y limit is always 0.

spacr.regression_panels.write_box_jitter_package(results: pandas.DataFrame, destination: str | pathlib.Path, *, panel_id: str, category_column: str, value_column: str, category_order: Sequence[str], x_label: str, y_label: str, narrative: PanelNarrative, gene_label_column: str | None = None, gene_url_column: str | None = None, statistics: Mapping[str, object] | None = None, style: PanelStyle = DEFAULT_PANEL_STYLE) → dict[str, pathlib.Path][source]

Write one deterministic box-and-jitter four-file panel package.

Parameters:

  • results – regression results, one row per point; the frame is copied and extended with the plotted values before writing.

  • destination – folder the four files (<panel_id>.pdf, <panel_id>.png, <panel_id>_stats.csv and <panel_id>_data.csv) are written to; created if absent.

  • panel_id – panel identifier used as the file-name stem and recorded in the stats CSV.

  • category_column – column holding each row’s category, compared as strings.

  • value_column – column of vertical values; every value must be numeric and finite.

  • category_order – left-to-right order of the categories; the names must be distinct and match the observed categories exactly.

  • x_label – horizontal axis label.

  • y_label – vertical axis label.

  • narrative – legend, purpose, observation and implication text placed below the panel in the PDF.

spacr.regression_panels.write_panel_package(results: pandas.DataFrame, destination: str | pathlib.Path, *, panel_id: str, x_column: str, y_column: str, lopit_column: str, x_label: str, y_label: str, x_limits: tuple[float, float], y_limits: tuple[float, float], horizontal_threshold: float, horizontal_threshold_label: str, effect_threshold: float, effect_threshold_label: str, narrative: PanelNarrative, gene_label_column: str | None = None, gene_url_column: str | None = None, point_label_column: str | None = None, statistics: Mapping[str, object] | None = None, style: PanelStyle = DEFAULT_PANEL_STYLE, palette: Mapping[str, str] = LOPIT_COLOURS) → dict[str, pathlib.Path][source]

Write the PDF, PNG, stats CSV, and plotted-data CSV for one panel.

Parameters:

  • results – regression results, one row per point; the frame is copied and extended with the plotted values before writing.

  • destination – folder the four files (<panel_id>.pdf, <panel_id>.png, <panel_id>_stats.csv and <panel_id>_data.csv) are written to; created if absent.

  • panel_id – panel identifier used as the file-name stem and recorded in the stats CSV.

  • x_column – column of horizontal (effect) values; must be numeric.

  • y_column – column of vertical values; must be numeric.

  • lopit_column – column of LOPIT/TAGM localisation categories that colour the points; every category must have a colour in palette.

  • x_label – horizontal axis label.

  • y_label – vertical axis label.

  • x_limits – (min, max) horizontal axis limits, also recorded in the stats CSV.

  • y_limits – (min, max) vertical axis limits, also recorded in the stats CSV.

  • horizontal_threshold – y value of the dashed horizontal threshold line; points with a label that lie above it and to the right of effect_threshold get their label drawn.

  • horizontal_threshold_label – what the dashed horizontal line represents, quoted in the legend text and stats CSV.

  • effect_threshold – x value of the dotted vertical effect-threshold line.

  • effect_threshold_label – what the dotted vertical line represents, quoted in the legend text and stats CSV.

  • narrative – legend, purpose, observation and implication text placed below the panel in the PDF.