pysteps.io#

Methods for browsing data archives, reading 2d precipitation fields and writing forecasts into files.

pysteps.io.interface#

Interface for the io module.

get_method(name, method_type)

Return a callable function for the method corresponding to the given name.

pysteps.io.archive#

Utilities for finding archived files that match the given criteria.

find_by_date(date, root_path, path_fmt, ...)

List input files whose timestamp matches the given date.

pysteps.io.importers#

Methods for importing files containing two-dimensional radar mosaics.

The methods in this module implement the following interface:

import_xxx(filename, optional arguments)

where xxx is the name (or abbreviation) of the file format and filename is the name of the input file.

The output of each method is a three-element tuple containing a two-dimensional radar mosaic, the corresponding quality field and a metadata dictionary. If the file contains no quality information, the quality field is set to None. Pixels containing missing data are set to nan.

The metadata dictionary contains the following recommended key-value pairs:

Key

Value

projection

PROJ.4-compatible projection definition

x1

x-coordinate of the lower-left corner of the data raster

y1

y-coordinate of the lower-left corner of the data raster

x2

x-coordinate of the upper-right corner of the data raster

y2

y-coordinate of the upper-right corner of the data raster

xpixelsize

grid resolution in x-direction

ypixelsize

grid resolution in y-direction

cartesian_unit

the physical unit of the cartesian x- and y-coordinates: e.g. ‘m’ or ‘km’

yorigin

a string specifying the location of the first element in the data raster w.r.t. y-axis: ‘upper’ = upper border ‘lower’ = lower border

institution

name of the institution who provides the data

unit

the physical unit of the data: ‘mm/h’, ‘mm’ or ‘dBZ’

transform

the transformation of the data: None, ‘dB’, ‘Box-Cox’ or others

accutime

the accumulation time in minutes of the data, float

threshold

the rain/no rain threshold with the same unit, transformation and accutime of the data.

zerovalue

the value assigned to the no rain pixels with the same unit, transformation and accutime of the data.

zr_a

the Z-R constant a in Z = a*R**b

zr_b

the Z-R exponent b in Z = a*R**b

Available Importers#

import_bom_rf3(filename, **kwargs)

Import a NetCDF radar rainfall product from the BoM Rainfields3.

import_fmi_geotiff(filename, **kwargs)

Import a reflectivity field (dBZ) from an FMI GeoTIFF file.

import_fmi_pgm(filename[, gzipped])

Import a 8-bit PGM radar reflectivity composite from the FMI archive.

import_knmi_hdf5(filename[, qty, accutime, ...])

Import a precipitation or reflectivity field (and optionally the quality field) from a HDF5 file conforming to the KNMI Data Centre specification.

import_mch_gif(filename, product, unit, ...)

Import a 8-bit gif radar reflectivity composite from the MeteoSwiss archive.

import_mch_hdf5(filename[, qty])

Import a precipitation field (and optionally the quality field) from a MeteoSwiss HDF5 file conforming to the ODIM specification.

import_mch_metranet(filename, product, unit, ...)

Import a 8-bit bin radar reflectivity composite from the MeteoSwiss archive.

import_mrms_grib(filename[, extent, window_size])

Importer for NSSL's Multi-Radar/Multi-Sensor System ([MRMS](https://www.nssl.noaa.gov/projects/mrms/)) rainrate product (grib format).

import_odim_hdf5(filename[, qty])

Import a precipitation field (and optionally the quality field) from a HDF5 file conforming to the ODIM specification.

import_opera_hdf5(filename[, qty])

Wrapper to pysteps.io.importers.import_odim_hdf5() to maintain backward compatibility with previous pysteps versions.

import_saf_crri(filename[, extent])

Import a NetCDF radar rainfall product from the Convective Rainfall Rate Intensity (CRRI) product from the Satellite Application Facilities (SAF).

pysteps.io.nowcast_importers#

Methods for importing nowcast files.

The methods in this module implement the following interface:

import_xxx(filename, optional arguments)

