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

dnerini · dnerini · commit 5bcef2ee6307 · 2018-12-24T10:26:33.000+01:00
diff --git a/doc/conf.py b/doc/conf.py
@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1'
+version = u'0.2'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1'
+release = u'0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/cascade.rst b/doc/source/cascade.rst
@@ -3,8 +3,8 @@
 Scale-based decomposition of precipitation fields (:mod:`pysteps.cascade`)
 **************************************************************************
 
-Methods for band-pass filtering and scale-based decomposition of 2d precipitation 
-fields.
+Methods for constructing bandpass filters and decomposing 2d precipitation 
+fields into different spatial scales.
 
 pysteps.cascade.interface
 -------------------------
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -19,7 +19,7 @@ and objects included in pysteps.
    :maxdepth: 2
    :caption: Contents
    
-   nowcasting
+   nowcasts
    io
    motion
    extrapolation
diff --git a/doc/source/io.rst b/doc/source/io.rst
@@ -27,6 +27,8 @@ pysteps\.io\.importers
     import_bom_rf3
     import_fmi_pgm
     import_mch_gif
+    import_mch_hdf5
+    import_mch_metranet
     import_odim_hdf5
 
 .. automodule:: pysteps.io.importers
diff --git a/doc/source/motion.rst b/doc/source/motion.rst
@@ -0,0 +1,40 @@
+.. _pysteps.motion:
+
+Optical flow methods (:mod:`pysteps.motion`)
+********************************************
+
+Implementations of optical flow methods.
+
+pysteps\.motion\.interface
+--------------------------
+
+.. automodule:: pysteps.motion.interface
+    :members:
+
+pysteps\.motion\.darts
+----------------------
+
+.. automodule:: pysteps.motion.darts
+    :members:
+
+pysteps\.motion\.lucaskanade
+----------------------------
+
+.. currentmodule:: pysteps.motion.lucaskanade
+
+.. autosummary::
+    dense_lucaskanade
+
+.. automodule:: pysteps.motion.lucaskanade
+    :members:
+
+pysteps\.motion\.vet
+--------------------
+
+.. currentmodule:: pysteps.motion.vet
+
+.. autosummary::
+    vet
+
+.. automodule:: pysteps.motion.vet
+    :members:
diff --git a/doc/source/nowcasts.rst b/doc/source/nowcasts.rst
diff --git a/doc/source/postprocessing.rst b/doc/source/postprocessing.rst
@@ -5,7 +5,20 @@ Post-processing of forecasts (:mod:`pysteps.postprocessing`)
 
 Methods for post-processing of forecasts. Currently the module contains 
 cumulative density function (CDF)-based matching between a forecast and the 
-target distribution.
+target distribution and computation of mean value and exceedance probabilities 
+from forecast ensembles.
+
+pysteps\.postprocessing\.ensemblestats
+--------------------------------------
+
+.. currentmodule:: pysteps.postprocessing.ensemblestats
+
+.. autosummary::
+    mean
+    excprob
+
+.. automodule:: pysteps.postprocessing.ensemblestats
+    :members:
 
 pysteps\.postprocessing\.probmatching
 -------------------------------------
@@ -17,6 +30,7 @@ pysteps\.postprocessing\.probmatching
     nonparam_match_empirical_cdf
     pmm_init
     pmm_compute
+    shift_scale
 
 .. automodule:: pysteps.postprocessing.probmatching
     :members:
diff --git a/doc/source/references.bib b/doc/source/references.bib
@@ -80,7 +80,9 @@ @ARTICLE{PCH2018
   AUTHOR = "S. Pulkkinen and V. Chandrasekar and A.-M. Harri",
   TITLE = "Nowcasting of Precipitation in the High-Resolution {D}allas-{F}ort {W}orth ({DFW}) Urban Radar Remote Sensing Network",
   JOURNAL = "IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing",
-  NOTE = "accepted, to appear",
+  VOLUME = 11,
+  NUMBER = 8,
+  PAGES = "2773--2787",
   YEAR = 2018,
   DOI = "10.1109/JSTARS.2018.2840491"
 }
diff --git a/doc/source/timeseries.rst b/doc/source/timeseries.rst
@@ -13,7 +13,8 @@ pysteps\.timeseries\.autoregression
 .. currentmodule:: pysteps.timeseries.autoregression
 
 .. autosummary::
-    adjust_lag2_corrcoef
+    adjust_lag2_corrcoef1
+    adjust_lag2_corrcoef2
     estimate_ar_params_yw
     iterate_ar_model
 
diff --git a/doc/source/utils.rst b/doc/source/utils.rst
@@ -3,8 +3,8 @@
 Miscellaneous utility functions (:mod:`pysteps.utils`)
 ******************************************************
 
