Gaussian _____ Student’s t _____ Chi-squared _____ Fisher-Snedecor F _____ Hotelling’s T-squared

rft1d.distributions¶

SciPy-like interface to 1D RFT distributions. Currently implemented distributions include:

Gaussian

Student’s t

$\chi^2$

Fisher-Snedecor F

Hotelling’s T²

All distributions share the following functions:

Methods:

isf — RFT inverse survival function (critical height)

isf0d — Common (0D) inverse survival function (critical height)

p_cluster — RFT cluster-level inference

p_set — RFT set-level inference

sf — RFT survival function

sf0d — Common (0D) survival function.

Basic use:

All distributions can be accessed directly from rft1d as follows:

>>> height = 3.0
>>> nodes = 101
>>> FWHM = 10.0
>>> rft1d.norm.sf(height, nodes, FWHM)
>>> rft1d.norm.sf0d(height)

Unbroken and broken fields:

If the field is unbroken (i.e. continuous) between the start and the end of the field, then the “nodes” argument to all methods should be an integer representing the number of field nodes:

>>> height = 3.0
>>> nodes = 101
>>> FWHM = 10.0
>>> rft1d.norm.sf(height, nodes, FWHM)

However, if the field is broken (i.e. piecewise continuous), then the “nodes” argument should be a 1D mask: a boolean array (size: nodes) where False specifies nodes which are masked out:

>>> height = 3.0
>>> nodes = np.array([True]*20 + [False]*30 + [True]*51)
>>> FWHM = 10.0
>>> rft1d.norm.sf(height, nodes, FWHM)

Very rough fields and the Bonferroni correction:

When the fields are very rough (e.g. FWHM < 2), the Bonferroni correction may be less severe than the RFT correction. While both are vaild, it is generally best to use the less-severe threshold to maintain statistical power. To adopt the less-severe threshold use the keyword argument withBonf as follows:

>>> rft1d.norm.sf(3, 101, 1.5, withBonf=False) #yields 0.179
>>> rft1d.norm.sf(3, 101, 1.5, withBonf=True)  #yields 0.136

By default the withBonf argument is False.

>>> rft1d.norm.sf(3, 101, 1.5)  #yields 0.179

For smooth fields the keyword argument will have no effect:

>>> rft1d.norm.sf(3, 101, 5.0, withBonf=False) #yields 0.0590
>>> rft1d.norm.sf(3, 101, 5.0, withBonf=True)  #yields 0.0590

Very smooth fields:

When Gaussian fields become very smooth, they start to behave like Gaussian scalars. Theoretically RFT results are equivalent to scalar results when smoothness is infinite. Thus raising the FWHM value systematically will cause the RFT results to converge to typical 0D results:

>>> scipy.stats.norm.sf(2)  #yields 0.02275
>>> rft1d.norm.sf(3, 101, 10.0) #yields 0.31710
>>> rft1d.norm.sf(3, 101, 100.0) #yields 0.05693
>>> rft1d.norm.sf(3, 101, 1000.0) #yields 0.02599
>>> rft1d.norm.sf(3, 101, 10000.0) #yields 0.02284
>>> rft1d.norm.sf(3, 101, 100000.0) #yields 0.02275

Setting the smoothness to infinite will return the same result:

>>> rft1d.norm.sf(3, 101, np.inf) #yields 0.02275

Gaussian (rft1d.norm)¶

norm.isf(alpha, nodes, FWHM, withBonf=False)¶

RFT inverse survival function. (see also the survival function: rft1d.norm.sf)

Parameters:

alpha – upper tail probability (float; 0 < alpha < 1)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha.

Examples:

>>> rft1d.norm.isf(0.05, 101, 10.0)

norm.isf0d(alpha)¶

Inverse survival function (0D); equivalent to scipy.stats.norm.isf

Examples:

>>> rft1d.norm.isf0d([0.01, 0.05, 0.1])
>>> scipy.stats.norm.isf([0.01, 0.05, 0.1]3)

norm.p_cluster(k, u, nodes, FWHM, withBonf=False)¶

RFT cluster-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For set-specific probabilities use rft1d.norm.p_set

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.norm.isf

Parameters:

k – cluster extent (resels)

u – threshold

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Cluster-specific probability value.

Examples:

>>> rft1d.norm.p_cluster(0.5, 3.0, 101, 15.0)

norm.p_set(c, k, u, nodes, FWHM, withBonf=False)¶

RFT set-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce at least c upcrossings with a minimum extent of k when thresholded at u. This probability pertains to the entire excursion set. For cluster-specific probabilities use rft1d.norm.p_cluster

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.norm.isf

Parameters:

c – number of upcrossings

k – minimum cluster extent (resels)

u – threshold

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Set-specific probability value.

Examples:

>>> rft1d.norm.p_set(2, 0.5, 3.0, 101, 15.0)

norm.sf(u, nodes, FWHM, withBonf=False)¶

RFT survival function.

