Understanding essential input files

In this vignette, we will cover the contents for all the essential inputs used to build damage functions for a farm. As an example, we will build damage functions for a winery.

The winery in our example is shown in the image below. It is composed of 10 plots and 5 different grape varieties which each have different yields, prices and crop calendars.

Typology folder

Crop vulnerability

The typology folder is mainly used to declare the correspondance between a crop and its vulnerability type. This correspondance takes the form of a data.frame which loaded by default from a file named floodam.csv file in the typology folder. This data.frame contains 2 columns:

• type1 indicates which crop vulnerability should be used for type2 crop
• type2 indicates the name of the crop

In our example, it looks like this:

floodam.csv

type1	type2
vineyard	variety_1
vineyard	variety_2
vineyard	variety_3
vineyard	variety_4
vineyard	variety_5
vineyard	vineyard_floodam

As you can see, all vineyard varieties have the basic vineyard vulnerability. An optional supplementary row indicates a crop named vineyard_floodam which has been added to the example to show the difference between the basic vineyard damage function in floodam.agri and the ones specific to the winery.

Note that you do not have the obligation of creating the typology folder or the floodam.csv file. If you wish to do so, you will have to specify the typo argument when calling prepare_culture(), prepare_calendar() and prepare_action_value().

Crop names (optional)

An optional file that can be added to the typology folder named title.culture.csv is gives the correspondance between the “floodam” crop names and names that should be used for graphical visualisation. In our example, the correspondance data.frame looks like this:

title.culture.csv

code	titre
variety_1	Early vineyard 1
variety_2	Early vineyard 2
variety_3	Medium vineyard
variety_4	Late vineyard 2
variety_5	Late vineyard 2
vineyard_floodam	Default vineyard

Stat folder

The stat folder is used to keep files which give crops calendars, yields and various costs (treatment costs, harvest cost, selling prices, etc.). There is no need to include vineyard_floodam, to add any of these files because they will be found by default in your library’s installation folder.

Yields

Yields can be found in a file for which the name can be customized but should start with stat.<customized_name>.csv. If yields for several years are specified, a mean of all available data will be calculated.

• culture: name of crop
• yield.<year_n>: yield for a specific year
• yield.<year_n+x>: yield for another year (optional)

Below is a table showing the one used in our example.

stat.local.csv

culture	yield.2020	yield.2021
variety_1	50	55
variety_2	60	80
variety_3	70	70
variety_4	80	NA
variety_5	90	100

Crop calendars

Crop calendars can be found in a file which must be named calendar.csv. It is a data.frame which contains 3 columns:

• culture: name of crop
• phase: name of cropping stages, can either be a physiological stage (“maturity”) or a specific task (i.e. “harvest”)
• start.week: starting date of phase (in week)

In our example, it looks like this:

Action values

Action values can be found in a file which must be named action.value.table.csv. It is a data.frame which contain informations needed to evaluate costs of tasks to be performed when flooded or not. By default, there are the following 17 columns named accordingly to damagement files (see damagement section):

• culture: name of crop
• harvest: harvest cost (€/ha)
• sowing: sowing cost (€/ha)
• treatment: cost of one treatment (€/ha)
• replanting: replanting cost (€/ha)
• oversowing: oversowing cost, generally half the sowing cost (€/ha)
• chemical.harvest: cost of chemical harvest (€/ha)
• late.yield.loss: late yield loss rate when there is only one late yield defined (rate between 0 and 1)
• late.yield.loss1: first rate of late yield loss when there are several late yields defined (rate between 0 and 1)
• late.yield.loss2: second rate of late yield loss when there are several late yields defined (rate between 0 and 1)
• treatment.dose.fruitset: number of doses for the treatments in case of flood at the ‘fruitset’ phase
• treatment.dose.veraison: number of doses for the treatments in case of flood at the ‘veraison’ phase
• cut1.rate: first harvest cutting loss rate (rate between 0 and 1)
• cut2.rate: second harvest cutting loss rate (rate between 0 and 1)
• cut3.rate: third harvest cutting loss rate (rate between 0 and 1)
• half.rate: harvest loss rate (rate between 0 and 1)
• sale.price: crop sale price (€/ql, €/ql dried matter, €/hl)

Below is the content of this table in our example. Only the columns concerning the vineyard crop are shown:

Sample of action.value.table.csv (fields needed for vineyard crops)

culture	harvest	treatment	replanting	treatment.dose.fruitset	treatment.dose.veraison	sale.price
variety_1	595	80	26584	4	2	40
variety_2	595	80	26584	4	2	50
variety_3	595	80	26584	4	2	60
variety_4	595	80	26584	4	2	70
variety_5	595	80	26584	4	2	80

