unravel.allen_institute.abca.merfish.utils module#

Utilities for processing Allen Brain Cell Atlas (ABCA) MERFISH cells metadata and visualizing a brain slice with cells or gene expression data.

unravel.allen_institute.abca.merfish.utils.filter_neurons(cell_df)[source]#

Filter cells to neuronal classes (class index ≤ 29), based on integer prefix of ‘class’.

Parameters:

cell_df (DataFrame) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.load_cell_metadata(download_base_or_file)[source]#

Load MERFISH cell metadata (index: cell_label).

Parameters:

download_base_or_file (Path | str) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.join_reconstructed_coords(cell_df, download_base)[source]#

Join reconstructed coordinates + parcellation_index.

Parameters:

  • cell_df (DataFrame) –

  • download_base (Path | str) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.join_cluster_details(cell_df, download_base, species='mouse')[source]#

Join cluster annotations (class/subclass/etc.).

Parameters:

  • cell_df (DataFrame) –

  • download_base (Path | str) –

  • species (Literal['mouse', 'human']) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.join_cluster_colors(cell_df, download_base, species='mouse')[source]#

Join cluster color columns.

Parameters:

  • cell_df (DataFrame) –

  • download_base (Path | str) –

  • species (Literal['mouse', 'human']) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.join_parcellation_annotation(cell_df, download_base)[source]#

Join parcellation term acronyms.

Parameters:

  • cell_df (DataFrame) –

  • download_base (Path | str) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.join_parcellation_color(cell_df, download_base)[source]#

Join parcellation color columns.

Parameters:

  • cell_df (DataFrame) –

  • download_base (Path | str) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.filter_brain_section(cell_df, slice_index)[source]#

Subset to a single-section label by numeric slice index.

Parameters:

  • cell_df (DataFrame) –

  • slice_index (int) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.load_expression_data(download_base, imputed=False)[source]#

Open the (imputed or raw) log2 expression matrix .h5ad (backed=’r’).

Parameters:
unravel.allen_institute.abca.merfish.utils.select_gene(adata, gene)[source]#

Return (adata_subset_in_memory, gene_symbol) for a single gene.

Parameters:

gene (str) –

unravel.allen_institute.abca.merfish.utils.join_expression_to_section(adata_sub, gene_symbol, section_df)[source]#

Join single-gene expression to a section-level metadata table by cell_label.

Parameters:

  • gene_symbol (str) –

  • section_df (DataFrame) –

Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.genes_in_merfish_data(download_base)[source]#

Return list of gene symbols in the raw MERFISH log2 matrix.

Parameters:

download_base (Path | str) –

Return type:

list[str]

unravel.allen_institute.abca.merfish.utils.genes_in_imputed_merfish_data(download_base)[source]#

Return list of gene symbols in the imputed MERFISH log2 matrix.

Parameters:

download_base (Path | str) –

Return type:

list[str]

unravel.allen_institute.abca.merfish.utils.prepare_cells_table(download_base, species='mouse', include=('coords', 'cluster', 'colors', 'parcellation', 'parcellation_color'))[source]#

Run the frequent sequence of joins and return a fully enriched cell table.

include flags:

‘coords’ → reconstructed coords + parcellation_index ‘cluster’ → cluster annotations (class/subclass/etc.) ‘colors’ → cluster colors ‘parcellation’ → parcellation term acronyms ‘parcellation_color’ → parcellation colors

Parameters:
Return type:

DataFrame

unravel.allen_institute.abca.merfish.utils.build_neuron_subset(base)[source]#

Return a metadata dataframe subset containing ONLY neurons (rows where the integer prefix of the ‘class’ column <= 29)

Notes

  • Requires a ‘class’ column like ‘12 IT-L2/3 …’.

  • Adds the standard joins so downstream plotting has colors and labels.

Parameters:

base (Path) –

unravel.allen_institute.abca.merfish.utils.slice_index_dict()[source]#

Mapping from brain section labels (e.g. ‘C57BL6J-638850.40’) to corresponding slice indices in the 3D boundary volume.

Returns:

Keys are section labels, values are z indices.

Return type:

dict

unravel.allen_institute.abca.merfish.utils.load_region_boundaries(download_base)[source]#

Load the boundary NIfTI and return (array[z,y,x], extent) suitable for imshow.

Parameters:

download_base (Path | str) –

Return type:

Tuple[ndarray, Tuple[float, float, float, float]]

unravel.allen_institute.abca.merfish.utils.auto_zoom(ax, section_df, pad=0.25)[source]#

Tighten axes to the bounding box of x_reconstructed/y_reconstructed for the given section (plus a small padding).

Note: y-axis is inverted (top=small y), so we set ylim with (top, bottom).

Parameters:

pad (float) –

Return type:

None

unravel.allen_institute.abca.merfish.utils.plot_slice_color(base, slice_index, color_col, *, s_all, s_subset, alpha_all, alpha_subset, df, neurons=False)[source]#

Color mode: plots all cells for the slice using a categorical/hex color column, optionally overlays a subset, and adds boundary wireframe on top.

Parameters:

  • base (Path | str) –

  • slice_index (int) –

  • color_col (str) –

  • s_all (float) –

  • s_subset (float) –

  • alpha_all (float) –

  • alpha_subset (float) –

  • df (DataFrame | None) –

  • neurons (bool) –

unravel.allen_institute.abca.merfish.utils.plot_slice_gene(base, slice_index, gene, *, s_all, s_subset, alpha_all, alpha_subset, subset_df, imputed, neurons=False)[source]#

Gene mode: colors all cells by continuous expression (magma_r), adds a colorbar, optionally overlays a subset (also colored by expression), and adds the boundary wireframe. Highest-expressing cells are drawn last (on top).

Parameters:

  • base (Path | str) –

  • slice_index (int) –

  • gene (str) –

  • s_all (float) –

  • s_subset (float) –

  • alpha_all (float) –

  • alpha_subset (float) –

  • subset_df (DataFrame | None) –

  • imputed (bool) –

  • neurons (bool) –