title: "aWhere R Library"

author: "aWhere Team"

date: "December 2016"

output: rmarkdown::html_vignette

vignette: >

```{r setup, include=FALSE}

For customers that use R in their statistical modeling work, the `aWhereAPI` R package helps get you up and running with minimal integration effort. This vignette demonstrates the basic use of the `aWhereAPI` functions, which simplify the authentication and query construction processes. This package is also particularly helpful for users with limited knowledge of APIs and HTTP syntax.

For additional information or detail, please refer to the [complete documentation](https://github.com/aWhereAPI).

**Note:** `aWhereAPI` functions will only return metric units

**Note:** You will need to install R and have a working knowledge of its interface prior to installing and using this package.

**Note:** You will need to have the devtools library installed in R to install the package. Consult `devtools` [documentation](https://github.com/hadley/devtools) if necessary.

This package can be installed directly from GitHub with the following command:

devtools::install_github("aWhereAPI/aWhere-R-Library")

1. Download this [Github repo](https://github.com/aWhereAPI/aWhere-R-Library) and keep the `aWhere-R-Library-master` folder somewhere useful on your computer, such as your Desktop or My Documents.

2. Set the Working Path in R to the location that contains the `aWhere-R-Library-master` folder. If you placed it on your Desktop the working directory would be something like `C:\Users\USERNAME\Desktop`. In R, this command is:

* `setwd("C:\Users\USERNAME\Desktop")`

3. Run `library(devtools)` and `install("aWhere-R-Library-master")` to install and add the library to your environment.

To get aWhere API keys go to [aWhere Developer Community](http://developer.awhere.com/start) or contact your aWhere Account Executive.

One-time generation of a token can be done with the `get_token()` function. The resulting token will be automatically stored in your environment for use in API calls (tokens are active for one hour).

get_token("JFKL24JF290FJSKAFDF","jf0afsd9af0a")

Alternatively, the `load_credentials()` function accesses a text file saved on your computer with your API Key on the first line, and your Secret on the second. This function invokes `get_token()` so no further work is needed to generate additional access tokens while making calls.

```

This API provides an interface for customers to register their field locations and information about their plantings in the aWhere Platform. The ID for each field or planting can then be used for quick reference in other functions in the weather data APIs.

```

Running this function without any inputs will return a complete list of fields associated with your credentials. If a user wants information relating to a specific field only, they can pass the field ID to the function.

At this time only the name or farm ID of a field can be changed after you have created the field. Field IDs and coordinates cannot be changed. This example will change the farm ID of field_test to "TestFarmA" only if the farm ID is currently "farmA":

The function as constructed allows you to use the value of the first named variable (whether farm ID or field name) as the condition for replacing the second named variable.

Each field associated with your aWhere API account can be associated with multiple different planting records, specific to a crop and/or growing season. A planting record is only required when using the aWhere API to run models.

Requires both a previously-created field ID and specific information relating to the planting that occurred on that field. This example shows the simplest possible way to create a planting, though a number of other optional parameters are allowed. When complete, the auto-generated planting ID is returned.

Similar to get_fields(), this function retrieves information about previously-created plantings. This example returns all plantings associated with field_test.

The auto-generated planting ID must be supplied as well as the field ID.

All weather data requests are requested point by point. The API does not yet have the capacity to download regional data in a single call. The [batch jobs system](http://developer.awhere.com/api/reference/batch) is most useful for those wishing to request a large amount of data (e.g., many hundreds or thousands of points).

By default, you can request up to 30 months of daily historical data, counting back from the present date. For data beyond that, use the Norms API or speak with your aWhere representative for access to more of the daily data archive. The function `daily_observed_fields` provides the simplest method for retrieving historical data.

Users also have the option of using the alternative function `daily_observed_latlng` to retrieve historical data for a given pair of coordinates.

Forecasts are available from the current date plus up to the next 8 days, at multiple temporal resolutions - in 1, 2, 3, 4, 6, 8, 12, or 24-hour summary blocks.

As with daily observed historical data, forecast data can also be called based on latitude, longitude pairs.

The weather norms API allows you to offload the calculation of multi-year averages (minimum 3 years). This eliminates much of the need to download years and years of daily data just to calculate averages. The results also include the standard deviation for each average.

The Current Conditions API returns a snapshot of the weather at a geographic point using the nearest available station. While the data is QA'd before delivery, this service does not do the same advanced processing or interpolation as Daily Observed data.

Agronomic data can enrich your analysis by providing insight into the agronomic status of a field or crop. aWhere provides derived values like GDD (using a variety of different equations) PET (using the Penman-Monteith Equation), P/PET, and accumulated precipitation, accumulated GDD, accumulated PET, and P/PET over a range of days. The long-term norms for each value can also be queried.

Calculations can be customized in a number of different ways, consult the [API Documentation](http://developer.awhere.com/api/reference/agronomics/values) for more information.

The Agronomic Norms API returns the long-term normals for the agronomic values on any given set of days across any range of years for which we have data. The same customizable parameters for changing the calculation of agronomic values are also available in the norms.

Questions, comments, or requests about this vignette should be directed to [email protected]