npn_get_data_by_year: Get Data By Year

In rnpn: Interface to the National 'Phenology' Network 'API'

Get Data By Year

Description

Utility function to chain multiple requests to npn_get_data for requests where data should only be retrieved on an annual basis, or otherwise automatically be delineated in some way. Results in a data table that's a combined set of the results from each request to the data service.

Usage

npn_get_data_by_year(
  endpoint,
  query,
  years,
  period_start = "01-01",
  period_end = "12-31",
  download_path = NULL,
  six_leaf_layer = FALSE,
  six_bloom_layer = FALSE,
  agdd_layer = NULL,
  six_sub_model = NULL,
  additional_layers = NULL
)

Arguments

endpoint	String, the endpoint to query.
query	Base query string to use. This includes all the user selected parameters but doesn't include start/end date which will be automatically generated and added.
years	Integer vector; the years for which to retrieve data. There will be one request to the service for each year. If the period (determined by period_start and period_end) crosses a year boundary, years determines the start years.
period_start, period_end	Character vectors of the form "MM-DD". Used to determine the period over which phenophase status records are summarized. For example, to use a "water year" set period_start = "10-01" and period_end = "09-30". If not provided, they will default to "01-01" and "12-31", respectively, to use the calendar year.
download_path	Character, optional file path to the file for which to output the results.
six_leaf_layer	Boolean value when set to TRUE will attempt to resolve the date of the observation to a spring index, leafing value for the location at which the observations was taken.
six_bloom_layer	Boolean value when set to TRUE will attempt to resolve the date of the observation to a spring index, bloom value for the location at which the observations was taken.
agdd_layer	Numeric value, accepts 32 or 50. When set, the results will attempt to resolve the date of the observation to an AGDD value for the location; the 32 or 50 represents the base value of the AGDD value returned. All AGDD values are based on a January 1st start date of the year in which the observation was taken.
six_sub_model	Affects the results of the six layers returned. Can be used to specify one of three submodels used to calculate the spring index values. Thus setting this field will change the results of six_leaf_layer and six_bloom_layer. Valid values include: 'lilac', 'zabelli' and 'arnoldred'. For more information see the NPN's Spring Index Maps documentation: https://www.usanpn.org/data/maps/spring.
additional_layers	Data frame with first column named name and containing the names of the layer for which to retrieve data and the second column named param and containing string representations of the time/elevation subset parameter to use. This variable can be used to append additional geospatial layer data fields to the results, such that the date of observation in each row will resolve to a value from the specified layers, given the location of the observation.

Value

A tibble combining each requests results from the service. If download_path is specified, the file path is returned instead.

Examples

## Not run: 
endpoint <- "/observations/getObservations.json"
query <- list(
  request_src = "Unit%20Test",
  climate_data = "0",
  `species_id[1]` = "6"
)

npn_get_data_by_year(endpoint = endpoint,
                     query = query,
                     years = c(2013, 2014))

#Set a custom period from October through September
# This will return data for 2013-10-01 through 2014-09-30 and from 2014-10-01
# through 2015-09-30
npn_get_data_by_year(
  endpoint = endpoint,
  query = query,
  years = c(2013, 2014),
  period_start = "10-01",
  period_end = "09-30"
)

## End(Not run)

rnpn documentation built on April 3, 2025, 5:54 p.m.