spectralbrain 0.0.1__tar.gz

spectralbrain-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024–2026 Rodrigo Dalvit and SpectralBrain Contributors
+
+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.

spectralbrain-0.0.1/Makefile

@@ -0,0 +1,83 @@
+# Makefile — SpectralBrain development shortcuts
+# Usage: make <target>
+#
+# This Makefile wraps common uv/pytest/ruff commands so you don't have
+# to remember the exact invocations.  It's optional — you can always
+# run the underlying commands directly.
+
+.PHONY: help install install-full test lint format build clean \
+        publish-test publish docs check-version
+
+# Default target: show available commands.
+help:
+	@echo ""
+	@echo "SpectralBrain — development commands"
+	@echo "──────────────────────────────────────────────────"
+	@echo "  make install       Install core + dev dependencies"
+	@echo "  make install-full  Install everything (gpu, viz, bayesian, neuro)"
+	@echo "  make test          Run test suite"
+	@echo "  make test-fast     Run tests without slow markers"
+	@echo "  make lint          Check code style (ruff)"
+	@echo "  make format        Auto-format code (ruff)"
+	@echo "  make build         Build sdist + wheel"
+	@echo "  make check-version Show current package version"
+	@echo "  make publish-test  Publish to TestPyPI (manual, for debugging)"
+	@echo "  make clean         Remove build artifacts"
+	@echo "  make docs          Build documentation"
+	@echo ""
+
+# ── Installation ──────────────────────────────────────────────────────
+install:
+	uv sync --group dev
+
+install-full:
+	uv sync --all-extras --group dev
+
+# ── Testing ───────────────────────────────────────────────────────────
+test:
+	uv run pytest tests/ -v --tb=short
+
+test-fast:
+	uv run pytest tests/ -v --tb=short -m "not slow"
+
+test-cov:
+	uv run pytest tests/ --cov=spectralbrain --cov-report=html --cov-report=term-missing
+	@echo "Coverage report: htmlcov/index.html"
+
+# ── Code quality ──────────────────────────────────────────────────────
+lint:
+	uv run ruff check spectralbrain/ tests/
+	uv run ruff format --check spectralbrain/ tests/
+
+format:
+	uv run ruff format spectralbrain/ tests/
+	uv run ruff check --fix spectralbrain/ tests/
+
+typecheck:
+	uv run mypy spectralbrain/
+
+# ── Build & release ───────────────────────────────────────────────────
+build: clean
+	uv build
+	@echo ""
+	@echo "Built artifacts:"
+	@ls -lh dist/
+
+check-version:
+	@uv run python -c "import spectralbrain; print(f'Version: {spectralbrain.__version__}')"
+
+# Publish to TestPyPI using uv (for manual debugging; normally the
+# GitHub Actions workflow handles this automatically).
+publish-test: build
+	uv publish --publish-url https://test.pypi.org/legacy/ --trusted-publishing always
+
+# ── Documentation ─────────────────────────────────────────────────────
+docs:
+	uv run sphinx-build -b html docs/ docs/_build/html
+	@echo "Documentation: docs/_build/html/index.html"
+
+# ── Cleanup ───────────────────────────────────────────────────────────
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .mypy_cache .ruff_cache htmlcov/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	@echo "Cleaned build artifacts."

