htfa.group_permutation_test

htfa.group_permutation_test(model, X, coords, n_permutations=100, level=0, random_state=None, verbose=False)

Permutation test of differences between groups, per factor.

Group paths must have equal depth, with distinct labels for groups under different parents; ragged folder hierarchies can be fitted and plotted but do not define this level-wise permutation scheme.

The labels of level are shuffled among the units under each parent (the groups of the next level, moved with their subjects, or the subjects at the innermost level), and the model is refitted with the shuffled labels: the same estimator parameters, random_state included, and the model’s unpenalized stage-0 fits (free_fits_) as starts, since those do not depend on the labels. The observed statistics come from the same refit with the true labels (which, for an integer random_state and a fit made without starts or init_template, reproduces model). Every refit’s global template is matched to the first subject’s fixed stage-0 centers (mixture-weighted centers for mixture factors). This reference does not depend on the group labels. A single common permutation displays all statistics in the supplied model’s global template order; reference_indices records the underlying reference identity of each column. See GroupTest for the statistics.

Any caller-supplied starts must be independent of the tested labels; label-informed initialization invalidates this conditional permutation procedure. Group labels must be exchangeable within the specified units under the null. Subject order, and thus the first-subject reference, must be fixed independently of the tested labels and before inspecting effects; the reference is not generally invariant to reordering subjects. Per-factor hypotheses should be specified before examining their effects; use max-statistic correction for selection across factors.

Parameters:

modelHTFA

A fitted HTFA with groups.

X, coordslist of array_like

The data and coordinates model was fitted on.

n_permutationsint

Number of permutations P (default 100). The smallest attainable p-value is 1 / (P + 1).

levelint

Which level of groups to test (0, the top level, by default).

random_stateint, optional

Seed of the permutations (the refits use model.random_state).

verbosebool

Print the progress of the refits.

Returns:

GroupTest

Raises:

ValueError

If model was fitted without groups, level is out of range, no parent at level has two groups, or n_permutations < 1.

Examples

>>> import warnings
>>> from htfa import HTFA
>>> from htfa.synthetic import make_htfa_data
>>> Xs, Rs, _ = make_htfa_data(4, (8, 8), 15, K=2, random_state=0)
>>> model = HTFA(K=2, template_update="fixed", max_global_iter=2,
...              max_local_iter=3, init="power", standardize=False,
...              random_state=0)
>>> with warnings.catch_warnings():
...     warnings.simplefilter("ignore")  # 2 global iterations only
...     model = model.fit(Xs, Rs, groups=["a", "a", "b", "b"])
...     test = group_permutation_test(model, Xs, Rs, n_permutations=3,
...                                   random_state=0)
>>> test.groups, test.center_null.shape, test.pvalues("center").shape
(['a', 'b'], (3, 2), (2,))