acia.analysis.properties#

Before/after property-distribution histograms for filtered cell populations.

This module renders a grid of density-normalized histograms for one or more properties from a property-extractor DataFrame (the output of acia.analysis.ExtractorExecutor), optionally comparing an unfiltered population against a filtered one (e.g. via acia.segm.filter.apply_cell_filters()). Properties are laid out as columns; when a filtered (“after”) DataFrame is given, before/after are stacked as rows within the same column and share identical bin edges and axis limits, so outliers can be visually confirmed to “stay or vanish” under filtering.

acia.analysis.properties.plot_property_histograms(df_before, properties, *, df_after=None, units=None, bins=50, log_y=False, show_removed=False)[source]#

Plot density-normalized before/after histograms for one or more properties.

Properties are h-stacked as columns. When df_after is given, before (row 0) and after (row 1) are v-stacked as rows within each column, and share identical bin edges (computed from the combined range of df_before/df_after for that property) and identical x/y axis limits, so the two histograms for one property stay directly comparable.

Parameters:

  • df_before (pd.DataFrame) – the unfiltered (or “before”) property DataFrame, e.g. the output of acia.analysis.ExtractorExecutor.execute().

  • properties (Sequence[str]) – column names of df_before (and df_after, if given) to plot, one column of the grid per property.

  • df_after (pd.DataFrame | None) – optional filtered (or “after”) property DataFrame with the same columns as df_before. When given, the grid gains a second row per property for direct before/after comparison. When None, only df_before is plotted (one row).

  • units (dict[str, pint.Unit] | None) – optional column -> pint.Unit mapping (e.g. acia.analysis.ExtractorExecutor.units) used to format each column’s x-axis label as f"{prop} [{unit:~L}]". Properties missing from units (or units=None) fall back to the bare property name.

  • bins (int) – number of histogram bins (default 50).

  • log_y (bool) – if True, every Axes’ y-scale is set to "log" (still density-normalized). Default is linear.

  • show_removed (bool) – if True and df_after is an index-subset of df_before, overlay the filtered-out cells (before minus after) on each “after” histogram as a red step outline, so you can see where in the property’s range the filter cut. Density-normalized (shows location/shape, not count). Default False.

Returns:

A matplotlib Figure with a 1 x len(properties) grid (df_after=None) or 2 x len(properties) grid (df_after given) of density histograms. The figure is not shown (no plt.show()).

Raises:

  • TypeError – if properties is a bare str instead of a sequence of column names (a plausible typo, e.g. "area" instead of ["area"], that would otherwise be silently iterated character-by-character).

  • ValueError – if properties is empty. A property with no finite values to plot – an empty population (0 rows), an empty df_after (all cells filtered out), or an all-NaN column – is not an error: that axis is drawn empty with a “no cells” note.

  • KeyError – if a property in properties is not a column of df_before (or df_after, when given).

Return type:

Figure