Movatterモバイル変換

myClim: Microclimatic Data Processing

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 microclimaticdata are stored in size-efficient hierarchical structure which respects thehierarchy of field microclimate measurement (locality>loggers>sensors).

After data import, myClim can summarize the data and automatically correctfor the most common problems. The myClim package provides functions tocalculate aggregated microclimate statistics as well as methods for datacalibration, conversion and calculation of derived microclimatic variableslike growing degree days, freezing degree days, snow cover duration,volumetric water content and vapor pressure deficit.

Standardized microclimatic variables can be stored efficiently in myClimdata format or easily exported to standard R long or wide tables for furtheranalyses 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 functionsmc_read_files() andmc_read_data() are a Raw-format.Raw-format has the levels of: localities, loggers and sensors.Functionmc_agg() converts data from Raw-format to Agg-format.Agg-format is designed mainly for calculations,analysis and microclimatic variablesderivations on the basis of cleaned microclimatic data.Agg-format is missing the level of loggers. In Agg-format sensors are organizeddirectly in localities, without loggers.

The highest hierarchical level of myClim structure is thelocality. It has own metadata e.g.coordinates and elevation. For detail description of locality metadata seemc_LocalityMetadata.On the locality in Raw-format there areloggers; in Agg-format thesensors.See below. Loggers represents the files imported with myClim reading functions.Bothloggesr andsensors 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 metadataseemc_LoggerMetadata,mc_SensorMetadata,mc_data_sensors

In Raw-format Within the logger all sensors share time series. In Agg-format where level oflogger is missing, all sensors within the locality share time series. In Raw-formatthe time series between the loggers or between the localities can be of different timestep. E.g. on the locality there can be one logger measuring in time step15 minutes and another one measuring once a day. In Agg-format this is not allowed.Therefore it is necessary to usemc_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 stepmonth has variable number of seconds within the year. Therefore, metadata contains also textrepresentation of the step (data$metadata@period).

Schema of myClimRaw-format

            +-------------------------+$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                    |                                     |            |           | @join_serial                |                                     |            |           | @user_data                  |                                     |            |           +-----------------------------+                                     |            |           +------------------------------------------------------------------+|            | $loggers  | logger[1]                                                        ||            |           +------------------------------------------------------------------+|            |           |             +---------------------------+                        ||            |           | $metadata   | mc_LoggerMetadata - class |                        ||            |           |             +---------------------------+                        ||            |           |             | @type                     |                        ||            |           |             | @name                     |                        ||            |           |             | @serial_number            |                        ||            |           |             | @step                     |                        ||            |           |             | @raw_index                |                        ||            |           |             +---------------------------+                        ||            |           |             +----------------------------+                       ||            |           | $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 ofmc_agg() function.Agg-format is mainly designed for calculations which are faster in Agg and slower in Raw.

Schema of myClimAgg-format

            +----------------------------+$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                    |                      |            |            | @join_serial                |                      |            |            | @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]                                                     |            +-----------------------------------------------------------------+

Author(s)

Maintainer: Vojtěch KalčíkVojtech.Kalcik@ibot.cas.cz

Authors:

• Matěj ManMatej.Man@ibot.cas.cz

• Martin MacekMartin.Macek@ibot.cas.cz

• Josef BrůnaJosef.Bruna@ibot.cas.cz

• Lucia HederováLucia.Hederova@ibot.cas.cz

• Jan WildJan.Wild@ibot.cas.cz

• Martin KopeckýMartin.Kopecky@ibot.cas.cz

Other contributors:

• Institute of Botany of the Czech Academy of Sciences [copyright holder]

See Also

Useful links:

• http://labgis.ibot.cas.cz/myclim/index.html

• https://github.com/ibot-geoecology/myClim

Extract localities with []

Description

Using [] for extract localities.

Usage

## S3 method for class 'myClimList'x[...]

Arguments

Value

myClim object with subset of localities seemyClim-package

Examples

filtered_data <- mc_data_example_raw[1:2]

Length function for myClim object

Description

Function return number of localities.

Usage

## S3 method for class 'myClimList'length(x, ...)

Arguments

Examples

length(mc_data_example_agg)

Class for Logger File Data Format

Description

This class is used for parsing source TXT/CSV files downloaded from microclimaticloggers.

Details

myClim offers several pre-definedlogger file data formats, such as TOMST TMS or HOBO. Users can also define customreadings for their own loggers. Pre-defined and custom loggers in myClim each havetheir own specific object of class⁠mc_{logger}DataFormat⁠, which defines theparameters for handling logger files.The pre-defined logger definitions are stored in the R environment object./data/mc_data_formats.rda.

Slots

skip

The number of rows to skip before the first row containing microclimatic records.For example, to skip the header (default 0).

separator

The column separator (default is a comma ",").

date_column

The index of the date column - required (default NA).

date_format

The format of the date (default NA).

For a description of the date_format parameter, seestrptime(). If the format is in ISO8601and the functionvroom::vroom() automatically detects datetime values,the date_format parameter can be NA.

na_strings

Strings for representing NA values, e.g., "-100", "9999" (default "").

error_value

The value that represents an error of the sensor, e.g., 404, 9999 (default NA).

The error_value is replaced by NA, and intervals of errors are flagged insensor$states(seemyClim-package).

columns

A list with names and indexes of value columns - required (default list()).

Names come from names(mc_data_sensors). Names are defined as constants⁠mc_const_SENSOR_*⁠.For example, if the third column is temperature, you can define it ascolumns[[mc_const_SENSOR_T_C]] <- 3.There are universal sensors for arbitrary value types:mc_const_SENSOR_real,mc_const_SENSOR_integerandmc_const_SENSOR_logical. Multiple columns with same sensor type can be definedascolumns[[mc_const_SENSOR_real]] <- c(2, 3, 4). The names in this example will bereal1,real2 andreal3.

col_types

Parameter forvroom::vroom() (default NA).

To ensure the correct reading of values, you have the possibility to strictly define the types of columns.

filename_serial_number_pattern

A character pattern for detecting the serial number from the file name (default NA).

The regular expression with brackets around the serial number.For example, the pattern for old TOMST files is"data_(\\d+)_\\d+\\.csv$". If the value is NA, the name of the file is usedas the serial number.

data_row_pattern

A character pattern for detecting the correct file format (default NA).

The regular expression. If data_row_pattern is NA, then the file format is not checked.

logger_type

The type of logger: TMS, TMS_L45, Thermo, Dendro, HOBO, ... (default NA).

tz_offset

The timezone offset in minutes from UTC - required (default NA).

If the value of the tz_offset parameter is 0, then datetime values are in UTC.If the time zone offset is defined in the value, e.g.,"2020-10-06 09:00:00+0100",anddate_format is"%Y-%m-%d %H:%M:%S%z", the value is automatically converted to UTC.

index_column

The index of column, where is index (order) of values used for data checking (default NA).

See Also

mc_data_formats,mc_TOMSTDataFormat,mc_TOMSTJoinDataFormat,mc_HOBODataFormat

Class for reading HOBO logger files

Description

Provides the key for reading the HOBO source files. In which column is the date,in what format is the date, in which columns are records of which sensors.The code defining the class is in section methods ./R/model.R

Slots

convert_fahrenheit

if TRUE temperature values are converted from °F to °C (default FALSE)

See Also

mc_DataFormat,mc_data_formats

Class for locality metadata

Description

Class for locality metadata

Details

When reading without metadata, then locality is named after filewhere the data come from, or after the sensor id where the data come form.

Slots

locality_id

name of locality

elevation

of locality

lat_wgs84

latitude of locality in WGS-84

lon_wgs84

longitude of locality in WGS-84

tz_offset

offset from UTC in minutes

tz_type

type of time zone

join_serial

list of serial numbers of loggers for join operation

user_data

list for user data

See Also

myClim-package,mc_LoggerMetadata,mc_SensorMetadata

Class for logger clean info

Description

Class for logger clean info

Slots

step

Time step of microclimatic data series in seconds

count_duplicities

count of duplicated records - values with same date

count_missing

count of missing records; Period between the records should be the same length. If not, than missing.

count_disordered

count of records incorrectly ordered in time. In table, newer record is followed by the older.

rounded

T/F indication whether myClim automatically rounded time series to the closes half (HH:00, HH:30) e.g. 13:07 -> 13:00

Class for logger metadata

Description

Class for logger metadata

Slots

type

type of logger (TMS, Thermo, Dendro, HOBO)

name

name of the logger - default in format⁠(type)_(index)⁠

serial_number

serial number of the logger

step

time step of microclimatic time-seris in seconds.When provided by user, is used inmc_prep_clean() function instead ofautomatic step detection

raw_index

index of values in uncleaned data, used for data checking. This value is deleted during cleaning process.

Class for myClim object metadata

Description

Class for myClim object metadata

Slots

version

the version of the myClim package in which the object was created

format_type

type of format (Raw-format, Agg-format)

See Also

myClim-package

Class for myClim object metadata in Agg-format

Description

Class for myClim object metadata in Agg-format

Slots

version

the version of the myClim package in which the object was created

format_type

type of format (Raw-format, Agg-format)

step

time step of data in seconds

period

value frommc_agg() (e.g. month, day, all...)

intervals_start

start datetime of data intervals for spacial periods all and custom (seemc_agg())

intervals_end

end datetime of data intervals for spacial periods all and custom (seemc_agg())

See Also

mc_MainMetadatamyClim-package

Class for physical

Description

Class defining the element of the records (temperature, volumetric water content, height...)

Details

See e.g. definition of temperature. Similarly as the definition of new loggers, newphysicals can be added like modules.

Slot "name": "T_C"Slot "description": "Temperature °C"Slot "units": "°C"Slot "viridis_color_map": "C" Slot "scale_coeff": 0.03333333

Slots

name

of physical

description

character info

units

measurument (°C, %, m3/m3, raw, mm, ...)

viridis_color_map

viridis color map option

scale_coeff

coefficient for plot; value * scale_coef is in range 0-1

See Also

mc_data_physical

Class for sensor definition

Description

Sensor definitions are stored inmc_data_sensors.

Slots

sensor_id

unique identifier of sensor (TMS_T1, TMS_T2, TMS_T3, TMS_moist, ...)

logger

name of logger (TMS, Thermo, ...)

physical

unit of sensor (T_C, moisture_raw, moisture, RH) (default NA)

description

character info

value_type

type of values (real, integer, logical) (default real)

min_value

minimal value (default NA)

max_value

maximal value (default NA)

plot_color

color in plot (default "")

plot_line_width

width of line in plot (default 1)

See Also

mc_data_sensors

Class for sensor metadata

Description

Class for sensor metadata

Details

sensor_id must be one of the defined id in myClim. seemc_data_sensors.It is useful to select on of predefined, because it makes plotting and calculaton easier.Throughsensor_id myClim assign pre-deined physicyl units or plotting colors seemc_Sensor.

Slots

sensor_id

unique identifier of sensor (TMS_T1, TMS_T2, TMS_T3, TMS_moist, ...)mc_data_sensors e.g. TMS_T1, TMS_moist, snow_fresh...

name

character, could be same assensor_id but also defined by function or user.

height

character

calibrated

logical - detect if sensor is calibrated

See Also

myClim-package,mc_LoggerMetadata,mc_data_sensors

Class for reading TOMST logger files

Description

Provides the key for the column in source files. Where is the date,in what format is the date, in which columns are records of which sensors.The code defining the class is in section methods ./R/model.R

See Also

mc_DataFormat,mc_data_formats,mc_TOMSTJoinDataFormat

Class for reading TMS join files

Description

Provides the key for the column in source files. Where is the date,in what format is the date, in which columns are records of which sensors.The code defining the class is in section methods ./R/model.R

Details

TMS join file format is the output of IBOT internal post-processing of TOMST logger files.

See Also

mc_DataFormat,mc_data_formats,mc_TOMSTDataFormat,mc_TOMSTJoinDataFormat

Aggregate data by function

Description

mc_agg has two basic uses:

• aggregate (upscale) time step of microclimatic records with specified function (e. g. 15 min records to daily mean);

• convert myClim object from Raw-format to Agg-format seemyClim-package without time-series modification,this behavior appears whenfun=NULL,period=NULL.

Usage

mc_agg(  data,  fun = NULL,  period = NULL,  use_utc = TRUE,  percentiles = NULL,  min_coverage = 1,  custom_start = NULL,  custom_end = NULL,  custom_functions = NULL)

Arguments

Details

Any output of mc_agg is in Agg-format. That means thehierarchical level of logger is removed (Locality<-Logger<-Sensor<-Record), and all microclimatic records withinthe sensors are on the level of locality (Locality<-Sensor<-Record). SeemyClim-package.