Probability that 1D Gaussian fields with a smoothness FWHM would produce a 1D statistic field whose maximum exceeds u.

Parameters:

u – threshold (int, float, or sequence of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

The probability of exceeding the specified heights.

Examples:

>>> rft1d.norm.sf([1,2,3,4,5], 101, 10.0)

norm.sf0d(heights)¶

Survival function (0D); equivalent to scipy.stats.norm.sf

Examples:

>>> rft1d.norm.sf0d([0,1,2])
>>> scipy.stats.norm.sf([0,1,2]3)

Student’s t (rft1d.t)¶

t.isf(alpha, df, nodes, FWHM, withBonf=False)¶

RFT inverse survival function. (see also the survival function: rft1d.t.sf)

Parameters:

alpha – upper tail probability (float; 0 < alpha < 1)

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha.

Examples:

>>> rft1d.t.isf(0.05, 8, 101, 10.0)

t.isf0d(alpha, df)¶

Inverse survival function (0D); equivalent to scipy.stats.t.isf

Examples:

>>> rft1d.t.isf0d([0.01, 0.05, 0.1], 8)
>>> scipy.stats.t.isf([0.01, 0.05, 0.1], 8)

t.p_cluster(k, u, df, nodes, FWHM, withBonf=False)¶

RFT cluster-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For set-specific probabilities use rft1d.t.p_set

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.t.isf

Parameters:

k – cluster extent (resels)

u – threshold

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Cluster-specific probability value.

Examples:

>>> rft1d.t.p_cluster(0.5, 3.0, 8, 101, 15.0)

t.p_set(c, k, u, df, nodes, FWHM, withBonf=False)¶

RFT set-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce at least c upcrossings with a minimum extent of k when thresholded at u. This probability pertains to the entire excursion set. For cluster-specific probabilities use rft1d.t.p_cluster

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.t.isf

Parameters:

c – number of upcrossings

k – minimum cluster extent (resels)

u – threshold

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Set-specific probability value.

Examples:

>>> rft1d.t.p_set(2, 0.5, 3.0, 8, 101, 15.0)

t.sf(u, df, nodes, FWHM, withBonf=False)¶

RFT survival function.

Probability that 1D Gaussian fields with a smoothness FWHM would produce a 1D statistic field whose maximum exceeds u.

Parameters:

u – threshold (int, float, or sequence of int or float)

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

The probability of exceeding the specified heights.

Examples:

>>> rft1d.t.sf([1,2,3,4,5], 8, 101, 10.0)

t.sf0d(u, df)¶

Survival function (0D); equivalent to scipy.stats.t.sf

Examples:

>>> rft1d.t.sf0d([0,1,2], 8)
>>> scipy.stats.t.sf([0,1,2], 8)

Chi-squared (rft1d.chi2)¶

chi2.isf(alpha, df, nodes, FWHM, withBonf=False)¶

RFT inverse survival function. (see also the survival function: rft1d.chi2.sf)

Parameters:

alpha – upper tail probability (float; 0 < alpha < 1)

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha.

Examples:

>>> rft1d.chi2.isf(0.05, 8, 101, 10.0)

chi2.isf0d(alpha, df)¶

Inverse survival function (0D); equivalent to scipy.stats.chi2.isf

Examples:

>>> rft1d.chi2.isf0d([0.01, 0.05, 0.1], 8)
>>> scipy.stats.chi2.isf([0.01, 0.05, 0.1], 8)

chi2.p_cluster(k, u, df, nodes, FWHM, withBonf=False)¶

RFT cluster-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For set-specific probabilities use rft1d.chi2.p_set

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.chi2.isf

Parameters:

k – cluster extent (resels)

u – threshold

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Cluster-specific probability value.

Examples:

>>> rft1d.chi2.p_cluster(0.5, 3.0, 8, 101, 15.0)

chi2.p_set(c, k, u, df, nodes, FWHM, withBonf=False)¶

RFT set-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce at least c upcrossings with a minimum extent of k when thresholded at u. This probability pertains to the entire excursion set. For cluster-specific probabilities use rft1d.chi2.p_cluster

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.chi2.isf

Parameters:

c – number of upcrossings

k – minimum cluster extent (resels)

u – threshold

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Set-specific probability value.

Examples:

>>> rft1d.chi2.p_set(2, 0.5, 3.0, 8, 101, 15.0)

chi2.sf(u, df, nodes, FWHM, withBonf=False)¶

RFT survival function.

Probability that 1D Gaussian fields with a smoothness FWHM would produce a 1D statistic field whose maximum exceeds u.

Parameters:

u – threshold (int, float, or sequence of int or float)

df – degrees of freedom (int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

The probability of exceeding the specified heights.

Examples:

>>> rft1d.chi2.sf([1,2,3,4,5], 8, 101, 10.0)

chi2.sf0d(u, df)¶

Survival function (0D); equivalent to scipy.stats.chi2.sf

Examples:

>>> rft1d.chi2.sf0d([0,1,2], 8)
>>> scipy.stats.chi2.sf([0,1,2], 8)

Fisher-Snedecor F (rft1d.f)¶

f.isf(alpha, df, nodes, FWHM, withBonf=False)¶

RFT inverse survival function. (see also the survival function: rft1d.f.sf)

Parameters:

alpha – upper tail probability (float; 0 < alpha < 1)

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha.

Examples:

>>> rft1d.f.isf(0.05, (2,14), 101, 10.0)

f.isf0d(alpha, df)¶

Inverse survival function (0D); equivalent to scipy.stats.f.isf

Examples:

>>> rft1d.f.isf0d([0.01, 0.05, 0.1], (3,15))
>>> scipy.stats.f.isf([0.01, 0.05, 0.1], 4, 21)

f.p_cluster(k, u, df, nodes, FWHM, withBonf=False)¶

RFT cluster-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For set-specific probabilities use rft1d.f.p_set

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.f.isf

Parameters:

k – cluster extent (resels)

u – threshold

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Cluster-specific probability value.

Examples:

>>> rft1d.f.p_cluster(0.5, 3.0, (2,14), 101, 15.0)

f.p_set(c, k, u, df, nodes, FWHM, withBonf=False)¶

RFT set-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce at least c upcrossings with a minimum extent of k when thresholded at u. This probability pertains to the entire excursion set. For cluster-specific probabilities use rft1d.f.p_cluster

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.f.isf

Parameters:

c – number of upcrossings

k – minimum cluster extent (resels)

u – threshold

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Set-specific probability value.

Examples:

>>> rft1d.f.p_set(2, 0.5, 3.0, (2,14), 101, 15.0)

f.sf(u, df, nodes, FWHM, withBonf=False)¶

RFT survival function.

Probability that 1D Gaussian fields with a smoothness FWHM would produce a 1D statistic field whose maximum exceeds u.

Parameters:

u – threshold (int, float, or sequence of int or float)

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

The probability of exceeding the specified heights.

Examples:

>>> rft1d.f.sf([1,2,3,4,5], (2,14), 101, 10.0)

f.sf0d(u, df)¶

Survival function (0D); equivalent to scipy.stats.f.sf

Examples:

>>> rft1d.f.sf0d([0,1,2], (3,15))
>>> scipy.stats.f.sf([0,1,2], 4, 21)

Hotelling’s T2 (rft1d.T2)¶

T2.isf(alpha, df, nodes, FWHM, withBonf=False)¶

RFT inverse survival function. (see also the survival function: rft1d.T2.sf)

Parameters:

alpha – upper tail probability (float; 0 < alpha < 1)

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha.

Examples:

>>> rft1d.T2.isf(0.05, (2,14), 101, 10.0)

T2.isf0d(alpha, df)¶

0D inverse survival function for the Hotelling’s T2 distribution (not implemented in scipy.stats)

Examples:

>>> rft1d.T2.isf0d(0.05, (2,14))
>>> rft1d.T2.isf0d([0.01, 0.05, 0.10], (2,14))

T2.p_cluster(k, u, df, nodes, FWHM, withBonf=False)¶

RFT cluster-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For set-specific probabilities use rft1d.T2.p_set

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.T2.isf

Parameters:

k – cluster extent (resels)

u – threshold

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Cluster-specific probability value.

Examples:

>>> rft1d.T2.p_cluster(0.5, 3.0, (2,14), 101, 15.0)

T2.p_set(c, k, u, df, nodes, FWHM, withBonf=False)¶

RFT set-level inference.

Probability that 1D Gaussian fields with a smoothness of FWHM would produce at least c upcrossings with a minimum extent of k when thresholded at u. This probability pertains to the entire excursion set. For cluster-specific probabilities use rft1d.T2.p_cluster

Warning

The threshold u should generally be chosen objectively. One possibility is to calculate the alpha-based critical threshold using the inverse survival function: rft1d.T2.isf

Parameters:

c – number of upcrossings

k – minimum cluster extent (resels)

u – threshold

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

Set-specific probability value.

Examples:

>>> rft1d.T2.p_set(2, 0.5, 3.0, (2,14), 101, 15.0)

T2.sf(u, df, nodes, FWHM, withBonf=False)¶

RFT survival function.

Probability that 1D Gaussian fields with a smoothness FWHM would produce a 1D statistic field whose maximum exceeds u.

Parameters:

u – threshold (int, float, or sequence of int or float)

df – degrees of freedom (two-tuple of int or float)

nodes – number of field nodes (int) OR a binary field (boolean array)

FWHM – field smoothness (float)

withBonf – use a Bonferroni correction if less severe than the RFT correction (bool)

Returns:

The probability of exceeding the specified heights.

Examples:

>>> rft1d.T2.sf([1,2,3,4,5], (2,14), 101, 10.0)

T2.sf0d(u, df)¶

0D survival function for the Hotelling’s T2 distribution (not implemented in scipy.stats)

Examples:

>>> rft1d.T2.sf0d([0,1,2], (2,14))