Package 'rerddapXtracto'

Title: Extracts Environmental Data from 'ERDDAP™' Web Services
Description: Contains three functions that access environmental data from any 'ERDDAP™' data web service. The rxtracto() function extracts data along a trajectory for a given "radius" around the point. The rxtracto_3D() function extracts data in a box. The rxtractogon() function extracts data in a polygon. All of those three function use the 'rerddap' package to extract the data, and should work with any 'ERDDAP™' server. There are also two functions, plotBBox() and plotTrack() that use the 'plotdap' package to simplify the creation of maps of the data.
Authors: Roy Mendelssohn [aut, cre], Marie Auger-Methe [ctb], Sunny Bak-Hospital [ctb]
Maintainer: Roy Mendelssohn <[email protected]>
License: CC0
Version: 1.2.1
Built: 2024-11-16 05:21:34 UTC
Source: https://github.com/rmendels/rerddapxtracto

Help Index

cmocean colors The cmocean color palette by Kristen Thyng

Description

str(cmocean) List of 22 $ algae $ amp $ balance $ curl $ deep $ delta $ dense $ diff $ gray $ haline $ ice $ matter $ oxy $ phase $ rain $ solar $ speed $ tarn $ tempo $ topo $ thermal $ turbid

Usage

cmocean

Format

An object of class list of length 22.

cmocean colors The cmocean color palette by Kristen Thyng as implemented in the R package "oce"

Description

str(colors) List of 13 $ viridis $ cdom $ chlorophyll $ density $ freesurface $ oxygen $ par $ phase $ salinity $ temperature $ turbidity $ velocity $ vorticity

Usage

colors

Format

An object of class list of length 13.

dataInfo Data

Description

pre-Download of 'rerddap' info needed for examples so can run within CRAN Time limits

Usage

dataInfo

Format

An object of class info of length 3.

Details

obtained using dataInfo <- rerddap::info('erdHadISST')

Marlin Tag Data

Description

Telemetry data of a blue marlin tagged in the Pacific Ocean in 2003

Usage

Marlintag38606

Format

A data frame with 152 obs. of 7 variables:

date

time of observation given as YYYY-MM-DD

lon

longitude of observation

lat

latitude of observation

lowLon

low error on longitude

higLon

high error on longitude

lowLat

low error on latitude

higLat

high error on latitude

Source

Dr. Mike Musyl, Pelagic Research Group LLC

MBNMS Boundaries

Description

A dataset containing the latitudes and longitudes of a polygon that define boundaries of the Monterey Bay National Marine Sanctuary.

Usage

mbnms

Format

A data frame with 6666 obs. of 2 variables:

Longitude

Longitudes of a boundary polygon

Latitude

Latitudes of a boundary polygon

Source

https://sanctuaries.noaa.gov/library/imast_gis.html

MBsst Data

Description

pre-Download of Pacific West Coast SST fro use in 'plotBBox()' example can run within CRAN Time limits

Usage

MBsst

Format

An object of class list (inherits from rxtracto3D) of length 6.

Details

obtained using the 'rxtracto_3D()' command dataInfo <- rerddap::info('erdMBsstd1day') parameter <- 'sst' xcoord <- c(230, 230.1) ycoord <- c(33, 33.1) tcoord <- c('2006-01-15', '2006-01-15') zcoord <- c(0., 0.) MBsst <- rxtracto_3D(dataInfo, parameter, xcoord = xcoord, ycoord = ycoord, tcoord = tcoord, zcoord = zcoord)

Polar Bear Track Data

Description

Telemetry data of a tagged polar bear

Usage

PB_Argos

Format

A data frame with 1919 obs. of 4 variables:

DateTime

time of observation

QualClass

Quality Flag

Lat

latitude of observation

Lon

longitude of observation

Source

dryad dataset

https://datadryad.org/stash/dataset/doi:10.5061/dryad.4qrfj6q96

Citation

Auger-Méthé, Marie; Derocher, Andrew E. (2021). Argos and GPS data for a polar bear track [Dataset]. Dryad. https://doi.org/10.5061/dryad.4qrfj6q96

Associated Paper

Auger-Méthé, M., Newman, K., Cole, D., Empacher, F., Gryba, R., King, A. A., Leos-Barajas, V., Mills Flemming, J., Nielsen, A., Petris, G., and Thomas, L.. 2021. A guide to state–space modeling of ecological time series. Ecological Monographs 91(4):e01470. 10.1002/ecm.1470

plot result of 'rxtracto_3D'

Description

