agronomic_norms_area: agronomic_norms_area
In aWhereAPI/aWhere-R-Library: API calls for aWhere API

Description Usage Arguments Details Value References Examples

agronomic_norms_area pulls long term norm weather data from aWhere's API based on a data.frame of lat/lon, polygon or extent

agronomic_norms_area(
  polygon,
  month_day_start,
  month_day_end,
  year_start,
  year_end,
  propertiesToInclude = "",
  exclude_years = NULL,
  accumulation_start_date = "",
  gdd_method = "standard",
  gdd_base_temp = 10,
  gdd_min_boundary = 10,
  gdd_max_boundary = 30,
  includeFeb29thData = TRUE,
  numcores = 2,
  returnSpatialData = FALSE,
  bypassNumCallCheck = FALSE,
  verbose = TRUE,
  maxTryCount = 3,
  keyToUse = awhereEnv75247$uid,
  secretToUse = awhereEnv75247$secret,
  tokenToUse = awhereEnv75247$token,
  apiAddressToUse = awhereEnv75247$apiAddress
)

`polygon`	either a data.frame with column names lat/lon, SpatialPolygons object, well-known text string, or extent from raster package. If the object contains multiple polygons, the union of them is used. Information from each individal polygon can be retrieved by returning spatial data and using the over function from the sp package
`month_day_start`	character string of the first month and day for which you want to retrieve data, in the form: MM-DD. This is the start of your date range. e.g. '07-01' (July 1) (required)
`month_day_end`	character string of the last month and day for which you want to retrieve data, in the form: MM-DD. This is the end of your date range. e.g. '07-01' (July 1) (required)
`year_start`	character string of the starting year (inclusive) of the range of years for which you're calculating norms, in the form YYYY. e.g., 2008 (required)
`year_end`	character string of the last year (inclusive) of the range of years for which you're calculating norms, in the form YYYY. e.g., 2015 (required)
`propertiesToInclude`	character vector of properties to retrieve from API. Valid values are accumulations, gdd, pet, ppet, accumulatedGdd, accumulatedPrecipitation, accumulatedPet, accumulatedPpet (optional)
`accumulation_start_date`	Allows the user to start counting accumulations from before the specified start date (or before the planting date if using the most recent planting). Use this parameter to specify the date from which you wish to start counting, in the form: YYYY-MM-DD. The daily values object will still only return the days between the start and end date. This date must come before the start date. (optional)
`gdd_method`	There are variety of equations available for calculating growing degree-days. Valid entries are: 'standard', 'modifiedstandard', 'min-temp-cap', 'min-temp-constant' See the API documentation for a description of each method. The standard method will be used if none is specified. (character - optional)
`gdd_base_temp`	The base temp to use for the any of the GDD equations. The default value of 10 will be used if none is specified. (optional)
`gdd_min_boundary`	The minimum boundary to use in the selected GDD equation. The behavior of this value is different depending on the equation you're using The default value of 10 will be used if none is specified. (optional)
`gdd_max_boundary`	The max boundary to use in the selected GDD equation. The behavior of this value is different depending on the equation you're using. The default value of 30 will be used if none is specified. (optional)
`includeFeb29thData`	Whether to keep data from Feb 29th on leap years. Because weather/agronomics summary statistics are calculated via the calendar date and 3 years are required to generate a value, data from this date is more likely to be NA. ALlows user to drop this data to avoid later problems (defaults to TRUE)
`numcores`	number of cores to use in parallel loop. To check number of available cores: parallel::detectCores(). If you receive an error regarding the speed you are making calls, reduce this number
`returnSpatialData`	returns the data as a SpatialPixels object. Can be convered to raster with the command raster::stack NOTE: if multiple days worth of data is returned, it is necessary to subset to specific day for working with as spatial data (sp package: optional)
`bypassNumCallCheck`	set to TRUE to avoid prompting the user to confirm that they want to begin making API calls
`verbose`	Set to TRUE tp print messages to console about state of parallization call. Typically only visible if run from console and not GUI
`maxTryCount`	maximum number of times a call is repeated if the the API returns an error. Random pause between each call
`keyToUse`	aWhere API key to use. For advanced use only. Most users will not need to use this parameter (optional)
`secretToUse`	aWhere API secret to use. For advanced use only. Most users will not need to use this parameter (optional)
`tokenToUse`	aWhere API token to use. For advanced use only. Most users will not need to use this parameter (optional)
`apiAddressToUse`	Address of aWhere API to use. For advanced use only. Most users will not need to use this parameter (optional)
`exclude_year`	Year or years which you'd like to exclude from your range of years on which to calculate norms. To exclude multiple years, provide a vector of years. You must include at least three years of data with which to calculate the norms. (numeric, optional)

This function allows you to calculate the averages for agronomic attributes across any range of years for which data are available. The data pulled includes norms for growing degree days (GDDs), potential evapotranspiration (PET), Precipitation over potential evapotranspiration (P/PET), accumulated GDDs, accumulated precipitation, accumulated PET, and accumulated P/PET, along with the standard deviations for these variables. The data pulled is for the polygon or extent. The polygon should be either a SpatialPolygons object or a well-known text character string or an extent. Default units are returned by the API.

The data returned in this function allow you to compare this year or previous years to the long-term normals, calculated as the average of those agronomic conditions on that day in that location over the years specified.

Note about dates: The system does not adjust for any difference in dates between the location of the user and where data is being requested from. It is the responsibility of the user to ensure a valid date range is specified given any differences in timezone. These differences can have implications for whether a given date should be requested from the daily_observed functions or the forecast functions. Furthermore, because this function can take as input locations that may be in different timezones, it is the responsibility of the user to either ensure that the date range specified is valid for all relevant locations or to break the query into pieces.

data.frame of requested data for dates requested

https://docs.awhere.com/knowledge-base-docs/historical-agronomic-norms-by-geolocation/

## Not run: agronomic_norms_area(polygon = raster::getData('GADM', country = "Gambia", level = 0, download = T)
                              ,month_day_start = '02-01'
                              ,month_day_end = '03-10'
                              ,year_start = 2008
                              ,year_end = 2015
                              ,exclude_years =  c(2010,2011)
                              ,accumulation_start_date = ''
                              ,gdd_method = 'standard'
                              ,gdd_base_temp = 10
                              ,gdd_min_boundary = 10
                              ,gdd_max_boundary = 30
                              ,numcores = 2)
## End(Not run)