spectralbrain-0.0.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: spectralbrain
+Version: 0.0.1
+Summary: Spectral shape analysis for brain structures via the Laplace-Beltrami operator.
+Project-URL: Homepage, https://github.com/spectralbrain/spectralbrain
+Project-URL: Documentation, https://spectralbrain.readthedocs.io
+Project-URL: Repository, https://github.com/spectralbrain/spectralbrain
+Project-URL: Issues, https://github.com/spectralbrain/spectralbrain/issues
+Project-URL: Changelog, https://github.com/spectralbrain/spectralbrain/blob/main/CHANGELOG.md
+Author-email: Rodrigo Debona <r.debona@posgrad.ufsc.br>
+Maintainer-email: Rodrigo Debona <r.debona@posgrad.ufsc.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HKS,ShapeDNA,WKS,brain,laplace-beltrami,morphometry,neuroimaging,neuroscience,shape-analysis,spectral-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.11
+Requires-Dist: h5py>=3.10
+Requires-Dist: lapy>=1.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: nibabel>=5.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyvista>=0.44
+Requires-Dist: rich>=13.7
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.13
+Requires-Dist: seaborn>=0.13
+Requires-Dist: tqdm>=4.66
+Requires-Dist: vtk>=9.3
+Provides-Extra: bayesian
+Requires-Dist: arviz>=0.18; extra == 'bayesian'
+Requires-Dist: bambi>=0.14; extra == 'bayesian'
+Requires-Dist: pymc>=5.16; extra == 'bayesian'
+Provides-Extra: full
+Requires-Dist: antspyx>=0.4; (platform_system != 'Windows') and extra == 'full'
+Requires-Dist: arviz>=0.18; extra == 'full'
+Requires-Dist: bambi>=0.14; extra == 'full'
+Requires-Dist: brainspace>=0.1.16; extra == 'full'
+Requires-Dist: cupy-cuda13x; (platform_system != 'Darwin') and extra == 'full'
+Requires-Dist: dipy>=1.9; extra == 'full'
+Requires-Dist: hippomaps; extra == 'full'
+Requires-Dist: hippunfold-plot; extra == 'full'
+Requires-Dist: ipywidgets>=8.1; extra == 'full'
+Requires-Dist: jax[cuda13]; extra == 'full'
+Requires-Dist: jupyterlab>=4.2; extra == 'full'
+Requires-Dist: mne-connectivity>=0.7; extra == 'full'
+Requires-Dist: mne>=1.7; extra == 'full'
+Requires-Dist: nilearn>=0.13; extra == 'full'
+Requires-Dist: open3d>=0.19; (python_version < '3.13') and extra == 'full'
+Requires-Dist: pybids>=0.16; extra == 'full'
+Requires-Dist: pymc>=5.16; extra == 'full'
+Requires-Dist: scienceplots>=2.1; extra == 'full'
+Requires-Dist: templateflow>=24.0; extra == 'full'
+Requires-Dist: torch>=2.4; extra == 'full'
+Requires-Dist: torchvision; extra == 'full'
+Requires-Dist: trame-vtk; extra == 'full'
+Requires-Dist: trame-vuetify; extra == 'full'
+Requires-Dist: trame>=3.6; extra == 'full'
+Requires-Dist: vedo>=2024.5; extra == 'full'
+Requires-Dist: yabplot; (python_version == '3.11.*') and extra == 'full'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda13x; (platform_system != 'Darwin') and extra == 'gpu'
+Requires-Dist: jax[cuda13]; extra == 'gpu'
+Requires-Dist: torch>=2.4; extra == 'gpu'
+Requires-Dist: torchvision; extra == 'gpu'
+Provides-Extra: neuro
+Requires-Dist: antspyx>=0.4; (platform_system != 'Windows') and extra == 'neuro'
+Requires-Dist: brainspace>=0.1.16; extra == 'neuro'
+Requires-Dist: dipy>=1.9; extra == 'neuro'
+Requires-Dist: mne-connectivity>=0.7; extra == 'neuro'
+Requires-Dist: mne>=1.7; extra == 'neuro'
+Requires-Dist: nilearn>=0.13; extra == 'neuro'
+Requires-Dist: pybids>=0.16; extra == 'neuro'
+Requires-Dist: templateflow>=24.0; extra == 'neuro'
+Provides-Extra: notebooks
+Requires-Dist: ipywidgets>=8.1; extra == 'notebooks'
+Requires-Dist: jupyterlab>=4.2; extra == 'notebooks'
+Requires-Dist: trame-vtk; extra == 'notebooks'
+Requires-Dist: trame-vuetify; extra == 'notebooks'
+Requires-Dist: trame>=3.6; extra == 'notebooks'
+Provides-Extra: viz
+Requires-Dist: brainspace>=0.1.16; extra == 'viz'
+Requires-Dist: hippomaps; extra == 'viz'
+Requires-Dist: hippunfold-plot; extra == 'viz'
+Requires-Dist: open3d>=0.19; (python_version < '3.13') and extra == 'viz'
+Requires-Dist: scienceplots>=2.1; extra == 'viz'
+Requires-Dist: vedo>=2024.5; extra == 'viz'
+Requires-Dist: yabplot; (python_version == '3.11.*') and extra == 'viz'
+Description-Content-Type: text/markdown
+
+# spectralbrain
+Input Agnostic Morfphometric Spectral Descriptors of Brain Structures Acquisition and Analysis.

