nigsp.operations.surrogates.test_significance

nigsp.operations.surrogates.test_significance(surr, data=None, method='Bernoulli', p=0.05, p_bernoulli=None, return_masked=False, mean=False)

Test the significance of the empirical data against surrogates.

Two methods are implemented, ‘Bernoulli’ and ‘frequentist’.

• ‘frequentist’ is a group or single subject test. It tests that the empirical data are in the highest (or lowest) percentile (where the percentile is defined by p/2).

• ‘Bernoulli’ is a group test. It tests that the number of subjects for which the empirical data is higher (or lower) than a set of surrogates (frequentist approach) is at the tail of a binomial cumulative distribution (where ‘tail’ is defined by p).

Note that p is expressed as two-tails test for the frequentist approach and a one-tail test for the Bernoulli approach.

Both surr and data are expected to have first dimensions: observations [x subjects].

Parameters:

surrnumpy.ndarray

The surrogate matrix, where all surrogates are aligned along the last axis. May have the empirical data matrix last along the last axis. Expected to have shape: observations, [subjects,] surrogates.

datanumpy.ndarray or None, optional

The empirical data matrix. If given, it’s appended at the end of the surrogate matrix. Expected to have shape: observations[, subjects].

method‘Bernoulli’ or ‘frequentist’, optional

The method to adopt for testing, either based on a Bernoulli process or a frequentist observation (see above).

pfloat, optional

The probability threshold to adopt for the frequentist approach part. Note that this is a two-tails test.

p_bernoullifloat or None, optional

The probability threshold to adopt for Bernoulli’s test. If left as None, the specified p value will be used instead, and p will be set to 0.1. Note that this is a one-tail test.

return_maskedbool, optional

If True, returns the masked data. If False, returns a mask that holds True where the good data are (inverse of numpy mask). Mask has the same shape as data.

meanbool, optional

If True, returns the average of the masked data along the last axis.

Returns:

numpy.ndarray

A numpy.ndarray shaped observations[, subjects]. If return_masked is True, returns the masked version of data, otherwise returns the mask. If mean is True, returns the average along the subject axis.

Raises:

ValueError

If data is not None and the surrogate shape (except last axis) is different from the data shape.

NotImplementedError

If any other method rather than those listed above is selected.