r.avaflow 2.0 User manual

Even though r.avaflow 2.0 can be operated through a simple Graphical User Interface (GUI), this is strongly discouraged as it is very inefficient. Even though beginners often feel uncomfortable first in working with the terminal and with shell scripts, most of them quickly understand that this is a highly comfortable and efficient way to launch simulations and to analyze the results in a systematic way.

First, you have to launch GRASS with the desired Location and Mapset. Please consult the official GRASS website to learn how to do so. You will not use the GUI of GRASS, but work in the terminal. The command line prompt should start with the GRASS version and, in brackets, the location. This means that you are really in GRASS. You can now start the GUI of r.avaflow by just typing

r.avaflow

As said above, this is inefficient as every single argument of r.avaflow 2.0 has to be typed or selected, and if you would like to run the same simulation for a second time, everything would have to be entered again. More efficiently, you can type the arguments directly into the command line:

r.avaflow -e -v prefix=test phases=s elevation=af_elev hrelease1=af_hrelease

In this case, r.avaflow 2.0 would run a simulation with the one-phase model and evaluate and visualize the results, using the elevation map af_elev and the solid release height map af_hrelease as input. The results are collected in a folder named test_results, which will be stored in the current directory. Both maps would have to be available as GRASS rasters in the current mapset.

You can learn much more about the input of r.avaflow in the section below. However, also with this minimum input it can be demonstrated that this way of operation is more efficient than through the GUI: if you wish to run the simulation again, you can just recover the string by typing the upward key.

But we still go one step further. We can also write the command we have just typed into the terminal in an executable text file, and instead execute this file. Whereas this does not look very straightforward on a first glance, it dramatically increases our flexibility: we can now write several commands into the same script - for example, running r.avaflow for several times with different input. We can go for a beer, to sleep, or even on holiday, and see the results when we have returned, without any intervention required in between.

It is recommended to create a folder for each project we are working on. So, let us create the folder projects/test in our home directory. Within this folder, let us create a text file with the name test.avaflow.start.sh. The suffix sh stands for shell script, which is the most common type of executable file in LINUX environments. We now copy the text we have executed from the command line into this script, and save our changes. Then, back in the terminal, we have to change to the directory where the script is stored, and execute the script by typing sh and its name:

cd projects/test/

sh test.avaflow.start.sh

You will find the folder with the results of the simulation in the directory projects/test. Using shell scripts, you cannot only run several simulations at a time. They also help you to:

• Import tiff or ascii rasters into GRASS (command r.in.gdal)
• Create generic landcapes (command r.mapcalc)
• Preprocess raster maps (command r.mapcalc)
• Compute statistics of deposited volumes (command r.volume)

Examples of such start scipts can be found in the training data.

The names of all output raster maps, folders and files start with the prefix defined by the parameter prefix. r.avaflow 2.0 produces a set of output GRASS raster maps stored in the active mapset as well as a set of asc, gif, png and txt files stored in subfolders of the folder [prefix]_results:

• Input files for model evaluation, parameter sensitivity analysis and parameter optimization with the software AIMEC are stored in the subfolder [prefix]_aimec.
• Exported ascii raster maps for use with other software packages are stored in the subfolder [prefix]_ascii.
• Text files are stored in the subfolder [prefix]_files.
• Output hydrographs, maps and derived animations, profile plots and derived animations and ROC Plots are stored in the subfolder [prefix]_plots.

The subfolders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles, including their content, are produced only if the flag v (visualization of model results) is specified. In addition, the subfolder [prefix]_hydrograph depends on the specification of the parameters hydrograph and hydrocoords. The folder [prefix]_aimec is only produced with the flag m, whereas the folder [prefix]_profiles is only produced without the flag m.

If the flag v was not specified when executing the model, the visualization can be performed afterwards by running the command:

This step is only possible if the output raster maps still exist in the active GRASS mapset and the directory [prefix]_results has remained unchanged since the original computation. However, advanced users may manually modify the content of the text file [prefix]_documentation.txt.

r.avaflow 2.0 produces the following output raster maps which are, however, stored permanently only with the flag k:

