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(edge_statistic='pearson', edge_selection=[PThreshold(threshold=[0.05], correction=[None])]), select_stable_edges=False, stability_threshold=0.8, impute_missing_values=True, calculate_residuals=False, n_permutations=0, edge_significance_method='nbs', nbs_threshold=0.5, nbs_component_stat='extent', atlas=None, atlas_labels=None, device='cpu', random_state=42)

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(edge_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
calculate_residuals	bool	If True, regress the covariates out of the connectome before modeling (residualization), in addition to the model variants.	False
n_permutations	int	Number of label permutations for significance testing. 0 disables permutation testing; use 1000+ for publishable p-values.	0
edge_significance_method	str	How edge-stability significance is established from the permutations. '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_threshold	float	Stability threshold (>=) for NBS component forming. Because stability is discrete over the outer folds, 0.5 keeps edges selected in a majority of folds. Ignored when 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)

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]		required