ana3AIMEC (Automated Indicator based Model Evaluation and Comparison, [Fis13]) is a post-processing
module to analyze and compare results from avalanche simulations.
For this purpose, avalanche simulation results are transformed into an avalanche thalweg following coordinate system
(see Fig. 14, Fig. 15, Fig. 16),
which enables the comparison of different simulations (for example varying parameter sets,
or performed with different models) of the same avalanche catchment, in a standardized way.
There is also the option to compare simulation results to a reference data set, which can consist of a reference
point, line or polygon. The simulation results are analysed regarding a chosen result variable (peak pressure, thickness or
velocity) and a threshold of this variable. The derived runout point and/or line is then compared to the reference point, line or polygon.
For further information, have a look at the Section Analyze with respect to reference data sets.
In AvaFrame/avaframe/runScripts, two different run scripts are provided and show examples
on how the post-processing module ana3AIMEC can be used:
full Aimec analysis for simulation results of one computational module (from 1 simulation to
x simulations). runScripts.runAna3AIMEC.runAna3AIMEC()
using Aimec to compare the results of two different computational modules (one reference
for the reference computational module and multiple simulations in the other computational module).
runScripts.runAna3AIMECCompMods.runAna3AIMECCompMods()
In all cases, one needs to provide a minimum amount of input data. Below is an example workflow
for the full Aimec analysis, as provided in runScripts/runAna3AIMEC.py:
DEM (digital elevation model) as .asc file with ESRI grid format
Note
The spatial resolution of the DEM and its extent can differ from the result raster data.
Spatial resolution can also differ between simulations. If this is the case, the spatial
resolution of the reference simulation results raster is used (default) or, if provided,
the resolution specified in the configuration file (cellSizeSL) is used.
This is done to ensure that all simulations will be transformed and analyzed using the
same spatial resolution.
avalanche thalweg in LINES (as a shapefile named NameOfAvalanche/Inputs/LINES/path_aimec.shp), the line needs to cover the entire affected area but is not allowed
to exceed the DEM extent
a method to define the reference simulation. By default, an arbitrary simulation
is defined as reference. This can be changed in the ana3AIMEC/local_ana3AIMECCfg.ini
as explained in Defining the reference simulation.
consider adjusting the default settings to your application in the Aimec configuration
(in your local copy of ana3AIMEC/local_ana3AIMECCfg.ini) regarding the domain transformation, result types, runout computation and figures
If a comparison to reference data sets is desired, additionally the following inputs are required:
reference point, line and/or polygon in avalancheDir/Inputs/REFDATA (as shp file with corresponding suffix, options are *_POINT.shp, *_LINE.shp, *_POLY.shp)
Note
The reference point shp file must only contain a single point.
There is the option to define a runout area for the analysis, which is based on the slope angle of the avalanche thalweg.
This can be defined in the Aimec configuration by setting the defineRunoutArea flag to True.
The start of runout area is then determined by finding the first point on the thalweg profile where the slope angle falls below the
startOfRunoutAreaAngle value and all points upslope of the a additionally provided split point are ignored (see Fig. 16).
This functionality requires an additional input:
a splitPoint in POINTS (as a shapefile named NameOfAvalanche/Inputs/POINTS/splitPoint.shp),
this point is then snapped onto the thalweg based on the shortest horizontal distance
output figures in NameOfAvalanche/Outputs/ana3AIMEC/anaMod/
csv file with the results in NameOfAvalanche/Outputs/ana3AIMEC/anaMod/
(a detailed list of the results is described in Analyze results)
Note
anaMod refers to the computational module that has been used to create the avalanche simulation results and is specified in
the ana3AIMEC configuration.
in your local copy of ana3AIMEC/ana3AIMECCfg.ini you can adjust the default settings (if not, the standard settings are used)
enter path to the desired NameOfAvalanche/ folder in your local copy of avaframeCfg.ini
run:
python3runScripts/runAna3AIMEC.py
Note
In the default configuration, the analysis is performed on the simulation result files located in NameOfAvalanche/Outputs/anaMod/peakFiles, where anaMod is specified in the aimecCfg.ini. There is also the option to directly provide a path to an input directory to the ana3AIMEC.ana3AIMEC.fullAimecAnalysis(). However, the peak field file names need to have a specific format: A_B_C_D_E.asc, where:
A - releaseAreaScenario: refers to the name of the release shape file
B - simulationID: needs to be unique for the respective simulation
C - simType: refers to null (no entrainment, no resistance), ent (with entrainment), res (with resistance), entres (with entrainment and resistance)
D - modelType: can be any descriptive string of the employed model (here dfa for dense flow avalanche)
E - result type: is pft (peak flow thickness) and pfv (peak flow velocity)
AIMEC (Automated Indicator based Model Evaluation and Comparison, [Fis13]) was developed
to analyze and compare avalanche simulations. The computational module presented here is inspired
from the original AIMEC code. The simulations are analyzed and compared by projecting the
results along a chosen poly-line (same line for all the simulations that are compared)
called avalanche thalweg. The raster data, initially located on a regular and uniform grid
(with coordinates x and y) is transformed based on a regular non uniform grid (grid points are not
uniformly spaced) that follows the avalanche thalweg (with curvilinear coordinates (s,l)).
This grid can then be “straightened” or “deskewed” in order to plot it in the (s,l)
coordinates system.
The simulation results (two dimensional fields of e.g. peak flow velocities, pressure or
flow thickness) are processed in a way that it is possible to compare characteristic
values that are directly linked to the flow variables such as maximum peak flow thickness,
maximum peak flow velocity or deduced quantities, for example maximum peak pressure, pressure
based runout (including direct comparison to possible references, see
Area indicators) for different simulations. The following figure
illustrates the raster transformation process.
All two dimensional field results (for example peak flow velocities / pressure or flow thickness) can be
transformed into the curvilinear system using the previously described method. The maximum and
average values of those fields are computed in each cross-section (l direction) along the thalweg.
For example the maximum \(A_{cross}^{max}(s)\) and average \(\bar{A}_{cross}(s)\) of
the two dimensional distribution \(A(s,l)\) is:
The runout point is always given with respect to a peak result field (\(A(s,l)\) which could be
peak pressure or flow thickness, etc.) and a threshold value (\(A_{lim}>0\)).
The runout point (\(s=s_{runout}\)) and the respective \((x_{runout},y_{runout})\)
in the original coordinate system, correspond to the last point in flow direction where the
chosen peak result \(A_{cross}^{max}(s)\) is above the threshold value \(A_{lim}\).
Note
It is very important to note that the position of the runout point depends on the chosen
threshold value and peak result field. It is also possible to use
\(\bar{A}_{cross}(s)>A_{lim}\) instead of \(A_{cross}^{max}(s)>A_{lim}\)
to define the runout point.
This length depends on what is considered to be the beginning of the avalanche \(s=s_{start}\).
It can be related to the release area, to the transition point (first point where the slope
angle is below \(30^{\circ}\)), to the runout area point (first point where the slope
angle is below \(10^{\circ}\)) or in a similar way as \(s=s_{runout}\) is defined
saying that \(s=s_{start}\) is the first point where \(A_{cross}^{max}(s)>A_{lim}\)
(this is the option implemented in ana3AIMEC.ana3AIMEC.py).
The runout length is then defined as \(L=s_{runout}-s_{start}\). In the analysis results,
this is called \(deltaSXY\), whereas \(s_{runout}\) gives the length measured from
the start of the thalweg to the runout point.
From the maximum values along path of the distribution \(A(s,l)\) calculated in
Mean and max values along thalweg, it is possible to calculate
the global maximum (MMA) and average maximum (AMA) values of the two dimensional
distribution \(A(s,l)\):
\[MMA = \max_{\forall s \in [s_{start},s_{runout}]} A_{cross}^{max}(s) \quad\mbox{and}\quad
AMA = \frac{1}{s_{runout}-s_{start}}\int_{s_{start}}^{s_{runout}} A_{cross}^{max}(s)ds\]
When comparing the runout area (corresponding to a given threshold \(A_{cross}^{max}(s)>A_{Lim}\))
of two simulations, it is possible to distinguish four different zones. For example, if the
first simulation (sim1) is taken as reference and if True corresponds to the assertion
that the avalanche reached this zone (reached means \(A_{cross}^{max}(s)>A_{Lim}\)) and
False the avalanche did not reached this zone, those four zones are:
TP (true positive) zone: green zone on Fig. 15 , sim1 = True sim2 = True
FP (false positive) zone: blue zone on Fig. 15 , sim1 = False sim2 = True
FN (false negative) zone: red zone on Fig. 15 , sim1 = True sim2 = False
TN (true negative) zone: gray zone on Fig. 15 , sim1 = False sim2 = False
The two simulations are identical (in the runout zone) when the area of both FP and FN are zero.
In order to provide a normalized number describing the difference between two simulations,
the area of the different zones is normalized by the area of the reference simulation
\(A_{ref} = A_{TP} + A_{FP}\). This leads to the 4 area indicators:
\(\alpha_{TP} = A_{TP}/A_{ref}\), which is 1 if sim2 covers at least the reference
\(\alpha_{FP} = A_{FP}/A_{ref}\), which is a positive value if sim2 covers an area
outside of the reference
\(\alpha_{FN} = A_{FN}/A_{ref}\), which is a positive value if the reference covers
an area outside of sim2
\(\alpha_{TN} = A_{TN}/A_{ref}\) (this value may not be of great interest because it
depends on the width and length of the entire domain of the result rasters (s,l))
Identical simulations (in the runout zone) lead to \(\alpha_{TP} = 1\) , \(\alpha_{FP} = 0\)
and \(\alpha_{FN} = 0\)
From the analysis of the release mass (\(m_r\) at the beginning, i.e \(t = t_{ini}\)),
total mass (\(m_t\) at the end, i.e \(t = t_{end}\)) and entrained mass
(\(m_e\) at the end, i.e \(t = t_{end}\)) it is possible to calculate the
growth index \(GI\) and growth gradient \(GG\) of the avalanche:
To apply a complete Aimec analysis, a reference simulation needs to be defined.
The analysis of the other simulations will be compared to the one of the reference simulation.
The reference simulation can be determined by its name (or part of the name) or based on some
configuration parameter and value (to adjust in the local copy of ana3AIMEC/ana3AIMECCfg.ini)
if it comes from the com1DFA module (or any computational module that provides a configuration):
based on simulation name
one needs to provide a non-empty string in the AIMEC configuration
file for the referenceSimName parameter. This string can be a part or the full name of the
reference simulation. A warning is raised if several simulation match the criterion (can happen
if part of the name is given) and the first simulation found is arbitrarily taken as reference.
based on some configuration parameter
one needs to provide a varParList (parameter or list of parameters separated by |) in the AIMEC configuration file as well as the desired sorting order
(ascendingOrder, True by default) for these parameters and optionally a referenceSimValue.
The simulations are first going to be sorted according to varParList and ascendingOrder
(this is done by the pandas function sort_values).
The reference simulation is either the first simulation found after sorting if no referenceSimValue
or the simulation matching the referenceSimValue provided (closest value if the parameter is a
float or integer, case insensitive for strings). If multiple simulations match the criterion,
the first simulation is taken as reference and a warning is raised.
First, the transformation from (x,y) coordinate system (where the original rasters lie in) to
(s,l) coordinate system is applied given a new domain width (domainWidth). This is done by
ana3AIMEC.aimecTools.makeDomainTransfo(). A new grid corresponding to the new domain
(following the avalanche thalweg) is built with a cell size defined by the reference simulation
(default) or cellSizeSL if provided. The transformation information are stored in
a rasterTransfo dictionary (see ana3AIMEC.aimecTools.makeDomainTransfo() for more details).
The simulation results (for example peak velocities / pressure or flow thickness) are
projected on the new grid using the transformation information by
ana3AIMEC.aimecTools.assignData(). The projected results are stored in
the newRasters dictionary.
This results in the following plot:
Fig. 16 Alr avalanche coordinate transformation and peak pressure field reprojetion.
Calculates the different indicators described in the Theory section
for a given threshold. The threshold can be based on pressure, flow thickness, …
(this needs to be specified in the configuration file). Returns a resAnalysisDF dataFrame
with the analysis results (see ana3AIMEC.ana3AIMEC.postProcessAIMEC() for more details).
In this dataFrame there are multiple columns, one for each result from the analysis
(one column for runout length, one for MMA, MAM…) and one row for each simulation analyzed.
To include a comparison to reference data sets, the flag includeReference in your local copy of ana3AIMEC/ana3AIMECCfg.ini
must to be set to True. After reading the coordinates of the point, line or polygon from the respective shp file, a raster with the same extent
as the DEM is created with values indicating which cells are affected by the features (see ana3AIMEC.ana3AIMEC.postProcessReference()).
This raster is then transformed into the thalweg following coordinate system. From the transformed rasters, a runout line/point is computed.
This is done by identifying for each L coordinate (across thalweg) the corresponding S coordinate (along thalweg) for
the point, line or polygon feature (see ana3AIMEC.aimecTools.computeRunoutLine()).
In case of the polygon the S coordinate furthest in thalweg direction is chosen.
A runout line is also derived from the simulation results. This is done by identifying for each simulation, the
last point along the thalweg where the chosen threshold of the chosen runoutResType is still exceeded (similar to the
identification of the runout point), for each L coordinate (across thalweg).
For each simulation the derived runout line is compared to the runout line derived from the reference line or polygon, whereas
in the case of the reference point, a distance between this point and the simulation runout point is computed.
The derived difference measures are saved to the aimec result DataFrame, see List of Aimec result variables
and several plots are created, see Reference data set analysis plots.
Plots and saves the desired figures and writes results in resAnalysisDF to a csv file.
By default, Aimec saves five summary plots plus three plots per simulation comparing the
numerical simulations to the reference. The five summary plots are:
“slComparisonStats” shows the peak field specified in the configuration and computed runout points
in the top panel, wherease in the bottom panel the statistics
in terms of cross maximum peak value along profile are plotted (mean, max and quantiles)
Fig. 18 Reference peak field runout area with runout points and distribution of cross max values of peak field along thalweg
if only two simulations are compared, additionally the difference between
the two simulations in terms of peak values along profile are shown for
peak pressure, peak flow velocity and peak flow thickness in “slComparison”.
Fig. 19 Maximum peak fields comparison between two simulations
“ROC” shows the normalized area difference between reference and other simulations.
“deltaSXvsrunoutAngle” and “pfvFieldMaxvspftFieldMax” show the distribution of these values for all the simulations.
There is the option to indicate scenarios in these plots using the available simulation parameters
Acutally other parameter vs parameter plots can be added by setting the parameter names in the ana3AIMEC configuration
in the section called PLOTS.
Fig. 21 DeltaSXY vs runout angle of all sims colorcoded using the simType
Fig. 22 Max field values of peak flow velocity vs flow thickness of all sims colorcoded using the simType
“thalwegAltitude” shows the cross section max values of peak flow thickness as bars on top of the thalweg elevation profile.
The colors of the bars correspond to the cross section max values of the respective peak flow velocity.
Using the specified velocityThresholdValue (aimecCfg.ini section PLOTS), runout length \(/Delta S_{xy}\),
elevation drop \(/Delta z\) and the corresponding runout angle \(\alpha\) are computed.
The red dots indicate the location of overall max peak flow velocity and thickness and the grey shaded area the runout area.
The plots “_hashID_ContourComparisonToReference” and “_hashID_massAnalysis” where “hashID” is the name of the simulation show the 2D difference to the reference,
the statistics associated and the mass analysis figure (this means these figures are created for each simulation).
Fig. 24 The area comparison panel (top left) shows the false negative (FN in blue, which is where the reference field exceeds the
threshold but not the simulation) and true positive (TP in red, which is where the simulation field exceeds the
threshold but not the reference) areas. The contour comparison panel (top right) shows the contour lines of the reference (full lines) and the simulation (dashed lines)
of the desired result fields in the runout area. It also shows the difference between the reference and simulation
and computes the repatriation of this difference (Probability Density Function and Cumulative Density Function
of the difference)
Fig. 25 The mass analysis plot shows the evolution of the total and entrained mass during
the simulation and compares it to the reference
referenceLineTransfo_referenceFeature plot where referenceFeature corresponds to either the reference point, line or polygon, As an example we here show the transformation plot of a polygon:
Fig. 26 Reference polygon in cartesian coordinate system already indicating which coordinates have been identified as
runout line in the thalweg following (SL) coordinate system (left panel), transformed into
the thalweg following coordinate system with identified runout line in blue (right panel).
runoutLineComparison plot where the runout line derived from the simulation is compared to the runout line derived from the reference line or polygon is compared and some statistical measures are provided:
Fig. 27 Difference between runout line derived from simulation using the runoutResType and threhsoldValue from
the ana3AIMEC configuration and the reference data set, in this example the line is derived from
the reference polygon. The root mean squared error is computed over all points where both, the runout
line derived from the simulation and the reference data set have points.
The result variables listed below are partly included in the above described plots and are also saved to the Aimec results directory as ..resAnalysisDF.csv, with one row per simulation. In the following, the resType represents the result type(s) set in the aimecCfg.ini for the parameter resTypes.
resTypeFieldMax: maximum value of resType simulation result (simulation coordinate system)
resTypeFieldMin: minimum value of resType simulation result (simulation coordinate system), values smaller than a threshold (minValueField in aimecCfg.ini) are masked
resTypeFieldMean: average value of resType simulation result (simulation coordinate system), values smaller than a threshold (minValueField in aimecCfg.ini) are masked
resTypeFieldStd: standard deviation of resType simulation result (simulation coordinate system), values smaller than a threshold (minValueField in aimecCfg.ini) are masked
maxresTypeCrossMax: maximum value of cross profile maximum values of resType field (transformed in thalweg-following coordinate system)
sRunout: the last point along the thalweg (\(S_{XY}\)) where the transformed resType field (cross profile maximum values) still exceeds a threshold value (thresholdValue in aimecCfg.ini)
lRunout: the cross profile coordinate (\(L_{XY}\)) of the last point along the thalweg (\(S_{XY}\)) where the transformed resType field (cross profile maximum values) still exceeds a threshold value (thresholdValue in aimecCfg.ini)
xRunout, yRunout: x and y coordinates of the sRunout point (simulation coordinate system)
sMeanRunout, xMeanRunout, yMeanRunout: runout point coordinates derived with cross profile mean values of transformed resType field instead of cross profile maximum values
deltaSXY: distance along thalweg (\(S_{XY}\)) where the transformed resType field exceeds a threshold value (thresholdValue in aimecCfg.ini)
zRelease: altitude along thalweg where the transformed resType field first exceeds a threshold value (thresholdValue in aimecCfg.ini)
zRunout: altitude of the sRunout point
deltaZ: altitude difference between zRelease and zRunout
runoutAngle: corresponding runout angle based on deltaSXY and deltaZ
If reference data sets are included in analysis, additionally these outputs are provided:
refSim_Diff_sRunout: difference between simulation runout point and reference point along S coordinate
refSim_Diff_lRunout: difference between simulation runout point and reference point along S coordinate
runoutLineDiff_line_RMSE: root mean squared error between difference along S coordinate over all L coordinates between runout line derived from simulation and reference line
runoutLineDiff_poly_RMSE: root mean squared error between difference along S coordinate over all L coordinates between runout line derived from simulation and reference polygon
runoutLineDiff_line_pointsNotFoundInSim: number of runout points not found in simulation but in reference / all points found in reference runout line
runoutLineDiff_line_pointsNotFoundInRef: number of runout points not found in reference but in simulation / all points found in simulation runout line
runoutLineDiff_poly_pointsNotFoundInSim: number of runout points not found in simulation but in reference / all points found in reference runout polygon
runoutLineDiff_poly_pointsNotFoundInRef: number of runout points not found in reference but in simulation / all points found in simulation runout polygon
All configuration parameters are explained in ana3AIMEC/ana3AIMECCfg.ini (and can be modified in a local copy
ana3AIMEC/local_ana3AIMECCfg.ini):
### Config File - This file contains the main settings for the ana3AIMEC run## Set your parameters# This file is part of Avaframe.# This file will be overridden by local_ana3AIMEC.ini if it exists# So copy this file to local_ana3AIMEC.ini, adjust your variables there# Optional settings-------------------------------[AIMECSETUP]# width of the domain around the avalanche path in [m]domainWidth=600# The cell size for the new (s,l) raster is automatically computed from the reference result file (leave the following field empty)# It is possible to force the cell size to take another value, then specify this new value below, otherwise leave empty (default).cellSizeSL=# define a runout area based on an angle of the thalweg profile (requires splitPoint in avaName/Inputs/POINTS as shpFile)defineRunoutArea=True# only used if defineRunoutArea=True - angle for the start of the run-out zonestartOfRunoutAreaAngle=10# data result type for general analysis (ppr|pft|pfd). If left empty takes the result types available for all simulationsresTypes=ppr|pft|pfv# data result type for runout analysis (ppr, pft, pfv)runoutResType=ppr# limit value for evaluation of runout (depends on the runoutResType chosen)thresholdValue=1# contour levels value for the difference plot (depends on the runoutResType chosen)# use | delimiter (for ppr 1|3|5|10, for pft 0.1|0.25|0.5|0.75|1)contourLevels=1|3|5|10# max of runoutResType difference for contour lines plus capped difference in runoutResType plot (for example 1 (pft), 5 (ppr))diffLim=1# percentile to display when analyzing the peak values along profile# for example 5 (corresponding to 5%) will lead to the interval [2.5, 97.5]%percentile=5# chose interpolation method between 'nearest' and 'bilinear'interpMethod=bilinear# threshold distance [m]. When looking for the beta point make sure at least# dsMin meters after the beta point also have an angle bellow 10°dsMin=30# computational module that was used to produce avalanche simulations (to locate peakFiles)anaMod=com1DFA# two computational module that were used to produce avalanche simulations (to locate peakFiles) for comparison separated by |comModules=# if a computation module is benchmark, specify the test name (we assume that the testName folder is in AvaFrame/benchmarks/)testName=# parameter used for ordering the simulations - multiple possible; (e.g.relTh|deltaTh)varParList=# True if ascending ordering of simulations for varPar, False if descending orderascendingOrder=True# parameter value (first parameter in varParList) that should be used as reference simulation (e.g. 1.0)referenceSimValue=# OR directly set reference simulation by its name (name of simulation result file or parts of it that definitively# identify one particular simulation)referenceSimName=# unit of desired result parameter (e.g. m)unit=#---------------------------------------## Uncomment this section FILTER in your local copy of the ini file and add filter parameter and parameter values## see the example provided below for release thickness#[FILTER]## define parameter and corresponding values from the simulation configuration to filter simulations## multiple parameters are possible, just add them in a new line each##relTh = 0.75|0.9|0.8[PLOTS]# if extraPlots true additional analysis plots are createdextraPlots=True# for one to one comparison of two result variables or derived quantities with option to distinguish scenarios using scenario# comparison result variables options: resTypeFieldMax (or Min or Mean), maxresTypeCrossMax, sRunout, deltaSXY, zRelease,# zRunout, deltaH, relMass, finalMass, entMass, thalwegTravelAngle# comparison result variable 1compResType1=pfvFieldMax|deltaSXY# comparison result variable 2compResType2=pftFieldMax|runoutAngle# scenario parameter name used to colorcode comparison plots scenarioName=# interval of cross max values of pft to create bars in profile plotbarInterval=25# threshold of velocity to compute alpha anglevelocityThreshold=1.# plot save results flags------------------------[FLAGS]# Which value to plot in resultVisu# 1 = mean pressure data# 2 = growth index# 3 = max pressure datatypeFlag=3# number of simulations above which a (additional) density plot is creatednDensityPlot=100# Mass analysisflagMass=True#----------------------------------------------------------
