# Manipulating STICS XML files

    library(SticsRFiles)

# Introduction

The purpose of this document is to provide starting information about:

- how parameters are defined/structured in STICS XML files
- how to find information about parameters among an XML files set
- how to use functions for extracting data from XML STICS input files
- how to use functions for replacing data into them

Simple reproducible use cases based on 3 essential functions get_param_info, get_param_xml and set_param_xml are described in this document.

For the moment, queries for selecting information among `usms`, `soils` are limited. For example, getting soil parameters for a list of soils is possible, as getting usms informations using a usms list.

Queries inspecting elements downwards are not available yet; as for example, getting soil names/parameters using a criterion like `argi` values > 20.

Exploring files content for files sets are also possible, but not replacing parameters values.

This document has been generated using the latest STICS version V10.1.0.

# Understanding what are parameters in STICS XML files

## XML files structures describing parameters

XML files are self documented files and hierarchically structured. Syntaxic rules are based on what we call nodes (i.e. nodes names, similar to html tags) and attributes (nodes attributes values).

STICS XML files are filled with different kinds of parameters description structures according to their type/role in the model formalisms.

As we can see in the above XML file extract from a general parameter file:

- Parameters are grouped according to formalisms (in a `xml <formalisme>...</formalisme>` block)

- Parameters may be defined by single values This kind of definition is common for all files types and the parameter name is stored in the `nom` attribute of a `param` XML node. So the first parameter name in the example is `beta` and its value is `1.40000` (inside `param` tags).

- Option parameters (with or without attached parameters, eventually with sub-option) The corresponding parameter name for an option node is stored in an attribute named `nomParam` and the corresponding value is given in the attribute `choix` of the option node. For example, the value of the parameter `codesymbiose` is `2` in the example (choix=“2”).

        <formalisme nom="Water absorption and nitrogen content of the plant">
        <param format="real" max="2.0" min="1.0" nom="beta">1.40000</param>
            <param format="real" max="1.0" min="0.2" nom="lvopt">0.50000</param>
            <param format="real" max="0.1" min="0.01" nom="difN">0.04500</param>
            <param format="real" max="30.0" min="5.0" nom="plNmin">10.00000</param>
            <param format="real" max="50.0" min="0.0" nom="irrlev">20.00000</param>
            <param format="real" max="50.0" min="0.0" nom="QNpltminINN">0.00000</param>
            <option choix="2" nom="Nitrogen fixation by legumes" nomParam="codesymbiose">
            <choix code="1" nom="critical nitrogen"/>
                <choix code="2" nom="nodule activity">
                <option choix="2" nom="mineral nitrogen inhibition" nomParam="codefxn">
                    <choix code="1" nom="no effect"/>
                        <choix code="2" nom="nitrogen amount"/>
                        <choix code="3" nom="nitrogen concentration"/>
                    </option>
                </choix>
            </option>
        </formalisme>

- Parameters with several values (for soil layers, technical operations,…) Several values may be defined for example relatively to soil parameters (different layers) or for crop management operations (with time repetitions).

- Example from soil files In the above file extract for soil parameters, each set of parameters (included in `tableau` nodes) is repeated for each soil layer (layers names are set in the `nom` attributes from layer 1 to layer 5). The parameters names are defined in a `nom` attribute in each `colonne` XML tag.

      <sol nom="solcanne">
    ...
        </tableau_entete>
        <tableau nb_colonnes="8" nom="layer 1">
          <colonne nom="epc">20.00</colonne>
          <colonne nom="HCCF">46.80</colonne>
          <colonne nom="HMINF">26.20</colonne>
          <colonne nom="DAF">1.08</colonne>
          <colonne nom="cailloux">0.00</colonne>
          <colonne nom="typecailloux">1</colonne>
          <colonne nom="infil">50.00</colonne>
          <colonne nom="epd">10</colonne>
    ...
        </tableau>
        <tableau nb_colonnes="8" nom="layer 5">
          <colonne nom="epc">20.00</colonne>
          <colonne nom="HCCF">50.10</colonne>
          <colonne nom="HMINF">25.50</colonne>
          <colonne nom="DAF">0.99</colonne>
          <colonne nom="cailloux">0.00</colonne>
          <colonne nom="typecailloux">1</colonne>
          <colonne nom="infil">50.00</colonne>
          <colonne nom="epd">10</colonne>
    ...