-Utility functions for converting data values to/from different units and 
-manipulating the dimensions of precipitation fields.
+Utility functions for converting data values to/from different units, 
+manipulating the dimensions of precipitation fields and computing the FFT.
 
 pysteps\.utils\.conversion
 --------------------------
@@ -26,12 +26,25 @@ pysteps\.utils\.dimension
 
 .. autosummary::
     aggregate_fields_time
+    aggregate_fields_space
     aggregate_fields
+    clip_domain
     square_domain
 
 .. automodule:: pysteps.utils.dimension
     :members:
 
+pysteps\.utils\.fft
+-------------------
+
+.. currentmodule:: pysteps.utils.fft
+
+.. autosummary::
+    get_method
+
+.. automodule:: pysteps.utils.fft
+    :members:
+
 pysteps\.utils\.interface
 -------------------------
 
@@ -47,6 +60,8 @@ pysteps\.utils\.transformation
     dB_transform
     boxcox_transform
     boxcox_transform_test_lambdas
+    NQ_transform
+    sqrt_transform
 
 .. automodule:: pysteps.utils.transformation
     :members:
diff --git a/doc/source/verification.rst b/doc/source/verification.rst
@@ -33,8 +33,8 @@ pysteps\.verification\.ensscores
 .. currentmodule:: pysteps.verification.ensscores
 
 .. autosummary::
-    ensemble_fss_skill
-    ensemble_fss_spread
+    ensemble_skill
+    ensemble_spread
     rankhist_init
     rankhist_accum
     rankhist_compute
@@ -48,6 +48,7 @@ pysteps\.verification\.plots
 .. currentmodule:: pysteps.verification.plots
 
 .. autosummary::
+    plot_intensityscale
     plot_rankhist
     plot_reldiag
     plot_ROC
@@ -78,7 +79,10 @@ pysteps\.verification\.spatialscores
 .. currentmodule:: pysteps.verification.spatialscores
 
 .. autosummary::
-    compute_fss
+    binary_mse
+    intensity_scale_init
+    intensity_scale_accum
+    fss
 
 .. automodule:: pysteps.verification.spatialscores
     :members:
diff --git a/pysteps/cascade/__init__.py b/pysteps/cascade/__init__.py
@@ -1,2 +1,4 @@
+"""Methods for constructing bandpass filters and decomposing 2d precipitation 
+fields into different spatial scales."""
 
 from .interface import get_method
diff --git a/pysteps/cascade/decomposition.py b/pysteps/cascade/decomposition.py
@@ -23,7 +23,7 @@
 """
 
 import numpy as np
-from .. utils import fft as fft_module
+from .. import utils
 
 def decomposition_fft(X, filter, **kwargs):
     """Decompose a 2d input field into multiple spatial scales by using the Fast
@@ -55,7 +55,7 @@ def decomposition_fft(X, filter, **kwargs):
     """
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
     MASK = kwargs.get("MASK", None)
diff --git a/pysteps/extrapolation/__init__.py b/pysteps/extrapolation/__init__.py
@@ -1,2 +1,5 @@
+"""Methods for advection-based extrapolation of precipitation fields. Currently 
+the module contains an implementation of the semi-Lagrangian method described 
+in :cite:`GZ2002`."""
 
 from .interface import get_method
diff --git a/pysteps/io/__init__.py b/pysteps/io/__init__.py
@@ -1,3 +1,6 @@
+"""Methods for browsing data archives, reading 2d precipitation fields and writing 
+forecasts into files."""
+
 from .interface import get_method
 from .archive import *
 from .exporters import *
diff --git a/pysteps/motion/__init__.py b/pysteps/motion/__init__.py
@@ -1,2 +1,3 @@
+"""Implementations of optical flow methods."""
 
 from .interface import get_method
diff --git a/pysteps/noise/__init__.py b/pysteps/noise/__init__.py
@@ -1,2 +1,5 @@
+"""Methods for generating stochastic perturbations of 2d precipitation and velocity 
+fields."""
+
 from .interface import get_method
 from . import utils
diff --git a/pysteps/noise/fftgenerators.py b/pysteps/noise/fftgenerators.py
@@ -32,7 +32,7 @@
 import numpy as np
 from scipy import optimize
 from .. import utils
-from .. utils import fft as fft_module
+from .. import utils
 
 def initialize_param_2d_fft_filter(X, **kwargs):
     """Takes one ore more 2d input fields, fits two spectral slopes, beta1 and beta2,
@@ -88,7 +88,7 @@ def initialize_param_2d_fft_filter(X, **kwargs):
     doplot   = kwargs.get('doplot', False)
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
 
@@ -216,7 +216,7 @@ def initialize_nonparam_2d_fft_filter(X, **kwargs):
     use_full_fft = kwargs.get('use_full_fft', False)
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
 
