spacr.figures.distributions

Well-level distribution panels for regression reports.

This module plots normalized guide representation and response distributions from the table used to fit a model. These panels remain separate from spacr.figures.panels, whose registry consumes coefficient tables. Returned Panel records include the plotted data and the statistics needed to interpret each distribution.

Functions

build_panel(key, frame, *[, target, figsize])	Draw one distribution panel on its own figure and return (figure, Panel).
fraction_column(→ Optional[str])	Return the first known guide-share column in frame, or None.
gini(→ float)	The Gini coefficient of a non-negative sample.
guide_fraction(→ spacr.figures.panels.Panel)	Draw a histogram of guide representation within wells on ax and return its panel record.
one_value_per_well(frame, column, well)	Return the response once per well when it is constant within every well.
relative_representation(frame, fraction, well)	Each guide's share of its well, divided by an equal split of that well.
response(→ spacr.figures.panels.Panel)	Draw the response histogram with skewness and excess kurtosis on ax and return its panel record.
response_column(→ Optional[str])	Return the name of the response column, or None when none is found.
save_distributions(→ Dict[str, str])	Write both distributions into a run's results folder.
shape_of(→ dict)	Return the skewness, excess kurtosis and a short verdict for the finite values.
well_column(→ Optional[str])	The well identifier, or None when the frame does not carry one.

Module Contents

spacr.figures.distributions.build_panel(key: str, frame, *, target: str | None = None, figsize=(3.4, 2.6), **kwargs)

Draw one distribution panel on its own figure and return (figure, Panel).

The same shape and the same margins as spacr.figures.sheet.build_panel() so a saved distribution sits beside a saved volcano at the same size on the grid. The style is applied as a context manager, as everywhere in this package: spaCR draws from a long-lived GUI and a global rcParams write would restyle every later figure in the session.

Parameters:

• key – distribution-panel name from REGISTRY.

• frame – data table consumed by the selected panel.

spacr.figures.distributions.fraction_column(frame) → str | None

Return the first known guide-share column in frame, or None.

Parameters:

frame – table whose columns are searched for a known guide-share name.

spacr.figures.distributions.gini(values) → float

The Gini coefficient of a non-negative sample.

0 when every value is equal, approaching 1 when one value holds everything. The standard evenness statistic for a pooled library, and the same one spacr.plot.plot_lorenz_curves() reports.

The statistic is the same but its input is not, although both are labelled “Gini”. The Lorenz curves take raw gRNA counts pooled over a plate; this panel takes each guide’s share of its own well divided by that well’s equal split. On the tsg101 screen those are 0.20 and 0.32 – the panel’s is larger because normalising by the well removes the between-well spread that flattens the pooled curve. The two values are therefore not comparable.

NaN for an empty sample, one with a negative value, or one that sums to zero, rather than a ZeroDivisionError or a silent 0.0 – an evenness of zero would be read as “perfectly even”, which is the opposite of “there was nothing to measure”.

Parameters:

values – guide-representation values; non-finite values are ignored.

spacr.figures.distributions.guide_fraction(ax, frame, *, well: str | None = None, bins: int | None = None, relative: bool = True) → spacr.figures.panels.Panel

Draw a histogram of guide representation within wells on ax and return its panel record.

Each guide’s share of its well, divided by the well’s equal share when relative is true (the default), is plotted on a log2 axis because the quantity is a ratio: half and twice equal representation are the same distance from 1, which they are not on a linear axis, and a library’s abundances are approximately log-normal.

Parameters:

• ax – Matplotlib axes on which to draw the histogram.

• frame – guide-level table containing a recognized share column and, for the relative view, a well identifier.

spacr.figures.distributions.one_value_per_well(frame, column: str, well: str | None)

Return the response once per well when it is constant within every well.

(values, deduplicated).

The pipeline passes the response as one row per guide-in-well, but the response is a property of the well – on the reference screen log_pred has exactly one distinct value in each of the 610 wells, repeated once per guide the well retained. Counting every row would count a 15-guide well fifteen times and give n = 1,945 for 610 independent observations, overstating the evidence three-fold and weighting the distribution towards wells with many guides.

If the response varies within any well, every row is kept, because collapsing it would then be wrong.

Parameters:

• frame – observation table containing the response and optional well identifier.

• column – response column to extract from frame.

• well – well-identifier column, or None to retain every response observation.

spacr.figures.distributions.relative_representation(frame, fraction: str, well: str)

Each guide’s share of its well, divided by an equal split of that well.

(values, dropped_wells, dropped_rows). 1.0 means the guide holds exactly its share; 2.0 means twice what an equal split would give it.

The raw fraction confounds evenness with how many guides were retained in the well: a two-guide well and a fifteen-guide well produce shares an order of magnitude apart with no unevenness at all. Dividing by the well’s own equal share removes that dependence, so a single reference line at 1 applies to every well.

Parameters:

• frame – guide-level table containing the share and well columns.

• fraction – name of the guide-share column in frame.

• well – name of the well-identifier column in frame.

spacr.figures.distributions.response(ax, frame, *, column: str | None = None, well: str | None = None, bins: int | None = None, family: str = 'gaussian') → spacr.figures.panels.Panel

Draw the response histogram with skewness and excess kurtosis on ax and return its panel record.

For family='gaussian' a normal curve with the response’s mean and SD is drawn over the histogram. Skewness and excess kurtosis are printed on the panel, so symmetry does not have to be judged by eye.

Parameters:

• ax – Matplotlib axes on which to draw the histogram.

• frame – model-input table containing the response observations.

spacr.figures.distributions.response_column(frame, column: str | None = None) → str | None

Return the name of the response column, or None when none is found.

An explicit column is returned when the frame has it, and None otherwise; the pipeline knows its dependent variable and should pass it. Without one, a frame with exactly one numeric column (the shape dmatrices returns) uses that column. Otherwise the first name in RESPONSE_COLUMNS that the frame has is used, and the panel labels its axis with the column it drew.

Parameters:

frame – model-input table whose numeric and named response columns are inspected.

spacr.figures.distributions.save_distributions(frame, dst, *, response_variable: str | None = None, target: str | None = None, order: Sequence[str] = ORDER) → Dict[str, str]

Write both distributions into a run’s results folder.

Returns {panel_name: path} for panels that were drawn; unavailable panels are omitted. The function never opens an interactive window.

The default target='print' produces page-readable ink for saved files. Pass another target explicitly when the output will be embedded on a GUI surface.

Parameters:

• frame – well- or guide-level table consumed by the distribution panels.

• dst – results directory in which to write the panel files.

spacr.figures.distributions.shape_of(values) → dict

Return the skewness, excess kurtosis and a short verdict for the finite values.

Returned rather than printed so a test can assert the number a reader is shown, and so the console summary can quote the same one the panel does instead of computing its own.

Parameters:

values – response values whose finite observations define the shape.

spacr.figures.distributions.well_column(frame) → str | None

The well identifier, or None when the frame does not carry one.

Parameters:

frame – table whose columns are searched for a known well identifier.