stilt.calc_footprint#

stilt.calc_footprint(particles, receptor, grid, *, smooth_factor=1.0, time_integrate=False, transforms=(), name='', directory=None, geometry_hash=None)[source]#

Calculate a footprint from particles, as STILT-R’s calc_footprint does.

The particle transforms are applied first, in order, so the footprint records exactly the transforms it was made with. Near the receptor, particle tracks are interpolated to finer times when particles cross more than a grid cell per step. Each particle’s foot is added to the cell it is in, and each time step is smoothed with a Gaussian kernel that widens with the particles’ spread and age. The sum is divided by the number of particles and binned by hour, unless time_integrate is set.

A grid that goes all the way around the earth (xmin=-180, xmax=180, with cells that fit 360 degrees) is treated as a circle: a particle cloud across 180 degrees is measured as one cloud, and smoothing that spills past the east edge returns at the west edge, and the other way. STILT-R measures the cloud’s longitudes as written, from -180 to 180, and drops what is smoothed past the edge, so on such a grid it smooths a cloud near 180 degrees with a far too wide kernel and loses part of the footprint.

On a projected grid the kernel’s width is worked out in degrees, as on a longitude/latitude grid, and converted to the grid’s units, so the footprint is smoothed as much. STILT-R applies its formula to the projected coordinates and barely smooths a footprint there. The step that decides the early-time interpolation is measured on the projected grid, in its units, so a grid of 100 m cells is interpolated as a 0.001° grid is. STILT-R measures it in degrees and never interpolates on a grid in meters.

Parameters:

  • particles (DataFrame) – Particle table, such as stilt.run_trajectories() returns or sim.particles, with columns particle, age (minutes since release), lon, lat, and foot.

  • receptor (stilt.receptor.Receptor) – Receptor the particles were released from.

  • grid (Grid) – Domain and resolution of the footprint. For a footprint given by a geometry, derive it first: stilt.Mesh.from_spec(geometry).to_grid().

  • smooth_factor (float) – Factor on the width of the Gaussian smoothing kernel. 0 turns smoothing off.

  • time_integrate (bool) – Sum the footprint over time into one layer instead of hourly layers.

  • transforms (Sequence[Any]) – Particle transforms applied before the footprint is calculated, as objects or as the mappings config.yaml takes ({"kind": "pressure_weighting"}).

  • name (str) – Name of the footprint, usually the variant name.

  • directory (str | Path | None) – Where a relative file name in a transform’s settings starts, such as an averaging-kernel table: the project directory.

  • geometry_hash (str | None) – Hash of the geometry the grid was derived for (sim.variant.geometry_hash), recorded with the footprint so aggregating it onto another mesh warns.

Returns:

The footprint, named foot, with dimensions (time, lat, lon) or (time, y, x) on a projected grid. Coordinates are cell centers, and time is the start of each hour. The .stilt accessor has the methods that use it.

Return type:

DataArray

Raises:

  • ImportError – If a transform is a mapping whose kind cannot be imported.

  • EmptyFootprint – If no particle is over the grid, or the table has none.

Examples

>>> grid = stilt.Grid(
...     xmin=-113, xmax=-110.5, ymin=40, ymax=42, xres=0.01, yres=0.01
... )
>>> foot = stilt.calc_footprint(
...     particles, receptor, grid, smooth_factor=0.5
... )