HCPM

HCPM is a Python implementation of the Hypergraph-based Cytoarchitectonic Parcellation Method. It represents ordered cortical columns as vertices, links adjacent columns with sliding hyperedges and combines representation learning with deep embedded clustering.

This directory contains release version 0.1.0.

Repository: https://github.com/yo3nglau/HCPM

Scope

The package accepts a numeric feature matrix with one row per ordered cortical column. The default study configuration uses 49 features: ten Gray Level Index summaries, one cell-density measure and the mean and standard deviation of 19 cell-morphology measures.

The software provides:

• feature validation and within-matrix standardization;
• sliding-hyperedge construction and normalized propagation;
• a hypergraph autoencoder with deep embedded clustering;
• K-means, spectral-clustering and no-hypergraph baselines;
• deterministic seed handling and multi-seed comparisons;
• boundary-transition and tolerance-based matching utilities;
• optional preparation of 49-feature matrices from Cellpose outputs;
• machine-readable NumPy and JSON outputs;
• frozen-model inference with saved standardization parameters.

HCPM produces candidate partitions from the supplied feature matrix. Internal clustering indices and boundary counts do not by themselves establish anatomical accuracy.

Installation

Create the tested environment and install the package:

conda env create -f environment.yml
conda activate hcpm
python -m pip install -e .

Quick start

Generate an unrestricted synthetic feature matrix:

python examples/make_synthetic.py

Fit HCPM:

hcpm fit \
  --features examples/synthetic_features.npy \
  --config configs/default.yaml \
  --output results/synthetic_fit \
  --clusters 10 \
  --hyperedge-size 20 \
  --gamma 0.1 \
  --seed 2023

Compare HCPM with matched clustering baselines:

hcpm compare \
  --features examples/synthetic_features.npy \
  --output results/synthetic_comparison \
  --clusters 10 \
  --hyperedge-size 20 \
  --seeds 2023 2024 2025 2026 2027

Run the supplied frozen representative example:

hcpm predict \
  --features examples/representative_canine_visual_cortex/representative_features_2349x49.npy \
  --checkpoint examples/representative_canine_visual_cortex/reference_model.pt \
  --output results/representative_prediction

Prepare a feature matrix from compatible Cellpose tiles, ordered streamlines and a semantic mask:

python -m hcpm.prepare_features \
  --cellpose-features path/to/tile_features \
  --streamlines path/to/streamlines.npy \
  --semantic-mask path/to/semantic_mask.tif \
  --max-assignment-distance 75 \
  --output results/prepared_features

Outputs

Training writes labels, boundary positions, embeddings, standardization parameters, metrics, the resolved configuration, dependency versions and a reloadable checkpoint. Prediction writes labels, boundary positions, embeddings and a summary JSON file.

See docs/data_format.md for input definitions and docs/reproducibility.md for configuration and determinism details.

Tests

pytest -q

Data boundaries

Raw whole-slide images, cell masks and atlas-registration resources are not included. The representative example contains a derived 2,349 × 49 feature matrix and frozen outputs, without raw image data or local filesystem paths.

Licence

The software and software documentation are released under the MIT License; see LICENSE. The derived representative feature matrix, checkpoint and reference outputs are released under the Creative Commons Attribution 4.0 International License (CC BY 4.0); see DATA_LICENSE.md and DATA_NOTICE.md.