stilt.observations.transport_error#

stilt.observations.transport_error(particles, error_particles, flux, *, transforms=(), context=None, levels=20, length_scale=356.0, percentile=1.0, regression=False, noise_splits=16, background=None)[source]#

Transport-error variance of the modelled enhancement (Lin and Gerbig, 2005).

Parameters:

  • particles (DataFrame) – The simulation’s main particle table (sim.trajectories.data) and one or more error-trajectory tables: sim.error_trajectories.data for a single realization, or [t.data for t in sim.all_error_trajectories] for the ensemble a run with error_realizations > 1 produced.

  • error_particles (DataFrame | Sequence[DataFrame]) – The simulation’s main particle table (sim.trajectories.data) and one or more error-trajectory tables: sim.error_trajectories.data for a single realization, or [t.data for t in sim.all_error_trajectories] for the ensemble a run with error_realizations > 1 produced.

  • flux (DataArray) – Surface flux field (see stilt.flux).

  • transforms (Sequence[Any]) – The footprint’s particle transforms and the context to apply them with (config.transforms and sim.transform_context(name)), so the error is weighted the way the footprint is (averaging kernel, pressure weighting, lifetime decay). Applied to both tables.

  • context (Optional[TransformContext]) – The footprint’s particle transforms and the context to apply them with (config.transforms and sim.transform_context(name)), so the error is weighted the way the footprint is (averaging kernel, pressure weighting, lifetime decay). Applied to both tables.

  • levels (int | Sequence[float]) – Release-height levels to compute statistics on: a number of equal-width bins between the lowest and highest release height, or explicit bin edges. Particles with at most levels distinct release heights (a multipoint receptor) use those heights directly. A point receptor is one level.

  • length_scale (float | None) – Vertical e-folding length of the error correlation between levels, in metres (X-STILT’s 356 m); None treats levels as uncorrelated. Irrelevant for a point receptor.

  • percentile (float) – Per level, drop particles above this quantile of the enhancement before taking the variance. 1.0 keeps every particle (Lin and Gerbig); X-STILT uses 0.99 to tame a few particles that cross a point source. Means always use every particle.

  • regression (bool) – Use X-STILT’s regression scaling of the per-level variance differences (see _scale_dvar()) instead of the signed differences. Biased upward under sampling noise; for reproducing X-STILT results.

  • noise_splits (int) – Random half-splits of the unperturbed particles used to estimate noise; 0 skips it.

  • background (Optional[DataArray]) – A background field to sample at each particle’s endpoint (see background()). Wind errors move the endpoints as well as the surface contact, so with a field the statistics are of the modelled mole fraction, enhancement plus background per particle, as X-STILT computes them.

Return type:

TransportError

Notes

Per level l with n_l of N particles, dvar_l is the change in the variance of the per-particle enhancement under the perturbation, s_l = sign(dvar_l) sqrt(|dvar_l|), and the column variance is Σ_ij w_i w_j s_i s_j exp(-|h_i - h_j| / L) with w_l = n_l / N and h the level heights; for one level it is dvar itself. Because the transforms are applied to the particles first, the level statistics are already in column-weighted units and the weights are the particle counts.

With several error realizations, each level’s mean_err and var_err are averaged over them before dvar is formed, so the perturbed side’s sampling noise falls as 1/sqrt(N). The unperturbed side is the same particles in every realization, so its noise does not fall: with N realizations the null spread of variance is sqrt((1 + 1/N) / 2) times the single-realization noise, which tends to 1/sqrt(2) and not to zero. noise carries that factor. Running more realizations therefore buys at most a sqrt(2) tighter estimate; it does not turn an unresolved case into a resolved one.

The signal is the extra spread the perturbation adds, so it is small when the wind error decorrelates quickly (HYSPLIT decorrelates it with the distance a particle travels as well as with time) and when turbulent dispersion already spreads the particles widely, as in a convective afternoon. Judge a single value against noise; over many receptors, aggregate the signed variance with a median rather than clipping each one at zero.