- Example from tec files In the above file extract for crop management parameters, each set of parameters is repeated for each operation (undefined number) corresponding to an `intervention` node . Inside each `intervention` node, parameters names are defined in a `nom` attribute for each `colonne` XML tag.

      <formalisme nom="supply of organic residus">
        <ta nb_interventions="1" nom="interventions">
          <ta_entete nb_colonnes="7">
            <colonne nom="julres"/>
            <colonne nom="coderes"/>
            <colonne nom="qres"/>
            <colonne nom="Crespc"/>
            <colonne nom="CsurNres"/>
            <colonne nom="Nminres"/>
            <colonne nom="eaures"/>
          </ta_entete>
          <intervention nb_colonnes="7">
            <colonne nom="julres">112</colonne>
            <colonne nom="coderes">1</colonne>
            <colonne nom="qres">1.00</colonne>
            <colonne nom="Crespc">42.00</colonne>
            <colonne nom="CsurNres">60.00</colonne>
            <colonne nom="Nminres">0.00</colonne>
            <colonne nom="eaures">0.00</colonne>
          </intervention>
    ...
          <intervention nb_colonnes="7">
            <colonne nom="julres">220</colonne>
            <colonne nom="coderes">1</colonne>
            <colonne nom="qres">1.00</colonne>
            <colonne nom="Crespc">42.00</colonne>
            <colonne nom="CsurNres">60.00</colonne>
            <colonne nom="Nminres">0.00</colonne>
            <colonne nom="eaures">0.00</colonne>
          </intervention>
    ...

## Functions for XML files manipulations

Rules have been defined to easily search and extract information from XML files in order to simplify the way of using functions dedicated to XML files manipulations.

In some cases, information relative to upward dependence are needed for extracting parameters values, but in most cases only the parameters names are mandatory in functions arguments.

# Getting XML files examples from the `SticsRFiles` library

Several XML examples files have bee included in the package in order to use them in `reproducible` manipulations and results described in this document. These examples files are extracted from the JavaSTICS standard distribution (some of them have been renamed).

## Getting the XML files source directory

In xml_dir, we store the directory path of the XML files available in the SticsRFiles installation directory.

    xml_dir <- get_examples_path(file_type = "xml", stics_version = stics_version)

    # For linux > '/path/to/user/R/x86_64-pc-linux-gnu-library/3.6/SticsRFiles/ >
    # extdata/xml/examples/V10.0'

    # For windows > 'C:/Users/username/Documents/R/win-lib/3.6/SticsRFiles/ >
    # extdata/xml/examples/V10.0'

## Examples files

    xml_files <- list.files(path = xml_dir, pattern = ".xml$", full.names = TRUE)

    # Listing only the first three files of the entire list

    # For linux > [1]
    # '/path/to/user/R/x86_64-pc-linux-gnu-library/3.6/SticsRFiles/extdata/xml >
    # /examples/V10.0/file_ini.xml' > [2]
    # '/path/to/user/R/x86_64-pc-linux-gnu-library/3.6/SticsRFiles/extdata/xml >
    # /examples/V10.0/file_plt.xml' > [3]
    # '/path/to/user/R/x86_64-pc-linux-gnu-library/3.6/SticsRFiles/extdata/xml >
    # /examples/V10.0/file_sta.xml'

    # For windows > [1]
    # 'C:/Users/username/Documents/R/win-lib/3.6/SticsRFiles/extdata/xml/ >
    # examples/V10.0/file_ini.xml' > [2]
    # 'C:/Users/username/Documents/R/win-lib/3.6/SticsRFiles/extdata/xml/ >
    # examples/V10.0/file_plt.xml' > [3]
    # 'C:/Users/username/Documents/R/win-lib/3.6/SticsRFiles/extdata/xml/ >
    # examples/V10.0/file_sta.xml'

The corresponding files types to file names is given in the above table:

files | groups
--- | ---
file_ini.xml | initializations
file_plt.xml | plant
file_sta.xml | station
file_tec.xml | crop management
param_gen.xml | general
param_newform.xml | general (new formalisms)
sols.xml | soils
usms.xml | usms

## Copying files in a local directory

### A specific file

    # Setting a local directory path xml_loc_dir <- '/path/to/local/directory'

    file.copy(from = file.path(xml_dir, "sols.xml"), to = file.path(xml_loc_dir, "sols.xml"),
        overwrite = TRUE)
    #> [1] TRUE

### All files

    file.copy(from = xml_files, to = xml_loc_dir)
    #> [1]  TRUE  TRUE  TRUE  TRUE  TRUE  TRUE FALSE  TRUE

# Getting information about parameters

## Searching parameters names from files

The `get_param_info` function search is performed in a parameter table stored internally in the SticsRFiles library with respect to the model version (V10.1.0 as default one).

This function uses 2 optional arguments i.e.: * `param` a name or a part of a parameter name (or a vector of) for searching in parameters names * and/or `keyword` for searching in the parameters description information.

