Skip to content

CPM Analysis

The CPMAnalysis class is the main entry point for both regression and classification analyses.

CPMAnalysis

This class handles the process of performing CPM analysis with cross-validation and permutation testing.

Supports both regression and binary classification tasks.

__init__(results_directory, task_type=None, cpm_model=LinearCPM, cv=KFold(n_splits=10, shuffle=True, random_state=42), inner_cv=None, edge_selection=UnivariateEdgeSelection(selection_statistic='pearson', edge_selection=[PThreshold(threshold=[0.05], correction=[None])]), select_stable_edges=False, stability_threshold=0.8, impute_missing_values=True, standardize_covariates=True, model_input='raw', n_permutations=0, stability_significance_method='nbs', nbs_stability_threshold=0.5, nbs_component_stat='extent', atlas=None, atlas_labels=None, device='cpu', random_state=42, **removed)

Initialize the CPMAnalysis object.

Parameters:

Name Type Description Default
results_directory str

Directory to which all results, plots, and the HTML report are saved.

required
task_type Union[TaskType, str, None]

Type of task: 'regression' or 'classification'. If None, it is auto-detected from the target variable (a binary target is treated as classification).

None
cpm_model Type[LinearCPM]

The CPM model class to fit each fold. One of LinearCPM, DecisionTreeCPM, RandomForestCPM, or GAMCPM.

LinearCPM
cv Union[BaseCrossValidator, BaseShuffleSplit, RepeatedKFold, StratifiedKFold]

Outer cross-validation strategy used for performance estimation.

KFold(n_splits=10, shuffle=True, random_state=42)
inner_cv Union[BaseCrossValidator, BaseShuffleSplit, RepeatedKFold, StratifiedKFold]

Inner cross-validation strategy for hyperparameter tuning (e.g. the p-threshold) and stable-edge selection. If None, no inner loop is run and exactly one edge-selection configuration must be provided.

None
edge_selection UnivariateEdgeSelection

Edge-selection method and its hyperparameter grid.

UnivariateEdgeSelection(selection_statistic='pearson', edge_selection=[PThreshold(threshold=[0.05], correction=[None])])
select_stable_edges bool

If True, keep only edges selected in a sufficient fraction of inner folds (see stability_threshold). Requires an inner_cv.

False
stability_threshold float

Minimum fraction of inner folds in which an edge must be selected to be considered stable. Only used when select_stable_edges=True.

0.8
impute_missing_values bool

Whether to impute missing values in X and the covariates (NaNs in the target y always raise an error).

True
standardize_covariates bool

z-score the covariates inside every outer training fold (mean and standard deviation of the training split, applied to the held-out split) before they enter edge selection, residualisation and the covariate models. This changes no estimate -- OLS residuals are invariant to rescaling the covariates -- but it keeps the confound regressions numerically sound. With covariates on very different scales (e.g. intracranial volume in mm^3 next to 0/1 indicators), the float32 regressions otherwise fail to remove part of the covariate variance, silently. The inner CV receives the already standardised training covariates. Set False only to reproduce results of cccpm 0.7.0.

True
model_input str

What the predictive models consume. 'raw' uses the connectome as given; 'residualized' regresses the covariates out of it first, fitting the residualiser on each training split and applying it to the held-out split. Independent of selection_input, which controls edge selection: together they are the 2x2 of confound control.

This is a property of the run, not an extra model. It has to be: OLS is invariant to it once the covariates are in the design -- full and increment are unchanged -- but a tree, forest or GAM is not. On identical edges, fitting full on raw versus residualised connectivity moves predictions by 391% of sd(y) for DecisionTreeCPM, 65% for RandomForestCPM and 19% for GAMCPM, against 0.0% for LinearCPM. A "residualised" model would therefore mean something different for every backend, and the user could not tell from the results which connectome produced full.

'raw'
n_permutations int

Number of label permutations for significance testing. 0 disables permutation testing; use 1000+ for publishable p-values.

0
stability_significance_method str

How edge-stability significance is established from the permutations -- that is, whether an edge is selected across folds more consistently than chance. This is a different question from which edges pass the selection threshold in the first place, which is set on :class:PThreshold. 'nbs' uses the Network-Based Statistic (connected-component test, subnetwork-level FWER control); 'tfce' uses network Threshold-Free Cluster Enhancement (per-edge FWER control, no primary threshold).

'nbs'
nbs_stability_threshold float

Stability threshold (>=) for NBS component forming -- a fraction of folds, not a p-value. Because stability is discrete over the outer folds, 0.5 keeps edges selected in a majority of them. Ignored when the method is 'tfce'.

0.5
nbs_component_stat str

NBS component statistic: 'extent' (number of edges, classic NBS) or 'intensity' (summed supra-threshold stability). Ignored when method is 'tfce'.

'extent'
atlas str

Which atlas to use for the brain plots in the report. Either the name of a built-in atlas (e.g. 'Schaefer100-17'; see :func:cccpm.atlases.list_atlases) or a path to a custom CSV file with columns region, x, y, z (MNI coordinates), and optionally network, hemisphere, structure. When a network column is present, the network-summary matrix and chord diagram are enabled automatically. None disables the brain plots that require coordinates.

None
atlas_labels str

.. deprecated:: Use atlas instead. Accepts a path to a custom atlas CSV. If both atlas and atlas_labels are given, atlas wins. This parameter will be removed in a future release.

None
device str

Compute device: 'cpu', or 'cuda'/'gpu' to use an available GPU (falls back to CPU with a warning if CUDA is unavailable).

'cpu'
random_state int

Seed for permutation generation. Uses a local RNG and does not modify the global NumPy/torch random state.

42

run(X, y, covariates=None)

Estimates a model using the provided data and conducts permutation testing. This method first fits the model to the actual data and subsequently performs estimation on permuted data for a specified number of permutations. Finally, it calculates permutation results.

Parameters:

Name Type Description Default
X Union[DataFrame, ndarray]
required
y Union[Series, DataFrame, ndarray]
required
covariates Union[Series, DataFrame, ndarray, None]

Omit it (or pass None) for vanilla CPM with no confound control. In that mode only the connectome model is defined -- covariates, full, full and increment need covariates and are reported as NaN, and the models that do exist are listed in available_models.json. Options that presuppose covariates (a *_partial edge statistic, model_input='residualized') then raise up front.

None