Getting started

floodam.building produces flood damage functions for built assets from a comprehensive inventory of those assets, covering materials and components, the position in space (xyz) of those components and the furnishing present (if any).

This vignette provides a high-level description of the overall workflow you will use with floodam.building. The specifics of some of the steps in this workflow are covered in separate vignettes.

Basic workflow

The process starts by providing the input mentioned above. To make things easier, floodam.building is shipped with various testing models that include the specific inputs needed. The models are available in your library’s installation folder, so just ask R to locate them. You will also need to provide a folder where the output of floodam.building can be stored (our example uses a temporary directory):

#> Loading required package: floodam.building
library(floodam.building)

#> set up model to use example shipped with floodam
model_path = list(
data = system.file("extdata", package = "floodam.building"),
output = tempdir()
)

Let us use the model called adu_t. This model proposes a 4-room house where three of them are organized around a central living room. To generate a flood damage function for this model, we use the function analyse_model() specifying load, extract and damaging as analysis’ stages:

model = analyse_model(
  "adu_t",
  stage = c("load", "extract", "damaging"),
  path = model_path
)
#> Loading model 'adu_t'...
#>  - Structure of building.xml of 'adu_t' has been successfully checked
#>  ... successful
#> Extracting building information for 'adu_t'...
#>  - extracted:
#>          - parameter
#>          - storey
#>          - room
#>          - wall
#>          - opening
#>          - coating
#>  - missing (not found):
#>          - furniture
#>  ... Informations successfully extracted for 'adu_t'
#> Computing some values for 'adu_t'...
#>  ... Informations successfully extracted for 'adu_t'
#> Computing damage for 'adu_t'...
#>  ... Damaging successfully computed for 'adu_t'
#> End of analysis for 'adu_t'. Total elapsed time 1.88 secs
#> More information availabe at /tmp/RtmpQ1In9b/model//adu_t/adu_t.log

The function analyse_model() accepts input in both XML and YAML formats. By default, the function looks for the XML format, so, if you prefer to work with the YAML format, make sure that you specify type_building = "yaml" when calling the function.

The output of the function analyse_model() is an object of class model. This class of objects can be navigated like nested R lists. Also, congratulations are in order! You have now successfully processed your first model and have created your first damage function. It is available inside the object model, along with other information. Let us explore it further.

Basic visualization

floodam.building counts on methods to visualize key information stored in model. For example, since floodam.building uses highly detailed and spatialized information of the dwelling, you can generate the dwelling plan.

#> visualization of the house's plan
plot(model, view = "top")

You also have available a default visualization of the damage function estimated for this building. To generate it, simply change the value of the parameter view.

#> visualization of the house's damage function
plot(model, view = "damaging")

Now let us stop at this diagram for a moment to understand what you are seeing. floodam.building calculates the damage functions according to two different parameters: flood water depth and flood duration. The bottom half of the figure contains three different plots, each one presenting damage curves for flood events up to three different durations: 12 hours, 60 hours and 120 hours. Any of these plots also presents three different “curves”:

  • Furniture: damage function corresponding to furniture only.
  • Building: damage function corresponding to structural elements of the building only.
  • Total: damage function aggregating both structural elements and furniture.

The top half of the figure contains two different plots. The top-right graph offers a comparison of the total damage curves for the three aforementioned flood durations. The top-left graph represents the amount of damage (in EUR) per flood depth (x-axis) and flood duration (y-axis).

Accessing data

The data to produce the plots above is stored within the object model, in the slot damaging. Since objects of class model can be navigated like nested lists, the information is accessible via R’s standard operators for indexing operations.

Flood damage functions are stored as matrices. You will find several two main types of functions:

  • The absolute flood damage function, which expresses the damage in monetary units (EUR). It is located in the slot labelled absolute and available for the structural elements (building), for the furniture if any (furniture) and for the aggregation of both (total).

  • The surface flood damage function, which expresses the damage in monetary units (EUR) per unit of surface (squared meters). It is located in the slot labelled surface and available for the structural elements (building), for the furniture if any (furniture) and for the aggregation of both (total).

Let us check one of these matrices. In them, rows represent the different flood depths for which floodam.building calculates the damage (the default resolution depth step is 10 cm) while columns represent the maximum duration of the flood event. In this example, the damage estimated for a 6-hour flood event with a flood depth of 40 cm is EUR 8211.42.

#> visualization of the house's damage function
head(model[["damaging"]][["absolute"]][["total"]], 10) |> knitr::kable()
0 12 24 36 48 60 72 84 96 108 120 132 144
0 0 0.000 0.000 0.000 0.000 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
10 0 6005.500 6005.500 6005.500 6005.500 7781.50 7781.50 7781.50 7781.50 7781.50 7781.50 7781.50 7781.50
20 0 7589.500 7589.500 7589.500 7589.500 9437.50 9437.50 9437.50 9437.50 9437.50 9437.50 9437.50 9437.50
30 0 8211.420 8211.420 8211.420 8211.420 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18
40 0 8211.420 8211.420 8211.420 8211.420 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18 13173.18
50 0 8211.420 8211.420 8211.420 8211.420 13325.34 13325.34 13325.34 13325.34 13325.34 13325.34 13325.34 13325.34
60 0 8477.908 8477.908 8477.908 8477.908 13452.33 13452.33 13452.33 13452.33 13452.33 13452.33 13452.33 13452.33
70 0 8744.396 8744.396 8744.396 8744.396 13579.31 13579.31 13579.31 13579.31 13579.31 13579.31 13579.31 13579.31
80 0 9010.884 9010.884 9010.884 9010.884 13705.81 13705.81 13705.81 13705.81 13705.81 13705.81 13705.81 13705.81
90 0 9277.372 9277.372 9277.372 9277.372 13832.31 13832.31 13832.31 13832.31 13832.31 13832.31 13832.31 13832.31

Learn more

The rest of the vignettes provide more information on several different aspects. Please check: