Merge branch 'master' of https://github.com/pySTEPS/pysteps

Author: dnerini

pysteps/nowcasts/extrapolation.py

@@ -14,7 +14,8 @@ def forecast(R, V, num_timesteps, extrap_method="semilagrangian", extrap_kwargs=
       field.
     V : array-like
       Array of shape (2,m,n) containing the x- and y-components of the advection
-      field. The velocities are assumed to represent one time step.
+      field. The velocities are assumed to represent one time step between the 
+      inputs.
     num_timesteps : int
       Number of time steps to forecast.
 
@@ -24,14 +25,15 @@ def forecast(R, V, num_timesteps, extrap_method="semilagrangian", extrap_kwargs=
       Name of the extrapolation method to use. See the documentation of
       pysteps.extrapolation.interface.
     extrap_kwargs : dict
-      Optional dictionary that is supplied as keyword arguments to the
+      Optional dictionary that is expanded into keyword arguments for the
       extrapolation method.
 
     Returns
     -------
     out : ndarray
       Three-dimensional array of shape (num_timesteps,m,n) containing a time
-      series of nowcast precipitation fields.
+      series of nowcast precipitation fields. The time step is taken from
+      the advection field.
 
     See also
     --------

pysteps/nowcasts/interface.py

@@ -1,18 +1,20 @@
 import numpy as np
 
-"""The forecast methods in the nowcasts module implement the following interface:
+"""The methods in the nowcasts module implement the following interface:
 
-    forecast(R, V, num_timesteps, keyword arguments)
+    forecast(R, V, num_timesteps, **kwargs)
 
 where R (m,n) is the input precipitation field and V (2,m,n) is an array
 containing  the x- and y-components of the m*n advection field. num_timesteps
 is an integer specifying the number of time steps to forecast. The interface
 accepts optional keyword arguments specific to the given method.
 
-The output depends on the type of the method. For deterministic methods, the 
-output is a three-dimensional array of shape (num_timesteps,m,n) containing a 
-time series of nowcast precipitation fields. For stochastic methods, the 
-output is a four-dimensional array of shape (num_ensemble_members,num_timesteps,m,n).
+The output depends on the type of the method. For deterministic methods, the
+output is a three-dimensional array of shape (num_timesteps,m,n) containing a
+time series of nowcast precipitation fields. For stochastic methods that produce
+an ensemble, the output is a four-dimensional array of shape
+(num_ensemble_members,num_timesteps,m,n). The time step of the output is taken
+from the inputs.
 
 """
 
@@ -25,14 +27,14 @@ def get_method(name):
     +-------------------+-----------------------------------------------------+
     |     Name          |              Description                            |
     +===================+=====================================================+
-    |  eulerian         | this approach simply keeps the last observation     |
-    |                   | frozen (Eulerian persistence)                       |
+    |  eulerian         | this approach keeps the last observation frozen     |
+    |                   | (Eulerian persistence)                              |
     +-------------------+-----------------------------------------------------+
     |  lagrangian or    | this approach extrapolates the last observation     |
-    |  extrapolation    | following the motion field (Lagrangian persistence) |
+    |  extrapolation    | using the motion field (Lagrangian persistence)     |
     +-------------------+-----------------------------------------------------+
     |  steps            | implementation of the STEPS stochastic nowcasting   |
-    |                   | method as described in :cite:`Seed2003`,            |
+    |                   | method described in :cite:`Seed2003`,               |
     |                   | :cite:`BPS2006` and :cite:`SPN2013`                 |
     +-------------------+-----------------------------------------------------+
 

pysteps/nowcasts/steps.py

@@ -63,17 +63,19 @@ def forecast(R, V, n_timesteps, n_ens_members=24, n_cascade_levels=6, R_thr=None
     bandpass_filter_method : {'gaussian', 'uniform'}
       Name of the bandpass filter method to use with the cascade decomposition.
       See the documentation of pysteps.cascade.interface.
-    noise_method : {'parametric','nonparametric','ssft','nested'}
+    noise_method : {'parametric','nonparametric','ssft','nested',None}
       Name of the noise generator to use for perturbating the precipitation
-      field. See the documentation of pysteps.noise.interface.
+      field. See the documentation of pysteps.noise.interface. If set to None,
+      no noise is generated.
     noise_stddev_adj : bool
       Optional adjustment for the standard deviations of the noise fields added
       to each cascade level. See pysteps.noise.utils.compute_noise_stddev_adjs.
     ar_order : int
       The order of the autoregressive model to use. Must be >= 1.
-    vel_pert_method : {'bps'}
-      Name of the noise generator to use for perturbing the velocity field. See
-      the documentation of pysteps.noise.interface.
+    vel_pert_method : {'bps',None}
+      Name of the noise generator to use for perturbing the advection field. See
+      the documentation of pysteps.noise.interface. If set to None, the advection 
+      field is not perturbed.
     conditional : bool
       If set to True, compute the statistics of the precipitation field
       conditionally by excluding the areas where the values are below the
@@ -128,13 +130,19 @@ def forecast(R, V, n_timesteps, n_ens_members=24, n_cascade_levels=6, R_thr=None
       If return_output is True, a four-dimensional array of shape
       (n_ens_members,n_timesteps,m,n) containing a time series of forecast
       precipitation fields for each ensemble member. Otherwise, a None value
-      is returned.
+      is returned. The time step is taken from the input precipitation fields R.
 
     See also
     --------
     pysteps.extrapolation.interface, pysteps.cascade.interface,
     pysteps.noise.interface, pysteps.noise.utils.compute_noise_stddev_adjs
 
+    Notes
+    -----
+    If noise_method and vel_pert_method are set to None and n_ens_members is set
+    to 1, the produced nowcast is deterministic (i.e. the S-PROG nowcast, see
+    :cite:`Seed2003`).
+
     References
     ----------
     :cite:`Seed2003`, :cite:`BPS2006`, :cite:`SPN2013`