Migrating from v0.5.1¶

nltools 0.6.0 delegates to nilearn, scikit-learn and polars instead of re-implementing them. The data classes keep their jobs, but their names, keyword vocabulary and return types line up with each other and with the libraries underneath: Brain_Data is BrainData, nltools.stats is nltools.algorithms, prediction and regression return typed records instead of loose dictionaries, and one keyword name means one thing everywhere. There are no compatibility aliases — a v0.5.1 name either has a listed replacement or is gone. BrainCollection and collection-level execution are deferred to 0.6.1; in 0.6.0, apply BrainData methods per subject and stack the results with concatenate.

Quick reference¶

Renames and import paths¶

Old class names raise ImportError; moved modules raise ModuleNotFoundError. Two find-and-replace passes cover the class renames:

sd 'Brain_Data' 'BrainData' **/*.py
sd 'Design_Matrix' 'DesignMatrix' **/*.py

The four v0.5.1 mask functions keep their home in nltools.mask, joined by roi_to_brain_from_atlas.

Examples¶

Every example below runs against the same simulated data.

import matplotlib
import numpy as np

matplotlib.use("Agg")  # this page is rendered without a display
import matplotlib.pyplot as plt

from nltools import Adjacency, BrainData, DesignMatrix, Simulator
from nltools.mask import create_sphere

roi = create_sphere([0, -18, 18], radius=8)
brain = Simulator(random_state=0).create_data([0.0, 1.0] * 10, 1.0, reps=1).apply_mask(roi)
conditions = np.asarray(brain.Y).ravel()
print(brain.shape, conditions[:6])

(20, 81) [0. 1. 0. 1. 0. 1.]

Data classes¶

Shape and emptiness are properties rather than methods.

# v0.5.1: brain.shape(), brain.isempty(), brain.empty()
print(brain.shape, brain.is_empty, brain.create_empty().shape)

(20, 81) False (0,)

Adjacency.shape is the logical square shape; the packed vector length moved to vector_shape.

rng = np.random.default_rng(1)
square = rng.normal(size=(10, 10))
square = (square + square.T) / 2
np.fill_diagonal(square, 0)
adjacency = Adjacency(square, matrix_type="similarity")

# v0.5.1: adjacency.shape() was (45,) and adjacency.square_shape() was (10, 10)
print(adjacency.shape, adjacency.vector_shape)

(10, 10) (45,)

Design matrices and GLM¶

DesignMatrix is backed by polars. Column assignment goes through with_columns, and to_numpy() is the escape hatch. Generated columns — intercepts, polynomial trends, cosine bases, spike regressors — carry the reserved .nl_ prefix so they can never collide with a column of yours.

import polars as pl

design = DesignMatrix({"stim": np.tile([0.0, 1.0], 10)}, sampling_freq=0.5)
design = design.add_poly(1)

# v0.5.1: dm['stim_sq'] = dm['stim'] ** 2
design = design.with_columns((pl.col("stim") ** 2).alias("stim_sq"))

# v0.5.1: ['stim', 'stim_sq', 'poly_0', 'poly_1'] and dm.polys
print(design.columns, design.confounds)

['stim', '.nl_poly_0', '.nl_poly_1', 'stim_sq'] ['.nl_poly_0', '.nl_poly_1']

standardize(method='zscore') replaces zscore(). Called without columns= it standardizes the non-confound columns only, where zscore() rescaled the intercept and drift terms along with everything else.

# v0.5.1: design.zscore(columns=['stim'])
standardized = design.standardize(method="zscore", columns=["stim"])
print(dict(zip(standardized.columns, standardized.to_numpy().std(axis=0).round(2))))

{'stim': np.float64(0.97), '.nl_poly_0': np.float64(0.0), '.nl_poly_1': np.float64(0.61), 'stim_sq': np.float64(0.5)}

Convolution names the kernel with kernel=. The output column keeps the _c{i} suffix it had in v0.5.1, and .convolved now lists those output names rather than the source names.

# v0.5.1: DesignMatrix(...).convolve(conv_func='hrf'); .convolved was ['stim']
convolved = DesignMatrix({"stim": np.tile([0.0, 1.0], 10)}, sampling_freq=0.5).convolve()
print(convolved.columns, convolved.convolved)

['stim_c0'] ['stim_c0']