In casemc_agg() is used only for conversion from Raw-format to Agg-format (⁠fun=NULL, period=NULL⁠) then microclimaticrecords are not modified. Equal step in all sensors is required for conversion from Raw-format to Agg-format, otherwiseperiod must be specified.

When fun and period are specified, microclimatic records are aggregated based on a selected function into a specified period.The name of the aggregated variable will contain also the name of the function used for the aggregation (e.g. TMS_T1_mean).Aggregated time step is named after the first time step of selected period i.e. day = c(2022-12-29 00:00, 2022-12-30 00:00...);week = c(2022-12-19 00:00, 2022-12-28 00:00...); month = c(2022-11-01 00:00, 2022-12-01 00:00...);year = c(2021-01-01 00:00, 2022-01-01 00:00...).When first or last period is incomplete in original data, the incomplete part is extended with NA values to match specified period.For example, when you want to aggregate time-series to monthly mean, but your time-series starts on January 15 ending December 20,myClim will extend the time-series to start on January 1 and end on December 31.If you want to still use the data from the aggregation periods with not complete data coverage, you can adjust the parametermin_coverage.

Empty sensors with no records are excluded.mc_agg() return NA for empty vector except fromfun=count which returns 0.When aggregation functions are provided as vector or list e.g. c(mean, min, max), than they are all applied to all the sensorsand multiple results are returned from each sensors. When named list (names are the sensor ids) of functions is provided thenmc_agg()apply specific functions to the specific sensors based on the named listlist(TMS_T1=c("max", "min"), TMS_T2="mean").mc_agg returns new sensors on the localities putting aggregationfunction in its name (TMS_T1 -> TMS_T1_max), despite sensor names contains aggregationfunction, sensor_id stays the same as before aggregation in sensor metadata (e.g. TMS_T1 -> TMS_T1).Sensors created with functionsmin,max,mean,percentile,sum,rangekeeps identical sensor_id and value_type as original input sensors.When functionsum is applied onlogical sensor (e.g. snow as TRUE, FALSE) theoutput isinteger i.e. number ofTRUE values.

Sensors created with functionscount has sensor_idcount and value_typeinteger,functioncoverage has sensor_idcoverage and value_typereal

If the myClim object contains any states (tags) table, such as error tags or quality tags,the datetime defining the start and end of the tag will be rounded according to the aggregation period parameter.

Value

Returns new myClim object in Agg-format seemyClim-package When fun=NULL, period=NULLrecords are not modified but only converted to Agg-format.When fun and period are provided then time step is aggregated based on function.

Examples

hour_data <- mc_agg(mc_data_example_clean, c("min", "max", "percentile"),                              "hour", percentiles = 50, min_coverage=0.5)day_data <- mc_agg(mc_data_example_clean, list(TMS_T1=c("max", "min"), TMS_T2="mean"),                             "day", min_coverage=1)month_data <- mc_agg(mc_data_example_clean, fun=list(TMS_T3="below5"),period = "month",                               custom_functions = list(below5=function(x){length(x[x<(-5)])}))

Cumulative sum

Description

This function creates a new virtual sensor on locality within the myClim data object.The virtual sensor represents the cumulative sum of the values on the input sensor.Names of new sensors are original sensor name +outpus_suffix.

Usage

mc_calc_cumsum(data, sensors, output_suffix = "_cumsum", localities = NULL)

Arguments

Details

If value type of sensor is logical, then output type is integer. (TRUE, TRUE, FALSE -> 2)

Value

The same myClim object as input but with added cumsum sensors.

Examples

cumsum_data <- mc_calc_cumsum(mc_data_example_agg, c("TMS_T1", "TMS_T2"))

Freezing Degree Days

Description

This function creates a new virtual sensor on locality within the myClim data object.The new virtual sensor provides FDD Freezing Degree Days.

Usage

mc_calc_fdd(data, sensor, output_prefix = "FDD", t_base = 0, localities = NULL)

Arguments

Details

The allowed step length for FDD calculation is day and shorter.Function creates a new virtual sensor with the same time step as input data.For shorter time steps than the day (which is however not intuitive for FDD)the FDD value is the contribution of the time step to the freezing degree day.Be careful while aggregating freezing degree days to longer periodsonly meaningful aggregation function issum, but myClim allows you to apply anything seemc_agg().

Note that FDD is always positive number, despite summing freezing events. When you sett_base=-1 you get the sum of degree days below -1 °C but expressed in positive numberif you sett_base=1 you get also positive number. Therefore pay attention toname of output variable which containst_base value. FDD1_TMS_T3, t_base=1 vs FDDminus1_TMS_T3, t_base=-1

Value

The same myClim object as input but with added virtual FDD sensor

Examples

fdd_data <- mc_calc_fdd(mc_data_example_agg, "TMS_T3", localities = c("A2E32", "A6W79"))fdd_agg <- mc_agg(fdd_data, list(TMS_T3=c("min", "max"), FDD5="sum"), period="day")

Growing Degree Days

Description

This function creates a new virtual sensor for each locality within myClim data object. The new virtual sensorprovides values of GDD (Growing Degree Days) in degees Celsius for each time step in the original timeseries.

Usage

mc_calc_gdd(data, sensor, output_prefix = "GDD", t_base = 5, localities = NULL)

Arguments

Details

Function calculates growing degree days as follows: GDD = max(0;(T - Tbase)) . period(days)The maximum allowed time step length for GDD calculation is one day.Function creates a new virtual sensor with the same time step as input data.For shorter time steps than one day, the GDD value is the contributionof the interval to the growing degree day, assuming constant temperature over this period.Be careful while aggregating growing degree days to longer periods, because only meaningful aggregation function here issum,but myClim let you apply any aggregation function seemc_agg().

Value

The same myClim object as input but with added virtual GDD sensor

Examples

gdd_data <- mc_calc_gdd(mc_data_example_agg, "TMS_T3", localities = c("A2E32", "A6W79"))gdd_agg <- mc_agg(gdd_data, list(TMS_T3=c("min", "max"), GDD5="sum"), period="day")

Snow detection from temperature

Description

This function creates a new virtual sensor on locality within the myClim data object.Virtual sensor hosts values of snow cover presence/absence detected from temperature time-series.

Usage

mc_calc_snow(  data,  sensor,  output_sensor = "snow",  localities = NULL,  range = 1,  tmax = 1.25,  days = 3)

Arguments

Details

Function detects snow cover from temperature time-series. Temperature sensor is considered as covered by snowwhen the maximal temperature in the preceding or subsequent time-window (specified bydays param)does not exceed specifictmax threshold value (default 1.25°C) and the temperature range remain below specifiedrange threshold (default 1°C). This function rely on insulating effect of a of snow layer,significantly reducing diurnal temperature variation and restricting the maximal temperature near the groundclose to freezing point. Temperature sensor near the ground (TMS_T2) is default choice for snow-cover detection from Tomst TMS loggers.Snow detection with default values accurately detects snow of depth > 15cm (unpublished data).For detection of thin snow, range parameter should be set to 3-4 °C.The function returns vector of snow cover (TRUE/FLASE) with same time-step as input data. To get number of days with snow coverand more snow summary characteristics usemc_calc_snow_agg after snow detection.

Value

myClim object with added virtual sensor 'snow' (logical) indicating snow presence/absence (TRUE/FALSE).

Examples

data <- mc_calc_snow(mc_data_example_agg, "TMS_T2", output_sensor="TMS_T2_snow",                     localities = c("A2E32", "A6W79"))

Summary of TRUE/FALSE snow sensor

Description

This function works with the virtual snow sensor of TRUE/FALSEwhich is the output ofmc_calc_snow(). So, before callingmc_calc_snow_agg you need to calculate or importmc_read_TRUE/FALSE snow sensor.mc_calc_snow_agg returns the summary table of snow sensor(e.g number of days with snow cover, first and last date of continualsnow cover longer than input period).The snow summary is returned for whole date range provided. And is returned asnew data.frame in contrast with other mc_calc functions returning virtual sensors.

Usage

mc_calc_snow_agg(  data,  snow_sensor = "snow",  localities = NULL,  period = 3,  use_utc = FALSE)

Arguments

Details

Primary designed for virtual snow sensor calculated bymc_calc_snow(),but accepts any sensor with TRUE/FLAST snow event detection. Ifsnow_sensoron the locality is missing, then locality is skipped.

Value

Returns data.frame with columns:

• locality - locality id

• snow_days - number of days with snow cover

• first_day - first day with snow

• last_day - last day with snow

• first_day_period - first day of period with continual snow cover based onperiod parameter

• last_day_period - last day of period with continual snow cover based onperiod parameter

Examples

data <- mc_calc_snow(mc_data_example_agg, "TMS_T2", output_sensor="TMS_T2_snow",                     localities = c("A2E32", "A6W79"))mc_calc_snow_agg(data, "TMS_T2_snow")

Converting Tomst dendrometer values to micrometers

Description

This function creates a new virtual sensor on locality within the myClim data object.The virtual sensor provides the values of the change in stem size converted from rawTomst units to micrometers. Note that newer versions of Tomst Lollysoftware can directly convert raw Tomst units to micrometers.

Usage

mc_calc_tomst_dendro(  data,  dendro_sensor = mc_const_SENSOR_Dendro_raw,  output_sensor = mc_const_SENSOR_dendro_l_um,  localities = NULL)

Arguments

Value

myClim object same as input but with added dendro_l_um sensor

Examples

agg_data <- mc_calc_tomst_dendro(mc_data_example_agg, localities="A1E05")

Calculate vapor pressure deficit (in kPa)

Description

This function creates a new virtual sensor on locality within the myClim data object.The virtual sensor represents the vapor pressure deficit (in kPa) calculatedfrom temperature and relative air humidity.

Usage

mc_calc_vpd(  data,  temp_sensor = "HOBO_T",  rh_sensor = "HOBO_RH",  output_sensor = "VPD",  elevation = 0,  metadata_elevation = TRUE,  localities = NULL)

Arguments

Details

Equation are from the CR-5 Users Manual 2009–12 from Buck Research. These equations have been modified from Buck (1981)and adapted by Jones, 2013 (eq. 5.15)Elevation to pressure conversion function uses eq. 3.7 from Campbell G.S. & Norman J.M. (1998).

Value

myClim object same as input but with added VPD sensor

References

Jones H.G. (2014) Plants and Microclimate, Third Edit. Cambridge University Press, CambridgeBuck A.L. (1981) New equations for computing vapor pressure and enhancment factor. Journal of Applied Meteorology 20: 1527–1532.Campbell G.S. & Norman J.M. (1998). An Introduction to Environmental Biophysics, Springer New York, New York, NY

Examples

agg_data <- mc_calc_vpd(mc_data_example_agg, "HOBO_T", "HOBO_RH", localities="A2E32")

Conversion of raw TMS soil moisture values to volumetric water content (VWC)

Description

This function creates a new virtual sensor on the locality within the myClim data object.Function converts the raw TMS soil moisture (scaled TDT signal)to volumetric water content (VWC).

Usage

mc_calc_vwc(  data,  moist_sensor = mc_const_SENSOR_TMS_moist,  temp_sensor = mc_const_SENSOR_TMS_T1,  output_sensor = "VWC_moisture",  soiltype = "universal",  localities = NULL,  ref_t = mc_const_CALIB_MOIST_REF_T,  acor_t = mc_const_CALIB_MOIST_ACOR_T,  wcor_t = mc_const_CALIB_MOIST_WCOR_T,  frozen2NA = TRUE)

Arguments

Details

This function is suitable for TOMST TMS loggers measuring soil moisture in raw TMS units.The raw TMS units represents inverted and numerically rescaled (1-4095) electromagnetic signal from the moisture sensor workingon Time Domain Transmission principle (Wild et al. 2019). For TMS4 logger, the typical raw TMS moisture values range from cca115 units in dry air to cca 3635 units in distilled water - seemc_calib_moisture.

Raw TMS moisture values can be converted to the soil volumetric water content with calibration curves. The function providesseveral experimentally derived calibration curves which were developped at reference temperature. To account for the differencebetween reference and actual temperature, the function uses actual soil temperature values measured by TMS_T1 soil temperaturesensor.

The default calibration curve is "universal", which was designed for mineral soils (see Kopecký et al. 2021).Specific calibration curves were developed for several soil types (see Wild et al. 2019) and the user can choose one of theseor can define its own calibration - seemc_data_vwc_parameters

