hemispec-toolkit 0.1.0__tar.gz

hemispec_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MA Qi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hemispec_toolkit-0.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include src/hemispec/py.typed
+recursive-include src/hemispec/resources *.sh
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store
+
+prune assets
+prune build
+prune dist
+prune data
+prune outputs
+prune reference
+prune p2a-session

hemispec_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: hemispec-toolkit
+Version: 0.1.0
+Summary: HemiSpec toolkit for reconstruction-derived hemispheric specificity analysis from NIfTI maps.
+Author: HemiSpec Toolkit Authors
+License-Expression: MIT
+Project-URL: Homepage, https://mqqq333.github.io/HemiSpec/
+Project-URL: Documentation, https://mqqq333.github.io/HemiSpec/
+Project-URL: Repository, https://github.com/mqqq333/HemiSpec
+Project-URL: Issues, https://github.com/mqqq333/HemiSpec/issues
+Keywords: neuroimaging,nifti,brain,hemisphere reconstruction,structural specificity,ANS,RNS
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: nibabel>=5.0
+Requires-Dist: pandas>=1.5
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: scipy>=1.9
+Requires-Dist: matplotlib>=3.5
+Provides-Extra: model
+Requires-Dist: torch>=2.0; extra == "model"
+Provides-Extra: classifier
+Requires-Dist: scikit-learn<1.8,>=1.3; extra == "classifier"
+Requires-Dist: joblib>=1.3; extra == "classifier"
+Provides-Extra: gui
+Requires-Dist: customtkinter>=5.2; extra == "gui"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pyinstaller>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Dynamic: license-file
+
+# HemiSpec
+
+**HemiSpec: Reconstruction-derived Hemispheric Specificity**
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](#)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+HemiSpec is a unified software and documentation project for reconstruction-derived hemispheric specificity analysis. The recommended user path is the PyPI package: it manages the Python runtime dependencies and installs the `hemispec` CLI and `hemispec-gui` entry points in the same environment that carries PyTorch and model-cache access. The repository also contains the MkDocs Material website, public-safe examples, tests, and release scripts.
+
+<p align="center">
+  <img src="docs/assets/figures/hemispec-study-design.png" alt="HemiSpec study design overview" width="100%">
+</p>
+
+## Recommended PyPI install / Download v0.1.0
+
+HemiSpec v0.1.0 is available as a first public beta / research-software release. PyPI is the primary install path because model-enabled workflows need a real Python/PyTorch environment; the CLI and GUI are entry points installed by that package rather than separate primary products.
+
+Install the full model/GUI-capable package from PyPI:
+
+```bash
+python -m pip install "hemispec-toolkit[gui,model,classifier]"
+hemispec --help
+```
+
+GitHub Release artifacts remain available for archived, offline, or Windows-folder fallback installs:
+
+- GitHub Release: https://github.com/mqqq333/HemiSpec/releases/tag/v0.1.0
+- Windows CLI: `HemiSpec-CLI-v0.1.0-win64.exe`
+- Windows GUI: `HemiSpec-GUI-v0.1.0-win64.zip`
+- Python artifacts: `hemispec_toolkit-0.1.0-py3-none-any.whl` and `hemispec_toolkit-0.1.0.tar.gz`
+
+The source repository carries reusable DGN generator checkpoints and hemisphere-classifier bundles under `assets/models/` via Git LFS, so users can run model-enabled workflows without retraining. Wheels and lightweight desktop builds do not embed the 300 MB+ weights, but the PyPI-installed CLI/GUI/API can auto-download the released model assets into a per-user cache on first model run. The normal path is: input preprocessed GM maps -> run HemiSpec -> get ANS/RNS maps. See [Data and models](docs/data-and-models.md) before publishing or redistributing additional assets.
+
+## Method boundary
+
+The ANS/RNS metric framework and the original cross-hemispheric DGN approach originate from Wang et al. 2024, *Patterns*, "Using a deep generation network reveals neuroanatomical specificity in hemispheres". HemiSpec builds on that framework and organizes reusable software tooling plus behavioral-phenotype downstream-analysis workflows around it.
+
+ANS and RNS remain metric names. The public package, CLI, GUI, and project identity are **HemiSpec**.
+
+## Repository layout
+
+```text
+src/hemispec/              Python package, public API, CLI, GUI, workflows
+docs/                      MkDocs Material documentation website
+tests/                     pytest regression tests with synthetic fixtures
+examples/                  public-safe examples and IO contracts
+scripts/                   release/local launcher helpers; research utilities are isolated in scripts/research
+assets/                    reusable model bundles plus local atlas/data placement docs
+.github/workflows/         CI and GitHub Pages workflows
+```
+
+Reusable DGN checkpoints and classifier bundles are tracked with Git LFS. Real subject-level NIfTI files and generated outputs remain excluded.
+
+## Install for development
+
+For normal use, install the released package from PyPI as shown above. For local development from a source checkout:
+
+```bash
+python -m pip install -e .[dev]
+python -m pytest
+```
+
+Model-enabled source-checkout extras:
+
+```bash
+python -m pip install -e .[gui,model,classifier]
+hemispec models --install --with-classifier  # optional pre-download; otherwise first model run downloads
+```
+
+## PyPI-installed CLI
+
+```bash
+hemispec --help
+python -m hemispec --help
+```
+
+## Model-enabled GUI
+
+For normal use, launch the GUI from the same PyPI/conda environment that contains PyTorch and HemiSpec. Clone with Git LFS only when you want a source checkout with repository model files:
+
+```bash
+git lfs install
+git clone https://github.com/mqqq333/HemiSpec.git
+cd HemiSpec
+git lfs pull
+python -m pip install -e .[gui,model,classifier]
+python scripts/hemispec_gui_entry.py
+```
+
+The GUI setup card should report the DGN model and classifier bundle as found after Git-LFS checkout or PyPI cache download. In a PyPI install, the first model run downloads the released model assets to the user cache if they are not already present. Provide preprocessed `*_GM_masked.nii.gz` inputs and choose an output workspace.
+
+## Public-safe quickstart
+
+```bash
+python -m pip install hemispec-toolkit
+hemispec quickstart --out-dir hemispec_quickstart
+```
+
+The built-in synthetic example creates toy NIfTI maps and validates the public file/command contract without private MRI data, model weights, or a source checkout. Source-tree wrapper scripts remain under `examples/synthetic_quickstart/` for development.
+
+## Documentation site
+
+```bash
+python -m pip install -r requirements-docs.txt
+python -m mkdocs serve
+```
+
+Build strictly before publishing:
+
+```bash
+python -m mkdocs build --strict
+```
+
+## Citation
+
+If you use the reconstruction-derived ANS/RNS framework, cite the original Patterns paper:
+
+Wang, G. et al. (2024). Using a deep generation network reveals neuroanatomical specificity in hemispheres. *Patterns*, 5, 100930. https://doi.org/10.1016/j.patter.2024.100930
+
+A separate HemiSpec handedness manuscript/software citation will be added when the manuscript, archive DOI, or release record is public.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hemispec_toolkit-0.1.0/README.md

@@ -0,0 +1,124 @@
+# HemiSpec
+
+**HemiSpec: Reconstruction-derived Hemispheric Specificity**
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](#)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+HemiSpec is a unified software and documentation project for reconstruction-derived hemispheric specificity analysis. The recommended user path is the PyPI package: it manages the Python runtime dependencies and installs the `hemispec` CLI and `hemispec-gui` entry points in the same environment that carries PyTorch and model-cache access. The repository also contains the MkDocs Material website, public-safe examples, tests, and release scripts.
+
+<p align="center">
+  <img src="docs/assets/figures/hemispec-study-design.png" alt="HemiSpec study design overview" width="100%">
+</p>
+
+## Recommended PyPI install / Download v0.1.0
+
+HemiSpec v0.1.0 is available as a first public beta / research-software release. PyPI is the primary install path because model-enabled workflows need a real Python/PyTorch environment; the CLI and GUI are entry points installed by that package rather than separate primary products.
+
+Install the full model/GUI-capable package from PyPI:
+
+```bash
+python -m pip install "hemispec-toolkit[gui,model,classifier]"
+hemispec --help
+```
+
+GitHub Release artifacts remain available for archived, offline, or Windows-folder fallback installs:
+
+- GitHub Release: https://github.com/mqqq333/HemiSpec/releases/tag/v0.1.0
+- Windows CLI: `HemiSpec-CLI-v0.1.0-win64.exe`
+- Windows GUI: `HemiSpec-GUI-v0.1.0-win64.zip`
+- Python artifacts: `hemispec_toolkit-0.1.0-py3-none-any.whl` and `hemispec_toolkit-0.1.0.tar.gz`
+
+The source repository carries reusable DGN generator checkpoints and hemisphere-classifier bundles under `assets/models/` via Git LFS, so users can run model-enabled workflows without retraining. Wheels and lightweight desktop builds do not embed the 300 MB+ weights, but the PyPI-installed CLI/GUI/API can auto-download the released model assets into a per-user cache on first model run. The normal path is: input preprocessed GM maps -> run HemiSpec -> get ANS/RNS maps. See [Data and models](docs/data-and-models.md) before publishing or redistributing additional assets.
+
+## Method boundary
+
+The ANS/RNS metric framework and the original cross-hemispheric DGN approach originate from Wang et al. 2024, *Patterns*, "Using a deep generation network reveals neuroanatomical specificity in hemispheres". HemiSpec builds on that framework and organizes reusable software tooling plus behavioral-phenotype downstream-analysis workflows around it.
+
+ANS and RNS remain metric names. The public package, CLI, GUI, and project identity are **HemiSpec**.
+
+## Repository layout
+
+```text
+src/hemispec/              Python package, public API, CLI, GUI, workflows
+docs/                      MkDocs Material documentation website
+tests/                     pytest regression tests with synthetic fixtures
+examples/                  public-safe examples and IO contracts
+scripts/                   release/local launcher helpers; research utilities are isolated in scripts/research
+assets/                    reusable model bundles plus local atlas/data placement docs
+.github/workflows/         CI and GitHub Pages workflows
+```
+
+Reusable DGN checkpoints and classifier bundles are tracked with Git LFS. Real subject-level NIfTI files and generated outputs remain excluded.
+
+## Install for development
+
+For normal use, install the released package from PyPI as shown above. For local development from a source checkout:
+
+```bash
+python -m pip install -e .[dev]
+python -m pytest
+```
+
+Model-enabled source-checkout extras:
+
+```bash
+python -m pip install -e .[gui,model,classifier]
+hemispec models --install --with-classifier  # optional pre-download; otherwise first model run downloads
+```
+
+## PyPI-installed CLI
+
+```bash
+hemispec --help
+python -m hemispec --help
+```
+
+## Model-enabled GUI
+
+For normal use, launch the GUI from the same PyPI/conda environment that contains PyTorch and HemiSpec. Clone with Git LFS only when you want a source checkout with repository model files:
+
+```bash
+git lfs install
+git clone https://github.com/mqqq333/HemiSpec.git
+cd HemiSpec
+git lfs pull
+python -m pip install -e .[gui,model,classifier]
+python scripts/hemispec_gui_entry.py
+```
+
+The GUI setup card should report the DGN model and classifier bundle as found after Git-LFS checkout or PyPI cache download. In a PyPI install, the first model run downloads the released model assets to the user cache if they are not already present. Provide preprocessed `*_GM_masked.nii.gz` inputs and choose an output workspace.
+
+## Public-safe quickstart
+
+```bash
+python -m pip install hemispec-toolkit
+hemispec quickstart --out-dir hemispec_quickstart
+```
+
+The built-in synthetic example creates toy NIfTI maps and validates the public file/command contract without private MRI data, model weights, or a source checkout. Source-tree wrapper scripts remain under `examples/synthetic_quickstart/` for development.
+
+## Documentation site
+
+```bash
+python -m pip install -r requirements-docs.txt
+python -m mkdocs serve
+```
+
+Build strictly before publishing:
+
+```bash
+python -m mkdocs build --strict
+```
+
+## Citation
+
+If you use the reconstruction-derived ANS/RNS framework, cite the original Patterns paper:
+
+Wang, G. et al. (2024). Using a deep generation network reveals neuroanatomical specificity in hemispheres. *Patterns*, 5, 100930. https://doi.org/10.1016/j.patter.2024.100930
+
+A separate HemiSpec handedness manuscript/software citation will be added when the manuscript, archive DOI, or release record is public.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

hemispec_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hemispec-toolkit"
+version = "0.1.0"
+description = "HemiSpec toolkit for reconstruction-derived hemispheric specificity analysis from NIfTI maps."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+  "numpy>=1.23",
+  "nibabel>=5.0",
+  "pandas>=1.5",
+  "openpyxl>=3.1",
+  "scipy>=1.9",
+  "matplotlib>=3.5",
+]
+authors = [
+  {name = "HemiSpec Toolkit Authors"}
+]
+keywords = [
+  "neuroimaging",
+  "nifti",
+  "brain",
+  "hemisphere reconstruction",
+  "structural specificity",
+  "ANS",
+  "RNS",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+[project.urls]
+Homepage = "https://mqqq333.github.io/HemiSpec/"
+Documentation = "https://mqqq333.github.io/HemiSpec/"
+Repository = "https://github.com/mqqq333/HemiSpec"
+Issues = "https://github.com/mqqq333/HemiSpec/issues"
+
+[project.optional-dependencies]
+model = [
+  "torch>=2.0",
+]
+classifier = [
+  "scikit-learn>=1.3,<1.8",
+  "joblib>=1.3",
+]
+gui = [
+  "customtkinter>=5.2",
+]
+dev = [
+  "pytest>=7",
+  "build>=1.0",
+  "pyinstaller>=6.0",
+  "ruff>=0.8",
+]
+
+[project.scripts]
+hemispec = "hemispec.cli:main"
+hemispec-gui = "hemispec.gui:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hemispec = [
+  "py.typed",
+  "resources/preprocess/*.sh",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+  "gui: tests requiring a graphical display/Tk",
+]
+norecursedirs = [
+  ".venv-build",
+  "build",
+  "dist",
+  "reference",
+  "assets",
+  "outputs",
+  "data",
+  "classifier_models",
+  "TRT_outputs",
+]
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+extend-exclude = [
+  "assets",
+  "build",
+  "data",
+  "dist",
+  "outputs",
+  "reference",
+]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+

