# Import dendrometer data

The package `dendrometeR` provides functions to analyze dendrometer data using daily methods and a stem-cycle apprach (cf. Deslauriers et al. 2011). The package contains functions to fill gaps, to calculate daily statistics, to identify stem-cyclic phases and to analyze the processed dendrometer data in relation to environmental parameters. In addition, various plotting functions are provided.

This vignette describes how dendrometer series should be formatted for use in `dendrometeR`, and how data formats can be checked.

## Description of required data format

For use in `dendrometeR`, input data should be formatted with a timestamp as row names and dendrometer series in columns. The timestamp should have the following date-time format: `%Y-%m-%d %H:%M:%S`. Missing values in the dendrometer series should be indicated with `NA`.

Functions are designed for analyses on single growing seasons, amongst others because ARMA-based gap-filling routines will then perform best (i.e. ARMA parameters might be distinct for individual growing seasons). To allow the usage of `dendrometeR` for datasets from the Southern Hemisphere, various functions, however, allow to define two calendar years.

## Transformation of dendrometer data

This section illustrates the transformation of dendrometer data using the datasets `dmCDraw`, `dmHSraw` and `dmEDraw`, which come with `dendrometeR`, into the required input format. Also other possible data transformation issues are discussed.

#### Example dmCD_raw

The dataset `dmCDraw` presents an hourly dendrometer series for a tree from Camp Daniel, Canada, for the year 2008. The raw data can be loaded with `data(dmCDraw)`, and looks as follows:

site | year | tree | Month | Day | H | dendro | M | S | MDY | DHMS
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
SIM | 2008 | dendro | 4 | 11 | 0 | -0.4574325 | 0 | 0 | 17633 | 1523491200
SIM | 2008 | dendro | 4 | 11 | 1 | -0.4563325 | 0 | 0 | 17633 | 1523494800
SIM | 2008 | dendro | 4 | 11 | 2 | -0.4530275 | 0 | 0 | 17633 | 1523498400
SIM | 2008 | dendro | 4 | 11 | 3 | -0.4364625 | 0 | 0 | 17633 | 1523502000
SIM | 2008 | dendro | 4 | 11 | 4 | -0.4265200 | 0 | 0 | 17633 | 1523505600

The data does not include a timestamp in the requested date-time format (`%Y-%m-%d %H:%M:%S`), but separate columns for year, month (M), day (D), hour (H) and second (S) instead. To transform these columns to a single timestamp, execute:

    dm.data <- data.frame(timestamp = ISOdate(year = dmCDraw$year, month = dmCDraw$Month,
    day = dmCDraw$Day, hour = dmCDraw$H, min = dmCDraw$M))

A new data frame is created with a timestamp in the first column. Now, the column with dendrometer data should be added to the data frame:

    dm.data$dendro <- dmCDraw$dendro

Finally, the timestamp column should be put as row names and deleted thereafter:

    rownames(dm.data) <- dm.data$timestamp
    dm.data$timestamp <- NULL

The output, also saved as `dmCD` within the package, looks as follows:

| dendro
--- | ---
2008-04-11 00:00:00 | -0.4574325
2008-04-11 01:00:00 | -0.4563325
2008-04-11 02:00:00 | -0.4530275
2008-04-11 03:00:00 | -0.4364625
2008-04-11 04:00:00 | -0.4265200

#### Example dmHS_raw

The dataset `dmHSraw` presents a half-hourly dendrometer series for a tree from the monitoring plot Hinnensee, Germany, for the year 2012. The raw data can be loaded with `data(dmHSraw)`, and looks as follows:

TIMESTAMP | DOY | YEAR | dBUP2
--- | --- | --- | ---
2012-03-28 00:00 | 88 | 2012 | 0
2012-03-28 00:30 | 88 | 2012 | 0
2012-03-28 01:00 | 88 | 2012 | 0
2012-03-28 01:30 | 88 | 2012 | 0
2012-03-28 02:00 | 88 | 2012 | 0

