API

run 

wonkyconn.run.global_parser(exit_on_error: bool = True) → ArgumentParser: Build the CLI argument parser for wonkyconn.

wonkyconn.run.main(argv: None | Sequence[str] = None) → None: Entry point for the wonkyconn CLI.

workflow 

Process fMRIPrep outputs to timeseries based on denoising strategy.

wonkyconn.workflow.is_halfpipe(index: BIDSIndex) → bool: Check whether the indexed dataset was produced by HALFpipe.

wonkyconn.workflow.load_data_frame(args: Namespace) → DataFrame: Load a phenotype TSV with participant_id, gender, and age columns.

wonkyconn.workflow.make_record(index: BIDSIndex, data_frame: DataFrame, connectivity_matrices: list[ConnectivityMatrix], distance_matrices: dict[str, ndarray[tuple[Any, ...], dtype[float64]]], region_memberships: dict[str, DataFrame], metric_key: str, seg_key: str, atlases: dict[str, Atlas], disable_prediction_gradient: bool) → dict[str, Any]: Compute all QC metrics for a single group of connectivity matrices.

wonkyconn.workflow.workflow(args: Namespace) → None: Run the group-level connectivity quality-control pipeline.

class wonkyconn.config.WonkyConnConfig(bids_dir: Path | None = None, output_dir: Path | None = None, analysis_level: str = 'group', phenotypes: Path | None = None, atlas: list[tuple[str, ~pathlib.Path]]=<factory>, verbosity: int = 2, debug: bool = False, light_mode: bool = False, theme: str | None = None, suppress_warnings: bool = False)

Shared configuration for CLI and GUI.

classmethod from_cli_args(args: Namespace | None) → WonkyConnConfig: Create a config from argparse args (may be partial when GUI is requested).

to_namespace() → Namespace: Convert to argparse.Namespace expected by workflow.

atlas 

class wonkyconn.atlas.Atlas(seg: str, image: ~nibabel.nifti1.Nifti1Image, structure: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.bool]] = <factory>)

Abstract base class representing a brain atlas.

seg

The “seg” value that the atlas corresponds to. A “seg” uniquely identifies an atlas in a given space and resolution.

Type:: str

image

The Nifti1Image object for the atlas file.

Type:: nib.nifti1.Nifti1Image

static create(seg: str, path: Path) → Atlas

Create an Atlas object based based on it’s “seg” value and path.

Parameters:

seg (str) – The “seg” value.
path (Path) – The path to the image.

Returns:

An instance of the Atlas class.

Return type:

Atlas

Raises:

None –

abstractmethod get_centroid_points() → ndarray[tuple[Any, ...], dtype[float64]]

Returns the centroid points of the atlas regions.

Returns:: An array of centroid indices.
Return type:: npt.NDArray[np.float64]

get_centroids() → ndarray[tuple[Any, ...], dtype[float64]]

Returns the centroid coordinates of the atlas regions.

Returns:: An array of centroid coordinates.
Return type:: npt.NDArray[np.float64]

get_distance_matrix() → ndarray[tuple[Any, ...], dtype[float64]]

Calculates the pairwise distance matrix between the centroids of the atlas regions.

Returns:: The distance matrix.
Return type:: npt.NDArray[np.float64]

abstractmethod get_yeo7_membership() → DataFrame

Get the yeo7 network membership of the atlas.

Returns:: membership of each parcel in shape (number of parcels, 7)
Return type:: pd.DataFrame

load_yeo7_network() → Nifti1Image

Load and resample the yeo 7 networks to the atlas’s space.

Returns:: resampled yeo 7 networks image.
Return type:: nib.nifti1.Nifti1Image

class wonkyconn.atlas.DsegAtlas(seg: str, image: nibabel.nifti1.Nifti1Image, structure: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.bool]] = <factory>)

get_centroid_points() → ndarray[tuple[Any, ...], dtype[float64]]

Returns the centroid points of the atlas regions.

Returns:: An array of centroid indices.
Return type:: npt.NDArray[np.float64]

