# Preparing your input file

    library(ambre)
    set.seed(2024)

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")`.