rft1d.geom¶
Geometry module
This module contains functions for computing various geomtric characteristics of 1D fields and upcrossings.
Basic geometry functions:¶
bwlabel¶
-
rft1d.geom.
bwlabel
(b, merge_wrapped=False)¶ Label clusters in a binary field b. This function yields the same output as scipy.ndimage.measurements.label but is much faster for 1D fields. If merge_wrapped
Parameters: b — a binary field
merge_wrapped — if True, boundary upcrossings will be merged into a single cluster.
Returns: L — labeled upcrossings (array of integers)
n — number of upcrossings
Example: >>> y = rft1d.random.randn1d(1, 101, 10.0) >>> b = y > 2.0 >>> L,n = rft1d.geom.bwlabel(b)
estimate_fwhm¶
-
rft1d.geom.
estimate_fwhm
(R)¶ Estimate field smoothness (FWHM) from a set of random fields or a set of residuals.
Parameters: R — a set of random fields, or a set of residuals
Returns: FWHM — the estimated FWHM
Example: >>> FWHM = 12.5 >>> y = rft1d.random.randn1d(8, 101, FWHM) >>> w = rft1d.geom.estimate_fwhm(y) #should be close to 12.5
Note
The estimated FWHM will differ from the specified FWHM (just like sample means differ from the population mean). This function implements an unbiased estimate of the FWHM, so the average of many FWHM estimates is expected to converge to the specified value.
Field geometry (resel counts)¶
resel_counts¶
-
rft1d.geom.
resel_counts
(R, fwhm=1, element_based=False)¶ Resolution element (resel) counts.
This function assembles resel counts, either from a set of residuals or from a binary mask. If using a binary mask, True represents regions which are masked out.
Parameters: R — a set of random fields, a set of residuals, or a binary field mask
fwhm — the true or estimated FWHM
element_based — element-based sampling (default: node-based sampling)
Returns: resels — (r0, r1): 0D and 1D resel counts, respectively
Note: The resel counts define the field on which the random process occurs. The first count (r0) is the Hadwiger characteristic, which specifies the number of unbroken field segments. An unbroken field has r0 = 1. The second count (r1) is the field size divided by the FWHM.
Important: All RFT expectations stem directly from these resel counts.
Important cases: - Node-based sampling (default), unbroken field with Q nodes — the field size is (Q-1) and resels = [1, (Q-1)/FWHM]
- Element-based sampling, unbroken field, Q elements — the field size is Q and resels = [1, Q/FWHM]
- Node-based sampling (default), broken field with S segements and Q nodes — the field size is (Q-S) and resels = [S, (Q-S)/FWHM]
- Element-based sampling, broken field with S segements and Q elements — the field size is Q and resels = [S, Q/FWHM]
Examples (unbroken field): >>> import numpy as np >>> b = np.zeros(101) #no masked regions >>> resels = rft1d.geom.resel_counts(b, fwhm=10.0) #yields(1,10) >>> resels = rft1d.geom.resel_counts(b, fwhm=10.0, element_based=True) #yields(1,10.1)
Examples (broken field): >>> b = np.zeros(101) >>> b[25:55] = 1 >>> resels = rft1d.geom.resel_counts(b, fwhm=10.0) #yields(2,6.9) >>> resels = rft1d.geom.resel_counts(b, fwhm=10.0, element_based=True) #yields(2,7.1)
resel conversion functions¶
-
rft1d.geom.
resels2fwhm
(resels, nNodes, element_based=False)¶ Get the FWHM from resel counts based on the number of field nodes.
Parameters: resels — resel counts
nNodes — number of field nodes (in broken fields: number of unbroken nodes)
element_based — element-based sampling (default: node-based sampling)
Returns: fwhm — field FWHM
Example: >>> resels = (1, 10.0) >>> w = rft1d.geom.resels2fwhm(resels, 101) #yields 10.0 >>> resels = (2, 6.9) >>> w = rft1d.geom.resels2fwhm(resels, 71) #yields 10.0
Note: See rft1d.geom.resel_counts for details regarding the keyword “element_based”** and node-based vs. element-based sampling.
-
rft1d.geom.
resels2fwhm_masked
(resels, mask, element_based=False)¶ Get the FWHM from resel counts based on a binary field mask
Parameters: resels — resel counts
mask — binary field mask
element_based — element-based sampling (default: node-based sampling)
Returns: fwhm — field FWHM
Example: >>> resels = (2, 6.9) >>> b = np.zeros(101) >>> b[25:55] = 1 >>> w = rft1d.geom.resels2fwhm_masked(resels, b) #yields 10.0
Note: See rft1d.geom.resel_counts for details regarding the keyword “element_based”** and node-based vs. element-based sampling.
-
rft1d.geom.
resels2nelements
(resels, fwhm)¶ Get the field size from resel counts based on the FWHM (element-based sampling).
Example: >>> resels = (1, 10.0) >>> nNodes = rft1d.geom.resels2nelements(resels, 10.0) #yields 100 >>> resels = (2, 6.9) >>> nNodes = rft1d.geom.resels2nelements(resels, 10.0) #yields 69
Note: See rft1d.geom.resel_counts for details regarding node-based vs. element-based sampling.
-
rft1d.geom.
resels2nnodes
(resels, fwhm)¶ Get the number of field nodes from resel counts based on the FWHM
Parameters: resels — resel counts
fwhm — actual or estimated FWHM*element_based* — element-based sampling (default: node-based sampling)
Returns: nNodes — number of field nodes
Example: >>> resels = (1, 10.0) >>> nNodes = rft1d.geom.resels2nnodes(resels, 10.0) #yields 101 >>> resels = (2, 6.9) >>> nNodes = rft1d.geom.resels2nnodes(resels, 10.0) #yields 71
Note: See rft1d.geom.resel_counts for details regarding node-based vs. element-based sampling.
-
rft1d.geom.
resels2fieldsize
(resels, fwhm, element_based=False)¶ Get the field size from resel counts based on the FWHM. Equivalent to rft1d.geom.resels2nnodes minus the number of unbroken field segments.
Example: >>> resels = (1, 10.0) >>> nNodes = rft1d.geom.resels2fieldsize(resels, 10.0) #yields 100 >>> resels = (2, 6.9) >>> nNodes = rft1d.geom.resels2fieldsize(resels, 10.0) #yields 69
Note: See rft1d.geom.resel_counts for details regarding the keyword “element_based”** and node-based vs. element-based sampling.
Upcrossing metric calculations¶
rft1d.geom.ClusterMetricCalculator¶
-
class
rft1d.geom.
ClusterMetricCalculator
¶ A class for computing various geometric characteristics of the excursion set including number of upcrossings, upcrossing (cluster) extents, etc.
Parameters: None
Returns: calc — a ClusterMetricCalculator instance
Example: >>> y = rft1d.random.randn1d(1, 101, 15.0) >>> calc = rft1d.geom.ClusterMetricCalculator() >>> k = calc.cluster_extents(y, 0.5) #cluster extents when thresholded at 0.5
-
cluster_extents
(y, u, interp=True, wrap=False)¶ Upcrossing extents (units: nodes).
Parameters: y — a 1D field
u — threshold height
interp — interpolate to threshold u
wrap — wrap upcrossings from the end to the start of the field
Returns: k — list of upcrossing extents, or [0] if no upcrossings
Example: >>> k = calc.cluster_extents(y, 0.0) #cluster extents when thresholded at 0.0
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-
cluster_minima
(y, u, interp=True)¶ Minimum field height inside each upcrossing.
Parameters: y — a 1D field
u — threshold height
interp — interpolate to threshold u
Returns: zmin — list of upcrossing minima; [0] if no upcrossings
Example: >>> k = calc.cluster_minima(y, 0.0)
Warning
If interp is True, the minima are all u.
Danger
If u is zero and interp is True the user may be unable to distinguish between two cases: (i) no upcrossings and (ii) one upcrossing with a minimum of zero. Most thresholds we’re interested in are much higher than zero, so this buggy behavior is not deemed serious. To check the number of upcrossings use the nMaxima method.
-
max_cluster_extent
(y, u, interp=True, wrap=False)¶ Maximum upcrossing extent
Parameters: y — a 1D field
u — threshold height
interp — interpolate to threshold u
wrap — wrap upcrossings from the end to the start of the field
Returns: kmax — maximum upcrossing extent (unit: nodes)
Example: >>> k = calc.max_cluster_extent(y, 0.2)
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-
mean_cluster_extent
(y, u, interp=True, wrap=False)¶ Mean upcrossing extent
Parameters: y — a 1D field
u — threshold height
interp — interpolate to threshold u
wrap — wrap upcrossings from the end to the start of the field
Returns: kmean — mean upcrossing extent (unit: nodes)
Example: >>> k = calc.mean_cluster_extent(y, 0.5)
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-
nMaxima
(y, u)¶ Number of maxima. Equivalent to nUpcrossings.
-
nSuprathresholdNodes
(y, u)¶ Number of nodes in the excursion set.
Parameters: y — a 1D field
u — threshold height
Returns: nNodes — number of nodes which survive the threshold u
Example: >>> nNodes = calc.nSuprathresholdNodes(y, 0.5)
Warning
This returns simply the number of nodes, which is not equivelent to extent. To compute the total extent you must subtract the number of upcrossings from this value. Otherwise use rft1d.geom.nSuprathresholdResels or rft1d.geom.total_excursion_set_extent.
-
nSuprathresholdResels
(y, u, fwhm=1.0, interp=True)¶ Number of resels in the excursion set.
Parameters: y — a 1D field
u — threshold height
fwhm — actual or estimated FWHM
interp — interpolate to threshold u
Returns: nResels — number of resels which survive the threshold u
Example: >>> nResels = calc.nSuprathresholdResels(y, 0.5)
Warning
This is a length measure, so is similar to (nSuprathresholdNodes minus nUpcrossings) divided by the FWHM, with the exception that extents can be interpolated to u.
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-
nUpcrossings
(y, u)¶ Number of upcrossings.
Parameters: y — a 1D field
u — threshold height
Returns: c — number of upcrossings
Example: >>> c = calc.nUpcrossings(y, 0.5)
-
nUpcrossingsByExtent
(y, u, k, interp=True, wrap=False)¶ Number of upcrossings at threshold extent k.
Parameters: y — a 1D field
u — threshold height
k — cluster extent threshold (unit: nodes)
interp — interpolate to threshold u
wrap — wrap upcrossings from the end to the start of the field
Returns: c — number of upcrossings whose extents equal or exceed k
Example: >>> c = calc.nUpcrossingsByExtent(y, 3.5, 5.0)
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-
total_excursion_set_extent
(y, u, interp=True)¶ Total extent of the excursion set.
Parameters: y — a 1D field
u — threshold height
fwhm — actual or estimated FWHM
interp — interpolate to threshold u
Returns: k — total extent of the excursion set u
Example: >>> nResels = calc.total_excursion_set_extent(y, 0.5)
Note: This is a length measure, so is similar to nSuprathresholdNodes minus nUpcrossings, with the exception that extents can be interpolated to u.
Danger
Setting interp to False is faster, but it will cause disagreements between node-based and element-based sampling. If the upcrossing is large this difference is negligible, but for small upcrossing there may be strange results (e.g. upcrossing with an extent of zero). Recommendation: always interpolate.
-