get_yeo7_membership() → DataFrame

Get the yeo7 network membership of the atlas.

Returns:: membership of each parcel in shape (number of parcels, 7)
Return type:: pd.DataFrame

class wonkyconn.atlas.ProbsegAtlas(seg: str, image: nibabel.nifti1.Nifti1Image, structure: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.bool]] = <factory>, epsilon: float = 1e-06)

get_centroid_points() → ndarray[tuple[Any, ...], dtype[float64]]

Returns the centroid points of the atlas regions.

Returns:: An array of centroid indices.
Return type:: npt.NDArray[np.float64]

get_yeo7_membership() → DataFrame

Get the yeo7 network membership of the atlas.

Returns:: membership of each parcel in shape (number of parcels, 7)
Return type:: pd.DataFrame

base 

class wonkyconn.base.ConnectivityMatrix(path: Path, metadata: dict[str, Any], has_header: bool = False)

Represents a connectivity matrix.

path

The path to the “.tsv” file containing the connectivity matrix.

Type:: Path

metadata

Additional metadata associated with the connectivity matrix.

Type:: dict[str, Any]

load() → ndarray[tuple[Any, ...], dtype[float64]]

Load the connectivity matrix from the file.

Returns:: The loaded connectivity matrix as a NumPy array.
Return type:: ndarray

property region_count: int

Get the number of regions in the connectivity matrix.

Returns:: The number of regions.
Return type:: int

correlation 

logger 

General logger for the wonkyconn package.

wonkyconn.logger.set_verbosity(verbosity: int | list[int]) → None: Set the logger verbosity level (0=ERROR, 1=WARNING, 2=INFO, 3=DEBUG).

features 

features.quality_control_connectivity 

wonkyconn.features.quality_control_connectivity.calculate_median_absolute(x: pd.Series[float]) → float: Calculate Absolute median value

wonkyconn.features.quality_control_connectivity.calculate_qcfc(data_frame: DataFrame, connectivity_matrices: Iterable[ConnectivityMatrix], metric_key: str = 'MeanFramewiseDisplacement') → DataFrame

metric calculation: quality control / functional connectivity

For each edge, we then computed the correlation between the weight of that edge and the mean relative RMS motion. QC-FC relationships were calculated as partial correlations that accounted for participant age and sex

Parameters:

data_frame (pd.DataFrame) – The data frame containing the covariates “age” and “gender”. It needs to have one row for each connectivity matrix.
connectivity_matrices (Iterable[ConnectivityMatrix]) – The connectivity matrices to calculate QCFC for.
metric_key (str, optional) – The key of the metric to use for QCFC calculation. Defaults to “MeanFramewiseDisplacement”.

Returns:

The QCFC values between connectivity matrices and the metric.

Return type:

pd.DataFrame

wonkyconn.features.quality_control_connectivity.calculate_qcfc_percentage(qcfc: DataFrame) → float

Calculate the percentage of significant QC-FC relationships.

Parameters:: qcfc (pd.DataFrame) – The QC-FC values between connectivity matrices and the metric.
Returns:: The percentage of significant QC-FC relationships.
Return type:: float

wonkyconn.features.quality_control_connectivity.significant_level(x: pd.Series[float], alpha: float = 0.05, correction: str | None = None) → npt.NDArray[np.bool_]

Apply FDR correction to a pandas.Series p-value object.

Parameters:

x (pandas.Series) – Uncorrected p-values.
alpha (float) – Alpha threshold.
correction (str | None) – Multiple comparison method. None for no correction. See statsmodels.stats.multitest.multipletests.

Returns:

Mask for data passing multiple comparison test.

Return type:

npt.NDArray[np.bool_]

features.network 

Network similarity measures.

wonkyconn.features.network.network_similarity(connectivity_matrices: list[ConnectivityMatrix], region_membership: DataFrame) → Tuple[DataFrame, float64]

Calculate network similarity of of default mode network recovered through functional connectivity and Yeo’s template.

Parameters:

