lair.air.stilt

Stochastic Time-Inverted Lagrangian Transport (STILT) Model.

A python implementation of the [R-STILT](jmineau/stilt) model framework.

> Inspired by uataq/air-tracker-stiltctl

Functions

stilt_init(project[, branch, repo])

Initialize STILT project

Classes

BaseConfig(*args, **kwargs)	STILT Configuration
ColumnReceptor(time, longitude, latitude, ...)	Represents a vertical column receptor at a single (x, y) location, defined by a bottom and top height.
Control(*args, **kwargs)	HYSPLIT control parameters.
ErrorParams(*args, **kwargs)
Footprint(simulation_id, receptor, data, ...)	STILT footprint.
FootprintCollection(simulation)
FootprintParams(*args, **kwargs)
Location(geometry)	Represents a spatial location for STILT models, independent of time.
MetParams(*args, **kwargs)
Meteorology(path, format, tres)	Meteorological data files for STILT simulations.
Model(project, **kwargs)
ModelConfig(*args, **kwargs)
ModelParams(*args, **kwargs)
MultiPointReceptor(time, points)	Represents a receptor composed of multiple 3D points, all at the same time.
Output(simulation_id, receptor, data)	Abstract base class for STILT model outputs.
PointReceptor(time, longitude, latitude, height)	Represents a single receptor at a specific 3D point (latitude, longitude, height) in space and time.
Receptor(time, location)
Resolution(*args, **kwargs)
Simulation(config)
SimulationCollection([sims])
SimulationConfig(*args, **kwargs)
SlantReceptor(time, points)	Represents a slanted column receptor, defined by multiple points along the slant.
SystemParams(*args, **kwargs)
Trajectory(simulation_id, receptor, data, ...)	STILT trajectory.
TransportParams(*args, **kwargs)
UserFuncParams(*args, **kwargs)

lair.air.stilt.stilt_init(project: str | Path, branch: str | None = None, repo: str | None = None)

Initialize STILT project

Python implementation of Rscript -e “uataq::stilt_init(‘project’)”

Parameters:

projectstr

Name/path of STILT project. If path is not provided, project will be created in current working directory.

branchstr, optional

Branch of STILT project repo. The default is jmineau.

repostr, optional

URL of STILT project repo. The default is jmineau/stilt.

class lair.air.stilt.Meteorology(path: str | Path, format: str, tres: str | Timedelta)

Meteorological data files for STILT simulations.

__init__(path: str | Path, format: str, tres: str | Timedelta)

class lair.air.stilt.Location(geometry: Geometry)

Represents a spatial location for STILT models, independent of time. Can be used to generate consistent location IDs and create receptors when combined with time.

__init__(geometry: Geometry)

Initialize a location with a shapely geometry.

Parameters:

geometryshapely.Geometry

A geometric object (e.g., Point, MultiPoint, LineString).

property geometry

Location geometry.

property id: str

Generate a unique identifier for this location based on its geometry.

property coords: DataFrame

Returns the location’s coordinates as a pandas DataFrame.

property points: List[Point]

Returns a list of shapely Point objects representing the location’s coordinates.

classmethod from_point(longitude, latitude, height) → Location

Create a Location from a single point.

Parameters:

longitudefloat

Longitude coordinate

latitudefloat

Latitude coordinate

heightfloat

Height above ground level

Returns:

Location

A point location

classmethod from_column(longitude, latitude, bottom, top) → Location

Create a Location representing a vertical column.

Parameters:

longitudefloat

Longitude coordinate

latitudefloat

Latitude coordinate

bottomfloat

Bottom height of column

topfloat

Top height of column

Returns:

Location

A column location

classmethod from_points(points) → Location

Create a Location from multiple points.

Parameters:

pointslist of tuple

List of (lon, lat, height) tuples

Returns:

Location

A multi-point location

class lair.air.stilt.Receptor(time, location: Location)

__init__(time, location: Location)

A receptor that wraps a geometric object (Point, MultiPoint, etc.) and associates it with a timestamp.

Parameters:

timedatetime

The timestamp associated with the receptor.

locationLocation

A location object representing the receptor’s spatial position.

property geometry: Geometry

Receptor geometry.

property timestr: str

Get the time as an ISO formatted string.

Returns:

str

Time in ‘YYYYMMDDHHMM’ format.

static build(time, longitude, latitude, height) → Receptor

Build a receptor object from time, latitude, longitude, and height.

Parameters:

timedatetime

Timestamp of the receptor.

longitudefloat | list[float]

Longitude(s) of the receptor.

latitudefloat | list[float]

Latitude(s) of the receptor.

heightfloat | list[float]

Height(s) above ground level of the receptor.

Returns:

Receptor

The constructed receptor object.

static load_receptors_from_csv(path: str | Path) → List[Receptor]

Load receptors from a CSV file.

class lair.air.stilt.PointReceptor(time, longitude, latitude, height)

Represents a single receptor at a specific 3D point (latitude, longitude, height) in space and time.

__init__(time, longitude, latitude, height)

A receptor that wraps a geometric object (Point, MultiPoint, etc.) and associates it with a timestamp.

Parameters:

timedatetime

The timestamp associated with the receptor.

locationLocation

A location object representing the receptor’s spatial position.

class lair.air.stilt.MultiPointReceptor(time, points)

Represents a receptor composed of multiple 3D points, all at the same time.

__init__(time, points)

A receptor that wraps a geometric object (Point, MultiPoint, etc.) and associates it with a timestamp.

Parameters:

timedatetime

The timestamp associated with the receptor.

locationLocation

A location object representing the receptor’s spatial position.

class lair.air.stilt.ColumnReceptor(time, longitude, latitude, bottom, top)

Represents a vertical column receptor at a single (x, y) location, defined by a bottom and top height.