The kernel itself is nilearn's. convolve() calls compute_regressor at oversampling=50, and building a DesignMatrix from an events file calls make_first_level_design_matrix, so both produce exactly what a nilearn FirstLevelModel would. v0.5.1's kernel peaked around 8 s instead of 5 s at TR = 2 (#492), so every convolved regressor — and every beta, t and contrast downstream — changes. Array kernels are unaffected.

Reading an events file is now the constructor's job; onsets_to_dm is gone.

from pathlib import Path

from nltools.datasets import get_resource_path

events = Path(get_resource_path()) / "onsets_example.csv"

# v0.5.1: onsets_to_dm(events, sampling_freq=0.5, run_length=200)
events_design = DesignMatrix(events, run_length=200, TR=2.0)
print(events_design.shape, events_design.columns[:3])

# Raw boxcars, for a design you convolve yourself (PPI, FIR)
print(DesignMatrix(events, run_length=200, TR=2.0, hrf_model=None).columns[:3])

(200, 13) ['BillyRiggins_c0', 'BuddyGarrity_c0', 'CoachTaylor_c0']
['BillyRiggins', 'BuddyGarrity', 'CoachTaylor']

BrainData.regress() is gone. Fit the model, then ask for the contrasts you want: t, p and standard errors are per contrast, not per regressor.

fit_design = DesignMatrix({"stim": conditions}, sampling_freq=0.5).add_poly(0)

# v0.5.1: brain.X = df; out = brain.regress(); out['beta'], out['t'], out['p']
fitted = brain.fit(model="glm", X=fit_design)
print(fitted.model.betas.shape, round(float(fitted.model.r2.data.mean()), 4))

result = fitted.compute_contrasts({"stim": [1, 0]}, inference=True)["stim"]
print(type(result).__name__, result.statistic.shape, result.degrees_of_freedom)

(2, 81) 0.2311
ContrastResult (81,) 18.0

The standalone OLS helper survives the move to nltools.algorithms but loses mode=; the robust and ARMA fits are gone.

from nltools.algorithms import regress

X = np.column_stack([np.ones(20), conditions])

# v0.5.1: regress(X, Y, mode='ols')
betas, se, t, p, df, residuals = regress(X, rng.normal(size=(20, 5)))
print(betas.shape, df[0])

(2, 5) 18

Prediction¶

predict takes the labels, the estimator and the cross-validation scheme as three separate keywords and returns a frozen PredictResult record. There is no cv_dict and no set_cv: pass an integer (that many unshuffled stratified folds), or any sklearn splitter, plus groups= when folds must respect subjects.

# v0.5.1: out = brain.predict(algorithm='svm', cv_dict={'type': 'kfolds', 'n_folds': 3})
predicted = brain.predict(y=conditions, estimator="linear_svc", cv=3)
print(type(predicted).__name__, predicted.weight_map.shape, len(predicted.scores))

PredictResult (81,) 3

spatial_scale replaces predict_multi: the same call runs whole-brain, per-ROI or searchlight decoding. estimator='ridge' and 'ridge_classifier' now fit RidgeCV/RidgeClassifierCV over a 1e-3…1e6 grid inside the per-fold scaler pipeline instead of a single default penalty; pass estimator_kwargs={'alphas': [1.0]} or your own sklearn object to pin one.

Roc spells its threshold rule method=, and its arguments are keyword-only.

from nltools import Roc

# v0.5.1: Roc(scores, labels, threshold_type='optimal_overall')
roc = Roc(
    input_values=np.asarray(predicted.predictions, dtype=float),
    binary_outcome=conditions.astype(bool),
    method="optimal_overall",
)
roc.calculate()
print(round(roc.accuracy, 3), round(roc.auc, 3))

1.0 1.0

Similarity and RSA¶

The compared object is data on both classes, and the metric is metric=. Adjacency.similarity renames perm_type= to method= and flips the diagonal flag to include_diag=.

# v0.5.1: brain.similarity(image=brain[0], method='correlation')
print(np.round(brain.similarity(brain[0], metric="correlation")[:3], 3))

other = rng.normal(size=(10, 10))
other = (other + other.T) / 2
np.fill_diagonal(other, 0)

# v0.5.1: adjacency.similarity(other, perm_type='2d', ignore_diagonal=True)
out = adjacency.similarity(
    Adjacency(other, matrix_type="similarity"),
    method="2d",
    metric="spearman",
    include_diag=False,
    n_permute=100,
    random_state=0,
)
print({k: round(float(v), 3) for k, v in out.items()})

[ 1.    -0.153 -0.085]
{'correlation': 0.059, 'p': 0.644}

cluster_summary moves the central tendency to summary= and the within/between choice to scope=.

labels = ["left"] * 5 + ["right"] * 5

# v0.5.1: adjacency.cluster_summary(clusters=labels, metric='mean', summary='within')
summary = adjacency.cluster_summary(clusters=labels, summary="mean", scope="within")
print({k: round(v, 3) for k, v in summary.items()})

{'left': -0.211, 'right': -0.253}

For a searchlight or ROI RSA, BrainData.distance(spatial_scale='roi', roi_mask=atlas) builds the Adjacency stack that the v0.5.1 workflow assembled by hand, and nltools.mask.roi_to_brain_from_atlas paints the reduced values back onto the atlas.

Alignment¶

Both alignment entry points now store transformation_matrix in one orientation, transformed = original @ T, so back-projection is transformed @ T.T everywhere. v0.5.1's BrainData.align stored the transpose of this, contradicting its own docstring.

target = Simulator(random_state=1).create_data([0.0, 1.0] * 10, 1.0, reps=1).apply_mask(roi)
aligned = brain.align(target, method="procrustes")

# v0.5.1: aligned['transformed'].data @ aligned['transformation_matrix'].data
recovered = aligned["transformed"].data @ aligned["transformation_matrix"].data.T
centered = brain.data - brain.data.mean(axis=0)
print(round(float(np.corrcoef(recovered.ravel(), centered.ravel())[0, 1]), 6))

1.0

Shared response models arrive through the same method: brain.align(target, method='probabilistic_srm') or 'deterministic_srm', and nltools.algorithms.align aligns a list of subjects. The SRM and DetSRM classes are no longer importable — the method builds them for you.

Statistics and inference¶

Everything from nltools.stats lives in nltools.algorithms. The four permutation tests gained a _test suffix, everything after the data arguments is keyword-only, and return_perms= became return_null=.

# v0.5.1: from nltools.stats import one_sample_permutation
#         one_sample_permutation(x, n_permute=200, return_perms=True)
from nltools.algorithms import one_sample_permutation_test

print({k: round(v, 3) for k, v in one_sample_permutation_test(
    rng.normal(size=50), n_permute=200, random_state=0
).items()})

{'mean': -0.135, 'p': 0.269}

ttest takes a popmean and an optional permutation test, and no longer thresholds for you; nltools.algorithms.threshold is the separate step.

from nltools.algorithms import fdr, threshold

# v0.5.1: brain.ttest(threshold_dict={'fdr': .05})
t_test = brain.ttest(popmean=0.0)
print(sorted(t_test), t_test["t"].shape)

q = fdr(t_test["p"].data, q=0.05)
print(round(q, 5), threshold(t_test["t"], t_test["p"], thr=q).shape)

['mean', 'p', 't', 'z'] (81,)
0.00901 (81,)

Adjacency.ttest returns the same four maps as BrainData.ttest — the mean is its own key, and t is the t-statistic rather than the edgewise mean.

Bootstrapping returns a BootstrapResult: an estimate, a standard error, and a central percentile interval at confidence_level. save_weights= became return_samples=.

# v0.5.1: out = brain.bootstrap('mean', n_samples=1000); out['Z'], out['p']
boot = brain.bootstrap("mean", n_samples=1000, confidence_level=0.95, random_state=0)
print(type(boot).__name__, boot.estimate.shape, round(float(boot.ci_lower.mean()), 3))

BootstrapResult (81,) 0.038

Intersubject correlation is a function, not an Adjacency method: nltools.algorithms.isc, isc_group, isfc and isps take arrays and return dictionaries.

Plotting¶

The standalone plotters are gone; each class draws itself, and the axis keyword is ax everywhere, matching matplotlib.

# v0.5.1: design.heatmap(); adjacency.plot(limit=1, axes=ax)
figure = design.plot()
adjacency.plot(limit=1)

# v0.5.1: plot_brain(brain.mean(), how='glass', thr_upper=1)
brain.mean().plot(method="glass", upper=1)
plt.close("all")
print(type(figure).__name__)

Figure

BrainData.plot renames threshold_upper/threshold_lower to upper/lower and moves v0.5.1's view='glass'|'mni'|'full' onto method=; view= is now the slice axis. iplot is rebuilt on niivue and takes view=, threshold=, atlas= and an autoscale/symmetric display pair. component_viewer is the only standalone plotting function left.

IO and datasets¶

The bundled-dataset fetchers cache to a shared location of their own, so data_dir= and resume= are gone and verbose is quiet by default. These two examples download data, so they are not executed when this page is built.

from nltools.datasets import fetch_pain, fetch_neurovault_collection

# v0.5.1: fetch_pain(data_dir='~/nltools_data', resume=True, verbose=1)
pain = fetch_pain()

# v0.5.1: download_collection(collection=504); get_collection_image_metadata(504)
metadata, files = fetch_neurovault_collection(504)

Atlases and bundled resources are looked up by name with load_atlas, list_atlases, fetch_resource and list_resources. HDF5 files written by 0.5.1 or earlier no longer load: export them to NIfTI or CSV under 0.5.1 first, then read them back in 0.6.0.

Removals and their replacements¶

What did not change¶

BrainData, Adjacency and DesignMatrix still mean what they meant in v0.5.1, and the methods that were already well named — threshold, detrend, filter, r_to_z, distance, to_nifti, write — keep their names and their results. Masks are still nibabel images, BrainData.data is still a 2-D NumPy array of images by voxels, Y and X still hold labels and designs, and KFoldStratified and the four v0.5.1 functions in nltools.mask are unchanged. Reading a NIfTI file, a list of files, or a NeuroVault URL into BrainData works as before, and now accepts Path objects too.