---
title: "Retrieve Data From SHARK"
output:
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Retrieve Data From SHARK}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include=FALSE}
shark_available <- tryCatch({
  httr::status_code(httr::GET("https://shark.smhi.se/",
                               httr::timeout(5))) < 400
}, error = function(e) FALSE)
```

## SHARK

SHARK is the Swedish Ocean Archive's (Svenskt HavsARKivs) platform for data downloads. It stores biological, physical, and chemical marine environmental monitoring data. On behalf of the Swedish Agency for Marine and Water Management, SMHI serves as the national data host for oceanography and marine biology. SMHI is also recognized by UNESCO as a National Oceanographic Data Center (NODC) within the Oceanographic Data and Information (IODE) programme. The data can be accessed via a [web interface](https://shark.smhi.se/en/) or directly through the [API](https://shark.smhi.se/api/docs/), as demonstrated in this tutorial using `SHARK4R`.

## Getting Started

#### Installation

You can install the latest version of `SHARK4R` from CRAN using:
```{r, eval=FALSE}
install.packages("SHARK4R")
```

Load the `SHARK4R` library:
```{r}
library(SHARK4R)
```

## Retrieve Data Table

Data can be retrieved with the same filtering options available in [SHARK](https://shark.smhi.se/en/). To see the available filtering options, please refer to `get_shark_options()` and the information below.

```{r, include=FALSE, eval=shark_available}
shark_data <- try(
  get_shark_data(fromYear = 2019, toYear = 2020,
                 months = c(4, 5, 6), dataTypes = "Chlorophyll",
                 verbose = FALSE),
  silent = TRUE
)
if (inherits(shark_data, "try-error")) shark_available <- FALSE
```

```{r, eval=FALSE}
# Retrieve chlorophyll data for April to June from 2019 to 2020
shark_data <- get_shark_data(fromYear = 2019,
                             toYear = 2020,
                             months = c(4, 5, 6),
                             dataTypes = "Chlorophyll",
                             verbose = FALSE)

# Print data
print(shark_data)
```

```{r, echo=FALSE, eval=shark_available}
print(shark_data)
```

## Get SHARK API Options

Filtering options, including data types, dataset names, stations, taxa, and more, can be retrieved using the `get_shark_options()` function.

```{r, include=FALSE, eval=shark_available}
shark_options <- try(get_shark_options(), silent = TRUE)
if (inherits(shark_options, "try-error")) shark_available <- FALSE
```

```{r, eval=FALSE}
# Retrieve available search options
shark_options <- get_shark_options()

# List the names of the available options
names(shark_options)

# View available datatypes
dataTypes <- shark_options$dataTypes
print(dataTypes)

# View available dataset names
datasetNames <- shark_options$datasets
head(datasetNames) # Print first few dataset names
```

```{r, echo=FALSE, eval=shark_available}
names(shark_options)
dataTypes <- shark_options$dataTypes
print(dataTypes)
datasetNames <- shark_options$datasets
head(datasetNames)
```

## Retrieve Datasets (Zip-archives)

In addition to accessing data in tabular form, you can also download complete datasets packaged as zip archives. This is useful if you want to store complete datasets locally for further analysis.

To explore all available dataset names, use the `get_shark_options()`. Once you know which datasets you need, you can pass their names (or partial names) to the `get_shark_datasets()` function.

```{r, include=FALSE, eval=shark_available}
dataset_name <- datasetNames[1:2]
shark_data_zip <- try(
  get_shark_datasets(dataset_name, save_dir = tempdir(), verbose = FALSE),
  silent = TRUE
)
if (inherits(shark_data_zip, "try-error")) shark_available <- FALSE
```

```{r, eval=FALSE}
# Select a dataset name (e.g., the first two in the list)
dataset_name <- datasetNames[1:2]

# Download the dataset as a zip-archive to a temporary directory
shark_data_zip <- get_shark_datasets(dataset_name,
                                     save_dir = tempdir(),
                                     verbose = FALSE) # Quiet output

# Print the paths to the downloaded files
print(shark_data_zip)
```

```{r, echo=FALSE, eval=shark_available}
print(shark_data_zip)
```

Please note that `SHARK4R` also includes useful functions for reading local SHARK data files, such as `read_shark()` and `read_shark_deliv()`.

---

## Citation

```{r, echo=FALSE}
# Print citation
citation("SHARK4R")
```

```{r, echo=FALSE}
clean_shark4r_cache(0, clear_perm_cache = TRUE, verbose = FALSE)
```
