Analyse a model — analyse_model • floodam.building

This function performs a comprehensive analysis of a building model, allowing users to selectively execute different stages of the analysis pipeline, including loading the model, extracting information, calculating damages, generating hydraulic inputs, plotting results, and saving the model.

Usage

analyse_model(
  model,
  type = "",
  stage = "",
  hazard_range = getOption("floodam_building_hazard_range"),
  path = getOption("floodam_building_path"),
  file_name = getOption("floodam_building_file_name"),
  type_building = getOption("floodam_building_type_building"),
  version_building = NULL,
  verbose = getOption("floodam_building_verbose")
)

Arguments

model: either a character, name given to the model or an object of class model
type: character, type of model that is loaded, default to ""
stage: character, stage of the analysis to execute, default to nothing; admitted values: "load", "extract", "damaging", "hydraulic", "graph", "save", and "display". If "all" is specified, all available stages will be executed. See details
hazard_range: if damaging are calculated, gives the range for hazard, default to getOption("floodam_building_hazard_range")
path: list of useful paths, default to getOption("floodam_building_path")
file_name,: list of useful file names, default to getOption("floodam_building_file_name")
type_building: character, type of building file (building or yaml)
version_building: character, version of building model to be used
verbose: boolean, will floodam tells what it is doing, default to getOption("floodam_building_verbose")

Value

an object of class model. See details

Details

The stage parameter is a crucial parameter for controlling exactly which parts of the analysis pipeline are executed. It is a character vector that specifies the sequence of analysis steps (or "stages") to run:

"load" loads input file and creates object of class model. This is the first stage to run
"extract" extracts information from the model and organizes it in tables. This is the second stage you need to run and requires the "load" stage to have been run first
"damaging" computes the damage function of the model. Requires the "extract" stage
"hydraulic" extracts hydraulic input data from model and computes damage functions by room and segment of external wall (input in function analyse_hydraulics()). Requires the "extract" stage
"graph" saves plots in a temporary directory. The number of plots created depends on the stage: Top and side view of building modeled and, if "damaging" stage has been called already, the damaging function. Requires the "extract" stage
"save" saves data in the path stored in the model object created by the function. Requires the "extract" stage
"display" displays plot of top view of the building model. Requires the "extract" stage
"all" executes stages "load", "extract", "damaging", "hydraulic", "graph", "save" and "display"

The function returns a model object, which is a list with the following elements (the presence of each element depends on the stages executed):

"name": a character string representing the model name
"category": a character string representing the damage category
"path": a list containing file paths related to the model
"file_name": a list containing the file names related to the model
"data_table": a list of data.frames containing information about the building components and their attributes. Created/updated by the "extract" stage
"value": a list of data.frames with information about (i) the monetary value of the building and its contents and (ii) the internal and external surfaces calculated with the input data. Created by the "extract" stage
"damaging": a list containing damage calculations. Created by the "damaging" stage
"hydraulic": a list containing input data for a hydraulic model. Created by the "hydraulic" stage
"dam_room_wall": a list containing damage calculations by room and wall segment. Created by the "hydraulic" stage.

Examples


# Example 1
# declaring input and output paths
model_path = list(
  data = system.file("extdata", package = "floodam.building"),
  output = tempdir()
)

# analyzing model 'adu_t' of type 'adu' using stages *load*, *extract* and 
# *damaging* 
analyse_model(
  model = "adu_t", 
  type = "adu", 
  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
#> 		- furniture
#> 	- missing (not found):
#> 	... 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.03 secs
#> More information availabe at /tmp/RtmpVBDWD4/model/adu/adu_t/adu_t.log

# Example 2
# using preloaded model 'adu_t_basement' 
model = adu_t_basement

# extracting model data
model = analyse_model(model = model, stage = "extract")
#> Extracting building information for 'adu_t_basement'...
#> 	- extracted:
#> 		- parameter
#> 		- storey
#> 		- room
#> 		- wall
#> 		- opening
#> 		- coating
#> 		- furniture
#> 	- missing (not found):
#> 	... Informations successfully extracted for 'adu_t_basement'
#> Computing some values for 'adu_t_basement'...
#> 	... Informations successfully extracted for 'adu_t_basement'
#> End of analysis for 'adu_t_basement'. Total elapsed time 0.11 secs
#> More information availabe at /tmp/R-test/model/adu/adu_t_basement/adu_t_basement.log

# calculating damage function
model = analyse_model(model = model, stage = "damaging")
#> Computing damage for 'adu_t_basement'...
#> 	... Damaging successfully computed for 'adu_t_basement'
#> End of analysis for 'adu_t_basement'. Total elapsed time 1.03 secs
#> More information availabe at /tmp/R-test/model/adu/adu_t_basement/adu_t_basement.log

# calculating hydraulic inputs
model = analyse_model(model = model, stage = "hydraulic")
#> Extracting input data for hydraulic model for 'adu_t_basement'...
#> 	... converting hydraulic input data in 'adu_t_basement' to meters
#> 	... hydraulic input data in 'adu_t_basement' succesfully converted to meters
#> 	... hydraulic input data successfully extracted for 'adu_t_basement'
#> Computing damage by room and external wall segment for 'adu_t_basement'...
#> 	... Damaging by room and external wall successfully computed for 'adu_t_basement'
#> End of analysis for 'adu_t_basement'. Total elapsed time 1.17 secs
#> More information availabe at /tmp/R-test/model/adu/adu_t_basement/adu_t_basement.log