unravel.allen_institute.abca.merfish.merfish module#

Use abca_merfish or mf from UNRAVEL to plot MERFISH data from the Allen Brain Cell Atlas (ABCA). This script has several useful functions for ABCA data exploration.

Note

https://alleninstitute.github.io/abc_atlas_access/notebooks/merfish_ccf_registration_tutorial.html#read-in-section-reconstructed-and-ccf-coordinates-for-all-cells
The slice index ranges from 05 to 67.
Missing slices include: 07 20 21 22 23 34 41 63 65.

Usage for gene expression:#

abca_merfish -b path/to/base_dir -s slice -g gene

Usage for color:#

abca_merfish -b path/to/base_dir -s slice -c color

unravel.allen_institute.abca.merfish.merfish.parse_args()[source]#

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

Load the cell metadata DataFrame from the MERFISH data (using cell_label as the index).

Parameters:#

download_basePath: The root directory of the MERFISH data or the path to the cell metadata.

Returns:#

cell_dfpd.DataFrame: The cell metadata. Columns: ‘brain_section_label’, ‘cluster_alias’, ‘average_correlation_score’, ‘feature_matrix_label’, ‘donor_label’, ‘donor_genotype’, ‘donor_sex’, ‘x_section’, ‘y_section’, ‘z_section’

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

Join the cell metadata with the reconstructed coordinates (using cell_label).

Parameters:#

cell_dfpd.DataFrame: The cell metadata.
download_basePath: The root directory of the MERFISH data.

Returns:#

cell_joinedpd.DataFrame: The cell metadata joined with the reconstructed coordinates. Added columns: ‘x_reconstructed’, ‘y_reconstructed’, ‘z_reconstructed’, ‘parcellation_index’

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

Join the cell metadata DataFrame with the cluster details (using ‘cluster_alias’).

Parameters:#

cell_df_joinedpd.DataFrame: The cell metadata DataFrame [joined with other metadata].
download_basePath: The root directory of the Allen Brain Cell Atlas data.

Returns:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the cluster details. Added mouse columns: ‘neurotransmitter’, ‘class’, ‘subclass’, ‘supertype’, ‘cluster’ Added human columns: ‘neurotransmitter’, ‘supercluster’, ‘cluster’, ‘subcluster’

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

Join the cell metadata DataFrame with the cluster colors (using ‘cluster_alias’).

Parameters:#

cell_df_joinedpd.DataFrame: The cell metadata DataFrame [joined with other metadata].
download_basePath: The root directory of the Allen Brain Cell Atlas data.

Returns:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the cluster colors. Added mouse columns: ‘neurotransmitter_color’, ‘class_color’, ‘subclass_color’, ‘supertype_color’, ‘cluster_color’ Added human columns: ‘neurotransmitter_color’, ‘supercluster_color’, ‘cluster_color’, ‘subcluster_color’

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

Join the cell metadata DataFrame with the parcellation annotation (using parcellation_index).

Parameters:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the cluster colors.
download_basePath: The root directory of the MERFISH data.

Returns:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the parcellation annotation. Added columns: ‘parcellation_organ’, ‘parcellation_category’, ‘parcellation_division’, ‘parcellation_structure’, ‘parcellation_substructure’

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

Join the cell metadata DataFrame with the parcellation color (using parcellation_index).

Parameters:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the parcellation annotation.
download_basePath: The root directory of the MERFISH data.

Returns:#

cell_df_joinedpd.DataFrame: The cell metadata joined with the parcellation color. Added columns: ‘parcellation_organ_color’, ‘parcellation_category_color’, ‘parcellation_division_color’, ‘parcellation_structure_color’, ‘parcellation_substructure_color’

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

Filter the cell metadata DataFrame for a specific brain section (using brain_section_label).

Parameters:#

cell_dfpd.DataFrame: The cell metadata.
slice_indexint: The index of the brain section to filter for.

Returns:#

sectionpd.DataFrame: The cell metadata for the specified brain section.

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

Load the region boundaries from the MERFISH data.

Parameters:#

download_basePath: The root directory of the MERFISH data.

