Rainfall Model API

class rwgen.RainfallModel(spatial_model, project_name, input_timeseries=None, point_metadata=None, season_definitions='monthly', intensity_distribution='exponential', output_folder='./output', statistic_definitions=None, easting=None, northing=None, elevation=None)

Neyman-Scott Rectangular Pulse (NSRP) rainfall model for point/site and spatial simulations.

Parameters:

  • spatial_model (bool) – Flag to indicate whether point or spatial model.

  • project_name (str) – A name for the gauge/site location, domain or catchment.

  • input_timeseries (str) – Path to file containing timeseries data (for point model) or folder containing timeseries data files (for spatial model). Needed if running pre-processing or fitting steps.

  • point_metadata (pandas.DataFrame or str) – Metadata (or path to metadata file) on point (site/gauge) locations to use for fitting, simulation and/or evaluation for a spatial model only. See Notes for details.

  • season_definitions (str, list or dict) – The model works on a monthly basis by default, but this argument allows for user-defined seasons (see Notes).

  • intensity_distribution (str) – Flag to indicate the type of probability distribution for raincell intensities. Defaults to 'exponential' (with 'weibull' also available currently).

  • output_folder (str) – Root folder for model output. Defaults to './output'.

  • statistic_definitions (pandas.DataFrame or str) – Definitions (descriptions) of statistics to use in fitting and/or evaluation (or path to file of definitions). See Notes for explanation of format.

  • easting (int or float) – Easting of gauge/site for a point simulation. Required if planning to simulate other variables (temperature, PET, …) or apply climate change perturbations via the perturb_statistics() method. Not required for a spatial model.

  • northing (int or float) – Northing of gauge/site for a point simulation. See easting entry above.

  • elevation (int or float) – Elevation of gauge/site for a point simulation. See easting entry above.

Notes

Seasons can be specified through the season_definitions argument in several ways:

  • As descriptive strings ('monthly', 'quarterly', 'half-years', 'annual'). More control can be gained using e.g. 'quarterly_dec' to make Dec-Jan-Feb the first season and so on. Specifying annual will lead to the whole year being considered together, i.e. no seasonality.

  • As a list of strings indicating season abbreviations, e.g. ['DJF', 'MAM', 'JJA', 'SON'].

  • As a dictionary whose keys are the months of the year (integers 1-12) and whose values represent a season identifier, e.g. dict(12=1, 1=1, 2=1, 3=2, 4=2, 5=2, 6=3, 7=3, 8=3, 9=4, 10=4, 11=4) would give quarterly seasons beginning in December.

Statistic definitions are required primarily for model fitting and evaluation. The default statistic_definitions are taken largely from RainSim V3.1 and can be changed with a similarly structured .csv file. Note that:

  • Thresholds can be specified for probability_dry for 1hr (0.1mm or 0.2mm) and 24hr (0.2mm or 1.0mm) durations.

  • Lag can be specified for autocorrelation and cross-correlation (if not specified then defaults of 1 and 0 will be used, respectively).

For a point model the default statistic_definitions are:

Statistic_ID

Name

Duration

Weight

1

variance

1H

1

2

skewness

1H

2

3

probability_dry_0.2mm

1H

7

4

mean

24H

6

5

variance

24H

2

6

skewness

24H

3

7

probability_dry_0.2mm

24H

7

8

autocorrelation_lag1

24H

6

9

variance

72H

3

For a spatial model the default statistic_definitions are:

Statistic_ID

Name

Duration

Weight

1

variance

1H

3

2

skewness

1H

3

3

probability_dry_0.2mm

1H

5

4

mean

24H

5

5

variance

24H

2

6

skewness

24H

2

7

probability_dry_0.2mm

24H

6

8

autocorrelation_lag1

24H

3

9

cross-correlation_lag0

24H

2

10

variance

72H

3

For a spatial model, metadata for point (gauge/site) locations to be used in fitting, simulation or evaluation must be specified through the point_metadata argument. This should be a table like the one below (or a path to a .csv file containing such a table):

Point_ID

Easting

Northing

Name

Elevation

1

659493

5556905

Burgkunstadt

277.5

2

640130

5574573

Lautertal

343.79

3

688073

5524669

Creussen

449.5

Elevation is good to include if available.

__init__(spatial_model, project_name, input_timeseries=None, point_metadata=None, season_definitions='monthly', intensity_distribution='exponential', output_folder='./output', statistic_definitions=None, easting=None, northing=None, elevation=None)

Methods

__init__(spatial_model, project_name[, ...])

preprocess([calculation_period, ...])

Prepare reference statistics, weights and scale factors for use in model fitting, simulation and evaluation.

fit([fitting_method, parameter_bounds, ...])

Fit model parameters.

simulate([output_types, output_subfolders, ...])

Simulate stochastic time series realisation(s) of NSRP process.

postprocess([amax_durations, ...])

Post-processing to calculate statistics from simulated point output.

set_parameters(parameters)

Set parameters attribute.

set_statistics([point_metadata, ...])

Set statistics and related attributes.

perturb_statistics(change_factors[, ...])

Perturb reference statistics using a set of change factors.

plot([plot_type, data_types, point_id])

Plot reference, fitted and/or simulated statistics.

update_output_folder(output_folder)

update_simulation_config([...])

Update default configuration settings for simulation.

update_shuffling_config([target_duration, ...])

Update shuffling settings for fitting and simulation using modified Kim and Onof (2020) method.

Attributes

reference_statistics

Statistics to use as reference in fitting, simulation and/or evaluation

parameters

Parameters to use in simulation

fitted_statistics

Statistics of the NSRP process given current parameters

simulated_statistics

Statistics of simulated time series

parameter_names

Parameter names.

unique_seasons

Unique season identifiers.
fitted_statistics

Statistics of the NSRP process given current parameters

Type:

pandas.DataFrame

property parameter_names

Parameter names.

Type:

list of str

parameters

Parameters to use in simulation

Type:

pandas.DataFrame

reference_statistics

Statistics to use as reference in fitting, simulation and/or evaluation

Type:

pandas.DataFrame

simulated_statistics

Statistics of simulated time series

Type:

pandas.DataFrame

property unique_seasons

Unique season identifiers.

Type:

list of int