nltools 0.5.0__tar.gz → 0.6.0.dev0__tar.gz

nltools-0.6.0.dev0/.gitignore

@@ -0,0 +1,93 @@
+# Python Related #
+###################
+*.pyc
+*.log
+*.egg*
+build/
+dist/
+.cache/
+htmlcov
+.pytest_cache/*
+dev/
+# Logs and databases #
+######################
+*.log
+*.sql
+*.sqlite
+*.json
+
+# iPython Notebook Caches #
+###########################
+.ipynb_checkpoints
+
+# OS generated files #
+######################
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+thumbs.db
+Thumbs.db
+
+# Tests & Coverage
+##################
+.coverage
+htmlcov/
+.pytest_cache
+
+# PyCharm
+#########
+.idea
+
+# TOX
+#####
+.tox
+.tox/*
+
+# Docs
+######
+examples/**/*.nii.gz
+data.nii.gz
+environment.yml
+rep_id.csv
+y.csv
+env
+.vscode/settings.json
+.vscode/bookmarks.json
+dev.py
+dev.ipynb
+.venv
+docs/**/*.nii.gz
+.ruff_cache/
+audit/
+claude-research/
+
+# Nifti templates + parcellations — fetched lazily from
+# https://huggingface.co/datasets/nltools/niftis on first use
+nltools/resources/niftis/
+
+*.db
+scripts/sub-*
+*.nii.gz
+scratch/
+.playwright-cli/
+**/__pycache__/
+.kata.local.toml
+
+# Zensical site output
+/site/
+
+# Tutorial pages: build artifacts generated from the marimo notebooks beside
+# them by scripts/marimo_to_zensical.py (`uv run poe docs-generate`). The
+# patterns match the notebooks (scripts/marimo_to_zensical.py TUTORIAL_GLOBS),
+# so a hand-written page in either directory is still tracked.
+docs/tutorials/basics/[0-9]*_*.md
+docs/tutorials/data-operations/[0-9]*_*.md
+docs/tutorials/analysis/[0-9]*_*.md
+docs/tutorials/workflows/[0-9]*_*.md
+
+# The tutorials' joblib fit cache, `Memory(".tutorial-cache")`, and the recorded
+# page outputs docs_show replays (pages/). Deliberately not under .cache/, which
+# is zensical's and which `zensical build -c` wipes whole.
+/.tutorial-cache/

{nltools-0.5.0 → nltools-0.6.0.dev0}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2018 Cosan Lab
+Copyright (c) 2015-2026 Cosan Lab & SciMinds Research Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

