Gaussian _____ Student’s t _____ Chisquared _____ FisherSnedecor F _____ Hotelling’s Tsquared
rft1d.distributions¶
SciPylike interface to 1D RFT distributions. Currently implemented distributions include:
 Gaussian
 Student’s t
 FisherSnedecor 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 clusterlevel inference p_set — RFT setlevel 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 lesssevere threshold to maintain statistical power. To adopt the lesssevere 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 uppertail 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 clusterlevel inference.
Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For setspecific probabilities use rft1d.norm.p_set
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Clusterspecific 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 setlevel 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 clusterspecific probabilities use rft1d.norm.p_cluster
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Setspecific 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 uppertail 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 clusterlevel inference.
Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For setspecific probabilities use rft1d.t.p_set
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Clusterspecific 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 setlevel 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 clusterspecific probabilities use rft1d.t.p_cluster
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Setspecific 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)
Chisquared (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 uppertail 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 clusterlevel inference.
Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For setspecific probabilities use rft1d.chi2.p_set
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Clusterspecific 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 setlevel 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 clusterspecific probabilities use rft1d.chi2.p_cluster
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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: Setspecific 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)
FisherSnedecor 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 (twotuple 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 uppertail 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 clusterlevel inference.
Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For setspecific probabilities use rft1d.f.p_set
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased critical threshold using the inverse survival function: rft1d.f.isf
Parameters: k – cluster extent (resels)
u – threshold
df – degrees of freedom (twotuple 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: Clusterspecific 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 setlevel 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 clusterspecific probabilities use rft1d.f.p_cluster
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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 (twotuple 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: Setspecific 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 (twotuple 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 (twotuple 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 uppertail 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 clusterlevel inference.
Probability that 1D Gaussian fields with a smoothness of FWHM would produce an upcrossing of extent k when thresholded at u. For setspecific probabilities use rft1d.T2.p_set
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased critical threshold using the inverse survival function: rft1d.T2.isf
Parameters: k – cluster extent (resels)
u – threshold
df – degrees of freedom (twotuple 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: Clusterspecific 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 setlevel 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 clusterspecific probabilities use rft1d.T2.p_cluster
Warning
The threshold u should generally be chosen objectively. One possibility is to calculate the alphabased 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 (twotuple 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: Setspecific 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 (twotuple 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))