Update documentation

.gitignore

@@ -44,3 +44,4 @@ dev_data/
 
 
 
+inst/doc

NEWS.md

@@ -0,0 +1,6 @@
+ag5Tools 0.0.1
+
+### Improvements
+
+* Added a `NEWS.md` file to track changes to the package.
+

R/extract.R

@@ -7,17 +7,18 @@
 #' and location, where the first dates value is the start date and the second the end date.
 
 #'@name ag5_extract
-#'@param coords numeric Vector of length = 2 of the form (lon, lat), or a data.fram with required columns
-#'@param variable The AgERA5 variable to extract, see details for available options
-#'@param statistic character Only for some variables, see details for valid options
-#'@param dates The dates for extracting the specified variable, either single character or a vector of length 2
+#'@param coords numeric vector of length = 2 of the form (lon, lat), or a \code{data.frame} with required columns
+#'@param variable \code{character} The AgERA5 variable to extract, see details for available options
+#'@param statistic \code{character} Only for some variables, see details for valid options
+#'@param dates \code{character} The dates for extracting the specified variable, a vector of length 1 extracts a single date, while
+#'a vector of length 2 indicates the start and end dates.
 #'or the column name in the case of \code{data.frame}
-#'@param lon character Column name of longitude values in the case of \code{data.frame}
-#'@param lat character Column name of latitude values in the case of \code{data.frame}
-#'@param start_date Column name of start_date values in the case of \code{data.frame}
-#'@param end_date Column name of end_date values in the case of \code{data.frame}
+#'@param lon \code{character} Column name of longitude values in the case of \code{data.frame}
+#'@param lat \code{character} Column name of latitude values in the case of \code{data.frame}
+#'@param start_date \code{character} Column name of start_date values in the case that coords is a \code{data.frame}
+#'@param end_date \code{character} Column name of end_date values in the case that coords is a \code{data.frame}
 #'@param time Only for variable Relative-Humidity-2m, see details for valid options
-#'@param path The path for the folder containing the AgERA5 files
+#'@param path \code{character} The path for the folder containing the AgERA5 files
 #'@param celsius logical Only for variables "Temperature-Air-2m" and "2m_dewpoint_temperature".
 #'If \code{TRUE} the values are converted from Kelvin to Celsius. Default is \code{FALSE}
 #'@param ... Other parameters
@@ -78,7 +79,7 @@
 #'                       dates = "1991-04-22",
 #'                       variable = "Temperature-Air-2m",
 #'                       statistic = "Max-Day-Time",
-#'                       path "C:/temperature_data/")
+#'                       path = "C:/temperature_data/")
 #'}
 #'
 #'@references

vignettes/extracing_data.Rmd

@@ -0,0 +1,65 @@
+---
+title: "Extracing AgERA5 data with ag5Tools"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{extracing_data}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+### Why a extracting function for agERA5 data?  
+
+The agERA5 data is downloaded from the Copernicus Climate Data Store as NetCDF files format, with a file extension `.nc`.
+
+The data is provided as daily observations and each file correspond to a given day. For instance, if you want precipitation data for year 2010, you will have 365 files or 366 in the case of a leap year.
+
+In case you want to use the precipitation data as model covariates, you have to seek for the specific dates and extract the data corresponding to the locations where the trial was established. Instead, you can use the ag5_extract function as demostrated in the next section.  
+
+Let's say you have observations from field trials of a trait of interest (e.g., yield) and want to link that with rainfall data to explore the effect of rainfall on that trait. You know the the plating and harvest dates for each trial plot. Then you can extract the time series of daily rainfall starting at plating date and finishing at harvest date.  
+
+Our synthetic example data shows the dates for random locations in Arusha, Tanzania.
+
+```{r}
+
+data("arusha_df", package = "ag5Tools")
+
+head(arusha_df)
+
+
+
+```
+With `ag5_extract()` function you can extract the required data, as long as you have downloaded it already.
+```{r eval = FALSE}
+
+library(ag5Tools)
+
+arusha_rainfall <- ag5_extract(coords = arusha_df,
+                               variable = "Precipitation-Flux",
+                               path = "D:/agera5_data/")
+
+```
+Notice that the `data.frame arusha_df` already has column names that match the default arguments in the function. If they do not match, you should indicate the column names as arguments of the function `ag5_download()`.  
+
+For example, if your `data.frame` has location columns named `x` and `y` and dates named as `planting_date` and `harvest_date`, the call to function `ag5_extract()` will look like:
+
+```{r eval = FALSE}
+arusha_rainfall <- ag5_extract(coords = example_df,
+                               lon = "x",
+                               lat = "y",
+                               start_date = "planting_date",
+                               end_date = "harvest_date",
+                               variable = "Precipitation-Flux",
+                               path = "D:/agera5_data/")
+
+```
+
+
+
+
+