The information columns in the returned tibble are:

- `name`: parameter name
- `file`: file type of the parameter (keyword), see above table for correspondence with files

keyword | xml file | parameter kind
--- | --- | ---
STATION | _sta.xml | wheather station
PARPLT | _plt.xml | plant
PARAM | param_gen.xml | general
PARSOL | sols.xml | soil
PARTEC | _tec.xml | crop management
PARAMV6 | param_newform.xml | general parameters
USMXML | usms.xml | usm
USM/USMXML | usms.xml | usm
INIT | _ini.xml | initialisation
PARSOL/USM | sols.xml/usms.xml | soil or usm

- `min`: minimal bound
- `max`: maximal bound
- `definition`: parameter description

Whatever the arguments list is when calling the function, the returned tibble always contains all of these columns.

Information about `bounds` may be missing according to parameters kind.

> For example, for initialization or usm parameters and/or character type parameters (files names, residues type,…), bounds dont make any sense and `NA` is used as missing values.

### Getting all STICS parameters information

Using the `get_param_info` function without any argument, or with specifying the desired `STICS` version, allows to get a table containing all input parameters.

In the above code block, an extract of the returned information table is shown:

    param_names <- get_param_info()

    head(param_names)

    #>         name    file min max
    #> 1     aangst STATION   0 0.9
    #> 2 abscission  PARPLT   0   1
    #> 3      aclim STATION   4  25
    #> 4      adens  PARPLT  -2   0
    #> 5      adfol  PARPLT -10  10
    #> 6       adil  PARPLT   1   7
    #>                                                                          definition
    #> 1           coefficient of the Angstrom relationship for extraterrestrial radiation
    #> 2                                  fraction of senescent leaves falling to the soil
    #> 3 climatic component to calculate actual soil evaporation (Brisson & Perrier, 1991)
    #> 4                                                  Interplant competition parameter
    #> 5          parameter determining the leaf density evolution within the chosen shape
    #> 6                parameter of the critical dilution curve [Nplante]=adil MS^(-bdil)

The full parameters data.frame content is presented in the above paged table.

### Getting information about one or more parameters