• [prefix]_hflow[timestep]: flow height for the time step [timestep] in metres, one map is produced for each time step;
• [prefix]_vflowx[timestep]: flow velocity in direction of the flow path for the time step [timestep] in m/s, one map is produced for each time step;
• [prefix]_vflowy[timestep]: flow velocity normal to the flow path for the time step [timestep] in m/s, one map is produced for each time step;
• [prefix]_vflow[timestep]: flow velocity for the time step [timestep] in m/s, one map is produced for each time step;
• [prefix]_tflow[timestep]: flow kinetic energy for the time step [timestep] in J, one map is produced for each time step;
• [prefix]_pflow[timestep]: flow pressure for the time step [timestep] in Pa, one map is produced for each time step;
• [prefix]_basechange[timestep]: entrained or deposited height (change of basal surface) at the time step [timestep] in m, one map is produced for each time step - deposition is indicated by positive values, entrainment by negative values.

The number of the phase each map refers to is inserted before [timestep]. Maps without that number refer to the entire flow. Maxima of flow heights, flow kinetic energies, and flow pressures over the entire simulation are provided with the suffix _max. The final values of the flow heights and entrained/deposited heights are provided with the suffix _fin. [prefix]_elev_mod denotes the elevation in metres at the end of the simulated event (initial elevation corrected for entrainment and deposition.

With the flag m, mainly three output maps are produced, representing the impact indicator indices for maximum flow height ([prefix]_iii_hflow.png), for maximum flow kinetic energy ([prefix]_iii_tflow.png) and for maximum flow pressure ([prefix]_iii_pflow.png). The impact indicator index represents the number of simulation runs where the maximum value of the considered parameter computed for a pixel is equal or larger than the corresponding impact threshold (parameter imparam) divided by the total number of successful simulation runs.

In addition to the output maps, some preprocessed input maps are produced (with the flag m they may amount to a large number, depending on the number of model runs). All output maps and preprocessed input maps are also stored as ascii rasters in the folder [prefix]_ascii.

With the flag m, this folder contains the automatically generated input folders and files for the validation, parameter sensitivity analysis and optimization tool AIMEC. In order to enable applying this tool to the results produced by r.avaflow 2.0, the content and structure of this folder should not be manipulated manually.

Most of the output and preprocessed input raster maps stored in the active GRASS mapset are also exported as ascii rasters in order to be accessible with other software packages. The naming scheme follows the one used for the GRASS raster maps.

The following text files summarize the main parameters of the simulation or are needed for the construction of the maps and plots in the folders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles:

• [prefix]_averages.txt: portion of area of interest with an observed deposit and average of impact indicator index (with flag m only).
• [prefix]_ctrlpoints.txt: IDs, coordinates and selected result raster values (hmax = maximum flow height and the flow heights of all time steps, and hentrmax = maximum height of entrainment and the heights of entrainment of all time steps without flag m; iii = impact indicator index according to flow height with flag m) of all control points specified by the parameter ctrlpoints.
• [prefix]_directions[phase].txt: Velocities in x and y direction. This file is needed for the construction of arrows indicating flow direction and velocity in the maps stored in the folder [prefix]_maps (not applicable with flag m).
• [prefix]_documentation.txt: summary of the flags and parameters specified when starting the simulation as well as some further parameters needed for constructing the maps and plots in the folders [prefix]_hydrographs, [prefix]_maps and [prefix]_profiles when running r.avaflow 2.0 with the flag v only.
• [prefix]_hydinfo[hydrograph].txt, where [hydrograph] stands for the number of the hydrograph: output hydrograph data for each time step (not applicable with flag m). T = time passed; H = flow height; V = flow velocity; E = height of entrainment/deposition; Q = discharge. Numbers at the end of the headers indicate the phase the column refers to.
• [prefix]_hydprofiles.txt: x and y coordinates of the centre (xC, yC) and terminal points (x1, y1, x2, y2) of all hydrographs. Hydrograph IDs starting with I indicate input hydrograps, hydrograph IDs starting with O indicate output hydrographs. This file is not produced with flag m. The hydrograph profiles along with the IDs are shown in the maps stored in the folder [prefix]_maps.
• [prefix]_nout1.txt: two-line file, in the first line displaying the number of time steps, in the second line the model success (1=success; 2=failure, usually for numerical reasons). With the flag m, one file is produced for each model run, the number of the model run is added to the file name as suffix.
• [prefix]_param.txt: Raw input parameter file created by r.avaflow.py (only without flag m).
• [prefix]_params.txt: This file is produced along with the flag m only. It summarizes the input parameters for all model runs.
• [prefix]_profile.txt: Profile data illustrating elevation, flow height, depth of entrainment and deposition, flow velocity, flow kinetic energy and flow pressure at all time steps along the pre-defined profile (parameter profile). This file is needed for the construction of the profiles stored in the folder [prefix]_profiles (not applicable with flag m).
• [prefix]_summary.txt: summary file of the simulation, each line documenting the main parameters of each time step. With the flag m, one summary file is produced for each model run, the number of the model run is added as suffix. The content of the summary file(s) is largely identical to the screen output during routing of the flow. With model=1 the meanings of the column headers are: nout: number of time step; nsum: number of internal time step of the routing algorithm (these time steps are very short in order to ensure numerical stability); cfl: indicator for numerical stability (value should be smaller than 0.5); tdim: duration of one internal time step (1/100 s); tsum: time passed since start of the flow (s); dmax: maximum flow depth at time step (m); vmax: maximum flow velocity at time step (m/s); volume: flow volume at time step (cubic metres in the summary file; 1000s of cubic metres on the screen output); ekin: kinetic energy summed up over the entire flow (J in the summary file; MJ on the screen output). Numbers at the end of the headers indicate the phase the column refers to.
• [prefix]_time.txt: computational time (excluding visualization) in seconds.
• [prefix]_validation.txt: This file includes some model outcomes, in particular the validation scores derived from the comparison of the model results with the observed impact area (parameter impactarea) or the observed height of deposit (parameter hdeposit). Thereby, the modelled impact area is defined by the area where the maximum flow height is equal or larger than the threshold defined by the parameter imparam. The modelled deposit is defined by the area where the flow height at the end of the simulation is equal or larger than the threshold defined by the parameter imparam.

• Hydrograph plots are produced for all input and output hydrographs (flow height and discharge) defined by the parameter hydrocoords, using the data stored in the files [prefix]_hydinfo[hydrograph].txt and [prefix]_hydprofiles.txt. The hydrograph profiles along with the IDs are shown in the maps stored in the folder [prefix]_maps. This file is not produced with flag m.
• Without the flag m, colour layouts of the simulated flow height ([prefix]_hflow[timestep].png), flow kinetic energy ([prefix]_tflow[timestep].png), flow pressure ([prefix]_pflow[timestep].png) and, if applicable, height of entrainment/deposition ([prefix]_basechange[timestep].png) are drawn for each time step [timestep]. They are stored in the sub-folder [prefix]_maps_timesteps. The release area and/or release hydrographs (parameter hydrocoords) are displayed as well as the flow path (parameter profile), the observed impact area (parameter impactarea), the observed deposit (parameter hdeposit) and the locations and IDs of the control points (parameter ctrlpoints), if specified. If the parameter orthophoto is not provided, a hillshade derived from the elevation raster map is shown as background. Otherwise, the orthophoto is shown as background.
  

  Maps of the maximum values (suffix _max) of flow height, flow kinetic energy and flow pressure over the entire simulation and a map of the final height of entrainment and deposition (suffix _fin) are drawn at the top level of the folder along with animated gifs illustrating the evolution of the flow parameters during the simulation. The suffix c in the file names of the gifs refers to compressed versions. With the flag m, only three maps are drawn, illustrating the impact indicator indices for maximum flow height ([prefix]_iii_hflow.png), for maximum flow kinetic energy ([prefix]_iii_tflow.png) and for maximum flow pressure ([prefix]_iii_pflow.png).

• Without the flag m, series of vertical profiles following the flow path (parameter flowpath) are constructed, illustrating the flow height (put on top of the terrain) along with bar plots representing flow velocity ([prefix]_vflow[timestep].png), flow kinetic energy ([prefix]_tflow[timestep].png) and flow pressure ([prefix]_pflow[timestep].png). They are stored in the sub-folder [prefix]_profiles_timesteps. Animated gifs visualizing the complete sequences of profiles are stored at the top level of the folder. The suffix c in the file names of the gifs refers to compressed versions.
• In the case of multiple model runs (flag m and parameter cores) and the availability of a map of the observed deposit (parameter hdeposit), 2 ROC Plots relating impact indicator index map to the observed deposition area are created: one plot includes the entire study area ([prefix]_roc.png), the second one uses a normalized area of true negative predictions ([prefix]_rocn.png). The area under the curve AUCROC is displayed as the key indicator for the prediction quality.

Two additional text files, aucroc.txt and aucrocn.txt, are produced along with the ROC Plots. These files are stored directly in the working directory and display the prefix of the computation along with the corresponding value of AUCROC: in aucroc.txt, the value refers to the entire area of interest, while in aucrocn.txt the true negative area is normalized. These two files are not overwritten during the next execution of r.avaflow. Instead, a new line is added each time r.avaflow is run with the flag v. This facilitates the analysis of the AUCROC values in case of multiple executions of r.avaflow 2.0.