As you can see, in this example, we only modified the sale.price of each grape variety.

Damagement folder

The damagement folder is used to keep files which give vulnerability rules for each crop. Vulnerability files for base floodam crops are delivered in your library installation folder. In our example we will use the basic vulnerability rules for the vineyard crop which will be found by default thanks to the specified correspondance of crops and their vulnerability in floodam.csv or in the typo argument (see above).

For each crop, there is a folder in which there are four files:

• action.csv: rules for the calculation of action costs in case of flooding.
• damaging.complement.csv: complementary information to damaging.core.csv to build the damage functions.
• damaging.core.csv: core damage functions.
• rule.csv: rules for calculating loss of plant or yield.

Creating the damage functions

You are now briefed to understand damage functions are built ! You can run the code below to build the damage functions for this winery and view the results with the available functions to produce plots.

Step 1: declaring paths

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

#> Setting up environment paths (inputs and outputs)
output = file.path(tempdir(), "winery")
input = setNames(
    system.file("extdata", "vignettes", "winery", package = "floodam.agri"),
    "winery"
) # setting a name to input helps keep track of where data has been found
path = init_path(
  output = output,
  input = input,
  default = TRUE # default value, TRUE is obligatory to fetch the default
  # damagement files
)

Step 2: preparing data

#> Extracting damagement files to output
prepare_culture(path)

#> Extracting and copying calendars to output
prepare_calendar(path)

#> Building weight files
prepare_typology(path)

#> Preparing necessary action values and yields
prepare_action_value(path)

floodam.agri comes with a default visualisation function called plot_crop_calendar() which creates a plot of the different physiological phases for a set of crops. Use it to compare calendars as shown in the chunk below:

plot_crop_calendar(
  path,
  title_culture = TRUE,
  reference = "vineyard_floodam", # the reference crop appears above other crops
  order_phase = "harvest" # order crops by harvest date
)

Step 3.1: calculate_damaging()

Use calculate_damaging to build raw damage functions. For the purpose of our example, we will simplify the default flood resolution so that the running time is shorter by changing the loaded global data stored in the LEVEL variable.

#> Simplifying LEVEL
level = LEVEL
level[["duration"]] = seq(0, 5, 1)
level[["height"]] = seq(0, 100, 10)

#> Calculating damage function
damaging = calculate_damaging(
  path,
  culture = NULL,
  level = level,
  update.hazard = TRUE,
  retrieve = TRUE
)
#> Update of culture damaging functions:
#>  Processing variety_1... Finished in 1.05 secs
#>  Processing variety_2... Finished in 1.06 secs
#>  Processing variety_3... Finished in 1.03 secs
#>  Processing variety_4... Finished in 1.05 secs
#>  Processing variety_5... Finished in 1.06 secs
#>  Processing vineyard_floodam... Finished in 1.05 secs
#> ... processed in 6.30 secs

Step 3.2: combine_damaging()

Use combine_damaging to combine the raw damage functions in one file along with associated hazard parameters.

#> Combine damage into one file for each damage type
combine = combine_damaging(
  path = path,
  damage.culture = damaging,
  retrieve = "total" # one of c("total", "yield.annual", "yield.differed",
  # "replanting", "soil", material")
)
#> Processing combinations of damaging curves...    ... Finished in 0.70172 secs

floodam.agri comes with several default visualisation functions. For example you can use plot_damage_function() which creates a plot of the damage curves for a one or more crops. Use it to compare damage functions as shown in the chunk below:

#> Show plot
plot_damage_function(
  path = path,
  damage = "total",
  legend = TRUE,
  main = "Damage curves for all grape varieties of the winery",
  current = 1,
  duration = 4,
  height = 100
)

You can also view disaggregated damage curves thanks to plot_disaggregated_damage(). Here is an example of its use below:

#> Show plot
plot_disaggregated_damage_function(
  path = path,
  culture = "variety_1",
  current = 1,
  duration = 4,
  height = 100
)

Step 3.3: aggregate_damage()

Use aggregate_damage to simplify the damage curves by aggregating weeks into seasons, durations into periods, etc. In the chunk below we use the default aggregation parameters provided by floodam.agri.

#> Aggregate damage
agg_damaging = aggregate_damage(
  path,
  damage_origin = "total" # default
)

As shown in getting started vignette, you can use plot_aggregated_damage to view the damage curves produced by aggregate_damage().

#> Show plot
plot_aggregated_damage(
  path = path,
  damage = "total.aggregate", # default
  culture = "variety_1",
  current = "light", # default
  duration = c("short", "long"), # default
  legend = "include"
)