|
1 | | -# rerddapXtracto (Version 1.1.3) |
2 | | -rerddapXtracto - R package for accessing environmental data using 'rerddap' |
| 1 | +rerddap |
| 2 | +===== |
3 | 3 |
|
4 | | -****** |
5 | | -`rxtracto()`option to use the ERDDAP "Interpolate service", which can greatly |
6 | | -speed up extracts for large tracks. |
7 | | -****** |
8 | 4 |
|
9 | 5 |
|
| 6 | +[](https://cranchecks.info/pkgs/rerddap) |
| 7 | +[](https://github.com/ropensci/rerddap/actions) |
| 8 | +[](https://codecov.io/github/ropensci/rerddap?branch=master) |
| 9 | +[](https://github.com/r-hub/cranlogs.app) |
| 10 | +[](https://cran.r-project.org/package=rerddap) |
10 | 11 |
|
11 | | -****** |
12 | | -`rxtracto()` major rewrite of this function to reduce the number of requests made to the ERDDAP server, and to improve overall speed. |
13 | | -****** |
| 12 | +`rerddap` is a general purpose R client for working with ERDDAP servers. |
14 | 13 |
|
| 14 | +Package Docs: <https://docs.ropensci.org/rerddap/> |
15 | 15 |
|
16 | | -`rerddapXtracto` is an <span style="color:blue">R</span> package developed to subset and extract satellite and other oceanographic related data from a remote <span style="color:blue">ERDDAP</span> server. The program can extract data for a moving point in time along a user-supplied set of longitude, latitude, time and depth points; in a 3D bounding box; or within a polygon (through time). |
| 16 | +## Installation |
17 | 17 |
|
18 | | -There are also two plotting functions, `plotTrack()` and `plotBox()` that make use of the `plotdap` package. See the new [rerdapXtracto vignette](https://rmendels.github.io/UsingrerddapXtracto.html). |
| 18 | +From CRAN |
19 | 19 |
|
20 | 20 |
|
| 21 | +```r |
| 22 | +install.packages("rerddap") |
| 23 | +``` |
21 | 24 |
|
22 | | -There are three main data extraction functions in the `rerddapXtracto` package: |
23 | | - |
24 | | -- `rxtracto <- function(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)` |
25 | | - |
26 | | -- `rxtracto_3D <- function(dataInfo, parameter = NULL, xcoord = NULL, ycoord = NULL, zcoord = NULL, tcoord = NULL, xName = 'longitude', yName = 'latitude', zName = 'altitude', tName = 'time', verbose = FALSE)` |
27 | | - |
28 | | -- `rxtractogon <- function(dataInfo, parameter, xcoord = NULL, ycoord = NULL, zcoord = NULL, tcoord = NULL, xName = 'longitude', yName = 'latitude', zName = 'altitude', tName = 'time', verbose = FALSE)` |
29 | | - |
30 | | -and two functions for producing maps: |
31 | | - |
32 | | -- `plotTrack <- function(resp, xcoord, ycoord, tcoord, plotColor = 'viridis', myFunc = NA, |
33 | | - mapData = NULL, crs = NULL, |
34 | | - animate = FALSE, cumulative = FALSE, |
35 | | - name = NA, shape = 20, size = .5)` |
36 | | - |
37 | | -- `plotBBox <- function(resp, plotColor = 'viridis', time = NA, myFunc = NA, |
38 | | - mapData = NULL, crs = NULL, |
39 | | - animate = FALSE, cumulative = FALSE, name = NA, |
40 | | - maxpixels = 10000)` |
41 | | - |
42 | | - |
43 | | -For data requests that cross the dateline for datasets that are |
44 | | -on a (-180, 180) longitude grid, there are some important caveats: |
45 | | - |
46 | | -- Request must be on a (0, 360) longitude grid |
47 | | -- Several of the checks that the request makes sense are disabled if the request |
48 | | -cross the dateline and the dataset is on a (-180, 180) longitude grid. |
49 | | -- User therefore has more responsibility to check that the request makes sense |
50 | | -for the dataset being accessed. |
51 | | - |
52 | | - |
| 25 | +Or development version from GitHub |
53 | 26 |
|
54 | 27 |
|
| 28 | +```r |
| 29 | +remotes::install_github("ropensci/rerddap") |
| 30 | +``` |
55 | 31 |
|
56 | | -`rerddapXtracto` uses the `rerddap`, `ncdf4` , `parsedate`, `plotdap` and `sp` packages , and these packages (and the packages imported by these packages) must be installed first or `rerddapXtracto` will fail to install. |
57 | 32 |
|
58 | | -```{r install,eval=FALSE} |
59 | | -install.packages("ncdf4") |
60 | | -install.packages("parsedate") |
61 | | -install.packages("plotdap") |
62 | | -install.packages("rerddap") |
63 | | -install.packages("sp") |
| 33 | +```r |
| 34 | +library("rerddap") |
64 | 35 | ``` |
65 | 36 |
|
| 37 | +Some users may experience an installation error, stating to install 1 or more |
| 38 | +packages, e.g., you may need `DBI`, in which case do, for example, |
| 39 | +`install.packages("DBI")` before installing `rerddap`. |
66 | 40 |
|
| 41 | +## Background |
67 | 42 |
|
68 | | -``` |
| 43 | +ERDDAP is a server built on top of OPenDAP, which serves some NOAA data. You can get gridded data (griddap (<https://upwell.pfeg.noaa.gov/erddap/griddap/documentation.html>)), which lets you query from gridded datasets, or table data (tabledap (<https://upwell.pfeg.noaa.gov/erddap/tabledap/documentation.html>)) which lets you query from tabular datasets. In terms of how we interface with them, there are similarities, but some differences too. We try to make a similar interface to both data types in `rerddap`. |
| 44 | + |
| 45 | +## NetCDF |
69 | 46 |
|
| 47 | +`rerddap` supports NetCDF format, and is the default when using the `griddap()` function. NetCDF is a binary file format, and will have a much smaller footprint on your disk than csv. The binary file format means it's harder to inspect, but the `ncdf4` package makes it easy to pull data out and write data back into a NetCDF file. Note the the file extension for NetCDF files is `.nc`. Whether you choose NetCDF or csv for small files won't make much of a difference, but will with large files. |
70 | 48 |
|
| 49 | +## Caching |
71 | 50 |
|
| 51 | +Data files downloaded are cached in a single directory on your machine determined by the `hoardr` package. When you use `griddap()` or `tabledap()` functions, we construct a MD5 hash from the base URL, and any query parameters - this way each query is separately cached. Once we have the hash, we look in the cache directory for a matching hash. If there's a match we use that file on disk - if no match, we make a http request for the data to the ERDDAP server you specify. |
72 | 52 |
|
73 | | -# Required legalese |
| 53 | +## ERDDAP servers |
74 | 54 |
|
75 | | -“The United States Department of Commerce (DOC) GitHub project code is provided |
76 | | -on an ‘as is’ basis and the user assumes responsibility for its use. |
77 | | -DOC has relinquished control of the information and no longer has responsibility |
78 | | -to protect the integrity, confidentiality, or availability of the information. |
79 | | -Any claims against the Department of Commerce stemming from the use of its |
80 | | -GitHub project will be governed by all applicable Federal law. Any reference to |
81 | | -specific commercial products, processes, or services by service mark, trademark, |
82 | | -manufacturer, or otherwise, does not constitute or imply their endorsement, |
83 | | -recommendation or favoring by the Department of Commerce. The Department of |
84 | | -Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used |
85 | | -in any manner to imply endorsement of any commercial product or activity by DOC |
86 | | -or the United States Government.” |
| 55 | +You can get a data.frame of ERDDAP servers using the function `servers()`. Most I think serve some kind of NOAA data, but there are a few that aren't NOAA data. If you know of more ERDDAP servers, send a pull request, or let us know. |
87 | 56 |
|
| 57 | +## Meta |
88 | 58 |
|
| 59 | +* Please [report any issues or bugs](https://github.com/ropensci/rerddap/issues). |
| 60 | +* License: MIT |
| 61 | +* Get citation information for `rerddap` in R doing `citation(package = 'rerddap')` |
| 62 | +* Please note that this package is released with a [Contributor Code of Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project, you agree to abide by its terms. |
0 commit comments