plotBBox is a function to plot the results from 'rxtracto_3D'()' and 'rxtractogon()'

Usage

plotBBox(
  resp,
  plotColor = "viridis",
  time = NA,
  myFunc = NA,
  mapData = NULL,
  crs = NULL,
  animate = FALSE,
  cumulative = FALSE,
  name = NA,
  maxpixels = 10000
)

Arguments

resp

data frame returned from 'rxtracto_3D'()' or 'rxtractogon()'
plotColor

the color to use in plot from 'cmocean'
time

a function to map multi-time to one, or else identity for animation
myFunc

function of one argument to transform the data
mapData

map data from 'maps' or 'mapdata', must be of class 'map'
crs

valid crs string
animate

if multiple times, if TRUE will animate the maps
cumulative

makes cumulative animation of data
name

name for colorbar label
maxpixels

maximum number of pixels to use in making the map - controls resolution

Value

a 'plotdap' plot

Examples

## example code to download data for plotBBox
## dataInfo <- rerddap::info('erdMBsstd1day')
## parameter <- 'sst'
## xcoord <- c(230, 230.1)
## ycoord <- c(33, 33.1)
## tcoord <- c('2006-01-15', '2006-01-15')
## zcoord <- c(0., 0.)
## MBsst <- rxtracto_3D(dataInfo, parameter, xcoord = xcoord, ycoord = ycoord,
##                      tcoord = tcoord, zcoord = zcoord)
##
## low resolution selected to keep time to render down
# suppressWarnings(p <- plotBBox(MBsst, maxpixels = 50))

plot result of 'rxtracto'

Description

plotTrack is a function to plot the results from 'rxtracto()'

Usage

plotTrack(
  resp,
  xcoord,
  ycoord,
  tcoord,
  plotColor = "viridis",
  myFunc = NA,
  mapData = NULL,
  crs = NULL,
  animate = FALSE,
  cumulative = FALSE,
  name = NA,
  shape = 20,
  size = 0.5
)

Arguments

resp

data frame returned from 'rxtracto()'
xcoord

passed to 'rxtracto()'
ycoord

passed to 'rxtracto()'
tcoord

passed to 'rxtracto()'
plotColor

the color to use in plot from 'cmocean'
myFunc

function of one argument to transform the data
mapData

map data from 'maps' or 'mapdata', must be of class 'map'
crs

valid crs string
animate

if multiple times, if TRUE will animate the maps
cumulative

makes cumulative animation of data
name

name for colorbar label
shape

shape to use to mark track
size

size of shape to use to mark track

Value

a 'plotdap' plot

Examples

## example data download for plotTrack
## tagData <- Marlintag38606
## xpos <- tagData$lon[1:20]
## ypos <- tagData$lat[1:20]
## tpos <- tagData$date[1:20]
## zpos <- rep(0., length(xpos))

## example data download for plotTrack
## swchlInfo <- rerddap::info('erdSWchla8day')
##scwchl <- rxtracto(swchlInfo, parameter = 'chlorophyll', xcoord = xpos,
##        ycoord = ypos, tcoord = tpos, zcoord = zpos, xlen = .2, ylen = .2)
##
# suppressWarnings(p <- plotTrack(swchl, xpos, ypos, tpos, plotColor = 'algae'))

Extract environmental data along a trajectory from an 'ERDDAP™' server using 'rerddap'.

Description

rxtracto_new uses the R program 'rerddap' to extract environmental data from an 'ERDDAP' server along a (x,y,z, time) trajectory.

Usage

rxtracto(
  dataInfo,
  parameter = NULL,
  xcoord = NULL,
  ycoord = NULL,
  zcoord = NULL,
  tcoord = NULL,
  xlen = 0,
  ylen = 0,
  zlen = 0,
  xName = "longitude",
  yName = "latitude",
  zName = "altitude",
  tName = "time",
  interp = NULL,
  verbose = FALSE,
  progress_bar = FALSE
)

Arguments

dataInfo

- the return from an 'rerddap::info' call to an 'ERDDAP™' server
parameter

- character string containing the name of the parameter to extract
xcoord