connectivity_matrices (list[ConnectivityMatrix]) – A collection of functional connectivity matrices of the same atlas and denoising method.
region_membership (pd.DataFrame) – Atlas parcel correspondence to Yeo 7 network. Generate throguh the Atlas class.

Returns:

Group level statistics of average correlation with the default mode network and: t-statistics of DMN-FPN distance vs DMN-VIS distance.

Return type:

Tuple[pd.DataFrame, np.float64]

wonkyconn.features.network.single_subject_within_network_connectivity(connectivity_matrix: ConnectivityMatrix, region_membership: DataFrame, yeo_network_index: int = 7) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], float64]

Compute within-network connectivity and DMN correlation for a single subject.

Parameters:

connectivity_matrix (ConnectivityMatrix) – Functional connectivity matrix.
region_membership (pd.DataFrame) – Atlas parcel correspondence to Yeo 7 network. Generate throguh class Atlas.
yeo_network_index (int, optional) – Yeo network for similarity calculation. Defaults to 7.

Returns:

Mean of functional connectivity value within each network. npt.NDArray[np.float64]: Standard deviation of functional connectivity value within each network. np.float64: Average pearson’s correlation of the connectivity pattern with the selected network.

Return type:

npt.NDArray[np.float64]

features.gcor 

GCOR feature implementation.

wonkyconn.features.gcor.calculate_gcor(connectivity_matrices: Iterable[ConnectivityMatrix]) → float: Aggregate GCOR values for a collection of connectivity matrices.

wonkyconn.features.gcor.compute_gcor(matrix: ndarray[tuple[Any, ...], dtype[float64]]) → float: Compute the GCOR value from a correlation matrix.

features.distance_dependence 

wonkyconn.features.distance_dependence.calculate_distance_dependence(qcfc: DataFrame, distance_matrix: ndarray[tuple[Any, ...], dtype[float64]]) → float

Calculate the Spearman correlation between the distance matrix and the QC-FC correlation values.

Parameters: - qcfc (pd.DataFrame): The qcfc DataFrame containing the correlation values with

a multi-index of the lower triangular indices

distance_matrix (npt.NDArray[np.float64]): The distance matrix of the atlas regions.

Returns: - float: The distance dependence value.

features.calculate_degrees_of_freedom 

Calculate degree of freedom

class wonkyconn.features.calculate_degrees_of_freedom.DegreesOfFreedomLossResult(confound_regression_percentage, motion_scrubbing_percentage, nonsteady_states_detector_percentage)

confound_regression_percentage: float: Alias for field number 0

motion_scrubbing_percentage: float: Alias for field number 1

nonsteady_states_detector_percentage: float: Alias for field number 2

wonkyconn.features.calculate_degrees_of_freedom.calculate_degrees_of_freedom_loss(connectivity_matrices: list[ConnectivityMatrix]) → DegreesOfFreedomLossResult

Calculate the percent of degrees of freedom lost during denoising.

Parameters:

connectivity_matrices (list[ConnectivityMatrix]) – Connectivity matrices to evaluate.

Returns:

Percentages for confound regression, motion: scrubbing, and non-steady-state volume removal.

Return type:

DegreesOfFreedomLossResult

wonkyconn.features.calculate_degrees_of_freedom.calculate_for_key(connectivity_matrices: list[ConnectivityMatrix], count: Sequence[int], keys: list[str], predicate: Callable[[str], bool] | None = None) → float

Get the mean percentage for a given metadata key.

Parameters:

connectivity_matrices (list[ConnectivityMatrix]) – List of connectivity matrices.
count (Sequence[int]) – The total number of volumes for each connectivity matrix.
keys (list[str]) – Metadata keys in decreasing priority. Values can be numeric or a sequence of strings.
predicate (Callable[[str], bool] | None) – Optional filter applied when the metadata value is a sequence of strings.

Returns:

The mean percentage.

Return type:

float

features.calculate_gradients_correlation 

wonkyconn.features.calculate_gradients_correlation.calculate_gradients_similarity(gradients: ndarray, group_gradients: ndarray) → float