Currently available calibration curves are: sand, loamy sand A,loamy sand B, sandy loam A, sandy loam B, loam, silt loam, peat, water,universal, sand TMS1, loamy sand TMS1, silt loam TMS1.For details seemc_data_vwc_parameters.

It is also possible to define a new calibarion function with custom parametersa,b andc. These can bederived e.g. from TOMST TMS Calibr utility after entering custom ratio of clay, silt, sand.

Warning: TOMST TMS Calibr utility was developed for TMS3 series of TMS loggers, which havedifferent range of raw soil moisture values than TMS4 series.

The function by default replace the moisture records in frozen soils with NA (paramfrozen2NA),because the TMS soil moisture sensor was not designed to measure in frozen soils and the returned values are thus not comparablewith values from non-frozen soil.

Value

myClim object same as input but with added virtual VWC moisture sensor

References

Wild, J., Kopecký, M., Macek, M., Šanda, M., Jankovec, J., Haase, T. (2019) Climate at ecologically relevant scales:A new temperature and soil moisture logger for long-term microclimate measurement. Agriculture and Forest Meteorology 268, 40-47.https://doi.org/10.1016/j.agrformet.2018.12.018

Kopecký, M., Macek, M., Wild, J. (2021) Topographic Wetness Index calculation guidelines based on measured soilmoisture and plant species composition. Science of the Total Environment 757, 143785. https://doi.org/10.1016/j.scitotenv.2020.143785

See Also

mc_data_vwc_parameters

Examples

data1 <- mc_calc_vwc(mc_data_example_agg, soiltype="sand", localities="A2E32")data2 <- mc_calc_vwc(mc_data_example_agg, localities="A2E32",                     soiltype=list(a=-3.00e-09, b=0.000161192, c=-0.109956505))

Calculates coefficients for TMS moisture conversion to VWC

Description

Specialized function for calibration of TOMST TMS moisture sensor.Function calculate correction parameters for individual logger (slope and intercept)from TMS moisture measurements in demineralized water and dry air.

Usage

mc_calib_moisture(  raw_air,  raw_water,  t_air = 24,  t_water = 24,  ref_air = 114.534,  ref_water = 3634.723,  ref_t = mc_const_CALIB_MOIST_REF_T,  acor_t = mc_const_CALIB_MOIST_ACOR_T,  wcor_t = mc_const_CALIB_MOIST_WCOR_T)

Arguments

Details

This function calculate calibration parameterscor_factor andcor_interceptaccounting for individual differencies in TMS moisture sensor signal in air and in water against referenceloggers which were used for estimation of parameters of soil VWC conversion curves.These parameters must be loaded into myClim objectmc_prep_calib_load()prior to callingmc_calc_vwc().Parameters for soils available in my_Clim were derived for TMS3 logger version, with slightly different typical air and water signal.Correction parameters for TMS4 loggers therefore can be expected in the range of values:cor_factor = (-150; -450) and cor_slope = (100, 450)

Value

list with correction factor and correction slope

Examples

# load example datafiles <- c(system.file("extdata", "data_94184102_0.csv", package = "myClim"))tomst_data <- mc_read_files(files, "TOMST")# vwc without calibrationtomst_data <- mc_calc_vwc(tomst_data, soiltype = "universal", output_sensor = "VWC_universal")# load calibrationmy_cor <- mc_calib_moisture(raw_air = 394, raw_water = 3728, t_air = 21, t_water = 20)my_calib_tb <- data.frame(serial_number = c("94184102"), sensor_id = "TMS_moist",                          datetime = as.POSIXct("2020-01-01 00:00"),                          cor_factor = my_cor$cor_factor, cor_slope = my_cor$cor_slope)tomst_data_cal <- mc_prep_calib_load(tomst_data, my_calib_tb)# vwc using calibrationtomst_data_cal <- mc_calc_vwc(tomst_data_cal, soiltype = "universal",                              output_sensor = "VWC_universal_calib")# plot results## Not run: sensors <- mc_info(tomst_data_cal)$sensor_namemc_plot_line(tomst_data_cal, sensors = c(sensors[startsWith(sensors,"VWC")])     + ggplot2::scale_color_viridis_d(begin = 0.2, end = 0.8))## End(Not run)

Default temperature drift for TMS moisture in the air.

Description

1.91132689118083 = default temperature drift correction parameter in the air -TMS moisture sensor. This constant is used in the functionmc_calc_vwc.

Usage

mc_const_CALIB_MOIST_ACOR_T

Format

An object of classnumeric of length 1.

Default ref. temperate for TMS moisture calibration

Description

24°C = default reference calibration temperate for TMS moisture sensor

Usage

mc_const_CALIB_MOIST_REF_T

Format

An object of classnumeric of length 1.

Default temperature drift for TMS moisture in the water

Description

0.64108 = default temperature drift correction parameter in the water -TMS moisture sensor. This constant is used in the functionmc_calc_vwc.

Usage

mc_const_CALIB_MOIST_WCOR_T

Format

An object of classnumeric of length 1.

Default sensor for TOMST Dendrometer temperature

Description

Default sensor for TOMST Dendrometer temperature

Usage

mc_const_SENSOR_Dendro_T

Format

An object of classcharacter of length 1.

Default sensor for TOMST Dendrometer radius difference

Description

This constant is used in the functionmc_calc_tomst_dendroas default sensor for converting the change in stem size from rawTOMST units to micrometers.mc_const_SENSOR_Dendro_raw = "Dendro_raw"

Usage

mc_const_SENSOR_Dendro_raw

Format

An object of classcharacter of length 1.

Freezing Degree Days sensor id seemc_calc_fdd()

Description

Freezing Degree Days sensor id seemc_calc_fdd()

Usage

mc_const_SENSOR_FDD

Format

An object of classcharacter of length 1.

Growing Degree Days sensor id seemc_calc_gdd()

Description

Growing Degree Days sensor id seemc_calc_gdd()

Usage

mc_const_SENSOR_GDD

Format

An object of classcharacter of length 1.

Onset HOBO external temperature sensor id

Description

Onset HOBO external temperature sensor id

Usage

mc_const_SENSOR_HOBO_EXTT

Format

An object of classcharacter of length 1.

Onset HOBO humidity sensor id

Description

Onset HOBO humidity sensor id

Usage

mc_const_SENSOR_HOBO_RH

Format

An object of classcharacter of length 1.

Onset HOBO temperature sensor id

Description

Onset HOBO temperature sensor id

Usage

mc_const_SENSOR_HOBO_T

Format

An object of classcharacter of length 1.

Relative humidity sensor id

Description

Relative humidity sensor id

Usage

mc_const_SENSOR_RH

Format

An object of classcharacter of length 1.

Default sensor for TOMST TMS soil temperature

Description

This constant is used in the functionmc_calc_vwc to account for soil temperature effectwhile converting the raw TMS soil moisture (scaled TDT signal) to volumetric water content (VWC).mc_const_SENSOR_TMS_T1 = "TMS_T1"

Usage

mc_const_SENSOR_TMS_T1

Format

An object of classcharacter of length 1.

Default sensor for TOMST TMS temperature of soil surface

Description

Default sensor for TOMST TMS temperature of soil surface

Usage

mc_const_SENSOR_TMS_T2

Format

An object of classcharacter of length 1.

Default sensor for TOMST TMS air temperature

Description

Default sensor for TOMST TMS air temperature

Usage

mc_const_SENSOR_TMS_T3

Format

An object of classcharacter of length 1.

Default sensor for TOMST TMS raw soil moisture

Description

This constant is used in the functionmc_calc_vwc as default for sensor forconverting the raw TMS soil moisture (scaled TDT signal) to volumetric water content (VWC).mc_const_SENSOR_TMS_moist = "TMS_moist"

Usage

mc_const_SENSOR_TMS_moist

Format

An object of classcharacter of length 1.

Temperature sensor id

Description

Temperature sensor id

Usage

mc_const_SENSOR_T_C

Format

An object of classcharacter of length 1.

Default sensor for TOMST Thermologger temperature

Description

Default sensor for TOMST Thermologger temperature

Usage

mc_const_SENSOR_Thermo_T

Format

An object of classcharacter of length 1.

Vapor Pressure Deficit sensor id seemc_calc_vpd()

Description

Vapor Pressure Deficit sensor id seemc_calc_vpd()

Usage

mc_const_SENSOR_VPD

Format

An object of classcharacter of length 1.

Volumetric soil moisture sensor id seemc_calc_vwc()

Description

Volumetric soil moisture sensor id seemc_calc_vwc()

Usage

mc_const_SENSOR_VWC

Format

An object of classcharacter of length 1.

Count sensor id seemc_agg()

Description

Count sensor id seemc_agg()

Usage

mc_const_SENSOR_count

Format

An object of classcharacter of length 1.

Coverage sensor id seemc_agg()

Description

Coverage sensor id seemc_agg()

Usage

mc_const_SENSOR_coverage

Format

An object of classcharacter of length 1.

Radius difference sensor id

Description

Radius difference sensor id

Usage

mc_const_SENSOR_dendro_l_um

Format

An object of classcharacter of length 1.

General integer sensor id

Description

General integer sensor id

Usage

mc_const_SENSOR_integer

Format

An object of classcharacter of length 1.

General logical sensor id

Description

General logical sensor id

Usage

mc_const_SENSOR_logical

Format

An object of classcharacter of length 1.

Precipitation sensor id

Description

Precipitation sensor id

Usage

mc_const_SENSOR_precipitation

Format

An object of classcharacter of length 1.

General real sensor id

Description

General real sensor id

Usage

mc_const_SENSOR_real

Format

An object of classcharacter of length 1.

Snow existence sensor id seemc_calc_snow()

Description

Snow existence sensor id seemc_calc_snow()

Usage

mc_const_SENSOR_snow_bool

Format

An object of classcharacter of length 1.

Height of newly fallen snow sensor id

Description

Height of newly fallen snow sensor id

Usage

mc_const_SENSOR_snow_fresh

Format

An object of classcharacter of length 1.

Height snow sensor id

Description

Height snow sensor id

Usage

mc_const_SENSOR_snow_total

Format

An object of classcharacter of length 1.

Time of sun shine sensor id

Description

Time of sun shine sensor id

Usage

mc_const_SENSOR_sun_shine

Format

An object of classcharacter of length 1.

Speed of wind sensor id

Description

Speed of wind sensor id

Usage

mc_const_SENSOR_wind_speed

Format

An object of classcharacter of length 1.

Example data in Agg-format.

Description

Cleaned data in Agg-format. Three example localities situated inSaxon Switzerland National Park.myClim object has metadata and covers time period from 2020-10 to 2021-02.

Data includes time-series from 4 loggers:

• Tomst TMS4 with 4 sensors ("TMS_T1", "TMS_T2", "TMS_T3", "TMS_moist")

