Preparing your input file

Every ambre analysis starts from one Excel file describing your reuse scenario. Get that file right and the rest of the pipeline just runs; get a label wrong and create_scenario() stops with an error. This vignette is the reference for building that file: the nine columns, their allowed values, and the traps to avoid. If you have not seen a run yet, read vignette("a-get-started", package = "ambre") first.

Anatomy of the file

The file has ten columns, one row per situation you want to assess. Here is a bundled two-row example – use it as a template:

readxl::read_excel(
  system.file("input_1culture_2pop.xlsx", package = "ambre")
) |>
  knitr::kable()

CropName	Area	PopulationName	nb_population	PathName	STEPtreatmentName	CollectiveTreatmentName	InitialProcessName	SupplementaryProcessName	nb_day_decay
Tomato	10	Irrigation staff	1	Ingestion of water droplets during maintenance of the irrigation system	Q.1 - Activated Sludge	Q.2 - Maturation Pond	Q.6 - Chlorination	E.1.1 - Micro-sprinkler	NA
Corn seed	35	Maintenance staff	1	Ingestion following direct contact with a part of the plant during crop maintenance, followed by hand-to-mouth contact	Q.1 - Activated Sludge	Q.2 - Maturation Pond	Q.6 - Chlorination	P.5 - Natural die-off	3

Column	Meaning
`CropName`	the crop being irrigated
`Area`	irrigated area, in hectares
`PopulationName`	the exposed population for this crop
`nb_population`	how many people are exposed
`PathName`	the exposure pathway (how the water reaches the population exposed)
`STEPtreatmentName`	the Wastewater Treatment Plant (WWTP) process
`CollectiveTreatmentName`	additional treatment after the WWTP, common to all crop
`InitialProcessName`	individual process (equipment or practice) step currently in place
`SupplementaryProcessName`	individual process (equipment or practice) step of a new scenario to evaluate
`nb_decay`	an on-field barrier (equipment or practice)

Each row is one crop x population x pathway combination. A scenario with two crops, each exposing three populations, is six rows.

Validity bounds and empty cells

Two numeric columns are range-checked when you build the scenario:

Area must be greater than 0 and below 10000 hectares;
nb_population must be greater than 0 and below 5000.

The four barrier columns (STEPtreatmentName, CollectiveTreatmentName, InitialProcessName, SupplementaryProcessName) may be left empty (NA) when a scheme does not use that slot – for instance a row with a plant step and a field barrier but no collective treatment. On the other hand, a cell may contain several processes separated by commas (i.e. “P.9 - Peeling, P.8 - Drying”). The name columns, by contrast, must match a known value exactly (indicated in instruction sheet), and that is what the rest of this vignette is about.

The allowed values

The names you type are resolved against config_ambre, the bundled database. Printing the catalogs straight from that object guarantees this list stays true to the package you actually have installed.

Crops – the CropName column:

config_ambre$crop[, c("CropName", "CropDescription", "CropHeight")]
#> # A tibble: 6 × 3
#>   CropName  CropDescription                                           CropHeight
#>   <chr>     <chr>                                                          <dbl>
#> 1 Corn seed On the surface, more than 50 cm away from the irrigation…         50
#> 2 Potato    At ground level                                                    0
#> 3 Onion     Underground                                                       -1
#> 4 Apple     On the surface, more than 50 cm away from the irrigation…         50
#> 5 Salad     At ground level                                                    0
#> 6 Tomato    On the surface, more than 25 cm away from the irrigation…         25

Populations – the PopulationName column:

dplyr::distinct(
  config_ambre$path$description[, c("PopulationID", "PopulationName")]
)
#> # A tibble: 6 × 2
#>   PopulationID PopulationName   
#>          <dbl> <chr>            
#> 1            1 Irrigation staff 
#> 2            2 Maintenance staff
#> 3            3 Harvesting staff 
#> 4            4 Local residents  
#> 5            5 Passerby         
#> 6            6 Consumers

Exposure pathways – the PathName column must match exactly a PathDescription listed below:

config_ambre$path$description[, c("PathID", "PathDescription", "PopulationName")] |>
  knitr::kable()

PathID	PathDescription	PopulationName
1	Ingestion of water droplets during maintenance of the irrigation system	Irrigation staff
2	Ingestion of water droplets during a power outage	Irrigation staff
3	Inhalation of aerosols while moving through fields during irrigation	Irrigation staff
4	Ingestion following direct contact with a part of the plant during crop maintenance, followed by hand-to-mouth contact	Maintenance staff
5	Ingestion following direct contact with the soil during crop maintenance, followed by hand-to-mouth contact	Maintenance staff
6	Ingestion following direct contact with a part of the plant during harvesting, followed by hand-to-mouth contact	Harvesting staff
7	Ingestion following direct contact with the ground during harvesting, followed by hand-to-mouth contact	Harvesting staff
8	Ingestion of water droplets during irrigation near residential areas	Local residents
9	Inhalation of aerosols during irrigation near residential areas	Local residents
10	Ingestion of water droplets while moving near irrigated areas	Passerby
11	Inhalation of aerosols while driving near irrigated areas	Passerby
12	Consumption of the final product potatoes	Consumers
13	Consumption of the final product onion	Consumers
14	Consumption of the final product apple	Consumers
15	Consumption of the final product salad	Consumers
16	Consumption of the final product tomato	Consumers
17	Consumption of the final product surface and leafy (e.g., salad)	Consumers
18	Consumption of the final product surface, not leaf (e.g., tomato)	Consumers
19	Consumption of the final product through the soil roots	Consumers

