---
title: "Article 3: Understanding the suit function"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::knitr}
  %\VignetteIndexEntry{Article 3: Understanding the suit function}
  %\usepackage[UTF-8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
## Introduction
The `suit` function is used for computing the suitability score and class of the land units for a given target crop. The function has the following usage:
```{r, eval=FALSE}
suit(
  crop,
  terrain = NULL,
  water = NULL,
  temp = NULL,
  mf = "triangular",
  sow_month = NULL,
  minimum = NULL,
  maximum = "average",
  interval = NULL,
  sigma = NULL
)
```
Check the documentation for details of the arguments. This article will focus on how to use this function. To evaluate the suitability score of Marinduque land units for terrain, soil, water and temperature characteristics, simply run the `suit` function for each of these characteristics. That is,
```{r}
library(ALUES)
banana_suit <- suit("banana", terrain=MarinduqueLT)
names(banana_suit)
```
The warning above simply tells the user that one of the factor, CECc, in the target crop requirement, has parameter intervals for all suitability classes equal to 16, and the package used this value as the maximum constant for computing the suitability scores. For more, please refer to the **Article 2: Methodology used in ALUES** of the documentation.

The `suit` function returns a list of output of target characteristics, in this case `"terrain"` and `"soil"`. To access the output, simply run the following:
```{r, eval=FALSE}
banana_suit[["terrain"]]
banana_suit[["soil"]]
```
Each of these are lists, with the following names:
```{r}
names(banana_suit[["soil"]])
```
So that, to access the factors evaluated, simply run the following:
```{r}
banana_suit[["soil"]][["Factors Evaluated"]]
```

## Targetting Crop
There are 56 crops available in ALUES, and what we've illustrated above are for banana only. Other crops are listed below:
```{r}
d <- utils::data(package = "ALUES")
alues_data <- d$results[, "Item"]
crop_data <- regmatches(alues_data, gregexpr(paste0("^[A-Z]{2,}", collapse = "|"), alues_data))
crop_data <- unique(unlist(lapply(crop_data, function(x) substr(x, 1, nchar(x)-1))))
crop_data
```
These are the names for the input string for the `suit` function. For example, to target sweet potato the input string is not `"sweet potato"` but rather `potatosw`. That is,
```{r, error=TRUE}
potato_suit1 <- suit("sweet potato", terrain=MarinduqueLT)
potato_suit2 <- suit("potatosw", terrain=MarinduqueLT)
```

## Targetting Crop Factors
The idea of evaluating a land unit is to match quality of the land against the standard value of the target factor. Therefore, if the crop does not include the factor you are targeting, then there won't be any matching to be done. For example, the land units evaluated above are those in Marindque, which has the following soil and terrain characteristics:
```{r}
head(MarinduqueLT)
```
The crop that we are trying to target is banana. The `suit` function simply require the user to input a string name for the target crop, and the function will look for the corresponding crop datasets. For example, for banana these are the crop requirements datasets for the four characteristics:
```{r}
BANANATerrain
BANANASoil
BANANAWater
BANANATemp
```
These datasets are used by the `suit` function depending on the specified characteristics of the input land units. So for `banana_suit` object above, the target crop datasets were `BANANATerrain` and `BANANASoil` since the input land unit specified is `terrain=MarinduqueLT`. However, input land unit only targetted the soil factors and not the terrain factors, since none of the factors in `MarinduqueLT` matched with the factors in `BANANATerrain`. That is why, accessing the output for the terrain characteristics for the `banana_suit` object will return the following:
```{r}
banana_suit[["terrain"]]
```

## Targetting Multiple Characteristics
The example above only targetted the terrain and soil characteristics, but the `suit` function allows user to also target water and temp simultaneously. This is done as follows:
```{r}
banana_multi <- suit("banana", terrain=MarinduqueLT, water=MarinduqueWater, temp=MarinduqueTemp, sow_month=2)
names(banana_multi)
```
It is necessary to specify the sowing month when specifying the water and temperature characteristics of the input land units. In this case, we are saying that the first sowing month for both water and temperature characteristics correspond to February. No factors were targetted by input land unit for banana for terrain, water and temperature characteristics.
```{r}
banana_suit[["terrain"]]
banana_suit[["water"]]
banana_suit[["temp"]]
lapply(banana_suit[["soil"]], function(x) head(x))
```
Only the head (first six) of the output of the items in the soil characteristics are shown.

## Membership Function
There are three membership functions (MFs) available in the `suit` function, namely *triangular*, *trapezoidal* and *Gaussian*. For example, the following computes the suitability scores and classes using trapezoidal MF.
```{r}
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal")
head(banana_suit[["soil"]][["Suitability Score"]])
head(banana_suit[["soil"]][["Suitability Class"]])
```

## Intervals
Another option available in the `suit` function is the `interval`. By default, ALUES uses an equally spaced suitability class intervals for deriving the suitability class. That is, for N [0, 0.25), S3 [0.25, 0.50), S2 [0.50, 0.75), and S1 [0.75, 1].

### Custom Intervals
Users can modify the default equally spaced intervals, for example:
```{r}
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval=c(0, 0.3, 0.6, 0.9, 1))
head(banana_suit[["soil"]][["Suitability Score"]])
head(banana_suit[["soil"]][["Suitability Class"]])
```
The above code sets the new suitability class intervals into: N [0, 0.3), S3 [0.3, 0.6), S2 [0.6, 0.9), and S1 [0.9, 1].

### Unbias Intervals
The problem with the fixed interval is that the said intervals does not take into account the shape of the membership function and the spacing of the parameter interval limits (*See* Article 2 for parameter intervals). Custom intervals might be able to capture this if the user computed the interval limits manually, but ALUES provides an option just for this, by setting `interval="unbias"`. That is,
```{r}
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias")
head(banana_suit[["soil"]][["Suitability Score"]])
head(banana_suit[["soil"]][["Suitability Class"]])
```
By setting the `interval="unbias"`, the `suit` function will generate a different likely unequally spaced suitability class intervals, but the interval limits are mathematically correct, in terms of the mapping of the parameter interval limits to suitability class limits via the membership function.

## Maximum and Minimum
Another parameter that can be set for `suit` are the `minimum` and `maximum`. These are the constants used by the membership function for computing the suitability score.
```{r}
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias")
banana_suit[["soil"]][["Factors Evaluated"]]
```
From the above result, there are four factors targetted by the input land unit, these are CFragm, CECc, pHH2O and SoilTe. Suppose we know the maximum value that these factors can take, say 60 for CFragm, 20 for CECc, 9 for pHH2O, and 10 for SoilTe. We can specify these as follows:
```{r}
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias", maximum=c(60, 20, 9, 10))
banana_suit
```
The result gave us an error. We understand the error for terrain characteristics, but for soil it says the argument maximum must be equal in length with the target factors specified in the input land units dataset. We know that there should be 4 factors, but upon checking we see that the `MarinduqueLT` also have Lon and Lat columns, which ALUES assumes to be a target factor as well. Indeed, we need to exclude these columns (those that are not the target factors) when specifying `minimum` or `maximum` constants. Thus, it should be:
```{r}
MarinduqueLT2 <- MarinduqueLT[, 3:ncol(MarinduqueLT)]
banana_suit <- suit("banana", terrain=MarinduqueLT2, mf="trapezoidal", interval="unbias", maximum=c(60, 20, 9, 10))
head(banana_suit[["soil"]][["Suitability Score"]])
head(banana_suit[["soil"]][["Suitability Class"]])
```

## Sigma of Gaussian
The `sigma` argument is used to specify scale of the Gaussian membership function. That is, it is only applicable for `mf="gaussian"`.