---
title: "Introduction to quantarticR"
output:
  html_document:
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Introduction to quantarticR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE, message = FALSE)
library(quantarcticR)
## for vignette purposes, and if this is Ben's computer, use a persistent cache_dir
if (grepl("ben_ray", qa_cache_dir())) qa_cache_dir("c:/data/Quantarctica3")

```

# Overview

The `quantarcticR` package provides access to Quantarctica data sets for R users, **without** needing QGIS to be installed. 

This vignette:

* explains what Quantarctica data is
* shows how the datasets can be used in R 
* provides examples of how you can work with them


# What is Quantarctica?

[Quantarctica](http://quantarctica.npolar.no/about.html) is a collection of Antarctic geographical datasets which works with the free, cross-platform, open-source software QGIS. It includes community-contributed, peer-reviewed data from ten different scientific themes and a professionally-designed basemap.

Quantarctica is is published and made available under [under a Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).

If you use it, please cite it:

Matsuoka K, Skoglund A, Roth G (2018) Quantarctica `dataset`. Norwegian Polar Institute. https://doi.org/10.21334/npolar.2018.8516e961

In addition, published works produced using Quantarctica are asked to cite each dataset that was used in the work. Please consult the abstract of each data set for the relevant citation.

# Caching datasets

The [quantarcticR](https://github.com/SCAR-sandpit/quantarcticR) R package provides you with flexibility to either temporarily or persistently store the data that is downloaded from Quantarctica. By default a temporary directory is used, which will only persist for the current R session. This means that data will not be re-used from session to session, and you may end up re-downloading the same data if you run the same script in different sessions.

You can instead choose to save the data to a persistent directory, by issuing the command `qa_cache_dir("persistent")` after loading the `quantarcticR` package. This will use a standard user data directory (e.g. under the user's `AppData` directory on Windows operating systems). You could also specify a particular directory to use, if you prefer:

```
qa_cache_dir("c:/my/data/directory/")
```

You can switch cache directories at any time, and you can find out the current cache directory by calling `qa_cache_dir()` with no arguments.


# Quantarctica Data Sets

Start by loading the package:

```{r}
library(quantarcticR)
```

In order to return a list of the datasets available, use the `qa_datasets` function.

```{r}
datasets <- qa_datasets()
head(datasets)
```

In the `datasets` object we can see the following:

- `layername` which is the name of the dataset
- `main_file` is the primary data file associated with each dataset
- `type` which is the object type (currently "shapefile" or "raster")
- `cached` whether it has been downloaded to the local cache or not
- `download_size` which is the size of the dataset.

# Dataset details

In order to view the details of a dataset use the `qa_dataset` function. This function gives more information about the dataset (but does not download or return the actual data). For example, with the simple basemap called "ADD Simple basemap":

```{r}
basemap <- qa_dataset("ADD Simple basemap")
basemap
```

# Fetch a dataset

To actually fetch the data, use the `qa_get` function. You can provide it with either the name of the dataset (i.e. `layername` as returned by `qa_datasets()`) or the dataset object (as returned by `qa_dataset()`).

Here we'll fetch a dataset called "AntGG Free-air gravity anomaly (10km)".

```{r}
ga_info <- qa_dataset("AntGG Free-air gravity anomaly (10km)") ## the dataset info
ga_data <- qa_get(ga_info, verbose = TRUE) ## fetch the actual data
class(ga_data)
```

# Raster Plot

The gravity anomaly data set is a raster, so we can use the raster package to plot it.

```{r gravanom}
library(raster)
plot(ga_data)
```

The Quantarctica project maintainers have gone to quite a lot of effort to create nice visual representations of the data layers, by defining colour palettes and similar. The full range of visual information is not yet available through quantarcticR, but it is a work in progress. In this case, there is a colour palette for the gravity anomaly layer:

```{r}
cmap <- ga_info$palette[[1]]
cmap
```

We need to make some tweaks to the palette to cope with the differences in how QGIS defines them compared to how `raster` expects them (we will endeavour to automatically deal with such differences in future versions of quantarcticR):

```{r}
breaks <- c(cmap$value, cellStats(ga_data, "max"))
breaks[1] <- cellStats(ga_data, "min")
```

Re-plot using that colour map, and with a land layer underneath:

```{r gravanom_with_palette}
basemap <- qa_get("ADD Simple basemap")
plot(basemap)
plot(ga_data, breaks = breaks, col = cmap$color, add = TRUE, legend = FALSE)
```

which is a little closer to the Quantarctica-rendered version of the same data layer:

![](./phys_antgg.png)


# Using datasets with sf

Read in the simple basemap "ADD Simple basemap" data as an sf object and use the ggplot2 and sf packages to create a plot.

```{r sfplot}
library(sf)
library(ggplot2)

surface_sf <- qa_get("ADD Simple basemap", shapefile_reader = sf::st_read)

class(surface_sf)
ggplot(surface_sf) + geom_sf()
```