moduleOut3Plot.rst

out3Plot: Plots

This module gathers various functions for creating visualisations of simulation results, analysis results, etc. Details on these functions can be found in :pyout3Plot. General plot settings can be found in :pyout3Plot.plotUtils and the respective configuration file out3Plot/plotUtilsCfg.ini.

In the following sections, some of these plotting functions are described in more detail.

plotUtils

:pyout3Plot.plotUtils gathers the general settings used for creating plots as well as small utility functions.

makeColorMap

When plotting raster data, :pyout3Plot.plotUtils.makeColorMap is useful for deriving a suitable colormap. As inputs, this function requires: :

makeColorMap(colormapDict, minimum level, maximum level, continuous flag)

By setting the continuous flag, there is the option to return a continuous or discrete colormap. Within this function, several default colormaps are available, as for example the ones used to visualize flow thickness, flow velocity or pressure. These can be initialised by:

from avaframe.out3Plot import plotUtils
plotUtils.cmapThickness

A colormap dictionary is loaded with information about the colormap, specific colors and levels corresponding to the default option of visualising pressure in com1DFA. If the flag continuous is set to True, this function returns a colormap object and a norm object fitted to the minimum and maximim values provided as input parameters. If the continuous flag is set to False, it will return a colormap object and a norm object representing the discrete levels defined in the dictionary. The maximum level provided in the inputs will be added as maximum level of the colorscale. See the two example plots below, where the predefined levels correspond to 1, 10, 25, and 50 kPa and the maximum level provided as input is 320 kPa.

left panel: continuous colormap. right panel: default discrete colormap used for pressure in com1DFA

In order to define customized discrete colorbars, there are different options. Firstly, provide a colorbar dictionary that follows the structure in the example dictionary: :

from cmcrameri import cm as cmapCameri
colormapDict = {'cmap': cmapCameri.hawaii.reversed(),
                'colors': ["#B0F4FA", "#75C165", "#A96C00", "#8B0069"],
                'levels': [1.0, 10.0, 25.0, 50.0]}

It is also possible to provide key colors only. In this case the number of levels will match the number of colors and are equally distributed between the provided maximum and minimum value. If neither colors nor levels are provided in the dictionary, a default of six levels will be used. Another option is to just provide a colormap object instead of a dictionary. Here the continuous flag will be ignored and a colormap object as well as a norm object fitted to the maximum and minimum value will be returned.

outQuickPlot

:pyout3Plot.outQuickPlot is used to generate plots of raster datasets, as for example the simulation results of :pycom1DFA.

generatePlot

:pyout3Plot.outQuickPlot.generatePlot creates two plots, one plot with four panels, first dataset, second dataset, the absolute difference of the two datasets and the absolute difference capped to a smaller range of differences (ppr: +- 100kPa, pft: +-1m, pfv:+- 10ms-1). The difference plots also include an insert showing the histogram and the cumulative density function of the differences. The second plot shows a cross- and along profile cut of the two datasets. In addition to the plots, a dictionary is returned with information on the plot paths, as well as the statistical measures of the difference plots, such as mean, max and min difference. Details on the required inputs for this function can be found in :pyout3Plot.outQuickPlot.generatePlot.

Output plot from generatePlot on peak flow thickness results

quickPlotBench

:pyout3Plot.outQuickPlot.quickPlotBench calls :pyout3Plot.outQuickPlot.generatePlot to generate all comparison plots between the results of two simulations. This requires information on simulation names and paths to the simulation results and the desired result type. For further details have a look at :pyout3Plot.outQuickPlot.quickPlotBench.

quickPlotSimple

:pyout3Plot.outQuickPlot.quickPlotSimple is a bit more general, as it calls :pyout3Plot.outQuickPlot.generatePlot to generate the comparison plots between of two raster datasets of identical shape in a given input directory, without requiring further information. For further details have a look at :pyout3Plot.outQuickPlot.quickPlotSimple.

To run

An example on how to create the difference plots for two raster datasets of identical shape is provided in :pyrunScript/runQuickPlotSimple

• first go to AvaFrame/avaframe
• copy avaframeCfg.ini to local_avaframeCfg.ini and set your avalanche directory and the flag showPlot
• specifiy input directory, default is data/NameOfAvalanche/Work/simplePlot

• run:

  python3 runScripts/runQuickPlotSimple.py

generateOnePlot

:pyout3Plot.outQuickPlot.generateOnePlot creates one plot of a single raster dataset. The first panel shows the dataset and the second panel shows a cross- or along profile of the dataset. The function returns a list with the file path of the generated plot. For further details have a look at :pyout3Plot.outQuickPlot.generateOnePlot.

Output plot from generatePlotOne on peak flow thickness results

quickPlotOne

:pyout3Plot.outQuickPlot.quickPlotOne calls :pyout3Plot.outQuickPlot.generateOnePlot to generate the plot corresponding to the input data. For information on the required inputs have a look at :pyout3Plot.outQuickPlot.quickPlotOne.

To run quickPlotOne

An example on how to create this plot from a given input directory or from the default one data/NameOfAvalanche/Work/simplePlot, is provided in :pyrunScript/runQuickPlotOne

