rnpn

R client for the National Phenology Network database API

https://github.com/usa-npn/rnpn

Science Score: 54.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
✓
Committers with academic emails
2 of 12 committers (16.7%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (20.3%) to scientific vocabulary

Keywords

data national-phenology-network phenology r r-package rstats species web-api

Keywords from Contributors

genome http-mock antweb bison ebird ecoengine gbif idigbio inaturalist noaa-data

Last synced: 4 months ago · JSON representation ·

Repository

R client for the National Phenology Network database API

Basic Info

Host: GitHub
Owner: usa-npn
License: other
Language: R
Default Branch: master
Homepage: http://usa-npn.github.io/rnpn/
Size: 22 MB

Statistics

Stars: 22
Watchers: 6
Forks: 11
Open Issues: 31
Releases: 3

Topics

data national-phenology-network phenology r r-package rstats species web-api

Created over 14 years ago · Last pushed 4 months ago

Metadata Files

Readme Changelog Contributing License Citation Codemeta

README.Rmd

---
output:
  github_document
---

# rnpn

```{r echo=FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.path='inst/img/'
)
```


[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)
[![CRAN status](https://www.r-pkg.org/badges/version/rnpn)](https://CRAN.R-project.org/package=rnpn)
[![R-CMD-check](https://github.com/usa-npn/rnpn/actions/workflows/R-CMD-check.yaml/badge.svg?branch=master)](https://github.com/usa-npn/rnpn/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/usa-npn/rnpn/graph/badge.svg)](https://app.codecov.io/gh/usa-npn/rnpn)


`rnpn` is an R client for interacting with the USA National Phenology Network data web services.
These services include access to a rich set of observer-contributed, point-based phenology records as well as geospatial data products including gridded phenological model and climatological data.

Documentation is available for the National Phenology Network [API documentation](https://docs.google.com/document/d/1yNjupricKOAXn6tY1sI7-EwkcfwdGUZ7lxYv7fcPjO8/edit?hl=en_US), which describes the full set of REST services this package wraps.

There is no need for an API key to grab data from the National Phenology Network but users are required to self identify, on an honor system, against requests that may draw upon larger datasets.
For functions that require it, simply populate the request_source parameter with your name or the name of your institution.

## Installation

CRAN version

```{r eval=FALSE}
install.packages("rnpn")
```

Development version:

```{r eval=FALSE}
install.packages("devtools")
library('devtools')
devtools::install_github("usa-npn/rnpn")
```

```{r}
library('rnpn')
```

This package has dependencies on both curl and gdal.
Some Linux based systems may require additional system dependencies for those required packages, and accordingly this package, to install correctly.
For example, on Ubuntu:

```{r eval=FALSE}
sudo apt install libcurl4-openssl-dev
sudo apt install libproj-dev libgdal-dev
```

## The Basics

Many of the functions to search for data require knowing the internal unique identifiers of some of the database entities to filter the data down efficiently.
For example, if you want to search by species, then you must know the internal identifier of the species.
To get a list of all available species use the following:

```{r eval=FALSE}
species_list <- npn_species()
```

Similarly, for phenophases:

```{r eval=FALSE}
phenophases <- npn_phenophases()
```

### Getting Observational Data

There are four main functions for accessing observational data, at various levels of aggregation.
At the most basic level you can download the raw status and intensity data.

```{r eval=FALSE}
some_data <- npn_download_status_data(
  request_source = 'Your Name or Org Here',
  years = c(2015),
  species_id = c(35),
  states = c('AZ', 'IL')
)
```

Note that through this API, data can only be filtered chronologically by full calendar years.
You can specify any number of years in each API call.
Also note that request_source is a required parameter and should be populated with your name or the name of the organization you represent.
All other parameters are optional but it is highly recommended that you filter your data search further.

### Getting Geospatial Data

This package wraps around standard WCS endpoints to facilitate the transfer of raster data.
Generally, this package does not focus on interacting with WMS services, although they are available.
To get a list of all available data layers, use the following:

```{r eval=FALSE}
layers <- npn_get_layer_details()
```

You can then use the name of the layers to select and download geospatial data as a raster.

```{r eval=FALSE}
npn_download_geospatial(
  coverage_id = 'si-x:lilac_leaf_ncep_historic',
  date = '2016-12-31',
  format = 'geotiff',
  output_path = './six-test-raster.tiff'
)
```

## Example of combined observational and geospatial data
For more details see Vignette VII

```{r, echo=FALSE, out.width = "70%", fig.pos="h"}
knitr::include_graphics("vignettes/figures/7-plot.png")
```

## What's Next

Please read and review the vignettes for this package to get further information about the full scope of functionality available.

## Acknowledgments

This code was developed, in part, as part of the integrated [Pheno-Synthesis Software Suite (PS3)](https://git.earthdata.nasa.gov/projects/APIS/repos/pheno-synthesis-software-suite/browse).
The authors acknowledge funding for this work through NASA's AIST program (80NSSC17K0582, 80NSSC17K0435, 80NSSC17K0538, and 80GSFC18T0003).
The University of Arizona and the USA National Phenology Network's efforts with this package are supported in part by US Geological Survey (G14AC00405, G18AC00135) and the US Fish and Wildlife Service (F16AC01075 and F19AC00168).

## Meta

* Please [report any issues or bugs](https://github.com/usa-npn/rnpn/issues).
* License: MIT
* Get citation information for `rnpn` in R doing `citation(package = 'rnpn')`
* 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.

Owner

Name: USA National Phenology Network
Login: usa-npn
Kind: organization
Location: 1311 E. 4th Street, Tucson, AZ 85721

Website: https://www.usanpn.org
Repositories: 26
Profile: https://github.com/usa-npn

USA National Phenology Network

Citation (CITATION.cff)

# --------------------------------------------
# CITATION file created with {cffr} R package
# See also: https://docs.ropensci.org/cffr/
# --------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "rnpn" in publications use:'
type: software
license: MIT
title: 'rnpn: Interface to the National ''Phenology'' Network ''API'''
version: 1.4.0
doi: 10.32614/CRAN.package.rnpn
abstract: Programmatic interface to the Web Service methods provided by the National
  'Phenology' Network (<https://usanpn.org/>), which includes data on various life
  history events that occur at specific times.
authors:
- family-names: Switzer
  given-names: Jeff
  email: jeff@usanpn.org
- family-names: Chamberlain
  given-names: Scott
- family-names: Marsh
  given-names: Lee
- family-names: Wong
  given-names: Kevin
- family-names: Scott
  given-names: Eric R
  orcid: https://orcid.org/0000-0002-7430-7879
repository: https://CRAN.R-project.org/package=rnpn
repository-code: https://github.com/usa-npn/rnpn
url: http://usa-npn.github.io/rnpn/
date-released: '2025-03-25'
contact:
- family-names: Switzer
  given-names: Jeff
  email: jeff@usanpn.org
keywords:
- data
- national-phenology-network
- phenology
- r
- r-package
- rstats
- species
- web-api

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "rnpn",
  "description": "Programmatic interface to the Web Service methods provided by the National 'Phenology' Network (<https://usanpn.org/>), which includes data on various life history events that occur at specific times.",
  "name": "rnpn: Interface to the National 'Phenology' Network 'API'",
  "relatedLink": "http://usa-npn.github.io/rnpn/",
  "codeRepository": "https://github.com/usa-npn/rnpn",
  "issueTracker": "https://github.com/usa-npn/rnpn/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.4.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.3.1 (2023-06-16)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Jeff",
      "familyName": "Switzer",
      "email": "jeff@usanpn.org"
    },
    {
      "@type": "Person",
      "givenName": "Scott",
      "familyName": "Chamberlain"
    },
    {
      "@type": "Person",
      "givenName": "Lee",
      "familyName": "Marsh"
    },
    {
      "@type": "Person",
      "givenName": "Kevin",
      "familyName": "Wong"
    },
    {
      "@type": "Person",
      "givenName": "Eric R",
      "familyName": "Scott",
      "@id": "https://orcid.org/0000-0002-7430-7879"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "givenName": "David",
      "familyName": "LeBauer"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Jeff",
      "familyName": "Switzer",
      "email": "jeff@usanpn.org"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "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=covr"
    },
    {
      "@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": "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": "markdown",
      "name": "markdown",
      "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=markdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "RColorBrewer",
      "name": "RColorBrewer",
      "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=RColorBrewer"
    },
    {
      "@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": "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": "terra",
      "name": "terra",
      "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=terra"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "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"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "vcr",
      "name": "vcr",
      "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=vcr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "withr",
      "name": "withr",
      "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=withr"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.5.0"
    },
    "2": {
      "@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"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "httr2",
      "name": "httr2",
      "version": ">= 1.1.0",
      "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=httr2"
    },
    "4": {
      "@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"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "lifecycle",
      "name": "lifecycle",
      "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=lifecycle"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "magrittr",
      "name": "magrittr",
      "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=magrittr"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "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=rlang"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "tibble",
      "name": "tibble",
      "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=tibble"
    },
    "9": {
      "@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"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "xml2",
      "name": "xml2",
      "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=xml2"
    },
    "SystemRequirements": null
  },
  "fileSize": "14545.583KB",
  "citation": [
    {
      "@type": "CreativeWork",
      "datePublished": "2025",
      "author": [
        {
          "@type": "Person",
          "givenName": "Jeff",
          "familyName": "Switzer",
          "email": "jeff@usanpn.org"
        },
        {
          "@type": "Person",
          "givenName": "Scott",
          "familyName": "Chamberlain"
        },
        {
          "@type": "Person",
          "givenName": "Lee",
          "familyName": "Marsh"
        },
        {
          "@type": "Person",
          "givenName": "Kevin",
          "familyName": "Wong"
        },
        {
          "@type": "Person",
          "givenName": "Eric R",
          "familyName": "Scott",
          "@id": "https://orcid.org/0000-0002-7430-7879"
        }
      ],
      "name": "rnpn: Interface to the National 'Phenology' Network 'API'",
      "identifier": "10.32614/CRAN.package.rnpn",
      "url": "http://usa-npn.github.io/rnpn/",
      "@id": "https://doi.org/10.32614/CRAN.package.rnpn",
      "sameAs": "https://doi.org/10.32614/CRAN.package.rnpn"
    }
  ]
}

GitHub Events

Total

Create event: 36
Release event: 3
Issues event: 86
Watch event: 3
Delete event: 19
Issue comment event: 94
Member event: 2
Push event: 175
Pull request review event: 25
Pull request review comment event: 23
Pull request event: 58
Fork event: 2

Last Year

Create event: 36
Release event: 3
Issues event: 86
Watch event: 3
Delete event: 19
Issue comment event: 94
Member event: 2
Push event: 175
Pull request review event: 25
Pull request review comment event: 23
Pull request event: 58
Fork event: 2

Committers

Last synced: 5 months ago

All Time

Total Commits: 489
Total Committers: 12
Avg Commits per committer: 40.75
Development Distribution Score (DDS): 0.485

Past Year

Commits: 255
Committers: 4
Avg Commits per committer: 63.75
Development Distribution Score (DDS): 0.071

Top Committers

Name	Email	Commits
Eric Scott	s**r@g**m	252
Scott Chamberlain	m**s@g**m	106
npnlee85	l**e@u**g	45
npnlee85@gmail.com	n**5@g**m	32
alyssarosemartin	a**n@g**m	19
Jeff Switzer	j**r@g**m	18
David LeBauer	d**r@a**u	6
Maëlle Salmon	m**n@y**e	3
Erin Zylstra	e**a@g**m	3
Kevin Wong	k**n@u**g	3
steven2249	s**w@b**u	1
Jeroen Ooms	j**s@g**m	1

Committer Domains (Top 20 + Academic)

usanpn.org: 2 berkeley.edu: 1 arizona.edu: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 84
Total pull requests: 65
Average time to close issues: 9 months
Average time to close pull requests: about 1 month
Total issue authors: 13
Total pull request authors: 6
Average comments per issue: 1.37
Average comments per pull request: 0.8
Merged pull requests: 49
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 60
Pull requests: 54
Average time to close issues: about 1 month
Average time to close pull requests: 18 days
Issue authors: 3
Pull request authors: 2
Average comments per issue: 0.7
Average comments per pull request: 0.69
Merged pull requests: 39
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

Aariq (54)
sckott (13)
jeffswitzer (4)
ezylstra (3)
tdlan80 (2)
maelle (1)
Peter9192 (1)
rsbivand (1)
lzachmann (1)
cboettig (1)
vijaybarve (1)
ahhurlbert (1)
djhocking (1)

Pull Request Authors

Aariq (62)
npnlee85 (4)
dlebauer (2)
ezylstra (2)
maelle (1)
stevenysw (1)

Top Labels

Issue Labels

bug (13) priority: low (4) feature (4) API (3) refactor (2) priority: high (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 726 last-month
Total docker downloads: 88,633

Total dependent packages: 0
Total dependent repositories: 2
Total versions: 15
Total maintainers: 1

cran.r-project.org: rnpn

Interface to the National 'Phenology' Network 'API'

Homepage: https://github.com/usa-npn/rnpn
Documentation: http://cran.r-project.org/web/packages/rnpn/rnpn.pdf
License: MIT + file LICENSE
Latest release: 1.4.1
published 4 months ago

Versions: 15
Dependent Packages: 0
Dependent Repositories: 2
Downloads: 726 Last month
Docker Downloads: 88,633

Rankings

Docker downloads count: 0.0%

Forks count: 6.9%

Stargazers count: 13.4%

Average: 14.5%

Downloads: 19.5%

Dependent repos count: 19.5%

Dependent packages count: 27.9%

Maintainers (1)

jeff@usanpn.org

Last synced: 4 months ago

Dependencies

DESCRIPTION cran

R >= 3.5.0 depends
XML * imports
curl * imports
data.table >= 1.9.6 imports
httr >= 1.1.0 imports
jsonlite >= 0.9.19 imports
magrittr * imports
plyr * imports
raster * imports
rgdal * imports
sp >= 1.1 imports
tibble * imports
RColorBrewer * suggests
covr * suggests
ggplot2 * suggests
knitr * suggests
markdown * suggests
rmarkdown * suggests
testthat * suggests
vcr * suggests

.github/workflows/R-CMD-check.yaml actions

actions/cache v2 composite
actions/checkout v2 composite
actions/upload-artifact main composite
r-lib/actions/setup-pandoc v1 composite
r-lib/actions/setup-r v1 composite