If parameters names are known and are given with the right syntax, information can be retrieved as follows

    get_param_info(param = "albedo")

    get_param_info(param = c("albedo", "latitude", "humcapil"))

    #>                      name   file  min max                  definition
    #> 55                 albedo PARSOL 0.05 0.6 albedo of the bare dry soil
    #> 56   albedomulchplastique PARTEC 0.05 0.8     albedo of plastic cover
    #> 57     albedomulchresidus  PARAM 0.05 0.8       albedo of plant mulch
    #> 58  albedomulchresidus(1)  PARAM 0.05 0.8       albedo of plant mulch
    #> 59 albedomulchresidus(10)  PARAM 0.05 0.8       albedo of plant mulch
    #> 60 albedomulchresidus(11)  PARAM 0.05 0.8       albedo of plant mulch
    #> 61 albedomulchresidus(12)  PARAM 0.05 0.8       albedo of plant mulch
    #> 62 albedomulchresidus(13)  PARAM 0.05 0.8       albedo of plant mulch
    #> 63 albedomulchresidus(14)  PARAM 0.05 0.8       albedo of plant mulch
    #> 64 albedomulchresidus(15)  PARAM 0.05 0.8       albedo of plant mulch
    #> 65 albedomulchresidus(16)  PARAM 0.05 0.8       albedo of plant mulch
    #> 66 albedomulchresidus(17)  PARAM 0.05 0.8       albedo of plant mulch
    #> 67 albedomulchresidus(18)  PARAM 0.05 0.8       albedo of plant mulch
    #> 68 albedomulchresidus(19)  PARAM 0.05 0.8       albedo of plant mulch
    #> 69  albedomulchresidus(2)  PARAM 0.05 0.8       albedo of plant mulch
    #> 70 albedomulchresidus(20)  PARAM 0.05 0.8       albedo of plant mulch
    #> 71 albedomulchresidus(21)  PARAM 0.05 0.8       albedo of plant mulch
    #> 72  albedomulchresidus(3)  PARAM 0.05 0.8       albedo of plant mulch
    #> 73  albedomulchresidus(4)  PARAM 0.05 0.8       albedo of plant mulch
    #> 74  albedomulchresidus(5)  PARAM 0.05 0.8       albedo of plant mulch
    #> 75  albedomulchresidus(6)  PARAM 0.05 0.8       albedo of plant mulch
    #> 76  albedomulchresidus(7)  PARAM 0.05 0.8       albedo of plant mulch
    #> 77  albedomulchresidus(8)  PARAM 0.05 0.8       albedo of plant mulch
    #> 78  albedomulchresidus(9)  PARAM 0.05 0.8       albedo of plant mulch
    #>                        name    file  min max
    #> 55                   albedo  PARSOL 0.05 0.6
    #> 56     albedomulchplastique  PARTEC 0.05 0.8
    #> 57       albedomulchresidus   PARAM 0.05 0.8
    #> 58    albedomulchresidus(1)   PARAM 0.05 0.8
    #> 59   albedomulchresidus(10)   PARAM 0.05 0.8
    #> 60   albedomulchresidus(11)   PARAM 0.05 0.8
    #> 61   albedomulchresidus(12)   PARAM 0.05 0.8
    #> 62   albedomulchresidus(13)   PARAM 0.05 0.8
    #> 63   albedomulchresidus(14)   PARAM 0.05 0.8
    #> 64   albedomulchresidus(15)   PARAM 0.05 0.8
    #> 65   albedomulchresidus(16)   PARAM 0.05 0.8
    #> 66   albedomulchresidus(17)   PARAM 0.05 0.8
    #> 67   albedomulchresidus(18)   PARAM 0.05 0.8
    #> 68   albedomulchresidus(19)   PARAM 0.05 0.8
    #> 69    albedomulchresidus(2)   PARAM 0.05 0.8
    #> 70   albedomulchresidus(20)   PARAM 0.05 0.8
    #> 71   albedomulchresidus(21)   PARAM 0.05 0.8
    #> 72    albedomulchresidus(3)   PARAM 0.05 0.8
    #> 73    albedomulchresidus(4)   PARAM 0.05 0.8
    #> 74    albedomulchresidus(5)   PARAM 0.05 0.8
    #> 75    albedomulchresidus(6)   PARAM 0.05 0.8
    #> 76    albedomulchresidus(7)   PARAM 0.05 0.8
    #> 77    albedomulchresidus(8)   PARAM 0.05 0.8
    #> 78    albedomulchresidus(9)   PARAM 0.05 0.8
    #> 803                humcapil  PARSOL    2  10
    #> 1050               latitude STATION  -90  90
    #>                                                                                    definition
    #> 55                                                                albedo of the bare dry soil
    #> 56                                                                    albedo of plastic cover
    #> 57                                                                      albedo of plant mulch
    #> 58                                                                      albedo of plant mulch
    #> 59                                                                      albedo of plant mulch
    #> 60                                                                      albedo of plant mulch
    #> 61                                                                      albedo of plant mulch
    #> 62                                                                      albedo of plant mulch
    #> 63                                                                      albedo of plant mulch
    #> 64                                                                      albedo of plant mulch
    #> 65                                                                      albedo of plant mulch
    #> 66                                                                      albedo of plant mulch
    #> 67                                                                      albedo of plant mulch
    #> 68                                                                      albedo of plant mulch
    #> 69                                                                      albedo of plant mulch
    #> 70                                                                      albedo of plant mulch
    #> 71                                                                      albedo of plant mulch
    #> 72                                                                      albedo of plant mulch
    #> 73                                                                      albedo of plant mulch
    #> 74                                                                      albedo of plant mulch
    #> 75                                                                      albedo of plant mulch
    #> 76                                                                      albedo of plant mulch
    #> 77                                                                      albedo of plant mulch
    #> 78                                                                      albedo of plant mulch
    #> 803  threshold of soil gravimetric water content under which capillary rise occurs (dry soil)
    #> 1050                                                                     latitude of the site

### Getting parameters information using partial names matching

A search with incomplete names may be done as follows

    get_param_info(param = "hum")
    #>                   name    file min  max
    #> 392       codetesthumN PARAMV6   1    2
    #> 803           humcapil  PARSOL   2   10
    #> 804            humirac PARAMV6   0    2
    #> 805  humirac_decisemis  PARTEC   0    1
    #> 1249           profhum  PARSOL  10  150
    #> 1250 profhumrecolteuse  PARTEC   0  100
    #> 1251     profhumsemoir  PARTEC   0  100
    #> 1282    prophumtassrec   PARAM 0.8  1.8
    #> 1283    prophumtasssem   PARAM 0.8  1.8
    #> 1293          psihumin   PARAM  -5 -0.1
    #>                                                                                                                                                    definition
    #> 392                                            option to define automatic N fertilisation calculation: 1 = based on rainfall, 2 = based on soil water content
    #> 803                                                                  threshold of soil gravimetric water content under which capillary rise occurs (dry soil)
    #> 804  A revoir: 1 = la fonction F_humirac atteint un plateau (ancien code) / 2 = la fonction n atteint pas de plateau (identique a la phase germination-levee)
    #> 805                                     relative soil moisture threshold above which sowing is possible (0 = no sensitivity to drought, 1 = highly sensitive)
    #> 1249                                                                                                    maximum soil depth with an active biological activity
    #> 1250                                                         soil depth at which moisture is considered to allow harvesting (if soil compaction is activated)
    #> 1251                                                             soil depth at which moisture is considered to allow sowing (if soil compaction is activated)
    #> 1282                                                    soil moisture content (fraction of field capacity) above which compaction may occur and delay harvest
    #> 1283                                                     soil moisture content (fraction of field capacity) above which compaction may occur and delay sowing
    #> 1293                                                                                                      soil water potential corresponding to wilting point

    param_names <- get_param_info(param = c("alb", "hum"))

