tracmass.load#

tracmass.load(filename=None, *, env=None, dtm=None, reverse=None, columns=None, filters=None, lonlat=False, gcm=None, clean=True, rampup=False)[source]#

Load a trajectory file written by ParticleRecorder.

The file is chosen by, in order of precedence:

  1. filename, if given;

  2. env and/or dtm: the file the settings-driven recorder writes for that environment (default: the active one) and run start date — {output_folder}/{stem}_{forward|reverse}_{dtm}.parquet (also looked for in base_output_dir itself and its {env} / {output_name} sub-folders, where files written with a different use_sub_folder setting end up). Without dtm, the newest file of that environment;

  3. nothing given: the newest .parquet file in base_output_dir or one of its sub-folders, i.e. the most recently written run.

Parameters:

  • filename (str or Path or None, optional) – Path of the file to read.

  • env (str or None, optional) – tracmass.toml environment whose base_output_dir / use_sub_folder / output_name locate the file. Read with settings.from_env; the active environment is not changed.

  • dtm (str or pd.Timestamp or None, optional) – Run start date (the date in the file name).

  • reverse (bool or None, optional) – Run direction. Default None: either, as long as only one matches.

  • columns (list of str or None, optional) – Columns to read. Default: all.

  • filters (dict or list or None, optional) – Rows to read, applied while reading (row groups that cannot match are skipped). A dict {"window": 0} means column == value for each item (a list/tuple/set value means column in value); otherwise pyarrow filters: a list of (column, op, value) tuples (ANDed), or a list of such lists (ORed). Filter columns need not be in columns. Combined (AND) with the clean row filter. Default: all rows.

  • lonlat (bool, optional) – Add lon / lat columns (degrees), converted from x / y with the GCM adapter’s xy_to_lonlat (glorys, ecco2). x / y are read for this even if not in columns. Default False.

  • gcm (str or None, optional) – Adapter for lonlat. Default: gcm in the file’s metadata, else [env.gcm] name of env, of the env in the file’s metadata, or of the active environment. The file’s gcm_product (e.g. "glorys12v1") selects which of the adapter’s grids is used, whatever product is currently configured.

  • clean (bool, optional) – Return only the snapshot rows (event_type == "snapshot"; no deactivation events) and only the columns id, x, y, dtm (plus lon, lat with lonlat). An explicit columns takes precedence over the column part. Default True; clean=False returns every row and column.

  • rampup (bool, optional) – With clean, also keep the event_type == "rampup" rows (the extra saves inside the first windows of a run with rampup_windows), and add the event_type column (unless columns is given) to tell them from the window snapshots. The time between consecutive saves is df.attrs["tracmass.run"] ["save_dt_seconds"]. Default False.

Returns:

pd.DataFrame – The trajectory rows. df.attrs["path"] is the file read and df.attrs["tracmass.run"] its run metadata ({} if none; see tracmass.runsetup.run_metadata() for the keys).

Raises:

  • FileNotFoundError – If no matching file exists.

  • TypeError – If filename is given together with env / dtm.

  • ValueError – If dtm matches both a forward and a reverse run and reverse is not given, or lonlat is set and no GCM with xy_to_lonlat can be found.

Return type:

DataFrame

Examples

>>> df = tracmass.load()                          # newest run, id/x/y/dtm
>>> df = tracmass.load(clean=False)               # every row and column
>>> df = tracmass.load(env="omi_falkor")          # newest omi_falkor run
>>> df = tracmass.load(env="omi_falkor", dtm="2007-06-01")
>>> df = tracmass.load("traj.parquet", columns=["id", "dtm", "x", "y"])
>>> df = tracmass.load(filters={"window": 0})     # first window only
>>> df = tracmass.load(filters=[("window", "<", 10), ("reason", "==", 2)])
>>> df = tracmass.load(env="omi_falkor", lonlat=True)   # + lon, lat columns
>>> df = tracmass.load(lonlat=True)  # id, x, y, dtm, lon, lat
>>> df = tracmass.load(rampup=True)  # + ramp-up saves, event_type column