---

title: "Data visualization"

output: rmarkdown::html_vignette

vignette: >

%\VignetteIndexEntry{Data visualization}

%\VignetteEngine{knitr::rmarkdown}

%\VignetteEncoding{UTF-8}

---

```{r, include = FALSE}

knitr::opts_chunk$set(

collapse = TRUE,

eval = TRUE,

echo = TRUE,

comment = "#>",

dpi = 150,

fig.align = "center",

out.width = "80%",

fig.height = 4,

fig.width = 7

)

```

The package `forcis` provides [numerous functions](https://docs.ropensci.org/forcis/reference/index.html#visualization-tools) to visualize FORCIS data. This vignette shows how to use and customize these functions.

## Setup

First, let's import the required packages.

```{r setup}

library(forcis)

library(ggplot2)

```

Before proceeding, let's download the latest version of the FORCIS database.

```{r 'download-db', eval=FALSE}

# Create a data/ folder ----

dir.create("data")

# Download latest version of the database ----

download_forcis_db(path = "data", version = NULL)

```

The vignette will use the plankton net data of the FORCIS database. Let's import the latest release of the data.

```{r 'load-data', echo=FALSE}

file_name <- system.file(

file.path("extdata", "FORCIS_net_sample.csv"),

package = "forcis"

)

net_data <- read.csv(file_name)

```

```{r 'load-data-user', eval=FALSE}

# Import net data ----

net_data <- read_plankton_nets_data(path = "data")

```

**NB:** In this vignette, we use a subset of the plankton net data, not the whole dataset.

## Spatial visualization

### Creating a world map

The function `geom_basemap()` can be used to easily add World countries, oceans and bounding box to a `ggplot2` object.

```{r 'geom-basemap'}

# World basemap ----

ggplot() +

geom_basemap()

```

These layers come from the [Natural Earth](https://www.naturalearthdata.com/) website and are defined in the [Robinson projection](https://epsg.io/54030).

### Mapping FORCIS data

The function `ggmap_data()` can be used to plot FORCIS data on a World map. Let's map the plankton nets data.

```{r 'ggmap-raw-data'}

# Map raw net data ----

ggmap_data(net_data)

```

User can customize the aesthetic of the data:

```{r 'ggmap-raw-data-2'}

# Customize map ----

ggmap_data(net_data, col = "#ff0000", fill = NA, shape = 21, size = 3)

```

This function works with the output of various functions available in the `forcis` package. For example:

```{r 'ggmap-filtered-data', echo=TRUE, eval=FALSE}

# Filter net data ----

net_data_indian <- filter_by_ocean(net_data, ocean = "Indian Ocean")

# Map filtered data ----

ggmap_data(net_data_indian)

```

Note that the `forcis` package is pipe-friendly.

```{r 'ggmap-filtered-data-pipe', eval=FALSE}

# Same as before, but w/ the pipe ----

net_data |>

filter_by_ocean(ocean = "Indian Ocean") |>

ggmap_data()

```

You can export this map with the function `ggsave()` of the package `ggplot2`.

```{r 'ggmap-save', eval=FALSE}

# Map filtered data ----

net_data_indian_map <- net_data |>

filter_by_ocean(ocean = "Indian Ocean") |>

ggmap_data() +

ggtitle("FORCIS net data - Indian Ocean")

# Save as PNG ----

ggsave(

net_data_indian_map,

filename = "net_data_indian_map.png",

width = 20,

height = 11,

units = "cm",

dpi = 300,

scale = 1.5,

bg = "white"

)

```

## Temporal visualization

### Plot data by year of sampling

The function `plot_record_by_year()` plots the number of records (y-axis) by year (x-axis).

```{r 'plot-record-by-year'}

# Plot number of records by year ----

plot_record_by_year(net_data)

```

### Plot data by month of sampling

The function `plot_record_by_month()` plots the number of records (y-axis) by month (x-axis).

```{r 'plot-record-by-month'}

# Plot number of records by month ----

plot_record_by_month(net_data)

```

### Plot data by season

The function `plot_record_by_season()` plots the number of records (y-axis) by season (x-axis).

```{r 'plot-record-by-season'}

# Plot number of records by season ----

plot_record_by_season(net_data)

```

## Vertical visualization

### Plot data by depth of sampling

The function `plot_record_by_depth()` plots the number of records (x-axis) by depth intervals (y-axis).

```{r 'plot-record-by-depth'}

# Plot number of records by depth ----

plot_record_by_depth(net_data)

```