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
• • Fisher-Snedecor F
• Hotelling’s T2

All distributions share the following functions:

Methods: Basic use: 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. 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) ``` 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) ``` 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 ``` 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)

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) Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha. ```>>> 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) Cluster-specific probability value. ```>>> 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) Set-specific probability value. ```>>> 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) The probability of exceeding the specified heights. ```>>> 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)

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) Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha. ```>>> 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) Cluster-specific probability value. ```>>> 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) Set-specific probability value. ```>>> 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) The probability of exceeding the specified heights. ```>>> 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)

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) Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha. ```>>> 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) Cluster-specific probability value. ```>>> 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) Set-specific probability value. ```>>> 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) The probability of exceeding the specified heights. ```>>> 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)

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) Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha. ```>>> 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) Cluster-specific probability value. ```>>> 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) Set-specific probability value. ```>>> 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) The probability of exceeding the specified heights. ```>>> 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)

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) Quantile corresponding to upper-tail probability alpha. Equivalently: critical threshold at a Type I error rate of alpha. ```>>> 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) Cluster-specific probability value. ```>>> 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) Set-specific probability value. ```>>> 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) The probability of exceeding the specified heights. ```>>> 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)) ```