nltools 0.6.0.dev0__py3-none-any.whl

nltools/data/simulator/haxby.py

@@ -0,0 +1,124 @@
+"""A synthetic Haxby-like dataset, built the way `Simulator` builds data.
+
+Despite living beside the fetchers in `nltools.datasets`, `load_haxby_example`
+downloads nothing: it injects condition-specific signal into a tiny seeded
+volume. That makes it a simulator, so its implementation sits here.
+"""
+
+from nltools.data.braindata import BrainData
+from nltools.data.designmatrix import DesignMatrix
+from nltools.io.events import events_to_dm
+
+
+_HAXBY_CONDITIONS = (
+    "face",
+    "house",
+    "cat",
+    "bottle",
+    "scissors",
+    "shoe",
+    "chair",
+    "scrambledpix",
+)
+
+
+def load_haxby_example(n_runs=1, random_state=42):
+    """Load a small synthetic Haxby-like dataset, entirely in-memory.
+
+    Returns paired lists of `BrainData` and `DesignMatrix`, one entry per
+    run, generated from a tiny synthetic volume (10 x 10 x 5 = 500 voxels)
+    with condition-specific signal injected into disjoint voxel clusters.
+    No network I/O, no disk I/O, no nilearn fetcher dependency. Runs in
+    well under a second.
+
+    Intended for tutorials, documentation examples, and tests where
+    downloading a real fMRI dataset is impractical. The
+    eight conditions match the real Haxby 2001 object-recognition experiment
+    (face, house, cat, bottle, scissors, shoe, chair, scrambledpix), arranged
+    in a randomized 9-TR block design with TR=2.5s.
+
+    Args:
+        n_runs (int): Number of runs to generate. Default 1.
+        random_state (int | None): Seed for reproducible output. Default 42.
+
+    Returns:
+        tuple: `(list[BrainData], list[DesignMatrix])`, each of length `n_runs`.
+            The DesignMatrix columns are the eight condition names suffixed
+            with `_c0` (HRF-convolved boxcars).
+
+    Examples:
+        ```python
+        from nltools.datasets import load_haxby_example
+
+        brain_data, design_matrices = load_haxby_example()
+        data, dm = brain_data[0], design_matrices[0]
+        data.shape  # → (72, 500)
+        "face_c0" in dm.columns  # → True
+        ```
+    """
+    import numpy as np
+    import pandas as pd
+    import nibabel as nib
+
+    rng = np.random.default_rng(random_state)
+
+    TR = 2.5
+    block_tr = 9  # 22.5s blocks, same order of magnitude as real Haxby
+    n_conditions = len(_HAXBY_CONDITIONS)
+    n_timepoints = block_tr * n_conditions  # 72 TRs per run
+    spatial_shape = (10, 10, 5)
+    n_voxels = int(np.prod(spatial_shape))
+    affine = np.diag([3.0, 3.0, 3.0, 1.0]).astype(np.float32)
+    mask_img = nib.Nifti1Image(np.ones(spatial_shape, dtype=np.float32), affine)
+
+    brain_data_list = []
+    design_matrix_list = []
+
+    for _ in range(n_runs):
+        order = list(rng.permutation(_HAXBY_CONDITIONS))
+        events_df = pd.DataFrame(
+            [
+                {
+                    "onset": i * block_tr * TR,
+                    "duration": block_tr * TR,
+                    "trial_type": cond,
+                }
+                for i, cond in enumerate(order)
+            ]
+        )
+        dm_data = events_to_dm(
+            events_df,
+            run_length=n_timepoints,
+            sampling_freq=1.0 / TR,
+        )
+        dm = DesignMatrix(dm_data, sampling_freq=1.0 / TR).convolve()
+
+        # Positive BOLD-like baseline intensity + voxelwise Gaussian noise,
+        # plus signal injected into a disjoint voxel cluster per condition
+        # so contrasts produce real spatial patterns. The positive baseline
+        # is required so percent-signal-change scaling inside GLM fits
+        # (which divides by the voxel mean) stays numerically sane.
+        baseline = 100.0
+        noise_sd = 1.0
+        signal_strength = 5.0  # BOLD units → clearly visible pattern in plots
+        data_flat = (
+            baseline + noise_sd * rng.standard_normal((n_voxels, n_timepoints))
+        ).astype(np.float32)
+        voxels_per_cond = n_voxels // n_conditions
+        voxel_order = rng.permutation(n_voxels)
+        for c_idx, cond in enumerate(_HAXBY_CONDITIONS):
+            cond_col = f"{cond}_c0"
+            if cond_col not in dm.columns:
+                continue
+            regressor = np.asarray(dm[cond_col], dtype=np.float32)
+            cluster = voxel_order[
+                c_idx * voxels_per_cond : (c_idx + 1) * voxels_per_cond
+            ]
+            data_flat[cluster, :] += signal_strength * regressor
+
+        data_4d = data_flat.reshape((*spatial_shape, n_timepoints))
+        img = nib.Nifti1Image(data_4d, affine)
+        brain_data_list.append(BrainData(img, mask=mask_img, verbose=0))
+        design_matrix_list.append(dm)
+
+    return brain_data_list, design_matrix_list

