unravel.allen_institute.abca.scRNA_seq.expression_plot module

Use abca_scRNAseq_expression_plot (rna_exp_plot) from UNRAVEL to plot expression summary CSVs.

Inputs:

• Wide CSVs produced by abca_scRNAseq_expression_summary (rna_exp_summary).

Plots:

• Dot plot (default): dot color = mean log2(CPM+1) expression; dot size = percent expression above the threshold used by expression_summary.py.

• Heatmap: mean expression, percent expression, or both.

The script auto-detects genes from columns ending in _mean_expression.

# Top 50 by expression, ordered by expression –rank-by mean

# Top 50 by expression, then reorder those 50 by prevalence –rank-by mean –sort-by cells

Usage (sorting by mean expression by default):

rna_exp_plot -i path/expression_summary_thr3/5HTR__Human_NAC__supercluster.csv [-ct cell_type1 cell_type2 …] [-g gene1 gene2 …] [-n 50] [–rank-by …] [–sort-by …] [–no-cell-stats] [-p dotplot|heatmap|both] [–heatmap-metric <value>] [–mean-max <value>] [–percent-max <value>] [–size-min <value>] [–size-max <value>] [–mean-cmap <cmap>] [–percent-cmap <cmap>] [–annotate] [-o output_dir] [-op output_prefix] [-f png|pdf|svg] [–dpi <value>] [-v]

Usage for selected cell types and genes (ranked by mean expression and sorted by cell count):

rna_exp_plot -i path/expression_summary_thr3/5HTR__Human_NAC__supercluster.csv -ct “Medium spiny neuron” “Eccentric medium spiny neuron” -g DRD1 DRD2 –sort-by cells

Usage for the 50 most abundant cell types sorted by abundance:

rna_exp_plot -i file.csv –rank-by cells

Usage for parallel processing:

fd -e csv -d 1 -j 4 -x rna_exp_plot -i {}

unravel.allen_institute.abca.scRNA_seq.expression_plot.parse_args()

unravel.allen_institute.abca.scRNA_seq.expression_plot.safe_name(value)

Convert text to a file-name-safe string.

Parameters:

value (str) –

Return type:

str

unravel.allen_institute.abca.scRNA_seq.expression_plot.natural_sort_text(value)

Return a zero-padded natural-sort key.

Return type:

str

unravel.allen_institute.abca.scRNA_seq.expression_plot.color_cell_type_tick_labels(ax, df)

Bold and color y-axis cell-type labels.

Parameters:

• ax (Axes) –

• df (DataFrame) –

Return type:

None

unravel.allen_institute.abca.scRNA_seq.expression_plot.detect_genes(columns)

Detect genes from wide mean-expression column names.

Parameters:

columns (list[str]) –

Return type:

list[str]

unravel.allen_institute.abca.scRNA_seq.expression_plot.validate_and_select_genes(df, requested_genes)

Return requested or detected genes and validate plot metrics.

Parameters:

• df (DataFrame) –

• requested_genes (list[str] | None) –

Return type:

list[str]

unravel.allen_institute.abca.scRNA_seq.expression_plot.row_rank(df, genes, rank_by)

Calculate the metric used to select and sort cell types.

Parameters:

• df (DataFrame) –

• genes (list[str]) –

• rank_by (str) –

Return type:

Series

unravel.allen_institute.abca.scRNA_seq.expression_plot.prepare_plot_dataframe(df, genes, cell_types, contains, min_cells, min_percent_cells, top, rank_by, sort_by, show_cell_stats)

Filter, rank, sort, and label summary rows for plotting.

Parameters:

• df (DataFrame) –

• genes (list[str]) –

• cell_types (list[str] | None) –

• contains (list[str] | None) –

• min_cells (int) –

• min_percent_cells (float) –

• top (int) –

• rank_by (str) –

• sort_by (str) –

• show_cell_stats (bool) –

Return type:

DataFrame

unravel.allen_institute.abca.scRNA_seq.expression_plot.summary_context(df)

Return species, level, and threshold labels from a summary CSV.

Parameters:

df (DataFrame) –

Return type:

tuple[str, str, str]

unravel.allen_institute.abca.scRNA_seq.expression_plot.default_title(df, custom_title)

Create a base title from summary metadata.

Parameters:

• df (DataFrame) –

• custom_title (str | None) –

Return type:

str

unravel.allen_institute.abca.scRNA_seq.expression_plot.automatic_figure_size(n_rows, n_genes, width, height)

Choose a readable figure size while allowing explicit overrides.

Parameters:

• n_rows (int) –

• n_genes (int) –

• width (float | None) –

• height (float | None) –

Return type:

tuple[float, float]

unravel.allen_institute.abca.scRNA_seq.expression_plot.matrix_for_metric(df, genes, suffix)

Return a numeric cell-type by gene matrix.

Parameters:

• df (DataFrame) –

• genes (list[str]) –

• suffix (str) –

Return type:

ndarray

unravel.allen_institute.abca.scRNA_seq.expression_plot.finite_max(values, fallback=1.0)

Return a positive finite maximum suitable for a color scale.

Parameters:

• values (ndarray) –

• fallback (float) –

Return type:

float

unravel.allen_institute.abca.scRNA_seq.expression_plot.save_figure(fig, output_path, dpi)

Save and close a Matplotlib figure.

Parameters:

• fig (Figure) –

• output_path (Path) –

• dpi (int) –

Return type:

None

unravel.allen_institute.abca.scRNA_seq.expression_plot.plot_dotplot(df, genes, title, output_path, threshold, width, height, mean_max, percent_max, size_min, size_max, mean_cmap, dpi)

Plot mean expression as color and percent expression as dot size.

Parameters:

• df (DataFrame) –

• genes (list[str]) –

• title (str) –

• output_path (Path) –

• threshold (str) –

• width (float | None) –

• height (float | None) –

• mean_max (float | None) –

• percent_max (float) –

• size_min (float) –

• size_max (float) –

• mean_cmap (str) –

• dpi (int) –

Return type:

None

unravel.allen_institute.abca.scRNA_seq.expression_plot.plot_heatmap(df, genes, metric, title, output_path, threshold, width, height, mean_max, percent_max, mean_cmap, percent_cmap, annotate, dpi)

Plot a mean- or percent-expression heatmap.

Parameters:

• df (DataFrame) –

• genes (list[str]) –

• metric (str) –

• title (str) –

• output_path (Path) –

• threshold (str) –

• width (float | None) –

• height (float | None) –

• mean_max (float | None) –

• percent_max (float) –

• mean_cmap (str) –

• percent_cmap (str) –

• annotate (bool) –

• dpi (int) –

Return type:

None

unravel.allen_institute.abca.scRNA_seq.expression_plot.main()