Skip to content

Model bundles

HemiSpec tracks reusable model parameters under assets/models/ via Git LFS. Clone current main with Git LFS enabled; otherwise model files may remain small pointer files.

git lfs install
git clone https://github.com/mqqq333/HemiSpec.git
cd HemiSpec
git lfs pull
python -m pip install -e ".[model,classifier]"
git rev-parse HEAD

Record the printed commit hash so the code and model checkout can be identified later.

Bundled DGN checkpoints

assets/models/dgn/
  outputs_bi_stable_L/ckpts/best_netG_L.pth
  outputs_bi_stable_R/ckpts/best_netG_R.pth

These are the bilateral generator checkpoints used by hemispec workflow and the GUI. Training intermediates, discriminator checkpoints, and reconstruction previews are not shipped.

Bundled classifier models

assets/models/hemisphere_classifier/
  OUT_noICBM_train_ICBM_external_saved_models/
  OUT_noICBM_train_ICBM_external_saved_models_paired_residual/

Each metric folder contains a sanitized runtime *_model_bundle.joblib, the trained *_final_pipeline.joblib, and feature_names.csv. Public bundles exclude cohort identifiers, sample counts, evaluation metrics, training reports, and private provenance paths. The default GUI/API classifier mode uses OUT_noICBM_train_ICBM_external_saved_models; paired_residual can be selected through CLI/API configuration.

The released classifier requires its compatible Glasser 1.5 mm atlas and label table, with 180 homologous parcels per hemisphere: labels 1..180 on the left and 1001..1180 on the right. A custom atlas is supported for ROI-only export; it is not compatible with the released classifier.

Discovery order

HemiSpec resolves model paths in this order:

  1. explicit CLI/API/GUI path when provided;
  2. environment variables such as HEMISPEC_DGN_MODEL_ROOT and HEMISPEC_CLASSIFIER_MODEL_DIR;
  3. bundled source-checkout paths under assets/models/;
  4. the per-user cache (HEMISPEC_MODEL_CACHE, or the OS-specific HemiSpec cache).

Current main can download missing DGN checkpoints from the repository's Git LFS media into the per-user cache. To prefetch those checkpoints explicitly:

hemispec models --install

Although hemispec models still exposes --with-classifier, the current classifier cache download is incomplete because required feature_names.csv media URLs return HTTP 404. Use classifier assets from the Git LFS checkout or an explicit local directory instead; see Data and models.

Distribution notes

Model binaries are tracked with Git LFS. Keep raw MRI data, generated outputs, and private manuscript-only artifacts out of the repository. Additional model bundles should include provenance, compatible HemiSpec version, preprocessing assumptions, checksums, license, and citation notes.

For implementation details, see DGN model bundles. ANS/RNS and the cross-hemispheric DGN framework originate from Wang et al. (2024).