pycontrails.datalib.gruan.GRUAN

class pycontrails.datalib.gruan.GRUAN(product, site, cachestore=<object object>)

Bases: object

Access GRUAN data over anonymous FTP.

GRUAN is the Global Climate Observing System Reference Upper-Air Network. It provides high-quality measurements of atmospheric variables from ground to stratosphere through a global network of radiosonde stations.

Added in version 0.59.0.

Parameters:

  • product (str) – GRUAN data product. See AVAILABLE for available products. These currently include: - RS92-GDP.2 - RS92-GDP.1 - RS92-PROFILE-BETA.2 - RS92-PROFILE-BETA.3 - RS41-EDT.1 - RS-11G-GDP.1

  • site (str) – GRUAN station identifier. See AVAILABLE for available sites for each product.

  • cachestore (cache.CacheStore | None, optional) – Cache store to use for downloaded files. If not provided, a disk cache store will be created in the user cache directory under gruan/. Set to None to disable caching.

Notes

The FTP files have the following hierarchy:

/pub/data/gruan/processing/level2/
    {product-root}/
        version-{NNN}/
            {SITE}/
                {YYYY}/
                    <filename>.nc

  • {product-root} is the product name without the trailing version integer (e.g. RS92-GDP)

  • version-{NNN} zero-pads to three digits (suffix .2 -> version-002)

  • {SITE} is the station code (e.g. LIN)

  • {YYYY} is launch year

  • Filenames encode launch time and revision (parsed by extract_gruan_time())

Discovery helpers methods:

Typical workflow:

  1. Inspect AVAILABLE (fast) or call available_sites() (live)

  2. Instantiate GRUAN(product, site)

  3. Call years()

  4. Call list_files(year)

  5. Call get(filename) for an xarray.Dataset

__init__(product, site, cachestore=<object object>)

Methods

__init__(product, site[, cachestore])

available_sites()

Get a list of available GRUAN sites for each supported product.

get(filename)

Download a GRUAN dataset by filename.

list_files([year])

List available files for a given year.

years()

Get a list of available years for the selected product and site.

Attributes

cachestore

product

site

AVAILABLE

base_path_product

Get the base path for GRUAN data product on the FTP server.

base_path_site

Get the base path for GRUAN data site on the FTP server.
AVAILABLE = {'RS-11G-GDP.1': ['SYO', 'TAT', 'NYA', 'LIN'], 'RS41-EDT.1': ['LIN', 'POT', 'SNG'], 'RS92-GDP.1': ['BOU', 'CAB', 'LIN', 'PAY', 'POT', 'SOD', 'TAT'], 'RS92-GDP.2': ['BAR', 'BEL', 'BOU', 'CAB', 'DAR', 'GRA', 'LAU', 'LIN', 'MAN', 'NAU', 'NYA', 'PAY', 'POT', 'REU', 'SGP', 'SOD', 'TAT', 'TEN', 'GVN'], 'RS92-PROFILE-BETA.2': ['BOU', 'CAB', 'LIN', 'POT', 'SOD', 'TAT'], 'RS92-PROFILE-BETA.3': ['BOU', 'CAB', 'LIN', 'POT', 'SOD', 'TAT']}
static available_sites()

Get a list of available GRUAN sites for each supported product.

The GRUAN.AVAILABLE is a hardcoded snapshot of this data. The data returned by this function does not change frequently, so it is cached for efficiency.

Returns:

dict[str, list[str]] – Mapping of product names to lists of available site identifiers.

property base_path_product

Get the base path for GRUAN data product on the FTP server.

property base_path_site

Get the base path for GRUAN data site on the FTP server.

cachestore
get(filename)

Download a GRUAN dataset by filename.

Parameters:

filename (str) – GRUAN filename to download, e.g. “LIN-RS-01_2_RS92-GDP_002_20210125T132400_1-000-001.nc”

Returns:

xarray.Dataset – The GRUAN dataset retrieved from the FTP server. If caching is enabled, the file is downloaded to the cache store and loaded from there on subsequent calls.

list_files(year=None)

List available files for a given year.

Parameters:

year (int | None, optional) – Year to list files for. If None, list files for all available years. The later may be time-consuming.

Returns:

list[str] – List of available GRUAN filenames for the specified year.

product
site
years()

Get a list of available years for the selected product and site.