spectralbrain-0.0.1/README.md

@@ -0,0 +1,2 @@
+# spectralbrain
+Input Agnostic Morfphometric Spectral Descriptors of Brain Structures Acquisition and Analysis.

spectralbrain-0.0.1/RELEASE.md

@@ -0,0 +1,196 @@
+# Release Guide — SpectralBrain
+
+This document walks through the complete release process: from bumping
+the version to seeing `spectralbrain` live on PyPI.  The workflow is
+designed so that **creating a GitHub Release** is the only manual step;
+everything else is automated.
+
+---
+
+## One-time setup (you only do this once)
+
+### 1. Configure PyPI Trusted Publisher
+
+The OIDC trusted publisher model eliminates API tokens entirely.  PyPI
+authenticates your GitHub Actions workflow via short-lived OIDC
+credentials — nothing is stored as a secret.
+
+Go to <https://pypi.org/manage/account/publishing/> and add a **pending
+publisher** with these exact values:
+
+| Field            | Value                            |
+|------------------|----------------------------------|
+| PyPI project     | `spectralbrain`                  |
+| Owner            | `<your-github-username-or-org>`  |
+| Repository       | `spectralbrain`                  |
+| Workflow name    | `publish.yml`                    |
+| Environment name | `pypi`                           |
+
+Repeat the same process on **TestPyPI** at
+<https://test.pypi.org/manage/account/publishing/>, using environment
+name `testpypi`.
+
+### 2. Create GitHub Environments
+
+In your repository, go to **Settings → Environments** and create two
+environments:
+
+**`pypi`** — for production PyPI.  Recommended protection rules:
+
+- ✅ Required reviewers (add yourself) — this adds a manual approval
+  step before the package goes live.
+- ✅ Allow only the `main` branch.
+
+**`testpypi`** — for TestPyPI.  You can skip protection rules here
+since TestPyPI is a sandbox.
+
+### 3. Verify CI is green
+
+Push the `.github/workflows/ci.yml` and `.github/workflows/publish.yml`
+files to your repository.  The CI workflow should trigger on the next
+push to `main` or any PR.  Make sure it passes before attempting a
+release.
+
+---
+
+## Making a release
+
+### Step 1 — Ensure `main` is clean
+
+```bash
+git checkout main
+git pull origin main
+uv run pytest tests/ -v         # all tests pass
+uv run ruff check spectralbrain/  # no lint errors
+```
+
+### Step 2 — Create a git tag
+
+SpectralBrain uses `hatch-vcs` for versioning: the version number is
+derived from the most recent git tag.  There is no version string to
+edit manually in `pyproject.toml`.
+
+```bash
+# Choose the next version following semantic versioning.
+# Examples: v0.1.0, v0.2.0, v1.0.0, v1.0.1
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Verify that `hatch-vcs` picks it up:
+
+```bash
+uv run python -c "import spectralbrain; print(spectralbrain.__version__)"
+# Should print: 0.1.0
+```
+
+### Step 3 — Create a GitHub Release
+
+Go to your repo's **Releases** page → **Draft a new release**:
+
+1. **Choose a tag**: select the tag you just pushed (e.g., `v0.1.0`).
+2. **Release title**: `v0.1.0` (or a descriptive name).
+3. **Description**: paste the relevant section of your CHANGELOG, or
+   click "Generate release notes" to auto-populate from merged PRs.
+4. **Pre-release**: check this box for alpha/beta/rc versions.
+5. Click **Publish release**.
+
+### Step 4 — Watch the automation
+
+Creating the release triggers `.github/workflows/publish.yml`.  Go to
+the **Actions** tab to watch the progress:
+
+1. **Build** job: builds the sdist + wheel, verifies the version
+   matches the tag, uploads artifacts.
+2. **Publish to TestPyPI** job: uploads to the TestPyPI sandbox
+   (automatic, no approval needed).
+3. **Publish to PyPI** job: waits for your manual approval (if you
+   configured environment protection), then publishes.
+
+The whole process takes about 2 minutes.
+
+### Step 5 — Verify the release
+
+```bash
+# From TestPyPI (should work immediately):
+pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            spectralbrain
+
+# From production PyPI (after approval):
+pip install spectralbrain
+python -c "import spectralbrain; print(spectralbrain.__version__)"
+```
+
+---
+
+## How versioning works
+
+SpectralBrain uses **hatch-vcs**, which reads version information
+from git tags automatically.  The rules are:
+
+| Git state                        | Resulting version        |
+|----------------------------------|--------------------------|
+| Exactly on tag `v0.2.0`         | `0.2.0`                  |
+| 3 commits after `v0.2.0`        | `0.2.1.dev3+g<hash>`    |
+| No tags at all                   | `0.1.0.dev0` (fallback) |
+| Dirty working tree on `v0.2.0`  | `0.2.1.dev0+dirty`      |
+
+This means you **never** need to edit a version string in a Python
+file.  The single source of truth is the git tag.
+
+---
+
+## Releasing a patch / hotfix
+
+```bash
+git checkout main
+# Make your fix, commit it.
+git tag v0.1.1
+git push origin main v0.1.1
+# Create a GitHub Release for v0.1.1.
+```
+
+---
+
+## Releasing a pre-release (alpha/beta/rc)
+
+```bash
+git tag v0.2.0a1    # alpha
+git tag v0.2.0b1    # beta
+git tag v0.2.0rc1   # release candidate
+git push origin v0.2.0a1
+# Create a GitHub Release and CHECK the "Pre-release" box.
+```
+
+Pre-releases go through the same pipeline.  PyPI will mark them as
+pre-release, so `pip install spectralbrain` won't pick them up unless
+the user opts in with `pip install --pre spectralbrain`.
+
+---
+
+## Troubleshooting
+
+**"Version mismatch" error in the build job**
+This means `hatch-vcs` derived a version that doesn't match the
+release tag.  Usually caused by not fetching the full git history.
+The workflow uses `fetch-depth: 0` to prevent this.  If you're
+running locally, make sure the tag is on the current commit:
+`git describe --tags --dirty`.
+
+**"Token exchange failed" in the publish job**
+The OIDC handshake between GitHub and PyPI failed.  Check that:
+(a) the workflow filename in your trusted publisher config on PyPI
+matches exactly (`publish.yml`), (b) the environment name matches
+(`pypi`), and (c) the `id-token: write` permission is present.
+
+**TestPyPI succeeds but PyPI fails**
+If you're using environment protection rules, check the Actions tab —
+the PyPI publish job may be waiting for manual approval.  Click
+"Review deployments" and approve it.
+
+**Package installs but `import spectralbrain` fails**
+Run `pip show spectralbrain` to check it's installed, then
+`python -c "import spectralbrain; print(spectralbrain.__file__)"`.
+If the version shows `0.1.0.dev0`, the git tag wasn't present at
+build time.  Rebuild with the tag on the commit.

spectralbrain-0.0.1/environment.yml

@@ -0,0 +1,160 @@
+# environment.yml — SpectralBrain + computational neuroscience workbench
+#
+# A single, robust conda environment pinned to Python 3.11 (required by
+# yabplot and open3d).  Uses conda-forge exclusively — do NOT mix with
+# the 'defaults' or 'pytorch' channels to avoid ABI conflicts.
+#
+# Create:   conda env create -f environment.yml
+# Update:   conda env update -f environment.yml --prune
+# Lock:     conda-lock lock -f environment.yml -p linux-64 -p osx-arm64
+# Activate: conda activate spectralbrain
+#
+# For the SpectralBrain library itself in editable mode, after activating:
+#   pip install -e ".[full]"
+# Or, for faster resolution:
+#   uv pip install -e ".[full]"
+
+name: spectralbrain
+channels:
+  - conda-forge
+
+dependencies:
+  # ────────────────────────────────────────────────────────────────────
+  # Python — pinned to 3.11 (yabplot / open3d / hippunfold-plot ceiling)
+  # ────────────────────────────────────────────────────────────────────
+  - python=3.11
+
+  # ────────────────────────────────────────────────────────────────────
+  # Core scientific computing
+  # ────────────────────────────────────────────────────────────────────
+  - numpy>=2.0
+  - scipy>=1.13
+  - scikit-learn>=1.4
+  - pandas>=2.2
+  - statsmodels>=0.14
+  - pingouin>=0.5
+  - networkx>=3.2
+  - h5py>=3.10
+  - sympy>=1.12
+
+  # ────────────────────────────────────────────────────────────────────
+  # Neuroimaging — core I/O and analysis
+  # ────────────────────────────────────────────────────────────────────
+  - nibabel>=5.2
+  - nilearn>=0.10
+  - dipy>=1.9
+  - mne>=1.7
+  - mne-connectivity>=0.7
+  - pybids>=0.16
+  - templateflow>=24.0
+  - fslpy>=3.18
+  - datalad>=1.0
+  - brainspace>=0.1.10
+
+  # ────────────────────────────────────────────────────────────────────
+  # Spectral geometry and 3D surfaces
+  # ────────────────────────────────────────────────────────────────────
+  - lapy>=1.0
+  - trimesh>=4.0
+  - igl>=2.5              # libigl Python bindings
+  - pyglet>=2.0
+  - vtk>=9.3
+  - pyvista>=0.44
+  - pyvistaqt>=0.11
+
+  # ────────────────────────────────────────────────────────────────────
+  # 2D visualization
+  # ────────────────────────────────────────────────────────────────────
+  - matplotlib>=3.8
+  - seaborn>=0.13
+  - plotly>=5.18
+  - statannotations
+  - python-ternary
+
+  # ────────────────────────────────────────────────────────────────────
+  # 3D visualization
+  # ────────────────────────────────────────────────────────────────────
+  - vedo>=2024.5
+
+  # ────────────────────────────────────────────────────────────────────
+  # Deep learning (conda-forge CUDA builds — single source of truth)
+  # Comment out pytorch-cuda for CPU-only machines.
+  # ────────────────────────────────────────────────────────────────────
+  - pytorch>=2.4
+  - torchvision
+  - torchaudio
+  - pytorch-cuda=12.4     # ← remove this line for CPU-only environments
+  - lightning>=2.3
+
+  # ────────────────────────────────────────────────────────────────────
+  # Bayesian inference
+  # ────────────────────────────────────────────────────────────────────
+  - pymc>=5.16
+  - arviz>=0.18
+  - bambi>=0.14
+  - nutpie>=0.12          # Rust NUTS sampler — fastest on conda-forge
+
+  # ────────────────────────────────────────────────────────────────────
+  # Jupyter / interactive / Trame
+  # ────────────────────────────────────────────────────────────────────
+  - jupyterlab>=4.2
+  - ipywidgets>=8.1
+  - trame>=3.5
+  - trame-vtk
+  - trame-vuetify
+  - nodejs>=20
+
+  # ────────────────────────────────────────────────────────────────────
+  # Graph and network analysis
+  # ────────────────────────────────────────────────────────────────────
+  - networkx>=3.2
+  - python-igraph>=0.11
+
+  # ────────────────────────────────────────────────────────────────────
+  # Development and testing
+  # ────────────────────────────────────────────────────────────────────
+  - pytest>=8.0
+  - pytest-cov>=5.0
+  - ruff>=0.5
+  - pre-commit>=3.5
+
+  # ────────────────────────────────────────────────────────────────────
+  # Build toolchain (needed by some pip packages below)
+  # ────────────────────────────────────────────────────────────────────
+  - pip
+  - setuptools>=70
+  - wheel
+  - cython>=3.0
+  - cmake>=3.27
+
+  # ────────────────────────────────────────────────────────────────────
+  # pip-only / research-only packages (not on conda-forge or pip is
+  # the canonical install method)
+  # ────────────────────────────────────────────────────────────────────
+  - pip:
+    # 3D point cloud analysis
+    - open3d>=0.19
+    - meshplot
+
+    # Brain-specific visualization
+    - scienceplots>=2.1
+    - yabplot
+    - hippunfold-plot
+    - hippomaps
+    - enigmatoolbox
+
+    # ANTsPy (complex build; pip wheel is more reliable)
+    - antspyx>=0.4
+
+    # SuStaIn (disease progression modeling)
+    - git+https://github.com/ucl-pond/pySuStaIn.git
+
+    # SpectralBrain itself (editable install from local checkout)
+    # Uncomment after cloning the repo:
+    # - -e ".[full]"
+
+variables:
+  # Prevent macOS OpenMP duplicate-runtime crash
+  KMP_DUPLICATE_LIB_OK: "TRUE"
+  # Force EGL for headless rendering (VTK 9.5+ PyPI wheel has EGL built-in)
+  PYOPENGL_PLATFORM: "egl"