Package 'shar'

calculate_energy

Description

Calculate mean energy

Usage

calculate_energy(
  pattern,
  weights = c(1, 1),
  return_mean = FALSE,
  verbose = TRUE
)

Arguments

pattern	List with reconstructed patterns.
weights	Vector with weights used to calculate energy. The first number refers to Gest(r), the second number to pcf(r).
return_mean	Logical if the mean energy is returned.
verbose	Logical if progress report is printed.

Details

The function calculates the mean energy (or deviation) between the observed pattern and all reconstructed patterns (for more information see Tscheschel & Stoyan (2006) or Wiegand & Moloney (2014)). The pair correlation function and the nearest neighbour distance function are used to describe the patterns.

Value

vector

References

Kirkpatrick, S., Gelatt, C.D.Jr., Vecchi, M.P., 1983. Optimization by simulated annealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>

Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random point patterns. Computational Statistics and Data Analysis 51, 859–871. <https://doi.org/10.1016/j.csda.2005.09.007>

Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis in ecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8

See Also

plot_energy, reconstruct_pattern, fit_point_process

Examples

pattern_random <- fit_point_process(species_a, n_random = 19)
calculate_energy(pattern_random)
calculate_energy(pattern_random, return_mean = TRUE)

## Not run: 
marks_sub <- spatstat.geom::subset.ppp(species_a, select = dbh)
marks_recon <- reconstruct_pattern_marks(pattern_random$randomized[[1]], marks_sub,
n_random = 19, max_runs = 1000)
calculate_energy(marks_recon, return_mean = FALSE)

## End(Not run)

---

classify_habitats

Description

Classify habitats

Usage

classify_habitats(raster, return_breaks = FALSE, ...)

Arguments

raster	SpatRaster with continuous environmental values.
return_breaks	Logical if breaks should be returned as well.
...	Arguments passed on to classIntervals.

Details

Classifies a SpatRaster from the raster packages with continuous values into n discrete classes. The cut function used to classify the raster, uses include.lowest = TRUE.

For more information about the classification methods, see classIntervals from the classInt package and/or the provided References. The help page of classIntervals also includes further possible arguments to find breaks (e.g., different styles, number of classes, fixed breaks, etc.).

Value

SpatRaster

References

Armstrong, M.P., Xiao, N., Bennett, D.A., 2003. Using genetic algorithms to create multicriteria class intervals for choropleth maps. Annals of the Association of American Geographers 93, 595–623. <https://doi.org/10.1111/1467-8306.9303005>

Dent, B.D., 1999. Cartography: Thematic map design, 5th ed. WCB/McGraw-Hill, Boston, USA. ISBN 978-0-697-38495-9

Fisher, W.D., 1958. On grouping for maximum homogeneity. Journal of the American Statistical Association 53, 789–798. <https://doi.org/10.1080/01621459.1958.10501479>

Jenks, G.F., Caspall, F.C., 1971. Error in choroplethic maps: Definition, measurement, reduction. Annals of the Association of American Geographers 61, 217–244. <https://doi.org/10.1111/j.1467-8306.1971.tb00779.x>

Jiang, B., 2013. Head/tail breaks: A new classification scheme for data with a heavy-tailed distribution. The Professional Geographer 65, 482-494. <https://doi.org/10.1080/00330124.2012.700499>

Slocum, T.A., McMaster, R.B., Kessler, F.C., Howard, H.H., 2009. Thematic cartography and geovisualization, 3rd ed. ed, Prentice Hall Series in Geographic Information Science. Pearson Prentice Hall, Upper Saddle River, USA. ISBN 978-0-13-229834-6

Wand, M. P., 1995. Data-based choice of histogram binwidth. The American Statistician 51, 59-64. <https://doi.org/10.1080/00031305.1997.10473591>

See Also

classIntervals

Examples

landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")

landscape_classified <- classify_habitats(terra::rast(landscape), style = "fixed",
fixedBreaks = c(0, 0.25, 0.75, 1.0), return_breaks = TRUE)

---

fit_point_process

Description

Fit point process to randomize data

Usage

fit_point_process(
  pattern,
  n_random = 1,
  process = "poisson",
  return_para = FALSE,
  return_input = TRUE,
  simplify = FALSE,
  verbose = TRUE
)

Arguments

pattern	ppp object with point pattern
n_random	Integer with number of randomizations.
process	Character specifying which point process model to use. Either "poisson" or "cluster".
return_para	Logical if fitted parameters should be returned.
return_input	Logical if the original input data is returned.
simplify	Logical if only pattern will be returned if n_random = 1 and return_input = FALSE.
verbose	Logical if progress report is printed.

Details

The functions randomizes the observed point pattern by fitting a point process to the data and simulating n_random patterns using the fitted point process. It is possible to choose between a Poisson process or a Thomas cluster process model. For more information about the point process models, see e.g. Wiegand & Moloney (2014).

Value

rd_pat

References

Plotkin, J.B., Potts, M.D., Leslie, N., Manokaran, N., LaFrankie, J.V., Ashton, P.S., 2000. Species-area curves, spatial aggregation, and habitat specialization in tropical forests. Journal of Theoretical Biology 207, 81–99. <https://doi.org/10.1006/jtbi.2000.2158>

Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis in ecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8

Examples

pattern_fitted <- fit_point_process(pattern = species_a, n_random = 39)

---

Example landscape (random cluster neutral landscape model).

Description

An example map to show landscapetools functionality generated with the NLMR::nlm_fbm() algorithm.

Usage

landscape

Format

A SpatRaster object.

Source

Simulated neutral landscape model with R. <https://github.com/ropensci/NLMR/>

---

list_to_randomized

Description

Convert list to rd_* object.

Usage

list_to_randomized(list, observed = NULL)

Arguments

list	List
observed	Observed

Details

Convert list of randomized point pattern or raster layer to a rd_* object that can be used with all functions of the package. The main purpose of this utility function is to allow an easy parallelization of the randomization approach.

For more information, please see the "Parallelization" article.

Value

rd_pat, rd_ras

See Also

randomize_raster, translate_raster, reconstruct_pattern

Examples

## Not run: 
fit_list <- lapply(X = 1:39, FUN = function(i) {fit_point_process(pattern = species_a,
n_random = 1, simplify = TRUE, return_input = FALSE, verbose = FALSE)})

list_to_randomized(list = fit_list, observed = species_a)

## End(Not run)

---

pack_randomized

Description

Save randomized raster object

Usage

pack_randomized(raster)

Arguments

raster

rd_ras object with randomized raster.

Details

Because of how SpatRaster are saved (need to be packed), this function wraps all raster objects and prepares them for saving first. For further details, see wrap.

Value

rd_ras

See Also

unpack_randomized, wrap

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
landscape_random <- randomize_raster(landscape_classified, n_random = 3)
x <- pack_randomized(raster = landscape_random)

## End(Not run)

---

plot_energy

Description

Plot energy of pattern reconstruction

Usage

plot_energy(pattern, col = NULL)

Arguments

pattern	rd_pat or rd_mar object with randomized patterns.
col	Vector with colors. Must be the same length as n_random.

Details

The function plots the decrease of the energy over time, i.e. the iterations. This can help to identify if the chosen max_runs for the reconstruction were sufficient. The pattern object must have been created using reconstruct_pattern_* .

Value

void

See Also

reconstruct_pattern, fit_point_process

Examples

## Not run: 
pattern_recon <- reconstruct_pattern(species_a, n_random = 3, max_runs = 1000)
plot_energy(pattern_recon)

marks_sub <- spatstat.geom::subset.ppp(species_a, select = dbh)
marks_recon <- reconstruct_pattern_marks(pattern_recon$randomized[[1]], marks_sub,
n_random = 1, max_runs = 1000)
plot_energy(marks_recon)

## End(Not run)

---

plot.rd_mar

Description

Plot method for rd_pat object

Usage

