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 T^{2}
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))