• first go to AvaFrame/avaframe
• copy avaframeCfg.ini to local_avaframeCfg.ini and set your avalanche directory and the flag showPlot
• copy out3Plot/outQuickPlotCfg.ini to out3Plot/local_outQuickPlotCfg.ini and optionally specify input directory

• run:

  python3 runScripts/runQuickPlotOne.py

in1DataPlots

:pyout3Plot.in1DataPlots can be used to plot a sample and its characteristics derived with :pyin1Data.computeFromDistribution, such as: cumulative distribution function (CDF), bar plot of sample values, probability density function (PDF) of the sample, comparison plot of empirical- and desired CDF and comparison of empirical- and desired PDF.

statsPlots

:pyout3Plot.statsPlots can be used to create scatter plots using a peak dictionary where information on two result parameters of avalanche simulations is saved. This peak dictionary can be created using the function :pyana4Stats.getStats.extractMaxValues of :pyana4Stats.getStats. This can be used to visualize results of avalanche simulations where a parameter variation has been used or for e.g. in the case of different release area scenarios. If a parameter variation was used to derive the simulation results, the plots indicate the parameter values in color. If the input data includes information about the 'scenario' that was used, for example different release scenarios, the plots use different colors for each scenario. There is also the option to add a kde (kernel density estimation) plot for each result parameter as marginal plots. An example on how these plotting functions are used and exemplary plots can be found in moduleAna4Stats:getStats

Additionally, a plotting function for visualising probability maps is provided by :pyout3Plot.statsPlots.plotProbMap, where probability maps can be plotted including contour lines. An example on how these plotting function is used and an exemplary plot can be found in moduleAna4Stats:probAna.

plotValuesScatter

:pyout3Plot.statsPlots.plotValuesScatter produces a scatter plot of result type 1 vs result type 2 with color indicating values of the varied parameter.

plotValuesScatterHist

:pyout3Plot.statsPlots.plotValuesScatterHist produces a scatter plot with marginal kde plots of result type 1 vs result type 2 with color indicating different scenarios (optional).

plotHistCDFDiff

:pyout3Plot.statsPlots.plotHistCDFDiff generates the histogram plot and CDF plot of a input dataset.

Output plot from plotHistCDFDiff on peak pressure results from two simulations of avaAlr

particle analysis plots

:pyout3Plot.particleAnalysisPlots can be used to create plots of particle properties for a :pycom1DFA simulation, where particles refer to two-dimensional numerical columns (see DFAnumerics:Discretization). The particle properties can be analyzed over time or transformed into a thalweg following coordinate system using :pyana3AIMEC. Additional functions to compute velocity envelopes, i.e. the min and max values of the particle properties over time but also along the thalweg are used (see :pyout3Plot.outParticleAnalysis.velocityEnvelope and :pyout3Plot.outParticleAnalysis.velocityEnvelopeThalweg). The provided run script runScripts/runParticleAnalysis.py, provides an example of calling :pycom1DFA to perform an avalanche simulation and then perform the respective particle analysis including a coordinate transformation and producing the final plots, which are examplary shown here:

Particle properties summary plot showing a map view of the affected area (by all particles) based on the peak flow velocity field, the tracked particles trajectories in dark blue with the superimposed thalweg line. The panels in the middle row show the evolution of particles' trajectory lengths, velocity and acceleration over time. In the rightmost panels, the particle data has been transformed into a thalweg following coordinate system and particle properties are shown along the thalweg coordinate S_XY. The light blue area extends from the min value found for all particles to the max value and the blue solid lines indicate the values of the tracked particles.

The left panel shows a map view of the peak flow velocity field for the avalanche simulation with superimposed thalweg line. The top right plot shows the thalweg profile and the 'velocity altitude', i.e. the thalweg elevation plus the peak flow velocity cross max values along the thalweg to the power of two divided by two times the gravity acceleration, these values are then colored using the peak flow velocity cross max values. In the legend, the runout length ΔS_xy, altitude difference Δz and corresponding runout anlge α, measured using the peak flow velocity field and a threhsold of 1 ms^− 1 (default setting) are provided. The lower right panel shows the thalweg-time diagram for the respective simulation.

The left panel shows a map view of the peak flow velocity field for the avalanche simulation with superimposed thalweg line. The right panel shows the velocity envelope for all particles, the mean and median particle velocity and the spread of altitudes covered by the particle positions along the thalweg coordinate.

Note

In order to create the presented plots, in addtion to the particle data also result fields of peak flow velocity are required.

To run

• first go to AvaFrame/avaframe
• copy avaframeCfg.ini to local_avaframeCfg.ini and set your desired avalanche directory name
• create an avalanche directory with required input files - for this task you can use moduleIn3Utils:Initialize Project
• in AvaFrame/avaframe/out3Plot, copy outParticleAnalysisCfg.ini to local_outParticleAnalysisCfg.ini and set your desired configuration for the analysis, the avalanche simulation run in com1DFA_override, the aimec analysis in ana3AIMEC_override and the range time diagram in distanceTimeAnalysis_override section

• run: :

  python3 runScripts/runParticleAnalysis.py