## S3 method for class 'rd_mar'
plot(
  x,
  what = "sf",
  n = NULL,
  probs = c(0.025, 0.975),
  ask = TRUE,
  verbose = TRUE,
  ...
)

Arguments

x	rd_mar object with randomized patterns.
what	Character specifying to plot summary functions of point patterns (what = "sf") or actual patterns (what = "pp").
n	Integer with number or vector of ids of randomized pattern to plot. See Details section for more information.
probs	Vector with quantiles of randomized data used for envelope construction.
ask	Logical if the user is asked to press <RETURN> before second summary function is plotted (only used if what = "sf").
verbose	Logical if progress report is printed.
...	Not used.

Details

The function plots the pair correlation function and the nearest neighbour function of the observed pattern and the reconstructed patterns (as "simulation envelopes").

It is also possible to plot n randomized patterns and the observed pattern using what = "pp". If n is a single number, n randomized patterns will be sampled to plot. If n is a vector, the corresponding patterns will be plotted.

Value

void

See Also

reconstruct_pattern, fit_point_process

Examples

## Not run: 
pattern_recon <- reconstruct_pattern(species_a, n_random = 1, max_runs = 1000,
simplify = TRUE, return_input = FALSE)
marks_sub <- spatstat.geom::subset.ppp(species_a, select = dbh)
marks_recon <- reconstruct_pattern_marks(pattern_recon, marks_sub,
n_random = 19, max_runs = 1000)
plot(marks_recon)

## End(Not run)

---

plot.rd_multi

Description

Plot method for rd_multi object

Usage

## S3 method for class 'rd_multi'
plot(x, verbose = TRUE, ...)

Arguments

x	rd_multi Object created with reconstruct_pattern_multi. multiple marks.
verbose	Logical if progress should be printed.
...	Currently not used

Details

Calculates and visualises various summary statistics for the results of multi-marks point pattern reconstruction.

Value

void

See Also

reconstruct_pattern_multi

---

plot.rd_pat

Description

Plot method for rd_pat object

Usage

## S3 method for class 'rd_pat'
plot(
  x,
  what = "sf",
  n = NULL,
  probs = c(0.025, 0.975),
  ask = TRUE,
  verbose = TRUE,
  ...
)

Arguments

x	rd_pat object with randomized patterns.
what	Character specifying to plot summary functions of point patterns (what = "sf") or actual patterns (what = "pp").
n	Integer with number or vector of ids of randomized pattern to plot. See Details section for more information.
probs	Vector with quantiles of randomized data used for envelope construction.
ask	Logical if the user is asked to press <RETURN> before second summary function is plotted (only used if what = "sf").
verbose	Logical if progress report is printed.
...	Not used.

Details

The function plots the pair correlation function and the nearest neighbour function of the observed pattern and the reconstructed patterns (as "simulation envelopes").

It is also possible to plot n randomized patterns and the observed pattern using what = "pp". If n is a single number, n randomized patterns will be sampled to plot. If n is a vector, the corresponding patterns will be plotted.

Value

void

See Also

reconstruct_pattern, fit_point_process

Examples

## Not run: 
pattern_random <- fit_point_process(species_a, n_random = 39)
plot(pattern_random)

pattern_recon <- reconstruct_pattern(species_b, n_random = 19,
max_runs = 1000, method = "hetero")
plot(pattern_recon)

## End(Not run)

---

plot.rd_ras

Description

Plot method for rd_ras object

Usage

## S3 method for class 'rd_ras'
plot(x, n = NULL, col, verbose = TRUE, nrow, ncol, ...)

Arguments

x	rd_ras object with randomized raster.
n	Integer with number or vector of ids of randomized raster to plot. See Details section for more information.
col	Vector with color palette used for plotting.
verbose	Logical if messages are printed.
nrow, ncol	Integer with number of rows and columns of plot grid.
...	Not used.

Details

Function to plot randomized raster. If n is a single number, n randomized raster will be sampled to plot. If n is a vector, the corresponding raster will be plotted. col, nrow, ncol are passed to plot.

Value

void

See Also

