dataaimsr

dataaimsr: An R Client for the Australian Institute of Marine Science Data Platform API which provides easy access to AIMS Data Platform - Published in JOSS (2021)

https://github.com/ropensci/dataaimsr

Keywords

Keywords from Contributors

Repository

Australian Institute of Marine Science (AIMS) Data Platform API Client which provides easy access to AIMS Data Platform scientific data and information.

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
stopifnot(require(knitr))
options(width = 90)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/",
  out.width = "100%"
)
```

```{r, echo = FALSE}
version <- as.vector(read.dcf("DESCRIPTION")[, "Version"])
version <- gsub("-", ".", version)
```

# dataaimsr 


[![](https://badges.ropensci.org/428_status.svg)](https://github.com/ropensci/software-review/issues/428)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.03282/status.svg)](https://doi.org/10.21105/joss.03282)
[![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html)
[![R build status](https://github.com/ropensci/dataaimsr/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/dataaimsr/actions)
[![Codecov test coverage](https://codecov.io/gh/ropensci/dataaimsr/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/dataaimsr?branch=master)
![pkgdown](https://github.com/ropensci/dataaimsr/workflows/pkgdown/badge.svg)
[![license](https://img.shields.io/badge/license-MIT + file LICENSE-lightgrey.svg)](https://choosealicense.com/)
[![packageversion](https://img.shields.io/badge/Package%20version-`r version`-orange.svg)](commits/master)
[![Ask Us Anything
\!](https://img.shields.io/badge/Ask%20us-anything-1abc9c.svg)](https://github.com/ropensci/dataaimsr/issues/new)
![Open Source
Love](https://badges.frapsoft.com/os/v2/open-source.svg?v=103)


**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](https://doi.org/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][1] 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](#datasets) that can be explored through `dataaimsr`.

[1]: https://open-aims.github.io/data-platform/

## Installation

### Requesting an AIMS Data Platform API Key

**AIMS Data Platform** requires an API Key for data requests, [get a key here](https://open-AIMS.github.io/data-platform/key-request).

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](https://CRAN.R-project.org/package=httr/vignettes/secrets.html)
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=XXXXXXXXXXXXX
```

The `.Renviron` file is usually stored in each users home directory:

System        | .Renviron file locations
--------------|-------------------------
MS Windows    | C:\Users\‹username›\.Renviron  or C:\Users\‹username›\Documents\.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

```{r, eval = FALSE}
# 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][4].

[4]: https://ropensci.github.io/dataaimsr/articles/

## 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][2] webpage. **NB:** Records may not be continuous for
the time spans given.

[2]: https://apps.aims.gov.au/metadata/view/0887cb5b-b443-4e08-a169-038208109466

### 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][3] webpage.

[3]: https://apps.aims.gov.au/metadata/view/4a12a8c0-c573-11dc-b99b-00008a07204e 

## License

`dataaimsr` is provided by the [Australian Institute of Marine Science](https://www.aims.gov.au) under the MIT License ([MIT](https://opensource.org/license/mit/)).

## Code of Conduct

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.

## AIMS R package logos

Our R package logos use a watercolour map of Australia, obtained with the [ggmap](https://CRAN.R-project.org/package=ggmap) R package, which downloads original map tiles provided by [Stamen Design](https://stamen.com/), under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0), with data from [OpenStreetMap](https://www.openstreetmap.org/), under [CC BY SA](https://creativecommons.org/licenses/by-sa/3.0).

Owner

JOSS Publication

dataaimsr: An R Client for the Australian Institute of Marine Science Data Platform API which provides easy access to AIMS Data Platform

Published

June 04, 2021

DOI

10.21105/joss.03282

Volume 6, Issue 62, Page 3282

Authors

Diego R. Barneche
Australian Institute of Marine Science, Crawley, WA 6009, Australia, The Indian Ocean Marine Research Centre, The University of Western Australia, Crawley, WA 6009, Australia

Greg Coleman
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Duncan Fermor
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Eduardo Klein
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Tobias Robinson
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Jason Smith
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Jeffrey L. Sheehan
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Shannon Dowley
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Dean Ditton
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Kevin Gunn
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Gavin Ericson
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Murray Logan
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Mark Rehbein
Australian Institute of Marine Science, Townsville, Qld 4810, Australia

Editor

Kristen Thyng

Tags

sea surface temperature weather stations long-term environmental monitoring Australia API

View PDF Review Thread Software Archive

CodeMeta (codemeta.json)

{
  "@context": [
    "https://doi.org/10.5063/schema/codemeta-2.0",
    "http://schema.org"
  ],
  "@type": "SoftwareSourceCode",
  "identifier": "dataaimsr",
  "description": "AIMS Data Platform API Client which provides easy access to AIMS Data Platform scientific data and information.",
  "name": "dataaimsr: AIMS Data Platform API Client",
  "codeRepository": "https://github.com/ropensci/dataaimsr",
  "relatedLink": "https://ropensci.github.io/dataaimsr",
  "issueTracker": "https://github.com/ropensci/dataaimsr/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.0.3",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.0.2 (2020-06-22)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Diego R.",
      "familyName": "Barneche",
      "email": "d.barneche@aims.gov.au"
    },
    {
      "@type": "Organization",
      "name": "AIMS Datacentre",
      "email": "adc@aims.gov.au"
    }
  ],
  "contributor": {},
  "copyrightHolder": {},
  "funder": {},
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Diego R.",
      "familyName": "Barneche",
      "email": "d.barneche@aims.gov.au"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "httptest",
      "name": "httptest",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httptest"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rgeos",
      "name": "rgeos",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rgeos"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "purrr",
      "name": "purrr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=purrr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": [
    {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.3.0"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "httr",
      "name": "httr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "jsonlite",
      "name": "jsonlite",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=jsonlite"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "parsedate",
      "name": "parsedate",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=parsedate"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "tidyr",
      "name": "tidyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tidyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rnaturalearth",
      "name": "rnaturalearth",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rnaturalearth"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sf"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggrepel",
      "name": "ggrepel",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggrepel"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "curl",
      "name": "curl",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=curl"
    }
  ],
  "releaseNotes": "https://github.com/ropensci/dataaimsr/blob/master/NEWS.md",
  "fileSize": "37783.917KB",
  "contIntegration": "https://codecov.io/gh/ropensci/dataaimsr?branch=master",
  "developmentStatus": "https://www.tidyverse.org/lifecycle/#maturing",
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/428",
    "provider": "https://ropensci.org"
  }
}

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages