---
title: "Getting Started"
output: rmarkdown::html_vignette
bibliography: ../inst/references.bib
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
set.seed(42)
library("mlr3")
library("mlr3spatiotempcv")

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

This package adds resampling methods for the {mlr3} package framework suited for spatial, temporal and spatiotemporal data.
These methods can help to reduce the influence of [autocorrelation](https://mlr3book.mlr-org.com/special-tasks.html#spatiotemporal-intro) on performance estimates when performing cross-validation.
While this article gives a rather technical introduction to the package, a more applied approach can be found in the [mlr3book section on "Spatiotemporal Analysis"](https://mlr3book.mlr-org.com/special-tasks.html#spatiotemporal).

After loading the package via `library("mlr3spatiotempcv")`, the spatiotemporal resampling methods and example tasks provided by {mlr3spatiotempcv} are available to the user **alongside the default {mlr3} resampling methods and tasks**.

## Creating a spatial Task

To make use of spatial resampling methods, a {mlr3} task that is aware of its spatial characteristic needs to be created.
Two child classes exist in {mlr3spatiotempcv} for this purpose: 

- `TaskClassifST`
- `TaskRegrST`

To create one of these, one can either pass a `sf` object as the "backend" directly:

```r
# create 'sf' object
data_sf = sf::st_as_sf(ecuador, coords = c("x", "y"))

# create mlr3 task
task = TaskClassifST$new("ecuador_sf",
  backend = data_sf, target = "slides", positive = "TRUE"
)
```

or use a plain `data.frame`.
In this case, the constructor of `TaskClassifST` needs a few more arguments:

```r
data = mlr3::as_data_backend(ecuador)
task = TaskClassifST$new("ecuador",
  backend = data, target = "slides",
  positive = "TRUE", extra_args = list(coordinate_names = c("x", "y"))
)
```

Now this Task can be used as a normal {mlr3} task in any kind of modeling scenario.
Have a look at the [mlr3book section on "Spatiotemporal Analysis"](https://mlr3book.mlr-org.com/special-tasks.html#spatiotemporal) on how to apply a spatiotemporal resampling method to such a task.

# Contributed assets by {mlr3spatiotempcv}

In {mlr3}, dictionaries are used for overview purposes of available methods.
The following sections show which dictionaries get appended with new entries when loading {mlr3spatiotempcv}.

# Task Type

Additional task types:

-   `TaskClassifST`

-   `TaskRegrST`

```{r}
mlr_reflections$task_types
```

# Task Column Roles

Additional column roles:

-   `coordinates`

```{r}
mlr_reflections$task_col_roles
```

# Resampling Methods

Additional resampling methods:

-   `spcv_block`

-   `spcv_buffer`

-   `spcv_coords`

-   `spcv_disc`

-   `spcv_tiles`

-   `spcv_env`

-   `sptcv_cluto`

-   `sptcv_cstf`

and their respective repeated versions.

```{r, warning=FALSE}
as.data.table(mlr_resamplings)
```

# Examples Tasks

Additional example tasks:

- `tsk("ecuador")` (spatial, classif)
- `tsk("cookfarm")` (spatiotemp, regr)

# Upstream Packages and Scientific References

The following table lists all spatiotemporal methods implemented in {mlr3spatiotempcv} (or {mlr3}), their upstream R package and scientific references.
All methods besides `"spcv_buffer"` also have a corresponding "repeated" method.

+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| Category                       | (Package) Method Name                         | Reference         | mlr3 Notation                        |
+================================+===============================================+===================+======================================+
| **Buffering**, spatial         | (blockCV) Spatial Buffering                   | @valavi2018       | `rsmp("spcv_buffer")`                |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Buffering**, spatial         | (sperrorest) Spatial Disc                     | @brenning2012     | `rsmp("spcv_disc")`                  |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Blocking**, spatial          | (blockCV) Spatial Blocking                    | @valavi2018       | `rsmp("spcv_block")`                 |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Blocking**, spatial          | (sperrorest) Spatial Tiles                    | @valavi2018       | `rsmp("spcv_tiles")`                 |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Clustering**, spatial        | (sperrorest) Spatial CV                       | @brenning2012     | `rsmp("spcv_coords")`                |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Clustering**, feature-space  | (blockCV) Environmental Blocking              | @valavi2018       | `rsmp("spcv_env")`                   |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| ------------------------------ | --------------------------------------------- | ----------------- | ------------------------------------ |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Grouping**, predefined inds  | (mlr3) Predefined partitions                  |        -          | `rsmp("custom_cv")`                  |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Grouping**, spatiotemporal   | (mlr3) via `col_roles` `"group"`              |        -          | `rsmp("cv")`, `Task$set_col_roles()` |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Grouping**, spatiotemporal   | (CAST) Leave-Location-and-Time-Out            | @meyer2018        | `rsmp("sptcv_cstf")`                 |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+
| **Clustering**, spatiotemporal | (skmeans) Spatiotemporal Clustering           | @zhao2002         | `rsmp("sptcv_cluto")`                |
+--------------------------------+-----------------------------------------------+-------------------+--------------------------------------+

# References
