vignettes/a03_understanding_suit.Rmd
a03_understanding_suit.RmdThe 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 input arguments:
suit(
crop,
terrain = NULL,
water = NULL,
temp = NULL,
mf = "triangular",
sow_month = NULL,
minimum = NULL,
maximum = "average",
interval = NULL,
sigma = NULL
)Check the R documentation for details of the arguments. This article
will focus on how to use the said 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,
## Loading required package: Rcpp
banana_suit <- suit("banana", terrain=MarinduqueLT)## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.
names(banana_suit)## [1] "terrain" "soil"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:
banana_suit[["terrain"]]
banana_suit[["soil"]]Each of these are lists, with the following names:
names(banana_suit[["soil"]])## [1] "Factors Evaluated" "Suitability Score"
## [3] "Suitability Class" "Factors' Minimum Values"
## [5] "Factors' Maximum Values" "Factors' Weights"
## [7] "Crop Evaluated" "Warning"So that, to access the factors evaluated, simply run the following:
banana_suit[["soil"]][["Factors Evaluated"]]## [1] "CFragm" "CECc" "pHH2O" "SoilTe"There are 56 crops available in ALUES, and what we’ve illustrated above is for banana only. Other crops are listed below:
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## [1] "ALFALFA" "AVOCADO" "BAMBOO" "BANANA" "BARLEY"
## [6] "BEANCA" "BEANS" "CABBAGE" "CARROTS" "CASHEW"
## [11] "CASSAVA" "CHICKPEA" "CINNAMON" "CITRUS" "COCOA"
## [16] "COCONUT" "COFFEEAR" "COFFEERO" "COTTON" "COWPEA"
## [21] "CUCUMBER" "GROUNDNUTS" "GUAVA" "LONGAN" "MAIZE"
## [26] "MANGO" "MILLETS" "OILPALM" "OLIVES" "ONION"
## [31] "PAPAYA" "PEACH" "PEAR" "PEA" "PEPPERGR"
## [36] "PERSIMMON" "PINEAPPLE" "PLUM" "POTATOSW" "POTATO"
## [41] "RICEBR" "RICEIW" "RICENF" "RICEUR" "RUBBER"
## [46] "SAFFLOWER" "SESAME" "SORGHUM" "SOYA" "SUGARCANE"
## [51] "SUNFLOWER" "TEA" "TOBACCO" "TOMATO" "WATERMELON"
## [56] "WHEAT"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,
potato_suit1 <- suit("sweet potato", terrain=MarinduqueLT)## Error in suit("sweet potato", terrain = MarinduqueLT): Input crop='sweet potato' is not available in the database, see docs for list of ALUES data.
potato_suit2 <- suit("potatosw", terrain=MarinduqueLT)## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.The idea of evaluating a land unit is to match the 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:
head(MarinduqueLT)## Lat Lon CECc pHH2O CFragm SoilTe
## 1 121.8792 13.52084 12 53 11 12
## 2 121.8875 13.52084 12 52 9 12
## 3 121.8958 13.52084 12 53 10 12
## 4 121.9375 13.52084 12 52 10 12
## 5 121.9458 13.52084 12 54 12 12
## 6 121.9542 13.52084 13 54 11 12The 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:
BANANATerrain## code s3_a s2_a s1_a s1_b s2_b s3_b wts
## 1 Slope1 6.0 4 2 <NA> <NA> <NA> <NA>
## 2 Slope2 16.0 8 4 <NA> <NA> <NA> <NA>
## 3 Slope3 30.0 16 8 <NA> <NA> <NA> <NA>
## 4 Flood 2.5 2 1 <NA> <NA> <NA> 1
## 5 Drainage 4.0 3 2 <NA> <NA> <NA> 2
## 6 SlopeD 3.0 2 1 <NA> <NA> <NA> 1
BANANASoil## code s3_a s2_a s1_a s1_b s2_b s3_b wts
## 1 CFragm 55.0 35.0 15.0 <NA> <NA> <NA> 3
## 2 SoilDpt 50.0 75.0 100.0 <NA> <NA> <NA> 2
## 3 CaCO3 15.0 10.0 0.0 <NA> <NA> <NA> 3
## 4 Gyps 10.0 4.0 0.0 <NA> <NA> <NA> 3
## 5 CECc 16.0 16.0 16.0 <NA> <NA> <NA> 3
## 6 BS 19.9 20.0 35.0 <NA> <NA> <NA> 3
## 7 SumBCs 2.8 2.8 4.0 <NA> <NA> <NA> 3
## 8 pHH2O 4.5 5.2 5.6 7.5 8 8.2 3
## 9 OC 0.7 0.8 1.5 <NA> <NA> <NA> 2
## 10 ECedS 6.0 4.0 2.0 <NA> <NA> <NA> 3
## 11 ESP 12.0 8.0 4.0 <NA> <NA> <NA> 3
## 12 SoilTe 2.0 4.0 9.0 <NA> <NA> <NA> 2
BANANAWater## code s3_a s2_a s1_a s1_b s2_b s3_b wts
## 1 WyAv 1000 1250 1500 <NA> <NA> <NA> <NA>
## 2 WmDryLen 6 4 3 <NA> <NA> <NA> <NA>
BANANATemp## code s3_a s2_a s1_a s1_b s2_b s3_b wts
## 1 TyMaxAv 14 16 18 <NA> <NA> <NA> 2
## 2 TmMinXm 2 8 15 <NA> <NA> <NA> 2
## 3 TmMinXmAb -2 0 8 <NA> <NA> <NA> <NA>These datasets are used by the suit function depending
on the targetted characteristics of the input land units (specified by
the user) on the said function. So for banana_suit object
above, the target crop datasets were BANANATerrain and
BANANASoil since the input land unit specified is
terrain=MarinduqueLT. Further, the 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:
banana_suit[["terrain"]]## [1] "Error: No factor(s) to be evaluated, since none matches with the crop requirements. If water or temp characteristics was specified then maybe you forgot to specify the sow_month argument, read doc for suit."The example above only targetted the terrain and soil
characteristics, but the suit function allows user to also
target water and temp simultaneously. For examples, we can evaluate the
land units of Lao Cai, Vietnam for all three characteristics as follows
for irrigated rice (`riceiw``):
riceiw_multi <- suit("riceiw", terrain=LaoCaiLT, water=LaoCaiWater, temp=LaoCaiTemp, sow_month=10)
names(riceiw_multi)## [1] "terrain" "soil" "water" "temp"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 October (See Article 6 for more on this). No factors were targetted by input land unit for banana for terrain, water and temperature characteristics.
## $`Factors Evaluated`
## [1] "Flood" "SlopeD"
##
## $`Suitability Score`
## Flood SlopeD
## 1 0.75 0.75
## 2 0.75 0.75
## 3 0.75 0.75
## 4 0.75 0.75
## 5 0.75 0.75
## 6 0.50 0.75
##
## $`Suitability Class`
## Flood SlopeD
## 1 S1 S1
## 2 S1 S1
## 3 S1 S1
## 4 S1 S1
## 5 S1 S1
## 6 S2 S1
##
## $`Factors' Minimum Values`
## Flood SlopeD
## 0 0
##
## $`Factors' Maximum Values`
## Flood SlopeD
## 4 4
##
## $`Factors' Weights`
## [1] 1 1
##
## $`Crop Evaluated`
## [1] "RICEIWTerrain"## $`Factors Evaluated`
## [1] "CFragm" "SoilDpt" "CECc" "BS" "SumBCs" "OC"
##
## $`Suitability Score`
## CFragm SoilDpt CECc BS SumBCs OC pHH2O SoilTe
## 1 1.0000000 0.4390244 0.9789474 0.7692308 0.6346154 0.7368421 0.7883212 0.75
## 2 1.0000000 0.4390244 0.9789474 0.7692308 0.6346154 0.7368421 0.7883212 0.75
## 3 1.0000000 0.4390244 0.9789474 0.7692308 0.6346154 0.7368421 0.7883212 0.75
## 4 1.0000000 0.4390244 0.9789474 0.7692308 0.6346154 0.7368421 0.7883212 0.75
## 5 1.0000000 0.4390244 0.9789474 0.7692308 0.6346154 0.7368421 0.7883212 0.75
## 6 0.9019608 0.6341463 0.0000000 0.5341538 0.6019231 0.6368421 0.7737226 0.25
##
## $`Suitability Class`
## CFragm SoilDpt CECc BS SumBCs OC pHH2O SoilTe
## 1 S1 S3 S1 S1 S2 S2 S1 S1
## 2 S1 S3 S1 S1 S2 S2 S1 S1
## 3 S1 S3 S1 S1 S2 S2 S1 S1
## 4 S1 S3 S1 S1 S2 S2 S1 S1
## 5 S1 S3 S1 S1 S2 S2 S1 S1
## 6 S1 S2 N S2 S2 S2 S1 S3
##
## $`Factors' Minimum Values`
## CFragm SoilDpt CECc BS SumBCs OC
## 0 0 0 0 0 0
##
## $`Factors' Maximum Values`
## CFragm SoilDpt CECc BS SumBCs OC
## 51.0 102.5 19.0 65.0 5.2 1.9
##
## $`Factors' Weights`
## [1] 3 3 3 2 3 2
##
## $`Crop Evaluated`
## [1] "RICEIWSoil"## $`Factors Evaluated`
## [1] "Oct" "Nov" "Dec" "Jan"
##
## $`Suitability Score`
## Oct Nov Dec Jan
## 1 0.3665481 0.1949630 0.06068148 0.1170857
## 2 0.4050074 0.2246519 0.09386667 0.2040571
## 3 0.3820444 0.2175704 0.08654815 0.1921714
## 4 0.2256000 0.2367111 0.03573333 0.1185143
## 5 0.2422222 0.2302519 0.04157037 0.1266857
## 6 0.3205333 0.2062222 0.07051852 0.1724000
##
## $`Suitability Class`
## Oct Nov Dec Jan
## 1 S3 N N N
## 2 S3 N N N
## 3 S3 N N N
## 4 N N N N
## 5 N N N N
## 6 S3 N N N
##
## $`Factors' Minimum Values`
## Oct Nov Dec Jan
## 0 0 0 0
##
## $`Factors' Maximum Values`
## Oct Nov Dec Jan
## 880.0 880.0 880.0 714.2
##
## $`Factors' Weights`
## [1] NA NA NA NA
##
## $`Crop Evaluated`
## [1] "RICEIWWater"## $`Factors Evaluated`
## [1] "Nov"
##
## $`Suitability Score`
## Nov
## 1 0.5283333
## 2 0.5330000
## 3 0.5410000
## 4 0.6453333
## 5 0.6306667
## 6 0.5653333
##
## $`Suitability Class`
## Nov
## 1 S2
## 2 S2
## 3 S2
## 4 S2
## 5 S2
## 6 S2
##
## $`Factors' Minimum Values`
## Nov
## 0
##
## $`Factors' Maximum Values`
## Nov
## 52
##
## $`Factors' Weights`
## [1] 2
##
## $`Crop Evaluated`
## [1] "RICEIWTemp"Only the head (first six) of the output of the items are shown.
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.
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal")## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.
head(banana_suit[["soil"]][["Suitability Score"]])## CFragm CECc pHH2O SoilTe
## 1 1 0.7500 0 1
## 2 1 0.7500 0 1
## 3 1 0.7500 0 1
## 4 1 0.7500 0 1
## 5 1 0.7500 0 1
## 6 1 0.8125 0 1
head(banana_suit[["soil"]][["Suitability Class"]])## CFragm CECc pHH2O SoilTe
## 1 S1 S1 N S1
## 2 S1 S1 N S1
## 3 S1 S1 N S1
## 4 S1 S1 N S1
## 5 S1 S1 N S1
## 6 S1 S1 N S1Another 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].
Users can modify the default equally spaced intervals, for example:
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval=c(0, 0.3, 0.6, 0.9, 1))## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.
head(banana_suit[["soil"]][["Suitability Score"]])## CFragm CECc pHH2O SoilTe
## 1 1 0.7500 0 1
## 2 1 0.7500 0 1
## 3 1 0.7500 0 1
## 4 1 0.7500 0 1
## 5 1 0.7500 0 1
## 6 1 0.8125 0 1
head(banana_suit[["soil"]][["Suitability Class"]])## CFragm CECc pHH2O SoilTe
## 1 S1 S2 N S1
## 2 S1 S2 N S1
## 3 S1 S2 N S1
## 4 S1 S2 N S1
## 5 S1 S2 N S1
## 6 S1 S2 N S1The 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].
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,
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias")## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.
head(banana_suit[["soil"]][["Suitability Score"]])## CFragm CECc pHH2O SoilTe
## 1 1 0.7500 0 1
## 2 1 0.7500 0 1
## 3 1 0.7500 0 1
## 4 1 0.7500 0 1
## 5 1 0.7500 0 1
## 6 1 0.8125 0 1
head(banana_suit[["soil"]][["Suitability Class"]])## CFragm CECc pHH2O SoilTe
## 1 S1 N N S1
## 2 S1 N N S1
## 3 S1 N N S1
## 4 S1 N N S1
## 5 S1 N N S1
## 6 S1 N N S1By 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.
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.
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias")## Warning in suitability(terrain, crop_soil, mf = mf, sow_month = NULL, minimum
## = minimum, : maximum is set to 16 for factor CECc since all parameter intervals
## are equal.
banana_suit[["soil"]][["Factors Evaluated"]]## [1] "CFragm" "CECc" "pHH2O" "SoilTe"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:
banana_suit <- suit("banana", terrain=MarinduqueLT, mf="trapezoidal", interval="unbias", maximum=c(60, 20, 9, 10))
banana_suit## $terrain
## [1] "Error: No factor(s) to be evaluated, since none matches with the crop requirements. If water or temp characteristics was specified then maybe you forgot to specify the sow_month argument, read doc for suit."
##
## $soil
## [1] "Error: maximum length should be equal to the number of factors in the input land units."The result gave us an error. We understand the error for terrain
characteristics, but for soil it says that the argument
maximum must be equal in length with the target factors
specified in the input land unit datasets. 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, rather spatial variables) when specifying
minimum or maximum constants. Thus, it should
be:
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"]])## CFragm CECc pHH2O SoilTe
## 1 0 0.7500 0 0
## 2 1 0.7500 0 0
## 3 0 0.7500 0 0
## 4 0 0.7500 0 0
## 5 0 0.7500 0 0
## 6 0 0.8125 0 0
head(banana_suit[["soil"]][["Suitability Class"]])## CFragm CECc pHH2O SoilTe
## 1 N N N N
## 2 S1 N N N
## 3 N N N N
## 4 N N N N
## 5 N N N N
## 6 N N N N