A L U E S

ALUES: Agricultural Land Use Evaluation System, Getting Started

Authors:
Arnold R. Salvacion                                                                      
arsalvacion@gmail.com
Data Analysis and Visualization using R (blog)                                         

Al-Ahmadgaid B. Asaad (maintainer)
alstated@gmail.com

Agricultural Land Use Evaluation System (ALUES) is an R package that evaluates land suitability for different crop production. The package is based on the Food and Agriculture Organization (FAO) and the International Rice Research Institute (IRRI) methodology for land evaluation. Development of ALUES is inspired by similar tool for land evaluation, Land Use Suitability Evaluation Tool (LUSET). The package uses fuzzy logic approach to evaluate land suitability of a particular area based on inputs such as rainfall, temperature, topography, and soil properties. The membership functions used for fuzzy modeling are the following: Triangular, Trapezoidal and Gaussian. The methods for computing the overall suitability of a particular area are also included, and these are the Minimum, Maximum, Product, Sum, Average, Exponential and Gamma. Finally, ALUES uses the power of Rcpp library for efficient computation.

INSTALLATION

The package is not yet on CRAN, and is currently under development on github. To install it, run the following:

We want to hear some feedbacks, and if you have any suggestion or issues regarding this package, please do submit it here.

DATASET

The package contains several datasets which can be categorized into two:

1. Land Units' Attributes - datasets that contain the attributes of the land units of a given location.
2. Crop Requirements - datasets that contain the required values of factors of a particular crop for the land units.

Land Units' Attributes

The package contains sample dataset of land units' attributes from two countries:

1. Marinduque, Philippines:
   • MarinduqueLT - a dataset consisting the land and terrain characteristics of the land units of Marinduque, Philippines;
   • MarinduqueTemp - a dataset consisting the temperature characteristics of the land units of Marinduque, Philippines; and
   • MarinduqueWater - a dataset consisting the water characteristics of the land units of Marinduque, Philippines.
2. Lao Cai, Vietnam
   • LaoCaiLT - a dataset consisting the land and terrain characteristics of the land units of Lao Cai, Vietnam;
   • LaoCaiTemp - a dataset consisting the temperature characteristics of the land units in Lao Cai, Vietnam;
   • LaoCaiWater - a dataset consisting the water characteristics of the land units of Lao Cai, Vietnam;

For example, the first six land units in MarinduqueLT is shown below

The complete list of factors is available in the pdf version.

Crop Requirements

The crops available in the package are the listed in Table 1.

Code	Crops
Table 1: Crops Dataset Available in ALUES.
BANANA-	Banana
CASSAVA-	Cassava
COCOA-	Cocoa
COCONUT-	Coconut
COFFEEAR-	Arabica Coffee
COFFEERO-	Robusta Coffee
RICEBR-	Rainfed Bunded Rice
RICEIW-	Irrigated Rice
RICENF-	Rice Cultivation Under Natural Floods
RICEUR-	Rainfed Upland Rice

From the table, the codes are suffixed with the land units' characteristics (TerrainCR, SoilCR, WaterCR and TemperatureCR) required for the crop. For example, below are the required values for the terrain characteristics of the land units on cultivating coconut:

For required characteristics of soil, water and temperature on cultivating coconut the codes are COCONUTSoilCR, COCONUTWaterCR and COCONUTTemperatureCR, respectively.

R FUNCTIONS

The package contains the following functions:

1. suitability - computes the suitability scores and classes of the land units base on the requirements of the crop.
2. overall_suit- computes the overall suitability of the land units, using the suitability scores obtained from the suitability function.

Suitability

In this section, we will get into the details of the suitability function. Usage

