stilt.Project.transport_error#

Project.transport_error(sel, error, flux, *, workers=None, **options)[source]#

Return the transport error of each selected simulation’s modeled enhancement.

The same estimate as sim.transport_error, for every selected receptor at once (Lin and Gerbig, 2005; the Transport Error guide). sel is the unperturbed run, and error names the wind-error variant of the same receptors. Every realization of error that has run is averaged, so a receptor whose ensemble is still running gets an estimate from the realizations it has.

Receptors are read and estimated one at a time, in workers threads. Each thread holds one receptor’s particle tables: the unperturbed one and one per realization.

Parameters:

  • sel (Any) – The simulations, as for status(), all of one variant that runs once (no realizations).

  • error (str) – The wind-error variant, such as "hrrr-err".

  • flux (DataArray) – Surface flux field, in µmol m⁻² s⁻¹, the same for every receptor.

  • workers (int | None) – Threads that read and estimate receptors. Defaults to the CPUs this process may use (in a Slurm job, the job’s), at most 8.

  • **options (Any) – Passed to stilt.particles.transport_error(): levels, length_scale, percentile, noise_splits, and background.

Returns:

The selection with six more columns, from TransportError: enhancement, enhancement_perturbed, background, variance, noise, and realizations (how many realizations of error were averaged). A receptor without particles in the selected variant or in any realization of error gets NaN and realizations 0.

Return type:

DataFrame

Raises:

  • KeyError – If the project has no variant named error.

  • ValueError – If the selection holds more or fewer than one variant, that variant is an ensemble, or it is error itself.

Notes

Each receptor’s particles are read whole. A table of 1.4 million rows takes about a second to read, so a selection of hundreds of receptors takes minutes. The per-level tables of TransportError are not kept; get them for one receptor with sim.transport_error.

Examples

>>> sims = project.simulations
>>> wbb = sims[
...     (sims.variant == "hrrr") & (sims.site == "WBB")
... ]
>>> errors = project.transport_error(wbb, "hrrr-err", flux)
>>> errors.groupby(errors.time.dt.month).variance.median()