```
library(shar)
library(spatstat)
library(terra)
set.seed(42)
```

The core of **shar** are functions to to simulate null
model data by randomizing either the environmental data (i.e. raster
data) or the locations of species (i.e. point pattern data). The null
data is then used to analyse if significant species-habitat associations
are present. Additionally, functions to visualize and analyse the
results are available as well as some utility functions. The methods are
mainly described in Harms et al. (2001), Plotkin et al. (2000) and
Wiegand & Moloney (2014). The methods are not necessary
complementary, but are rather different approaches for the same
result.

All functions are designed for discrete habitat classes. Following,
in case only continuous data is available, this has to be classified to
discrete classes. `classify_habitats`

provides several ways
to classify the data such as the Fisher-Jenks algorithm (Fisher 1958,
Jenks & Caspall 1971)

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

There are two functions to randomize the environmental data:
`translate_raster()`

and `randomize_raster()`

. The
first function is a torus translation of the raster, shifting the
habitat map in all four cardinal directions. This is only possible for
rectangular observation areas and results in
`n_random <- (terra::nrow(terra::rast(landscape)) + 1) * (terra::ncol(terra::rast(landscape)) + 1) - 4`

randomized rasters. The other function randomizes the environmental data
using a random-walk algorithm. Here, the number of randomized rasters
can be specified using the `n_random`

argument.

However, all methods require “fully mapped data” in a sense that NA cells of the environmental data are allowed only if simultaneously these areas cannot accommodate any locations of the point pattern (e.g., a water body within a forest area). This needs to be reflected in the observation window of the point pattern. For the torus translation method, no NA values are allowed at all.

```
<- translate_raster(raster = landscape_discrete)
torus_trans
<- randomize_raster(raster = landscape_discrete, n_random = 39) random_walk
```

To randomize the location data (i.e. the point pattern) either
`fit_point_process()`

or `reconstruct_pattern()`

are available. The first fits either a Poisson process or a cluster
process to the data. The difference to solutions from the
`spatstat`

package is that the number of points is always
identical. The second functions reconstructs the spatial characteristics
of the data using pattern reconstruction (Tscheschel & Stoyan 2006).
This is advantageous for point patterns not describable by simple point
process models. For both function, the number of patterns can be
specified by the `n_random`

argument.

```
<- fit_point_process(pattern = species_b, process = "cluster", n_random = 39)
gamma_test
# (this can takes some time)
<- reconstruct_pattern(pattern = species_b, n_random = 39,
reconstruction e_threshold = 0.05, method = "cluster")
```

The most important function to analyse results is
`results_habitat_association()`

. This function compares the
observed data to the null model data and by that is able to show
significant species-habitat associations. The functions work for both,
randomized environmental data or randomized location data.

Please be aware that due to the randomization of the null model data,
results might slightly differ between different randomization approaches
(e.g., `fit_point_process()`

vs. `translate_raster()`

) and even for repetitions of the
same approach. However, the counts of the observed data should be
identical, and general results and trends should be similar.

```
results_habitat_association(pattern = species_a, raster = random_walk)
#> > Input: randomized raster
#> > Quantile thresholds: negative < 0.025 || positive > 0.975
#> habitat breaks count lo hi significance
#> 1 1 NA 35 11.00 30.20 positive
#> 2 2 NA 44 23.70 49.05 n.s.
#> 3 3 NA 36 21.75 49.05 n.s.
#> 4 4 NA 4 24.80 59.05 negative
#> 5 5 NA 73 51.95 77.05 n.s.
results_habitat_association(pattern = reconstruction, raster = landscape_discrete)
#> > Input: randomized pattern
#> > Quantile thresholds: negative < 0.025 || positive > 0.975
#> habitat breaks count lo hi significance
#> 1 1 NA 6 2.95 11.15 n.s.
#> 2 2 NA 18 19.85 51.30 negative
#> 3 3 NA 18 33.95 58.00 negative
#> 4 4 NA 21 36.90 54.05 negative
#> 5 5 NA 129 38.90 76.50 positive
```

There is also the possibility to visualize the randomized data using
the `plot()`

function.

`plot(random_walk)`

```
plot(reconstruction, ask = FALSE)
```

For the randomized point pattern data, it is also possible to show the “difference” in terms of the energy (Tscheschel & Stoyan 2006) between the patterns.

```
calculate_energy(pattern = gamma_test, return_mean = TRUE)
#> [1] 0.1318716
calculate_energy(pattern = reconstruction, return_mean = TRUE)
#> [1] 0.04907375
```

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

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

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

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

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