nltools/data/validation.py

@@ -0,0 +1,83 @@
+"""Frame validation shared by the data classes.
+
+`BrainData.X`/`.Y` and `Adjacency.Y` accept the same range of tabular inputs
+and store the same polars frame, so the ingress check lives here rather than
+inside either class.
+"""
+
+from pathlib import Path
+
+import numpy as np
+import polars as pl
+
+
+def _validate_frame(frame, data_shape=None, frame_type="DataFrame"):
+    """Validate and process an X or Y frame for a data class.
+
+    Accepts pandas DataFrames for user convenience but always returns a
+    polars DataFrame. Internal data-class state is polars-only.
+
+    Args:
+        frame (pl.DataFrame | pd.DataFrame | dict | np.ndarray | str | Path | None):
+            Input to validate: ``None``, a path to a CSV, a polars or pandas
+            DataFrame, a dict of columns, or a 1D/2D numpy array.
+        data_shape (tuple | None): Data shape to validate the row count against.
+        frame_type (str): Name of the frame for error messages (e.g. ``"X"``,
+            ``"Y"``).
+
+    Returns:
+        pl.DataFrame: Validated frame as polars. Empty ``pl.DataFrame()`` when
+            ``frame`` is ``None``.
+
+    Raises:
+        TypeError: If frame is not a supported type.
+        ValueError: If frame rows do not match ``data_shape[0]`` or CSV read fails.
+    """
+    if frame is None:
+        return pl.DataFrame()
+
+    # Unwrap DesignMatrix to its underlying polars DataFrame — DM-specific
+    # metadata (sampling_freq, convolved, confounds) isn't preserved on
+    # BrainData, but users should be able to hand a DM in directly.
+    from nltools.data.designmatrix import DesignMatrix
+
+    if isinstance(frame, DesignMatrix):
+        frame = frame.data
+
+    if isinstance(frame, pl.DataFrame):
+        out = frame
+    elif isinstance(frame, (str, Path)):
+        try:
+            out = pl.read_csv(frame, has_header=False)
+        except Exception as e:
+            raise ValueError(
+                f"Could not read {frame_type} from file '{frame}'. "
+                f"Make sure the file exists and is a valid CSV. Error: {e}"
+            )
+    elif isinstance(frame, dict):
+        out = pl.DataFrame(frame)
+    elif isinstance(frame, np.ndarray):
+        arr = frame if frame.ndim == 2 else frame.reshape(-1, 1)
+        out = pl.DataFrame(arr)
+    else:
+        try:
+            import pandas as pd
+        except ImportError:
+            pd = None
+        if pd is not None and isinstance(frame, pd.DataFrame):
+            out = pl.DataFrame({str(c): frame[c].to_numpy() for c in frame.columns})
+        else:
+            raise TypeError(
+                f"{frame_type} must be a filepath (str/Path), numpy array, dict, or "
+                f"polars/pandas DataFrame. Received {type(frame).__name__}"
+            )
+
+    if not out.is_empty() and data_shape is not None:
+        if out.shape[0] != data_shape[0]:
+            raise ValueError(
+                f"{frame_type} rows ({out.shape[0]}) do not match "
+                f"data rows ({data_shape[0]}). Each row in {frame_type} should "
+                f"correspond to an image in the data."
+            )
+
+    return out

nltools/datasets.py

