Type: Package
Title: Species-Habitat Associations
Version: 2.3.1
Maintainer: Maximilian H.K. Hesselbarth <mhk.hesselbarth@gmail.com>
Description: Analyse species-habitat associations in R. Therefore, information about the location of the species (as a point pattern) is needed together with environmental conditions (as a categorical raster). To test for significance habitat associations, one of the two components is randomized. Methods are mainly based on Plotkin et al. (2000) <doi:10.1006/jtbi.2000.2158> and Harms et al. (2001) <doi:10.1111/j.1365-2745.2001.00615.x>.
License: GPL (≥ 3)
URL: https://r-spatialecology.github.io/shar/
BugReports: https://github.com/r-spatialecology/shar/issues/
Depends: R (≥ 3.1.0)
Imports: classInt, graphics, grDevices, methods, spatstat.explore, spatstat.geom, spatstat.model, spatstat.random, stats, terra, utils
Suggests: covr, dplyr, knitr, rmarkdown, spatstat (≥ 2.0-0), testthat (≥ 3.0.0)
RoxygenNote: 7.3.2
VignetteBuilder: knitr
Encoding: UTF-8
LazyData: true
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-01-10 12:59:54 UTC; mhesselbarth
Author: Maximilian H.K. Hesselbarth ORCID iD [aut, cre], Marco Sciaini ORCID iD [aut], Chris Wudel ORCID iD [aut], Zeke Marshall ORCID iD [ctb], Thomas Etherington ORCID iD [ctb], Janosch Heinermann ORCID iD [ctb]
Repository: CRAN
Date/Publication: 2025-01-10 13:10:02 UTC

Package description

Description

Analyse species-habitat associations in R. Therefore, information about the location of the species is needed and about the environmental conditions. To test for significance habitat associations, one of the two components is randomized. Methods are mainly based on Plotkin et al. (2000) <doi:10.1006/jtbi.2000.2158> and Harms et al. (2001) <doi:10.1111/j.1365-2745.2001.00615.x>.

Author(s)

Maintainer: Maximilian H.K. Hesselbarth mhk.hesselbarth@gmail.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

energy_fun

Description

Energy function

Usage

Energy_fun(
  f,
  f0,
  statistics,
  f_,
  f0_,
  statistics_,
  fn,
  p,
  p_,
  Lp,
  w_statistics
)

Arguments

f

Result of the calc_moments_full function which represents product-moment contribution of a point at coordinates x, y with marks, for the whole new ponit pattern.

f0

Column sums of the weights of the brand correlation functions of the new point pattern.

statistics

Results of the compute_statistics function for the new point pattern (calculation of optional spatial statistics).

fn

Determination of the weightings of the mark correlation functions.

p

Defines the initial state of the new ponit pattern.

p_

Reference point pattern.

Lp

Distance measure for the calculation of the energy function (Lp distance, 1 <= p <Inf).

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.

Details

Defining the Energy_fun function to calculate the "energy" of the pattern (where a lower energy indicates a better match).

Value

vector

calc_gest

Description

Calculate Gest

Usage

calc_gest(dist, r, n_points)

Arguments

dist

matrix with distance pairs.

r

vector with distances r.

n_points

numeric with number of points

Details

Calculates Gest based on distances created with get_dist_pairs.

Value

data.frame

See Also

get_dist_pairs

calc_moments

Description

Calculate moments

Usage

calc_moments(fn, p, exclude = NULL, x, y, mark, kernel, rmax_bw, r)

Arguments

fn

Determination of the weightings of the mark correlation functions.

p

Defines the initial state of the new ponit pattern.

exclude

Vector indicating which values not to use.

x, y

x and y coordinates of the points from the reference point pattern.

mark

Marks the currently viewed point pattern.

kernel

Result of the kernel calculation, calculated with the calc_kernels function.

rmax_bw

Maximum distance at which the summary statistics are evaluated + Bandwidth with which the kernels are scaled, so that this is the standard deviation of the smoothing kernel.

r

Sequence from rmin to rmax in rcount steps.

Details

Definition of the product-moment function for calculating the contribution of a point at the coordinates x, y with marking.

Value

matrix

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)

classint_to_vector

Description

Convert classIntervals to vector

Usage