randomize_raster, translate_raster

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
landscape_random <- randomize_raster(landscape_classified, n_random = 19)
plot(landscape_random)

## End(Not run)

---

print.rd_mar

Description

Print method for rd_mar object

Usage

## S3 method for class 'rd_mar'
print(x, digits = 4, ...)

Arguments

x	rd_mar object with randomized patterns.
digits	Integer with number of decimal places (round) to be printed.
...	Arguments passed to cat.

Details

Printing method for random patterns created with reconstruct_pattern_marks.

Value

void

See Also

reconstruct_pattern_marks

Examples

## Not run: 
pattern_recon <- reconstruct_pattern(species_a, n_random = 1, max_runs = 1000,
simplify = TRUE, return_input = FALSE)
marks_sub <- spatstat.geom::subset.ppp(species_a, select = dbh)
marks_recon <- reconstruct_pattern_marks(pattern_recon, marks_sub,
n_random = 19, max_runs = 1000)
print(marks_recon)

## End(Not run)

---

print.rd_pat

Description

Print method for rd_pat object

Usage

## S3 method for class 'rd_pat'
print(x, digits = 4, ...)

Arguments

x	rd_pat object with randomized patterns.
digits	Integer with number of decimal places (round).
...	Arguments passed to cat.

Details

Printing method for random patterns created with reconstruct_pattern_*.

Value

void

See Also

reconstruct_pattern, fit_point_process

Examples

pattern_random <- fit_point_process(species_a, n_random = 199)
print(pattern_random)

## Not run: 
pattern_recon <- reconstruct_pattern(species_b, n_random = 19, max_runs = 1000,
method = "hetero")
print(pattern_recon)

## End(Not run)

---

print.rd_ras

Description

Print method for rd_ras object

Usage

## S3 method for class 'rd_ras'
print(x, ...)

Arguments

x	rd_ras object with randomized raster.
...	Arguments passed to cat.

Details

Printing method for random patterns created with randomize_raster or translate_raster.

Value

void

See Also

randomize_raster, translate_raster

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
landscape_random <- randomize_raster(landscape_classified, n_random = 19)

print(landscape_random)

## End(Not run)

---

randomize_raster

Description

Randomized-habitats procedure

Usage

randomize_raster(
  raster,
  n_random = 1,
  directions = 4,
  return_input = TRUE,
  simplify = FALSE,
  verbose = TRUE
)

Arguments

raster	SpatRaster with discrete habitat classes.
n_random	Integer with number of randomizations.
directions	Interger with cells neighbourhood rule: 4 (rook's case), 8 (queen's case).
return_input	Logical if the original input data is returned.
simplify	Logical if only the raster will be returned if n_random = 1 and return_input = FALSE.
verbose	Logical if progress report is printed.

Details

The function randomizes a habitat map with discrete classes (as SpatRaster) as proposed by Harms et al. (2001) as “randomized-habitats procedure”. The algorithm starts with an empty habitat map and starts to assign random neighbouring cells to each habitat (in increasing order of abundance in observed map). We modified the procedure slightly by increasing a probability to jump to a non-neighbouring cell as the current patch becomes larger.

In case the SpatRaster contains NA cells, this needs to be reflected in the observation window of the point pattern as well (i.e., no point locations possible in these areas).

Value

rd_ras

References

Harms, K.E., Condit, R., Hubbell, S.P., Foster, R.B., 2001. Habitat associations of trees and shrubs in a 50-ha neotropical forest plot. Journal of Ecology 89, 947–959. <https://doi.org/10.1111/j.1365-2745.2001.00615.x>

See Also

translate_raster

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
landscape_random <- randomize_raster(landscape_classified, n_random = 19)

## End(Not run)

---

reconstruct_pattern

Description

Pattern reconstruction

Usage

reconstruct_pattern(
  pattern,
  method = "homo",
  n_random = 1,
  e_threshold = 0.01,
  max_runs = 10000,
  no_change = Inf,
  annealing = 0.01,
  weights = c(1, 1),
  r_length = 255,
  r_max = NULL,
  stoyan = 0.15,
  return_input = TRUE,
  simplify = FALSE,
  verbose = TRUE,
  plot = FALSE
)

