1
#' @title Download and Create a Tidy Data Frame of CRU CL v. 2.0 Climatology Variables
2
#'
3
#' @description This function automates downloading and importing \acronym{CRU}
4
#' \acronym{CL} v. 2.0 climatology data and creates a tidy data frame of the
5
#' data.  If requested, minimum and maximum temperature may also be
6
#' automatically calculated as described in the data readme.txt file.  Data may
7
#' be cached for later use by this function, saving time downloading files in
8
#' future use of the function.
9
#'
10
#' Nomenclature and units from readme.txt:
11
#' \describe{
12
#' \item{pre}{precipitation (millimetres/month)}
13
#'   \describe{
14
#'    \item{cv}{cv of precipitation (percent)}
15
#'   }
16
#' \item{rd0}{wet-days (number days with >0.1mm rain per month)}
17
#' \item{tmp}{mean temperature (degrees Celsius)}
18
#' \item{dtr}{mean diurnal temperature range (degrees Celsius)}
19
#' \item{reh}{relative humidity (percent)}
20
#' \item{sunp}{sunshine (percent of maximum possible (percent of day length))}
21
#' \item{frs}{ground-frost (number of days with ground-frost per month)}
22
#' \item{wnd}{10 metre windspeed (metres/second)}
23
#' \item{elv}{elevation (automatically converted to metres)}
24
#' }
25
#' For more information see the description of the data provided by
26
#' \acronym{CRU}, \url{https://crudata.uea.ac.uk/cru/data/hrg/tmc/readme.txt}
27
#'
28
#' @param pre Logical.  Fetch precipitation (millimetres/month) from server and
29
#' return in the data frame?  Defaults to \code{FALSE}.
30
#' @param pre_cv Logical.  Fetch cv of precipitation (percent) from server and
31
#' return in the data frame?  Defaults to \code{FALSE}.  NOTE.  Setting this to
32
#' \code{TRUE} will always results in \strong{pre} being set to \code{TRUE} and
33
#' returned as well.
34
#' @param rd0 Logical.  Fetch wet-days (number days with >0.1millimetres rain
35
#' per month) and return in the data frame?  Defaults to \code{FALSE}.
36
#' @param dtr Logical.  Fetch mean diurnal temperature range (degrees Celsius)
37
#' and return it in the data frame?  Defaults to \code{FALSE}.
38
#' @param tmp Logical.  Fetch temperature (degrees Celsius) and return it in the
39
#' data frame?  Defaults to \code{FALSE}.
40
#' @param tmn Logical.  Calculate minimum temperature values (degrees Celsius)
41
#' and return it in the data frame?  Defaults to \code{FALSE}.
42
#' @param tmx Logical.  Calculate maximum temperature (degrees Celsius) and
43
#' return it in the data frame?  Defaults to \code{FALSE}.
44
#' @param reh Logical.  Fetch relative humidity and return it in the data frame?
45
#' Defaults to FALSE.
46
#' @param sunp Logical.  Fetch sunshine, percent of maximum possible (percent of
47
#' day length) and return it in data frame?  Defaults to \code{FALSE}.
48
#' @param frs Logical.  Fetch ground-frost records (number of days with ground-
49
#' frost per month) and return it in data frame?  Defaults to \code{FALSE}.
50
#' @param wnd Logical.  Fetch 10m wind speed (metres/second) and return it in the
51
#' data frame? Defaults to \code{FALSE}.
52
#' @param elv Logical.  Fetch elevation (converted to metres) and return it in
53
#' the data frame?  Defaults to \code{FALSE}.
54
#' @param cache Logical.  Store CRU CL v. 2.0 data files locally for later use?
55
#' If \code{FALSE}, the downloaded files are removed when R session is closed.
56
#' To take advantage of cached files in future sessions, use \code{cache = TRUE}
57
#' after the initial download and caching.  Defaults to \code{FALSE}.
58
#'
59
#' @examples
60
#' \donttest{
61
#' # Download data and create a data frame of precipitation and temperature
62
#' # without caching the data files
63
#' CRU_pre_tmp <- get_CRU_df(pre = TRUE, tmp = TRUE)
64
#'
65
#' head(CRU_pre_tmp)
66
#'
67
#' library(tibble)
68
#' CRU_pre_tmp
69
#' }
70
#'
71
#' @seealso
72
#' \code{\link{create_CRU_stack}}
73
#' \code{\link{manage_cache}}
74
#'
75
#' @return A tidy data frame of \acronym{CRU} \acronym{CL} v. 2.0 climatology
76
#' elements as a \code{\link[tibble]{tibble}} object
77
#'
78
#' @author Adam H. Sparks, \email{adamhsparks@@gmail.com}
79
#'
80
#' @note
81
#' This package automatically converts elevation values from kilometres to
82
#' metres.
83
#'
84
#' @export
85

86
get_CRU_df <- function(pre = FALSE,
87
                       pre_cv = FALSE,
88
                       rd0 = FALSE,
89
                       tmp = FALSE,
90
                       dtr = FALSE,
91
                       reh = FALSE,
92
                       tmn = FALSE,
93
                       tmx = FALSE,
94
                       sunp = FALSE,
95
                       frs = FALSE,
96
                       wnd = FALSE,
97
                       elv = FALSE,
98
                       cache = FALSE) {
99 1
  if (!isTRUE(pre) & !isTRUE(pre_cv) & !isTRUE(rd0) & !isTRUE(tmp) &
100 1
      !isTRUE(dtr) & !isTRUE(reh) & !isTRUE(tmn) & !isTRUE(tmx) &
101 1
      !isTRUE(sunp) & !isTRUE(frs) & !isTRUE(wnd) & !isTRUE(elv)) {
102 1
    stop("\nYou must select at least one element for download.\n",
103 1
         call. = FALSE)
104
  }
105

106 1
  cache_dir <- .set_cache(cache)
107

108 1
  files <- .get_CRU(pre,
109 1
                    pre_cv,
110 1
                    rd0,
111 1
                    tmp,
112 1
                    dtr,
113 1
                    reh,
114 1
                    tmn,
115 1
                    tmx,
116 1
                    sunp,
117 1
                    frs,
118 1
                    wnd,
119 1
                    elv,
120 1
                    cache_dir)
121

122 1
  d <- .create_df(tmn, tmx, tmp, dtr, pre, pre_cv, elv, files)
123 1
  return(tibble::as_tibble(d))
124
}

Read our documentation on viewing source code .

Loading