rnpn (version 1.4.1)

npn_get_data_by_year: 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
)

Value

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

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.

Examples

if (FALSE) {
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"
)
}