The found parameters data.frame content is presented in the above paged table.

## Searching parameters using keywords

The `keyword` argument (one or several possible strings) may be used to search in all textual columns as `name` or `description`.

    get_param_info(keyword = "hum")

    param_names <- get_param_info(keyword = c("alb", "hum"))

The found parameters data.frame content is presented in the above paged table.

# Getting parameters values from XML files

The `get_param_xml` function is used for extracting parameters values in XML files (for one file or a list of), optionally providing it a parameter name or a names list.

The result of the function call is a named list (with files names), and each element of the list contains a named list of the parameters values (see examples below).

For usms or soils parameter, a conditional selection may be used to filter parameter values respectively through a list of usms or soils.

Among STICS parameters files types, XML structure may be different, and they can contain either one/several occurrence(s) of parameters with scalar values (soils or usms description), or one/several occurrence(s) of parameters with vector values (along soil depth, crop management operations,…).

So parameters values extraction with the `get_param_xml` requires different input arguments combination to do so.

## Scalar parameters extraction

- For one parameter and one occurrence

    # Fixing files paths
    sols <- file.path(xml_loc_dir, "sols.xml")
    par_gen <- file.path(xml_loc_dir, "param_gen.xml")

    # A option parameter
    get_param_xml(par_gen, param = "codeactimulch")
    #> $param_gen.xml
    #> $param_gen.xml$codeactimulch
    #> [1] 1

    # A simple parameter
    get_param_xml(par_gen, param = "tnitopt")
    #> $param_gen.xml
    #> $param_gen.xml$tnitopt
    #> [1] 30

    # Using a conditional selection
    get_param_xml(sols, param = "argi", select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 30.2

- For one parameter and several occurences

    # For all soils

    get_param_xml(sols, param = "argi")
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1] 30.2 21.0 27.0 39.0  1.0 12.2 70.0 22.0  9.9 10.2 10.2 17.0 23.1 22.0 27.0
    #> [16] 30.7  0.1 27.3 25.0 10.2 25.0 28.6 36.0 29.0 10.2 21.2 22.2 13.0 17.0 15.0
    #> [31] 26.0 28.2 20.0

- For several parameters and several occurrences

    # For all soils
    get_param_xml(sols, param = c("argi", "pH"))
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1] 30.2 21.0 27.0 39.0  1.0 12.2 70.0 22.0  9.9 10.2 10.2 17.0 23.1 22.0 27.0
    #> [16] 30.7  0.1 27.3 25.0 10.2 25.0 28.6 36.0 29.0 10.2 21.2 22.2 13.0 17.0 15.0
    #> [31] 26.0 28.2 20.0
    #>
    #> $sols.xml$pH
    #>  [1] 7.00 7.00 7.00 7.00 5.36 8.10 7.00 7.00 6.10 8.40 8.30 7.00 7.00 7.00 7.00
    #> [16] 7.00 7.00 7.00 7.00 8.30 7.00 7.00 7.00 7.00 7.00 7.95 7.00 7.00 6.50 7.00
    #> [31] 7.86 7.84 5.00