where xxx is the name (or abbreviation) of the file format and filename is the name of the input file.

The output of each method is a two-element tuple containing the nowcast array and a metadata dictionary.

The metadata dictionary contains the following mandatory key-value pairs:

Key

Value

projection

PROJ.4-compatible projection definition

x1

x-coordinate of the lower-left corner of the data raster

y1

y-coordinate of the lower-left corner of the data raster

x2

x-coordinate of the upper-right corner of the data raster

y2

y-coordinate of the upper-right corner of the data raster

xpixelsize

grid resolution in x-direction

ypixelsize

grid resolution in y-direction

yorigin

a string specifying the location of the first element in the data raster w.r.t. y-axis: ‘upper’ = upper border ‘lower’ = lower border

institution

name of the institution who provides the data

timestep

time step of the input data (minutes)

unit

the physical unit of the data: ‘mm/h’, ‘mm’ or ‘dBZ’

transform

the transformation of the data: None, ‘dB’, ‘Box-Cox’ or others

accutime

the accumulation time in minutes of the data, float

threshold

the rain/no rain threshold with the same unit, transformation and accutime of the data.

zerovalue

it is the value assigned to the no rain pixels with the same unit, transformation and accutime of the data.

Available Nowcast Importers#

import_netcdf_pysteps(filename[, onerror])

Read a nowcast or an ensemble of nowcasts from a NetCDF file conforming to the CF 1.7 specification.

pysteps.io.exporters#

Methods for exporting forecasts of 2d precipitation fields into various file formats.

Each exporter method in this module has its own initialization function that implements the following interface:

initialize_forecast_exporter_xxx(outpath, outfnprefix, startdate, timestep,
                                 n_timesteps, shape, metadata,
                                 n_ens_members=1,
                                 incremental=None, **kwargs)

where xxx specifies the file format.

This function creates the output files and writes the metadata. See the documentation of the initialization methods for the format of the output files and their names. The datasets are written by calling pysteps.io.exporters.export_forecast_dataset(), and the files are closed by calling pysteps.io.exporters.close_forecast_files().

The arguments of initialize_forecast_exporter_xxx are described in the following table:

Argument

Type/values

Description

outpath

str

output path

outfnprefix

str

prefix of output file names

startdate

datetime.datetime

start date of the forecast

timestep

int

length of the forecast time step (minutes)

n_timesteps

int

number of time steps in the forecast this argument is ignored if incremental is set to ‘timestep’.

shape

tuple

two-element tuple defining the shape (height,width) of the forecast grids

metadata

dict

metadata dictionary containing the projection,x1,x2,y1,y2 and unit attributes described in the documentation of pysteps.io.importers

n_ens_members

int

number of ensemble members in the forecast this argument is ignored if incremental is set to ‘member’

incremental

{None, ‘timestep’, ‘member’}

allow incremental writing of datasets the available options are: ‘timestep’ = write a forecast or a forecast ensemble for a given time step ‘member’ = write a forecast sequence for a given ensemble member

Optional exporter-specific arguments are passed with kwargs. The return value is a dictionary containing an exporter object. This can be used with pysteps.io.exporters.export_forecast_dataset() to write the datasets to the output files.

Available Exporters#

initialize_forecast_exporter_geotiff(...[, ...])

Initialize a GeoTIFF forecast exporter.

initialize_forecast_exporter_kineros(...[, ...])

Initialize a KINEROS2 format exporter for the rainfall ".pre" files specified in https://www.tucson.ars.ag.gov/kineros/.

initialize_forecast_exporter_netcdf(outpath, ...)

Initialize a netCDF forecast exporter.

Generic functions#

export_forecast_dataset(field, exporter)

Write a forecast array into a file.

close_forecast_files(exporter)

Close the files associated with a forecast exporter.

pysteps.io.readers#

Module with the reader functions.

read_timeseries(inputfns, importer, **kwargs)

Read a time series of input files using the methods implemented in the pysteps.io.importers module and stack them into a 3d array of shape (num_timesteps, height, width).