DOC: Check consistency between docstring and tutorial for paired permutation cluster test

[Cathaway]

Proposed documentation enhancement

This tutorial Mass-univariate twoway repeated measures ANOVA on single trial power — MNE 1.10.1 documentation gave an example that puts number of replications/subjects as the first dimension, akin to 1), but the API doc mne.stats.permutation_cluster_test — MNE 1.10.1 documentation tells me I should take after 2)? If I'm not mistaken one of these documentations needs revision right?

[welcome]

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴

[scott-huberty]

Hey @Cathaway can you help me understand better the discrepancy between the tutorial and the API documentation, and if you have a suggestion for improving one or both of these pages of the documentation, that would be helpful!

I interpret the API doc for the X parameter of permutation_cluster_test as: Pass a list of Numpy arrays, where n_observations corresponds to dimension 0 in each array. (and This is what the tutorial does, no?)

Is the issue that the API doc uses the term "first dimension" ("The first dimension of each array is the number of observations from that group"), which is ambiguous because indexing in Python is 0-based? i.e. does "first dimension" mean axis 0 , or does it mean axis 1 ?

If so, I agree that this could be more clear!

[Cathaway]

Hi @scott-huberty thank you for the reply! The way I understand the API doc is (if I understood it at all) that permutation_cluster_test() accepts a list of numpy array, each array contains data in one experimental condition, within each data each row represents one subject/replication, and each column represents a datapoint/timepoint. Hence the general structure should be (n_condition x n_subject x n_timepoint) given the data has only one channel:

	Timepoint 1	Timepoint 2	...	Timepoint n
Subject 1			...
Subject 2			...
Subject ...			...
Subject n			...

(for each array in the list)

If this is true my problem is that the tutorial I cited gave a table that's supposed to represent the structure of example data (titled Sample data layout, under section Setup repeated measure ANOVA), without saying whether this table is the structure of data before or after transforming to meet the function's requirement. We need two tables that clearly say, e.g. Table 1 is the data structure as is, Table 2 is the data structure required by the function. So that users can get a very clear message of how they should prepare the data.

I'd also suggest put up a table like that in the API doc to graphically show what's the required data structure