Create a conservation planning problem()
following the
mathematical formulations used in Marxan (detailed in Beyer
et al. 2016). Note that these problems are solved using
exact algorithms and not simulated annealing (i.e., the Marxan software).
marxan_problem(x, ...)
# S3 method for default
marxan_problem(x, ...)
# S3 method for data.frame
marxan_problem(x, spec, puvspr, bound = NULL, blm = 0, symmetric = TRUE, ...)
# S3 method for character
marxan_problem(x, ...)
character
file path for a Marxan input file (typically
called "input.dat"
), or data.frame
containing planning unit
data (typically called "pu.dat"
). If the argument to x
is a
data.frame
, then each row corresponds to a different planning unit,
and it must have the following columns:
integer
unique identifier for each planning unit.
These identifiers are used in the argument to puvspr
.
numeric
cost of each planning unit.
integer
indicating if each planning unit
should not be locked in the solution (0) or if it should be locked in
(2) or locked out (3) of the solution. Although Marxan allows
planning units to be selected in the initial solution (using values of
1), these values have no effect here. This column is optional.
not used.
data.frame
containing information on the features.
The argument to spec
must follow the conventions used by
Marxan for the species data file (conventionally called
"spec.dat"
). Each row corresponds to a different feature and
each column corresponds to different information about the features. It
must contain the columns listed below. Note that the argument to
spec
must contain at least one column named "prop"
or
"amount"
---but not both columns with both of these
names---to specify the target for each feature.
integer
unique identifier for each feature
These identifiers are used in the argument to puvspr
.
character
name for each feature.
numeric
relative target for each feature
(optional).
numeric
absolute target for each
feature (optional).
data.frame
containing information on the amount of
each feature in each planning unit. The argument to
puvspr
must follow the conventions used in the Marxan input
data file (conventionally called "puvspr.dat"
). It must contain the
following columns:
integer
planning unit identifier.
integer
feature identifier.
numeric
amount of the feature in the
planning unit.
NULL
object indicating that no boundary data
is required for the conservation planning problem, or a data.frame
containing information on the planning units' boundaries. The argument to
bound
must follow the conventions used in the Marxan input
data file (conventionally called "bound.dat"
). It must contain the
following columns:
integer
planning unit identifier.
integer
planning unit identifier.
numeric
length of shared boundary
between the planning units identified in the previous two columns.
numeric
boundary length modifier. This argument only
has an effect when argument to x
is a data.frame
. The
default argument is zero.
logical
does the boundary data (i.e., argument to
bound
) describe symmetric relationships between planning units?
If the boundary data contain asymmetric connectivity data,
this parameter should be set to FALSE
.
Defaults to TRUE
.
problem()
(i.e., ConservationProblem
) object.
This function is provided as a convenient wrapper for solving Marxan problems using the prioritizr package. Please note that it requires installation of the data.table package to import Marxan data files.
In previous versions, this function could not accommodate asymmetric connectivity data. It has now been updated to handle asymmetric connectivity data.
Ball IR, Possingham HP, and Watts M (2009) Marxan and relatives: Software for spatial conservation prioritisation in Spatial conservation prioritisation: Quantitative methods and computational tools. Eds Moilanen A, Wilson KA, and Possingham HP. Oxford University Press, Oxford, UK.
Beyer HL, Dujardin Y, Watts ME, and Possingham HP (2016) Solving conservation planning problems with integer linear programming. Ecological Modelling, 228: 14--22.
For more information on the correct format for for Marxan input data, see the official Marxan website and Ball et al. (2009).
# create Marxan problem using Marxan input file
# (note this example requires the data.table package to be installed)
# \dontrun{
input_file <- system.file("extdata/input.dat", package = "prioritizr")
p1 <- marxan_problem(input_file) %>%
add_default_solver(verbose = FALSE)
# solve problem
s1 <- solve(p1)
# print solution
head(s1)
#> id cost status xloc yloc locked_in locked_out solution_1
#> 1 3 0.000 0 1116623 -4493479 FALSE FALSE 0
#> 2 30 7527.275 3 1110623 -4496943 FALSE TRUE 0
#> 3 56 37349.075 0 1092623 -4500408 FALSE FALSE 0
#> 4 58 16959.021 0 1116623 -4500408 FALSE FALSE 0
#> 5 84 34220.256 0 1098623 -4503872 FALSE FALSE 0
#> 6 85 178907.584 0 1110623 -4503872 FALSE FALSE 0
# create Marxan problem using data.frames that have been loaded into R
# (note this example also requires the data.table package to be installed)
## load in planning unit data
pu_path <- system.file("extdata/input/pu.dat", package = "prioritizr")
pu_dat <- data.table::fread(pu_path, data.table = FALSE)
head(pu_dat)
#> id cost status xloc yloc
#> 1 3 0.000 0 1116623 -4493479
#> 2 30 7527.275 3 1110623 -4496943
#> 3 56 37349.075 0 1092623 -4500408
#> 4 58 16959.021 0 1116623 -4500408
#> 5 84 34220.256 0 1098623 -4503872
#> 6 85 178907.584 0 1110623 -4503872
## load in feature data
spec_path <- system.file("extdata/input/spec.dat", package = "prioritizr")
spec_dat <- data.table::fread(spec_path, data.table = FALSE)
head(spec_dat)
#> id prop spf name
#> 1 10 0.3 1 bird1
#> 2 11 0.3 1 nvis2
#> 3 12 0.3 1 nvis8
#> 4 13 0.3 1 nvis9
#> 5 14 0.3 1 nvis14
#> 6 15 0.3 1 nvis20
## load in planning unit vs feature data
puvspr_path <- system.file("extdata/input/puvspr.dat",
package = "prioritizr")
puvspr_dat <- data.table::fread(puvspr_path, data.table = FALSE)
head(puvspr_dat)
#> species pu amount
#> 1 26 56 120.344884
#> 2 26 58 45.167010
#> 3 26 84 68.047375
#> 4 26 85 9.735624
#> 5 26 86 7.803476
#> 6 26 111 478.327417
## load in the boundary data
bound_path <- system.file("extdata/input/bound.dat", package = "prioritizr")
bound_dat <- data.table::fread(bound_path, data.table = FALSE)
head(bound_dat)
#> id1 id2 boundary
#> 1 3 3 16000
#> 2 3 30 4000
#> 3 3 58 4000
#> 4 30 30 12000
#> 5 30 58 4000
#> 6 30 85 4000
# create problem without the boundary data
p2 <- marxan_problem(pu_dat, spec_dat, puvspr_dat) %>%
add_default_solver(verbose = FALSE)
# solve problem
s2 <- solve(p2)
# print solution
head(s2)
#> id cost status xloc yloc locked_in locked_out solution_1
#> 1 3 0.000 0 1116623 -4493479 FALSE FALSE 0
#> 2 30 7527.275 3 1110623 -4496943 FALSE TRUE 0
#> 3 56 37349.075 0 1092623 -4500408 FALSE FALSE 0
#> 4 58 16959.021 0 1116623 -4500408 FALSE FALSE 0
#> 5 84 34220.256 0 1098623 -4503872 FALSE FALSE 0
#> 6 85 178907.584 0 1110623 -4503872 FALSE FALSE 0
# create problem with the boundary data and a boundary length modifier
# set to 5
p3 <- marxan_problem(pu_dat, spec_dat, puvspr_dat, bound_dat, 5) %>%
add_default_solver(verbose = FALSE)
# solve problem
s3 <- solve(p3)
# print solution
head(s3)
#> id cost status xloc yloc locked_in locked_out solution_1
#> 1 3 0.000 0 1116623 -4493479 FALSE FALSE 0
#> 2 30 7527.275 3 1110623 -4496943 FALSE TRUE 0
#> 3 56 37349.075 0 1092623 -4500408 FALSE FALSE 0
#> 4 58 16959.021 0 1116623 -4500408 FALSE FALSE 0
#> 5 84 34220.256 0 1098623 -4503872 FALSE FALSE 0
#> 6 85 178907.584 0 1110623 -4503872 FALSE FALSE 0
# }