__init__(time, longitude, latitude, bottom, top)

A receptor that wraps a geometric object (Point, MultiPoint, etc.) and associates it with a timestamp.

Parameters:

timedatetime

The timestamp associated with the receptor.

locationLocation

A location object representing the receptor’s spatial position.

class lair.air.stilt.SlantReceptor(time, points)

Represents a slanted column receptor, defined by multiple points along the slant.

classmethod from_top_and_bottom(time, bottom, top, numpar, weights=None)

Parameters:

timeany

Timestamp.

bottomtuple

(lon, lat, height) tuple for the bottom of the slant.

toptuple

(lon, lat, height) tuple for the top of the slant.

numparint

Number of points along the slant.

weightslist of float, optional

Weights for each point along the slant. Must be the same length as numpar.

class lair.air.stilt.Resolution(*args: Any, **kwargs: Any)

class lair.air.stilt.Control(*args: Any, **kwargs: Any)

HYSPLIT control parameters.

classmethod from_path(path)

Build Control object from HYSPLIT control file.

Returns:

Control

Control object with parsed parameters.

class lair.air.stilt.SystemParams(*args: Any, **kwargs: Any)

class lair.air.stilt.FootprintParams(*args: Any, **kwargs: Any)

property resolutions: List[Resolution] | None

Get the x and y resolutions as a list of tuples.

class lair.air.stilt.MetParams(*args: Any, **kwargs: Any)

class lair.air.stilt.ModelParams(*args: Any, **kwargs: Any)

class lair.air.stilt.TransportParams(*args: Any, **kwargs: Any)

class lair.air.stilt.ErrorParams(*args: Any, **kwargs: Any)

xyerr_params() → dict[str, float | None]

Get the XY error parameters as a dictionary.

zierr_params() → dict[str, float | None]

Get the ZI error parameters as a dictionary.

property winderrtf: int

Determine the winderrtf flag based on the presence of error parameters.

Returns:

int

Wind error control flag.

0 : No error parameters are set 1 : ZI error parameters are set 2 : XY error parameters are set 3 : Both XY and ZI error parameters are set

class lair.air.stilt.UserFuncParams(*args: Any, **kwargs: Any)

class lair.air.stilt.BaseConfig(*args: Any, **kwargs: Any)

STILT Configuration

This class consolidates all configuration parameters for the STILT model, including system settings, footprint parameters, meteorological data, model specifics, transport settings, error handling, and user-defined functions.

classmethod from_path(path: str | Path) → Self

Load STILT configuration from a YAML file.

class lair.air.stilt.SimulationConfig(*args: Any, **kwargs: Any)

classmethod from_path(path: str | Path) → Self

Load STILT configuration from a YAML file.

class lair.air.stilt.ModelConfig(*args: Any, **kwargs: Any)

classmethod from_path(path: str | Path) → Self

Load STILT configuration from a YAML file.

build_simulation_configs() → List[SimulationConfig]

Build a list of SimulationConfig objects, one for each receptor.

class lair.air.stilt.Output(simulation_id, receptor, data)

Abstract base class for STILT model outputs.

__init__(simulation_id, receptor, data)

class lair.air.stilt.Trajectory(simulation_id: str, receptor: Receptor, data: DataFrame, n_hours: int, met_files: list[Path], params: dict)

STILT trajectory.

__init__(simulation_id: str, receptor: Receptor, data: DataFrame, n_hours: int, met_files: list[Path], params: dict)

property id: str

Generate the ID for the trajectory.

property is_error: bool

Determine if the trajectory has errors based on the wind error flag.

class lair.air.stilt.Footprint(simulation_id: str, receptor: Receptor, data: DataArray, xmin: float, xmax: float, ymin: float, ymax: float, xres: float, yres: float, projection: str = '+proj=longlat', smooth_factor: float = 1.0, time_integrate: bool = False)

STILT footprint.

__init__(simulation_id: str, receptor: Receptor, data: DataArray, xmin: float, xmax: float, ymin: float, ymax: float, xres: float, yres: float, projection: str = '+proj=longlat', smooth_factor: float = 1.0, time_integrate: bool = False)

property time_range: tuple[datetime, datetime]

Get time range of footprint data.

Returns:

tuple[pd.Timestamp, pd.Timestamp]

Time range of footprint data.

classmethod from_path(path: str | Path, **kwargs) → Self

Create Footprint object from netCDF file.

Parameters:

pathstr | Path

Path to netCDF file.

**kwargsdict

Additional keyword arguments for xr.open_dataset.

Returns:

Footprint

Footprint object.

static get_res_from_file(file: str | Path) → str

Extract resolution from the file name.

Parameters:

filestr | Path

Path to the footprint netCDF file.

Returns:

str

resolution.

static read_netcdf(file: str | Path, parse_receptor: bool = True, **kwargs) → Dataset

Read netCDF file and return xarray Dataset.

Parameters:

filestr | Path

Path to netCDF file.

parse_receptorbool, optional

Whether to parse receptor coordinates. Default is True.

**kwargsdict

Additional keyword arguments for xr.open_dataset.

Returns:

xr.Dataset

Footprint data as an xarray Dataset.

integrate_over_time(start: datetime | None = None, end: datetime | None = None) → DataArray

Integrate footprint over time.

Parameters:

startdatetime, optional

Start time of integration. The default is None.

enddatetime, optional

End time of integration. The default is None.

Returns:

xr.DataArray

Time-integrated footprint

class lair.air.stilt.FootprintCollection(simulation)

__init__(simulation)

get(resolution: str) → Footprint | None

Get footprint for a specific resolution.

Parameters:

resolutionstr

Resolution string (e.g., ‘1x1’).

Returns:

Footprint | None

Footprint object if available, else None.