core¶

Module-level helpers for BrainCollection.

Pure functions: metadata coercion, mask resolution, run/step ID generation, step-directory naming. No class state lives here.

Methods:

Methods¶

coerce_metadata¶

coerce_metadata(metadata: pl.DataFrame | pd.DataFrame | dict | None, n_subjects: int) -> pl.DataFrame

Coerce a metadata input into a polars DataFrame of length n_subjects.

Accepts polars/pandas DataFrames or a dict-of-columns. None yields a DataFrame with a default subject column (sub-0001, ...).

Polars metadata cannot hold DataFrames or arrays — those belong in the parallel slots (designs, _confounds, _sample_masks).

make_run_id¶

make_run_id(now: datetime | None = None) -> str

Build a fresh run_id of the form {timestamp}_{uuid8}.

Timestamp is UTC YYYYMMDDTHHMMSS; the uuid tail is 8 hex chars from secrets.token_hex(4). Lex-sortable, collision-free across processes.

make_step_dirname¶

make_step_dirname(op: str, kwargs: dict[str, Any] | None = None, *, now: datetime | None = None) -> str

Name a step subdir: {timestamp}_{seq}_{uuid8}_{op}_{key_kwargs}/.

Each call yields a unique name (UUID tail) — same op + same params twice produces two subdirs, never overwriting. The zero-padded seq is a process-monotonic counter placed after the second-resolution timestamp, so lexicographic order tracks creation order even for calls that share a second (the timestamp stays the primary, cross-process ordering key).

resolve_cache_dir¶

resolve_cache_dir(cache_dir: Path | str | None) -> Path | None

Resolve cache_dir per the spec’s precedence rules.

Order: explicit arg → NLTOOLS_CACHE_DIR env var → ./.nltools_cache. Returns None when the caller passes None (signaling tempdir mode). The returned path is not yet decorated with a run_id subdir; that happens at construction time on the instance.

resolve_mask¶

resolve_mask(mask: nib.Nifti1Image | Path | str) -> nib.Nifti1Image

Resolve a mask spec into a Nifti1Image.

Accepts a Nifti1Image, a path, or a known nltools template string (e.g. "3mm-MNI152-2009c"). String templates dispatch to the same resolver used by BrainData.