• Tomst Thermologger with 1 sensor ("Thermo_T)

• Tomst Point Dendrometer with 2 sensors ("Dendro_T", "Dendro_raw")

• HOBO U23 with 2 sensors ("HOBO_T", "HOBO_RH")

Usage

mc_data_example_agg

Format

An object of classmyClimList (inherits fromlist) of length 2.

Example cleaned data in Raw-format.

Description

Cleaned data. Three example localities situated in Saxon Switzerland National Park.myClim object has metadata and covers time period from 2020-10 to 2021-02.

Data includes time-series from 4 loggers:

• Tomst TMS4 with 4 sensors ("TMS_T1", "TMS_T2", "TMS_T3", "TMS_moist")

• Tomst Thermologger with 1 sensor ("Thermo_T)

• Tomst Point Dendrometer with 2 sensors ("Dendro_T", "Dendro_raw")

• HOBO U23 with 2 sensors ("HOBO_T", "HOBO_RH")

Usage

mc_data_example_clean

Format

An object of classmyClimList (inherits fromlist) of length 2.

Example data in Raw-format

Description

Raw data, not cleaned. Three example localities situatedin Saxon Switzerland National Park.myClim object has metadata and covers time period from 2020-10 to 2021-02.

Data includes time-series from 4 loggers:

• Tomst TMS4 with 4 sensors ("TMS_T1", "TMS_T2", "TMS_T3", "TMS_moist")

• Tomst Thermologger with 1 sensor ("Thermo_T)

• Tomst Point Dendrometer with 2 sensors ("Dendro_T", "Dendro_raw")

• HOBO U23 with 2 sensors ("HOBO_T", "HOBO_RH")

Usage

mc_data_example_raw

Format

An object of classmyClimList (inherits fromlist) of length 2.

Formats of source data files

Description

R object of class environment with the definitions how toparse specific microclimatic logger files. In case you would like to addnew, unsupported logger, this is the place where the reading key is stored.

Usage

mc_data_formats

Format

An object of classenvironment of length 3.

Details

Package myClim support formats TOMST, TOMST_join and HOBO.The environment object is stored in./data/mc_data_formats.rda.

TOMST

TOMST data format has defined structure. Expected name of data file is in format data_\<serial_number\>_\<x\>.csv.Value serial_number can be automatically detected from file name.Datetime is in UTC and is stored in col 2. Temperature values are stored in col 3-5. Moisture ()Supported logger types are TMS (for TMS-3/TMS-4), ThermoDataLogger (for Thermologger), Dendrometer and TMS_L45 (for TMS-4 Long 45cm).

TOMST_join

TOMST_join data format is used by output files from JoinTMS.exe software and from tupomanager.exe (TMS-1).Datetime in col 4, temperatures in col 5-7, moisture in col 8.

HOBO

HOBO data format is export format from software HOBOware of Onset company for HOBO U23 Pro v2 loggers (Temperature/RH).Format is very variable and can be adjusted by user in preferences of HOBOware. Strucuture of HOBO files format can be partlydetected automatically from header of data.Format of date-time (date_format) must be set manually in myClim reading functions (mc_read_files(),mc_read_data()).Date and time separated in more columns is not supported in myClim reading. If time zone is not defined in header of HOBO txt or csv fileand is not UTC, thentz_offset must be filled in while reading. UTF-8 encoding of HOBO file is required for reding to myClim.

See Also

mc_DataFormat,mc_TOMSTDataFormat,mc_TOMSTJoinDataFormat,mc_HOBODataFormat

Default heights of sensors

Description

This table is used to set the default heights in metadata of sensors based on logger type.The defaults were set based on the most common uses,defaults can be overwrite be user. seemc_prep_meta_sensor

Usage

mc_data_heights

Format

An object of classdata.frame with 15 rows and 4 columns.

Details

data.frame with columns:

• logger_type

• sensor_name

• height - character representation of height

• suffix - suffix for sensor_name. If suffix is NA, then sensor_name is not modified.

Default heights are:

TOMST - Thermo

• Thermo_T = air 200 cm

TOMST - TMS

• TMS_T1 = soil 8 cm

• TMS_T2 = air 2 cm

• TMS_T3 = air 15 cm

• TMS_moist = soil 0-15 cm

TOMST - Dendro

• Dendro_T = 130 cm

• Dendro_raw = 130 cm

TOMST - TMS_L45

• TMS_T1 = soil 40 cm

• TMS_T2 = soil 30 cm

• TMS_T3 = air 15 cm

• TMS_moist = soil 30-44 cm

HOBO - HOBO_U23-001A

• HOBO_T = air 150 cm

• HOBO_RH = air 150 cm

HOBO - HOBO_U23-004

• HOBO_T = air 2 cm

• HOBO_extT = soil 8 cm

See Also

mc_read_files(),mc_read_data()

Physical quantities definition

Description

R object of class environment with the definitions of physical elementsfor recording the microclimate e.g. temperature, speed, depth, volumetric water content...seemc_Physical. Similarly as in case of logger format definitionsmc_DataFormat it is easyto add new, physical here.

Usage

mc_data_physical

Format

An object of classenvironment of length 11.

See Also

mc_Physical

Currently supported physical elements:

• l_cm - length in cm

• l_mm - length in mm

• l_um - length in um

• VWC - volumetric moisture in m3/m3

• RH - relative humidity in %

• T_C - temperature in °C

• t_h - time in hours

• moisture_raw - raw TMS moisture sensor values

• radius_raw - radius difference in raw units

• v - speed in m/s

Sensors definition.

Description

R object of class environment with the definitions of (micro)climatic sensors.seemc_Sensor. Similarly as in case of logger format definitionsmc_DataFormat it is easyto add new, sensor here. There is also universal sensorreal where you can store any real values.

Usage

mc_data_sensors

Format

An object of classenvironment of length 28.

Details

Names of items are sensor_ids.Currently supported sensors:

• count - result ofcount functionmc_agg()

• coverage - result ofcoverage functionmc_agg()

• Dendro_T - temperature in Tomst dendrometer (°C)

• Dendro_raw - change in stem size in Tomst dendrometer (raw units)mc_calc_tomst_dendro()

• dendro_l_um - change in stem size (um)mc_calc_tomst_dendro()

• FDD - result of functionmc_calc_fdd()

• GDD - result of functionmc_calc_gdd()

• HOBO_RH - relative humidity in HOBO U23-001A logger (%)

• HOBO_T - temperature in HOBO U23 logger (°C)

• HOBO_extT - external temperature in HOBO U23-004 logger (°C)

• integer - universal sensor with integer values

• logical - universal sensor with logical values

• VWC - volumetric water content in soil (m3/m3)

• precipitation - (mm)

• real - universal sensor with real values

• RH - relative humidity sensor (%)

• snow_bool - result of functionmc_calc_snow()

• snow_fresh - fresh snow height (cm)

• snow_total - total snow height (cm)

• sun_shine - time of sun shine (hours)

• T_C - universal temperature sensor (°C)

• Thermo_T - temperature sensor in Tomst Thermologger (°C)

• TMS_T1 - soil temperature sensor in Tomst TMS (°C)

• TMS_T2 - surface temperature sensor in Tomst TMS (°C)

• TMS_T3 - air temperature sensor in Tomst TMS (°C)

• TMS_moist - soil moisture sensor in Tomst TMS (raw TMS units)

• wind - wind speed (m/s)

Volumetric water content parameters

Description

Data frame hosting the coefficients for the conversion of TMS raw moisture units tovolumetric warer content. The coefficients come from laboratory calibration for severalsoil types. For the best performance you should specify the soil type in case you know itand in case it could be approximated to the available calibration e.g sand, loam, loamy sand....Seemc_calc_vwc()

Usage

mc_data_vwc_parameters

Format

An object of classdata.frame with 13 rows and 9 columns.

Details

data.frame with columns:

• soiltype

• a

• b

• c

• rho

• clay

• silt

• sand

• ref

References

Wild, J., Kopecky, M., Macek, M., Sanda, M., Jankovec, J., Haase, T., 2019. Climate at ecologically relevant scales:A new temperature and soil moisture logger for long-term microclimate measurement. Agric. For. Meteorol. 268, 40-47.https://doi.org/10.1016/j.agrformet.2018.12.018

Kopecky, M., Macek, M., Wild, J., 2021. Topographic Wetness Index calculation guidelines based on measured soilmoisture and plant species composition. Sci. Total Environ. 757, 143785. https://doi.org/10.1016/j.scitotenv.2020.143785

Standardised myClim soil moisture variables

Description

The wrapper function returning 4 standardised and ecologically relevant myClim variablesderived from soil moisture measurements. The mc_env_moist function needs time-series ofvolumetric water content (VWC) measurements as input. Therefore, non-VWC soilmoisture measurements must be first converted to VWC.For TMS loggers seemc_calc_vwc()

Usage

mc_env_moist(  data,  period,  use_utc = TRUE,  custom_start = NULL,  custom_end = NULL,  min_coverage = 1)

Arguments

Details

This function was designed for time-series of step shorter than oneday and will not work with coarser data. In contrast with other myClim functionsreturning myClim objects, this wrapper function returns long table.Variables are named based on sensor name, height, and function e.g.,(VWC.soil_0_15_cm.5p, VWC.soil_0_15_cm.mean)

Standardised myClim soil moisture variables:

• VWC.5p: Minimum soil moisture = 5th percentile of VWC values

• VWC.mean: Mean soil moisture = mean of VWC values

• VWC.95p: Maximum soil moisture = 95th percentile of VWC values

• VWC.sd: Standard deviation of VWC measurements

Value

table in long format with standardised myClim variables

Examples

data <- mc_prep_crop(mc_data_example_agg, lubridate::ymd_h("2020-11-01 00"),                     lubridate::ymd_h("2021-02-01 00"), end_included = FALSE)data <- mc_calc_vwc(data, localities=c("A2E32", "A6W79"))mc_env_moist(data, "month")

Standardised myClim temperature variables

Description

The wrapper function returning 7 standardised and ecologically relevant myClim variablesderived from temperature measurements.

Usage

mc_env_temp(  data,  period,  use_utc = TRUE,  custom_start = NULL,  custom_end = NULL,  min_coverage = 1,  gdd_t_base = 5,  fdd_t_base = 0)

Arguments

Details

This function was designed for time-series of step shorter than oneday and will not work with coarser data. It automatically use allavailable sensors in myClim object and returns all possible variables basedon sensor type and measurement height/depth. In contrast with other myClim functionsreturning myClim objects, this wrapper function returns long table.The mc_env_temp function first aggregates time-series to daily time-stepand then aggregates to the final time-step set inperiod parameter.Because freezing and growing degree days are always aggregated with sum function,these two variables are not first aggregated to the daily time-steps.Variables are named based on sensor name, height, and function e.g.,(T.air_15_cm.max95p, T.air_15_cm.drange)

Standardised myClim temperature variables:

• min5p: Minimum temperature = 5th percentile of daily minimum temperatures

• mean: Mean temperature = mean of daily mean temperatures

• max95p: Maximum temperature = 95th percentile of daily maximum temperatures

• drange: Temperature range = mean of daily temperature range (i.e., difference between daily minima and maxima)

• GDD5: Growing degree days = sum of growing degree days above defined base temperature (default 5°C)gdd_t_base

• FDD0: Freezing degree days = sum of freezing degree days bellow defined base temperature (default 0°C)fdd_t_base

• frostdays: Frost days = number of days with frost (daily minimum < 0°C)fdd_t_base

Value

table in long format with standardised myClim variables

Examples

data <- mc_prep_crop(mc_data_example_clean, lubridate::ymd_h("2020-11-01 00"),                     lubridate::ymd_h("2021-02-01 00"), end_included = FALSE)mc_env_temp(data, "month")

Standardised myClim vapor pressure deficit variables

Description

The wrapper function returning 2 standardised and ecologically relevant myClim variablesderived from vapor pressure deficit. The mc_env_vpd function needs time-series ofvapor pressure deficit measurements as input. Therefore, VPD must be first calculatedfrom temperature and air humidity measurements - seemc_calc_vpd()

Usage

mc_env_vpd(  data,  period,  use_utc = TRUE,  custom_start = NULL,  custom_end = NULL,  min_coverage = 1)

Arguments

Details

This function was designed for time-series of step shorter than oneday and will not work with coarser data. The mc_env_vpd functionfirst aggregates time-series to daily time-stepand then aggregates to the final time-step set inperiod parameter.In contrast with other myClim functionsreturning myClim objects, this wrapper function returns long table.Variables are named based on sensor name, height, and function e.g.,(VPD.air_150_cm.mean, VPD.air_150_cm.max95p)

Standardised myClim vapor pressure deficit variables:

• VPD.mean: Mean vapor pressure deficit = mean of daily mean VPD

• VPD.max95p: Maximum vapor pressure deficit = 95th percentile of daily maximum VPD

Value

table in long format with standardised myClim variables

Filter data from myClim object

Description

This function filter data by localities, logger types and sensors.

Usage

mc_filter(  data,  localities = NULL,  logger_types = NULL,  loggers = NULL,  sensors = NULL,  reverse = FALSE,  stop_if_empty = TRUE)

Arguments

Details

In default settings it returns the object containing input localities / logger types / loggers / sensors.When you provide vector of localities e.g.localities=c("A6W79", "A2E32")selected localities are filtered with all loggers / sensors on those localities.When you provide vector of loggers e.g.loggers=c("TMS_1", "TMS_2")selected loggers are filtered through all localities.The same as When you provide vector of logger_typeslogger_types=c("TMS", "TMS_L45")selected loggers by type are filtered through all localities.(loggers or logger_types criterion is applicable only for raw data format seemyClim-package) andthe sensors parametersensors=c("TMS_T1", "TMS_T2"),selected sensors are filtered through all localities.When you combine localities, logger_types/loggers and sensors, then filtering returnselected sensors in selected loggers on selected localities.

Parameterreverse = TRUE returns myClim object complemented to object filtered by parameterreverse = FALSE.

• reverse = TRUE andlocalities are selected then the listed localities are removed from myClim object.

• reverse = TRUE andloggers are selected then the listed loggers are removed from all localities.

• reverse = TRUE andlogger_types are selected then the listed logger types are removed from all localities.

• reverse = TRUE andsensors are selected then listed sensors are removed from all loggers / localities.

• reverse = TRUE andlocalities andloggers are selected then the listed loggers are removed only from listed localities.

Only one of parameters loggers or logger_types can be used.

Value

filtered myClim object

Examples

## keep only "A6W79", "A2E32" localities with all their sensorsfiltered_data <- mc_filter(mc_data_example_raw, localities=c("A6W79", "A2E32"))## remove "A6W79", "A2E32" localities and keep all othersfiltered_data <- mc_filter(mc_data_example_raw, localities=c("A6W79", "A2E32"), reverse=TRUE)## keep only "TMS_T1", and "TMS_T2" sensors on all localitiesfiltered_data <- mc_filter(mc_data_example_raw, sensors=c("TMS_T1", "TMS_T2"))## remove "TMS_T1", and "TMS_T2" sensors from all localitiesfiltered_data <- mc_filter(mc_data_example_raw, sensors=c("TMS_T1", "TMS_T2"),reverse=TRUE)## keep only "TMS_T1", and "TMS_T2" sensors on "A6W79", "A2E32" localitiesfiltered_data <- mc_filter(mc_data_example_raw, localities=c("A6W79", "A2E32"),                           sensors=c("TMS_T1", "TMS_T2"))## Remove "Dendro" loggers on all localitiesfiltered_data <- mc_filter(mc_data_example_raw, logger_types="Dendro", reverse=TRUE)

Get sensors info table

Description

This function return data.frame with info about sensors

Usage

mc_info(data)

Arguments

Value

data.frame with columns:

• locality_id - when provided by user then locality ID, when not provided identical with serial number

• serial_number - serial number of logger when provided or automatically detected from file name or header

• sensor_id - original sensor id (e.g.,"GDD", "HOBO_T" ,"TMS_T1", "TMS_T2")

• sensor_name - original sensor id if not modified, if renamed then new name (e.g.,"GDD5", "HOBO_T_mean" ,"TMS_T1_max", "my_sensor01")

• start_date - the oldest record on the sensor

• end_date - the newest record on the sensor

• step_seconds - time step of records series (seconds)

• period - time step of records series (text)

• min_value - minimal recorded values

• max_value - maximal recorded value

• count_values - number of non NA records

• count_na - number of NA records

• height - height description of sensor

• calibrated - logical value indicating whether the sensor is calibrated

Examples

mc_info(mc_data_example_agg)

Get calibration info table

Description

This function return data.frame with calibration parameter of sensors loaded bymc_prep_calib_load().

Usage

mc_info_calib(data)

Arguments

Value

data.frame with columns:

• locality_id - when provided by user then locality ID, when not provided identical with serial number

• logger_name - name of logger in myClim object at the locality (e.g., "Thermo_1", "TMS_2")

• sensor_name - sensor name either original (e.g., TMS_T1, T_C), or calculated/renamed (e.g., "TMS_T1_max", "my_sensor01")

• datetime - date and time of calibration

• cor_factor - correction factor applied to the sensor values

• cor_slope - the slope of calibration curve

Examples

mc_info_calib(mc_data_example_clean)

Call cleaning log

Description

This function return data.frame with information from cleaning the loggers time series seemc_prep_clean()

Usage

mc_info_clean(data)

Arguments

Value

data.frame with columns:

• locality_id - when provided by user then locality ID, when not provided identical with serial number

• logger_name - Logger name at the locality.

• serial_number - serial number of logger when provided or automatically detected from file name or header

• start_date - date of the first record on the logger

• end_date - date of the last record on the logger

• step_seconds - detected time step in seconds of the logger measurements.

• count_duplicities - number of duplicated records (identical time)

• count_missing - number of missing records (logger outage in time when it should record)

• count_disordered - number of records incorrectly ordered in time (newer followed by older)

• rounded - T/F indication whether myClim automatically rounded time series minutes to the closes half (HH:00, HH:30) e.g. 13:07 -> 13:00

See Also

mc_prep_clean()

Count data

Description

This function return data.frame with the number of localities, loggers and sensors of input myClim object.

Usage

mc_info_count(data)

Arguments

Value

data.frame with count of localities, loggers and sensors

Examples

count_table <- mc_info_count(mc_data_example_raw)

Get loggers info table

Description

This function returns a data.frame with information about loggers.

Usage

mc_info_logger(data)

Arguments

Details

This function is designed to work only withmyClim objects inRaw-format, where the loggers are organized at localities.InAgg-format, myClim objects do not support loggers; sensors are directly connected to the locality.SeemyClim-package.mc_info_logger does not work in Agg-format.

Value

A data.frame with the following columns:

• locality_id - If provided by the user, it represents the locality ID; if not provided, it is identical to the logger's serial number.

• logger_name - Logger name.

• serial_number - Serial number of the logger, either provided by the user or automatically detected from the file name or header.

• logger_type - Logger type.

• start_date - The oldest record on the logger.

• end_date - The newest record on the logger.

• step_seconds - Time step of the record series (in seconds).

Examples

mc_info_logger(mc_data_example_raw)

Get localities metadata table

Description

This function return data.frame with localities metadata

Usage

mc_info_meta(data)

Arguments

Value

data.frame with columns:

• locality_id

• lon_wgs84

• lat_wgs84

• elevation

• tz_offset

Examples

mc_info_meta(mc_data_example_agg)

Get table of sensors range

Description

This function return data.frame with sensors range (min value, max value) and possible jumps.

Usage

mc_info_range(data)

Arguments

Details

This function is mainly useful to prepare input parameter formc_states_outlier() function.The range values are taken frommc_data_sensors. Those are manually definedranges based on logger/sensor technical limits and biologically meaningful values.

Value

data.frame with columns:

• sensor_name - name of sensor (e.g., TMS_T1, TMS_moist, HOBO_T) seemc_data_sensors

• min_value - minimal value

• max_value - maximal value

• positive_jump - Maximal difference between two consecutive values. Next value is higher than previous. (Positive number)

• negative_jump - Maximal difference between two consecutive values. Next value is lower than previous. (Positive number)

Examples

mc_info_range(mc_data_example_raw)

Get states (tags) info table

Description

This function return data.frame with information about sensor states (tags) seemyClim-package

Usage

mc_info_states(data)

Arguments

Details

This function is useful not only for inspecting actual states (tags) but also asa template for manually manipulating states (tags) in a table editor such as Excel.The output ofmc_info_states() can be saved as a table, adjusted outside R (adding/removing/modifying rows),and then read back into R to be used as input formc_states_insert ormc_states_update.

Value

data.frame with columns:

• locality_id - when provided by user then locality ID, when not provided identical with serial number

• logger_name - name of logger in myClim object at the locality (e.g., "Thermo_1", "TMS_2")

• sensor_name - sensor name either original (e.g., TMS_T1, T_C), or calculated/renamed (e.g., "TMS_T1_max", "my_sensor01")

• tag - category of state (e.g., "error", "source", "quality")

• start - start datetime

• end - end datetime

• value - value of tag (e.g., "out of soil", "c:/users/John/tmsData/data_911235678.csv")

Examples

mc_info_states(mc_data_example_raw)

Joining time-series from repeated downloads

Description

The function is designed to merge time-series data obtained throughrepeated downloads in the same location. Within a specific locality,the function performs the merging based on 1) logger type,physical element, and sensor height, or 2) based on the list of loggerserial numbers to be joined, provided by user in locality metadata.

Usage

mc_join(data, comp_sensors = NULL, by_type = TRUE, tolerance = NULL)

Arguments

Details

Joining is restricted to the myClim Raw-format (refer tomyClim-package).Loggers need to be organized within localities. The simplest method is to usemc_read_data,providingfiles_table with locality IDs. When usingmc_read_fileswithout metadata, a bit more coding is needed. In this case, you can createmultiple myClim objects and specify correct locality names afterwards,then merge these objects usingmc_prep_merge, which groups loggersbased on identical locality names.

The joining function operates seamlessly without user interventionin two scenarios:

1. when the start of a newer time series aligns with the end of an older one, and

2. when the two time-series share identical values during the overlap.

However, if values differ during the overlap, the user is prompted tointeractively choose which time-series to retain and which to discard.myClim provides information about differing time-series in the console,including locality ID, problematic interval (start-end),older logger ID and its time series start-end, and newer logger ID andits time series start-end. Additionally, an interactive graphicalwindow (plotly) displays conflicting time series, allowing the user tozoom in and explore values. In case of multiple conflicts, myClimsequentially asks the user for decisions.

Users have seven options for handling overlap conflicts, six of which are pre-defined.The seventh option allows the user to specify the exact timeto trim the older time-series and use the newer one. The options include:

• 1: using the older logger (to resolve this conflict),

• 2: using the newer logger (to resolve this conflict),

• 3: skip this join (same type loggers in locality aren't joined),

• 4: always using the older logger (to resolve this and all other conflicts),

• 5: always using the newer logger (to resolve this and all other conflicts)

• 6: exit joining process.

Users must press the number key, hit Return/Enter,or write in console the exact date in the format⁠YYYY-MM-DD hh:mm⁠to trim the older series and continue with the newer series.

by_type = TRUE (default)Loggers are joined based on logger type, physical element,and sensor height. This is a good option for the localities,were are NOT more loggers of identical type and height recording simultaneously.

by_type = FALSELoggers are joined based on the list of logger_serial belonging to each locality.User must specify in locality metadata, which logger serials are joined together.This is a good option for the localities, with more loggers of identical type andheight measuring simultaneously.

Loggers with multiple sensors are joined based on one ormore selected sensors (see parameter comp_sensors).The name of the resulting joined sensor is taken from the logger withthe oldest data. If serial_number is not equal during logger joining,the resulting serial_number is NA. Clean info is changed to NA exceptfor the step. When joining a non-calibrated sensor with a calibrated one,the calibration information must be empty in the non-calibrated sensor.

Thetolerance parameter can be used for cases, when joining multipletime-series which is "almost" identical, and the difference is causede.g. by logger precision or resolution.

For example of joining seemyClim vignette.

Value

myClim object with joined loggers.

Load myClim object

Description

This function loads the myClim .rds data object saved withmc_save.Themc_save andmc_load functions secure that the myClim object is correctlyloaded across myClim versions.

Usage

mc_load(file)

Arguments

Value

loaded myClim object

Examples

tmp_dir <- tempdir()tmp_file <- tempfile(tmpdir = tmp_dir)mc_save(mc_data_example_agg, tmp_file)data <- mc_load(tmp_file)file.remove(tmp_file)

Plot data - image

Description

Function plots single sensor form myClim data into PNG file with image() R base function.This was designed for fast, and easy data visualization especially focusing on missingvalues visualization and general data picture.

Usage

mc_plot_image(  data,  filename,  title = "",  localities = NULL,  sensors = NULL,  height = 1900,  left_margin = 12,  use_utc = TRUE)

Arguments

Details

Be careful with bigger data. Can take some time.

Value

PNG file created as specified in output file name

Examples

tmp_dir <- tempdir()tmp_file <- tempfile(tmpdir = tmp_dir)mc_plot_image(mc_data_example_clean, tmp_file, "T1 sensor", sensors="TMS_T1")file.remove(tmp_file)

Plot data - ggplot2 geom_line

Description

Function plots data with ggplot2 geom_line. Plot is returned as ggplot faced grid andis optimized for saving as facet, paginated PDF file.

Usage

mc_plot_line(  data,  filename = NULL,  sensors = NULL,  scale_coeff = NULL,  png_width = 1900,  png_height = 1900,  start_crop = NULL,  end_crop = NULL,  use_utc = TRUE,  localities = NULL,  facet = "locality",  color_by_logger = FALSE,  tag = NULL)

Arguments

Details

Saving as the PDF file is recommended, because the plot is optimizedto be paginate PDF (facet line plot is distributed to pages), each locality can berepresented by separate plot (facet = "locality") default, which is especially usefulfor bigger data. Whenfacet = NULL then single plot is returned showing all localities together.Whenfacet = physical sensors with identical physical units are grouped together across localities.Maximal number of physical units (elements) of sensors to be plotted in oneplot is two. First element is related to primary and second to secondary y axis.In case, there are multiple sensors with identical physical on one locality,they are plotted together forfacet = "locality" e.g., when you haveTMS_T1, TMS_T2, TMS_T3, Thermo_T, and VWC you get plot with 5 lines of different colors andtwo y axes. Secondary y axes are scaled with calculationvalues * scale_coeff.If scaling coefficient is NULL than function try to detects scale coefficient fromphysical unit of sensors seemc_Physical. Scaling is useful whenplotting together e.g. temperature and moisture. For native myClim loggers(TOMST, HOBO U-23) scaling coefficients are pre-defined.For other cases when plotting two physicals together,it is better to set scaling coefficients by hand.

Value

ggplot2 object

Examples

tms.plot <- mc_filter(mc_data_example_agg, localities = "A6W79")p <- mc_plot_line(tms.plot,sensors = c("TMS_T3","TMS_T1","TMS_moist"))p <- p+ggplot2::scale_x_datetime(date_breaks = "1 week", date_labels = "%W")p <- p+ggplot2::xlab("week")p <- p+ggplot2::scale_color_manual(values=c("hotpink","pink", "darkblue"),name=NULL)

Plot data from loggers

Description

Function save separate files (*.png) per the loggers to the directory.Only Raw-format supported, Agg-format not supported.For Agg-format usemc_plot_line(). Function was primary designedfor Tomst TMS loggers for fast, and easy data visualization.

Usage

mc_plot_loggers(  data,  directory,  localities = NULL,  sensors = NULL,  crop = c(NA, NA))

Arguments

Value

PNG files created in the output directory

Examples

tmp_dir <- file.path(tempdir(), "plot")mc_plot_loggers(mc_data_example_clean, tmp_dir)unlink(tmp_dir, recursive=TRUE)

Plot data - ggplot2 geom_raster

Description

Function plots data with ggplot2 geom_raster. Plot is returned as ggplot faced raster andis primary designed to be saved as .pdf file (recommended) or .png file.Plotting into R environment without saving any file is also possible.See details.

Usage

mc_plot_raster(  data,  filename = NULL,  sensors = NULL,  by_hour = TRUE,  png_width = 1900,  png_height = 1900,  viridis_color_map = NULL,  start_crop = NULL,  end_crop = NULL,  use_utc = TRUE)

Arguments

Details

Saving as the .pdf file is recommended, because the plot is optimizedto be paginate PDF (facet raster plot is distributed to pages), which is especially usefulfor bigger data. In case of plotting multiple sensors to PDF, the facet grids are grouped by sensor.I.e., all localities of sensor_1 followed by all localities of sensor_2 etc.When plotting only few localities, but multiple sensors,each sensor has own page. I.e., when plotting data from one locality, and 3 sensors resulting PDF has 3 pages.In case of plotting PNG, sensors are plotted in separated images (PNG files) by physical.I.e, when plotting 3 sensors in PNG it will save 3 PNG files named after sensors.Be careful with bigger data in PNG. Play withpng_height andpng_width.When too small height/width, image does not fit and is plotted incorrectly. Plotting intoR environment instead of saving PDF or PNG is possible, but is recommended only forlow number of localities (e.g. up to 10), becausehigh number of localities plotted in R environment results in very small picture which is hard/impossible to read.

Value

list of ggplot2 objects

Examples

tmp_dir <- tempdir()tmp_file <- tempfile(tmpdir = tmp_dir, fileext=".pdf")mc_plot_raster(mc_data_example_agg, filename=tmp_file, sensors=c("TMS_T3","TM_T"))file.remove(tmp_file)

Detection of out-of-soil measurements from TMS logger

Description

This function creates new virtual sensor labelling anomalies in TMS logger caused by displacement out of from soil.

Usage

mc_prep_TMSoffsoil(  data,  localities = NULL,  soil_sensor = mc_const_SENSOR_TMS_T1,  air_sensor = mc_const_SENSOR_TMS_T2,  moist_sensor = mc_const_SENSOR_TMS_moist,  output_sensor = "off_soil",  smooth = FALSE,  smooth_window = 10,  smooth_threshold = 0.5,  sd_threshold = 0.76085,  minmoist_threshold = 721.5)

Arguments

Details

TMS loggers, when correctly installed in the soil, exhibit certain temperature and soil moisture signal characteristics.Temperature varies the most at the soil interface, and temperature fluctuations in the soil are minimized.The moisture signal from a sensor that has lost direct contact with the soil is reduced.The following criteria are used for detecting faulty measurements: the ratio of the standard deviations of the soilsensor to the above-ground sensor within 24h moving window is greater than the defined threshold (default 0.76085),and simultaneously, the soil moisture minimum within 24h mowing window is less than 721.5.Optionally, the prediction results can be smoothed using a floating window to average-out unlikely short periods detected by the algorithm.Selection and parametrization of criteria was done using a recursive partitioning (rpart::rpart)on the training set of 7.8M readings in 154 TMS timeseries from different environmental settings (temperate forests, tropical rainforest, cold desert, alpine and subnival zone,and invalid measurements from loggers stored in the office or displaced from the soil).Sensitivity of the method (true positive rate) on was 95.1% and specificity (true negative rate) was 99.4% using function default parameters.Smoothing with 10 day floating window increased sensitivity to 96.8% while retaining specifity at the same level of 99.4%.Decreasing 'smooth_threshold' below 0.5 will extend periods flagged as faulty measurement.

Value

numeric vector (0 = correct measurement, 1 = faulty measurement) stored as virtual sensor in myClim object

Examples

data <- mc_read_files(system.file("extdata", "data_93142760_201904.csv", package = "myClim"),                      "TOMST")data <- mc_prep_TMSoffsoil(data)mc_plot_line(data, sensors = c("off_soil","TMS_T1", "TMS_T2","TMS_T3"))

Sensors calibration

Description

This function calibrate values of sensor (microclimatic records) using themyClim objectsensor$calibration parameters provided bymc_prep_calib_load().Microclimatic records are changed and myClim object parametersensor$metadata@calibratedis set to TRUE. It isn't allowed to calibrate sensor multiple times.

Usage

mc_prep_calib(data, localities = NULL, sensors = NULL)

Arguments

Details

This function performs calibration itself. It uses the calibration values (cor_factor, cor_slope) storedin myClim object sensor metadata sensor calibration loaded withmc_prep_calib_load().As it is possible to have multiple calibration values for one sensor in time (re-calibration after some time)different calibration values can be applied based on the calibration time. Older microclimatic recordsthen first calibrationdatetime available are calibrated anyway (in case sensor was calibrated ex-post)with the first calibration parameters available.

This function is not designed for moisture_raw calibration(conversion to volumetric water content) for this usemc_calc_vwc()

Only sensors with real value type can be calibrated. seemc_data_sensors()

Value

same myClim object as input but with calibrated sensor values.

Load sensor calibration parameters to correct microclimatic records

Description

This function loads calibration parameters from data.framelogger_calib_tableand stores them in the myClim object metadata. This functiondoes not calibrate data. For calibration itself runmc_prep_calib()

Usage

mc_prep_calib_load(data, calib_table)

Arguments

Details

This function allows user to provide correction coefficientscor_factor andcor_slope for linear sensor calibration.Calibrated data have by default the form of linear function terms:

⁠calibrated value = original value * (cor_slope + 1) + cor_factor⁠

In case of one-point calibration,cor_factor can be estimated as:⁠cor_factor = reference value - sensor value⁠andcor_slope should be set to 0.This function loads sensor-specificcalibration coefficients fromcalib_table and stores them into myClim Raw-formatobject metadata. Thecalib_table is data.frame with 5 columns:

• serial_number = serial number of the logger

• sensor_id = name of sensor, e.g. "TMS_T1"

• datetime = the date of the calibration in POSIXct type

• cor_factor = the correction factor

• cor_slope = the slope of calibration curve (in case of one-point calibration, use cor_slope = 0)

It is not possible to change calibration parameters for already calibrated sensor.This prevents repeated calibrations. Oncemc_prep_calib() is called thenit is not allowed to provide new calibration data, neither run calibration again.

Value

myClim object with loaded calibration information in metadata.Microclimatic records are not calibrated, only ready for calibration.To calibrate records runmc_prep_calib()

Cleaning datetime series

Description

By default,mc_prep_clean runs automatically whenmc_read_files()ormc_read_data() are called.mc_prep_clean checks the time-seriesin the myClim object in Raw-format for missing, duplicated, and disordered records.The function can either directly regularize microclimatictime-series to a constant time-step, remove duplicated records, andfill missing values with NA (resolve_conflicts=TRUE); or it caninsert new states (tags) seemc_states_insert to highlight records with conflictsi.e. duplicated datetime but different measurement values (resolve_conflicts=FALSE)but not perform the cleaning itself. When there were no conflicts,cleaning is performed in both cases (⁠resolve_conflicts=TRUE or FALSE⁠) See details.

Usage

mc_prep_clean(data, silent = FALSE, resolve_conflicts = TRUE, tolerance = NULL)

Arguments

Details

The functionmc_prep_clean can be used in two different ways depending onthe parameterresolve_conflicts. Whenresolve_conflicts=TRUE, the functionperforms automatic cleaning and returns a cleaned myClim object. Whenresolve_conflicts=FALSE,and myClim object contains conflicts (rows with identical time, but different measured value),the function returns the original, uncleaned object with tags (states) seemc_states_inserthighlighting records with duplicated datetime but different measured values.When there were no conflicts, cleaning is performed in both cases (⁠resolve_conflicts=TRUE OR FALSE⁠)

Processing the data withmc_prep_clean and resolving the conflicts is a mandatory steprequired for further data handling in themyClim library.

This function guarantee that all time series are in chronological order,have regular time-step and no duplicated records.Functionmc_prep_clean use either time-step provided by user during data import withmc_read(used time-step is permanently stored in logger metadatamc_LoggerMetadata;or if time-step is not provided by the user (NA),than myClim automaticallydetects the time-step from input time series based on the last 100 records.In case of irregular time series, function returns warning and skip (does not read) the file.

In cases when the user provides a time-step during data import inmc_read functionsinstead of relying on automatic step detection, and the provided step does not correspondwith the actual records (i.e., the logger records data every 900 seconds but the userprovides a step of 3600 seconds), the myClim rounding routine consolidates multiplerecords into an identical datetime. The resulting value corresponds to the one closestto the provided step (i.e., in an original series like ...9:50, 10:05, 10:20, 10:35, 10:50, 11:05...,the new record would be 10:00, and the value will be taken from the original record at 10:05).This process generates numerous warnings inresolve_conflicts=TRUE and a multitude of tagsinresolve_conflicts=FALSE.

Thetolerance parameter is designed for situations where the logger does not perform optimally,but the user still needs to extract and analyze the data. In some cases, loggers may recordmultiple rows with identical timestamps but with slightly different microclimate values,due to the limitations of sensor resolution and precision.By using thetolerance parameter, myClim will automatically select one of these valuesand resolve the conflict without generating additional warnings. It is strongly recommendedto set thetolerance value based on the sensor's resolution and precision.

In case the time-step is regular, but is not nicely rounded, function roundsthe time series to the closest nice time and shifts original data.E.g., original records in 10 min regular step c(11:58, 12:08, 12:18, 12:28)are shifted to newly generated nice sequence c(12:00, 12:10, 12:20, 12:30).Note that microclimatic records are not modified but only shifted.Maximum allowed shift of time series is 30 minutes. For example, when the time-stepis 2h (e.g. 13:33, 15:33, 17:33), the measurement times are shifted to (13:30, 15:30, 17:30).When you have 2h time step and wish to go to the whole hour(13:33 -> 14:00, 15:33 -> 16:00) the only way is aggregation -usemc_agg(period="2 hours") command after data cleaning.

Value

• cleaned myClim object in Raw-format (default)resolve_conflicts=TRUE orresolve_conflicts=FALSE but no conflicts exist

• cleaning log is by default printed in console, but can be called also later bymc_info_clean()

• non cleaned myClim object in Raw-format with "clean_conflict" tagsresolve_conflicts=FALSE and conflicts exist

Examples

cleaned_data <- mc_prep_clean(mc_data_example_raw)

Crop datetime

Description

This function crops data by datetime

Usage

mc_prep_crop(  data,  start = NULL,  end = NULL,  localities = NULL,  end_included = TRUE,  crop_table = NULL)

Arguments

Details

Function is able to crop data fromstart toend but works alsowithstart only orend only. When onlystart is provided, then function crops onlythe beginning of the time-series and vice versa usingend.

For advanced cropping per individual locality and logger usecrop_table parameter.Crop_table is r data.frame containing columns:

• locality_id - e.g. Loc_A1

• logger_name - e.g. TMS_1 seemc_info_logger

• start - POSIXct datetime in UTC

• end - POSIXct datetime in UTC

Iflogger_name is NA, then all loggers at certain locality are cropped. The columnlogger_nameis ignored in agg-format. Thestart orend can be NA, then the data are not cropped.If thecrop_table is provided, thenstart,end andlocalities parameters must be NULL.

Theend_included parameter is used for specification, whether to return data which containsendtime or not. For example when cropping the data to rounded days, typically users use midnight.2023-06-15 00:00:00 UTC. But midnight is the last date of ending day and the sametime first date of the next day. This will create the last day of time-series containing single record (midnight).This can be confusing when user performs aggregation with such data (e.g. daily mean of single record per day, typically NA) sosometimes it is better to useend_included = FALSE excluding end record and crop at 2023-06-14 23:45:00 UTC (15 minutes records).

Value

cropped data in the same myClim format as input.

Examples

cropped_data <- mc_prep_crop(mc_data_example_clean, end=as.POSIXct("2020-02-01", tz="UTC"))

Delete values by index

Description

This function is used to delete values in uncleaned raw myClim object by index.

Usage

mc_prep_delete(data, index_table)

Arguments

Details

Uncleaned logger contains raw indexes in metadata⁠@raw_index⁠. This functiondelete values by index_table parameter. This table (data.frame) contains 3 columns:

• locality_id = id of locality

• logger_name = name of logger

• raw_index = index of the value to be deleted

This function is used for data checking and validating. Especially in caseswhen there are duplicated values for identical time step. This allows youto manually (visually) select values to be deleted and delete them by table.

Value

raw myClim data with deleted values.

Examples

index_table <- data.frame(locality_id = c("A1E05", "A1E05"),                          logger_name = c("Thermo_1", "Thermo_1"),                          raw_index = c(1, 2))data <- mc_prep_delete(mc_data_example_raw, index_table)

Expand time steps

Description

Expands (downscales) time steps in raw myClim objects, e.g. from 1 hour to 15 minutes.The original step must be a multiple of the new step (e.g. 15 → 5 minutes works,but 15 → 10 minutes does not).Newly created gaps in the expanded series are filled withNA.

Usage

mc_prep_expandtime(  data,  to_step,  localities = NULL,  loggers = NULL,  from_step = NULL)

Arguments

Details

Works only with raw myClim objects.Iffrom_step is specified, only loggers with this step are expanded;loggers with other steps remain unchanged.

Value

raw myClim data with expanded datetime.

Examples

mc_prep_expandtime(mc_data_example_clean, to_step = 300, localities = "A1E05", loggers = "Thermo_1")

Fill NA

Description

This function approximate NA (missing) values. It was designed to fillonly small gaps in microclimatic time-series therefore, the default maximumlength of the gap is 5 missing records and longer gaps are not filledOnly linear method is implemented fromzoo::na.approx function.

Usage

mc_prep_fillNA(  data,  localities = NULL,  sensors = NULL,  maxgap = 5,  method = "linear")

Arguments

Value

myClim object with filled NA values

Merge myClim objects

Description

This function is designed to merge more existing myClim objects into one.

Usage

mc_prep_merge(data_items)

Arguments

Details

This function works only when the input myClim objects have the same format(Raw-format, Agg-format) It is not possible to merge Raw wit Agg format.Identical time-step is required for Agg-format data.

When the merged myClim objects in Raw-format contains locality with same names (locality_id),than list of loggers are merged on the locality. Sensors with the same name does not matter here.Loggers with the same name within the locality are allowed in the Raw-format.

When the merged myClim objects in Agg-format contains locality with same names (locality_id).than the sensors are merged on the locality. Sensors with same names are renamed.

Value

merged myClim object in the same format as input objects

Examples

merged_data <- mc_prep_merge(list(mc_data_example_raw, mc_data_example_raw))

Set metadata of localities

Description

This function allows you to add or modify locality metadata includinglocality names. Seemc_LocalityMetadata.You can import metadata from named list or from data frame. See details.

Usage

mc_prep_meta_locality(data, values, param_name = NULL)

Arguments

Details

Locality metadata is critical e.g. for correctly handling time zones.By providing geographic coordinates in locality metadata, the user can later harmonize all data to the local solar time (midday) #' withmc_prep_solar_tz() or calculate temporal offset to the UTC base on local time-zone.Alternatively, the user can directly provide the offset (in minutes) for individual localities. This can be useful especiallyfor heterogeneous data sets containing various localities with loggers recording in local time. By providing temporal offset for #' each locality separately, you can unify the whole dataset to UTC.Note that when tz_offset is set manually, than tz_type is set to⁠user defined⁠.

For minor metadata modification it is practical to use named list in combinationwithparam_name specification. E.g. when you wish to modify only time zone offset,then setparam_name="tz_offset" and provide named list with locality name andoffset valuelist(A1E05=60).Similarly, you can modify other metadata slotsmc_LocalityMetadata.

For batch or generally more complex metadata modification you can provide data.framewith columns specifyinglocality_id and one of⁠new_locality_id, elevation, lat_wgs84, lon_wgs84, tz_offset⁠.Provide locality_id (name) and the value in column of metadata you wish to update.In case of using data.frame useparam_name = NULL

Value

myClim object in the same format as input, with updated metadata

Examples

data <- mc_prep_meta_locality(mc_data_example_raw, list(A1E05=60), param_name="tz_offset")

Set metadata of sensors

Description

This function allows you to modify sensor metadata including sensor name. Seemc_SensorMetadata

Usage

mc_prep_meta_sensor(  data,  values,  param_name,  localities = NULL,  logger_types = NULL)

Arguments

Value

myClim object in the same format as input, with updated sensor metadata

Examples

data <- mc_prep_meta_sensor(mc_data_example_raw, list(TMS_T1="my_TMS_T1"), param_name="name")

Set solar time offset against UTC time

Description

This function calculates the temporal offset between local solar time and UTC time zone.Calculation is based on geographic coordinates of each locality.Therefore, the function does not work when longitude coordinate is not provided.

Usage

mc_prep_solar_tz(data)

Arguments

Details

myClim assumes that the data are in UTC. To calculate temporal offset based on local solar time, this function requiresgeographic coordinates (at least longitude) to be provided in locality metadata slotlon_wgs84 (in decimal degrees).Geographic coordinates for each locality can be provided already during data reading, seemc_read_data(), or addedlater withmc_prep_meta_locality() function.

TZ offset (in minutes) is calculated aslongitude / 180 * 12 * 60.

Value

myClim object in the same format as input, withtz_offset filled in locality metadata

Examples

data_solar <- mc_prep_solar_tz(mc_data_example_clean)

Reading files with locality metadata

Description

This function has two tables as the parameters.

(i)files_table is required parameter, it ust containpaths pointing to rawcsv logger files, specification ofdata format (logger type) andlocality name.

(ii)localities_table is optional, containinglocality id and metadata e.g. longitude, latitude, elevation...

Usage

mc_read_data(  files_table,  localities_table = NULL,  clean = TRUE,  silent = FALSE,  user_data_formats = NULL)

Arguments

Details

The input tables could be R data.frames or csv files. When loadingfiles_tableandlocalities_table from external CSV they must have header, column separator must be comma ",".If you only need to place loggers to correct localities,files_table is enough.If you wish to provide localities additional metadata, you need alsolocalities_table

By default, data are cleaned with the functionmc_prep_clean see function description.mc_prep_clean detects gaps in time-series data,duplicated records, or records in the wrong order. Importantly,mc_prep_cleanalso applies astep parameter if provided. The step parameter can be used eitherinstead of automatic step detection which can sometime failed, or to prunemicroclimatic data. For example, if you have a 15-minute time series but you wish tokeep only one record per hour (without aggregating), you can use step parameter.However, if a step is provided andclean = FALSE, then the step is only stored in themetadata of myClim, and the time-series data is not cleaned, and the step is not applied.

Value

myClim object in Raw-format seemyClim-package

See Also

mc_DataFormat

Examples

files_csv <- system.file("extdata", "files_table.csv", package = "myClim")localities_csv <- system.file("extdata", "localities_table.csv", package = "myClim")tomst_data <- mc_read_data(files_csv, localities_csv)

Reading files or directories

Description

This function read one or more CSV/TXT files or directories of identical,pre-defined logger type (format) seemc_DataFormat andmc_data_formats.This function does not support loading locality or sensor metadata while reading.Metadata can be loaded throughmc_read_data() orcan be provided later with functionmc_prep_meta_locality()

Usage

mc_read_files(  paths,  dataformat_name,  logger_type = NA_character_,  recursive = TRUE,  date_format = NA_character_,  tz_offset = NA_integer_,  step = NA_integer_,  clean = TRUE,  silent = FALSE,  user_data_formats = NULL)

Arguments

Details

If file is not in expected format, then file is skipped and warning printed in console.CSV/TXT files (loggers raw data) are in resulting myClim object placed to separatelocalities with empty metadata. Localities are named after serial_number of logger.Pre-defined logger types are ("Dendro","HOBO","Thermo","TMS","TMS_L45")

By default, data are cleaned with the functionmc_prep_clean see function description.mc_prep_clean detects gaps in time-series data,duplicated records, or records in the wrong order. Importantly,mc_prep_cleanalso applies astep parameter if provided. The step parameter can be used eitherinstead of automatic step detection which can sometime failed, or to prunemicroclimatic data. For example, if you have a 15-minute time series but you wish tokeep only one record per hour (without aggregating), you can use step parameter.However, if a step is provided andclean = FALSE, then the step is only stored in themetadata of myClim, and the time-series data is not cleaned, and the step is not applied.

It is good to specifydate_formatas this can often be the reason why reading have failed(see warnings after reading).

Value

myClim object in Raw-format seemyClim-package

See Also

mc_DataFormat,mc_prep_clean()

Examples

files <- c(system.file("extdata", "data_91184101_0.csv", package = "myClim"),           system.file("extdata", "data_94184102_0.csv", package = "myClim"))tomst_data <- mc_read_files(files, "TOMST",                             date_format = c("%d.%m.%Y %H:%M:%S",                                             "%Y.%m.%d %H:%M",                                             "%d.%m.%Y"))# user_data_formatsfiles <- system.file("extdata", "TMS94184102.csv", package = "myClim")user_data_formats <- list(my_logger=new("mc_DataFormat"))user_data_formats$my_logger@date_column <- 2user_data_formats$my_logger@date_format <- "%Y-%m-%d %H:%M:%S"user_data_formats$my_logger@tz_offset <- 0user_data_formats$my_logger@columns[[mc_const_SENSOR_T_C]] <- c(3, 4, 5)user_data_formats$my_logger@columns[[mc_const_SENSOR_real]] <- 6my_data <- mc_read_files(files, "my_logger", silent=TRUE, user_data_formats=user_data_formats)

Reading data from long data.frame

Description

This is universal function designed to read time series and valuesfrom long data.frame to myClim object.

Usage

mc_read_long(data_table, sensor_ids = list(), clean = TRUE, silent = FALSE)

Arguments

Details

Similar likemc_read_wide but is capable to read multiple sensorsfrom single table. Useful for data not coming from supported microclimaticloggers. E.g. meteorological station data.By default data are cleaned with functionmc_prep_clean().

Value

myClim object in Raw-format

See Also

mc_read_wide

Environment for reading problems

Description

Environment for reading problems

Usage

mc_read_problems

Format

An object of classenvironment of length 0.

Reading data from TubeDB

Description

Function is reading data from TubeDB (https://environmentalinformatics-marburg.github.io/tubedb/) into myClim object.

Usage

mc_read_tubedb(  tubedb,  region = NULL,  plot = NULL,  sensor_ids = NULL,  clean = TRUE,  silent = FALSE,  aggregation = "raw",  quality = "no",  ...)

Arguments

Details

In case you store your microclimatic time-series in TubeDB, you can read datawith TubeDB API into myClim object. You need to know database URL, username and password.

Value

myClim object in Raw-format

Examples

# Not run: To retrieve data from TubeDB, a running TubeDB server with a user account#          and a secret password is required.## Not run: tubedb <- TubeDB(url="server", user="user", password="password")data <- mc_read_tubedb(tubedb, region="ckras", plot=c("TP_KAR_19", "TP_KODA_61"))## End(Not run)

Reading data from wide data.frame

Description

This is universal function designed to read time-series and valuesfrom wide data.frame to myClim object. Useful for data not coming fromsupported microclimatic loggers. E.g. meteorological station data.

Usage

mc_read_wide(  data_table,  sensor_id = mc_const_SENSOR_real,  sensor_name = NULL,  clean = TRUE,  silent = FALSE)

Arguments

Details

The first column of input data.frame must be datetime column in POSIXct time format UTC timezone.Following columns represents localities. Column names are the localities names.All values in wide data.frame represents the same sensor type, e.g. air temperature. If you wish toread multiple sensors usemc_read_long or usemc_read_wide multiple times separatelyfor each sensor type and that merge myClim objects withmc_prep_mergeBy default data are cleaned with functionmc_prep_clean(). See function description. It detectsholes in time-series, duplicated records or records in wrong order.

Value

myClim object in Raw-format

See Also

mc_read_long

Export values to long table

Description

This function converts myClim object to long R data.frame.

Usage

mc_reshape_long(data, localities = NULL, sensors = NULL, use_utc = TRUE)

Arguments

Value

data.frame

columns:

• locality_id

• serial_number

• sensor_name

• height

• datetime

• time_to

• value

Examples

head(mc_reshape_long(mc_data_example_clean, c("A6W79", "A2E32"), c("TMS_T1", "TMS_T2")), 10)

Export values to wide table

Description

This function converts myClim object to the R data.frame with values of sensor in wide format.

Usage

mc_reshape_wide(  data,  localities = NULL,  sensors = NULL,  use_utc = TRUE,  show_logger_name = FALSE)

Arguments

Details

First column of the output data.frame is datetime followed by thecolumns for every sensor. When reshaping uncleaned data in Raw-format, only one loggerper myClim object is allowed to avoid potential confusion in case, there areduplicated values, allowed in uncleaned Raw myClim format.Name of the column is in format:

• localityid_loggerid_serialnumber_sensorname for Raw-format andshow_logger_name=FALSE

• localityid_loggername_sensornamefor Raw-format andshow_logger_name=TRUE

• localityid_sensorname for Agg-format

The less complex wide table is returned when exporting single sensor across localities.

Value

data.frame with columns:

• datetime

• locality1_sensor1

• ...

• ...

• localityN_sensorN

Examples

example_tms_wideformat <- mc_reshape_wide(mc_data_example_clean, c("A6W79", "A2E32"),                                          c("TMS_T1", "TMS_T2"))

Save myClim object

Description

This function was designed for saving the myClim data object to an.rds file, which can be later correctly loaded by any further versionof myClim package withmc_load. This is the safest way how to store andshare your myClim data.

Usage

mc_save(data, file)

Arguments

Value

RDS file saved at the output path destination

Examples

tmp_dir <- tempdir()tmp_file <- tempfile(tmpdir = tmp_dir)mc_save(mc_data_example_agg, tmp_file)file.remove(tmp_file)

Save myClim object separated by localities

Description

This function was designed for saving the myClim data object to multiple.rds files, which every contains data of one locality. Every file is named bylocality_id.

Usage

mc_save_localities(data, directory)

Arguments

Value

RDS files saved at the output path destination

Examples

tmp_dir <- tempdir()tmp_dir <- file.path(tmp_dir, "localities")dir.create(tmp_dir)mc_save_localities(mc_data_example_agg, tmp_dir)unlink(tmp_dir, recursive = TRUE)

Delete sensor states (tags)

Description

This function removes states (tags) defined by locality ID, sensor name, or tag value,or any combination of these three.

Usage

mc_states_delete(data, localities = NULL, sensors = NULL, tags = NULL)

Arguments

Value

myClim object in the same format as input, with deleted sensor states

Examples

data <- mc_states_delete(mc_data_example_clean, localities="A1E05",                         sensors=c(mc_const_SENSOR_Dendro_T, mc_const_SENSOR_Dendro_raw))

Convert a sensor to a state

Description

This function creates a new state from an existing logical (TRUE/FALSE) sensorand assigns this new state to selected existing sensors.

Usage

mc_states_from_sensor(  data,  source_sensor,  tag,  to_sensor,  value = NA,  inverse = FALSE)

Arguments

Details

The function is applicable only for logical (TRUE/FALSE) sensors. It allowsyou to convert such sensors into a state, represented as a tag. For example,you might calculate the estimation of snow cover usingmc_calc_snow (TRUE/FALSE)and then want to remove temperature records when the logger was covered by snow.In this case, you can convert the snow sensor to a state, and then replace thevalues with NA for that state usingmc_states_replace. In opposite casewhen you wish to keep e.g. only the moisture records when sensor was covered bysnow, useinverse = TRUE.

Value

Returns a myClim object in the same format as the input, with added states.

Examples

data <- mc_calc_snow(mc_data_example_agg, "TMS_T2", output_sensor="snow")data <- mc_states_from_sensor(data, source_sensor="snow", tag="snow", to_sensor="TMS_T2")

Insert new sensor states (tags)

Description

This function inserts new states (tags) into the selected part of the sensortime-series. For more information about the structure of states (tags),seemyClim-package.mc_states_insert() does not affectexisting rows in the states (tags) table but only inserts new rows even ifthe new ones are identical with existing (resulting in duplicated states).

Usage

mc_states_insert(data, states_table)

Arguments

Details

As a template for inserting states (tags), it is recommended to usethe output ofmc_info_states(), which will return the table with all necessarycolumns correctly named. Thesensor_name andvalue columns are optional and do notneed to be filled in.

Whenlocality_id is provided butsensor_name is NA in the states (tags) table,states are inserted for all sensors within the locality.

The states (tags) are associated with the sensor time-series, specifically tothe defined part of the time-series identified by start and end date times. Asingle time series can contain multiple states (tags) of identical or different types, and thesestates (tags) can overlap. Start and end date times are adjusted to fit withinthe range of logger/locality datetime and are rounded according to the logger's step. For instance,if a user attempts to insert a tag beyond the sensor time-series range,mc_states_insertwill adjust the start and end times to fit the available measurements. If a user defines a start time as'2020-01-01 10:23:00' on a logger with a 15-minute step, it will be rounded to '2020-01-01 10:30:00'.

Value

myClim object in the same format as input, with inserted sensor states

Examples

states <- data.frame(locality_id="A1E05", logger_name="Thermo_1",                     sensor_name="Thermo_T", tag="error",                     start=lubridate::ymd_hm("2020-10-28 9:00"),                     end=lubridate::ymd_hm("2020-10-28 9:30"))data <- mc_states_insert(mc_data_example_clean, states)

Create states for join conflicts

Description

This function creates a state (tag) when joining multiple overlappingtime-series with different microclimate values. State is created forall values that are in conflict in joining process.

Usage

mc_states_join(  data,  tag = "join_conflict",  by_type = TRUE,  tolerance = NULL,  older_newer_suffix = FALSE)

Arguments

Details

For more info see details ofmc_join function.Parameterolder_newer_suffix can be used for easier filtering of tags,to distinguish whether certain state on overlapping time series is connectedto older or newer record. It can help to decide which value keep and which remove.The loggers with same start and end datetimes cannot be marked as older/newer.Tag is without suffix in this case.

Value

Returns a myClim object with added states.

Create states for outlying values

Description

This function creates a state (tag) for all values that are either aboveor below certain thresholds (min_value,max_value), or at breakpoints where consecutive values of microclimate time-series suddenlyjump down or up (positive_jump,negative_jump).

Usage

mc_states_outlier(  data,  table,  period = NULL,  range_tag = "range",  jump_tag = "jump")

Arguments

Details

The best way to use this function is to first generate atable (data.frame) with pre-defined minimum, maximum, and jump thresholdsusing themc_info_range function. Then modify the thresholds as neededand apply the function (see example). All values abovemax_value and belowmin_value are tagged by default with therange tag. When consecutivevalues suddenly decrease by more thannegative_jump or increaseby more thanpositive_jump, such break points are tagged with thejump tag.It is possible to use only therange case, only thejump case, or both.

When theperiod parameter is used, the jump values are modified;range values are not affected. Depending on the logger step, thevalue of jump is multiplied or divided. For example, when the loggersare recording with a step of 15 minutes (900 s) and the user setsperiod = "1 hour" together withpositive_jump = 10, then consecutivevalues differing by (10 * (15 / 60) = 2.5) would be tagged. In this example,but with recording step 2 hours (7200 s), consecutive values differingby (10 * (120 / 60) = 20) would be tagged.

Value

Returns a myClim object in the same format as the input, with added states.

Examples

range_table <- mc_info_range(mc_data_example_clean)range_table$negative_jump[range_table$sensor_name == "TMS_moist"] <- 500data <- mc_states_outlier(mc_data_example_clean, range_table)

Replace values by states with tag

Description

This function replace values of sensors by states with tag.

Usage

mc_states_replace(data, tags, replace_value = NA, crop_margins_NA = FALSE)

Arguments

Details

The typical use of this function is for deleting/removing error/compromisedrecords from time-series by tagging them and then replacing tagged values with NA.Typically, when error/unwanted data appears at the beginning or end of time series, itcan be useful to crop time-series (delete records completely) usingcrop_margins_NA.

Value

myClim object in the same format as input, with replaced values

Examples

states <- data.frame(locality_id="A1E05", logger_name="Thermo_1",                     sensor_name="Thermo_T", tag="error",                     start=lubridate::ymd_hm("2020-10-28 9:00"),                     end=lubridate::ymd_hm("2020-10-28 9:30"))data <- mc_states_insert(mc_data_example_clean, states)data <- mc_states_replace(data, "error")

Convert states to logical (TRUE/FALSE) sensor

Description

This function creates a logical (TRUE/FALSE) sensor from specified states.

Usage

mc_states_to_sensor(  data,  tag,  to_sensor,  source_sensor = NULL,  inverse = FALSE)

Arguments

 If `to_sensor` is a single sensor name, the logical sensor is created  from the union of states across all sensors with the same tag. If `to_sensor`  contains multiple sensor names, the length of the vector must match the length  of `source_sensor`.

Details

The function allows you to create a TRUE/FALSE sensor based on a tag. By default,it generates a new sensor by combining all tags specified in thetag parameterfrom all available sensors at a particular logger or locality. If you specify asource_sensor, the function converts only the tags from that specific sensor.You can also create multiple new sensors from multiple tags by specifying morevalues into_sensor and providing exactly the same number of corresponding valuesinsource_sensor. For example, you can create one TRUE/FALSE sensor from stateson a temperature sensor and another from tags on a moisture sensor.

If you use parameterinverse = TRUE you get FALSE for each record where tag is assigned to andFALSE for the records where tag is absent. By default you get TRUE for all the recordswhere tag is assigned.

Value

Returns a myClim object in the same format as the input, with added sensors.

Examples

states <- data.frame(locality_id="A1E05", logger_name="Thermo_1",                     sensor_name="Thermo_T", tag="error",                     start=lubridate::ymd_hm("2020-10-28 9:00"),                     end=lubridate::ymd_hm("2020-10-28 9:30"))data <- mc_states_insert(mc_data_example_clean, states)data <- mc_states_to_sensor(data, tag="error", to_sensor="error_sensor")

Update sensor states (tags)

Description

This function updates (replaces) existing states (tags). For more information aboutthe structure of states (tags), seemyClim-package.In contrast withmc_states_insert, which does not affect existing states (tags),mc_states_update deletes all old states and replaces them with new ones,even if the new states table contains fewer states than original object.

Usage

mc_states_update(data, states_table)

Arguments

Details

As a template for updating states (tags), it is recommended to usethe output ofmc_info_states(), which will return the table with all necessarycolumns correctly named. Thesensor_name andvalue columns are optional and do notneed to be filled in.

The states (tags) are associated with the sensor time-series, specifically tothe defined part of the time-series identified by start and end date times. Asingle time series can contain multiple states (tags) of identical or different types, and thesestates (tags) can overlap. Start and end date times are adjusted to fit withinthe range of logger/locality datetime and are rounded according to the logger's step. For instance,if a user attempts to insert a tag beyond the sensor time-series range,mc_states_insertwill adjust the start and end times to fit the available measurements. If a user defines a start time as'2020-01-01 10:23:00' on a logger with a 15-minute step, it will be rounded to '2020-01-01 10:30:00'.

In contrast withmc_states_insert, the automatic filling of states whenlocality_idis provided butsensor_name is NA is not implemented inmc_states_update. When a user needs to updatestates (tags) for all sensors within the locality, each state (tag) needs to have a separate row inthe input table.

Value

myClim object in the same format as input, with updated sensor states

Examples

states <- mc_info_states(mc_data_example_clean)states$value <- basename(states$value)data <- mc_states_update(mc_data_example_clean, states)

Custom list for myClim object

Description

Top level list for store myClim data. (seemyClim-package) Rather service function usedfor checking, whether object is myClimList. The same time can be used to create standardR list from myClimList.

Usage

myClimList(metadata = NULL, localities = list())

Arguments

Value

the list containing myClim object’s metadata and localities

Print function for myClim object

Description

Function print metadata of myClim object and table from function mc_info().

Usage

## S3 method for class 'myClimList'print(x, ...)

Arguments

Examples

print(mc_data_example_agg, n=10)