nltools-0.6.0.dev0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: nltools
+Version: 0.6.0.dev0
+Summary: A Python package to analyze neuroimaging data
+Project-URL: Homepage, https://nltools.org
+Author-email: "Luke J. Chang" <luke.j.chang@dartmouth.edu>, Eshin Jolly <eshin.jolly@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: analysis,machine-learning,neuroimaging,preprocessing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: anywidget>=0.9
+Requires-Dist: h5py>=3.13
+Requires-Dist: himalaya<0.5,>=0.4.11
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: joblib>=1.5.3
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: nibabel>=5.2.0
+Requires-Dist: nilearn>=0.14.1
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: polars>=1.33.1
+Requires-Dist: pynv>=0.3
+Requires-Dist: scikit-learn>=1.8
+Requires-Dist: scipy>=1.11.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: tqdm>=4.67.1
+Provides-Extra: all
+Requires-Dist: h5py>=3.13; extra == 'all'
+Requires-Dist: ipywidgets>=8.1.7; extra == 'all'
+Requires-Dist: networkx>=3.5; extra == 'all'
+Provides-Extra: graph
+Requires-Dist: networkx>=3.5; extra == 'graph'
+Provides-Extra: h5
+Requires-Dist: h5py>=3.13; extra == 'h5'
+Provides-Extra: interactive-plots
+Requires-Dist: ipywidgets>=8.1.7; extra == 'interactive-plots'
+Description-Content-Type: text/markdown
+
+[![Package versioning](https://img.shields.io/pypi/v/nltools.svg)](https://pypi.org/project/nltools/)
+[![CI](https://github.com/cosanlab/nltools/actions/workflows/ci.yml/badge.svg)](https://github.com/cosanlab/nltools/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/cosanlab/nltools/branch/master/graph/badge.svg)](https://codecov.io/gh/cosanlab/nltools)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2229813.svg)](https://doi.org/10.5281/zenodo.2229813)
+![Python Versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+![Platforms](https://img.shields.io/badge/platform-linux%20%7C%20osx%20%7C%20win-blue)
+
+# NLTools
+
+Python toolbox for analyzing neuroimaging data, with a focus on multivariate analyses. It grew out of Tor Wager's object-oriented Matlab [CANlab core tools](http://wagerlab.colorado.edu/tools) and builds on [nilearn](https://nilearn.github.io) and [scikit-learn](https://scikit-learn.org). Requires Python 3.11+.
+
+## Documentation
+
+Documentation and tutorials are available at https://nltools.org
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/) (recommended, for use in a project):
+
+```
+uv add nltools
+```
+
+Or with pip:
+
+```
+pip install nltools
+```
+
+## Development
+
+`uv` manages the whole workflow — it creates the virtual environment, installs core and development dependencies, and installs `nltools` into it in editable mode.
+
+```
+git clone https://github.com/cosanlab/nltools
+cd nltools
+uv sync
+```
+
+Common tasks (run via [poe](https://poethepoet.natn.io/), all prefixed with `uv run`):
+
+| Command | What it does |
+|---|---|
+| `uv run poe lint` | Fix, format, and type-check (ruff + ty) |
+| `uv run poe test` | Run the fast test suite in parallel |
+| `uv run pytest -k test_name` | Run a specific test |
+| `uv run poe docs-serve` | Live-preview the docs site at localhost:8000 (executes tutorials via the cache) |
+| `uv run poe docs-build` | Full docs build (API reference + executed tutorials) |
+| `uv run poe tutorials` | Run every tutorial notebook end-to-end |
+| `uv build` | Build the package locally |
+| `uv add/remove [--dev] pkg` | Add or remove a (dev) dependency |

nltools-0.6.0.dev0/README.md

@@ -0,0 +1,51 @@
+[![Package versioning](https://img.shields.io/pypi/v/nltools.svg)](https://pypi.org/project/nltools/)
+[![CI](https://github.com/cosanlab/nltools/actions/workflows/ci.yml/badge.svg)](https://github.com/cosanlab/nltools/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/cosanlab/nltools/branch/master/graph/badge.svg)](https://codecov.io/gh/cosanlab/nltools)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2229813.svg)](https://doi.org/10.5281/zenodo.2229813)
+![Python Versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+![Platforms](https://img.shields.io/badge/platform-linux%20%7C%20osx%20%7C%20win-blue)
+
+# NLTools
+
+Python toolbox for analyzing neuroimaging data, with a focus on multivariate analyses. It grew out of Tor Wager's object-oriented Matlab [CANlab core tools](http://wagerlab.colorado.edu/tools) and builds on [nilearn](https://nilearn.github.io) and [scikit-learn](https://scikit-learn.org). Requires Python 3.11+.
+
+## Documentation
+
+Documentation and tutorials are available at https://nltools.org
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/) (recommended, for use in a project):
+
+```
+uv add nltools
+```
+
+Or with pip:
+
+```
+pip install nltools
+```
+
+## Development
+
+`uv` manages the whole workflow — it creates the virtual environment, installs core and development dependencies, and installs `nltools` into it in editable mode.
+
+```
+git clone https://github.com/cosanlab/nltools
+cd nltools
+uv sync
+```
+
+Common tasks (run via [poe](https://poethepoet.natn.io/), all prefixed with `uv run`):
+
+| Command | What it does |
+|---|---|
+| `uv run poe lint` | Fix, format, and type-check (ruff + ty) |
+| `uv run poe test` | Run the fast test suite in parallel |
+| `uv run pytest -k test_name` | Run a specific test |
+| `uv run poe docs-serve` | Live-preview the docs site at localhost:8000 (executes tutorials via the cache) |
+| `uv run poe docs-build` | Full docs build (API reference + executed tutorials) |
+| `uv run poe tutorials` | Run every tutorial notebook end-to-end |
+| `uv build` | Build the package locally |
+| `uv add/remove [--dev] pkg` | Add or remove a (dev) dependency |

nltools-0.6.0.dev0/nltools/__init__.py

@@ -0,0 +1,55 @@
+"""nltools: a Python toolbox for analyzing neuroimaging data.
+
+Focused on multivariate analyses and built on top of nilearn and scikit-learn,
+nltools provides high-level data classes — `BrainData`, `Adjacency`, and
+`DesignMatrix` — that wrap common neuroimaging workflows, alongside a
+functional core of statistics and algorithms (`nltools.algorithms`) that the
+data classes delegate to.
+"""
+
+__all__ = [
+    "Adjacency",
+    "BrainData",
+    "DesignMatrix",
+    "Roc",
+    "SimulateGrid",
+    "Simulator",
+    "__version__",
+    "concatenate",
+    "get_brainspace",
+    "reset_brainspace",
+    "set_brainspace",
+    "with_brainspace",
+]
+
+from .data import (
+    BrainData,
+    Adjacency,
+    DesignMatrix,
+    Simulator,
+    SimulateGrid,
+    Roc,
+)
+from .data.combine import concatenate
+from .templates import (
+    get_brainspace,
+    set_brainspace,
+    reset_brainspace,
+    with_brainspace,
+)
+from .version import __version__
+
+# Bind the submodules users reach through attribute access (e.g.
+# nltools.datasets, nltools.cross_validation) so no prior explicit
+# `import nltools.datasets` is needed. They are not part of the advertised
+# surface; the names in __all__ above are.
+from . import (  # noqa: F401
+    algorithms,
+    cross_validation,
+    data,
+    datasets,
+    io,
+    mask,
+    plotting,
+    utils,
+)

nltools-0.6.0.dev0/nltools/algorithms/__init__.py

@@ -0,0 +1,90 @@
+"""nltools.algorithms — the functional core of nltools.
+
+Every user-facing statistical function and algorithm is importable flat from
+here (`from nltools.algorithms import fdr, zscore, isc`), organized into
+focused submodules underneath:
+
+- **corrections**: multiple-comparison corrections (FDR, Holm-Bonferroni, thresholding)
+- **outliers**: outlier detection, winsorizing, z-scoring
+- **signal**: temporal signal processing (resampling, filtering, basis functions)
+- **similarity**: similarity metrics and Fisher transforms
+- **regression**: standalone OLS regression on numpy arrays
+- **alignment**: the `align`/`procrustes` entry points and the shared-response
+  estimators behind them
+- **inference**: permutation tests, bootstrap resampling, and intersubject
+  statistics (ISC/ISFC/ISPS), parallelized across joblib workers
+- **backends**: device selection and memory budgeting for the ridge paths;
+  `check_gpu_available` is how you ask before requesting `device='gpu'`
+
+Ridge regression lives in `nltools.models.Ridge`, which delegates its numerics
+to the Himalaya library and is reached through `BrainData.fit(model='ridge')`.
+"""
+
+__all__ = [
+    "align",
+    "align_states",
+    "calc_bpm",
+    "check_gpu_available",
+    "circle_shift",
+    "compute_searchlight_neighborhoods",
+    "compute_similarity",
+    "correlation_permutation_test",
+    "distance_correlation",
+    "downsample",
+    "fdr",
+    "find_spikes",
+    "fisher_r_to_z",
+    "fisher_z_to_r",
+    "holm_bonf",
+    "isc",
+    "isc_group",
+    "isfc",
+    "isps",
+    "make_cosine_basis",
+    "matrix_permutation_test",
+    "multi_threshold",
+    "one_sample_permutation_test",
+    "phase_randomize",
+    "procrustes",
+    "procrustes_distance",
+    "regress",
+    "threshold",
+    "transform_pairwise",
+    "trim",
+    "two_sample_permutation_test",
+    "upsample",
+    "winsorize",
+    "zscore",
+]
+
+from .alignment import (
+    align,
+    align_states,
+    procrustes,
+    procrustes_distance,
+)
+from .backends import check_gpu_available
+from .corrections import fdr, holm_bonf, multi_threshold, threshold
+from .neighborhoods import compute_searchlight_neighborhoods
+from .inference import (
+    circle_shift,
+    correlation_permutation_test,
+    distance_correlation,
+    matrix_permutation_test,
+    one_sample_permutation_test,
+    phase_randomize,
+    two_sample_permutation_test,
+)
+
+# Imported from the submodule, not the `inference` package namespace: exporting
+# the `isc` *function* there would shadow the `inference.isc` engine *module*.
+from .inference.intersubject import isc, isc_group, isfc, isps
+from .outliers import find_spikes, trim, winsorize, zscore
+from .regression import regress
+from .signal import calc_bpm, downsample, make_cosine_basis, upsample
+from .similarity import (
+    compute_similarity,
+    fisher_r_to_z,
+    fisher_z_to_r,
+    transform_pairwise,
+)

nltools-0.6.0.dev0/nltools/algorithms/alignment/__init__.py

@@ -0,0 +1,21 @@
+"""Multi-subject functional alignment algorithms.
+
+Algorithms for aligning functional data across subjects:
+
+- **SRM** / **DetSRM**: Shared Response Model (Chen et al. 2015)
+- **align**: whole-brain alignment of a group of subjects, by SRM or by
+  Procrustes-based hyperalignment (Haxby et al. 2011)
+- **procrustes** / **procrustes_distance**: pairwise Procrustes superposition
+  and its permutation test
+- **align_states**: match two sets of state weight maps
+"""
+
+# Internal package: these imports are re-exports for the rest of nltools, not
+# an advertised surface, so there is no `__all__` to mark them as used.
+from .srm import _SRM, _DetSRM  # noqa: F401
+from .procrustes import (  # noqa: F401
+    align,
+    align_states,
+    procrustes,
+    procrustes_distance,
+)