Arguments

pattern	ppp object with pattern.
method	Character with specifying the method. Either "homo", "cluster" or "hetero".
n_random	Integer with number of randomizations.
e_threshold	Double with minimum energy to stop reconstruction.
max_runs	Integer with maximum number of iterations if e_threshold is not reached.
no_change	Integer with number of iterations at which the reconstruction will stop if the energy does not decrease.
annealing	Double with probability to keep relocated point even if energy did not decrease.
weights	Vector with weights used to calculate energy. The first number refers to Gest(r), the second number to pcf(r).
r_length	Integer with number of intervals from r=0 to r=rmax for which the summary functions are evaluated.
r_max	Double with maximum distance used during calculation of summary functions. If NULL, will be estimated from data.
stoyan	Coefficient for Stoyan's bandwidth selection rule.
return_input	Logical if the original input data is returned.
simplify	Logical if only pattern will be returned if n_random=1 and return_input=FALSE.
verbose	Logical if progress report is printed.
plot	Logical if pcf(r) function is plotted and updated during optimization.

Details

The functions randomizes the observed pattern by using pattern reconstruction as described in Tscheschel & Stoyan (2006) and Wiegand & Moloney (2014). The algorithm shifts a point to a new location and keeps the change only, if the deviation between the observed and the reconstructed pattern decreases. The pair correlation function and the nearest neighbour distance function are used to describe the patterns.

The reconstruction can be stopped automatically if for n steps the energy does not decrease. The number of steps can be controlled by no_change and is set to no_change = Inf as default to never stop automatically.

The weights must be 0 < sum(weights) <= 1. To weight both summary functions identical, use weights = c(1, 1).

spatstat sets r_length to 513 by default. However, a lower value decreases the computational time, while increasing the "bumpiness" of the summary function.

The arguments n_points and window are used for method="homo" only.

method="homo":

The algorithm starts with a random pattern.

method="cluster":

The algorithm starts with a random but clustered pattern.

method="hetero":

The algorithm starts with a random but heterogeneous pattern.

Value

rd_pat

References

Kirkpatrick, S., Gelatt, C.D.Jr., Vecchi, M.P., 1983. Optimization by simulated annealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>

Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random point patterns. Computational Statistics and Data Analysis 51, 859–871. <https://doi.org/10.1016/j.csda.2005.09.007>

Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis in ecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8

See Also

calculate_energy, reconstruct_pattern_marks

Examples

## Not run: 
pattern_recon <- reconstruct_pattern(species_b, n_random = 19, max_runs = 1000)

## End(Not run)

---

reconstruct_pattern_marks

Description

Pattern reconstruction of marked pattern

Usage

reconstruct_pattern_marks(
  pattern,
  marked_pattern,
  n_random = 1,
  e_threshold = 0.01,
  max_runs = 10000,
  no_change = Inf,
  annealing = 0.01,
  r_length = 250,
  r_max = NULL,
  return_input = TRUE,
  simplify = FALSE,
  verbose = TRUE,
  plot = FALSE
)

Arguments

pattern	ppp object with pattern.
marked_pattern	ppp object with marked pattern. See Details section for more information.
n_random	Integer with number of randomizations.
e_threshold	Double with minimum energy to stop reconstruction.
max_runs	Integer with maximum number of iterations if e_threshold is not reached.
no_change	Integer with number of iterations at which the reconstruction will stop if the energy does not decrease.
annealing	Double with probability to keep relocated point even if energy did not decrease.
r_length	Integer with number of intervals from r = 0 to r = rmax for which the summary functions are evaluated.
r_max	Double with maximum distance used during calculation of summary functions. If NULL, will be estimated from data.
return_input	Logical if the original input data is returned.
simplify	Logical if only pattern will be returned if n_random = 1 and return_input = FALSE.
verbose	Logical if progress report is printed.
plot	Logical if pcf(r) function is plotted and updated during optimization.

Details

