pysteps.extrapolation

Extrapolation module functions and interfaces.

pysteps.extrapolation.interface

The functions in the extrapolation module implement the following interface:

extrapolate(extrap, precip, velocity, timesteps, outval=np.nan, **keywords)

where extrap is an extrapolator object returned by the initialize function, precip is a (m,n) array with input pre-cipitation field to be advected and velocity is a (2,m,n) array containing the x- and y-components of the m x n advection field. timesteps is an integer or list specifying the time steps to extrapolate. If an integer is given, a range of uniformly spaced steps 1,2,. . . ,timesteps is created. If a list is given, it is assumed to represent a sequence of monotonously increasing time steps. One time unit is assumed to represent the time step of the advection field.

The optional argument outval specifies the value for pixels advected from outside the domain. Optional keyword arguments that are specific to a given extrapolation method are passed as a dictionary.

The output of each method is an array that contains the time series of extrapolated fields of shape (num_timesteps, m, n).

get_method(name) Return two-element tuple for the extrapolation method corresponding to the given name.

eulerian_persistence(precip, velocity, timesteps)

A dummy extrapolation method to apply Eulerian per-sistence to a two-dimensional precipitation field.

pysteps.extrapolation.interface.get_method

pysteps.extrapolation.interface.get_method(name)

Return two-element tuple for the extrapolation method corresponding to the given name. The elements of the tuple are callable functions for the initializer of the extrapolator and the extrapolation method, respectively. The available options are:

Name Description

None returns None

eulerian this methods does not apply any advection to the input precipitation field (Eulerian persistence)

semila-grangian

implementation of the semi-Lagrangian method described in [GZ02]

pysteps.extrapolation.interface.eulerian_persistence

pysteps.extrapolation.interface.eulerian_persistence(precip, velocity, timesteps, outval=nan, **kwargs)

A dummy extrapolation method to apply Eulerian persistence to a two-dimensional precipitation field.

The method returns the a sequence of the same initial field with no extrapolation applied (i.e. Eulerian persistence).

Parameters

precip

[array-like] Array of shape (m,n) containing the input precipitation field. All values are required to be finite.

velocity

[array-like] Not used by the method.

timesteps

[int or list of floats] Number of time steps or a list of time steps.

outval

[float, optional] Not used by the method.

Returns

out

[array or tuple] If return_displacement=False, return a sequence of the same initial field of shape (num_timesteps,m,n). Otherwise, return a tuple containing the replicated fields and a (2,m,n) array of zeros.

Other Parameters

return_displacement

[bool] If True, return the total advection velocity (displacement) between the initial input field and the advected one integrated along the trajectory. Default : False

References

[GZ02]

pysteps.extrapolation.semilagrangian

Implementation of the semi-Lagrangian method described in [GZ02].

extrapolate(precip, velocity, timesteps[, . . . ]) Apply semi-Lagrangian backward extrapolation to a two-dimensional precipitation field.

pysteps.extrapolation.semilagrangian.extrapolate

pysteps.extrapolation.semilagrangian.extrapolate(precip, velocity, timesteps, outval=nan, xy_coords=None, allow_nonfinite_values=False, vel_timestep=1, **kwargs) Apply semi-Lagrangian backward extrapolation to a two-dimensional precipitation field.

Parameters

precip: array-like or None

Array of shape (m,n) containing the input precipitation field. All values are required

to be finite by default. If set to None, only the displacement field is returned without interpolating the inputs. This requires that return_displacement is set to True.

velocity: array-like

Array of shape (2,m,n) containing the x- and y-components of the m*n advection field.

All values are required to be finite by default.

timesteps: int or list of floats

If timesteps is integer, it specifies the number of time steps to extrapolate. If a list is given, each element is the desired extrapolation time step from the current time. The elements of the list are required to be in ascending order.

outval: float, optional

Optional argument for specifying the value for pixels advected from outside the domain.

If outval is set to ‘min’, the value is taken as the minimum value of precip. Default:

np.nan

xy_coords: ndarray, optional

Array with the coordinates of the grid dimension (2, m, n ).

• xy_coords[0]: x coordinates

• xy_coords[1]: y coordinates

By default, the xy_coords are computed for each extrapolation.

allow_nonfinite_values: bool, optional

If True, allow non-finite values in the precipitation and advection fields. This option is useful if the input fields contain a radar mask (i.e. pixels with no observations are set to nan).

Returns

out: array or tuple

If return_displacement=False, return a time series extrapolated fields of shape (num_timesteps,m,n). Otherwise, return a tuple containing the extrapolated fields and the integrated trajectory (displacement) along the advection field.

Other Parameters

displacement_prev: array-like

Optional initial displacement vector field of shape (2,m,n) for the extrapolation. Default:

None n_iter: int

Number of inner iterations in the semi-Lagrangian scheme. If n_iter > 0, the integration is done using the midpoint rule. Otherwise, the advection vectors are taken from the starting point of each interval. Default: 1

return_displacement: bool

If True, return the displacement between the initial input field and the one obtained by integrating along the advection field. Default: False

vel_timestep: float

The time step of the velocity field. It is assumed to have the same unit as the timesteps argument. Applicable if timeseps is a list. Default: 1.

interp_order: int

The order of interpolation to use. Default: 1 (linear). Setting this to 0 (nearest neighbor) gives the best computational performance but may produce visible artefacts. Setting this to 3 (cubic) gives the best ability to reproduce small-scale variability but may signifi-cantly increase the computation time.

References

[GZ02]