Barriers and treatments – any of the STEPtreatmentName, CollectiveTreatmentName, InitialProcessName or SupplementaryProcessName cells must be one or more of these names, separated by a **comma* (Q. = treatment, E. = equipment, P. = practice):

sort(unique(config_ambre$treatment$processes$TreatmentName))
#>  [1] "E.1 - Automatic irrigation"                   
#>  [2] "E.1.1 - Micro-sprinkler"                      
#>  [3] "E.1.2 - Surface drip irrigation"              
#>  [4] "E.1.3 - Subsurface drip irrigation"           
#>  [5] "E.2 - Mechanised crop maintenance"            
#>  [6] "E.3 - Mechanised harvesting"                  
#>  [7] "E.4 - Signage"                                
#>  [8] "E.5 - Fences"                                 
#>  [9] "E.7 - Sheet mulching"                         
#> [10] "E.8 - Personnal Protective Equipement"        
#> [11] "P.1 - Non-edilble crop"                       
#> [12] "P.10 - Rinsing with drinking water"           
#> [13] "P.11 - Washing with disinfectant"             
#> [14] "P.2 - Distance of 70m"                        
#> [15] "P.3 - Night-time irrigation"                  
#> [16] "P.4 - Shutdown irrigation in strong winds"    
#> [17] "P.5 - Natural die-off"                        
#> [18] "P.6 - Agri-food processing"                   
#> [19] "P.7 - Cooking"                                
#> [20] "P.8 - Drying"                                 
#> [21] "P.9 - Peeling"                                
#> [22] "Q.1 - Activated Sludge"                       
#> [23] "Q.2 - Maturation Pond"                        
#> [24] "Q.3 - UV Reactor"                             
#> [25] "Q.4 - Sand Filter and UV"                     
#> [26] "Q.5 - Microfiltration and UV"                 
#> [27] "Q.6 - Chlorination"                           
#> [28] "Q.7 - Microfiltration and UV and Chlorination"

The pathogens you simulate are not set in the Excel file – you pass them to run_qmra_intial_situation() / run_qmra_supplementary_process(). The 6 that can be simulated are :

library(dplyr)

pathogen <- config_ambre$health %>%
  filter(!if_else(is.na(infection_to_illness) & is.na(dalys_per_case), TRUE, infection_to_illness == dalys_per_case, missing = FALSE))
pathogen$PathogenName
#> [1] "Campylobacter jejuni"   "Escherichia coli"       "Norovirus"             
#> [4] "Rotavirus"              "Cryptosporidium parvum" "Giardia duodenalis"

More pathogen are available in config_ambre$health but parameters nfection_to_illness and dalys_per_case are not yet available.

Known pitfalls

Spelling is exact and unforgiving. PathName must reproduce a PathDescription exactly, including case and punctuation; CropName must be Potato, Corn seed, etc. A stray “s” is enough to fail. Even a bundled example, input_cas_apprentissage_complet.xlsx, is worth cross-checking:
```
vals <- readxl::read_excel(
  system.file("input_cas_apprentissage_complet.xlsx", package = "ambre")
)$CropName
setdiff(unique(vals), config_ambre$crop$CropName)   # crop names with no match
#> character(0)
```
Anything returned here is a label the database will not recognise. To help you complete the Excel file without making any mistakes, use the ‘instructions’ table, where you will find the names to use.
PathName implies its population. Each pathway is tied to a population in the database, so keep PopulationName consistent with the PathName you choose.

Validate your file

The check is simply to build the scenario. On a good file it returns a tibble with one row per input row and the resolved integer IDs:

scenario <- create_scenario(
  system.file("input_1culture_2pop.xlsx", package = "ambre")
)
scenario[, c("CropName", "CropID", "PopulationName", "PopulationID",
             "PathName", "PathID")]
#> # A tibble: 2 × 6
#>   CropName  CropID PopulationName    PopulationID PathName                PathID
#>   <chr>      <dbl> <chr>                    <dbl> <chr>                    <dbl>
#> 1 Tomato         6 Irrigation staff             1 Ingestion of water dro…      1
#> 2 Corn seed      1 Maintenance staff            2 Ingestion following di…      4

If a name is missing or misspelled, create_scenario() stops rather than guessing. Fix the offending cell against the catalogs above and try again. Once the scenario builds, you are ready to run the assessment – see vignette("a-get-started", package = "ambre") – and to inspect or extend the database behind these names in vignette("h-config-ambre", package = "ambre").