The function randomizes the numeric marks of a point pattern using pattern reconstruction as described in Tscheschel & Stoyan (2006) and Wiegand & Moloney (2014). Therefore, an unmarked as well as a marked pattern must be provided. The unmarked pattern must have the spatial characteristics and the same observation window and number of points as the marked one (see reconstruct_pattern_* or fit_point_process). Marks must be numeric because the mark-correlation function is used as summary function. Two randomly chosen marks are switch each iterations and changes only kept if the deviation between the observed and the reconstructed pattern decreases.

spatstat sets r_length to 513 by default. However, a lower value decreases the computational time while increasing the "bumpiness" of the summary function.

Value

rd_mar

References

Kirkpatrick, S., Gelatt, C.D.Jr., Vecchi, M.P., 1983. Optimization by simulated annealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>

Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random point patterns. Computational Statistics and Data Analysis 51, 859–871. <https://doi.org/10.1016/j.csda.2005.09.007>

Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis in ecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8

See Also

fit_point_process, reconstruct_pattern

Examples

## Not run: 
pattern_recon <- reconstruct_pattern(species_a, n_random = 1, max_runs = 1000,
simplify = TRUE, return_input = FALSE)
marks_sub <- spatstat.geom::subset.ppp(species_a, select = dbh)
marks_recon <- reconstruct_pattern_marks(pattern_recon, marks_sub,
n_random = 19, max_runs = 1000)

## End(Not run)

---

reconstruct_pattern_multi

Description

Pattern reconstruction of a pattern marked by multiple traits.

Usage

reconstruct_pattern_multi(
  marked_pattern,
  xr = marked_pattern$window$xrange,
  yr = marked_pattern$window$yrange,
  n_repetitions = 1,
  max_steps = 10000,
  no_change = 5,
  rcount = 250,
  rmax = 25,
  issue = 1000,
  divisor = "r",
  kernel_arg = "epanechnikov",
  timing = FALSE,
  energy_evaluation = FALSE,
  plot = FALSE,
  Lp = 1,
  bw = if (divisor %in% c("r", "d")) 0.5 else 5,
  sd = "step",
  steps_tol = 1000,
  tol = 1e-04,
  w_markcorr = c(d_d = 1, all = 1, d_all = 1, all_all = 1, d_d0 = 1, all0 = 1, d_all0 =
    1, all_all0 = 1),
  prob_of_actions = c(move_coordinate = 0.4, switch_coords = 0.1, exchange_mark_one =
    0.1, exchange_mark_two = 0.1, pick_mark_one = 0.2, pick_mark_two = 0.1),
  k = 1,
  w_statistics = c(),
  verbose = TRUE
)

Arguments

marked_pattern	ppp object with marked pattern. See Details section for more information.
xr, yr	Maximum extent in x and y direction of observation window.
n_repetitions	Integer representing the number of simulations to be performed.
max_steps	Maximum number simulation steps.
no_change	Integer representing the number of iterations (per 1000 simulation steps) after which the reconstruction is terminated if the energy does not decrease.
rcount	Integer representing the number of intervals for which the summary statistics are evaluated.
rmax	Maximum distance [m] up to which the summary statistics are evaluated.
issue	Integer that determines after how many simulations steps an output occurs.
divisor	Choice of divisor in the estimation formula: either "r" or "d".
kernel_arg	The kernel used to calculate the energy, possible kernels can be: Gaussian, Epanechnikov, Rectangular, Cumulative.
timing	Logical value: The computation time is measured if this is TRUE.
energy_evaluation	Logical value: If this is TRUE, the procedure stores the energy shares of the total energy per simulation step.
plot	Logical value: If this is TRUE, the procedure records the point pattern during optimization and updated.
Lp	Distance measure for the calculation of the energy function (Lp distance, 1 <= p < Inf).
bw	Bandwidth [m] with which the kernels are scaled, so that this is the standard deviation of the smoothing kernel.
sd	This is the standard deviation [m] used in the move_coordinate action.
steps_tol	After the value steps_tol it is checked whether the energy change is smaller than tol.
tol	Stops the procedure of energy if more than 1 - tol times no changes.
w_markcorr	Vector of possible weightings of individual mcf's. (Default: all equal).
prob_of_actions	Vector of probabilities for the actions performed. c(move_coordinate = 0.4, switch_coords = 0.1, exchange_mark_one = 0.1, exchange_mark_two = 0.1, pick_mark_one = 0.2, pick_mark_two = 0.1).
k	Vector of values k; used only if Dk is included in w_statistics.
w_statistics	vector of named weights for optional spatial statistics from the spatstat package to be included in the energy calculation. This may include Dk, K, Hs, pcf.
verbose	Logical if progress report is printed.