hemispec_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hemispec_toolkit-0.1.0/src/hemispec/__init__.py

@@ -0,0 +1,100 @@
+"""ANS/RNS computation and validation toolkit."""
+
+from .api import (
+    DGNInferenceConfig,
+    DGNModelBundle,
+    HemisphereClassificationConfig,
+    HemisphereClassificationResult,
+    MetricComputeConfig,
+    MetricComputeResult,
+    PipelineRunConfig,
+    PipelineRunResult,
+    PreprocessingSpec,
+    ValidationConfig,
+    ValidationRunResult,
+    ValidationSummaryRow,
+    compute_ans_rns_arrays,
+    compute_metrics,
+    default_classifier_output_path,
+    default_input_glob,
+    default_trt_output_path,
+    discover_local_dgn_bundles,
+    get_preprocessing_spec,
+    infer_dgn_direction_from_path,
+    normalize_dgn_direction,
+    resolve_classifier_model_dir,
+    resolve_dgn_model_root,
+    resolve_glasser_atlas_path,
+    resolve_glasser_label_table,
+    resolve_validation_hemis,
+    run_dgn_inference,
+    run_pipeline,
+    target_hemisphere_for_direction,
+    validate_hemisphere_classification,
+    validate_reliability,
+    validate_specificity,
+)
+from .model_assets import (
+    ensure_default_classifier_models,
+    ensure_default_dgn_models,
+    ensure_default_model_assets,
+)
+from .quickstart import make_synthetic_quickstart_inputs, run_synthetic_quickstart
+from .roi import RoiSummaryConfig, summarize_maps_by_atlas
+from .workflow import (
+    BilateralWorkflowConfig,
+    BilateralWorkflowResult,
+    run_bilateral_workflow,
+    summarize_bilateral_roi_features,
+    summarize_subject_metrics,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DGNInferenceConfig",
+    "BilateralWorkflowConfig",
+    "BilateralWorkflowResult",
+    "DGNModelBundle",
+    "HemisphereClassificationConfig",
+    "HemisphereClassificationResult",
+    "MetricComputeConfig",
+    "MetricComputeResult",
+    "PipelineRunConfig",
+    "PipelineRunResult",
+    "PreprocessingSpec",
+    "RoiSummaryConfig",
+    "ValidationConfig",
+    "ValidationRunResult",
+    "ValidationSummaryRow",
+    "compute_ans_rns_arrays",
+    "compute_metrics",
+    "default_classifier_output_path",
+    "default_input_glob",
+    "default_trt_output_path",
+    "discover_local_dgn_bundles",
+    "ensure_default_classifier_models",
+    "ensure_default_dgn_models",
+    "ensure_default_model_assets",
+    "get_preprocessing_spec",
+    "infer_dgn_direction_from_path",
+    "normalize_dgn_direction",
+    "resolve_classifier_model_dir",
+    "resolve_dgn_model_root",
+    "resolve_glasser_atlas_path",
+    "resolve_glasser_label_table",
+    "resolve_validation_hemis",
+    "make_synthetic_quickstart_inputs",
+    "run_dgn_inference",
+    "run_bilateral_workflow",
+    "run_pipeline",
+    "run_synthetic_quickstart",
+    "target_hemisphere_for_direction",
+    "validate_reliability",
+    "validate_hemisphere_classification",
+    "validate_specificity",
+    "summarize_maps_by_atlas",
+    "summarize_bilateral_roi_features",
+    "summarize_subject_metrics",
+]

hemispec_toolkit-0.1.0/src/hemispec/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main(prog="hemispec")