- For several parameters and one occurrence (conditional selection)

    # For one soil
    get_param_xml(sols, param = c("argi", "pH"), select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 30.2
    #>
    #> $sols.xml$pH
    #> [1] 7

## Vector parameters extraction

Vectors parameters are typically present in soils file or crop management files.

- Getting all values for given parameters and all soils

    # For all soil layers
    get_param_xml(sols, param = c("epc", "infil"))
    #> $sols.xml
    #> $sols.xml$epc
    #>   [1]  20  20  20  20  20  30  30  30  30  30  30  30  30  30   0  20  20  20
    #>  [19]   0   0   5  10  15  15  15  30  30  30  30  30  10  10  10  10  40  25
    #>  [37]  30  35  30   0  10  20  20  20   0  30  30  30  30   0  30  30  30  30
    #>  [55]   0  10  30  20  40  80  15  15  30  30  30  25  30  35  30   0   5  15
    #>  [73]  20  50  80  20  20  20   0   0  50   0   0   0   0  22  33   7   0   0
    #>  [91]  25  20  40  35   0  30  30  30  30   0  25  20  40  35   0  30  20  20
    #> [109]  20 110  10  20  40  60  70  10  50  50   0   0  30  30  30  30   0  10
    #> [127]  30  30  30  15  25  25  25  45   0  10  40  70  40  40  20  20  60   0
    #> [145]   0  20  30  30  20  20  10  20  30  30  30  10  20  30  30  30  20   5
    #> [163]   0   0   0
    #>
    #> $sols.xml$infil
    #>   [1] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00
    #>  [13] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00  0.00  0.00  0.00  0.00
    #>  [25]  0.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00
    #>  [37] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00
    #>  [49] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00
    #>  [61] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 10.00 20.00
    #>  [73]  2.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00  0.00  0.00  0.00  0.00
    #>  [85]  0.00  0.00  0.00  0.00  0.00  0.00 50.00 50.00 50.00 50.00 50.00 50.00
    #>  [97] 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00  0.00  0.00  0.00
    #> [109]  0.00  0.00 50.00 50.00 50.00 50.00 20.00 50.00 50.00 50.00 50.00 50.00
    #> [121] 50.00 50.00 50.00 50.00 50.00  0.00  0.00  0.00  0.00  0.00  0.00  0.00
    #> [133]  0.00  0.00  0.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00 50.00
    #> [145] 50.00  0.00  0.00  0.00  0.00  0.00 30.00 30.00 30.00 30.00 30.00 15.00
    #> [157] 15.00 15.00 15.00 15.00 10.00  0.01 50.00 50.00 50.00

- Getting all values for given parameters (for a given soil, or crop management operation)

    # For all soil layers
    get_param_xml(sols, param = c("epc", "infil"), select = "sol", value = "solcanne")
    #> Warning: The `value` argument of `get_param_xml()` is deprecated as of SticsRFiles
    #> 1.0.0.
    #> ℹ Please use the `select_value` argument instead.
    #> This warning is displayed once every 8 hours.
    #> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
    #> generated.
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 20 20 20 20 20
    #>
    #> $sols.xml$infil
    #> [1] 50 50 50 50 50

    # For all irrigation supplies
    tec <- file.path(xml_loc_dir, "file_tec.xml")
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"))
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #>  [1] 178 185 193 198 200 204 207 211 214 218 221 232 239 249 257 264
    #>
    #> $file_tec.xml$amount
    #>  [1] 20 24 29 29 28 31 21 21 23 18 22 16 16 30 29 20

- Selecting with values index (among 5 soil layers, several irrigations supply)

    # For soil layers 1 to 3
    get_param_xml(sols, param = c("epc", "infil"), select = "sol", select_value = "solcanne",
        ids = 1:3)
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 20 20 20
    #>
    #> $sols.xml$infil
    #> [1] 50 50 50

    # For irrigation operations 1 to 5
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"), ids = 1:5)
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #> [1] 178 185 193 198 200
    #>
    #> $file_tec.xml$amount
    #> [1] 20 24 29 29 28

## Getting all parameters values from files

Using the function without any argument produces a list of all parameters values of a file.

    tec_param_values <- get_param_xml(tec)[[1]]
    # Displaying only a subset of the list
    head(tec_param_values, n = 10)
    #> $julres
    #> [1] 112
    #>
    #> $coderes
    #> [1] 1
    #>
    #> $qres
    #> [1] 1
    #>
    #> $Crespc
    #> [1] 42
    #>
    #> $CsurNres
    #> [1] 60
    #>
    #> $Nminres
    #> [1] 0
    #>
    #> $eaures
    #> [1] 0
    #>
    #> $code_auto_profres
    #> [1] 1
    #>
    #> $resk
    #> [1] 0.14
    #>
    #> $resz
    #> [1] 5

A files list may be used also to get all parameters as follows in the same list

    param_values <- get_param_xml(c(tec, sols))

    # Files list names
    names(param_values)
    #> [1] "file_tec.xml" "sols.xml"

    # param_values extract of 5 elements from each file sub-list
    head(param_values$file_tec.xml, n = 5)
    #> $julres
    #> [1] 112
    #>
    #> $coderes
    #> [1] 1
    #>
    #> $qres
    #> [1] 1
    #>
    #> $Crespc
    #> [1] 42
    #>
    #> $CsurNres
    #> [1] 60

    head(param_values$sols.xml, n = 5)
    #> $argi
    #>  [1] 30.2 21.0 27.0 39.0  1.0 12.2 70.0 22.0  9.9 10.2 10.2 17.0 23.1 22.0 27.0
    #> [16] 30.7  0.1 27.3 25.0 10.2 25.0 28.6 36.0 29.0 10.2 21.2 22.2 13.0 17.0 15.0
    #> [31] 26.0 28.2 20.0
    #>
    #> $norg
    #>  [1] 0.270 0.100 0.210 0.150 0.700 0.110 0.200 0.120 0.070 0.160 0.180 0.210
    #> [13] 0.140 0.120 0.140 0.140 0.070 0.080 0.200 0.180 0.100 0.120 0.150 0.120
    #> [25] 0.140 0.070 0.110 0.100 0.150 0.080 0.088 0.088 0.100
    #>
    #> $profhum
    #>  [1] 40.0 31.0 27.0 27.0 40.0 30.0 50.0 35.0 50.0 30.0 30.0 27.0 22.0 35.0 30.0
    #> [16] 30.0 30.0 30.0 30.0 28.0 30.0 40.0 40.0 30.0 31.5 30.0 30.0 30.0 15.0 35.0
    #> [31] 25.0 25.0 20.0
    #>
    #> $calc
    #>  [1]  0.00  0.70  3.70  0.00  0.82  0.60  0.00  1.00  9.00 65.30 64.10  3.00
    #> [13]  0.60  1.00  5.50  0.00  0.00  0.10  6.50 64.10  6.50  0.00  0.95  1.00
    #> [25] 64.10 13.00  0.10  7.60  1.00  0.00  1.67 11.10 32.50
    #>
    #> $pH
    #>  [1] 7.00 7.00 7.00 7.00 5.36 8.10 7.00 7.00 6.10 8.40 8.30 7.00 7.00 7.00 7.00
    #> [16] 7.00 7.00 7.00 7.00 8.30 7.00 7.00 7.00 7.00 7.00 7.95 7.00 7.00 6.50 7.00
    #> [31] 7.86 7.84 5.00

# Replacing parameters values in XML files

## Defining the output file using function arguments

The set_param_xml function allows to set the output file with the following optional arguments as follows:

- For overwriting the existing file: use `overwrite = TRUE`

- For specifying a new file name and directory: use `save_as` for giving the new xml file path (including the .xml extension)

In the following examples, the original file is always overwritten. Before and after each `set_param_xml` call, the original and new written values are checked with a `get_param_xml` call.

## Scalar parameters

- For one parameter and one occurrence

    ## An option parameter

    # Initial value
    get_param_xml(par_gen, param = "codeactimulch")
    #> $param_gen.xml
    #> $param_gen.xml$codeactimulch
    #> [1] 1

    # Setting a new one
    set_param_xml(par_gen, param = "codeactimulch", values = 2, overwrite = TRUE)

    # Controlling the written value
    get_param_xml(par_gen, param = "codeactimulch")
    #> $param_gen.xml
    #> $param_gen.xml$codeactimulch
    #> [1] 2

    ## A simple parameter

    # Initial value
    get_param_xml(par_gen, param = "tnitopt")
    #> $param_gen.xml
    #> $param_gen.xml$tnitopt
    #> [1] 30

    # Setting a new one
    set_param_xml(par_gen, param = "tnitopt", values = 29.5, overwrite = TRUE)

    # Controlling written value
    get_param_xml(par_gen, param = "tnitopt")
    #> $param_gen.xml
    #> $param_gen.xml$tnitopt
    #> [1] 29.5

    ## Using a conditional selection

    # Initial value
    get_param_xml(sols, param = "argi", select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 30.2

    # Setting a new one
    set_param_xml(sols, param = "argi", values = 33, select = "sol", select_value = "solcanne",
        overwrite = TRUE)

    # Controlling written value
    get_param_xml(sols, param = "argi", select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 33

- For one parameter and several occurences

For passing several parameters values (for one or more parameters) or single values for several parameters, the `param_value` argument must contain a list of vectors of values with the same length as `param` vector.

    ## For all soils
    soils_number <- length(get_soils_list(sols))

    # Initial values
    get_param_xml(sols, param = "argi")
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1] 33.0 21.0 27.0 39.0  1.0 12.2 70.0 22.0  9.9 10.2 10.2 17.0 23.1 22.0 27.0
    #> [16] 30.7  0.1 27.3 25.0 10.2 25.0 28.6 36.0 29.0 10.2 21.2 22.2 13.0 17.0 15.0
    #> [31] 26.0 28.2 20.0

    # One value per occurence
    set_param_xml(sols, param = "argi", values = list(1:soils_number), overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = "argi")
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
    #> [26] 26 27 28 29 30 31 32 33

    # Setting the same value for all occurences
    set_param_xml(sols, param = "argi", values = 40, overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = "argi")
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1] 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40
    #> [26] 40 40 40 40 40 40 40 40

- For several parameters and several occurrences

    ## For all soils
    soils_number <- length(get_soils_list(sols))

    # Initial values

    # Setting one value per parameters occurence
    set_param_xml(sols, param = list("argi", "pH"), values = list(1:soils_number, soils_number:1),
        overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = c("argi", "pH"))
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
    #> [26] 26 27 28 29 30 31 32 33
    #>
    #> $sols.xml$pH
    #>  [1] 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9
    #> [26]  8  7  6  5  4  3  2  1

    # Setting the same value for all occurences
    set_param_xml(sols, param = c("argi", "pH"), values = list(50, 8), overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = c("argi", "pH"))
    #> $sols.xml
    #> $sols.xml$argi
    #>  [1] 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50 50
    #> [26] 50 50 50 50 50 50 50 50
    #>
    #> $sols.xml$pH
    #>  [1] 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8

- For several parameters and one occurrence (conditional selection)

    ## For one soil

    # Initial values
    get_param_xml(sols, param = c("argi", "pH"), select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 50
    #>
    #> $sols.xml$pH
    #> [1] 8

    # Setting new values
    set_param_xml(sols, param = c("argi", "pH"), values = list(50, 8), select = "sol",
        select_value = "solcanne", overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = c("argi", "pH"), select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$argi
    #> [1] 50
    #>
    #> $sols.xml$pH
    #> [1] 8

## Vector parameters

- All values (for all soil layers, or crop management operations)

    ## For all soil layers

    # Initial values
    get_param_xml(sols, param = c("epc", "infil"), select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 20 20 20 20 20
    #>
    #> $sols.xml$infil
    #> [1] 50 50 50 50 50

    # Setting new values
    set_param_xml(sols, param = c("epc", "infil"), values = list(18:22, 48:52), select = "sol",
        select_value = "solcanne", overwrite = TRUE)

    # Controlling written values
    get_param_xml(sols, param = c("epc", "infil"), select = "sol", select_value = "solcanne")
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 18 19 20 21 22
    #>
    #> $sols.xml$infil
    #> [1] 48 49 50 51 52

    ## For all irrigation operations
    tec <- file.path(xml_loc_dir, "file_tec.xml")

    # Initial values
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"))
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #>  [1] 178 185 193 198 200 204 207 211 214 218 221 232 239 249 257 264
    #>
    #> $file_tec.xml$amount
    #>  [1] 20 24 29 29 28 31 21 21 23 18 22 16 16 30 29 20

    # Setting new values
    set_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"), values = list(200:215,
        20:35), overwrite = TRUE)

    # Controlling written values
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"))
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #>  [1] 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
    #>
    #> $file_tec.xml$amount
    #>  [1] 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

- Some values

In the examples below, `ids` contains the position of the parameters values in the vector, for a given soil (5 layers) name or for irrigation supplies operations amounts. In that case, used values in `ids` are contiguous, but they do not need to be.

A vector of logical values may be used instead of position values for queries or replacement.

    ## For soil layers 1 to 3

    # Initial values
    get_param_xml(sols, param = c("epc", "infil"), select = "sol", select_value = "solcanne",
        ids = 1:3)
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 18 19 20
    #>
    #> $sols.xml$infil
    #> [1] 48 49 50

    # Setting new values
    set_param_xml(sols, param = c("epc", "infil"), values = list(20:18, 50:48), select = "sol",
        select_value = "solcanne", overwrite = TRUE, ids = 1:3)

    # Controlling written values

    get_param_xml(sols, param = c("epc", "infil"), select = "sol", select_value = "solcanne",
        ids = 1:3)
    #> $sols.xml
    #> $sols.xml$epc
    #> [1] 20 19 18
    #>
    #> $sols.xml$infil
    #> [1] 50 49 48

    ## For irrigation operations 1 to 5 (same indices for all parameters)

    # Initial values
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"))
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #>  [1] 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
    #>
    #> $file_tec.xml$amount
    #>  [1] 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

    # Setting new values
    set_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"), values = list(204:200,
        24:20), overwrite = TRUE, ids = 1:5)

    # Controlling written values
    get_param_xml(tec, param = c("julapI_or_sum_upvt", "amount"))
    #> $file_tec.xml
    #> $file_tec.xml$julapI_or_sum_upvt
    #>  [1] 204 203 202 201 200 205 206 207 208 209 210 211 212 213 214 215
    #>
    #> $file_tec.xml$amount
    #>  [1] 24 23 22 21 20 25 26 27 28 29 30 31 32 33 34 35