documentation/complete-documentation.md

In aWhereAPI/aWhere-R-Charts: Make Charts using output from aWhere API

aWhereCharts Library

This package of functions is designed to work primarily with the aWhere API, and users should first research and install the aWhereAPI package, and ensure they can make calls to the API and retrieve data. Users without an API account may sign up for a trial account.

The aWhereCharts package helps users accomplish a host of simple analytic tasks to get them started performing exploratory weather and agronomic charting as quickly as possible.

Installation

Note: Prior to installation you will need a working installation of R.

Note: You will need to have the devtools library installed in R. Consult documentation if necessary.

Automatically Install

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

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

Manually Install

1. Download this Github repo and keep the aWhere-R-ChartLibrary-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-ChartLibrary-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 the following set of commands to install and add the library to your environment:

   • library(devtools)
   • install("aWhere-R-ChartLibrary-master")
   • library(aWhereAPI)

Usage

The charting functions in this package are primarily designed to work with datasets generated by another function in this package: generateaWhereDataset(). This function pulls a standardized weather and agronomic dataset from the aWhere API for a given coordinate pair and span of dates, and users will need API credentials provided by aWhere and the aWhereAPI R package installed to successfully perform a call.

To get API keys, follow these instructions at the aWhere Developer Community. Note that normally the API Key and Secret are made up of random characters.

generateaWhereDataset

Prior to running generateaWhereDataset(), you'll need to use get_token() function (from the aWhereAPI package) to generate a token. Pass the API Key and API Secret from aWhere as the two parameters to this function. For example:

get_token("JFKL24JF290FJSKAFDF","jf0afsd9af0a")

You could also save the key and secret as variables. This function saves the token to a direct child of the base environment for use by any other aWhere function.

After you have successfully generated a token, generateaWhereDataset() can be executed with 6 required input parameters. An example is given here:

generateaWhereDataset(lat = -4.26, lon = 23.47, day_start = "2017-10-28", day_end = "2018-02-15", year_start = "2007", year_end = "2017")

The lat/lon parameters must be given in decimal degrees, and the day_start and day_end (indicating the first and last days of the date span for which you wish to retrieve data, denoted as YYYY-MM-DD) as well as the year_start and year_end (indicating the first and last years of the year span of data to include in the long-term normal - or LTN - calculations) must be character strings.

generateaWhereChart & generateaWhereStdDevChart

These functions generate line charts from an input dataset for an input variable, comparing the current conditions to long-term normals for the same time frame. It is designed to work with the generateaWhereDataset function. An example like the following will create a two-line chart comparing current accumulated Precipitation to LTN.

generateaWhereChart(data = df, variable = "accumulatedPrecipitation")

If the same parameters are used in the generateaWhereStdDevChart() function, as in the following, it will create the same chart, but with a shaded region above and below the LTN line equal to one standard deviation of each day's values. This can help users to understand if the current conditions are far outside the norm.

generateaWhereStdDevChart(data = df, variable = "accumulatedPrecipitation")

The acceptable variables are listed in the help documentation for the function. Additional optional parameters are also detailed, including adding a custom title to the chart, adding a line for effective precipitation, and customizing a rolling average window.

Formatting for the charts is performed using the ggplot2 and ggthemes packages.

generateaWhereHistogram

This function is most useful when users have a dataset with multiple observations across a region, and are trying to understand the variation. Advanced users will be able to generate such data using the API, while other aWhere clients may receive custom data files containing entire regions' worth of data. An example of the function's use is given here:

generateaWhereHistogram(data = df, variable = "SUM_Precip")

Unlike the generate chart functions above, the histogram function is not designed to accept a limited number of input variables to chart - users may specify any variable of the input dataset. However, unlike the above functions, generateaWhereStdDevChart() will not automatically configure a comparison of current to long-term normals. If users wish to set a comparison up, they can enable the function's optional parameters:

generateaWhereHistogram(data = df, variable = "SUM_Precip", compare = TRUE, compare_var = "LTN_SUM_Precip")

Additional optional parameters are allowed, and can be examined in detail in the help files for the function.

generateMultiplot

Weather and agronomic analysis often is aided by examining charts for several different attributes side by side. This function enables users to quickly assemble multiple plots generated by this package's charting functions (or any plot generated in R) into a flexible arrangement for easy viewing and saving.

generateMultiplot(rain_plot, maxtemp_plot, fontsize = 20, cols = 1)

The required inputs are plot objects separated by commas, and a title for the overall multiplot. Specifying the fontsize of the title, and the number of columns into which to arrange the plots is optional.

getCoordinateInfo

Users of the aWhere API will sometimes have a number of fields or latitude longitude coordinates for which they are querying data, sometimes from across the world. They may also have large files of data that span regions, but for which country designations were not provided. This function provides an option for users to quickly find the country in which a particular coordinate pair falls.

getCoordinateInfo(points = data[, c("longitude", "latitude")], attribute = "country")

The input to the points parameter must be a data frame or matrix with longitude in the first column and latitude in the second, and the attribute parameter may be "country", "continent", or "country classification".

aWhereAPI/aWhere-R-Charts documentation built on Dec. 30, 2021, 12:58 p.m.