hra-amap

HRA-AMAP

HRA-AMAP (Human Reference Atlas – Automated Mapping and Projection) enables automated projection of tissue blocks from a source organ to a new reference organ—typically aligned with the Human Reference Atlas (HRA)—as part of the HuBMAP initiative.

🧬 List of available millitomes: https://cns-iu.github.io/hra-amap/millitomes.html

📦 HRA Registrations repository: https://github.com/hubmapconsortium/hra-registrations

🚀 User Setup Instructions

Clone and install the repository directly from GitHub:

pip install git+https://github.com/cns-iu/hra-amap.git@main

Make sure you have a working C++ build environment (e.g., g++, make) available on your system.
Install BCPD (an essential component of this project)

Please follow the BCPD Installation Instructions if it is not already set up on your machine.
You are now ready to run the millitome registration commands (stage-1, stage-2, or run). See Usage Instructions for details below.

🧑‍💻 Developer Setup Instructions

To contribute or develop this project locally, follow the steps below:

Clone the repository:

git clone https://github.com/cns-iu/hra-amap.git
cd hra-amap

Install BCPD by following BCPD Installation Instructions.
Install [Node.js] (https://nodejs.org/en/download/) and run the command (required create RUI JSONs for Millitomes):
```
npx github:hubmapconsortium/hra-rui-locations-processor help
```
Install Hatch (used to build and install hra-amap package locally):
```
pip install hatch
```
Install dependencies for development:
```
pip install -e .
```
Build the package (compiles the BCPD binary and packages everything)
```
hatch build
```

Install the built wheel (adjust version if needed)

pip install dist/hra_amap-0.5.0-py3-none-any.whl

(Optional) Uninstall to reset or clean up
```
pip uninstall hra-amap
```
You are now ready to run the millitome registration commands (stage-1, stage-2, or run). See Usage Instructions for details below.

🧬 Adding a New Millitome Dataset

To register a new millitome organ, organize the necessary configuration and input files as described below.

📁 Directory Structure

Each millitome dataset should be placed in its own subdirectory under:

input-data/millitome/<organ-name>-<sex>-<source>/<version>/

📦 Required Files

Place the following files inside the directory: | Filename | Description | |-----------------------|------------------------------------------------------------------| | `config.yaml` | Configuration file with metadata and registration parameters. | | `source.glb` | The `.glb` version of the source mesh for visualization in RUI. |

⚙️ Millitome Registration Usage Instructions

🔹 Stage 1: Generates the projected 3D model data

It takes a configuration file with RUI locations and donor metadata, and generates projection data that serves as input for Stage 2.

hra-amap-stage-1 \
    --config <path_to_config.yaml> \
    --output_path <path_to_output_directory> \
    --point_cloud_output_path <path_to_point_cloud_tranformation_glb>

🔹 Stage 2: Produces the final registered organ model

It takes the output from Stage 1 (a projection file), a configuration file, and produces the final registered organ models.

hra-amap-stage-2 \
    --stage1_projection_path <path_to_projections.pickle.gz> \
    --output_path <path_to_output_directory> \
    --config <path_to_config.yaml>

🔹 Run All: Register All Available Millitome Organs This command automates both Stage 1 and Stage 2 for all available millitome configurations found in the input-data/millitome/ directory.

hra-amap-run

🔄 Backward Projection & Non-HRA Mapping (Extension)

In addition to standard millitome registration workflows, HRA-AMAP supports backward projection and Non-HRA mapping, enabling tissue blocks to be projected from HRA reference organs into external (non-HRA) atlas models.

This extension is designed for scenarios where:

Donor tissue blocks must be visualized and exported in a non-HRA organ space
External anatomical atlases need to be integrated into the HRA ecosystem

🧭 Pipeline Overview

The backward mapping workflow consists of two stages:

External Atlas (non-HRA)
        ↑ (Backward Projection)
Stage 1: Projection Generation
        ↓
Projection Pickle (.pickle.gz)
        ↓
Stage 2: Non-HRA Mapping
        ↓
GLB + JSON-LD Outputs

🧪 Stage 1: Projection Generation (Backward Projection)

Stage 1 generates organ registration projections using the HRA registration pipeline.
When the --backward_projection flag is enabled, the projection direction is reversed (HRA → non-HRA).

What this stage does

Loads source and target organ models
Swaps source/target when backward projection is enabled
Runs the organ registration pipeline
Exports:
- A projection pickle file (.pickle.gz)
- A point-cloud GLB for visual verification of alignment

CLI Usage

hra-amap-stage-1 \
  --config <path_to_config.yaml> \
  --output_path <path_to_output_projection.pickle>  \
  --point_cloud_output_path <path_to_point_cloud_tranformation_glb> \
  --backward_projection

🎯 Stage 2: Non-HRA Mapping

Stage 2 consumes the projection output from Stage 1 and maps donor tissue blocks into a non-HRA organ model space.

What this stage does

Waits for the HRA database to be ready
Fetches donor samples using an ontology term
Filters samples by:
- Organ
- Donor sex
Loads projected tissue blocks
Aligns blocks into the non-HRA organ mesh
Exports visualization and semantic metadata

CLI Usage

non-hra-mapping \
  --stage1_projection_path <path_to_projections.pickle.gz> \
  --config <path_to_config.yaml> \
  --output_path <path_to_output_directory> \
  --ontology-term http://purl.obolibrary.org/obo/UBERON_<ID>

HuBMAP-derived models (e.g., GCA intestine atlas)

Use this mode when the organ mesh is already aligned to the HuBMAP Framework. In this mode the pipeline:

Uses the organ centroid as a global anatomical anchor and places tissue blocks relative to the donor dataset’s global center
Skips donor-to-organ bounding-box scaling and per-axis fitting

non-hra-mapping \
  --stage1_projection_path <path_to_projections.pickle.gz> \
  --config <path_to_config.yaml> \
  --output_path <path_to_output_directory> \
  --ontology-term http://purl.obolibrary.org/obo/UBERON_<ID> \
  --hubmap_derived_model

This site is open source. Improve this page.