| 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 [aut, cre], Marco Sciaini [aut], Chris Wudel [aut], Zeke Marshall [ctb], Thomas Etherington [ctb], Janosch Heinermann [ctb] |
| Repository: | CRAN |
| Date/Publication: | 2025-01-10 13:10:02 UTC |
Package description
Description
Analyse species-habitat associations in R. Therefore, information about thelocation of the species is needed and about the environmental conditions. To testfor 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> andHarms et al. (2001) <doi:10.1111/j.1365-2745.2001.00615.x>.
Author(s)
Maintainer: Maximilian H.K. Hesselbarthmhk.hesselbarth@gmail.com (ORCID)
Authors:
Marco Sciainimarco.sciaini@posteo.net (ORCID)
Chris Wudelchris.wudel@tu-dresden.de (ORCID)
Other contributors:
Zeke Marshallee18zm@leeds.ac.uk (ORCID) [contributor]
Thomas Etheringtonteth001@aucklanduni.ac.nz (ORCID) [contributor]
Janosch Heinermannjanosch.heinermann@tu-dresden.de (ORCID) [contributor]
See Also
Useful links:
Report bugs athttps://github.com/r-spatialecology/shar/issues/
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 representsproduct-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 ofthe new point pattern. |
statistics | Results of the compute_statistics function for thenew 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 statisticsfrom the |
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 withget_dist_pairs.
Value
data.frame
See Also
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 areevaluated + Bandwidth with which the kernels are scaled, so that this is thestandard deviation of the smoothing kernel. |
r | Sequence from rmin to rmax in rcount steps. |
Details
Definition of the product-moment function for calculating the contributionof 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 observedpattern and all reconstructed patterns (for more information see Tscheschel &Stoyan (2006) or Wiegand & Moloney (2014)). The pair correlation function and thenearest neighbour distance function are used to describe the patterns.
Value
vector
References
Kirkpatrick, S., Gelatt, C.D.Jr., Vecchi, M.P., 1983. Optimization by simulatedannealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>
Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random pointpatterns. 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 inecology. 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 |
Details
Classifies a SpatRaster from theraster packages with continuousvalues into n discrete classes. Thecut function used to classify the raster,usesinclude.lowest = TRUE.
For more information about the classification methods, seeclassIntervals fromtheclassInt package and/or the provided References. The help page ofclassIntervalsalso includes further possible arguments to find breaks (e.g., different styles, numberof classes, fixed breaks, etc.).
Value
SpatRaster
References
Armstrong, M.P., Xiao, N., Bennett, D.A., 2003. Using genetic algorithms to createmulticriteria class intervals for choropleth maps. Annals of the Association ofAmerican 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 AmericanStatistical 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 aheavy-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 cartographyand 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 AmericanStatistician 51, 59-64. <https://doi.org/10.1080/00031305.1997.10473591>
See Also
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 aclassIntervals object. Ifdigits = 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 statisticsfrom the |
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 specifiedand is either rook's case (4 neighbours) or queen's case (8 neighbours).
Value
matrix
See Also
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
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 |
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 |
verbose | Logical if progress report is printed. |
Details
The functions randomizes the observed point pattern by fitting a point process tothe data and simulatingn_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 specializationin 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 inecology. 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
Example landscape (random cluster neutral landscape model).
Description
An example map to show landscapetools functionalitygenerated with theNLMR::nlm_fbm() algorithm.
Usage
landscapeFormat
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 thatcan be used with all functions of the package. The main purpose of this utility functionis 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 wrapsall raster objects and prepares them for saving first. For further details, seewrap.
Value
rd_ras
See Also
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( |
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 functionis plotted (only used if |
verbose | Logical if progress report is printed. |
... | Not used. |
Details
The function plots the pair correlation function and the nearest neighbour function ofthe observed pattern and the reconstructed patterns (as "simulation envelopes").
It is also possible to plot n randomized patterns and the observed patternusingwhat = "pp". Ifn is a single number,n randomizedpatterns will be sampled to plot. Ifn is a vector, the corresponding patternswill 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 |
verbose | Logical if progress should be printed. |
... | Currently not used |
Details
Calculates and visualises various summary statistics for the results ofmulti-marks point pattern reconstruction.
Value
void
See Also
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( |
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 functionis plotted (only used if |
verbose | Logical if progress report is printed. |
... | Not used. |
Details
The function plots the pair correlation function and the nearest neighbour function ofthe observed pattern and the reconstructed patterns (as "simulation envelopes").
It is also possible to plot n randomized patterns and the observed patternusingwhat = "pp". Ifn is a single number,n randomizedpatterns will be sampled to plot. Ifn is a vector, the corresponding patternswill 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. Ifn is a single number,n randomizedraster will be sampled to plot. Ifn is a vector, the corresponding rasterwill be plotted.col, nrow, ncol are passed toplot.
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 |
Details
The function plots the decrease of the energy over time, i.e. the iterations.This can help to identify if the chosenmax_runs for the reconstructionwere sufficient. Thepattern object must have been created usingreconstruct_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 |
Details
Printing method for random patterns created withreconstruct_pattern_marks.
Value
void
See Also
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 |
Details
Printing method for random patterns created withreconstruct_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 |
Details
Printing method for random patterns created withrandomize_raster ortranslate_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 |
verbose | Logical if progress report is printed. |
Details
The function randomizes a habitat map with discrete classes (as SpatRaster) as proposedby Harms et al. (2001) as “randomized-habitats procedure”. The algorithm starts with anempty habitat map and starts to assign random neighbouring cells to each habitat(in increasing order of abundance in observed map). We modified the procedureslightly by increasing a probability to jump to a non-neighbouring cell as thecurrent patch becomes larger.
In case the SpatRaster contains NA cells, this needs to be reflected in the observationwindow 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 oftrees 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
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 |
no_change | Integer with number of iterations at which the reconstruction willstop if the energy does not decrease. |
annealing | Double with probability to keep relocated point even if energydid 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_max | Double with maximum distance used during calculation of summary functions. If |
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 |
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 |
no_change | Integer with number of iterations at which the reconstruction willstop if the energy does not decrease. |
annealing | Double with probability to keep relocated point even if energydid 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_max | Double with maximum distance used during calculation of summary functions. If |
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 |
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 reconstructionas described in Tscheschel & Stoyan (2006) and Wiegand & Moloney (2014). Thealgorithm shifts a point to a new location and keeps the change only, if thedeviation between the observed and the reconstructed pattern decreases.The pair correlation function and the nearest neighbour distance function areused to describe the patterns.
The reconstruction can be stopped automatically if for n steps the energy does notdecrease. The number of steps can be controlled byno_change and is set tono_change = Inf as default to never stop automatically.
The weights must be 0 < sum(weights) <= 1. To weight both summary functions identical,useweights = c(1, 1).
spatstat setsr_length to 513 by default. However, a lower value decreasesthe computational time, while increasing the "bumpiness" of the summary function.
The argumentsn_points andwindow are used formethod="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 simulatedannealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>
Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random pointpatterns. 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 inecology. 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 |
no_change | Integer with number of iterations at which the reconstruction willstop if the energy does not decrease. |
annealing | Double with probability to keep relocated point even if energydid not decrease. |
r_length | Integer with number of intervals from |
r_max | Double with maximum distance used during calculation of summary functions. If |
return_input | Logical if the original input data is returned. |
simplify | Logical if only pattern will be returned if |
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 reconstructionas 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 havethe spatial characteristics and the same observation window and number of pointsas the marked one (seereconstruct_pattern_* orfit_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 thedeviation between the observed and the reconstructed pattern decreases.
spatstat setsr_length to 513 by default. However, a lower value decreasesthe 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 simulatedannealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>
Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random pointpatterns. 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 inecology. 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 sectionfor more information. |
xr,yr | Maximum extent in x and y direction of observation window. |
n_repetitions | Integer representing the number of simulations to beperformed. |
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 theenergy does not decrease. |
rcount | Integer representing the number of intervals for which thesummary statistics are evaluated. |
rmax | Maximum distance [m] up to which the summary statistics areevaluated. |
issue | Integer that determines after how many simulations steps anoutput occurs. |
divisor | Choice of divisor in the estimation formula: either "r" or "d". |
kernel_arg | The kernel used to calculate the energy, possible kernelscan 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 storesthe energy shares of the total energy per simulation step. |
plot | Logical value: If this is TRUE, the procedure records thepoint 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 isthe 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 energychange 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. |
k | Vector of values k; used only if Dk is included in w_statistics. |
w_statistics | vector of named weights for optional spatial statisticsfrom the |
verbose | Logical if progress report is printed. |
Details
A novel approach carries out a pattern reconstruction of marked dot patternsas 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 functionis used for pattern description. Additional summary statistics may beconsidered.Two randomly selected marks are chosen in each iteration, and oneof various actions is performed. Changes will only be retained if thedifference 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 simulatedannealing. Science 220, 671–680. <https://doi.org/10.1126/science.220.4598.671>
Tscheschel, A., Stoyan, D., 2006. Statistical reconstruction of random pointpatterns. 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 inecology. Chapman and Hall/CRC Press, Boca Raton. ISBN 978-1-4200-8254-8
Wudel, C., Schlicht, R., & Berger, U. (2023). Multi-trait point patternreconstruction 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 setxr <- 500yr <- 1000N <- 400y <- 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 functionreconstruction <- 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_marobject with randomized point pattern. |
raster | SpatRaster with original discrete habitat data or rd_ras object withrandomized 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 ofpoints within a habitat between the observed data and randomized data as described inPlotkin et al. (2000) and Harms et al. (2001). Significant positive or associations are presentif the observed count in a habitat is above or below a certain threshold of therandomized count, respectively.
In case the SpatRaster contains NA cells, this needs to be reflected in the observationwindow of the point pattern as well (i.e., no point locations possible in these areas).
Ifbreaks = NULL (default), only habitat labels (but not breaks) will bereturned. If a vector withbreaks 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 oftrees 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 specializationin 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 withn randomized raster or patterns. Ifn is a single number,n randomized elements will be sampledt. Ifn is a vector, thecorresponding 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 functionreconstruct_pattern_multi_trait_marks, specifies the kernel to be used tocalculate the energy, possible kernels can be: Gaussian, Epanechnikov,Rectangular, Cumulative. |
bw | Bandwidth with which the kernels are scaled, so that this is thestandard 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 tocalculate the kernel.
Value
list
Species a
Description
A species with negative associations to habitat 4 oflandscape. Please beaware that a negative association to one habitat will inevitable lead to positiveassociations to other habitats (Yamada et al. 2006).
Usage
species_aFormat
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 rainforest plot. Journal of Vegetation Science 17, 559–566.
Species b
Description
A species with positive associations to habitat 5 oflandscape. Please beaware that a positive association to one habitat will inevitable lead to negativeassociations to other habitats (Yamada et al. 2006)
Usage
species_bFormat
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 rainforest 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 representsproduct-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 translatedinto the corresponding direction. If both are null, all possible combinations are usedresulting 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 |
verbose | Logical if progress report is printed. |
Details
Torus translation test as described in Harms et al. (2001). The raster is shiftedin all four cardinal directions by steps equal to the raster resolution. If a cellexits 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 associationsof 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
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 tounpack previously packed raster objects that were saved usingpack_randomized.For further details, seewrap.
Value
rd_ras
See Also
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)