Returns:#

annotation_boundary_arraynp.ndarray: The region boundaries.
extenttuple: The extent of the image in mm coordinates for plotting with matplotlib.

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

Load MERFISH expression data from the Allen Brain Cell Atlas.

Parameters:

download_base (Path) – Root directory of the MERFISH data (e.g., /path/to/abc_download_root).
genes (str | list[str]) – One or more gene symbols to load.
imputed (bool, optional) – Whether to force loading the imputed MERFISH data. Default: False.

Returns:

adata – Expression data (backed) object. obs: ‘brain_section_label’ var: ‘gene_symbol’, ‘transcript_identifier’

Return type:

anndata.AnnData

unravel.allen_institute.abca.merfish.merfish.filter_expression_data(adata, genes)[source]#

Filter expression data for one or more genes.

Parameters:

adata (anndata.AnnData) – The MERFISH expression dataset (can be backed).
genes (list[str]) – List of gene symbols to extract.

Returns:

asubset (anndata.AnnData) – In-memory subset with columns for the selected genes.
gf (pd.DataFrame) – Gene metadata for the selected genes.

unravel.allen_institute.abca.merfish.merfish.create_expression_dataframe(ad, gf, section)[source]#

Extracts expression data for a specific gene by its symbol and returns a DataFrame.

Parameters:#

adanndata.AnnData: An anndata object containing the expression data. Columns: ‘gene_symbol’
gfpd.DataFrame: A DataFrame containing the gene metadata. Columns: ‘gene_symbol’, ‘transcript_identifier’
sectionpd.DataFrame: A DataFrame containing the cell metadata for a specific brain section. Columns: ‘brain_section_label’, ‘cluster_alias’, …

Returns:#

joinedpd.DataFrame: A DataFrame containing the expression data for the gene in the specified brain section.

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

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

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

Create a mapping of the brain section label to the corresponding slice index in the 3D image.

Returns:#

slice_index_mapdict: A mapping of the brain section label to the corresponding slice index in the 3D image.

unravel.allen_institute.abca.merfish.merfish.section_to_zindex(brain_section_label)[source]#

Convert the brain section label to the corresponding slice index in the 3D image.

Parameters:#

brain_section_labelstr: The brain section label (e.g. ‘C57BL6J-638850.05’).

Returns:#

zindexint: The corresponding slice index in the 3D image.

unravel.allen_institute.abca.merfish.merfish.plot_section(xx=None, yy=None, cc=None, val=None, pcmap=None, overlay=None, extent=None, bcmap=<matplotlib.colors.LinearSegmentedColormap object>, alpha=1.0, fig_width=6, fig_height=6)[source]#

Plot the point cloud with an overlay image.

Parameters:#

xxnp.ndarray: The x-coordinates of the points.
yynp.ndarray: The y-coordinates of the points.
ccnp.ndarray: The color of the points.
valnp.ndarray: The value of the points.
pcmapstr: The primary colormap to use for the point cloud.
overlaynp.ndarray: The overlay image.
extenttuple: The extent of the overlay image.
bcmapstr: The colormap to use for the boundary overlay.
alphafloat: The transparency of the overlay image.
fig_widthfloat: The width of the figure.
fig_heightfloat: The height of the figure.

Returns:#

figmatplotlib.figure.Figure: The figure object.
axmatplotlib.axes._axes.Axes: The axis object.

unravel.allen_institute.abca.merfish.merfish.points_to_img_sum(points_ndarray, x_size=1100, y_size=1100, pixel_size=10)[source]#

Generates a 2D image slice by summing the expression values of all cells in each pixel.

Parameters:#

points_ndarraynp.ndarray: A 2D ndarray containing the x, y coordinates of cells as well as expression values.
x_sizeint, optional: The size of the image along the x-axis. Default is 1100.
y_sizeint, optional: The size of the image along the y-axis. Default is 1100.
pixel_sizeint, optional: The size of each pixel in microns. Default is 10.

Returns:#

imgnp.ndarray: A 2D ndarray representing the image slice.

unravel.allen_institute.abca.merfish.merfish.main()[source]#