easysnowdata.stations.clients.RIHMIClient#

class easysnowdata.stations.clients.RIHMIClient(data_dir: str | PathLike | None = None, use_nsidc: bool = True, cache_dir: str | PathLike | None = None, base_url: str = 'https://noaadata.apps.nsidc.org/NOAA/G01170', timeout: int = 300, max_retries: int = 3, backoff: int = 4, session: Session | None = None, aisori_username: str | None = None, aisori_password: str | None = None)[source]#

Bases: object

Client for RIHMI-WDC route snow surveys and daily snow cover.

Route surveys (interval="periodic") come from АИСОРИ-М exports (scripted with source="aisori", or local files) and/or the public NSIDC G01170 archive (1966–1996, no credentials). Daily snow cover (interval="daily") comes only from АИСОРИ-М.

Parameters:

  • data_dir (str or Path, optional) – Folder of АИСОРИ-М exports, searched recursively for the downloaded *.zip files and for extracted *.txt/*.dat/*.csv data files (an export’s fld*/statlist* files are used, not read as data). See the module docstring for the export steps.

  • use_nsidc (bool) – Include NSIDC G01170 stations and route-survey data (default True).

  • cache_dir (str or Path, optional) – Where the G01170 tar files (~50 MB) and scripted АИСОРИ-М exports are cached. Defaults to easysnowdata.config.cache_dir("stations", "rihmi").

  • base_url (str) – Root of the NSIDC G01170 archive. Override for a mirror.

  • timeout (int) – HTTP settings for the NSIDC downloads.

  • max_retries (int) – HTTP settings for the NSIDC downloads.

  • backoff (int) – HTTP settings for the NSIDC downloads.

  • session (requests.Session, optional) – Pre-configured session (NSIDC downloads only; each АИСОРИ-М export opens its own).

  • aisori_username (str, optional) – АИСОРИ-М account for source="aisori". Default: the aisori auth provider (AISORI_USERNAME / AISORI_PASSWORD).

  • aisori_password (str, optional) – АИСОРИ-М account for source="aisori". Default: the aisori auth provider (AISORI_USERNAME / AISORI_PASSWORD).

fetch_aisori(station_ids: list[str] | str, interval: str = 'periodic', first_year: int = 1966, last_year: int | None = None, refresh: bool = False) → Path[source]#

Log in to АИСОРИ-М, export stations and years, return the cached zip.

Parameters:

  • station_ids (list[str] or str) – WMO indexes. Stations the АИСОРИ-М source does not offer are skipped with a warning; if none is offered, RIHMIError.

  • interval ({"periodic", "daily"}) – Route surveys (SNMAR) or daily snow cover (SNOW).

  • first_year (int) – Inclusive year range (last_year defaults to this year).

  • last_year (int) – Inclusive year range (last_year defaults to this year).

  • refresh (bool) – Re-run the export even if a cached copy exists. A cached export whose range reaches the current year is re-run after 7 days.

Returns:

Path – The export zip, readable with read_aisori_export().

get_all_stations(active_only: bool = False, bbox: tuple[float, float, float, float] | None = None) → list[dict][source]#

Every station in the RIHMI route-survey and snow-cover catalogues and (when use_nsidc) NSIDC G01170’s station.loc.

Parameters:

  • active_only (bool) – Keep only catalogue-"Active" stations (see the module docstring).

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat).

Returns:

list[dict] – station_id (WMO index), name (Cyrillic from RIHMI, else NSIDC’s Latin), name_latin, latitude, longitude, elevation_m, status, wmo_id, operator, measurement_method, has_swe, has_snwd, catalogue membership flags, start years, public_period, login_period, note and station_url.

Raises:

RIHMIError – If NSIDC’s station.loc cannot be downloaded.

get_metadata(station_id: str) → dict[source]#

Station dict plus data_variables.

Parameters:

station_id (str) – WMO index, e.g. "22113" (zero-padded to 5 digits).

Returns:

dict – The get_all_stations() dict plus data_variables, one entry per variable with name, type, interval, units (emitted), description, notes, begin_date, end_date and n_obs.

Notes

Route-survey variables are listed when the station is in the RIHMI route catalogue or NSIDC (NSIDC-only stations list just the fields NSIDC carries); snow-cover variables when it is in the snow-cover catalogue. begin_date is the catalogue start year (route catalogue: start of the dataset at that station; snow-cover catalogue: start of observations at the station), end_date is 1996-12-31 for NSIDC-only stations and None otherwise (ongoing behind a login). n_obs is None (unknown without reading the data).

Raises:

RIHMIError – If the station is in none of the catalogues.

get_data(station_ids: list[str] | str | None = None, variables: list[str] | str | None = None, bbox: tuple[float, float, float, float] | None = None, begin_date: str | date | None = None, end_date: str | date | None = None, interval: str = 'periodic', include_flags: bool = False, route_types: list[str] | str | None = None, files: Iterable[str | PathLike] | str | PathLike | None = None, source: str = 'auto') → list[dict][source]#

Standardized data fetch — a flat list of observation records.

Parameters:

  • station_ids (list[str] or str or None) – WMO indexes ("22113"). Required unless bbox is given.

  • variables (list[str] or str or None) – Native names ("SWE", "HS_MEAN", "H"…) or standardized types ("swe", "snwd", "density", "other") valid for the chosen interval. None = snow only: SWE + HS_MEAN (periodic) or H (daily).

  • bbox (tuple, optional) – (min_lon, min_lat, max_lon, max_lat).

  • begin_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

  • end_date (str or date, optional) – Inclusive YYYY-MM-DD bounds.

  • interval ({"periodic", "daily"}) – "periodic" = route snow surveys; "daily" = station snow cover (local exports only).

  • include_flags (bool) – Add flag (see DATA_FLAGS).

  • route_types (list[str] or str, optional) – Keep only these routes ("field", "forest", "ravine", "unknown"). Periodic only.

  • files (path or list of paths, optional) – АИСОРИ-М export files; overrides data_dir for this call.

  • source ({"auto", "nsidc", "files", "aisori"}) – "auto" merges local exports (preferred) with NSIDC; "nsidc" / "files" restrict to one. "aisori" logs in to АИСОРИ-М and exports the stations and the years of begin_date–end_date (default 1966 to this year) with fetch_aisori(); it needs the aisori credentials.

Returns:

list[dict] – {station_id, date, variable, type, value, units, interval, route_type, source} (+ flag). NSIDC downloads the ~50 MB G01170 syn.tar files once into the cache.

Raises:

  • ValueError – If neither station_ids nor bbox is provided.

  • RIHMIError – Unknown variable, interval, route type or source; daily data requested with no АИСОРИ-М export; download or export failure.

Example

>>> client = RIHMIClient()
>>> records = client.get_data(
...     station_ids="22113",
...     variables=["swe"],
...     begin_date="1985-01-01",
...     end_date="1985-04-30",
... )
>>> records[0]["units"], records[0]["route_type"]
('cm', 'field')

Examples using easysnowdata.stations.clients.RIHMIClient#

Russian route snow surveys (RIHMI-WDC)

Russian route snow surveys (RIHMI-WDC)

Recent Russian snow surveys and snow cover (RIHMI АИСОРИ-М)

Recent Russian snow surveys and snow cover (RIHMI АИСОРИ-М)