Calculate similarity between individual and group gradients via Spearman correlations + Fisher z-transform.

Parameters:

gradients (np.ndarray) – Individual gradients, shape (n_vertices, n_components).
group_gradients (np.ndarray) – Matched group-level gradients, same shape.

Returns:

Averaged similarity (mean Fisher-z across components).

Return type:

float

wonkyconn.features.calculate_gradients_correlation.clean_matrix_from_atlas(matrix: ndarray, atlas: Nifti1Image) → ndarray

Remove rows/columns from a connectivity matrix for regions not present in the atlas.

Parameters:

matrix (np.ndarray) – Connectivity matrix.
atlas (nib.Nifti1Image) – Masked atlas.

Returns:

Connectivity matrix limited to regions present in the atlas.

Return type:

np.ndarray

wonkyconn.features.calculate_gradients_correlation.extract_gradients(connectivity_matrices: Iterable[ConnectivityMatrix], atlas: Nifti1Image) → tuple[ndarray, ndarray]

Calculate gradients for each individual and load group-level gradients for alignment.

Parameters:

connectivity_matrices (Iterable[ConnectivityMatrix]) – List of connectivity matrices to process.
atlas (nib.Nifti1Image) – The atlas NIfTI image.

Returns:

Individual aligned gradients and group-level: template gradients.

Return type:

tuple[np.ndarray, np.ndarray]

wonkyconn.features.calculate_gradients_correlation.group_mean_connectivity(connectivity_matrices: Iterable[ConnectivityMatrix]) → ndarray

Calculate the group mean connectivity matrix from a list of connectivity matrices.

Parameters:: connectivity_matrices (Iterable[ConnectivityMatrix]) – List of connectivity matrices to process.
Returns:: The group mean connectivity matrix.
Return type:: np.ndarray

wonkyconn.features.calculate_gradients_correlation.overlapping_atlas_with_mask(subject_atlas: Nifti1Image, group_mask: Nifti1Image) → Nifti1Image

Create a new atlas containing only regions that overlap with the group gradient mask.

Parameters:

subject_atlas (nib.Nifti1Image) – The subject’s atlas in NIfTI format.
group_mask (nib.Nifti1Image) – The group gradient mask in NIfTI format.

Returns:

Atlas with non-overlapping regions zeroed out.

Return type:

nib.Nifti1Image

wonkyconn.features.calculate_gradients_correlation.process_single_matrix(connectivity_matrix: ndarray, atlas: Nifti1Image, gradient_mask: Nifti1Image, gradient_imgs: List[Nifti1Image]) → Tuple[ndarray, ndarray]

Process a single connectivity matrix to compute its gradients aligned to group gradients.

Parameters:

connectivity_matrix (np.ndarray) – The connectivity matrix to process.
atlas (nib.Nifti1Image) – The atlas NIfTI image.
gradient_mask (nib.Nifti1Image) – The group gradient mask NIfTI image.
gradient_imgs (List[nib.Nifti1Image]) – List of group gradient NIfTI images.

Returns:

The individual gradients aligned to group: gradients and the group gradients as a NumPy array.

Return type:

Tuple[np.ndarray, np.ndarray]

wonkyconn.features.calculate_gradients_correlation.remove_nan_from_matrix(matrix: ndarray) → Tuple[ndarray, ndarray]

Remove rows/columns from a connectivity matrix that contain NaN values.

Checks only the upper triangle (including diagonal) for symmetric matrices.

Parameters:

matrix (np.ndarray) – Square connectivity matrix.

Returns:

Cleaned connectivity matrix with NaN: rows/columns removed, and indices of the kept rows/columns.

Return type:

tuple[np.ndarray, np.ndarray]

wonkyconn.features.calculate_gradients_correlation.remove_nan_roi_atlas(atlas: Nifti1Image, kept_idx: ndarray) → Nifti1Image

Remove ROIs from an atlas that are not present in a connectivity matrix.

Parameters:

