# Get started

#### 2019-11-15

## Design

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 neessary complementary, but are rather different approaches for the same result.

## Preprocessing of input data

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)

    landscape_discrete <- classify_habitats(raster = landscape, classes = 5)

## Randomize environmental data

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 <- (raster::nrow(landscape) + 1) * (raster::ncol(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.

    torus_trans <- translate_raster(raster = landscape_discrete)

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

## Randomize location data

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.

    gamma_test <- fit_point_process(pattern = species_a, n_random = 39, process = "cluster")

    reconstruction <- reconstruct_pattern_homo(pattern = species_a, n_random = 39) # takes some time

## Analyse results

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.

    results_habitat_association(pattern = species_a, raster = random_walk)
    #> > Input: randomized raster | Quantile thresholds: negative < 0.025 - positive > 0.975
    #>   habitat count    lo    hi significance
    #> 1       1     9  2.95 12.05         n.s.
    #> 2       2    25  8.00 21.05     positive
    #> 3       3    27  9.95 25.10     positive
    #> 4       4     0 15.90 28.05     negative
    #> 5       5    12  4.95 19.05         n.s.

    results_habitat_association(pattern = reconstruction, raster = landscape_discrete)
    #> > Input: randomized point pattern | Quantile thresholds: negative < 0.025 - positive > 0.975
    #>   habitat count    lo    hi significance
    #> 1       1     8  1.00 23.35         n.s.
    #> 2       2    22 25.85 49.10     negative
    #> 3       3    33 40.80 68.05     negative
    #> 4       4    19 44.00 71.10     negative
    #> 5       5   118 20.85 60.05     positive

There is also the possibility to visualize the randomized data using `plot_randomized_raster()` or `plot_randomized_pattern()`.

    plot_randomized_raster(random_walk)

    plot_randomized_pattern(reconstruction)

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

    calculate_energy(pattern = reconstruction, return_mean = TRUE)
    #> [1] 0.01871392

### References

Fisher, W. D. 1958 “On grouping for maximum homogeneity”, Journal of the American Statistical Association, 53, 789-798

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(6), 947-959.

Jenks, G. F., Caspall, F. C., (1971). Error on choroplethic maps: definition, measurement, reduction. Annals, Association of American Geographers, 61(2), 217–244;

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(1), 81-99.

Tscheschel, A., & Stoyan, D. (2006). Statistical reconstruction of random point patterns. Computational Statistics and Data Analysis, 51(2), 859-871.

Wiegand, T., & Moloney, K. A. (2014). Handbook of spatial point-pattern analysis in ecology. Boca Raton: Chapman and Hall/CRC Press.