Skip to main content

StatsCluster

Namespace: STSLIB  ·  Library: Statistics Library

Python equivalent

mne.stats.permutation_cluster_test in MNE-Python.

#include <sts/sts_cluster.h>

class STSLIB::StatsCluster

Cluster-based permutation test for comparing two conditions.

Maris-Oostenveld cluster-mass permutation tests and Threshold-Free Cluster Enhancement on (channel,time) or (vertex,time) statistic maps.

src/examples/ex_sts_statistics/main.cpp
// 12 subjects, 8 channels on a line, 1 time point; channels 2-4 carry an effect in condition B
SparseMatrix<int> chain(8, 8);
for (int i = 0; i + 1 < 8; ++i) {
    chain.insert(i, i + 1) = 1;
    chain.insert(i + 1, i) = 1;
}
QVector<MatrixXd> condA, condB;
for (int s = 0; s < 12; ++s) {
    MatrixXd noiseA(8, 1), noiseB(8, 1);
    for (int ch = 0; ch < 8; ++ch) {
        noiseA(ch, 0) = std::sin(1.3 * s + 0.7 * ch);
        noiseB(ch, 0) = std::cos(0.9 * s + 1.1 * ch) + ((ch >= 2 && ch <= 4) ? 3.0 : 0.0);
    }
    condA.append(noiseA);
    condB.append(noiseB);
}
const StatsClusterResult clusters = StatsCluster::permutationTest(condA, condB, chain, 500);
// Cluster ids are negative where A < B; |id| - 1 indexes vecClusterStats and vecClusterPvals
const int effectCluster = clusters.matClusterIds(3, 0);

Static Methods​

permutationTest(dataA, dataB, adjacency, nPermutations, clusterAlpha, pThreshold, tail)​

Cluster-based permutation test.

Parameters:

  • dataA : const QVector< Eigen::MatrixXd > & Per-subject data for condition A. Each matrix is nChannels x nTimes.

  • dataB : const QVector< Eigen::MatrixXd > & Per-subject data for condition B. Each matrix is nChannels x nTimes.

  • adjacency : const Eigen::SparseMatrix< int > & Spatial adjacency matrix (nChannels x nChannels).

  • nPermutations : int Number of permutations (default 1024).

  • clusterAlpha : double Alpha level for initial thresholding (default 0.05).

  • pThreshold : double p-value threshold for reporting significant clusters (default 0.05).

  • tail : StatsTailType Tail type for the test.

Returns:

oneSamplePermutationTest(data, adjacency, threshold, nPermutations, tail)​

One-sample cluster-based permutation test.

Tests whether the mean across subjects differs from zero at each vertex x time point using sign-flip permutations.

Parameters:

  • data : const QVector< Eigen::MatrixXd > & Per-subject data. Each matrix is nVertices x nTimes.

  • adjacency : const Eigen::SparseMatrix< int > & Spatio-temporal adjacency matrix (nVerticesnTimes x nVerticesnTimes).

  • threshold : double Cluster-forming t-threshold.

  • nPermutations : int Number of sign-flip permutations.

  • tail : StatsTailType Tail type for the test.

Returns:

fTestPermutationTest(conditions, adjacency, threshold, nPermutations)​

F-test cluster-based permutation test for one-way ANOVA.

Tests for differences across conditions by randomly reassigning condition labels and computing max cluster F-statistics.

Parameters:

  • conditions : const QVector< QVector< Eigen::MatrixXd > > & Vector of conditions, each containing per-subject matrices (nVertices x nTimes).

  • adjacency : const Eigen::SparseMatrix< int > & Spatio-temporal adjacency matrix (nVerticesnTimes x nVerticesnTimes).

  • threshold : double Cluster-forming F-threshold.

  • nPermutations : int Number of permutations.

Returns:

tfce(statMap, adjacency, E, H, nSteps)​

Threshold-Free Cluster Enhancement (TFCE).

Enhances a statistic map by integrating cluster extent and height over a range of thresholds (Smith & Nichols 2009). Handles both positive and negative values. Both signs are swept by the thresholds h = k * dh, k = 1..nSteps, with dh = max|statMap| / (nSteps + 1), like MNE-Python's threshold=dict(start=dh, step=dh).

Parameters:

  • statMap : const Eigen::MatrixXd & Statistic map (nVertices x nTimes).

  • adjacency : const Eigen::SparseMatrix< int > & Spatio-temporal adjacency matrix (nVerticesnTimes x nVerticesnTimes).

  • E : double Extent exponent (default 0.5).

  • H : double Height exponent (default 2.0).

  • nSteps : int Number of threshold steps (default 100).

Returns:

  • Eigen::MatrixXd — TFCE-enhanced score map (nVertices x nTimes).

Example​

Used in examples​

ex_sts_statistics​

Statistics library on small literal data sets with known answers.

src/examples/ex_sts_statistics/main.cpp, line 176
const StatsClusterResult clusters = StatsCluster::permutationTest(condA, condB, chain, 500);
// Cluster ids are negative where A < B; |id| - 1 indexes vecClusterStats and vecClusterPvals
const int effectCluster = clusters.matClusterIds(3, 0);
const bool clusterOk = effectCluster < 0 && clusters.matClusterIds(2, 0) == effectCluster && clusters.matClusterIds(4, 0) == effectCluster && clusters.matClusterIds(7, 0) != effectCluster;
const double clusterP = clusterOk ? clusters.vecClusterPvals[-effectCluster - 1] : -1.0;
// The observed statistic counts as one permutation, so p >= 1 / (500 + 1) as in MNE-Python
ok &= expect(clusterOk && clusterP >= 1.0 / 501.0 && clusterP < 0.05,
             QString("channels 2-4 form one negative cluster, 1/501 <= p %1 < 0.05").arg(clusterP));

Authors of this file​