Although the data contains a timestamp, it is recommended to check this timestamp before putting it as row names, e.g. to avoid problems with daylight savings. Superfluous columns (i.e. DOY, YEAR) are excluded in the transformation process.

    dm.data <- data.frame(timestamp = as.POSIXct(strptime(dmHSraw$TIMESTAMP, '%Y-%m-%d %H:%M:%S'), tz = "GMT"))

A new data frame is created with a timestamp in the first column. Now, the column with dendrometer data should be added to the data frame:

    dm.data$dBUP2 <- dmHSraw$dBUP2

Finally, the timestamp column should be put as row names and deleted thereafter:

    rownames(dm.data) <- dm.data$timestamp
    dm.data$timestamp <- NULL

#### Example dmED_raw

The dataset `dmEDraw` presents a half-hourly dendrometer series for two trees from the monitoring plot Eldena, Germany, for the year 2015. The raw data can be loaded with `data(dmEDraw)`, and looks as follows:

| TIMESTAMP | Beech03 | Beech04
--- | --- | --- | ---
33553 | 2015-03-01 00:00:00 | 5349.147 | 4542.304
33554 | 2015-03-01 00:30:00 | 5349.807 | 4541.045
33555 | 2015-03-01 01:00:00 | 5349.617 | 4542.473
33556 | 2015-03-01 01:30:00 | 5349.923 | 4542.758
33557 | 2015-03-01 02:00:00 | 5350.483 | 4542.069

Although the data contains a timestamp, it is recommended to check this timestamp before putting it as row names, e.g. to avoid problems with daylight savings.

    dm.data <- data.frame(timestamp = as.POSIXct(strptime(dmEDraw$TIMESTAMP, '%Y-%m-%d %H:%M:%S'), tz = "GMT"))

A new data frame is created with a timestamp in the first column. Now, the columns with the two dendrometer series should be added to the data frame:

    # option 1: select series by typing column names:
    dm.data[,c("Beech03","Beech04")] <- dmEDraw[,c(2,3)]

    # option 2: select series from the character vector produced by names:
    dm.data[,names(dmEDraw)[c(2,3)]] <- dmEDraw[,c(2,3)]

In case of multiple dendrometer series in consecutive columns, the use of a multicolon `:` might be advantageous:

    dm.data[,names(dmEDraw)[2:3]] <- dmEDraw[,2:3]

Finally, the timestamp column should be put as row names and deleted thereafter:

    rownames(dm.data) <- dm.data$timestamp
    dm.data$timestamp <- NULL

## Checking format and resolution of input data

The function `is.dendro` checks whether the input dendrometer data is in the required format. It returns `TRUE` when the data is well-formatted, and `FALSE` if not. In the latter case, specific error messages on the nature of the problem (e.g., problems with timestamp, non-numeric data etc.) will be returned as well. See the following examples:

    is.dendro(dmCDraw)

    ## Warning in is.dendro(dmCDraw): rownames of 'dmCDraw' is not a timestamp or
    ## contains errors

    ## [1] FALSE

    is.dendro(dmCD)

    ## [1] TRUE

The temporal resolution of the dendrometer data can be checked using the function `dendro.resolution`. The output defaults to seconds, but can be specified in other units (mins“,”hours“,”days"):

    dendro.resolution(dmCD)

    ## [1] 3600

    dendro.resolution(dmCD, unts = "hours")

    ## [1] 1

The function `is.na` (base package) can be used to check whether dendrometer series contain gaps as follows:

    TRUE %in% is.na(dmCD)

    ## [1] FALSE

    data(dmED)
    TRUE %in% is.na(dmED)

    ## [1] TRUE

If `TRUE` is returned the data contains gaps, and if `FALSE` not.

## References

Deslauriers, A., Rossi, S., Turcotte, A., Morin, H. and Krause, C. (2011) A three-step procedure in SAS to analyze the time series from automatic dendrometers. Dendrochronologia 29: 151-161.