@@ -0,0 +1,218 @@
+"""Dataset, resource, and atlas lookups.
+
+Functions to fetch example datasets, bundled resources, and parcellations. The
+curated example datasets (`fetch_pain`, `fetch_emotion_ratings`) are hosted on
+the ``nltools/niftis`` Hugging Face dataset and resolve through the same
+`fetch_resource` machinery as the MNI templates and atlases. Arbitrary
+Neurovault collections are available via `fetch_neurovault_collection`, and
+`list_atlases` / `load_atlas` / `label_coords` cover the parcellations.
+"""
+
+__all__ = [
+    "download_nifti",
+    "fetch_emotion_ratings",
+    "fetch_neurovault_collection",
+    "fetch_pain",
+    "fetch_resource",
+    "get_resource_path",
+    "label_coords",
+    "list_atlases",
+    "list_resources",
+    "load_atlas",
+    "load_haxby_example",
+]
+
+import io
+from contextlib import nullcontext, redirect_stdout
+from os.path import dirname, join, sep as pathsep
+from pathlib import Path
+
+from nltools.data import BrainData
+from nltools.data.atlases import label_coords, list_atlases, load_atlas
+from nltools.data.simulator.haxby import load_haxby_example
+from nltools.templates import fetch_resource, list_resources
+
+# Core dependencies
+from nilearn.datasets import fetch_neurovault_ids
+
+# Optional dependencies
+try:
+    import requests
+except ImportError:
+    requests = None
+
+
+def get_resource_path():
+    """Get the path to the nltools resource directory.
+
+    Returns:
+        str: Absolute path to `nltools/resources/`, with a trailing separator.
+    """
+    return join(dirname(__file__), "resources") + pathsep
+
+
+# Curated datasets hosted on the ``nltools/niftis`` HF dataset. Each directory
+# holds a ``metadata.csv`` whose ``filename`` column is the image manifest.
+_PAIN_DIR = "datasets/pain"
+_EMOTION_DIR = "datasets/emotion_ratings"
+
+
+def download_nifti(url, data_dir=None):
+    """Download an image from a URL to a nifti file.
+
+    Args:
+        url (str): URL of the image to download
+        data_dir (str, optional): Directory to save the file. If None, uses current directory.
+
+    Returns:
+        str: Path to the downloaded file
+
+    Raises:
+        ImportError: If requests is not available
+        ValueError: If URL is invalid
+    """
+    if requests is None:
+        raise ImportError("requests package is required for downloading files")
+
+    if not url:
+        raise ValueError("URL cannot be empty")
+    if isinstance(url, Path):
+        url = str(url)
+
+    local_filename = url.split("/")[-1]
+    if data_dir is not None:
+        data_dir = Path(data_dir)
+        data_dir.mkdir(parents=True, exist_ok=True)
+        local_filename = data_dir / local_filename
+
+    try:
+        with requests.get(url, stream=True, timeout=(10, 60)) as r:
+            r.raise_for_status()
+
+            with open(local_filename, "wb") as f:
+                for chunk in r.iter_content(chunk_size=1024):
+                    if chunk:  # filter out keep-alive new chunks
+                        f.write(chunk)
+    except requests.RequestException as e:
+        raise ValueError(f"Failed to download {url}: {e}")
+
+    return str(local_filename)
+
+
+def fetch_neurovault_collection(collection_id, data_dir=None, verbose=1):
+    """Download images and metadata from a Neurovault collection.
+
+    This function uses the modern nilearn API to download collections from Neurovault.
+
+    Args:
+        collection_id (int): Neurovault collection ID
+        data_dir (str, optional): Directory to store downloaded data.
+            If None, uses nilearn's default data directory.
+        verbose (int, optional): Verbosity level; `0` is silent, including the
+            data-directory line nilearn reports whatever it is asked for.
+            Default: 1
+
+    Returns:
+        tuple[pl.DataFrame, list[str]]: `(metadata, files)` — the image metadata
+            table and the downloaded image paths.
+
+    Raises:
+        ValueError: If collection_id is invalid
+        RuntimeError: If download fails
+    """
+    import polars as pl
+
+    if not isinstance(collection_id, int) or collection_id <= 0:
+        raise ValueError("collection_id must be a positive integer")
+
+    try:
+        # nilearn resolves its data directory with `get_dataset_dir("neurovault",
+        # data_dir)` without forwarding `verbose`, so it announces that
+        # directory's absolute path however quietly it was asked to work.
+        # `verbose=0` has to mean silence: anything that captures a session and
+        # publishes it — a notebook, the docs build — would otherwise carry the
+        # path of the machine that ran it.
+        quiet = redirect_stdout(io.StringIO()) if verbose == 0 else nullcontext()
+        with quiet:
+            nv_data = fetch_neurovault_ids(
+                collection_ids=[collection_id], data_dir=data_dir, verbose=verbose
+            )
+
+        files = nv_data["images"]
+        metadata = pl.DataFrame(nv_data["images_meta"])
+
+        return metadata, files
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to download collection {collection_id}: {e}")
+
+
+def fetch_pain(verbose=0):
+    """Download and load the pain dataset from the nltools HF dataset.
+
+    Loads the Chang et al. (2015) pain-perception study: 28 subjects x 3
+    stimulus-intensity conditions = 84 whole-brain contrast images, with a
+    curated metadata table (`SubjectID`, `PainLevel`, `PainIntensity`, `Age`,
+    `Sex`, provenance `neurovault_id` / `name`).
+
+    Data is hosted on the ``nltools/niftis`` Hugging Face dataset and cached
+    locally on first use, so this works with no extra setup.
+
+    Args:
+        verbose (int, optional): Verbosity passed to `BrainData` while loading.
+            Default: 0
+
+    Returns:
+        BrainData: `BrainData` with the 84 images; `X` holds the metadata table.
+
+    References:
+        Chang, L. J., Gianaros, P. J., Manuck, S. B., Krishnan, A., & Wager, T. D. (2015).
+        A sensitive and specific neural signature for picture-induced negative affect.
+        PLoS biology, 13(6), e1002180.
+    """
+    import polars as pl
+
+    try:
+        metadata = pl.read_csv(fetch_resource(f"{_PAIN_DIR}/metadata.csv"))
+        files = [fetch_resource(f"{_PAIN_DIR}/{fn}") for fn in metadata["filename"]]
+        return BrainData(data=files, X=metadata, verbose=verbose)
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch pain dataset: {e}")
+
+
+def fetch_emotion_ratings(verbose=0):
+    """Download and load the emotion-rating dataset from the nltools HF dataset.
+
+    Loads the Chang et al. (2015) IAPS emotion-rating study: 679 whole-brain
+    contrast images across 150 subjects, each rating images 1-5, with a
+    built-in train/test holdout split. `X` carries the full portable Neurovault
+    metadata (key columns: `SubjectID`, `Rating`, `Holdout`, `AGE`, `SEX`).
+
+    Data is hosted on the ``nltools/niftis`` Hugging Face dataset and cached
+    locally on first use, so this works with no extra setup.
+
+    Args:
+        verbose (int, optional): Verbosity passed to `BrainData` while loading.
+            Default: 0
+
+    Returns:
+        BrainData: `BrainData` with the 679 images; `X` holds the metadata table.
+
+    References:
+        Chang, L. J., Gianaros, P. J., Manuck, S. B., Krishnan, A., & Wager, T. D. (2015).
+        A sensitive and specific neural signature for picture-induced negative affect.
+        PLoS biology, 13(6), e1002180.
+    """
+    import polars as pl
+
+    try:
+        metadata = pl.read_csv(fetch_resource(f"{_EMOTION_DIR}/metadata.csv"))
+        files = [
+            fetch_resource(f"{_EMOTION_DIR}/{fn}")
+            for fn in metadata["filename"].to_list()
+        ]
+        return BrainData(data=files, X=metadata, verbose=verbose)
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch emotion ratings dataset: {e}")

