---
title: "Manipulating STICS text files"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Manipulating STICS text files}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
options(tibble.print_min = 5, tibble.print_max = 5)
```

```{r eval=FALSE}
library(SticsRFiles)
```

```{r include=FALSE}
suppressWarnings(library(SticsRFiles))
```

```{r echo=FALSE}
stics_version <- get_stics_versions_compat()$latest_version
```

------


## Overview

This package allows the user to programmatically manipulate either the XML files used to store more information, or the text files directly used as inputs by the STICS model. This vignette explains the second one. For more details on how to manipulate XML files, please refer to the vignette [Manipulating STICS XML files](https://sticsrpacks.github.io/SticsRFiles/articles/Manipulating_Stics_XML_files.html).

> Disclaimer: These functionalities are more oriented toward advanced users and/or developers.

Using this package, it is possible to:

* convert the XML files to text files (`convert_xml2txt()`), please see the [Generating STICS text files](https://sticsrpacks.github.io/SticsRFiles/articles/Generating_Stics_text_files) vignette;
* read (`get_param_txt()` or set (`set_param_txt()`) parameters;
* Read the climate (`get_climate_txt()`);
* Set the output variables required (`gen_varmod()`).

To run a STICS simulation on these input files, please refer to the [`run_stics()`](https://sticsrpacks.github.io/SticsOnR/reference/run_stics.html) function from [SticsOnR](https://sticsrpacks.github.io/SticsOnR/index.html).

Some example data are available from the package and can be retrieved using the following function call for the STICS version `r stics_version`:

```{r}
example_txt_dir <-
  get_examples_path(file_type = "txt", stics_version = stics_version)
```
The `example_txt_dir` directory is: `r example_txt_dir`. By default, the latest STICS version is taken into account. 
For getting an example directory for another version, an additional argument must be given `stics_version` according to an existing version included in the package. The version list can be retrieved using:

```{r}
get_stics_versions_compat()$versions_list
```


## Getting parameter value

`get_param_txt()` helps to get the value of a given parameter in a USM. It has two main arguments, the directory of the USM (`workspace`, where the text files lives), and the parameter names (`param`) to be searched. But, if `param` is not used, the returned named list contains all the STICS parameters for a given USM.

Additional arguments can be set for specific extractions:

* `variety` is for getting parameters for a cultivar or a vector of
* `exact` may be used for indicating that the parameter(s) name(s) given by `param` must be matching exactly parameters names in files
* `stics_version` is to be used if one want to get parameters for another STICS version than the latest one (default), as for getting the example directory

For example to get the value of the atmospheric pressure:

```{r}
get_param_txt(workspace = example_txt_dir, param = "patm")
```

The function returns a named list according to the file where it found the parameter value (here "station") containing all the values found for the `patm` parameter (here 1000), along with the parameter name as found in the file. The function performs a fuzzy search, so here after the name of the parameter is only partially given, e.g.: `atm`

```{r}
get_param_txt(workspace = example_txt_dir, param = "atm")
```

Note that the function does not require the user to know in which file the parameter is because it search the parameter in all files. So if it finds several parameter with the same given name, it will return all. The next example shows how to get parameters from the soil file containing the letter "a":

```{r}
get_param_txt(workspace = example_txt_dir, param = "a")$soil
```
For an exact search of parameters, a specific argument `exact` must be set to **TRUE** (the default value is **FALSE** if not provided). 

Here we see another peculiarity: the name associated to the value has more information for the plant file, e.g. " `plant$plant1$P_Nmeta`" instead of "`plant$P_Nmeta`". This is because a USM can potentially have two plant files if it is an intercrop, so the function returns the plant file index where the parameter was found.

It is the same case for the tec file:

```{r}
get_param_txt(workspace = example_txt_dir, param = "interrang")
```


A particular search in plant parameters for specific varieties, can be done using the `variety` argument:

* either using names,
```{r}
get_param_txt(workspace = example_txt_dir, param = "stlevamf",
              variety = c("Pactol", "Cecilia", "clarica"))
```
* or using varieties indexes in plant file,
```{r}
get_param_txt(workspace = example_txt_dir, param = "stlevamf",
              variety = c(1, 2, 5))
