README.Rmd

---
title: "topotools"
output: github_document
---

Coding tools for working with local copies of [ETOPO data](https://www.ncei.noaa.gov/products/etopo-global-relief-model) and [GEBCO data](https://www.gebco.net/data_and_products/gridded_bathymetry_data/#global).

### ETOPO Citation
```
NOAA National Centers for Environmental Information. 2022: ETOPO 2022 15 Arc-Second Global Relief Model. NOAA National Centers for Environmental Information. DOI: 10.25921/fd45-gt74. Accessed 2023-03-17.
```

### GEBCO Citation
```
GEBCO Compilation Group (2022) GEBCO_2022 Grid (doi:10.5285/e0f0bb80-ab44-2739-e053-6c86abc0289c) Accessed 2023-03-17.
```

## Requirements

+ [terra](https://CRAN.R-project.org/package=terra)

+ [stars](https://CRAN.R-project.org/package=stars)

+ [sf](https://CRAN.R-project.org/package=sf)

+ [dplyr](https://CRAN.R-project.org/package=dplyr)

+ [ncdf4](https://CRAN.R-project.org/package=ncdf4)

## Installation

```
devtools::install_github("BigelowLab/topotools")
```

## Usage

```{r load_packages, message = FALSE}
library(topotools)
library(stars)
```

### Paths

ETOPO and GEBCO datasets are very large.  We suggest that you download them to a directory for bathymetry/topography datasets. Then store the path description to this directory in a hidden text file called `~/.topodata` in your home directory.  We can help with that.  Let's say your path is `/mnt/s1/projects/ecocast/coredata/bathy`.  Then just call the `set_root_path()` function from the `topotools` package like this.

```
set_root_path(path = "/mnt/s1/projects/ecocast/coredata/bathy", filename = "~/.topodata")
```

You don't need to do this each time you use the package; just once before your first use, and, of course, again if you move your data.

### The Data

Within this data directory create two subdirectories: `gebco` and `etopo`. 

Into the `gebco` directory store the "GEBCO_YYYY Grid
(ice surface elevation)" NetCDF file, where `YYYY` is obviously a 4 digit year.  It may download as a zipped file, but be sure to unzip it. You can find the [GEBCO data here](https://www.gebco.net/data_and_products/gridded_bathymetry_data/#global).

Into the `etopo` directory store either the 30 arc-second or 60 arc-second (or both!) NetCDF file. You can find [ETOPO data here](https://www.ncei.noaa.gov/products/etopo-global-relief-model).

Now you are all set to use the package. 

### Read in a region

While it is possible to read in the entire dataset for each source, generally the practice is to read in a portion defined by a bounding box specified in `[west, east, south, north]` order.

```{r etopo}
bb <- c( -72,  -63,   39,   46)
(etopo_files = list_etopo())
etopo <- read_etopo("ETOPO_2022_v1_60s_N90W180_surface.nc", bb = bb)
etopo
```

```{r}
(gebco_files = list_gebco())
gebco <- read_gebco("GEBCO_2022.nc", bb = bb)

gebco
```

Note that the GEBCO data provides approximately 4x the resolution of the ETOPO1 data.

For display purposes, it is helpful to clip each raster into a small range of values.

```{r}
plot(etopo, 
     main = "ETOPO1",
     axes = TRUE)
```

```{r}
plot(gebco, 
     main = "GEBCO", 
     axes = TRUE)
```


### Masking

The `mask_topo` function will work with either data set (well, any `terra::SpatRaster` or `stars::stars` object.) It has optional arguments, but at its simplest...

```{r mask}
masked_etopo = mask_topo(etopo)
plot(masked_etopo, axes = TRUE)
```