classint_to_vector(x, digits = NULL)

Arguments

x

classIntervals object

digits

Integer with digits used for rounding.

Details

Returns a character vector with breaks of a classIntervals object. If digits = NULL, results will not be rounded

Value

vector

Examples

## Not run: 
classint_to_vector(x = landscape_classified$breaks, digits = 4)

## End(Not run)

compute_statistics

Description

Compute summary statistics

Usage

compute_statistics(x, y, k, xr, yr, w_statistics, bw, divisor, kernel_arg, r)

Arguments

x, y

x and y coordinates of the points from the reference point pattern.

k

Vector of values k; used only if Dk is included in w_statistics below.

xr, yr

x and y extension of the observation window (start, end).

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.

bw, divisor, kernel_arg, r

Several parameters related to summary function.

Details

Compute optional spatial statistics using the spatstat package.

Value

list

create_neighbourhood

Description

Create neighbourhood

Usage

create_neighbourhood(cells, matrix, directions = 4)

Arguments

cells

Matrix with cell ids of focal cells.

matrix

Matrix in which cells are located.

directions

Integer with cells neighbourhood rule: 4 (rook's case), 8 (queen's case).

Details

Get cell ids of all neighbouring cells. The neighbourhoood rule can be specified and is either rook's case (4 neighbours) or queen's case (8 neighbours).

Value

matrix

See Also

randomize_raster

Examples

## Not run: 
mat <- matrix(1, nrow= 10, ncol = 10)
cell_id <- rbind(cbind(3,5), cbind(7,1))
create_neighbourhood(cell_id, mat)

## End(Not run)

extract_points

Description

Extract points

Usage

extract_points(raster, pattern)

Arguments

raster

SpatRaster with environmental data

pattern

ppp object with point pattern.

Details

The function extracts the number of points within each discrete habitat.

Value

data.frame

See Also

results_habitat_association

Examples

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

## End(Not run)

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)

get_dist_pairs

Description

Distance between points

Usage

get_dist_pairs(X, rmax)

Arguments

X

ppp object

rmax

Numeric with maximum distance

Details

Returns matrix with point pairs and distances between them.

Value

matrix

See Also

pcf.ppp

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

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)

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_algorithm

Description

Pattern reconstruction (internal)

Usage

reconstruct_algorithm(
  pattern,
  method,
  n_random,
  e_threshold,
  max_runs,
  no_change,
  annealing,
  weights,
  r_length,
  r_max,
  stoyan,
  verbose,
  plot
)

Arguments

pattern

ppp object with pattern.

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.

verbose

Logical if progress report is printed.

plot

Logical if pcf(r) function is plotted and updated during optimization.

Value

list

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)

sample_randomized

Description

Sample randomized list

Usage

sample_randomized(randomized, n = NULL, verbose = TRUE)

Arguments

randomized

List with randomized raster or patterns.

n

Integer with number or vector of ids of randomized pattern to plot.

verbose

Logical if progress report is printed.

Details

Get list with n randomized raster or patterns. If n is a single number, n randomized elements will be sampledt. If n is a vector, the corresponding elements will be returned.

Value

list

Examples

## Not run: 
sample_randomized(randomized = reconstruction$randomized, n = c(5, 10, 15))

## End(Not run)

select_kernel

Description

Kernel selection

Usage

select_kernel(kernel_arg, bw, rmax, divisor)

Arguments

kernel_arg

Parameter of the function reconstruct_pattern_multi_trait_marks, specifies the kernel to be used to calculate the energy, possible kernels can be: Gaussian, Epanechnikov, Rectangular, Cumulative.

bw

Bandwidth with which the kernels are scaled, so that this is the standard deviation of the smoothing kernel.

rmax

Maximum distance at which the summary statistics are evaluated.

divisor

Divisor in the smoothing kernel, d or r.

Details

Returns the function of the selected kernel, which is then used to calculate the kernel.

Value

list

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.

dummy_transf

Description

Tranfsorm to dummy variables

Usage

to_dummy(f)

Arguments

f

Result of the calc_moments_full function which represents product-moment contribution of a point at coordinates x, y with marks, for the whole point pattern.

Details

Function for the transformation of variables to dummy variables and back

Value

matrix

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)