nimare.stats.null_to_p

null_to_p(test_value, null_array, tail='two', symmetric=False)[source]

Return p-value for test value(s) against null array.

Changed in version 0.0.7:

  • [FIX] Add parameter symmetric.

Parameters:

  • test_value (1D array_like) – Values for which to determine p-value.

  • null_array (1D array_like) – Null distribution against which test_value is compared.

  • tail ({'two', 'upper', 'lower'}, optional) – Whether to compare value against null distribution in a two-sided (‘two’) or one-sided (‘upper’ or ‘lower’) manner. If ‘upper’, then higher values for the test_value are more significant. If ‘lower’, then lower values for the test_value are more significant. Default is ‘two’.

  • symmetric (bool) – When tail=”two”, indicates how to compute p-values. When False (default), both one-tailed p-values are computed, and the two-tailed p is double the minimum one-tailed p. When True, it is assumed that the null distribution is zero-centered and symmetric, and the two-tailed p-value is computed as P(abs(test_value) >= abs(null_array)).

Returns:

p_value – P-value(s) associated with the test value when compared against the null distribution. Return type matches input type (i.e., a float if test_value is a single float, and an array if test_value is an array).

Return type:

float

Notes

P-values are clipped based on the number of elements in the null array. Therefore no p-values of 0 or 1 should be produced.

When the null distribution is known to be symmetric and centered on zero, and two-tailed p-values are desired, use symmetric=True, as it is approximately twice as efficient computationally, and has lower variance.