Details

A novel approach carries out a pattern reconstruction of marked dot patterns as described by Tscheschel and Stoyan (2006) and Wiegand and Moloney (2014).

One particular feature is the simultaneous consideration of both marks, accounting for their correlation during reconstruction.

The marked point pattern (PPP object) must is currently structured as follows: X-coordinate, Y-coordinate, metric mark (e.g. diameter at breast height), and nominal mark (e.g. tree species).It is calculated in the unit metre [m].

A combination of the mark correlation function and pair correlation function is used for pattern description. Additional summary statistics may be considered.Two randomly selected marks are chosen in each iteration, and one of various actions is performed. Changes will only be retained if the difference between the observed and reconstructed pattern decreases (minimizing energy).

This method is currently only suitable for homogeneous point patterns.

A comprehensive description of the method can be found in Wudel et al. (2023).

Value

rd_multi

References

Kirkpatrick, S., Gelatt, C.D.Jr., Vecchi, M.P., 1983. Optimization by simulated annealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>

Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random point patterns. Computational Statistics and Data Analysis 51, 859–871. <https://doi.org/10.1016/j.csda.2005.09.007>

Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis in ecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8

Wudel, C., Schlicht, R., & Berger, U. (2023). Multi-trait point pattern reconstruction of plant ecosystems. Methods in Ecology and Evolution, 14, 2668–2679. https://doi.org/10.1111/2041-210X.14206

See Also

fit_point_process, reconstruct_pattern, reconstruct_pattern_marks

Examples

## Not run: 

# Random example data set
xr <- 500
yr <- 1000
N <- 400
y <- runif(N, min = 0, max = yr)
x <- runif(N, min = 0, max = xr)

species <- sample(c("A","B"), N, replace = TRUE)
diameter <- runif(N, 0.1, 0.4)

random <- data.frame(x = x, y = y, dbh = diameter, species = factor(species))

marked_pattern <- spatstat.geom::as.ppp(random, W = spatstat.geom::owin(c(0, xr), c(0, yr)))

# Reconstruction function
reconstruction <- reconstruct_pattern_multi(marked_pattern, n_repetitions = 2,
max_steps = 10000)

## End(Not run)

---

results_habitat_association

Description

Results habitat association

Usage

results_habitat_association(
  pattern,
  raster,
  significance_level = 0.05,
  breaks = NULL,
  digits = NULL,
  verbose = TRUE
)

Arguments

pattern	ppp object with original point pattern data or rd_pat or rd_mar object with randomized point pattern.
raster	SpatRaster with original discrete habitat data or rd_ras object with randomized environmental data.
significance_level	Double with significance level.
breaks	Vector with breaks of habitat classes.
digits	Integer with digits used during rounding.
verbose	Logical if messages should be printed.

Details

The functions shows significant habitat associations by comparing the number of points within a habitat between the observed data and randomized data as described in Plotkin et al. (2000) and Harms et al. (2001). Significant positive or associations are present if the observed count in a habitat is above or below a certain threshold of the randomized count, respectively.

In case the SpatRaster contains NA cells, this needs to be reflected in the observation window of the point pattern as well (i.e., no point locations possible in these areas).

If breaks = NULL (default), only habitat labels (but not breaks) will be returned. If a vector with breaks is provided (same order as increasing habitat values), the breaks will be included as well.

Value

data.frame

