API reference

This page documents the public API of ArchePy. Internal modules (those starting with an underscore, e.g. archepy._utils) are not part of the public API and may change without deprecation notice.

Spatial MS-AA

class archepy.Subject(X, sX, T=None, SST=None, sigmaSq=None, S=None, muS=None, sXC=None, XCtX=None, CtXtXC=None, SSt=None, XSt=None, SST_sigmaSq=0.0, NLL=0.0)[source]

Bases: object

Per-subject data and per-iteration sufficient statistics.

Parameters:

  • X (ndarray, shape (T, V)) – Observed data: time points × voxels.

  • sX (ndarray, shape (T, sV)) – “Tilde” data used to construct archetypes (often equal to X).

  • multi_subject_aa; (The remaining fields are populated and updated by)

  • yourself. (you do not need to set them)

  • T (Any)

  • SST (Any)

  • sigmaSq (Any)

  • S (Any)

  • muS (Any)

  • sXC (Any)

  • XCtX (Any)

  • CtXtXC (Any)

  • SSt (Any)

  • XSt (Any)

  • SST_sigmaSq (float)

  • NLL (float)

X: ndarray
sX: ndarray
T: Any = None
SST: Any = None
sigmaSq: Any = None
S: Any = None
muS: Any = None
sXC: Any = None
XCtX: Any = None
CtXtXC: Any = None
SSt: Any = None
XSt: Any = None
SST_sigmaSq: float = 0.0
NLL: float = 0.0
archepy.multi_subject_aa(subj, noc, opts=None)[source]

Fit Multi-Subject Archetypal Analysis (spatial variant).

Parameters:

  • subj (list of Subject) – One Subject per subject. Each provides X (T × V) and sX (T × sV); they may be the same array.

  • noc (int) – Number of archetypes (K).

  • opts (dict, optional) –

    Configuration. Keys (with defaults):

    • conv_crit (1e-6) — relative-NLL convergence threshold

    • maxiter (100) — maximum outer iterations

    • fix_var_iter (5) — keep sigmaSq fixed for this many iters

    • use_gpu (False) — run on GPU via CuPy

    • heteroscedastic (True) — per-voxel noise variance

    • numCstep (10) — inner C-update steps per outer iter

    • numSstep (20) — inner S-update steps per outer iter

    • sort_crit (“corr”) — how to order archetypes at the end

    • init (“FurthestSum”) — initialization scheme

    • initSstep (250) — extra S-update steps during init

    • rngSEED (None) — RNG seed

    • noise_threshold (None) — lower bound for sigmaSq

Returns:

  • results (list of dict) – Per-subject outputs: S, sXC, sigmaSq, NLL, SSE, SST, SST_sigmaSq.

  • C (ndarray, shape (sV, K)) – Shared archetype generator (columns sum to 1).

  • cost_fun (ndarray, shape (n_iter,)) – Negative log-likelihood at each outer iteration.

  • varexpl (float) – Variance explained, (SST - sum(SSE)) / SST.

  • elapsed (float) – Wall-clock time in seconds.

Return type:

tuple[list[dict[str, Any]], ndarray, ndarray, float, float]

Temporal MS-AA

class archepy.SubjectT(X, sX)[source]

Bases: object

Temporal MS-AA subject container.

Parameters:

  • X (ndarray, shape (V, T)) – Voxels × time points.

  • sX (ndarray, shape (V, sT)) – Voxels × “tilde” time points.

X: ndarray
sX: ndarray
archepy.multi_subject_aa_T(subj, noc, opts=None)[source]

Fit Multi-Subject Archetypal Analysis (temporal variant).

See archepy.multi_subject_aa() for the spatial variant and a description of the opts dictionary; the same options apply here.

Parameters:
Return type:

tuple[list[dict[str, Any]], ndarray, ndarray, float, float]

Initialization

archepy.furthest_sum(K, noc, i, exclude=None, *, treat_as_kernel=None, one_based=False)[source]

Greedy FurthestSum selection of noc candidate archetype indices.

Parameters:

  • K (ndarray) – Either a data matrix of shape (D, N) (observations as columns) or a symmetric kernel matrix of shape (N, N).

  • noc (int) – Number of indices to select.

  • i (int or iterable of int) – Initial seed index/indices.

  • exclude (iterable of int, optional) – Indices that must not be selected.

  • treat_as_kernel (bool, optional) – If None (default), auto-detect: a square symmetric K is treated as a kernel; otherwise as a data matrix. Pass False explicitly for large square data matrices to skip the symmetry check.

  • one_based (bool, default False) – If True, treat input/output indices as 1-based (MATLAB style).

Returns:

list[int] – Selected indices.

Return type:

list[int]

archepy.init.furthest_sum_gpu(*args, **kwargs)[source]

Lazy wrapper around the GPU FurthestSum.

Imported lazily so that import archepy does not fail when CuPy is not installed. Install GPU support with pip install archepy[gpu].

fMRI helpers

archepy.fmri.estimate_background_noise(file, file_filt)[source]

Estimate a noise variance threshold from background voxels of a NIfTI.

Parameters:

  • file (str) – Path to raw fMRI NIfTI (used to compute the background mask).

  • file_filt (str or None) – Path to filtered/preprocessed NIfTI (used to compute noise variance). If None, the raw file is used for both steps.

Returns:

float – Mean of per-voxel temporal variances over background voxels.

Return type:

float

Notes

Requires nibabel. Install with pip install archepy[fmri].

archepy.fmri.generate_synthetic_noise(sx, sy, noise_var=None, stepsize=8, show_plot=False)[source]

Generate radial variance maps for simulating spatially-varying noise.

Parameters:

  • sx (int) – Map size in x (rows) and y (cols).

  • sy (int) – Map size in x (rows) and y (cols).

  • noise_var (sequence of float, optional) – Maximum variances for each noise map. Defaults to [1, 4, 16].

  • stepsize (int, default 8) – Radial step size for the nested circular contours (in pixels).

  • show_plot (bool, default False) – If True, render diagnostic plots (requires matplotlib).

Returns:

ndarray, shape (sx, sy, K) – Stack of variance maps, one per entry in noise_var.

Return type:

ndarray