x	a data frame consisting the properties of the land units;
y	a data frame consisting the crop (e.g. coconut, cassava, etc.) requirements for a given characteristics (terrain, soil, water and temperature);
mf	membership function, default is set to "triangular". Other fuzzy models are "Trapezoidal" and "Gaussian".
sow.month	sowing month of the crop. Takes integers from 1 to 12 (inclusive), representing the twelve months of a year. So if sets to 1, the function assumes sowing month on January.
min	factor's minimum value. If NULL (default), min is set to 0. But if numeric of length one, say 0.5, then minimum is set to 0.5 for all factors. If factors on land units (x) have different minimum, then these can be concatenated to vector of mins, the length of this vector should be equal to the number of factors in x. However, if sets to "average", then min is theoretically computed as: Let X be a factor, then X has the following suitability class: S3, S2 and S1. Assuming the scores of the said suitability class for X are $a, b$ and $c$, respectively. Then, $$\mathrm{min} = a - \displaystyle\frac{(b - a) + (c - b)}{2}$$ For factors with suitability class S3, S2, S1, S1, S2 and S3 with scores $a, b, c, d, e$ and $f$, respectively. min is computed as, $$\mathrm{min} = a - \displaystyle\frac{(b - a) + (c - b) + (d - c) + (e - d) + (f - e)}{5}$$
max	factor's maximum value. Default is set to "average". If numeric of length one, say 50, then maximum is set to 50 for all factors. If factors on land units (x) have different maximum, then these can be concatenated to vector of maxs, the length of this vector should be equal to the number of factors in x. However, if sets to "average", then max is computed from the equation below: $$\mathrm{max}=c + \displaystyle\frac{(b-a) + (c-b)}{2}$$ For factors with suitability class S3, S2, S1, S1, S2 and S3 with scores $a, b, c, d, e$ and $f$, respectively. Then, $$\mathrm{max} = f + \displaystyle\frac{(b - a) + (c - b) + (d - c) + (e - d) + (f - e)}{5}$$
interval	domain for every suitability class (S1, S2, S3, and N). If "fixed", the interval would be 0 to 0.25 for N (Not Suitable), 0.25 to 0.50 for S3 (Marginally Suitable), 0.50 to 0.75 for S2 (Moderately Suitable), and 0.75 to 1 for (Highly Suitable). If "unbias", then the interval is set to 0 to $\displaystyle\frac{a}{\mathrm{max}}$ for N, $\displaystyle\frac{a}{\mathrm{max}}$ to $\displaystyle\frac{b}{\mathrm{max}}$ for S3, $\displaystyle\frac{b}{\mathrm{max}}$ to $\displaystyle\frac{c}{\mathrm{max}}$ for S2, and $\displaystyle\frac{c}{\mathrm{max}}$ to $\displaystyle\frac{\mathrm{max}}{\mathrm{max}}$ for S1.

Output
The function returns the following output:

1. Actual Factors Evaluated;
2. Suitability Score;
3. Suitability Class;
4. Factors' Minimum Values; and,
5. Factors' Maximum Values.

Example: To test the suitability of the land units in Marinduque, Philippines, for terrain requirements of coconut, we have

Before we run the function, let's check for the possible output. From the land units (MarinduqueLT), the only factor available to be evaluated is CFragm, for required soil characteristics of the coconut. The first land unit has 11% coarse fragment (CFragm), which falls within the S1 domain of the required soil characteristics, with domain [min - 15%), where min has default value set to 0. The second to sixth land units also are highly suitable as it falls within the said domain. Let's confirm it using the function,

Extract the first 6 of the outputs,

Indeed, just what we argued earlier.

Options for mf (Membership Function)
The membership function is an option for the type of fuzzy model, the available models are the following:

1. Triangular;
2. Trapezoidal; and,
3. Gaussian.

The suitability scores are computed base on these fuzzy models.

Options for sow.month (Sowing Month)
The sow.month is the sowing month which takes integers from 1 to 12, representing the twelve months of a year. So if sets to 1, the function assumes sowing month on January. This argument is only use for water and temperature characteristics.

To illustrate this, we will test the land units of Marinduque for the required water and temperature for rainfed bunded rice. Thus, we have

We will test first the land units for water, and here are the following water requirements for rainfed bunded rice,

The factors to be evaluated here are the following:

1. WmAv1 - Mean precipitation of first month (mm);
2. WmAv2 - Mean precipitation of second month (mm);
3. WmAv3 - Mean precipitation of third month (mm); and
4. WmAv4 - Mean precipitation of fourth month (mm).

If sowing month is set to November, then we have

1. WmAv1 - November;
2. WmAv2 - December;
3. WmAv3 - January; and
4. WmAv4 - February.

So for Novermber, we see the first land unit falls within the domain of S1, that is, 277 mm falls within [175 - 500 mm). And same thing for the first land unit of December, highly suitable. Let's fire up the function to confirm that,

You will have this error if there is no factors to be evaluated. What just happened here is that, the function assumed the data as neither water nor temperature characteristics. Thus, it ignores the WmAv1, WmAv2, WmAv3 and WmAv4 factors. But if we specify the sowing month (sow.month) to November (11), then we have

The first land unit for November does confirms to be S1, but for December it isn't, and instead S2 is given. This problem will be discussed later on details about the interval argument.

