# 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. L — labeled upcrossings (array of integers) n — number of upcrossings ```>>> 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 FWHM — the estimated FWHM ```>>> 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: Returns: 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) resels — (r0, r1): 0D and 1D resel counts, respectively 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. All RFT expectations stem directly from these resel counts. 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] ```>>> 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) ``` ```>>> 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) fwhm — field FWHM ```>>> 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 ``` 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) fwhm — field FWHM ```>>> resels = (2, 6.9) >>> b = np.zeros(101) >>> b[25:55] = 1 >>> w = rft1d.geom.resels2fwhm_masked(resels, b) #yields 10.0 ``` 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 ``` 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) nNodes — number of field nodes ```>>> 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 ``` 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 ``` 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 calc — a ClusterMetricCalculator instance ```>>> 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 k — list of upcrossing extents, or [0] if no upcrossings ```>>> 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 zmin — list of upcrossing minima; [0] if no upcrossings ```>>> 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 kmax — maximum upcrossing extent (unit: nodes) ```>>> 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 kmean — mean upcrossing extent (unit: nodes) ```>>> 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 nNodes — number of nodes which survive the threshold u ```>>> 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 nResels — number of resels which survive the threshold u ```>>> 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 c — number of upcrossings ```>>> 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 c — number of upcrossings whose extents equal or exceed k ```>>> 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 k — total extent of the excursion set u ```>>> nResels = calc.total_excursion_set_extent(y, 0.5) ``` 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.