```



The `get_param_txt()` function is a wrapper around other lower-level functions that reads the parameter values in a given file:

* get_ini_txt() for the `ficini.txt` file;
* get_general_txt() for the `tempopar.sti` file;
* get_tmp_txt() for the `tempoparv6.sti` file;
* get_plant_txt() for the `ficplt.txt` file;
* get_tec_txt() for the `fictec.txt` file;
* get_soil_txt() for the `param.sol` file;
* get_station_txt() for the `station.txt` file;
* get_usm_txt() for the `new_travail.usm` file;
* get_varmod() for the `var.mod` file;

All these functions are exported for convenience, but `get_param_txt()` is easier to use.

## Getting the meteorological data

The `get_climate_txt()` function helps to get the data from the `climat.txt` file, and is used as:

```{r eval=FALSE}
get_climate_txt(workspace = example_txt_dir)
```

```{r echo=FALSE}
library(dplyr)
get_climate_txt(workspace = example_txt_dir) %>%
  rmarkdown::paged_table()
```


The function adds a `Date` column that is at the standard `POSIXct` format for convenience.


## Setting parameter value

`set_param_txt()` is used to set the value of a given parameter in a USM. It has three main arguments, the directory of the USM (`workspace`, where the text files lives), the parameter name (`param`), and the new value of the parameter.


The actual value of of the atmospheric pressure read above is:
```{r}
get_param_txt(workspace = example_txt_dir, param = "patm")
```
To set a new value of `patm` to 900:
```{r}
set_param_txt(workspace = example_txt_dir, param = "patm", value = 900)
```

Now we can check that the value is changed:

```{r}
get_param_txt(workspace = example_txt_dir, param = "patm")
```

```{r include=FALSE}
# resetting the value:
set_param_txt(workspace = example_txt_dir, param = "patm", value = 1000)
```

There are four more arguments to the function:

* `append`: instead of changing the value of a parameter that already exist in the files, a parameter can be added to the file using this argument. This is used mainly by developers that added a parameter to the model and need to programmatically add it to the input files.

* `plant_id`: This is used for intercropping when there are two plant and tec files. The user can then choose to which plant the value will be changed.

* `variety`: This optional argument may be used for replacing varietal parameter values either giving a name (`codevar` in the plant file) or an index of the variety specified in the technical file (`variete`)

* `layer`: This may be used for replacing specific parameters values, for specific soil layers either for the soil characteristics (soil file: `param.sol`), or roots density and mineral elements concentration at the simulation start (initialisation file: `ficini.txt`). 

* `stics_version`: At last, the model version can be specified through that argument, because files content may vary according to the version. 


Specific replacements may be performed combining additional arguments as `plant_id`, `layer`:

* The initial values of `densinitial` are:
```{r}
get_param_txt(workspace = example_txt_dir, param = "densinitial")
```
* The values for the plant 1 and layers 1 and 4 are replaced as follows:

```{r}
set_param_txt(workspace = example_txt_dir,
              param = "densinitial",
              plant_id = 1,
              layer = c(1, 4),
              value = c(0.5, 0.1))
```

* The final values in the file are:
```{r}
get_param_txt(workspace = example_txt_dir, param = "densinitial")
```


Note that as for `get_param_txt()`, `set_param_txt()` finds automatically the file where the parameter is. It is also a wrapper around lower-level functions that set the parameter values in a given file:

* set_ini_txt() for the `ficini.txt` file;
* set_general_txt() for the `tempopar.sti` file;
* set_tmp_txt() for the `tempoparv6.sti` file;
* set_plant_txt() for the `ficplt.txt` file;
* set_tec_txt() for the `fictec.txt` file;
* set_soil_txt() for the `param.sol` file;
* set_station_txt() for the `station.txt` file;
* set_usm_txt() for the `new_travail.usm` file;

All these functions are exported for convenience, but `set_param_txt()` is easier to use. These low-level functions may be used when a parameter name is replicated between files and the user wants to change the value of one only, or if the user need to replace the values for a particular variety in the plant file.

## Set the output variables

The `gen_varmod()` function is used to set the required output variables in the `var.mod` file. For example if the user need the LAI and the dry mass:

```{r}
gen_varmod(workspace = example_txt_dir, var = c("lai(n)", "masec(n)"))
```

Controlling if the values where written:

```{r}
get_varmod(example_txt_dir)
```

Alternatively, the user can append a variable to the pre-existing vector of values using the `append` argument:

```{r}
gen_varmod(workspace = example_txt_dir, var = c("hauteur"), append = TRUE)
get_varmod(example_txt_dir)
```

To get the possible output variables from the model, the user can use the `get_var_info()` function that provide a fuzzy search:

```{r}
get_var_info("lai")
```