Predictive Models

Linear CPM

LinearCPM

PyTorch CPM model: OLS for regression, logistic regression (IRLS) for binary classification.

Every model variant, hyperparameter configuration and permutation is fitted in one batched linear-algebra pass rather than a Python loop.

Shapes

X : [N_samples, N_features] y : [N_samples, N_runs] (one column per permutation) covariates : [N_samples, N_cov], or None for vanilla CPM edges : [N_features, 2, N_runs] dim 1 = [positive, negative]

Predictions come back as [N_samples, N_models, N_networks, N_runs].

Whether the covariate variance has been taken out of X is decided by the caller (CPMAnalysis(model_input=...)), not here: this class fits whatever connectivity it is given. That is what makes deconfounding a property of the run rather than an extra model, and it is the only form that generalises -- the non-linear backends are not invariant to it, and a multivariate model computes no network strength to residualise at all.

Without covariates only the connectome model is defined -- covariates is an empty design, full collapses to connectome, and increment would be identically zero. Those slots are filled with NaN rather than a number that looks meaningful; see available_models.

available_models property

Model variants this fit actually defines, by name.

__init__(edges, device='cpu', task_type=TaskType.regression)

Args: edges: [N_features, 2, N_runs] boolean mask tensor. device: 'cpu' or 'cuda' task_type: TaskType.regression or TaskType.classification

fit(X, y, covariates=None)

Fit all CPM variants for every hyperparameter configuration and run.

get_network_strengths(X, covariates=None)

Per-subject positive/negative network strengths for the HTML report.

These are the strengths of whatever connectivity the model was given -- under model_input='residualized' that is the deconfounded connectome, so no separate residualised entry is needed or wanted.

Returns a dict of [N_samples, N_runs] tensors.

predict(X, covariates=None, return_proba=False)

Predict with every fitted variant.

Returns [N_samples, N_models, N_networks, N_params, N_runs]. For classification, probabilities when return_proba else 0/1 labels.

predict_class(X, covariates=None)

Class labels for classification; identical to predict() for regression.

predict_proba(X, covariates=None)

Probabilities for classification; identical to predict() for regression.

Nonlinear CPM models

BaseCPM

Bases: ABC

Base class for non-linear CPM models.

Matches the tensor-based pipeline interface of LinearCPM but delegates the connectome and full model fitting to subclass-defined estimators (sklearn, pygam, etc.). The covariates model always uses ordinary least-squares (LinearRegression).

Whether the connectome has been deconfounded is decided by the caller (CPMAnalysis(model_input=...)). It cannot be a model variant here: a tree or GAM is not invariant to shifting a feature by its covariate fit the way OLS is, so a "residualised" model name would mean something different for every backend. Measured on the same edges, fitting full on raw versus residualised connectivity moves predictions by 391% of sd(y) for a decision tree, 65% for a random forest and 19% for a GAM -- against 0.0% for LinearCPM.

Constructor

edges : tensor [N_features, 2, N_runs] device : str ('cpu' or 'cuda') — used only for output tensors task_type : TaskType — stored but not currently used (subclasses are regression-only; classification uses LinearCPM's IRLS)

fit(X, y, covariates)

Fit all CPM model variants for every permutation run.

Parameters:

Name	Type	Description	Default
X	array - like[N_samples, N_features]		required
y	array - like[N_samples, N_runs]		required
covariates	array - like[N_samples, N_cov]		required

fit_model(X, y) abstractmethod

Return a fitted estimator for (X, y). X and y are numpy.

get_network_strengths(X, covariates)

Calculate network strengths for all runs.

Returns:

Type	Description
dict with a "connectome" sub-dict mapping "positive"/"negative" to
tensors [N_samples, N_runs]. These are the strengths of whatever
connectivity the model was given -- under ``model_input='residualized'``
that is already the deconfounded connectome.

predict(X, covariates, return_proba=False)

Predict for all runs.

Returns:

Type	Description
Tensor[N_samples, N_models, N_networks, N_runs]

predict_model(estimator, X)

Predict with a fitted estimator. Override for non-sklearn APIs.