Tutorials
Alto Iguaçu River Basin Minimal Example
In this section an example of application of the model in the Brazilian basin of the Alto Iguaçu river is presented. For this case study you need to download the respective required dataset which is available on the datasets page.
For this example, we will set up the RUBEM model for ten years: 2000 to 2009. For this period, we will set up a 500 x 500 m spatial resolution (grid cell size). All maps used in this tutorial are in the WGS 84 ESPG 2346 projection. In this tutorial, each step to set up the model is discussed.
Create a new project
Create a new project in the downloaded dataset directory named Iguazu.json or another appropriate filename.
Initial Settings
Open the created Iguazu.json file and enter the following fields into the file to specify a directory to store the model output files. The output directory is the directory where the model will store the results:
{
"DIRECTORIES": {
"output": "/Iguazu/output/",
}
}
Enable Export results to station locations (tss) option to export of results at the locations of the gauging stations as CSV files. Then define the file containing the map of the stations locations samples:
{
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"samples": "Iguazu/maps/stations/samples.map"
},
}
Now let’s fill in the other fields with the appropriate maps from the input directory (Dataset maps folder), as indicated in the table below:
Model General settings |
|
|---|---|
DEM MAP |
|
DEM TIFF |
|
Clone MAP |
|
In the part Grid set 500.000 m as size value and in the part Simulation Period, set the start and end of the simulation, from January 2000 until December 2009.
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map",
},
}
Soil settings
In the Soil Parameters input maps and tables need to be provided for different physical soil parameters. Soil raster data are located at /input/maps/soil/. Define soil as /input/maps/soil/soil.map. This map has the soil types in the basin. The numerical values in this map correspond to the categorized soil types defined from the Brazilian Soil Classification System.
The folder /input/txt/soil contains tables with the values of the soil parameters coupled to each soil type. Select the corresponding table at each field (e.g. /input/txt/soil/Ksat.txt in Saturated Hydraulic Conductivity).
Set the following values for Initial Soil Conditions fields:
Initial Soil Conditions |
|
|---|---|
Initial Baseflow |
|
Baseflow Threshold |
|
Initial Saturated Zone Storage |
|
Initial Soil Moisture Content |
|
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map ",
"soil": "Iguazu/input/maps/soil/soil.map",
},
"TABLES": {
"bulk_density": "Iguazu/input/txt/soil/Bdens.txt",
"K_sat": "Iguazu/input/txt/soil/Ksat.txt",
"T_fcap": "Iguazu/input/txt/soil/Tfc.txt",
"T_sat": "Iguazu/input/txt/soil/Tsat.txt",
"T_wp": "Iguazu/input/txt/soil/Twp.txt",
"rootzone_depth": "Iguazu/input/txt/soil/Dpz.txt",
},
"INITIAL_SOIL_CONDITIONS": {
"T_ini": 0.5,
"bfw_ini": 10.0,
"bfw_lim": 150.0,
"S_sat_ini": 151.0,
},
}
Land Use settings
Land Use data are located at /input/maps/landuse/ and /input/maps/ndvi/ directories. These directories contain input maps (map-series) for landuse and NDVI. The filenames in ndvi folder have a strict numbering format: ndvi0000.001 until ndvi0000.228 in a monthly base. In folder landuse, files correspond to annual maps, cov00000.001 – cov00000.013. For landuse, RUBEM use the prior map when map correspond to current timestep (1 - Jan/2000 to 132-Dec/2010) is this example) does not exist in the directory.
Select cov00000.001 as Land Use map series, ndvi0000.001 for Normalized Difference Vegetation Index and the corresponds .map for maximum and minimum NDVI.
Similar to the soil tab, the folder /input/txt/landuse contains tables with the values of the land use parameters coupled to each cover type, select the corresponding table at each field (e.g. /input/txt/landuse/manning.txt in Manning file).
Use the default values for FPAR, LAI and Impervious Area Interception.
Default Values |
|
|---|---|
FPAR Maximum |
|
FPAR Minimum |
|
LAI Maximum |
|
Impervious Area Interception |
|
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
"ndvi": "Iguazu/input/maps/ndvi/",
"landuse": "Iguazu/input/maps/landuse/",
},
"FILENAME_PREFIXES": {
"ndvi_prefix": "ndvi",
"landuse_prefix": "cov",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map",
"soil": "Iguazu/input/maps/soil/soil.map",
"ndvi_max": "Iguazu/input/maps/ndvi/ndvi_max.map",
"ndvi_min": "Iguazu/input/maps/ndvi/ndvi_min.map",
},
"TABLES": {
"bulk_density": "Iguazu/input/txt/soil/Bdens.txt",
"K_sat": "Iguazu/input/txt/soil/Ksat.txt",
"T_fcap": "Iguazu/input/txt/soil/Tfc.txt",
"T_sat": "Iguazu/input/txt/soil/Tsat.txt",
"T_wp": "Iguazu/input/txt/soil/Twp.txt",
"rootzone_depth": "Iguazu/input/txt/soil/Dpz.txt",
"a_i": "Iguazu/input/txt/landuse/a_i.txtF",
"a_o": "Iguazu/input/txt/landuse/a_o.txt",
"a_s": "Iguazu/input/txt/landuse/a_s.txt",
"a_v": "Iguazu/input/txt/landuse/a_v.txt",
"manning": "Iguazu/input/txt/landuse/manning.txt",
"K_c_min": "Iguazu/input/txt/landuse/kcmin.txt",
"K_c_max": "Iguazu/input/txt/landuse/kcmax.txt",
},
"INITIAL_SOIL_CONDITIONS": {
"T_ini": 0.5,
"bfw_ini": 10.0,
"bfw_lim": 150.0,
"S_sat_ini": 151.0,
},
"CONSTANTS": {
"fpar_max": 0.950,
"fpar_min": 0.001,
"lai_max": 12.000,
"i_imp": 2.500,
},
}
Climate settings
In the Climate section define the appropriate map-series from /input/maps/prec/ for Precipitation [mm/month], /input/maps/etp/ for Potential Evapotranspiration [mm/month], and /input/maps/kp/ for Class A Pan Coefficient [-]. In the Rainy days section select the appropriate file from /input/txt/. It should be noted that the start date always has to correspond with the first climate forcing file (*.001).
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
"ndvi": "Iguazu/input/maps/ndvi/",
"landuse": "Iguazu/input/maps/landuse/",
"etp": "Iguazu/input/maps/etp/",
"prec": "Iguazu/input/maps/prec/",
"kp": "Iguazu/input/maps/kp/",
},
"FILENAME_PREFIXES": {
"etp_prefix": "etp",
"prec_prefix": "prec",
"kp_prefix": "kp",
"ndvi_prefix": "ndvi",
"landuse_prefix": "cob",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map",
"soil": "Iguazu/input/maps/soil/soil.map",
"ndvi_max": "Iguazu/input/maps/ndvi/ndvi_max.map",
"ndvi_min": "Iguazu/input/maps/ndvi/ndvi_min.map",
},
"TABLES": {
"rainydays": "Iguazu/input/txt/rainydays.txt",
"bulk_density": "Iguazu/input/txt/soil/Bdens.txt",
"K_sat": "Iguazu/input/txt/soil/Ksat.txt",
"T_fcap": "Iguazu/input/txt/soil/Tfc.txt",
"T_sat": "Iguazu/input/txt/soil/Tsat.txt",
"T_wp": "Iguazu/input/txt/soil/Twp.txt",
"rootzone_depth": "Iguazu/input/txt/soil/Dpz.txt",
"a_i": "Iguazu/input/txt/landuse/a_i.txt",
"a_o": "Iguazu/input/txt/landuse/a_o.txt",
"a_s": "Iguazu/input/txt/landuse/a_s.txt",
"a_v": "Iguazu/input/txt/landuse/a_v.txt",
"manning": "Iguazu/input/txt/landuse/manning.txt",
"K_c_min": "Iguazu/input/txt/landuse/kcmin.txt",
"K_c_max": "Iguazu/input/txt/landuse/kcmax.txt",
},
"INITIAL_SOIL_CONDITIONS": {
"T_ini": 0.5,
"bfw_ini": 10.0,
"bfw_lim": 150.0,
"S_sat_ini": 151.0,
},
"CONSTANTS": {
"fpar_max": 0.950,
"fpar_min": 0.001,
"lai_max": 12.000,
"i_imp": 2.500,
},
}
Parameters Settings
Values in this tab correspond to calibrated parameters in the basin. For the dataset, the figure below shows the values. The model calibration requires a trial and error approach when RUBEM Hydrological (plugin) is the only tool used. It is possible to adapt RUBEM (code) for using optimization tools for calibration e.g. Scipy library algorithms.
Parameter |
Value |
|---|---|
Interception Parameter (alpha) |
|
Rainfall Intensity Coefficient (b) |
|
Land Use Factor Weight (w_1) |
|
Soil Factor Weight (w_2) |
|
Slope Factor Weight (w_3) |
|
Regional Consecutive Dryness Level (rcd) |
|
Flow Direction Factor (f) |
|
Baseflow Recession Coefficient (alpha_GW) |
|
Flow Recession Coefficient (x) |
|
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
"ndvi": "Iguazu/input/maps/ndvi/",
"landuse": "Iguazu/input/maps/landuse/",
"etp": "Iguazu/input/maps/etp/",
"prec": "Iguazu/input/maps/prec/",
"kp": "Iguazu/input/maps/kp/",
},
"FILENAME_PREFIXES": {
"etp_prefix": "etp",
"prec_prefix": "prec",
"kp_prefix": "kp",
"ndvi_prefix": "ndvi",
"landuse_prefix": "cob",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map",
"soil": "Iguazu/input/maps/soil/soil.map",
"ndvi_max": "Iguazu/input/maps/ndvi/ndvi_max.map",
"ndvi_min": "Iguazu/input/maps/ndvi/ndvi_min.map",
},
"TABLES": {
"rainydays": "Iguazu/input/txt/rainydays.txt",
"bulk_density": "Iguazu/input/txt/soil/Bdens.txt",
"K_sat": "Iguazu/input/txt/soil/Ksat.txt",
"T_fcap": "Iguazu/input/txt/soil/Tfc.txt",
"T_sat": "Iguazu/input/txt/soil/Tsat.txt",
"T_wp": "Iguazu/input/txt/soil/Twp.txt",
"rootzone_depth": "Iguazu/input/txt/soil/Dpz.txt",
"a_i": "Iguazu/input/txt/landuse/a_i.txt",
"a_o": "Iguazu/input/txt/landuse/a_o.txt",
"a_s": "Iguazu/input/txt/landuse/a_s.txt",
"a_v": "Iguazu/input/txt/landuse/a_v.txt",
"manning": "Iguazu/input/txt/landuse/manning.txt",
"K_c_min": "Iguazu/input/txt/landuse/kcmin.txt",
"K_c_max": "Iguazu/input/txt/landuse/kcmax.txt",
},
"INITIAL_SOIL_CONDITIONS": {
"T_ini": 0.5,
"bfw_ini": 10.0,
"bfw_lim": 150.0,
"S_sat_ini": 151.0,
},
"CONSTANTS": {
"fpar_max": 0.950,
"fpar_min": 0.001,
"lai_max": 12.000,
"i_imp": 2.500,
},
"CALIBRATION": {
"alpha": 4.41,
"b": 0.07,
"w1": 0.51,
"w2": 0.12,
"w3": 0.37,
"rcd": 5.37,
"f": 0.58,
"alpha_gw": 0.92,
"x": 0.307,
},
}
Model Execution Settings
Within this section it’s necessary to specify for each variable if you want this to be reported as model output True or False. The Generate Files Section contais a list with all the variables that can be reported as model output.
In the example below it can be seen that Recharge, Accumulated Total Runoff and Total Interception are checked to be reported. If Export Results to stations locations (tss) was defined as True, time-series for the selected variables will be generated.
The default format the generated raster files is PCRaster map format map_raster_series": true,.
The complete project configuration file should look like this:
{
"GRID": {
"grid": 500.00,
},
"SIM_TIME": {
"start": "01/01/2000",
"end": "01/12/2009",
},
"DIRECTORIES": {
"output": "Iguazu/output/",
"ndvi": "Iguazu/input/maps/ndvi/",
"landuse": "Iguazu/input/maps/landuse/",
"etp": "Iguazu/input/maps/etp/",
"prec": "Iguazu/input/maps/prec/",
"kp": "Iguazu/input/maps/kp/",
},
"FILENAME_PREFIXES": {
"etp_prefix": "etp",
"prec_prefix": "prec",
"kp_prefix": "kp",
"ndvi_prefix": "ndvi",
"landuse_prefix": "cob",
},
"GENERATE_FILE": {
"tss": true,
},
"RASTERS": {
"dem": "Iguazu/input/maps/dem/dem.map",
"clone": "Iguazu/input/maps/clone/clone.map",
"samples": "Iguazu/maps/stations/samples.map",
"soil": "Iguazu/input/maps/soil/soil.map",
"ndvi_max": "Iguazu/input/maps/ndvi/ndvi_max.map",
"ndvi_min": "Iguazu/input/maps/ndvi/ndvi_min.map",
},
"TABLES": {
"rainydays": "Iguazu/input/txt/rainydays.txt",
"bulk_density": "Iguazu/input/txt/soil/Bdens.txt",
"K_sat": "Iguazu/input/txt/soil/Ksat.txt",
"T_fcap": "Iguazu/input/txt/soil/Tfc.txt",
"T_sat": "Iguazu/input/txt/soil/Tsat.txt",
"T_wp": "Iguazu/input/txt/soil/Twp.txt",
"rootzone_depth": "Iguazu/input/txt/soil/Dpz.txt",
"a_i": "Iguazu/input/txt/landuse/a_i.txt",
"a_o": "Iguazu/input/txt/landuse/a_o.txt",
"a_s": "Iguazu/input/txt/landuse/a_s.txt",
"a_v": "Iguazu/input/txt/landuse/a_v.txt",
"manning": "Iguazu/input/txt/landuse/manning.txt",
"K_c_min": "Iguazu/input/txt/landuse/kcmin.txt",
"K_c_max": "Iguazu/input/txt/landuse/kcmax.txt",
},
"INITIAL_SOIL_CONDITIONS": {
"T_ini": 0.5,
"bfw_ini": 10.0,
"bfw_lim": 150.0,
"S_sat_ini": 151.0,
},
"CONSTANTS": {
"fpar_max": 0.950,
"fpar_min": 0.001,
"lai_max": 12.000,
"i_imp": 2.500,
},
"CALIBRATION": {
"alpha": 4.41,
"b": 0.07,
"w1": 0.51,
"w2": 0.12,
"w3": 0.37,
"rcd": 5.37,
"f": 0.58,
"alpha_gw": 0.92,
"x": 0.307,
},
"GENERATE_FILE": {
"itp": true,
"bfw": false,
"srn": false,
"eta": false,
"lfw": false,
"rec": true,
"smc": false,
"rnf": false,
"arn": true,
"tss": true,
},
"RASTER_FILE_FORMAT": {
"map_raster_series": true,
"tiff_raster_series": false,
},
}
In a proper Conda environment, run the following command:
$ python rubem -c Iguazu.json
If all the project’s configuration file is specified correctly, the user should be faced with the following:
Loading configuration and validating inputs...
Simulation started...
.## Timestep 1 of 120
.## Timestep 2 of 120
-- Omited for brevity --
.## Timestep 120 of 120
Simulation finished successfully!
Elapsed time: 5 seconds
The files generated by the model will be in the directory specified in the output parameter.