dartbrains-tools 0.1.0__tar.gz

dartbrains_tools-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+.python-version
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+*.swp

dartbrains_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luke Chang
+
+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.

dartbrains_tools-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: dartbrains-tools
+Version: 0.1.0
+Summary: Helper library and interactive anywidgets for the DartBrains fMRI course
+Project-URL: Homepage, https://dartbrains.org
+Project-URL: Source, https://github.com/ljchang/dartbrains-tools
+Project-URL: Issues, https://github.com/ljchang/dartbrains-tools/issues
+Author-email: Luke Chang <luke.j.chang@dartmouth.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anywidget,education,fmri,marimo,neuroimaging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: anywidget>=0.9.21
+Requires-Dist: huggingface-hub>=1.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas
+Requires-Dist: plotly>=6.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: traitlets
+Provides-Extra: notebook
+Requires-Dist: marimo>=0.21; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# dartbrains-tools
+
+Helper library and interactive anywidgets for the [DartBrains](https://dartbrains.org)
+fMRI course. Extracted from the [book repo](https://github.com/ljchang/dartbrains)
+so the widgets and helpers can be installed standalone — including in
+[molab](https://molab.marimo.io) and pyodide/WASM marimo notebooks.
+
+## Install
+
+```bash
+pip install dartbrains-tools
+
+# Optional: include marimo for notebook_utils.youtube()
+pip install "dartbrains-tools[notebook]"
+```
+
+## Modules
+
+- `dartbrains_tools.data` — load the Pinel Localizer dataset from the Hugging Face Hub.
+- `dartbrains_tools.mr_simulations` — Bloch equation solvers, signal generators,
+  HRF, and Plotly visualization helpers.
+- `dartbrains_tools.mr_widgets` — 10 anywidgets for interactive MR physics teaching
+  (`PrecessionWidget`, `SpinEnsembleWidget`, `KSpaceWidget`, `ConvolutionWidget`,
+  `EncodingWidget`, `CompassWidget`, `NetMagnetizationWidget`, `TransformCubeWidget`,
+  `CostFunctionWidget`, `SmoothingWidget`).
+- `dartbrains_tools.notebook_utils` — small marimo helpers (`youtube`).
+
+## Quick start
+
+```python
+from dartbrains_tools.mr_widgets import PrecessionWidget
+
+w = PrecessionWidget(b0=3.0, flip_angle=90.0)
+w  # Interactive 3D Three.js animation in any anywidget host.
+```
+
+```python
+from dartbrains_tools.data import get_subjects, get_file, load_events
+
+subjects = get_subjects()
+bold = get_file("S01", "bold")
+events = load_events("S01")
+```
+
+## Development
+
+```bash
+git clone https://github.com/ljchang/dartbrains-tools
+cd dartbrains-tools
+uv sync
+uv run pytest
+uv build
+```
+
+## License
+
+MIT. The parent course materials at [dartbrains](https://github.com/ljchang/dartbrains)
+remain CC-BY-SA-4.0; this companion library is permissive so it can be reused
+in any downstream project.

dartbrains_tools-0.1.0/README.md

@@ -0,0 +1,59 @@
+# dartbrains-tools
+
+Helper library and interactive anywidgets for the [DartBrains](https://dartbrains.org)
+fMRI course. Extracted from the [book repo](https://github.com/ljchang/dartbrains)
+so the widgets and helpers can be installed standalone — including in
+[molab](https://molab.marimo.io) and pyodide/WASM marimo notebooks.
+
+## Install
+
+```bash
+pip install dartbrains-tools
+
+# Optional: include marimo for notebook_utils.youtube()
+pip install "dartbrains-tools[notebook]"
+```
+
+## Modules
+
+- `dartbrains_tools.data` — load the Pinel Localizer dataset from the Hugging Face Hub.
+- `dartbrains_tools.mr_simulations` — Bloch equation solvers, signal generators,
+  HRF, and Plotly visualization helpers.
+- `dartbrains_tools.mr_widgets` — 10 anywidgets for interactive MR physics teaching
+  (`PrecessionWidget`, `SpinEnsembleWidget`, `KSpaceWidget`, `ConvolutionWidget`,
+  `EncodingWidget`, `CompassWidget`, `NetMagnetizationWidget`, `TransformCubeWidget`,
+  `CostFunctionWidget`, `SmoothingWidget`).
+- `dartbrains_tools.notebook_utils` — small marimo helpers (`youtube`).
+
+## Quick start
+
+```python
+from dartbrains_tools.mr_widgets import PrecessionWidget
+
+w = PrecessionWidget(b0=3.0, flip_angle=90.0)
+w  # Interactive 3D Three.js animation in any anywidget host.
+```
+
+```python
+from dartbrains_tools.data import get_subjects, get_file, load_events
+
+subjects = get_subjects()
+bold = get_file("S01", "bold")
+events = load_events("S01")
+```
+
+## Development
+
+```bash
+git clone https://github.com/ljchang/dartbrains-tools
+cd dartbrains-tools
+uv sync
+uv run pytest
+uv build
+```
+
+## License
+
+MIT. The parent course materials at [dartbrains](https://github.com/ljchang/dartbrains)
+remain CC-BY-SA-4.0; this companion library is permissive so it can be reused
+in any downstream project.

dartbrains_tools-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dartbrains-tools"
+version = "0.1.0"
+description = "Helper library and interactive anywidgets for the DartBrains fMRI course"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Luke Chang", email = "luke.j.chang@dartmouth.edu" },
+]
+keywords = ["neuroimaging", "fmri", "anywidget", "education", "marimo"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "anywidget>=0.9.21",
+    "traitlets",
+    "numpy>=2.0",
+    "scipy>=1.13",
+    "plotly>=6.0",
+    "pandas",
+    "huggingface-hub>=1.0",
+]
+
+[project.optional-dependencies]
+notebook = ["marimo>=0.21"]
+
+[project.urls]
+Homepage = "https://dartbrains.org"
+Source = "https://github.com/ljchang/dartbrains-tools"
+Issues = "https://github.com/ljchang/dartbrains-tools/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dartbrains_tools"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/dartbrains_tools",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+ignore = ["E501"]

dartbrains_tools-0.1.0/src/dartbrains_tools/__init__.py

@@ -0,0 +1,20 @@
+"""DartBrains helper library: data loaders, MR physics simulations, anywidgets."""
+
+__version__ = "0.1.0"
+
+from . import data, mr_simulations, mr_widgets
+
+__all__ = [
+    "__version__",
+    "data",
+    "mr_simulations",
+    "mr_widgets",
+    "notebook_utils",  # lazy: requires the [notebook] extra (marimo)
+]
+
+
+def __getattr__(name):
+    if name == "notebook_utils":
+        from . import notebook_utils as _nu
+        return _nu
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

dartbrains_tools-0.1.0/src/dartbrains_tools/data.py

@@ -0,0 +1,107 @@
+"""
+DartBrains Localizer Dataset Access
+====================================
+
+Helper functions to download and access the Pinel Localizer dataset
+from HuggingFace Hub (dartbrains/localizer).
+
+Files are downloaded on first access and cached locally by huggingface_hub.
+"""
+
+import pandas as pd
+from huggingface_hub import hf_hub_download
+
+REPO_ID = "dartbrains/localizer"
+
+SUBJECTS = [f"S{i:02d}" for i in range(1, 21)]
+
+TR = 2.4  # seconds, from task-localizer_bold.json
+
+CONDITIONS = [
+    "audio_computation",
+    "audio_left_hand",
+    "audio_right_hand",
+    "audio_sentence",
+    "horizontal_checkerboard",
+    "vertical_checkerboard",
+    "video_computation",
+    "video_left_hand",
+    "video_right_hand",
+    "video_sentence",
+]
+
+
+def _download(filename: str) -> str:
+    """Download a file from the dartbrains/localizer dataset. Returns local cached path."""
+    return hf_hub_download(repo_id=REPO_ID, filename=filename, repo_type="dataset")
+
+
+def get_subjects() -> list[str]:
+    """Return list of subject IDs (S01-S20)."""
+    return list(SUBJECTS)
+
+
+def get_tr() -> float:
+    """Return the repetition time in seconds."""
+    return TR
+
+
+def get_file(subject: str, scope: str, suffix: str, extension: str = ".nii.gz") -> str:
+    """Download and return the local path to a dataset file.
+
+    Args:
+        subject: Subject ID, e.g. "S01"
+        scope: One of "raw", "derivatives", or "betas"
+        suffix: BIDS suffix -- "bold", "T1w", "events", "confounds", "mask",
+                or a condition name for betas (e.g. "audio_computation"),
+                or "all" for the stacked betas file
+        extension: File extension including dot, e.g. ".nii.gz", ".tsv"
+
+    Returns:
+        Local filesystem path to the cached file.
+    """
+    s = subject
+    sub = f"sub-{s}"
+
+    if scope == "betas":
+        if suffix == "all":
+            filename = f"derivatives/betas/{s}_betas{extension}"
+        else:
+            filename = f"derivatives/betas/{s}_beta_{suffix}{extension}"
+
+    elif scope == "raw":
+        if suffix == "events":
+            filename = f"{sub}/func/{sub}_task-localizer_events.tsv"
+        elif suffix == "bold":
+            # No raw bold on HF -- use preprocessed
+            filename = f"derivatives/fmriprep/{sub}/func/{sub}_task-localizer_space-MNI152NLin2009cAsym_desc-preproc_bold{extension}"
+        else:
+            raise ValueError(f"Unknown raw suffix: {suffix}")
+
+    elif scope == "derivatives":
+        if suffix == "bold":
+            filename = f"derivatives/fmriprep/{sub}/func/{sub}_task-localizer_space-MNI152NLin2009cAsym_desc-preproc_bold{extension}"
+        elif suffix == "T1w":
+            filename = f"derivatives/fmriprep/{sub}/anat/{sub}_space-MNI152NLin2009cAsym_desc-preproc_T1w{extension}"
+        elif suffix == "confounds":
+            filename = f"derivatives/fmriprep/{sub}/func/{sub}_task-localizer_desc-confounds_regressors.tsv"
+        elif suffix == "mask":
+            filename = f"derivatives/fmriprep/{sub}/func/{sub}_task-localizer_space-MNI152NLin2009cAsym_desc-brain_mask{extension}"
+        else:
+            raise ValueError(f"Unknown derivatives suffix: {suffix}")
+    else:
+        raise ValueError(f"Unknown scope: {scope}. Use 'raw', 'derivatives', or 'betas'.")
+
+    return _download(filename)
+
+
+def load_events(subject: str) -> pd.DataFrame:
+    """Download and load the events TSV for a subject as a DataFrame."""
+    path = get_file(subject, scope="raw", suffix="events", extension=".tsv")
+    return pd.read_csv(path, sep="\t")
+
+
+def load_confounds(subject: str) -> pd.DataFrame:
+    """Download and load the fmriprep confounds TSV for a subject."""
+    path = get_file(subject, scope="derivatives", suffix="confounds")
+    return pd.read_csv(path, sep="\t")