stilt.migration.read_stilt_r#

stilt.migration.read_stilt_r(by_id_dir, smooth_factor=None, error=False)[source]#

Read STILT-R or X-STILT by-id output, one simulation at a time.

Each folder of by_id_dir that holds <id>_traj.rds is a simulation. Its receptor, particles, and footprint come back as PYSTILT’s: a Receptor, a particle table (The Particle Table), and a footprint array, as stilt.read_particles() and stilt.read_footprint() return them. The folders are read in name order, which is time order, and each one only when the loop reaches it.

The receptor’s release points are the ones in the folder’s CONTROL file, the numbers HYSPLIT read, so a point receptor’s id is the folder’s name. Its time is the .rds file’s, which keeps the seconds that CONTROL drops. A receptor with one release point is a PointReceptor, two heights at one place are a ColumnReceptor, and release points at different places, such as X-STILT’s slant columns, are a MultiPointReceptor.

The particle columns get PYSTILT’s names: indx, time, long, lati, and xhgt become particle, age (minutes since release), lon, lat, and release_height. time is then the UTC time of each row, the receptor time plus age. Every other column keeps its STILT-R name, foot_no_hnf_dilution included: the near-field correction STILT-R applied stays as it is.

The footprint is <id>_foot.nc, on the grid its file gives, with layers stamped at the receptor time plus whole hours, as STILT-R stamps them. Its settings hold that grid, time_integrate (true for a backward run with one layer at the receptor time), and smooth_factor. The footprint file does not record smooth_factor. It comes from params.RDS, which STILT-R’s Slurm runs (rslurm) leave in _rslurm_<project>/ beside out/, or else from the smooth_factor argument. params.RDS is used only when its n_hours and numpar are the run’s (CONTROL, and the HYSPLIT settings the .rds saved). Other _foot.nc files in the folder, such as X-STILT’s footprints at other resolutions, are not read.

Parameters:

  • by_id_dir (str | Path) – The by-id folder, such as my_project/out/by-id.

  • smooth_factor (float | None) – The smooth_factor STILT-R made the footprints with, for a project without params.RDS (one run without Slurm). Not needed to read folders without a footprint.

  • error (bool) – Read the second set of particles a run with transport error saved (particle_error), the run with perturbed winds, in place of the first. STILT-R makes no footprint of it, so the footprint is None.

Yields:

  • receptor (Receptor) – Where and when the particles were released.

  • particles (pandas.DataFrame) – One row per particle per output step, as STILT-R saved them.

  • footprint (xarray.DataArray or None) – The footprint, or None when the folder has no <id>_foot.nc: STILT-R made particles only, or no particle reached the grid.

Raises:

  • ImportError – If the rdata package is not installed.

  • FileNotFoundError – If by_id_dir does not exist, no folder in it holds a _traj.rds file, or a folder that does has no CONTROL file.

  • ValueError – When a simulation is read, if its files are not as STILT-R writes them: a _traj.rds without the particle columns or the receptor time, a CONTROL file that cannot be read, or a footprint on a projected grid (only longitude/latitude grids are read) or with layers that are not whole hours from the receptor time. When a footprint is read, if its smooth_factor is not known (no params.RDS and no smooth_factor), if params.RDS disagrees with the run’s n_hours or numpar, or if it records a smooth_factor other than smooth_factor or more than one. With error, if a .rds holds no particle_error.

Warns:

UserWarning – When folders hold a _foot.nc but no _traj.rds. They are skipped: the particles are read from the .rds.

Return type:

Iterator[tuple[TypeAliasForwardRef(‘stilt.receptor.Receptor’), DataFrame, DataArray | None]]

Notes

A run with transport error stores a second set of particles in the same .rds (particle_error), which error reads. The HYSPLIT settings in the .rds (params) are not returned; import_stilt_r() records the settings of each run. X-STILT weights foot by the averaging kernel and pressure weighting after it saves the .rds, so its particles are unweighted and its footprint is weighted.

Examples

>>> for receptor, particles, foot in stilt.migration.read_stilt_r(
...     "out/by-id"
... ):
...     print(receptor.id, len(particles), foot is not None)

A project run on one machine has no params.RDS; give the smooth_factor from its run_stilt.r:

>>> sims = stilt.migration.read_stilt_r(
...     "out/by-id", smooth_factor=1
... )

The particles of the transport-error run:

>>> for receptor, perturbed, _ in stilt.migration.read_stilt_r(
...     "out/by-id", error=True
... ):
...     print(receptor.id, len(perturbed))