stilt.migration.import_stilt_r#

stilt.migration.import_stilt_r(by_id_dir, output_dir, version, *, name='stilt-r', smooth_factor=None, met_path=None)[source]#

Write the runs of a STILT-R or X-STILT by-id folder into a PYSTILT output directory.

Each run’s particles and footprint, as read_stilt_r() reads them, go to the folders of a variant with model: stilt-r (StiltRModel). A project whose config.yaml has that variant reads them as its own results: project.status, project.particles, project.footprints, and project.jacobian. The import prints the variant and its met, to paste into config.yaml, and returns the receptors, for receptors.csv.

Every folder of an output directory is named by the hash of its settings, and an imported run’s settings are only what STILT-R’s files record, never a default standing in for a value they do not give:

  • HYSPLIT’s settings from each run’s SETUP.CFG; n_hours, w_option, z_top, and emisshrs from its CONTROL; and ziscale from its ZICONTROL file when SETUP.CFG says STILT-R wrote one (ZICONTROLTF), else 1 (no scaling).

  • hnf_plume from the particles: STILT-R’s near-field correction adds the foot_no_hnf_dilution column.

  • The met: the directory the CONTROL files name, as they name it. Each run’s met files are recorded in its particle file, and need not exist any more.

  • The footprint’s grid and time_integrate from <id>_foot.nc, and its smooth_factor from params.RDS or smooth_factor, as read_stilt_r() reads them.

  • The STILT-R version, which no file records: version.

The second set of particles of a run with transport error (particle_error) goes to the folder of a second variant, <name>-err, with the wind and mixed-layer error settings STILT-R saved with it (particle_error_params). It has particles only: STILT-R makes no footprint of them. A run whose stilt.log says that no particle reached the footprint grid gets an empty footprint, as a PYSTILT run would. Results already in the output directory are kept, so an import can be run again after more STILT-R runs finish.

Parameters:

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

  • output_dir (str | Path) – The output directory, as output: in config.yaml names it.

  • version (str) – The STILT-R version that made the runs, such as the commit of uataq/stilt the project was made from (git rev-parse --short HEAD in a STILT-R project folder).

  • name (str) – Name of the variant and of its met. The transport-error variant is <name>-err.

  • smooth_factor (float | None) – The smooth_factor STILT-R made the footprints with, for a project without params.RDS, as for read_stilt_r().

  • met_path (str | None) – The met directory to record when the CONTROL files name more than one, such as STILT-R’s met_path with its files in yearly folders. Every directory they name must be in it.

Returns:

The receptors of the runs, in folder order, for stilt.Project.add_receptors().

Return type:

list[stilt.receptor.Receptor]

Raises:

  • ImportError – If the rdata package is not installed.

  • FileNotFoundError – As read_stilt_r() raises it, or if a run has no SETUP.CFG or no ZICONTROL file that its SETUP.CFG says it has.

  • ValueError – As read_stilt_r() raises it, or if name is not a variant name; if two runs were made with different settings, which is said by name (import each set from a by-id folder of its own, under a name of its own); if SETUP.CFG holds a setting PYSTILT does not have, or KMSL other than 0 (heights above sea level); if the CONTROL files name several met directories and met_path is not given or does not hold them all; or if SETUP.CFG and the .rds disagree on whether a run had transport error.

Examples

>>> receptors = stilt.migration.import_stilt_r(
...     "my_project/out/by-id", "output", version="1d936c1"
... )
mets:
  stilt-r:
    met_path: /data/hrrr
variants:
  stilt-r:
    model: stilt-r
    met: stilt-r
    version: 1d936c1
    capemin: -1
    ...
>>> project = stilt.Project.init("my_project_py", receptors, output="output", ...)