improver.cli.stochastic_noise module#
CLI to add stochastic noise to a cube using Short-Space Fourier Transform (SSFT).
- process(input_cube, *, ssft_init_params=None, ssft_generate_params=None, db_threshold=0.03, db_threshold_units='mm/hr', num_workers=None, scale_non_positive_noise=False, allow_seeded_parallel_processing=False)[source]#
Class to apply spatially-structured stochastic noise to non-positive regions of a field, building on the Short-Space Fourier Transform (SSFT) approach from Nerini et al. (2017).
This plugin is intended for use with positive zero-bounded diagnostics only, and is a particularly useful tool for Ensemble Copula Coupling-Quantile (ECC-Q) realization generation. While EEC-Q is used to improve the accuracy of forecasts by calibrating ensemble members to better represent the true distribution of the forecast variable, the rank-based reordering (sorting) of ensemble members at each grid point can lead to unrealistic individual members (e.g. single-pixel precipitation artifacts) when multiple raw ensemble members have identical values (‘ties’) of zero (very common in precipitation forecasts) and the post-processed calibrated probabilities indicate a non-zero value should occur. By adding spatially-structured noise to break ties in these non-positive regions, more realistic spatial structures can be generated in the final ECC-Q realizations, while still respecting the calibrated probabilities.
- Parameters:
input_cube (
inputcube) – Cube to which stochastic noise will be added. Typically a dependence template cube for ECC-Q realization generation, where noise is added to non-positive regions (e.g., locations with zero precipitation) to break ties in the raw ensemble and allow meaningful reordering.ssft_init_params (
str) – Keyword arguments for initializing SSFT filter using pysteps.noise.fftgenerators.initialize_nonparam_2d_ssft_filter. Provide as Python dict string, e.g., “{‘win_size’: (100, 100), ‘overlap’: 0.3}”. Recommended keys: win_size, overlap, war_thr. Default is an empty dict, which will use the pysteps defaults.ssft_generate_params (
str) – Keyword arguments for generating stochastic noise using pysteps.noise.fftgenerators.generate_noise_2d_ssft_filter. Provide as Python dict string, e.g., “{‘overlap’: 0.3, ‘seed’: 0}”. Recommended keys: overlap, seed. Default is an empty dict, which will use the pysteps defaults.db_threshold (
float) – Threshold value below which data will be set to a constant in dB scale to avoid issues with log(0). Value provided in units of db_threshold_units. Default is 0.03 mm/hr.db_threshold_units (
str) – Units of the db_threshold value. Default is “mm/hr”.num_workers (
int) – Number of worker threads for parallel FFT computation. If not specified, uses the smaller of the plugin’s default (number of available CPUs) or the number of realizations in the input cube.scale_non_positive_noise – If True, noise in non-positive regions (where template.data <= 0) will be scaled such that the maximum noise value in those regions is zero and all other noise values are negative. This prevents the addition of positive noise to non-positive regions, which could artificially increase values where the input cube indicates no signal should occur. Default is False.
allow_seeded_parallel_processing (
bool) – If True, allows multiple workers to be used even when a seed is provided in ssft_generate_params. This may improve computation speed, but can introduce run-to-run variation because pySTEPS uses global RNG seeding. If False, seeded runs are forced to a single worker for reproducibility. Default is False.
- Returns:
Cube with added stochastic noise.
See Pysteps documentation for further keyword arguments.