- a real array with the x-coordinates of the trajectory (if longitude in #' decimal degrees East, either 0-360 or -180 to 180)
ycoord

- a real array with the y-coordinate of the trajectory (if latitude in decimal degrees N; -90 to 90)
zcoord

-a real array with the z-coordinate of the trajectory (usually altitude or depth)
tcoord

- a character array with the times of the trajectory in "YYYY-MM-DD" - for now restricted to be time.
xlen

- real array defining the longitude box around the given point (xlen/2 around the point)
ylen

- real array defining the latitude box around the given point (ylen/2 around the point)
zlen

- real array defining the depth or altitude box around the given point (zlen/2 around the point)
xName

- character string with name of the xcoord in the 'ERDDAP™' dataset (default "longitude")
yName

- character string with name of the ycoord in the 'ERDDAP™' dataset (default "latitude")
zName

- character string with name of the zcoord in the 'ERDDAP™' dataset (default "altitude")
tName

- character string with name of the tcoord in the 'ERDDAP™' dataset (default "time")
interp

- array (size 2) of character strings - c(interpolation type, neighborhood) Uses the new ERDDAP interpoation option to get values See Vignette for details Default is Null, do not use the interpolation option
verbose

- logical variable (default FALSE) if the the URL request should be verbose
progress_bar

- logical variable (default FALSE) should a progress bar be displayed

Value

If success a dataframe containing:

  • column 1 = mean of data within search radius

  • column 2 = standard deviation of data within search radius

  • column 3 = number of points found within search radius

  • column 4 = time of returned value

  • column 5 = min longitude of call (decimal degrees)

  • column 6 = max longitude of call (decimal degrees)

  • column 7 = min latitude of call (decimal degrees)

  • column 8 = max latitude of call (decimal degrees)

  • column 9 = requested time in tag

  • column 10 = median of data within search radius

  • column 11 = median absolute deviation of data within search radius

else an error string

Examples

## toy example to show use
## but keep execution time down
##
# dataInfo <- rerddap::info('erdHadISST')
##
parameter <- 'sst'
xcoord <- c(-130.5)
ycoord <- c(40.5)
tcoord <- c('2006-01-16')
# extract <- rxtracto(dataInfo, parameter = parameter, xcoord = xcoord,
#                   ycoord = ycoord, tcoord= tcoord
#                   )
##
## bathymetry example
## 2-D example getting bathymetry
dataInfo <- rerddap::info('etopo360')
parameter <- 'altitude'
# extract <- rxtracto(dataInfo, parameter, xcoord = xcoord, ycoord = ycoord)

Extract environmental data in a 3-dimensional box from an 'ERDDAP' server using 'rerddap'.

Description

rxtracto_3D uses the R program 'rerddap' to extract environmental data from an 'ERDDAP' server in an (x,y,z, time) bounding box. The same call could be made directly in rerddap, but function is maintained as it is used in the polygon routine.

Usage

rxtracto_3D(
  dataInfo,
  parameter = NULL,
  xcoord = NULL,
  ycoord = NULL,
  zcoord = NULL,
  tcoord = NULL,
  xName = "longitude",
  yName = "latitude",
  zName = "altitude",
  tName = "time",
  verbose = FALSE,
  cache_remove = TRUE
)

Arguments

dataInfo

- the return from an 'rerddap:info' call to an 'ERDDAP' server
parameter

- character string containing the name of the parameter to extract
xcoord

- a real array with the x-coordinates of the trajectory (if longitude in #' decimal degrees East, either 0-360 or -180 to 180)
ycoord

- a real array with the y-coordinate of the trajectory (if latitude in decimal degrees N; -90 to 90)
zcoord

- a real array with the z-coordinate (usually altitude or depth)
tcoord

- a character array with the times of the trajectory in "YYYY-MM-DD" - for now restricted to be time.
xName

- character string with name of the xcoord in the 'ERDDAP' dataset (default "longitude")
yName

- character string with name of the ycoord in the 'ERDDAP' dataset (default "latitude")
zName

- character string with name of the zcoord in the 'ERDDAP' dataset (default "altitude")
tName

- character string with name of the tcoord in the 'ERDDAP' dataset (default "time")
verbose

- logical variable (default FALSE) if the the URL request should be verbose
cache_remove

- logical variable (default TRUE) whether to delete 'rerddap' cache

Value

If successful a structure with data and dimensions:

  • extract$data - the data array dimensioned (lon,lat,time)

  • extract$varname - the name of the parameter extracted

  • extract$datasetname - ERDDAP dataset name

  • extract$longitude - the longitudes on some scale as request

  • extract$latitude - the latitudes always going south to north

  • extract$time - the times of the extracts

else an error string

Examples

## toy example to show use
## and keep execution time low
##
# dataInfo <- rerddap::info('erdHadISST')
parameter <- 'sst'
xcoord <- c(-130.5, -130.5)
ycoord <- c(40.5, 40.5)
tcoord <- c('2006-01-16', '2006-01-16')
# extract <- rxtracto_3D(dataInfo, parameter, xcoord = xcoord, ycoord = ycoord,
#                        tcoord = tcoord)

## bathymetry example
## 2-D example getting bathymetry
dataInfo <- rerddap::info('etopo360')
parameter <- 'altitude'
# extract <- rxtracto_3D(dataInfo, parameter, xcoord = xcoord, ycoord = ycoord)

Extract environmental data in a polygon using 'ERDDAP' and 'rerddap'.

Description

rxtractogon uses the R program 'rerddap' to extract environmental data from an 'ERDDAP' server in a polygon through time.

Usage

rxtractogon(
  dataInfo,
  parameter,
  xcoord = NULL,
  ycoord = NULL,
  zcoord = NULL,
  tcoord = NULL,
  xName = "longitude",
  yName = "latitude",
  zName = "altitude",
  tName = "time",
  verbose = FALSE,
  cache_remove = TRUE
)

Arguments

dataInfo

- the return from an 'rerddap:info' call to an 'ERDDAP' server
parameter

- character string containing the name of the parameter to extract
xcoord

- array giving longitudes (in decimal degrees East, either 0-360 or -180 to 180) of polygon
ycoord

- array giving latitudes (in decimal degrees N; -90 to 90)of polygon
zcoord

- a real number with the z-coordinate(usually altitude or depth)
tcoord

- 2-array of minimum and maximum times as 'YYYY-MM-DD'
xName

- character string with name of the xcoord in the 'ERDDAP' dataset (default "longitude")
yName

- character string with name of the ycoord in the 'ERDDAP' dataset (default "latitude")
zName

- character string with name of the zcoord in the 'ERDDAP' dataset (default "altitude")
tName

- character string with name of the tcoord in the 'ERDDAP' dataset (default "time")
verbose

- logical variable (default FALSE) if the the URL request should be verbose
cache_remove

- logical variable (default TRUE) whether to delete 'rerddap' cache

Value

If successful a structure with data and dimensions

  • extract$data - the masked data array dimensioned (lon,lat,time)

  • extract$varname - the name of the parameter extracted

  • extract$datasetname - ERDDAP dataset name

  • extract$longitude - the longitudes on some scale as request

  • extract$latitude - the latitudes always going south to north

  • extract$time - the times of the extracts

else an error string

Details

rxtractogon extracts the data from the smallest bounding box that contains the polygon, and then uses the function "point.in.polygon" from the "sp" package to mask out the areas outside of the polygon. rxtractogon only works with datasets defined on a latitude and longitude grid.

Examples

## toy example to show use
## and keep execution time low
# dataInfo <- rerddap::info('erdHadISST')
parameter <- 'sst'
tcoord <- c("2016-06-15")
xcoord <- mbnms$Longitude[1:3]
ycoord <- mbnms$Latitude[1:3]
# sanctSST <- rxtractogon (dataInfo, parameter=parameter, xcoord = xcoord,
#                          ycoord = ycoord,  tcoord= tcoord)
#
## MBMS bathymetry example
xcoord <- mbnms$Longitude
ycoord <- mbnms$Latitude
dataInfo <- rerddap::info('etopo180')
parameter = 'altitude'
xName <- 'longitude'
yName <- 'latitude'
# bathy <- rxtractogon (dataInfo, parameter = parameter, xcoord = xcoord, ycoord = ycoord)

swchl Data

Description

pre-Download of Pacific West Coast SST fro use in 'plotTrack()' example can run within CRAN Time limits

Usage

swchl

Format

An object of class list (inherits from rxtractoTrack) of length 13.

Details

obtained using the 'rxtracto()' command tagData <- Marlintag38606 xpos <- tagData$lon[1:20] ypos <- tagData$lat[1:20] tpos <- tagData$date[1:20] tpos <- tagData$date[1:20] zpos <- rep(0., length(xpos)) swchlInfo <- rerddap::info('erdSWchla8day') swchl <- rxtracto(swchlInfo, parameter = 'chlorophyll', xcoord = xpos, ycoord = ypos, tcoord = tpos, zcoord = zpos, xlen = .2, ylen = .2)

convert result of 'rxtracto_3D' or 'rxtractogon' to tidy long-format

Description

tidy_grid is a function to convert result of 'rxtracto_3D' or 'rxtractogon' to "tidy" long-format

Usage

tidy_grid(response)

Arguments

response

data frame returned from 'rxtracto_3D'()' or 'rxtractogon()'

Value

a dataframe in long-format

Examples

MBsst_tidy <-tidy_grid(MBsst)