RiverForcing

Contents

RiverForcing#

class roms_tools.RiverForcing(*, grid: Grid, start_time: datetime, end_time: datetime, source: dict[str, str | Path | list[str | Path] | bool] | None = None, convert_to_climatology: str = 'if_any_missing', include_bgc: bool = False, bgc_source: dict | Annotated[ConstantsBgcSource | Rivr2oBgcSource, FieldInfo(annotation=NoneType, required=True, discriminator='name')] | None = None, model_reference_date: datetime = datetime.datetime(2000, 1, 1, 0, 0), indices: dict[str, list[tuple[int, int]]] | None = None, coast_snap_buffer_km: float | None = None, domain_edge_buffer: int = 20)#

Represents river forcing input data for ROMS.

Parameters:

  • grid (Grid) – Object representing the grid information.

  • start_time (datetime) – Start time of the desired river forcing data.

  • end_time (datetime) – End time of the desired river forcing data.

  • source (RawDataSource, optional) –

    Dictionary specifying the source of the river forcing data. Keys include:

    • ”name” (str): Name of the data source (e.g., “DAI”).

    • ”path” (Union[str, Path, List[Union[str, Path]]]): The path to the raw data file(s). This can be:

      • A single string (with or without wildcards).

      • A single Path object.

      • A list of strings or Path objects containing multiple files.

    • ”climatology” (bool): Indicates if the data is climatology data. Defaults to False.

    The default is the Dai and Trenberth global river dataset (updated in May 2019), which does not require a path.

  • convert_to_climatology (str, optional) –

    Determines when to compute climatology for river forcing. Options are:

    • ”if_any_missing” (default): Compute climatology for all rivers if any river has missing values.

    • ”never”: Do not compute climatology.

    • ”always”: Compute climatology for all rivers, regardless of missing data.

  • include_bgc (bool, optional) – Whether to include BGC tracers. Defaults to False.

  • bgc_source (dict, optional) –

    Primary river BGC dataset configuration. Only used when include_bgc=True. Keys include:

    • name (str): Registered dataset identifier.

    • path (str, Path, or list): File path(s), when required by the dataset.

    • fill (dict, optional): Secondary dataset with the same key structure. Supplies tracers missing from the primary result, or replaces non-finite primary values.

    If omitted when include_bgc=True, only constant default concentrations are used.

    Concentrations come from the primary dataset’s forcing_concentrations(), then are merged with fill via fill_river_bgc_concentrations.

  • model_reference_date (datetime, optional) – Reference date for the ROMS simulation. Default is January 1, 2000.

  • indices (dict[str, list[tuple[int, int]]], optional) –

    A dictionary specifying the river indices for each river to be included in the river forcing. This parameter is optional. If not provided, the river indices will be automatically determined based on the grid and the source dataset. If provided, it allows for explicit specification of river locations. The dictionary structure consists of river names as keys, and each value is a list of tuples. Each tuple represents a pair of indices corresponding to the eta_rho and xi_rho grid coordinates of the river.

    Example:
    indices = {

    ‘Hvita(Olfusa)’: [(8, 6), (7, 6)], ‘Thjorsa’: [(8, 6)], ‘JkulsFjll’: [(11, 12)], ‘Lagarfljot’: [(9, 13), (8, 13), (10, 13)], ‘Bruara’: [(8, 6)], ‘Svarta’: [(12, 9)]

    }

    In the example, the dictionary provides the river names as keys, and the values are lists of tuples, where each tuple represents the (eta_rho, xi_rho) indices for a river location.

Methods

RiverForcing.from_yaml(filepath)

Create an instance of the RiverForcing class from a YAML file.

RiverForcing.plot([var_name, river_names])

Plots the river flux (e.g., volume, temperature, or salinity) over time for all rivers.

RiverForcing.plot_locations([river_names])

Plots the original and updated river locations on a map projection.

RiverForcing.save(filepath[, format])

Save the river forcing to a NetCDF file.

RiverForcing.to_yaml(filepath)

Export the parameters of the class to a YAML file, including the version of roms-tools.

Attributes

RiverForcing.bgc_source

Primary and fill BGC dataset configuration.

RiverForcing.coast_snap_buffer_km

Maximum distance (in km) between a river mouth and the nearest coastal grid cell.

RiverForcing.convert_to_climatology

Determines when to compute climatology for river forcing.

RiverForcing.domain_edge_buffer

Number of grid cells to include beyond the domain boundary when searching for relevant rivers.

RiverForcing.include_bgc

Whether to include BGC tracers.

RiverForcing.indices

A dictionary of river indices.

RiverForcing.model_reference_date

Reference date for the ROMS simulation.

RiverForcing.source

Dictionary specifying the source of the river forcing data.

RiverForcing.grid

Object representing the grid information.

RiverForcing.start_time

Start time of the desired river forcing data.

RiverForcing.end_time

End time of the desired river forcing data.

RiverForcing.ds

An xarray Dataset containing post-processed variables ready for input into ROMS.

RiverForcing.climatology

Indicates whether the final river forcing is climatological.
Contents