References

Harms, K.E., Condit, R., Hubbell, S.P., Foster, R.B., 2001. Habitat associations of trees and shrubs in a 50-ha neotropical forest plot. Journal of Ecology 89, 947–959. <https://doi.org/10.1111/j.1365-2745.2001.00615.x>

Plotkin, J.B., Potts, M.D., Leslie, N., Manokaran, N., LaFrankie, J.V., Ashton, P.S., 2000. Species-area curves, spatial aggregation, and habitat specialization in tropical forests. Journal of Theoretical Biology 207, 81–99. <https://doi.org/10.1006/jtbi.2000.2158>

See Also

reconstruct_pattern, fit_point_process

Examples

landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
species_a_random <- fit_point_process(species_a, n_random = 199)
results_habitat_association(pattern = species_a_random, raster = landscape_classified)

---

Species a

Description

A species with negative associations to habitat 4 of landscape. Please be aware that a negative association to one habitat will inevitable lead to positive associations to other habitats (Yamada et al. 2006).

Usage

species_a

Format

A spatstat ppp object.

References

Yamada, T., Tomita, A., Itoh, A., Yamakura, T., Ohkubo, T., Kanzaki, M., Tan, S., Ashton, P.S., 2006. Habitat associations of Sterculiaceae trees in a Bornean rain forest plot. Journal of Vegetation Science 17, 559–566.

---

Species b

Description

A species with positive associations to habitat 5 of landscape. Please be aware that a positive association to one habitat will inevitable lead to negative associations to other habitats (Yamada et al. 2006)

Usage

species_b

Format

A spatstat ppp object.

References

Yamada, T., Tomita, A., Itoh, A., Yamakura, T., Ohkubo, T., Kanzaki, M., Tan, S., Ashton, P.S., 2006. Habitat associations of Sterculiaceae trees in a Bornean rain forest plot. Journal of Vegetation Science 17, 559–566.

---

translate_raster

Description

Torus translation

Usage

translate_raster(
  raster,
  steps_x = NULL,
  steps_y = NULL,
  return_input = TRUE,
  simplify = FALSE,
  verbose = TRUE
)

Arguments

raster	SpatRaster with discrete habitat classes.
steps_x, steps_y	Integer with number of steps (cells) the raster is translated into the corresponding direction. If both are null, all possible combinations are used resulting in n = ((50 + 1) * (50 + 1)) - 4 rasters.
return_input	Logical if the original input data is returned.
simplify	Logical if only the raster will be returned if n_random = 1 and return_input = FALSE.
verbose	Logical if progress report is printed.

Details

Torus translation test as described in Harms et al. (2001). The raster is shifted in all four cardinal directions by steps equal to the raster resolution. If a cell exits the extent on one side, it enters the extent on the opposite side.

The method does not allow any NA values to be present in the SpatRaster.

Value

rd_ras

References

Harms, K.E., Condit, R., Hubbell, S.P., Foster, R.B., 2001. Habitat associations of trees and shrubs in a 50-ha neotropical forest plot. Journal of Ecology 89, 947–959. <https://doi.org/10.1111/j.1365-2745.2001.00615.x>

See Also

randomize_raster

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")

landscape_random <- translate_raster(landscape_classified)
landscape_random_sub <- translate_raster(landscape_classified,
steps_x = 1:10, steps_y = 1:5)

## End(Not run)

---

unpack_randomized

Description

Load randomized raster object

Usage

unpack_randomized(raster)

Arguments

raster

rd_ras object with randomized raster.

Details

Because of how SpatRaster are saved (need to be packed), this function allows to unpack previously packed raster objects that were saved using pack_randomized. For further details, see wrap.

Value

rd_ras

See Also

pack_randomized wrap

Examples

## Not run: 
landscape_classified <- classify_habitats(terra::rast(landscape), n = 5, style = "fisher")
landscape_random <- randomize_raster(landscape_classified, n_random = 3)
x <- pack_randomized(raster = landscape_random)
y <- unpack_randomized(raster = y)

## End(Not run)

---