atlas (nib.Nifti1Image) – The atlas NIfTI image.
kept_idx (np.ndarray) – Indices of rows/columns kept after NaN removal.

Returns:

Atlas image with only kept ROIs and: the list of kept label values.

Return type:

tuple[nib.Nifti1Image, list[int]]

features.age_sex_prediction 

wonkyconn.features.age_sex_prediction.age_sex_scores(connectivity_matrices: List[ConnectivityMatrix], ages: NDArray[np.float64], genders: NDArray[np.str_], n_splits: int, n_pca: int, n_jobs: int = 4, random_state: int = 42) → Dict[str, float]

Computes age and sex prediction scores via connectivity.

Parameters:

connectivity_matrices (List[ConnectivityMatrix]) – List of matrix objects.
ages – Vector of subject ages.
genders – Vector of subject genders.
n_splits (int) – Number of splits for cross-validation.
n_pca (int) – Number of PCA components.
n_jobs (int) – Number of joblib threads.
random_state (int) – Random seed.

Returns:

Dictionary containing AUC, Accuracy, MAE, and R2.

Return type:

Dict[str, float]

wonkyconn.features.age_sex_prediction.training_pipeline(connectivity_data: ndarray[tuple[Any, ...], dtype[float32]], target_labels: ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[str_]], task_type: str, n_splits: int, n_pca: int, n_jobs: int = 4, random_state: int = 1) → DataFrame

Runs a cross-validation pipeline for age or sex prediction.

Parameters:

connectivity_data – Vectorized connectivity matrix.
target_labels – Target vector (ages or genders).
task_type (str) – Type of task (‘classification’ or ‘regression’).
n_splits (int) – Number of repetitions for cross-validation.
n_pca (int) – Number of principal components to extract.
n_jobs (int) – Number of cores for parallel calculation.
random_state (int) – Seed for reproducibility.

Returns:

Statistics (mean, 95% CI) of the scores obtained.

Return type:

pd.DataFrame

file_index 

file_index.base 

wonkyconn.file_index.base.create_defaultdict_of_set() → defaultdict[str, set[Path]]: Factory for a defaultdict whose values are sets of Path.

file_index.bids 

wonkyconn.file_index.bids.parse(path: Path) → dict[str, str] | None

Parses a BIDS-formatted filename and returns a dictionary of its tags.

Parameters:

path (Path) – The path to the file to parse.

Returns:

A dictionary of the file’s BIDS tags, or None if the: file is not a valid BIDS-formatted file.

Return type:

dict[str, str] | None

wonkyconn.file_index.bids.split_ext(path: str | Path) → tuple[str, str]

Splits filename and extension (.gz safe) >>> split_ext(‘some/file.nii.gz’) (‘file’, ‘.nii.gz’) >>> split_ext(‘some/other/file.nii’) (‘file’, ‘.nii’) >>> split_ext(‘otherext.tar.gz’) (‘otherext’, ‘.tar.gz’) >>> split_ext(‘text.txt’) (‘text’, ‘.txt’)

Adapted from niworkflows

visualization 

visualization.plot 

wonkyconn.visualization.plot.plot(records: list[dict[str, Any]], group_by: list[str], output_dir: Path) → None

Plot summary metrics based on the given result data frame.

Parameters:

records (list[dict]) –
Must contain keys: - median_absolute_qcfc - percentage_significant_qcfc - distance_dependence - gcor - dmn_similarity - dmn_vis_distance_vs_dmn_fpn - gradients_similarity - confound_regression_percentage - motion_scrubbing_percentage - nonsteady_states_detector_percentage - sex_auc - age_mae

plus the columns listed in group_by (used as index).
group_by (list[str]) – The list of columns that the results are grouped by.
output_dir (Path) – The directory to save the plot image into as “metrics.png”.

wonkyconn.visualization.plot.plot_degrees_of_freedom_loss(result_frame: DataFrame, degrees_of_freedom_loss_axes: Axes, legend_axes: Axes, colors: list[str]) → None: Plot stacked bars showing degrees-of-freedom loss by source.