Options for min (Factors' Minimum Value)
By default, min = 0 for all factors. This can be assigned to any positive integers, for example, using the cassava soil requirements,

Now let's try different minimums for factors, we will use the following:

CECc	pHH20	CFragm	SoilTe
Table 2: Custom min.
0.4	0.6	0.1	0.3

So we got an error, it is expected, since the length of the vector min should be equal to the number of factors in x, which is 6. Since we are not interested on the latitude (X) and longitude (Y) factors of the dataset, then we can ommit the two and rerun the code,

Only CECc and SoilTe are returned since these are the factors evaluated.

Options for max (Factors' Maximum Value)
By default max = 'average', and just like min, max can be assigned to any positive integer, example:

For different maximum value on every factor, we will use the following and ommit the first two factors in MarinduqueLT like what we did in the previous section.

CECc	pHH20	CFragm	SoilTe
Table 3: Custom max.
52.5	8.8	40	14

Options for interval (Domain of Suitability Scores)
The domain of suitability scores are set to default, 'fixed', if this option is used, the domain of the suitability scores would be,

Class	N	S3	S2	S1
Table 4: Domain for 'fixed'.
Domain	[0, 0.25)	[0.25, 0.5)	[0.5, 0.75)	[0.75, 1]

An example of interval = 'fixed' is the one illustrated in Options for sow.month (Sowing Month) above. Let us investigate the output of that, here is the crop requirements for water (the crop we are interested in, is the rainfed bunded rice),

Given that the starting sowing month assigned is November, then the following factors are evaluated:

1. WmAv1 - November;
2. WmAv2 - December;
3. WmAv3 - January; and
4. WmAv4 - February.

So we are going to extract this factors from the dataset, MarinduqueWater,

The suitability scores and class of this would be,

Focus your attention on suitability scores of Feb factor for the first three land units. We have here 0.3714, 0.3714 and 0.3771. And the domain of this base on Table 4, would be S3, S3 and S3. But, if we refer to the original data, the first three data points in Feb factor are all 65. Since WmAv4 is the corresponding requirements for Feb factor, with scores:

Factor	S3	S2	S1	S1	S2	S3	Weight
Table 5: WmAv4’s Suitability Requirements.
WmAv4	29	30	50	300	500	600	NA

Then it is easy to pin point what suitability class does the scores of the land units falls into. Which follows that all first three land units falls within class S1. See the problem with 'fixed' interval? This is the same problem for other factor like Dec (December), where instead of S1, we got S2. Users can change the domain though, that is, instead of using the 'fixed' option, users can assign for example, interval = c(0, 0.33, 0.56, 0.89, 1), which equivalently:

Class	N	S3	S2	S1
Table 6: Custom Domains.
Domain	[0, 0.33)	[0.33, 0.56)	[0.56, 0.89)	[0.89, 1]

Assigning new values for parameters of the interval won't solve the problem, but this argument has one more option to offer, which does solve the problem, and that is by changing interval = 'fixed' to interval = 'unbias'. Let's try it,

And that supports our argument above.

Weighting
The function, suitability, also considers the weights of the factors. An example of crop with no weights is the soil requirement for coconut,

The weights are assigned on the last column, Weight.class. And here is the soil requirements for the cassava, with weight on each factor:

If a given factor has a weight, then the function will compute the corresponding suitability and then use the weighting score to obtain the appropriate suitability score. The weights of the factors for the default interval (interval = 'fixed') are in Table 7:

Suitability	Factor Weights
Table 7: Weights of the Factors for 'fixed' Interval.
Class	1	2	3
S1	0.833	0.916	1.000
S2	0.583	0.667	0.750
S3	0.333	0.416	0.500
N	0.083	0.167	0.250

Thus the function simply divides the interval of the suitability class into three, for three weights.

Overall Suitability

x	a data frame consisting the suitability scores of a given characteristics (terrain, soil, water and temperature) for a given crop (e.g. coconut, cassava, etc.);
method	the method for computing the overall suitability, which includes the minimum, maximum, sum, product, average, exponential and gamma. If NULL, minimum is used.
interval	if NULL, the interval used are the following: 0-0.25 (Not suitable, N), 0.25-0.50 (Marginally Suitable, S3), 0.50-0.75 (Moderately Suitable, S2), and 0.75-1 (Highly Suitable, S1).
output	the output to be returned, either the scores or class. If NULL, both are returned.

DEMONSTRATION

Let's assume we are interested on the land units in Lao Cai, Vietnam, for cultivating irrigated rice. So here are the first 6 land units in the said location,

And here are the required values for factors of soil, terrain, temperature and water characteristics for irrigated rice,

Now, we are going to take the suitability scores for every characteristics,

Next, we will take the overall suitability on all factors in each land unit using the "average" method (default is "minimum").

Finally, take the overall suitability from these characteristics using the "maximum" method.