-
Notifications
You must be signed in to change notification settings - Fork 3
/
myClim-package.R
228 lines (226 loc) · 16.3 KB
/
myClim-package.R
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
if(getRversion() >= "2.15.1") globalVariables(c(".data"))
#' @description
#'
#' Package myClim was designed for microclimate data processing, storing, and analyzing.
#' The myClim wofrkflow consists of reading logger files, pre-processing the time-series,
#' time-series aggregation, and microclimatic variables calculation. The microclimatic
#' data are stored in size-efficient hierarchical structure which respects the
#' hierarchy of field microclimate measurement (locality>loggers>sensors).
#'
#' After data import, myClim can summarize the data and automatically correct
#' for the most common problems. The myClim package provides functions to
#' calculate aggregated microclimate statistics as well as methods for data
#' calibration, conversion and calculation of derived microclimatic variables
#' like growing degree days, freezing degree days, snow cover duration,
#' volumetric water content and vapor pressure deficit.
#'
#' Standardized microclimatic variables can be stored efficiently in myClim
#' data format or easily exported to stadard R long or wide tables for further
#' analyses and visualization.
#'
#' **myClim object**
#'
#' We implemented two slightly different data formats of myClim objects calling them:
#' Raw-format and Agg-format.
#' Raw-format is designed for data preparation. Mainly data cleaning,
#' metadata gathering, time zones handling and multiple downloads joining.
#' Outputs of functions [myClim::mc_read_files()] and [myClim::mc_read_data()] are a Raw-format.
#' Raw-format has the levels of: localities, loggers and sensors.
#' Function [myClim::mc_agg()] converts data from Raw-format to Agg-format.
#' Agg-format is designed mainly for calculations,analysis and microclimatic variables
#' derivations on the basis of cleaned microclimatic data.
#' Agg-format is missing the level of loggers. In Agg-format sensors are organized
#' directly in localities, without loggers.
#'
#' The highest hierarchical level of myClim structure is the `locality`. It has own metadata e.g.
#' coordinates and elevation. For detail description of locality metadata see [mc_LocalityMetadata].
#' On the locality in Raw-format there are `loggers`; in Agg-format the `sensors`.
#' See below. Loggers represents the files imported with myClim reading functions.
#' Both `loggesr` and `sensors` have own metadata. One logger could host more sensors e.g.
#' Tomst TMS logger hosing TMS_T1 soil temperature, TMS_T2 surface temperature,
#' TMS_T3 air temperature , TMS_moist soil moisture.
#' For detailed description of logger and sensor metadata
#' see [mc_LoggerMetadata], [mc_SensorMetadata], [mc_data_sensors]
#'
#' In Raw-format Within the logger all sensors share time series. In Agg-format where level of
#' logger is missing, all sensors within the locality share time series. In Raw-format
#' the time series between the loggers or between the localities can be of different time
#' step. E.g. on the locality there can be one logger measuring in time step
#' 15 minutes and another one measuring once a day. In Agg-format this is not allowed.
#' Therefore it is necessary to use [myClim::mc_agg()] to switch from Raw-format to the Agg-format.
#'
#' myClim time step is defined in seconds (`data$metadata@step`).
#' But some steps (especially irregular ones) may not be represented by seconds.
#' For example step `month` has variable number of seconds within the year. Therefore, metadata contains also text
#' representation of the step (`data$metadata@period`).
#'
#'Schema of myClim **Raw-format**
#'
#' \preformatted{
#' +-------------------------+
#' $metadata | mc_MainMetadata - class |
#' +-------------------------+
#' | @version |
#' | @format_type |
#' +-------------------------+
#' +-------------------------------------------------------------------------------+
#' $localities | locality[1] |
#' +-------------------------------------------------------------------------------+
#' | +-----------------------------+ |
#' | $metadata | mc_LocalityMetadata - class | |
#' | +-----------------------------+ |
#' | | @locality_id | |
#' | | @elevation | |
#' | | @lat_wgs84 | |
#' | | @lon_wgs84 | |
#' | | @tz_offset | |
#' | | @tz_type | |
#' | | @user_data | |
#' | +-----------------------------+ |
#' | +------------------------------------------------------------------+|
#' | $loggers | logger[1] ||
#' | +------------------------------------------------------------------+|
#' | | +---------------------------+ ||
#' | | $metadata | mc_LoggerMetadata - class | ||
#' | | +---------------------------+ ||
#' | | | @type | ||
#' | | | @serial_number | ||
#' | | | @step | ||
#' | | +---------------------------+ ||
#' | | +----------------------------+ ||
#' | | $clean_info | mc_LoggerCleanInfo - class | ||
#' | | +----------------------------+ ||
#' | | | @step | ||
#' | | | @count_duplicities | ||
#' | | | @count_missing | ||
#' | | | @count_disordered | ||
#' | | | @rounded | ||
#' | | +----------------------------+ ||
#' | | $datetime POSIXct vector ||
#' | | +---------------------------------------------------+||
#' | | $sensors | sensor[1] |||
#' | | +---------------------------------------------------+||
#' | | | +---------------------------+ |||
#' | | | $metadata | mc_SensorMetadata - class | |||
#' | | | +---------------------------+ |||
#' | | | | @sensor_id | |||
#' | | | | @name | |||
#' | | | | @height | |||
#' | | | | @calibrated | |||
#' | | | +---------------------------+ |||
#' | | | $values numeric/logical vector |||
#' | | | +----------+------------+-----------+|||
#' | | | $calibration | datetime | cor_factor | cor_slope ||||
#' | | | | ... | ... | ... ||||
#' | | | +----------+------------+-----------+|||
#' | | | +-----+-------+-----+-------+ |||
#' | | | $states | tag | start | end | value | |||
#' | | | | ... | ... | ... | ... | |||
#' | | | +-----+-------+-----+-------+ |||
#' | | +---------------------------------------------------+||
#' | | +---------------------------------------------------+||
#' | | | sensor[2] |||
#' | | +---------------------------------------------------+||
#' | | ... ||
#' | | +---------------------------------------------------+||
#' | | | sensor[n] |||
#' | | +---------------------------------------------------+||
#' | +------------------------------------------------------------------+|
#' | +------------------------------------------------------------------+|
#' | | logger[2] ||
#' | +------------------------------------------------------------------+|
#' | ... |
#' | +------------------------------------------------------------------+|
#' | | logger[n] ||
#' | +------------------------------------------------------------------+|
#' +-------------------------------------------------------------------------------+
#' +-------------------------------------------------------------------------------+
#' | locality[2] |
#' +-------------------------------------------------------------------------------+
#' ...
#' +-------------------------------------------------------------------------------+
#' | locality[n] |
#' +-------------------------------------------------------------------------------+}
#'
#'
#' Agg-format is the output of [myClim::mc_agg()] function.
#' Agg-format is mainly designed for calculations which are faster in Agg and slower in Raw.
#'
#'
#' Schema of myClim **Agg-format**
#'
#' \preformatted{
#' +----------------------------+
#' $metadata | mc_MainMetadataAgg - class |
#' +----------------------------+
#' | @version |
#' | @format_type |
#' | @step |
#' | @period |
#' | @intervals_start |
#' | @intervals_end |
#' +----------------------------+
#' +-----------------------------------------------------------------+
#' $localities | locality[1] |
#' +-----------------------------------------------------------------+
#' | +-----------------------------+ |
#' | $metadata | mc_LocalityMetadata - class | |
#' | +-----------------------------+ |
#' | | @locality_id | |
#' | | @elevation | |
#' | | @lat_wgs84 | |
#' | | @lon_wgs84 | |
#' | | @tz_offset | |
#' | | @tz_type | |
#' | | @user_data | |
#' | +-----------------------------+ |
#' | $datetime POSIXct vector |
#' | +---------------------------------------------------+|
#' | $sensors | sensor[1] ||
#' | +---------------------------------------------------+|
#' | | +---------------------------+ ||
#' | | $metadata | mc_SensorMetadata - class | ||
#' | | +---------------------------+ ||
#' | | | @sensor_id | ||
#' | | | @name | ||
#' | | | @height | ||
#' | | | @calibrated | ||
#' | | +---------------------------+ ||
#' | | $values numeric/logical vector ||
#' | | +----------+------------+-----------+||
#' | | $calibration | datetime | cor_factor | cor_slope |||
#' | | | ... | ... | ... |||
#' | | +----------+------------+-----------+||
#' | | +-----+-------+-----+-------+ ||
#' | | $states | tag | start | end | value | ||
#' | | | ... | ... | ... | ... | ||
#' | | +-----+-------+-----+-------+ ||
#' | +---------------------------------------------------+|
#' | +---------------------------------------------------+|
#' | | sensor[2] ||
#' | +---------------------------------------------------+|
#' | ... |
#' | +---------------------------------------------------+|
#' | | sensor[n] ||
#' | +---------------------------------------------------+|
#' +-----------------------------------------------------------------+
#' +-----------------------------------------------------------------+
#' | locality[2] |
#' +-----------------------------------------------------------------+
#' ...
#' +-----------------------------------------------------------------+
#' | locality[n] |
#' +-----------------------------------------------------------------+}
#'
#' @importFrom grDevices dev.off gray hcl.colors pdf png
#' @importFrom graphics abline axis axis.POSIXct box grconvertX grconvertY grid image layout legend lines mtext par plot
#' @importFrom methods callNextMethod is new slot<- slotNames as slot
#' @importFrom stats aggregate end quantile sd start var
#' @importFrom utils packageVersion read.table tail
#' @keywords internal
"_PACKAGE"
# The following block is used by usethis to automatically manage
# roxygen namespace tags. Modify with care!
## usethis namespace: start
## usethis namespace: end
NULL