| Title: | Robust Land-Use Optimization |
|---|---|
| Description: | Robust multi-criteria land-allocation optimization that explicitly accounts for the uncertainty of the indicators in the objective function. Solves the problem of allocating scarce land to various land-use options with regard to multiple, coequal indicators. The method aims to find the land allocation that represents the indicator composition with the best possible trade-off under uncertainty. optimLanduse includes the actual optimization procedure as described by Knoke et al. (2016) <doi:10.1038/ncomms11877> and the post-hoc calculation of the portfolio performance as presented by Gosling et al. (2020) <doi:10.1016/j.jenvman.2020.110248>. |
| Authors: | Kai Husmann [aut, cre]  ,
Volker von Groß [aut] ,
Jasper Fuchs [aut] ,
Kai Bödeker [aut] ,
Carola Paul [aut] ,
Thomas Knoke [aut] ,
Goettingen University - Forest Economics and Sustainable Land-use
Planning [cph, fnd],
TUM School of Life Sciences - Forest Management [cph, fnd] |
| Maintainer: | Kai Husmann <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.2.1 |
| Built: | 2024-11-11 05:30:06 UTC |
| Source: | https://github.com/forest-economics-goettingen/optimlanduse |
This iterative search function generates a list of all possible indicator combinations. All indicator combinations are converted into a list format, where each combination corresponds to a list entry. For each of these list entries, an optimization is performed using the initScenario and solveScenario functions of the package. How these functions work in detail (incl. example code) can be seen in the help of the respective function in the package and the README from Husmann et al. (2022). The results are entirely saved into the respective list entry. In addition, each entry is appended with the currently observed land-use portfolio and the land-use portfolio when all indicators are optimized together. Out of this list, we use the Bray-Curtis measure of dissimilarity to identify the indicators driving current land-use decisions. An example and further explanation is given in the README GitHub project page
autoSearch( coefTable, landUseObs, uValue = 1, optimisticRule = "expectation", fixDistance = 3 )autoSearch( coefTable, landUseObs, uValue = 1, optimisticRule = "expectation", fixDistance = 3 )
coefTable |
Coefficient table in the expected optimLanduse format. |
landUseObs |
Data frame with two columns. The first column has to contain the land-use options. The second column the respective shares. |
uValue |
u Value. The uncertainty value delivered in the coefTable is multiplied with this u value. The value, therefore, enables scenario analyses with differing uncertainties in relation to indicator values. Higher u values can be interpreted as a higher risk aversion of the decision maker. |
optimisticRule |
Either expectation or uncertaintyAdjustedExpectation. The rule indicates whether the optimistic outcomes of an indicator are directly reflected by their expectations or if the indicator is calculated as expectation + uncertainty when "more is better" or expectation - uncertainty respectively when "less is better". An optimization based on expectation considers only downside risks. |
fixDistance |
This optional numeric value allows to define distinct uncertainty levels for the calculation of the uncertainty space and the averaged distances of a certain land-cover composition (see Equation 9 in Husmann et al. (2020)). Passing NA disables fixDistance. In this case, the uncertainty space is defined by uValue. |
A list with all possible indicator combinations, their respective optimization results and the indicator set best describing the observed land-use decision.
Husmann, K., von Groß, V., Bödeker, K., Fuchs, J. M., Paul, C., & Knoke, T. (2022). optimLanduse: A package for multiobjective land-cover composition optimization under uncertainty. Methods in Ecology and Evolution, 00, 1– 10. https://doi.org/10.1111/2041-210X.14000
require(readxl) require(future.apply) plan(multisession) coefTable <- read_xlsx(exampleData("exampleGosling.xlsx")) # Subset to save computation time coefTable <- coefTable[coefTable$indicator %in% c("Long-term income", "Liquidity", "Protecting soil resources"),] obsLU <- data.frame(landUse = c("Pasture", "Crops", "Forest", "Plantation", "Alley Cropping", "Silvopasture"), share = c(0.59, 0.26, 0.14, 0.01, 0, 0)) combList <- autoSearch(coefTable = coefTable, landUseObs = obsLU, uValue = 2, optimisticRule = "expectation", fixDistance = 3) plan(sequential)require(readxl) require(future.apply) plan(multisession) coefTable <- read_xlsx(exampleData("exampleGosling.xlsx")) # Subset to save computation time coefTable <- coefTable[coefTable$indicator %in% c("Long-term income", "Liquidity", "Protecting soil resources"),] obsLU <- data.frame(landUse = c("Pasture", "Crops", "Forest", "Plantation", "Alley Cropping", "Silvopasture"), share = c(0.59, 0.26, 0.14, 0.01, 0, 0)) combList <- autoSearch(coefTable = coefTable, landUseObs = obsLU, uValue = 2, optimisticRule = "expectation", fixDistance = 3) plan(sequential)
The Portfolio performances are calculated and attached to the solved optimLanduse object. Each performance measure describes the relative proportion to the maximum achievable (the "target") of the indicator, given the current land use distribution and the uncertainty scenario set. The lowest performing scenario of all indicators is the degree of minimal fulfillment under the worst-possible outcome. It can thus be interpreted as the guaranteed performance. At least this proportion will be achieved across all indicators.
calcPerformance(x)calcPerformance(x)
x |
An optimized optimLanduse object. |
For further information and calculation, see the supplement of Gosling et al. (2020), Formula S5 (in the supplement of the paper) and also the paragraph optimLanduse functions and workflow - Post-processing in Husmann et al. (2022).
An optimized optimLanduse object with attached portfolio performance.
Gosling, E., Reith, E., Knoke T., Gerique, A., Paul, C. (2020): Exploring farmer perceptions of agroforestry via multi-objective optimisation: a test application in Eastern Panama. Agroforestry Systems 94. doi:10.1007/s10457-020-00519-0
Husmann, K., von Groß, V., Bödeker, K., Fuchs, J. M., Paul, C., & Knoke, T. (2022). optimLanduse: A package for multiobjective land-cover composition optimization under uncertainty. Methods in Ecology and Evolution, 00, 1– 10. https://doi.org/10.1111/2041-210X.14000
require(ggplot2) require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3) result <- solveScenario(x = init) performance <- calcPerformance(result) # Visualize the distance ggplot(performance$scenarioTable, aes(x = indicator, y = performance, color = indicator)) + geom_point() + geom_hline(yintercept = min(performance$scenarioTable$performance), linetype = "dashed", color = "red") + ylim(0, 1)require(ggplot2) require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3) result <- solveScenario(x = init) performance <- calcPerformance(result) # Visualize the distance ggplot(performance$scenarioTable, aes(x = indicator, y = performance, color = indicator)) + geom_point() + geom_hline(yintercept = min(performance$scenarioTable$performance), linetype = "dashed", color = "red") + ylim(0, 1)
The input data must suit the specific expected optimLanduse format prior to
initialization and optimization. This function
provides the possibility to easily transform data from the commonly used form
of the exemplary data
exampleData into the expected format. Please consider that the application of this function
is not mandatory and in most cases not required. Best practice is to
transform your data yourself into the expected format. Detailed information
about the expected format and possible data processing can be found on the
GitHub project page.
Note that incomplete rows, which include NA-values will be deleted
and an error message will be thrown.
dataPreparation(dat, uncertainty = "SE", expVAL = "mean")dataPreparation(dat, uncertainty = "SE", expVAL = "mean")
dat |
Data frame or tibble in the format of the |
uncertainty |
Indicates the column name of the uncertainty measure. Typical is "SE" for standard error or "SD" for standard deviation. |
expVAL |
Indicates the column name of the expected value. |
A formatted coefficients table with land-use options and indicator values ready for initialization via initScenario.
Gosling, E., Reith, E., Knoke, T. et al. Exploring farmer perceptions of agroforestry via multi-objective optimisation: a test application in Eastern Panama. Agroforest Syst 94, 2003–2020 (2020). https://doi.org/10.1007/s10457-020-00519-0
require(readxl) dat <- read_xlsx(exampleData("exampleGosling_dataPrep.xlsx"), col_names = TRUE) dat <- dataPreparation(dat, uncertainty = "sd", expVAL = "mean")require(readxl) dat <- read_xlsx(exampleData("exampleGosling_dataPrep.xlsx"), col_names = TRUE) dat <- dataPreparation(dat, uncertainty = "sd", expVAL = "mean")
optimLanduse comes bundled with exemplary data for land-use optimization. The files can also be found on your computer in the package folder './extdata'. These examples provide some quick applications of the package for demonstration and an example of the expected data structure of the data. Consider also the GitHub project page for exemplary applications of the package.
exampleData(fileName = "exampleGosling.xlsx")exampleData(fileName = "exampleGosling.xlsx")
fileName |
Name of the example file. See 'details' section for further explanation of all provided examples. |
exampleGosling.xlsx contains the freely available data from Gosling et al. (2020). exampleEmpty.xlsx contains a template for your data.
The path to the example file on your computer.
Gosling, E., Reith, E., Knoke, T. et al. Exploring farmer perceptions of agroforestry via multi-objective optimisation: a test application in Eastern Panama. Agroforest Syst 94, 2003–2020 (2020). https://doi.org/10.1007/s10457-020-00519-0
require(readxl) path <- exampleData() read_xlsx(path, col_names = FALSE) path <- exampleData("exampleGosling.xlsx") read_xlsx(path, col_names = FALSE)require(readxl) path <- exampleData() read_xlsx(path, col_names = FALSE) path <- exampleData("exampleGosling.xlsx") read_xlsx(path, col_names = FALSE)
The function initializes an optimLanduse S3 object on the basis of a coefficients table. Please note that the coefficients table must follow the expected optimLanduse format. The expected format is explained in the example on the GitHub project page and in the publication in Methods in Ecology and Evolution (Husmann et al. ,2022)
initScenario( coefTable, uValue = 1, optimisticRule = "expectation", fixDistance = 3 )initScenario( coefTable, uValue = 1, optimisticRule = "expectation", fixDistance = 3 )
coefTable |
Coefficient table in the expected optimLanduse format. |
uValue |
u Value. The uncertainty value delivered in the coefTable is multiplied with this u value. The value, therefore, enables scenario analyses with differing uncertainties in relation to indicator values. Higher u values can be interpreted as a higher risk aversion of the decision maker. |
optimisticRule |
Either expectation or uncertaintyAdjustedExpectation. The rule indicates whether the optimistic outcomes of an indicator are directly reflected by their expectations or if the indicator is calculated as expectation + uncertainty when "more is better" or expectation - uncertainty respectively when "less is better". An optimization based on expectation considers only downside risks. |
fixDistance |
This optional numeric value allows to define distinct uncertainty levels for the calculation of the uncertainty space and the averaged distances of a certain land-cover composition (see Equation 9 in Husmann et al. (2020)). Passing NA disables fixDistance. In this case, the uncertainty space is defined by uValue. |
Separating the initialization from the optimization is to save computation time in batch analysis. The separated function calls allow the user to perform multiple optimizations from one initialized object. This could save time in the scenario or sensitivity analysis.
A detailed description of the input parameters can be found in Husmann et al. (2022).
An initialized optimLanduse S3 object ready for optimization.
Husmann, K., von Groß, V., Bödeker, K., Fuchs, J. M., Paul, C., & Knoke, T. (2022). optimLanduse: A package for multiobjective land-cover composition optimization under uncertainty. Methods in Ecology and Evolution, 00, 1– 10. https://doi.org/10.1111/2041-210X.14000
require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3)require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3)
The function solves the optimization framework specified by the initialized optimLanduse object.
solveScenario(x, digitsPrecision = 4, lowerBound = 0, upperBound = 1)solveScenario(x, digitsPrecision = 4, lowerBound = 0, upperBound = 1)
x |
The initialized optimLanduse object. See |
digitsPrecision |
Precision of the loss value. digitsPrecision is the possibility to influence the calculation time. |
lowerBound |
Optional lower bounds for the land-use options. Must be 0 or a vector in the dimension of the land-use options. |
upperBound |
Optional upper bounds for the land-use options. Must be 1 or a vector in the dimension of the land-use options. |
The methodological background and the formulation of the optimization framework are described in Knoke et al. (2016) and in Husmann et al. (2022)
A solved landUse portfolio ready for export or further data processing.
Knoke, T., Paul, C., Hildebrandt, P. et al. (2016): Compositional diversity of rehabilitated tropical lands supports multiple ecosystem services and buffers uncertainties. Nat Commun 7, 11877. doi:10.1038/ncomms11877
Husmann, K., von Groß, V., Bödeker, K., Fuchs, J. M., Paul, C., & Knoke, T. (2022). optimLanduse: A package for multiobjective land-cover composition optimization under uncertainty. Methods in Ecology and Evolution, 00, 1– 10. https://doi.org/10.1111/2041-210X.14000
require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3) result <- solveScenario(x = init)require(readxl) dat <- read_xlsx(exampleData("exampleGosling.xlsx")) init <- initScenario(dat, uValue = 2, optimisticRule = "expectation", fixDistance = 3) result <- solveScenario(x = init)