nltools/io/__init__.py

@@ -0,0 +1,10 @@
+"""nltools I/O utilities.
+
+`events_to_dm` turns a BIDS events table into boxcar regressors. HDF5
+serialization for the data classes lives in `nltools.io.h5`; users reach it
+through `BrainData.write`/`Adjacency.write` and the constructors.
+"""
+
+from .events import events_to_dm
+
+__all__ = ["events_to_dm"]

nltools/io/events.py

@@ -0,0 +1,67 @@
+"""Convert BIDS events tables into design-matrix regressors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import polars as pl
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def events_to_dm(
+    events: pl.DataFrame | pd.DataFrame,
+    *,
+    run_length: int,
+    sampling_freq: float,
+) -> pl.DataFrame:
+    """Convert a BIDS events table to boxcar regressors aligned to TRs.
+
+    Uses `nilearn.glm.first_level.make_first_level_design_matrix` with
+    `hrf_model=None` to sample events onto the TR grid without HRF
+    convolution — the caller is expected to call `DesignMatrix.convolve()`
+    explicitly when convolution is desired. Drops nilearn's auto-added
+    `constant` column; users add the intercept via `add_poly(0)`.
+
+    Args:
+        events (pl.DataFrame | pd.DataFrame): Events table with BIDS columns
+            `onset`, `duration`, `trial_type` (required); `modulation` is
+            passed through if present.
+        run_length (int): Number of TRs the run contains.
+        sampling_freq (float): Sampling frequency in Hz (= 1/TR).
+
+    Returns:
+        pl.DataFrame: One column per unique `trial_type`, values in
+            {0, modulation} indicating where each condition is active.
+
+    Examples:
+        ```python
+        import polars as pl
+        from nltools.io import events_to_dm
+
+        events = pl.DataFrame(
+            {"onset": [0.0, 10.0], "duration": [5.0, 5.0], "trial_type": ["a", "b"]}
+        )
+        regressors = events_to_dm(events, run_length=20, sampling_freq=0.5)
+        ```
+    """
+    import pandas as pd
+    from nilearn.glm.first_level import make_first_level_design_matrix
+
+    if isinstance(events, pl.DataFrame):
+        events = pd.DataFrame(events.to_dict(as_series=False))
+
+    tr = 1.0 / sampling_freq
+    frame_times = np.arange(run_length) * tr
+    dm = make_first_level_design_matrix(
+        frame_times,
+        events=events,
+        hrf_model=None,
+        drift_model=None,
+    )
+    if "constant" in dm.columns:
+        dm = dm.drop(columns=["constant"])
+    # Avoid pyarrow dep on the pandas → polars hop.
+    return pl.DataFrame({str(c): dm[c].to_numpy() for c in dm.columns})