---
title: "Documentation"
output: html_document
---

<style>
body {
text-align: justify}
</style>

## **Quick reference guide**

For detailed guidelines and documentation, visit the full documentation at the <a href="https://iMARES-group.github.io/glossa/" target="_blank">GLOSSA website</a>.

---

## Workflow overview

1. **Start** a new analysis (`New analysis` tab)
2. **Upload** your data: occurrences, environmental layers, and optional files.
3. **Configure** analysis options: model type, pseudo-absence method, validation method.
4. **Model** fitting and projection
5. **Explore** the results (`Reports` tab)
6. **Download** outputs (`Exports` tab)

---

## Data requirements

The following files are required or optionally supported:

| Input Type | Description | Format |
|------------|-------------|--------|
| **Occurrence data** | Species records including presence/absence, coordinates, and timestamp | **tab-separated** file with columns: `decimalLongitude`, `decimalLatitude`, `pa`, `timestamp` |
| **Environmental layers** | Raster layers used as covariates for model fitting | `.zip` of `.tif, .nc, .asc` files (one per variable per timestamp) |
| **Projection layers** *(optional)* | Raster stack for projection (e.g., future scenarios) | `.zip` structured identically to environmental data |
| **Timestamp mapping** *(optional)* | Associates raster filenames with time identifiers | text file with one column (one value per row) indicating the timestamp associated with the environmental layers|
| **Study area** *(optional)* | Polygon for filtering and masking | `.geojson`, `.kml`, or `.gpkg` |
| **Target-group background** *(optional)* | Background points for target-group pseudo-absence methods | tab-separated file with same format as occurrence data (no need `pa` column, all presences) |

---

## Analysis options

### Model types
- **Native range model**: Includes a spatial smoother (longitude and latitude) and environmental predictors.
- **Suitable habitat model**: Includes environmental predictors only.

### Results
- **Model fitting**: Fits the selected model type, returns the model diagnostic, and predicts over a mean raster of the environmental space (just for model diagnostic).
- **Model projection**: Use the projection layers uploaded to predict on each timestamp and scenario.
- **Functional responses**: Estimates the relationship of species occurrences with environmental using partial dependence plots.
- **Variable importance**: Calculates the importance of each predictor as the loss of model predictive performance ussing a permutation based approach.

### Advanced settings
- **Occurrences thinning**: Apply spatial thinning on occurrence records.
- **Pseudo-absence generation**: If only presences provided pseudo-absences will be generated by random, target-group, or buffer-restricted sampling.
- **Standardization**: Z-score standardization is applied by subtracting the mean and dividing by the standard deviation.
- **Enlarge polygon**: Apply a buffer to expand the polygon if needed.
- **Model selection**: Currently, only BART is available.
- **Set a seed**: For reproducibility.

---

## Occurrence thinning

Spatial occurrence thinning in the geographic space using the following methods:

| Method | Description |
|--------|-------------|
| `"distance"` | Forces a minimum distance threshold in km between points |
| `"grid"` | Samples one occurrence from a grid with a given resolution in degrees |
| `"precision"` | Removes duplicated points given a decimal precision for the coordinates |

## Pseudo-absence strategies

Pseudo-absences are **not** absences, and therefore the interpretation of the results change. Pseudo-absences represent the available environment in the study area. Here we provide 3 pseudo-absence generation methods. For different approaches, the user can generate the pseudo-absences outside GLOSSA and provide them in the occurrence data file.

The pseudo-absence generation methods available are:

| Method | Description |
|--------|-------------|
| `"random"` | Uniform random sampling within the study area |
| `"target_group"` | Sample from a user-supplied background point dataset |
| `"buffer_restricted"` | Sample within a convez hull of species occurrences, excluding proximity to presences |

The ratio of pseudo-absences to presences and buffer distance can be specified.

---

## Cross-validation methods

Cross-validation assesses model performance and can be configured as:

| Method | Description |
|--------|-------------|
| `"k-fold"` | Random stratified cross-validation |
| `"spatial_blocks"` | Spatially-structured folds via geographic blocking |
| `"temporal_blocks"` | Based on unique `timestamp` values |

For spatial blocks, the block size can be:

- **Automatically estimated** via residual or predictor autocorrelation  
- **User-defined** (manual specification in meters)

---

## Results

After model execution, the following are available in the **Reports** tab:

- Prediction maps (native range and suitable habitat)
- Performance metrics (e.g., TSS, AUC)
- Cross-validation diagnostics
- Response curves
- Variable importance plots

---

## Exporting

- **Exports tab**: Download prediction maps, model data, variable importance, and cross-validation results. Also a configuration file with the inputs and settings of your analisys.
---

## Documentation

Comprehensive tutorials, examples, and package details are available at: <a href="https://iMARES-group.github.io/glossa/" target="_blank">full documentation</a>.
