spacr.toxo

Toxoplasma-specific visualisation helpers.

Every figure here is built inside _house(), which is spacr.figures.style applied as a context manager. Read that module before adding a panel; the rule it exists to enforce is that everything is grey except what the sentence is about, and this file is where breaking it was measured – see custom_volcano_plot().

Functions

custom_volcano_plot(data_path, metadata_path[, ...])	Render a volcano plot and return the significant feature names.
generate_score_heatmap(settings)	Build combined classification-score and control-fraction heatmaps for a plate.
go_term_enrichment_by_column(significant_df, metadata_path)	Compute and plot GO-term enrichment for each requested metadata column.
plot_gene_heatmaps(data, gene_list, columns[, ...])	Render a heatmap for selected genes across selected metadata columns.
plot_gene_phenotypes(data, gene_list[, x_column, ...])	Plot ranked mean phenotype with SE shading and highlight selected genes.

Module Contents

spacr.toxo.custom_volcano_plot(data_path, metadata_path, metadata_column='tagm_location', point_size=50, figsize=20, threshold=0, save_path=None, x_lim=None, y_lims=None, draw=True, highlight_location=None)

Render a volcano plot and return the significant feature names.

Plot each feature at (coefficient, -log10(p_value)). Features that do not pass the call rule are grey; called positive effects are green and called negative or zero effects are rust. This direction-based palette makes significance and effect direction the primary visual encoding. Localization is optional: highlight_location overlays selected compartments in blue instead of assigning simultaneous colours to every category.

Parameters:

• data_path (pandas.DataFrame or path-like) – Regression table containing feature, coefficient, and p_value columns. DataFrame input is copied.

• metadata_path (pandas.DataFrame or path-like) – Gene metadata containing one row per gene_nr and the selected metadata column. DataFrame input is copied.

• metadata_column (str, optional) – Localization or annotation column used by highlight_location.

• point_size (float, optional) – Marker area passed to Axes.scatter.

• figsize (float, optional) – Width and height of the square figure in inches. Typography scales with this value.

• threshold (float, optional) – Absolute coefficient threshold for calls. A row is returned when p_value <= 0.05 and abs(coefficient) >= abs(threshold).

• save_path (path-like, optional) – Destination passed to spacr.figures.scene.write_figure(), which draws the scene the screen would show and falls back to spacr.plot.save_figure(). The written extension follows the configured figure format either way.

• x_lim (sequence of float, optional) – Two x-axis limits. The default is [-0.5, 0.5].

• y_lims (sequence, optional) – Use [low, high] for one axis or [[lower_low, lower_high], [upper_low, upper_high]] for a broken y-axis. By default, fit one axis to the finite values.

• draw (bool, optional) – Build, optionally save, and show the figure. If false, return the hit list before constructing a figure.

• highlight_location (str or sequence of str, optional) – Values from metadata_column to overlay in the highlight colour and name in the in-panel legend.

Returns:

list of str – Feature-derived variable names that satisfy the call rule, in table order.

Raises:

• pandas.errors.MergeError – If the metadata contains duplicate gene_nr values and therefore cannot be joined many-to-one.

• ValueError – If y_lims does not match a supported form.

spacr.toxo.generate_score_heatmap(settings)

Build combined classification-score and control-fraction heatmaps for a plate.

Thin wrapper around spacr.submodules.generate_score_heatmap(), kept only so the historic spacr.toxo import path keeps working. This module used to carry a second copy of that function, identical to it line for line apart from the key names and the colormap, and left behind by the column_name -> columnID rename: it filtered, grouped and merged on column_name, a key no spaCR CSV carries any more, and one helper even created columnID and then immediately indexed column_name. Every call raised KeyError('column_name') on a canonical input. Rather than repair a second copy, delegate to the one that was migrated.

The only behavioural difference between the two copies was the colormap: this one hard-coded 'viridis' and ignored settings['cmap'], while the submodules version requires it. The default below preserves what toxo callers used to get while now honouring cmap when they pass it.

Imported inside the function on purpose: spacr.submodules pulls in cellpose, torch and shap at import time, and spacr.ml imports this module.

Parameters:

settings – Config dict with keys folders, csv_name, data_column, csv, cv_csv, data_column_cv, plateID, columnID, control_sgrnas, fraction_grna, dst and, optionally, cmap.

Returns:

merged DataFrame joining reads, classifier scores and CV scores per well.

spacr.toxo.go_term_enrichment_by_column(significant_df, metadata_path, go_term_columns=None)

Compute and plot GO-term enrichment for each requested metadata column.

For every go_term_column counts occurrences among hit vs background genes, runs Fisher’s exact test per term, and produces scatter plots of enrichment vs -log10(p) both per column and combined.

Parameters:

• significant_df – DataFrame of screen hits with a n_gene column.

• metadata_path – CSV path holding Gene ID plus GO-term columns.

• go_term_columns – Columns to test. Defaults to the four standard Computed/Curated GO categories.

Returns:

None. Results are displayed as Matplotlib figures.

spacr.toxo.plot_gene_heatmaps(data, gene_list, columns, x_column='Gene ID', normalize=False, save_path=None)

Render a heatmap for selected genes across selected metadata columns.

THE RAMP IS SINGLE-HUE. It was viridis, a rainbow that reads as five categories where the quantity is one ordered score; the house style’s Blues runs light to dark, so “more” is one direction rather than a tour of the spectrum. A diverging map would be right only if the values were signed, and after normalize they run 0 to 1.

Parameters:

• data – DataFrame containing per-gene rows. Copied before use – the row-key column this adds used to appear on the caller’s frame.

• gene_list – Genes to include as heatmap rows.

• columns – Column names to include as heatmap columns.

• x_column – Column holding gene identifiers for row matching.

• normalize – When True, min-max scale each gene’s row to [0, 1].

• save_path – Optional destination for the figure. Saving goes through spacr.figures.scene.write_figure() and, on its fallback, spacr.plot.save_figure(), so the format and the file extension follow the figure preference rather than always being PDF.

Returns:

None. Displays the Matplotlib figure.

spacr.toxo.plot_gene_phenotypes(data, gene_list, x_column='Gene ID', data_column='T.gondii GT1 CRISPR Phenotype - Mean Phenotype', error_column='T.gondii GT1 CRISPR Phenotype - Standard Error', save_path=None)

Plot ranked mean phenotype with SE shading and highlight selected genes.

Parameters:

• data (pandas.DataFrame) – Gene identifiers and phenotype/error columns. The frame is copied before numeric conversion.

• gene_list (iterable of str) – Gene names or TGGT1_<id> identifiers to highlight.

• x_column (str, default='Gene ID') – Column used to match gene identifiers.

• data_column (str) – Mean phenotype column plotted on the y-axis.

• error_column (str) – Standard-error column used for the uncertainty band.

• save_path (path-like, optional) – Figure destination. The configured figure format controls the final extension.

Notes

The complete ranked phenotype curve is drawn in grey and selected genes use the spaCR accent colour. The figure is displayed after optional save.

Nested helpers

plot_gene_heatmaps.extract_gene_id(gene)

Return the numeric portion of a TGGT1_<id> tag, or gene itself.

spacr/toxo.py:719

plot_gene_phenotypes.extract_gene_id(gene)

Return the numeric portion of a TGGT1_<id> tag, or gene itself.

spacr/toxo.py:623