Feature Composite (rojak.atmosphere.feature_composite)

Composites of observations about atmospheric features, such as lows, in each feature’s own km frame.

Observations, e.g. AMDAR turbulence reports, are composited about every centre of a feature, then compared with controls to show how the feature changes the traffic and the probability of events.

• The counterfactual is what would have been observed if the feature weren’t there. It can’t be observed directly.

• A control is the observations or the field resampled with the feature removed, used to estimate the counterfactual.

The parts of a composite:

• Features find the centres to composite about in time-chunked fields. ExtremaPointFeature finds lows or highs, one centre per extremum.

• Pairing matches observations with the centres at the same time step: LabelledRegionPairing by the region each centre owns, DistancePairing by distance.

• Bins count the pairs in each centre’s km frame: BinSpec.grid() for a 2D (y_km, x_km) grid.

• Controls pair the same centres with observations from another time: ControlDesign.

• Statistics come from the counts after they are computed: impact_statistics() for the traffic ratio, the relative risk and the odds ratio, and bootstrap() for intervals of any of them.

composite_observations_about_features() builds the dask graph and returns lazy counts per time chunk. With return_pairs=True, it also returns the centre and pair tables, whose columns are named by Column:

counts = composite_observations_about_features(
    ExtremaPointFeature(mslp, ExtremaKind.MINIMA, threshold=100_000),
    observations,
    pairing=LabelledRegionPairing(),
    bins=BinSpec.grid(2000, 50),
    controls=[ControlDesign("obs-7D", observation_offset=np.timedelta64(-7, "D"))],
).compute()
impact = impact_statistics(counts, min_count=20)
intervals = bootstrap(counts, impact_statistics, n_samples=500)

To add a new kind of feature or pairing, see rojak.atmosphere.feature_composite.extension.

Functions

bootstrap(counts, statistic, *[, n_samples, ...])	Quantiles of any statistic of the counts, from a block bootstrap over the chunks.
composite_observations_about_features(, ...)	Lazily count the observations about each centre of a feature, and about its controls, per time chunk.
impact_statistics(counts, *[, min_count, ...])	How the feature changes traffic and the probability of each event, relative to the controls.

Classes

BinSpec(*, max_km_extent, spacing_km)	The bins that pairs are counted on, in the km frame of their centre.
Column(*values)	Names of the columns that the feature composite reads from and writes to its per-chunk tables.
ControlDesign(label, *, observation_offset)	How to build one control: a resampling with the feature removed, used to estimate the counterfactual.
DistancePairing(max_distance_km, *[, shape])	Pair each observation with every centre at the same time step within max_distance_km of it.
ExtremaPointFeature(field, kind, *[, ...])	Lows or highs: one point feature per extremum of a field, found by identify_circular_extrema().
LabelledRegionPairing()	Pair each observation with the centre that owns the grid cell nearest to it, if any.