Pysteps

Pysteps v1.5.0 is now available with some exciting new features! We would like to thank everyone who contributed to this release.

Key updates
- Add new ensemble nowcast model: Lagrangian INtegro-Difference equation model with Autoregression (LINDA) by Pulkkinen et al. (2021). [221, [gallery](https://pysteps.readthedocs.io/en/latest/auto_examples/linda_nowcasts.html#sphx-glr-auto-examples-linda-nowcasts-py)]
- Implement the local Lagrangian approach for probabilistic nowcasting by Germann and Zawadzki (2004). [207, [gallery](https://pysteps.readthedocs.io/en/latest/auto_examples/probability_forecast.html#sphx-glr-auto-examples-probability-forecast-py)]
- Refactor the `utils.interpolate` module. The `rbfinterp2d` method now wraps the scipy's Rbf class, while the old version is renamed to `idwinterp2d` (inverse distance interpolation). [210]
- Implement the `max_num_features` keyword argument for all methods in the `pysteps.feature` module. With this argument, the user can specify the maximum number of detected features. [225]

Bug fixes
- Fix a bug in `utils.spectral.rapsd` function causing negative frequency for evenly-sized images. [211]
- Fix coordinates of the bounding box in `io.importers.import_mrms_grib`. [222]

Installation
You can upgrade to the latest release using `pip install pysteps --upgrade` or `conda update pysteps -c conda-forge`. It is also possible to build from source following [these instructions](https://pysteps.readthedocs.io/en/v1.5.1/user_guide/install_pysteps.html#install-from-source).

Important note
This release represents our last feature release for pysteps v1, while our efforts will now focus on the upcoming v2! See 216 to learn more about this.

Contributors
Thanks to the following developers for their contributions in this release (alphabetical order):
aperezhortal, dnerini, loforest, pulkkins, RubenImhoff

Summary
---------
- Major refactoring of the `pysteps.visualization` module to improve the code quality, documentation, and coverage. As a consequence, there have been few changes in the interfaces to the plotting functionalities that will produce new deprecation warnings for v1.6 [199]
- Fix incompatibility that appeared with scipy>=1.6 causing `pysteps.nowcasts.steps.forecast` to fail with argument `vel_pert_method="bps"` and a zero velocity field [203]
- Fix bug introduced in v1.4.0 concerning the usage of the netcdf exporter in `pysteps.nowcasts.steps.forecast` [200]
- Fix bug in `pysteps.utils.cleansing.decluster` [194]

For a more comprehensive list of all changes please have a look at the [release v1.4.1 Milestone](https://github.com/pySTEPS/pysteps/milestone/6?closed=1).

Contributors
----------------
aperezhortal dnerini pulkkins

Summary
------------
- Introducing the **thunderstorm detection and tracking** (DATing) modules [[example](https://pysteps.readthedocs.io/en/latest/auto_examples/thunderstorm_detection_and_tracking.html#sphx-glr-auto-examples-thunderstorm-detection-and-tracking-py)] [[doc1](https://pysteps.readthedocs.io/en/latest/pysteps_reference/feature.html#pysteps-feature-tstorm)] [[doc2](https://pysteps.readthedocs.io/en/latest/pysteps_reference/tracking.html#pysteps-tracking-tdating)] [178]
- Introducing the RainFARM ([Rebora et al. 2006](
https://doi.org/10.1175/JHM517.1)) module for **downscaling precipitation** fields [[example](https://pysteps.readthedocs.io/en/latest/auto_examples/rainfarm_downscale.html#sphx-glr-auto-examples-rainfarm-downscale-py)] [[doc](https://pysteps.readthedocs.io/en/latest/pysteps_reference/downscaling.html#pysteps-downscaling-rainfarm)] [173]
- Introducing the pysteps **importers plugins** [[doc](https://pysteps.readthedocs.io/en/latest/developer_guide/importer_plugins.html)] [#174]
- Improving the **semi-lagrangian extrapolation** method [[doc](https://pysteps.readthedocs.io/en/latest/generated/pysteps.extrapolation.semilagrangian.extrapolate.html#pysteps.extrapolation.semilagrangian.extrapolate)] [176] [191]
- Improving pysteps **netCDF exporter** [[doc](https://pysteps.readthedocs.io/en/latest/pysteps_reference/io.html#pysteps-io-exporters)] [175]
- Implementing a more general **importer for [ODIM](https://www.eumetnet.eu/glossary/odim/)**-compliant data sources [[doc](https://pysteps.readthedocs.io/en/latest/generated/pysteps.io.importers.import_odim_hdf5.html#pysteps.io.importers.import_odim_hdf5)] [171] [172]
- Improving plotting of basemaps [[doc](https://pysteps.readthedocs.io/en/latest/pysteps_reference/visualization.html#pysteps-visualization-basemaps)] [177] [180] [192]

... and plenty of smaller bug fixes and general improvements. For more info please have a look at the [release v1.4 Milestone](https://github.com/pySTEPS/pysteps/milestone/5?closed=1).

Breaking changes
------------------------

- `pysteps.extrapolation.semilagrangian`
- `D_prev`argument renamed to `displacement_prev` [184]
- `pysteps.utils.images`
- `pysteps.utils.images.shitomasi` method migrated to `pysteps.feature.shitomasi` [178]
- `pysteps.utils.images.blob` method migrated to `pysteps.feature.blob` [178]
- `pysteps.motion.lucaskande`
- `pysteps.motion.lucaskanade.track_features` method migrated to `pysteps.tracking.lucaskanade.track_features` [178]
- `pysteps.visualization`
- `map` argument renamed to `plot_map` [177] [180]

Contributors
----------------
aperezhortal chiara-arpae dnerini edigiacomo feldmann-m jleinonen loforest pulkkins RubenImhoff

* `cascade`
* Compute cascade level statistics by default in the `decomposition.decomposition_fft` function.
* `motion`
* Fix the issue with the padding keyword in the `motion.vet` function to correctly handle masked and non-masked input arrays.
* `noise`
* Add a very small offset to the tapering window to avoid zero values causing some artifacts with the `ssft` and `nested` filters.
* `nowcasts`
* Set out-of-domain values to nan in `sprog.forecast` and `steps.forecast`.
* Set negative values in `anvil.forecast` to zero.
* Add option to disable localization in `anvil.forecast` by passing `ar_window_radius=None`.
* Change default to `probmatching_method='cdf'` in `sprog.forecast`.
* `pystepsrc`
* Convert the value of pixelsize to km for `knmi` data.
* `verification`
* Fix error in `plot.plot_rankhist` caused by a different number of ticks and tick labels.
* `visualization`
* Fix interfaces in `motionfields` routines with respect to `basemaps.plot_geography`.
* Update docstrings in `motionfields`.

Future Warnings:
* `v1.4.0`:
* Rename keyword argument `map` to `plot_map` for all routines in the `visualization` module.

- `dataset`
- Fix permissions errors in `download_pysteps_data` and `download_mrms_data` functions
- Update installation instructions for Windows systems
- `motion.lucaskanade.dense_lucaskanade`
- Add option to use `blob_detection` as feature detection method
- `nowcasts.anvil`
- Implement precipitation mask when rainrate is set to None
- Minor changes to default values, masking and thresholding
- `utils.images`
- Add `blob_detection` method

- `dataset`
- add function `download_pysteps_data` to download the example data from the pysteps-data GitHub repo
- add function `create_default_pystepsrc` to create a default configuration file pointing to the local pysteps data directory
- add helper functions to easily load the example data for each data source (fmi, mch, opera, etc)
- `io.importers`:
- add function `import_mrms_grib` to import NSSL’s Multi-Radar/Multi-Sensor System (MRMS) grib data
- change spatial units from meters to kilometers in `import_knmi_hdf5` and fix definition of `y1`and `y2` parameters in the metadata.
- allow all the importers to specify the output array data type (dtype keyword) and fill invalid data with a predefined value (fillna keyword)
- add function to safely and consistently get the rain/no rain threshold
- `motion.constant`
- `constant`method returns two-dimensional advection field instead of one motion vector
- `motion.lucaskanade`
- fix bug in `dense_lucaskanade` handling of MaskedArrays inputs. Previously, the method ignored the input mask, unless the masked values where set as nans
- require ndarrays or MaskedArrays as input data to `dense_lucaskanade`
- `motion.vet`
- fix bug in `vet` keywords handling. Previously, the method argument passed to the minimizer was ignored
- `nowcasts`
- add deterministic nowcasting module `nowcasts.anvil`
- `utils.dimensions`
- include option `trim` in `aggregate_fields` function to allow aggregation along axes that are not perfectly divisible by a given window
- `utils.images`
- rename `ShiTomasi_detection` function to lowercase `shitomasi_detection` to comply with PEP8
- change default value for the `buffer_mask` argument in the `shitomasi_detection` function from 0 to 5 to provide a minimum buffer to no-data in the `motion.lucaskanade.dense_lucaskanade` method
- `utils.interpolate`
- change default value for the `epsilon` argument in the `rbfinterp2d` function from 5 to 10 to provide a more localized interpolation of motion vectors in the `motion.lucaskanade.dense_lucaskanade` method

Contributors to this release:
aperezhortal dnerini pulkkins RubenImhoff