stats¶
Provide standalone statistical functions for Adjacency matrices.
Each function takes an Adjacency instance as its first argument (adj).
Methods:
| Name | Description |
|---|---|
cluster_summary | This function provides summaries of clusters within Adjacency matrices. |
plot_label_distance | Create a violin plot of within- and between-label distances. |
plot_silhouette | Create a silhouette plot. |
r_to_z | Apply Fisher’s r to z transformation to each element of the data object. |
similarity | Calculate similarity between two Adjacency matrices. |
stats_label_distance | Calculate permutation tests on within and between label distance. |
threshold | Threshold an Adjacency instance. |
ttest | Calculate ttest across samples. |
z_to_r | Convert z score back into r value for each element of data object. |
Methods¶
cluster_summary¶
cluster_summary(adj, *, clusters = None, summary = 'mean', scope = 'within')This function provides summaries of clusters within Adjacency matrices.
It can compute mean/median of within and between cluster values. Requires a list of cluster ids indicating the row/column of each cluster.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance | required |
clusters | (list) list of cluster labels | None | |
summary | (str) central tendency, ‘mean’ or ‘median’. If None then return all r values | ‘mean’ | |
scope | (str) summarize ‘within’ cluster or ‘between’ clusters | ‘within’ |
Returns:
| Name | Type | Description |
|---|---|---|
dict | (dict) per-cluster summaries |
plot_label_distance¶
plot_label_distance(adj, labels = None, ax = None)Create a violin plot of within- and between-label distances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance (must be a single matrix) | required |
labels | array | numpy array of labels to plot | None |
Returns:
| Type | Description |
|---|---|
| None |
plot_silhouette¶
plot_silhouette(adj, *, labels = None, ax = None, permutation_test = True, n_permute = 5000, colors = None, figsize = (6, 4))Create a silhouette plot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance (must be a single matrix). | required |
labels | array | Numpy array of cluster/group labels. | None |
ax | Matplotlib axis handle. | None | |
permutation_test | bool | Whether to run a permutation test. Default True. | True |
n_permute | int | Number of permutations for the test. Default 5000. | 5000 |
colors | Optional list of RGB triplets, one per cluster (default: seaborn ‘hls’ palette). | None | |
figsize | Figure size tuple. Default (6, 4). | (6, 4) |
Returns:
| Name | Type | Description |
|---|---|---|
dict | Silhouette plot results including scores and optional permutation p-value. |
r_to_z¶
r_to_z(adj)Apply Fisher’s r to z transformation to each element of the data object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance. | required |
Returns:
| Name | Type | Description |
|---|---|---|
Adjacency | New Adjacency with z-transformed values. |
similarity¶
similarity(adj, data, plot = False, method = '2d', n_permute = 5000, metric = 'spearman', include_diag = False, nan_policy = 'omit', tail = 2, return_null = False, n_jobs = -1, random_state = None, *, project: bool = False, progress_bar: bool = False)Calculate similarity between two Adjacency matrices.
The default uses Spearman correlation and a permutation test.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance. | required |
data | Adjacency or array | Adjacency data, or 1-d array same size as adj.data. | required |
plot | bool | If True, plot stacked adjacency matrices. Default False. | False |
method | str | permutation scheme ‘1d’, ‘2d’, or None. | ‘2d’ |
n_permute | int | Number of permutations. Default 5000. | 5000 |
metric | str | ‘spearman’, ‘pearson’, or ‘kendall’. | ‘spearman’ |
include_diag | bool | Only applies to ‘directed’ Adjacency types using method=None or method=‘1d’. Default False (self-similarity is uninformative). Symmetric matrices never store the diagonal, so this flag is a no-op for them. | False |
nan_policy | str | How to handle NaN values. Options: - ‘omit’: Remove NaN values pairwise before computing correlation (default) - ‘propagate’: Allow NaN to propagate through calculations - ‘raise’: Raise an error if NaN values are present | ‘omit’ |
tail | int | str | 2 | ‘two’ (two-tailed, default) or 1 |
return_null | bool | If True, also return the null distribution. Default False. | False |
n_jobs | int | Number of parallel jobs. -1 means all cores. Default -1. | -1 |
random_state | int | Random seed for reproducibility. | None |
project | bool | If True and adj has a spatial_scale, project the per-matrix correlations back into brain space. Default False. | False |
progress_bar | bool | If True, show a progress bar. Default False. | False |
Returns:
| Type | Description |
|---|---|
| dict | list |
stats_label_distance¶
stats_label_distance(adj, *, labels = None, n_permute = 5000, n_jobs = -1, progress_bar = False)Calculate permutation tests on within and between label distance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance (must be a single matrix) | required |
labels | array | numpy array of labels to plot | None |
n_permute | int | number of permutations to run (default=5000) | 5000 |
Returns:
| Name | Type | Description |
|---|---|---|
dict | dictionary of within and between group differences and p-values |
threshold¶
threshold(adj, *, upper = None, lower = None, binarize = False)Threshold an Adjacency instance.
Provide upper and lower values or percentages to perform two-sided thresholding. Binarize will return a mask image respecting thresholds if provided, otherwise respecting every non-zero value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance | required |
upper | (float or str) Upper cutoff for thresholding. If string will interpret as percentile; can be None for one-sided thresholding. | None | |
lower | (float or str) Lower cutoff for thresholding. If string will interpret as percentile; can be None for one-sided thresholding. | None | |
binarize | bool | return binarized image respecting thresholds if provided, otherwise binarize on every non-zero value; default False | False |
Returns:
| Name | Type | Description |
|---|---|---|
Adjacency | thresholded Adjacency instance |
ttest¶
ttest(adj, *, permutation = False, n_permute = 5000, tail = 2, return_null = False, n_jobs = -1, random_state = None, progress_bar = False)Calculate ttest across samples.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance (must contain multiple matrices) | required |
permutation | (bool) Run ttest as permutation. Note this can be very slow. | False | |
n_permute | Number of permutations (used only when permutation=True). Default 5000. | 5000 | |
tail | 2 | ‘two’ (two-tailed, default) or 1 | |
return_null | If True, also return the null distribution. Default False. | False | |
n_jobs | Number of parallel jobs. Default -1 (all cores). | -1 | |
random_state | Random seed for reproducibility. | None | |
progress_bar | If True, show a progress bar. Default False. | False |
Returns:
| Name | Type | Description |
|---|---|---|
out | (dict) contains Adjacency instances of t values (or mean if running permutation) and Adjacency instance of p values. |
z_to_r¶
z_to_r(adj)Convert z score back into r value for each element of data object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adj | Adjacency | Adjacency instance. | required |
Returns:
| Name | Type | Description |
|---|---|---|
Adjacency | New Adjacency with r values. |