Hippocampal flatmaps

This repository describes the workflow for generating hippocampal flatmaps used in Bhandiwad et al. 2024. The repository also provides Python code for generating flatmaps from volumetric data and point cloud data (eg. spatial transcriptomic data, single neuron reconstructions) registered to the Allen CCFv3 template (P56) or epDev template (P04, P14).

Important note - The repository is dependent on streamlines generated from a forked instance of the IBL cortical streamlines repository. Please refer to the repo for more information about the implementation.

Quick start

1. Set up conda environment

conda env create -f flatmap.yml
conda activate flatmap

2. Download data files

Before creating flatmaps, users must download the relevant data files to their local machine. Data files contain references to the hippocampal mask, {x,y,z} to streamline mapping tables, precalculated nearest-neighbor tables for interpolation, etc.

In this example, we will use P56_HPF.hdf5 as the reference file for mapping adult mouse HPF data. Reference files are available for P56, P14, and P04 separately. For spatial transcriptomic data, we will also need P56_spatial_tx_cells.parquet, which contains HPF cells

Please note that these data files are large (3-5 GB).

Volumetric data

All volumetric data used for mapping should be registered to CCF. All volumetric data used are oriented in ASL orientation and are 10 micron voxel resolution.

To use this functionality, run the terminal command

python -m flatmap_image_volume.py
--inputfile path/to/input/volume/file
--region P56_HPF
--flatmaprefs path/to/flatmap_refs.hdf5
--outputfile path/to/output/file.nii.gz

Notes

• The --upsample flag can be used for volumes that need to be resampled to 10 micron resolution. If your input volume is already at 10 um voxel resolution, omit this flag.
• The --noninterpolation flag can be used for point cloud-type data that does not need to be interpolated.
• This command will generate a flatmap slab volume path/to/output/file.nii.gz
• Valid commands for --region are P56_HPF, P14_HPF, or P04_HPF. This will be updated as more regions generated.

Spatial transcriptomic data

Spatial transcriptomic data is aggregated from two Allen Institute datasets (Yao et al. 2023) and Zhang et al. (2023), which can be accessed using the ABC atlas.

To use this functionality, run the following terminal command:

python -m flatmap_spatial_tx.py
--level cell_type_ontology_level
--subset all
--refpath path/to/refs/directory
--outputfile path/to/output/file.nii.gz

Notes

• Commonly used levels are neurotransmitter, class, subclass, and supertype
• Subset is used to filter the categories in level. Default is all, which maps all cells
• Requires refpath as the directory where P56_HPF.hdf5 and P56_HFP_spatial_tx_cells.parquet files are stored locally

Single neuron morphology data

Single neuron morphology data is read from a *.swc file, which represents a neuron as a set of nodes with parent-child relationships in a tree-like structure. Because streamlines are only calculated within the hippocampal formation, any node that exists outside of the HPF along with all descendant nodes creates a break. Currently, curvilinear coordinate transformation is performed on the set of nodes that exist in the HPF using the flatmap_points function.

Level of support

We are not currently supporting this code, but simply releasing it to the community AS IS but are not able to provide any guarantees of support. The community is welcome to submit issues, but you should not expect an active response.