ALUES: Agricultural Land Use Evaluation System, Getting Started
Authors:
Arnold R. Salvacion
arsalvacion@gmail.com
Data Analysis and Visualization using R (blog)
AlAhmadgaid 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: Land Units' Attributes  datasets that contain the attributes of the land units of a given location.
 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: 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; andMarinduqueWater
 a dataset consisting the water characteristics of the land units of Marinduque, Philippines.

 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;
MarinduqueLT
is shown belowThe 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:suitability
 computes the suitability scores and classes of the land units base on the requirements of the crop.overall_suit
 computes the overall suitability of the land units, using the suitability scores obtained from thesuitability
function.
Suitability
In this section, we will get into the details of thesuitability
function.
Usagex  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 min s, 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 max s, 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{(ba) + (cb)}{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:
 Actual Factors Evaluated;
 Suitability Score;
 Suitability Class;
 Factors' Minimum Values; and,
 Factors' Maximum Values.
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:
 Triangular;
 Trapezoidal; and,
 Gaussian.
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:
WmAv1
 Mean precipitation of first month (mm);WmAv2
 Mean precipitation of second month (mm);WmAv3
 Mean precipitation of third month (mm); andWmAv4
 Mean precipitation of fourth month (mm).
WmAv1
 November;WmAv2
 December;WmAv3
 January; andWmAv4
 February.
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 haveThe 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:
WmAv1
 November;WmAv2
 December;WmAv3
 January; andWmAv4
 February.
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: 00.25 (Not suitable, N), 0.250.50 (Marginally Suitable, S3), 0.500.75 (Moderately Suitable, S2), and 0.751 (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.