Barneche DR, Coleman G, Fermor D, Klein E, Robinson T, Smith J, Sheehan JL, Dowley S, Ditton D, Gunn K, Ericson G, Logan M, Rehbein M (2021). dataaimsr: An R Client for the Australian Institute of Marine Science Data Platform API which provides easy access to AIMS Data Platform. Journal of Open Source Software, 6: 3282. doi: 10.21105/joss.03282.
Overview
The Australian Institute of Marine Science (AIMS) has a long tradition in measuring and monitoring a series of environmental parameters along the tropical coast of Australia. These parameters include long-term record of sea surface temperature, wind characteristics, atmospheric temperature, pressure, chlorophyll-a data, among many others. The AIMS Data Centre team has recently developed the AIMS Data Platform API which is a REST API providing JSON-formatted data to users. dataaimsr is an R package written to allow users to communicate with the AIMS Data Platform API using an API key and a few convenience functions to interrogate and understand the datasets that are available to download. In doing so, it allows the user to fully explore these datasets in R in whichever capacity they want (e.g. data visualisation, statistical analyses, etc). The package itself contains a plot method which allows the user to plot summaries of the different types of dataset made available by the API. Below we provide a brief context about the existing Datasets that can be explored through dataaimsr.
Installation
Requesting an AIMS Data Platform API Key
AIMS Data Platform requires an API Key for data requests, get a key here.
The API Key can be passed to the package functions as an additional api_key = "XXXX" argument. However, we strongly encourage users to maintain their API key as a private locally hidden environment variable (AIMS_DATAPLATFORM_API_KEY) in the .Renviron file for automatic loading at the start of an R session. Please read this article which details why keeping your API private is extremely important.
Users can modify their .Renviron file by adding the following line:
AIMS_DATAPLATFORM_API_KEY=XXXXXXXXXXXXXThe .Renviron file is usually stored in each users home directory:
| System | .Renviron file locations |
|---|---|
| MS Windows |
C:‹username›.Renviron or C:‹username›.Renviron
|
| Linux / MacOs |
/home/‹username›/.Renviron
|
Package
| Type | Source | Command |
|---|---|---|
| Release | CRAN | Not yet available |
| Development | GitHub |
remotes::install_github(“ropensci/dataaimsr”)
|
| Development | rOpenSci |
install.packages(“dataaimsr”, repos = “https://dev.ropensci.org”)
|
Usage
# assumes that user already has API key saved to
# .Renviron
library(dataaimsr)
# summarised by series
# for all sites that contain data
# within a defined date range
sdf_b <- aims_data("temp_loggers", api_key = NULL,
summary = "summary-by-series",
filters = list("from_date" = "2018-01-01",
"thru_date" = "2018-12-31"))
# downloads weather data from site Yongala
# within a defined date range
wdf_a <- aims_data("weather", api_key = NULL,
filters = list(site = "Yongala",
from_date = "2018-01-01",
thru_date = "2018-01-02"))More comprehensive examples about how to navigate dataaimsr and interrogate the datasets can be found on our online vignettes.
Datasets
Currently, there are two AIMS long-term monitoring datasets available to be downloaded through dataaimsr:
Northern Australia Automated Marine Weather And Oceanographic Stations
Automatic weather stations have been deployed by AIMS since 1980. Most of the stations are along the Great Barrier Reef (GBR) including the Torres Strait in North-Eastern Australia but there is also a station in Darwin and one at Ningaloo Reef in Western Australia. Many of the stations are located on the reef itself either on poles located in the reef lagoon or on tourist pontoons or other structures. A list of the weather stations which have been deployed by AIMS and the period of time for which data may be available can be found on the metadata webpage. NB: Records may not be continuous for the time spans given.
AIMS Sea Water Temperature Observing System (AIMS Temperature Logger Program)
The data provided here are from a number of sea water temperature monitoring programs conducted in tropical and subtropical coral reefs environments around Australia. Data are available from approximately 80 GBR sites, 16 Coral Sea sites, 7 sites in North West Western Australia (WA), 8 Queensland regional ports, 13 sites in the Solitary Islands, 4 sites in Papua New Guinea and 10 sites in the Cocos (Keeling) Islands. Data are obtained from in-situ data loggers deployed on the reef. Temperature instruments sample water temperatures every 5-10 minutes (typically) and are exchanged and downloaded approximately every 12 months. Temperature loggers on the reef-flat are generally placed just below Lowest Astronomical Tide level. Reef-slope (or where specified as Upper reef-slope) generally refers to depths 5–9 m while Deep reef-slope refers to depths of ~20 m. For more information on the dataset and its usage, please visit the metadata webpage.
License
dataaimsr is provided by the Australian Institute of Marine Science under the MIT License (MIT).
Code of Conduct
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
AIMS R package logos
Our R package logos use a watercolour map of Australia, obtained with the ggmap R package, which downloads original map tiles provided by Stamen Design, under CC BY 3.0, with data from OpenStreetMap, under CC BY SA.
