Title: Robust Land-Use Optimization
Version: 1.2.1
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>.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.2.3
Imports: lpSolveAPI (≥ 5.5.2.0-17.7), tidyr (≥ 1.1.2), dplyr (≥ 1.0.0), future (≥ 1.28.0), future.apply (≥ 1.9.0)
Suggests: readxl, ggplot2
URL: https://github.com/Forest-Economics-Goettingen/optimLanduse/
NeedsCompilation: no
Packaged: 2024-02-21 14:59:14 UTC; khusman1
Author: Kai Husmann ORCID iD [aut, cre], Volker von Groß ORCID iD [aut], Jasper Fuchs ORCID iD [aut], Kai Bödeker ORCID iD [aut], Carola Paul ORCID iD [aut], Thomas Knoke ORCID iD [aut], Goettingen University - Forest Economics and Sustainable Land-use Planning [cph, fnd], TUM School of Life Sciences - Forest Management [cph, fnd]
Maintainer: Kai Husmann <kai.husmann@uni-goettingen.de>
Repository: CRAN
Date/Publication: 2024-02-21 15:10:02 UTC

Optimize all possible indicator combinations

Description

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

Usage

autoSearch(
  coefTable,
  landUseObs,
  uValue = 1,
  optimisticRule = "expectation",
  fixDistance = 3
)

Arguments

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.

Value

A list with all possible indicator combinations, their respective optimization results and the indicator set best describing the observed land-use decision.

References

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

Examples

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)

Attach portfolio performance and distance to target

Description

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.

Usage

calcPerformance(x)

Arguments

x

An optimized optimLanduse object.

Details

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).

Value

An optimized optimLanduse object with attached portfolio performance.

References

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

Examples

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)

Transform data into the expected format

Description

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.

Usage

dataPreparation(dat, uncertainty = "SE", expVAL = "mean")

Arguments

dat

Data frame or tibble in the format of the exampleData. Please refer to the GitHub project page for more details.

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.

Value

A formatted coefficients table with land-use options and indicator values ready for initialization via initScenario.

References

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

Examples

require(readxl)
dat <- read_xlsx(exampleData("exampleGosling_dataPrep.xlsx"), col_names = TRUE)
dat <- dataPreparation(dat, uncertainty = "sd", expVAL = "mean")

Exemplary data in the required format

Description

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.

Usage

exampleData(fileName = "exampleGosling.xlsx")

Arguments

fileName

Name of the example file. See 'details' section for further explanation of all provided examples.

Details

exampleGosling.xlsx contains the freely available data from Gosling et al. (2020). exampleEmpty.xlsx contains a template for your data.

Value

The path to the example file on your computer.

References

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

Examples

require(readxl)
path <- exampleData()
read_xlsx(path, col_names = FALSE)
path <- exampleData("exampleGosling.xlsx")
read_xlsx(path, col_names = FALSE)

Initialize the robust optimization

Description

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)

Usage

initScenario(
  coefTable,
  uValue = 1,
  optimisticRule = "expectation",
  fixDistance = 3
)

Arguments

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.

Details

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).

Value

An initialized optimLanduse S3 object ready for optimization.

References

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

Examples

require(readxl)
dat <- read_xlsx(exampleData("exampleGosling.xlsx"))

init <- initScenario(dat,
                     uValue = 2,
                     optimisticRule = "expectation",
                     fixDistance = 3)

Perform the optimization

Description

The function solves the optimization framework specified by the initialized optimLanduse object.

Usage

solveScenario(x, digitsPrecision = 4, lowerBound = 0, upperBound = 1)

Arguments

x

The initialized optimLanduse object. See initScenario for the initialization.

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.

Details

The methodological background and the formulation of the optimization framework are described in Knoke et al. (2016) and in Husmann et al. (2022)

Value

A solved landUse portfolio ready for export or further data processing.

References

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

Examples

require(readxl)
dat <- read_xlsx(exampleData("exampleGosling.xlsx"))
init <- initScenario(dat, uValue = 2,
                     optimisticRule = "expectation",
                     fixDistance = 3)
result <- solveScenario(x = init)