stilt.particles.background#

stilt.particles.background(particles, field, *, transforms=(), receptor=None, directory=None)[source]#

Return the background mole fraction at a receptor.

The background is the field at each particle’s endpoint, averaged over the particles with the footprint’s weights.

Parameters:

  • particles (DataFrame) – The simulation’s particle table (sim.particles).

  • field (DataArray | Series) – The background field, or one value per particle that you sampled yourself, as a Series indexed by particle. For example, lair’s CarbonTracker.sample on sim.particles.stilt.endpoints(). A field is sampled at each particle’s endpoint, the row farthest in time from release (particles.stilt.endpoints()). Its vertical dimension must be named after the particle column it is matched against: pres for pressure in hPa, zagl for height above ground in meters, or a column you add, such as height above sea level from zagl + zsfc. Rename it with, for example, field.rename(level="pres"). A field with a time dimension is sampled at the endpoint’s time.

  • transforms (Sequence[Any]) – The footprint’s particle transforms (sim.variant.footprint.transforms), so the background is weighted like the footprint and adds to its enhancement. A tower receptor has none.

  • receptor (stilt.receptor.Receptor | None) – The receptor (sim.receptor), for the transforms. An averaging kernel read from a table needs it, and pressure weighting reads its altitude_ref.

  • directory (str | Path | None) – Where a kernel table’s relative path starts (project.directory).

Return type:

Background

Notes

Without transforms the value is the mean over particles. With pressure weighting the weights sum to the fraction of the atmosphere’s mass inside the column, (p_sfc - p_top) / p_sfc, the same fraction the enhancement covers. Add the part of the column above its top from the same field.