@@ -295,10 +295,10 @@ def generate_noise_2d_fft_filter(F, randstate=np.random, seed=None, fft_method=N
         randstate.seed(seed)
 
     if fft_method is None:
-        fft,fft_kwargs = fft_module.get_method("numpy")
+        fft,fft_kwargs = utils.get_method("numpy")
     else:
         if type(fft_method) == str:
-            fft,fft_kwargs = fft_module.get_method(fft_method)
+            fft,fft_kwargs = utils.get_method(fft_method)
         else:
             fft,fft_kwargs = fft
 
@@ -379,7 +379,7 @@ def initialize_nonparam_2d_ssft_filter(X, **kwargs):
     rm_rdisc = kwargs.get('rm_disc', True)
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
 
@@ -492,7 +492,7 @@ def initialize_nonparam_2d_nested_filter(X, gridres=1.0, **kwargs):
     rm_rdisc  = kwargs.get('rm_disc', True)
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
 
@@ -623,7 +623,7 @@ def generate_noise_2d_ssft_filter(F, randstate=np.random, seed=None, **kwargs):
     win_type = kwargs.get('win_type', 'flat-hanning')
     fft = kwargs.get("fft_method", "numpy")
     if type(fft) == str:
-        fft,fft_kwargs = fft_module.get_method(fft)
+        fft,fft_kwargs = utils.get_method(fft)
     else:
         fft,fft_kwargs = fft
 
diff --git a/pysteps/nowcasts/__init__.py b/pysteps/nowcasts/__init__.py
@@ -1,2 +1,4 @@
+"""Implementations of nowcasting methods. Currently the module contains a 
+deterministic advection extrapolation method and STEPS."""
 
 from .interface import get_method
diff --git a/pysteps/nowcasts/steps.py b/pysteps/nowcasts/steps.py
@@ -194,6 +194,7 @@ def forecast(R, V, n_timesteps, n_ens_members=24, n_cascade_levels=6, R_thr=None
     print("precipitation mask:     %s" % ("yes" if use_precip_mask else "no"))
     print("mask method:            %s" % mask_method)
     print("probability matching:   %s" % ("yes" if use_probmatching else "no"))
+    print("FFT method:             %s" % fft_method)
     print("")
 
     print("Parameters:")
diff --git a/pysteps/postprocessing/__init__.py b/pysteps/postprocessing/__init__.py
@@ -1 +1,6 @@
+"""Methods for post-processing of forecasts. Currently the module contains 
+cumulative density function (CDF)-based matching between a forecast and the 
+target distribution and computation of mean value and exceedance probabilities 
+from forecast ensembles."""
+
 from . import ensemblestats
diff --git a/pysteps/timeseries/__init__.py b/pysteps/timeseries/__init__.py
@@ -1 +1,3 @@
-
+"""Methods and models for time series analysis. Currently the module contains 
+implementation of an autoregressive AR(p) model and methods for estimating 
+the model parameters."""
diff --git a/pysteps/utils/__init__.py b/pysteps/utils/__init__.py
@@ -1,3 +1,6 @@
+"""Utility functions for converting data values to/from different units, 
+manipulating the dimensions of precipitation fields and computing the FFT."""
+
 from .arrays import *
 from .conversion import *
 from .dimension import *
diff --git a/pysteps/utils/fft.py b/pysteps/utils/fft.py
@@ -3,31 +3,15 @@
 try:
     import pyfftw.interfaces.numpy_fft as pyfftw_fft
     import pyfftw
-    # TODO: Caching and multithreading are currently disabled because they give 
-    # a segfault with dask.
+    # TODO: Caching is currently disabled because it gives segfault with dask.
     pyfftw.interfaces.cache.disable()
     pyfftw_imported = True
 except ImportError:
     pyfftw_imported = False
 import scipy.fftpack as scipy_fft
 import numpy.fft as numpy_fft
 
-from pysteps.exceptions import MissingOptionalDependency
-
 # use numpy implementation of rfft2/irfft2 because they have not been
 # implemented in scipy.fftpack
 scipy_fft.rfft2  = numpy_fft.rfft2
 scipy_fft.irfft2 = numpy_fft.irfft2
-
-def get_method(name):
-    """Return a callable function for the FFT method corresponding to the given name."""
-    if name == "numpy":
-        return numpy_fft,{}
-    elif name == "scipy":
-        return scipy_fft,{}
-    elif name == "pyfftw":
-        if not pyfftw_imported:
-            raise MissingOptionalDependency("pyfftw is required but it is not installed")
-        return pyfftw_fft,{"threads":1, "planner_effort":"FFTW_ESTIMATE"}
-    else:
-        raise ValueError("unknown method %s, the available methods are 'numpy', 'scipy' and 'pyfftw'" % name)
diff --git a/pysteps/utils/interface.py b/pysteps/utils/interface.py
diff --git a/pysteps/verification/__init__.py b/pysteps/verification/__init__.py
diff --git a/pysteps/visualization/__init__.py b/pysteps/visualization/__init__.py
