Package 'dendRoAnalyst'

Description

Identifies adverse climate periods from a climate time series and calculates relative dendrometer change from the start of each adverse phase.

In addition to the adverse phase itself, the function also defines a complete period for each event ID:

• the adverse climate phase, and

• the following normal climate phase until the next adverse phase starts (or until the end of the common series).

Relative dendrometer change is always calculated from the first day of the adverse phase for that ID.

The function returns:

• adverse_change: relative change only during adverse phases,

• normal_change: relative change only during the following normal phases,

• full_period_change: relative change across adverse + following normal phase,

• continuous_full_period_change: same as full_period_change, but values do not reset to 0 at the next adverse phase and instead continue from the end of the previous full period,

• period_info: per-ID and per-tree summary metrics.

Usage

clim.twd(
  df,
  Clim,
  dailyValue = "max",
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = TRUE
)

Arguments

Details

The algorithm works as follows:

1. Climate data are thresholded to identify adverse days.

2. Consecutive adverse days are grouped into candidate adverse runs.

3. Only runs satisfying thresholdDays are retained as true adverse events.

4. For each retained adverse event, the following normal period is defined as all non-adverse days until the next adverse event starts (or the end of the series).

5. Dendrometer data are resampled to daily resolution using dendro.resample.

6. Relative dendrometer change is calculated from the first day of the adverse phase for each ID.

Threshold syntax:

• single-threshold forms such as "<5", "<=10", ">3", ">=0", "==0",

• range forms for thresholdClim such as "between(5,10)" or "5:10", both interpreted inclusively.

thresholdDays must use a single-threshold form such as ">5".

Value

A list of class "clim_twd_output" containing:

adverse_change

A data frame of relative dendrometer change during adverse phases only.

normal_change

A data frame of relative dendrometer change during the following normal phases only.

full_period_change

A data frame of relative dendrometer change across adverse + following normal phase, reset to 0 at each adverse start.

continuous_full_period_change

A data frame similar to full_period_change, but values continue from the end of the previous full period instead of resetting to 0.

period_info

A data frame with one row per ID and tree, containing adverse and normal phase boundaries, the date and magnitude of maximum adverse decline during the adverse phase, lags to first drop below zero, lags to maximum adverse decline, and lags to return to zero.

phase_table

A data frame with adverse and normal phase boundaries for each ID.

Note

If the dendrometer and climate datasets have different time spans, analysis is automatically restricted to their common overlap.

References

Raffelsbauer V, Spannl S, Peña K, Pucha-Cofrep D, Steppe K, Bräuning A (2019). Tree Circumference Changes and Species-Specific Growth Recovery After Extreme Dry Events in a Montane Rainforest in Southern Ecuador. Frontiers in Plant Science, 10, 342. doi:10.3389/fpls.2019.00342

See Also

dendro.resample, phase.zg, phase.sc

Examples

data(gf_nepa17)
data(ktm_rain17)

rel_out <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  dailyValue = "max",
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = FALSE
)

head(rel_out$adverse_change)
head(rel_out$normal_change)
head(rel_out$full_period_change)
head(rel_out$continuous_full_period_change)
head(rel_out$period_info)

rel_out2 <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  thresholdClim = "between(5,10)",
  thresholdDays = ">3",
  showPlot = FALSE
)

Description

Calculates grouped statistics from the output of clim.twd().

The function can summarize relative dendrometer change trajectories and event-level metrics:

• by tree,

• by species,

• by site,

• or by species within site.

It can also restrict IDs to specific months, years, or custom day-of-year windows based on the adverse-phase start date of each ID.

Usage

clim.twd.stats(
  x,
  tree_info = NULL,
  response = c("adverse_change", "normal_change", "full_period_change",
    "continuous_full_period_change"),
  group_by = c("tree", "species", "site", "species_site"),
  center = c("mean", "median"),
  conf_level = 0.95,
  months = NULL,
  years = NULL,
  doy_window = NULL,
  year_window = NULL,
  include_tree_series = TRUE
)

Arguments

Details

Temporal filtering is based on the adverse_start date in x$phase_table. Multiple filters are combined, so for example users can simultaneously restrict to:

• specific months,

• specific years,

• a day-of-year window,

• and a year range.

If group_by = "species", "site", or "species_site", tree_info must provide the required columns.

Value

A list of class "clim_twd_stats" with:

trajectory_summary

Grouped time-series summary for each ID and date, including central tendency, SD bands, and empirical 95% limits.

id_summary

Grouped per-ID summary derived from x$period_info.

selected_ids

IDs retained after temporal filtering.

phase_table

Filtered phase table.

tree_info

Metadata table used for grouping.

long_data

Filtered long-format tree-level response table, if include_tree_series = TRUE.

settings

List of settings used to generate the summaries.

Examples

rel_out <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = FALSE
)

# tree-level statistics
st1 <- clim.twd.stats(
  rel_out,
  response = "full_period_change",
  group_by = "tree"
)

summary(st1)
plot(st1, type = "trajectory")

# species metadata
tree_info <- data.frame(
  tree = c("T2", "T3"),
  species = c("Pinus", "Pinus"),
  site = c("Ktm", "Ktm")
)

# species-level summaries restricted to IDs starting in months 6 to 8
st2 <- clim.twd.stats(
  rel_out,
  tree_info = tree_info,
  response = "full_period_change",
  group_by = "species",
  center = "median",
  months = 6:8
)

summary(st2)
plot(st2, type = "trajectory", band = "limit95")

# species within site
st3 <- clim.twd.stats(
  rel_out,
  tree_info = tree_info,
  response = "continuous_full_period_change",
  group_by = "species_site",
  doy_window = c(150, 250),
  year_window = c(2017, 2018)
)

Description

Performs hypothesis tests on parameters derived from clim.twd() output.

This function is designed for scenarios such as:

• species comparison as a whole,

• species comparison by year,

• site comparison as a whole,

• site comparison by year,

• species-within-site comparison,

• ID-wise comparisons.

The function uses the period_info table from clim.twd() and tests selected parameters across groups such as trees, species, sites, or species-site combinations.

Usage

clim.twd.test(
  x,
  tree_info = NULL,
  parameter = c("lag_to_below_zero", "lag_to_max_adverse_decline", "lag_to_return_zero",
    "max_adverse_decline_value", "change_end_adverse", "change_end_full_period",
    "continuous_end_full_period"),
  compare_by = c("tree", "species", "site", "species_site"),
  within = c("all", "year", "ID"),
  test_method = c("auto", "t_test", "welch_t", "wilcox", "anova", "kruskal"),
  ids = NULL,
  years = NULL,
  months = NULL,
  doy_window = NULL,
  year_window = NULL,
  pairwise = TRUE,
  p_adjust_method = "BH",
  min_n_per_group = 2
)

Arguments

Value

A list of class "clim_twd_test" containing:

data_used

Filtered test data used for the analyses.

test_results

Main test results by stratum.

pairwise_results

Pairwise comparison table where available.

group_summary

Descriptive summaries by stratum and group.

settings

Settings used for the analysis.

Examples

rel_out <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = FALSE
)

tree_info <- data.frame(
  tree = c("T2", "T3"),
  species = c("Pinus", "Pinus"),
  site = c("Ktm", "Ktm")
)

# species comparison across all retained IDs
tst1 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "max_adverse_decline_value",
  compare_by = "species",
  within = "all"
)

summary(tst1)
plot(tst1)

# species comparison by year
tst2 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "lag_to_return_zero",
  compare_by = "species",
  within = "year"
)

# site comparison by year
tst3 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "change_end_full_period",
  compare_by = "site",
  within = "year",
  test_method = "kruskal"
)

Description

Computes daily statistics from high-frequency dendrometer time series. For each day, it extracts the minimum and maximum values, their times of occurrence, daily mean and median, daily amplitude, the signed lag between the time of maximum and minimum, the day-to-day change in the daily maximum, and a daily status indicating whether the day is growing, shrinking, or stable relative to the previous day.

Usage

daily.data(df, TreeNum)

Arguments

Details

The function requires a data frame with a time column in the first column and one or more dendrometer series in the following columns. The user selects the series using TreeNum.

The returned object has class "daily_output", so it can be plotted directly with plot().

The column Max_diff is computed as:

$Max\_diff_t = Max_t - Max_{t-1}$

The column Day_status is derived from Max_diff:

• "growing" if Max_diff > 0

• "shrinking" if Max_diff < 0

• "stable" if Max_diff = 0

The first day has NA for Max_diff and Day_status.

Value

A tibble of class "daily_output" containing:

DATE

Calendar date.

Min

Daily minimum value.

Time_min

Time of day of minimum value.

Max

Daily maximum value.

Time_max

Time of day of maximum value.

mean

Daily mean value.

median

Daily median value.

amplitude

Daily amplitude = Max - Min.

Time_min_h

Time of minimum expressed in decimal hours.

Time_max_h

Time of maximum expressed in decimal hours.

lag_h

Signed difference in hours: Time_max_h - Time_min_h.

Remarks

"*" if Time_max > Time_min, otherwise "".

Max_diff

Difference between today's maximum and the previous day's maximum.

Day_status

"growing", "shrinking", "stable", or NA.

Note

The object returned by daily.data() can be plotted using plot() because it is assigned class "daily_output".

References

King G, Fonti P, Nievergelt D, Büntgen U, Frank D (2013) Climatic drivers of hourly to yearly tree radius variations along a 6°C natural warming gradient. Agricultural and Forest Meteorology 168:36–46. doi:10.1016/j.agrformet.2012.08.002

Examples

data(nepa17)
daily_stats <- daily.data(df = nepa17[1:1000, ], TreeNum = 1)
head(daily_stats, 10)

Description

This function changes the temporal resolution of dendrometer and climate time series. It supports both aggregation to coarser resolutions and interpolation to finer resolutions. The target resolution can be defined in minutes, hours, days, weeks, or month-end frequency. Aggregation can be performed using mean, max, min, sum, or count (number of non-missing values). When a finer temporal resolution than the original data is requested, the function can interpolate the series to the new time step using linear interpolation.

Usage

dendro.resample(
  df,
  by,
  value = "mean",
  method = c("auto", "aggregate", "interpolate")
)

Arguments

Value

A dataframe with resampled data. The first column contains the new time stamps and the remaining columns contain the resampled variables.

Examples

library(dendRoAnalyst)
data(nepa17)

# Monthly resampling using maximum values
resample_ME <- dendro.resample(df = gf_nepa17, by = "ME", value = "max")
head(resample_ME, 10)

# Daily resampling using mean values
resample_D <- dendro.resample(df = gf_nepa17, by = "D", value = "mean")

# Count non-missing values per day
resample_count <- dendro.resample(df = gf_nepa17, by = "D", value = "count",
                                  method = "aggregate")

# Interpolate to 30-minute resolution
resample_30M <- dendro.resample(df = gf_nepa17, by = "30M", value = "mean",
                                method = "auto")

Description

Truncates dendrometer data to a user-defined calendar-year and day-of-year window.

The first column of df is treated as the date-time column and is renamed internally to TIME. The date-time column may be a Date, POSIXct, or character vector in the format "yyyy-mm-dd HH:MM:SS". Character dates in the format "yyyy-mm-dd" are also accepted.

This version supports leap years correctly. For example, DOY = 366 is valid for leap years such as 2016, 2020, or 2024, but invalid for non-leap years.

Usage

dendro.truncate(df, CalYear, DOY)

Arguments

Details

The truncation rules are:

• If CalYear has length one and DOY has length one, data from that single day are returned.

• If CalYear has length one and DOY has length two, data from the first DOY to the second DOY within the same year are returned.

• If CalYear has length two and DOY has length one, data from that DOY in the first year to the same DOY in the second year are returned.

• If CalYear has length two and DOY has length two, data from the first DOY of the first year to the second DOY of the second year are returned.

The function uses real calendar dates internally rather than row positions. Therefore, leap-year DOY 366 is handled correctly.

Value

A tibble containing the truncated dendrometer data.

Examples

library(dendRoAnalyst)
data(nepa)

# Extract data from DOY 20 to 50 in 2017
trunc1 <- dendro.truncate(df = nepa, CalYear = 2017, DOY = c(20, 50))
head(trunc1, 10)

# Leap-year example, if the data contain year 2020
# trunc2 <- dendro.truncate(df = df2020, CalYear = 2020, DOY = c(1, 366))

Description

A single helper function that adds climate information to outputs from daily.data(), phase.zg(), or phase.sc().

Depending on the class of x and the selected scale, the function:

• joins daily climate to daily.data() output

• joins climate summaries to phase windows in ZG_cycle or SC_cycle

• joins subdaily climate features to point-level ZG_phase or SC_phase

Usage

dm_add_climate(
  x,
  clim,
  scale = c("auto", "daily", "phase", "subdaily"),
  mean_vars = NULL,
  min_vars = NULL,
  max_vars = NULL,
  sum_vars = NULL,
  median_vars = NULL,
  lag_vars = NULL,
  lagmean_vars = NULL,
  lagsum_vars = NULL,
  lag_days = c(1, 3, 7),
  sub_mean_vars = NULL,
  sub_sum_vars = NULL,
  sub_lag_vars = NULL,
  roll_hours = c(3, 6, 24),
  lag_hours = c(1, 3, 6, 24),
  suffix = "_phase"
)

Arguments

Value

The same biological object with climate information added.

Examples

data(nepa17)
data(gf_nepa17)
data(ktm_clim_hourly)

# daily.data() output + daily climate
dd <- daily.data(df = nepa17[1:1000, ], TreeNum = 1)
dd_clim <- dm_add_climate(
  dd,
  ktm_clim_hourly,
  scale = "daily",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)
head(dd_clim)

# phase.zg() output + phase-window climate
zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
zg_clim <- dm_add_climate(
  zg,
  ktm_clim_hourly,
  scale = "phase",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)
head(zg_clim$ZG_cycle)

# phase.sc() output + point-level subdaily climate
sc <- phase.sc(df = gf_nepa17[1:800, ], TreeNum = 1, smoothing = 12)
sc_point <- dm_add_climate(
  sc,
  ktm_clim_hourly,
  scale = "subdaily",
  sub_mean_vars = c("temp", "VPD", "RH"),
  sub_sum_vars  = c("prec"),
  sub_lag_vars  = c("temp", "VPD", "RH"),
  roll_hours = c(1, 3, 6, 24),
  lag_hours  = c(1, 3, 6, 24)
)
head(sc_point$SC_phase)

Description

Computes daily climate summaries from climate time series so they can be related to daily dendrometer summaries from daily.data().

The input can be a standardized climate object returned by read.climate(), a raw data frame, or a valid file path accepted by read.climate().

In addition to same-day climate summaries, the function can also compute lagged and antecedent daily climate features from the summarized daily series:

• lagged values (e.g. previous 1 or 3 days)

• antecedent means over previous n days

• antecedent sums over previous n days

Usage

dm_daily_clim(
  clim_df,
  mean_vars = NULL,
  min_vars = NULL,
  max_vars = NULL,
  sum_vars = NULL,
  median_vars = NULL,
  lag_vars = NULL,
  lagmean_vars = NULL,
  lagsum_vars = NULL,
  lag_days = c(1, 3, 7)
)

Arguments

Details

Lagged and antecedent features are calculated from the already summarized daily climate columns. For example, if VPD is included in max_vars, the daily summary column will be VPD_max. If this column is listed in lag_vars and lag_days = 1, then the additional column VPD_max_lag_1d is created.

Antecedent means and sums exclude the current day. For example:

$x\_lagmean\_3d(t) = mean(x_{t-3}, x_{t-2}, x_{t-1})$

$x\_lagsum\_7d(t) = sum(x_{t-7}, \ldots, x_{t-1})$

Value

A tibble of class "daily_clim" with one row per day.

Examples

data(ktm_clim_hourly)
clim_day <- dm_daily_clim(
  ktm_clim_hourly,
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("VPD"),
  sum_vars  = c("prec"),
  lag_vars = c("VPD_max", "temp_mean"),
  lagmean_vars = c("temp_mean", "VPD_mean", "RH_mean"),
  lagsum_vars = c("prec_sum"),
  lag_days = c(1, 3, 7)
)
head(clim_day, 5)

Description

Builds a long-format epoch table by extracting climate values before and after event times.

The optional Year and DOY arguments allow the user to restrict which events are included in the superposed epoch analysis. The full climate table is retained for lag extraction so that values before and after selected events are still available.

Usage

dm_epoch_extract(
  events,
  clim,
  vars = "all",
  lag_before = 24,
  lag_after = 24,
  step = 1,
  unit = c("hours", "days", "mins"),
  agg_fun = "mean",
  var_funs = NULL,
  Year = NULL,
  DOY = NULL,
  restrict_null_to_window = TRUE
)

Arguments

Value

An object of class c("dm_epoch", "dm_epoch_extract").

Examples

# events <- dm_event_times(zg, event = "GRO_start")
# ep <- dm_epoch_extract(
#   events = events,
#   clim = climate,
#   vars = c("Rain", "temp", "vpd"),
#   Year = c(2022, 2023, 2024),
#   DOY = c(100, 300),
#   lag_before = 24,
#   lag_after = 24,
#   unit = "hours"
# )

Description

Tests observed superposed epoch composites against empirical null distributions generated by randomly sampled anchor times.

If the input object was created with Year and/or DOY filters in [dm_epoch_extract()] and restrict_null_to_window = TRUE, null anchors are sampled from the same calendar-year and day-of-year window.

Usage

dm_epoch_test(
  x,
  statistic = c("mean", "median"),
  null = c("same_doy_window", "same_month", "random_time"),
  n_iter = 1000,
  doy_window = 15,
  match_hour = TRUE,
  match_minute = TRUE,
  conf_level = 0.95,
  seed = NULL
)

Arguments

Value

An object of class c("dm_epoch", "dm_epoch_test").

Description

Extracts climate at event times and summarizes climate in windows preceding those events. Event times can be phase starts, phase ends, or Max.twd.time for phase.zg() output.

Usage

dm_event_climate(
  x,
  clim_df,
  event = c("phase_start", "phase_end", "max_twd"),
  phase = "all",
  windows = c(0, 1, 3, 6, 12, 24, 48),
  mean_vars = NULL,
  max_vars = NULL,
  min_vars = NULL,
  sum_vars = NULL,
  median_vars = NULL,
  instant_vars = NULL,
  instant_match = c("nearest", "previous", "next")
)

Arguments

Value

A tibble with one row per event and climate summaries in the requested antecedent windows.

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)

evt_zg <- dm_event_climate(
  zg,
  ktm_clim_hourly,
  event = "phase_start",
  phase = "all",
  windows = c(0, 1, 3, 6, 12, 24),
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)

head(evt_zg)

evt_maxtwd <- dm_event_climate(
  zg,
  ktm_clim_hourly,
  event = "max_twd",
  windows = c(0, 1, 3, 6, 12, 24),
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("VPD"),
  sum_vars  = c("prec")
)

head(evt_maxtwd)

Description

Summarizes a climate variable extracted by dm_event_climate() by phase, event type, month, or month-of-year.

Usage

dm_event_climate_summary(
  event_data,
  climate_var,
  group_var = c("Phase", "event_type"),
  by = c("none", "month", "month_of_year", "year"),
  Year = NULL,
  DOY = NULL
)

Arguments

Value

A tibble of summary statistics.

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
evt_zg <- dm_event_climate(
  zg,
  ktm_clim_hourly,
  event = "phase_start",
  windows = c(0, 3, 6, 12, 24),
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("VPD"),
  sum_vars  = c("prec")
)

smry <- dm_event_climate_summary(
  evt_zg,
  climate_var = "VPD_mean_prev_6h",
  group_var = "Phase",
  by = "month_of_year"
)

head(smry)

Description

Tests whether an event-based climate variable differs between groups such as phases or event types.

Usage

dm_event_climate_test(
  event_data,
  climate_var,
  group_var = c("Phase", "event_type"),
  by = c("none", "month", "month_of_year", "year"),
  Year = NULL,
  DOY = NULL,
  method = c("auto", "anova", "kruskal", "t.test", "wilcox")
)

Arguments

Value

A list with summary statistics, overall tests, and pairwise tests.

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
evt_zg <- dm_event_climate(
  zg,
  ktm_clim_hourly,
  event = "phase_start",
  windows = c(0, 3, 6, 12, 24),
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("VPD"),
  sum_vars  = c("prec")
)

tst <- dm_event_climate_test(
  evt_zg,
  climate_var = "VPD_mean_prev_6h",
  group_var = "Phase",
  by = "month_of_year",
  method = "auto"
)

tst$summary
tst$overall_tests
head(tst$pairwise_tests)

Description

Extracts event times from objects returned by phase.zg() or phase.sc(). The resulting table can be passed directly to [dm_epoch_extract()] for superposed epoch analysis.

Usage

dm_event_times(
  x,
  event = "all",
  phase = NULL,
  min_duration = NULL,
  min_magnitude = NULL,
  min_max_twd = NULL,
  remove_na_times = TRUE
)

Arguments

Value

A tibble of events with class c("dm_events", ...).

Description

Joins daily climate summaries to the output of daily.data() by calendar date.

The climate input can be:

• the output of dm_daily_clim()

• the output of read.climate()

• a raw climate data frame

• a valid climate file path readable by read.climate()

If the supplied climate input is not already a daily climate table, it will first be converted to daily summaries with dm_daily_clim() using default daily means for numeric variables.

Usage

dm_join_daily_clim(daily_obj, clim_daily)

Arguments

Value

The daily.data() output with climate columns appended. The returned object has class c("daily_output_clim", "daily_output", ...).

Examples

data(nepa17)
data(ktm_clim_hourly)

dd <- daily.data(df = nepa17[1:1000, ], TreeNum = 1)

clim_std <- read.climate(
  ktm_clim_hourly,
  time_col = "TIME",
  vars = c("temp", "prec", "VPD", "RH"),
  verbose = FALSE
)

clim_day <- dm_daily_clim(
  clim_std,
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)

dd_clim <- dm_join_daily_clim(dd, clim_day)
head(dd_clim)

Description

Summarizes climate conditions within each phase window of phase.zg() or phase.sc() output and appends those summaries to ZG_cycle or SC_cycle.

The climate input can be:

• the output of read.climate()

• a raw climate data frame

• a valid climate file path readable by read.climate()

Climate variables are summarized over each phase interval defined by the Start and End columns of the phase-cycle table.

Usage

dm_join_phase_clim(
  x,
  clim_df,
  mean_vars = NULL,
  min_vars = NULL,
  max_vars = NULL,
  sum_vars = NULL,
  median_vars = NULL,
  suffix = "_phase"
)

Arguments

Value

The same phase object with climate summaries appended to ZG_cycle or SC_cycle. The returned object has class c("ZG_output_clim", "ZG_output", ...) or c("SC_output_clim", "SC_output", ...).

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)

zg_clim <- dm_join_phase_clim(
  zg,
  ktm_clim_hourly,
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)

head(zg_clim$ZG_cycle)

Description

Joins timestamp-level subdaily climate features to point-level output from phase.zg() or phase.sc().

The climate input can be:

• the output of dm_subdaily_clim()

• the output of read.climate()

• a raw climate data frame

• a valid climate file path readable by read.climate()

If the supplied climate input is not already a subdaily climate-feature table, the function attempts to standardize it with read.climate() and then joins by exact timestamp using the TIME column.

Usage

dm_join_subdaily_clim(x, clim_sub)

Arguments

Value

The same phase object with climate features appended to ZG_phase or SC_phase. The returned object has class c("ZG_output_clim", "ZG_output", ...) or c("SC_output_clim", "SC_output", ...).

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)

clim_sub <- dm_subdaily_clim(
  ktm_clim_hourly,
  mean_vars = c("temp", "VPD", "RH"),
  sum_vars  = c("prec"),
  lag_vars  = c("temp", "VPD", "RH"),
  roll_hours = c(1, 3, 6, 24),
  lag_hours  = c(1, 3, 6, 24)
)

zg_point_clim <- dm_join_subdaily_clim(zg, clim_sub)
head(zg_point_clim$ZG_phase)

Description

General plotting function for dendrometer outputs with attached climate information. It works with objects of class daily_output_clim, ZG_output_clim, and SC_output_clim, usually produced by dm_add_climate(), dm_join_daily_clim(), dm_join_phase_clim(), or dm_join_subdaily_clim().

The function can display one selected climate variable through time, by phase or day status, as boxplots or violin plots, or as a climate-response relationship.

Usage

dm_plot_climate(
  x,
  climate_var,
  metric_var = NULL,
  scale = c("auto", "daily", "cycle", "point"),
  type = c("timeseries", "boxplot", "violin", "both", "relation"),
  group_var = NULL,
  Year = NULL,
  DOY = NULL,
  point_alpha = 0.6,
  add_smooth = FALSE,
  temporal = NULL
)

Arguments

Value

A ggplot2 object, returned invisibly.

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
zg_clim <- dm_add_climate(
  zg,
  ktm_clim_hourly,
  scale = "phase",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)

dm_plot_climate(
  zg_clim,
  climate_var = "VPD_mean_phase",
  scale = "cycle",
  type = "boxplot"
)

plot(
  zg_clim,
  climate_var = "VPD_mean_phase",
  scale = "cycle",
  type = "boxplot"
)

Description

Plots and compares multiple climate variables attached to climate-augmented dendrometer outputs. It works with objects of class daily_output_clim, ZG_output_clim, and SC_output_clim.

Supported plot types include faceted time-series, grouped boxplots, violin plots, combined violin-boxplots, correlation heatmaps, and regression heatmaps.

Usage

dm_plot_climate_compare(
  x,
  climate_vars = NULL,
  numeric_vars = NULL,
  scale = c("auto", "daily", "cycle", "point"),
  type = c("timeseries", "boxplot", "violin", "both", "cor_heatmap",
    "regression_heatmap"),
  group_var = NULL,
  Year = NULL,
  DOY = NULL,
  box_scales = c("free_y", "fixed"),
  cor_method = c("pearson", "spearman", "kendall"),
  use_pairwise = TRUE,
  regression_stat = c("r.squared", "slope", "p.value"),
  point_alpha = 0.5,
  show_values = FALSE,
  temporal = NULL
)

Arguments

Details

For type = "regression_heatmap", pairwise simple linear regressions are fitted as y ~ x for every variable combination. The heatmap can display $R^2$, slope, or p-value.

Value

A ggplot2 object, returned invisibly.

Examples

data(gf_nepa17)
data(ktm_clim_hourly)

zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
zg_clim <- dm_add_climate(
  zg,
  ktm_clim_hourly,
  scale = "phase",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)

dm_plot_climate_compare(
  zg_clim,
  climate_vars = c("temp_mean_phase", "VPD_mean_phase", "RH_mean_phase"),
  scale = "cycle",
  type = "boxplot"
)

plot(
  zg_clim,
  climate_vars = c("temp_mean_phase", "VPD_mean_phase", "RH_mean_phase"),
  scale = "cycle",
  type = "boxplot"
)

Description

Standardizes one or more dendrometer series within seasonal years so that multiple trees can be brought to a comparable scale while preserving their within-season temporal pattern.

Seasonal years are defined as:

• "NH": Northern Hemisphere year, from 01 Jan to 31 Dec

• "SH": Southern Hemisphere year, from 01 Jul to 30 Jun of the next year

• "CS": Custom season defined by CS_doys = c(doy1, doy2)

For season_type = "CS":

• if CS_doys[1] <= CS_doys[2], the season stays within one calendar year

• if CS_doys[1] > CS_doys[2], the season wraps across years

Standardization is applied separately for each dendrometer series and each seasonal year.

Usage

dm_standardize(
  df,
  season_type = c("NH", "SH", "CS"),
  CS_doys = NULL,
  method = c("center", "amplitude", "robust_amplitude", "minmax", "zscore",
    "robust_zscore", "percentile"),
  ref_type = c("first_value", "first_n_days", "ref_window"),
  ref_n_days = 7,
  ref_doys = NULL,
  q_low = 0.05,
  q_high = 0.95
)

Arguments

Value

A list of class "dm_standardized" containing:

• data: wide data frame with columns TIME, season_year, in_season, and standardized dendrometer series

• parameters: tibble with one row per tree and seasonal year, summarizing the reference value and scaling denominator used

• metadata: method and seasonal-year settings

For season_type = "CS", observations outside the custom season are retained in data, but their standardized values are set to NA and in_season = FALSE.

Examples

data(gf_nepa17)

# Northern Hemisphere seasonal-year standardization
out_nh <- dm_standardize(
  df = gf_nepa17,
  season_type = "NH",
  method = "robust_amplitude"
)

# Southern Hemisphere seasonal-year standardization
out_sh <- dm_standardize(
  df = gf_nepa17,
  season_type = "SH",
  method = "center"
)

# Custom season within one year
out_cs1 <- dm_standardize(
  df = gf_nepa17,
  season_type = "CS",
  CS_doys = c(100, 280),
  method = "robust_amplitude"
)

# Custom season wrapping across years
out_cs2 <- dm_standardize(
  df = gf_nepa17,
  season_type = "CS",
  CS_doys = c(250, 120),
  method = "percentile"
)

head(out_nh$data)
head(out_nh$parameters)

Description

Computes rolling-window and lagged climate features at subdaily resolution for direct linkage with point-level dendrometer outputs such as ZG_phase and SC_phase.

The input can be a standardized climate object returned by read.climate(), a raw data frame, or a valid file path accepted by read.climate().

Usage

dm_subdaily_clim(
  clim_df,
  mean_vars = NULL,
  sum_vars = NULL,
  lag_vars = NULL,
  roll_hours = c(3, 6, 24),
  lag_hours = c(1, 3, 6, 24)
)

Arguments

Details

The function learns the temporal resolution automatically from the median time step in the TIME column. It works with hourly as well as minute-resolution data (for example 60-, 30-, 15-, 10-, or 5-minute data).

Rolling windows and lags are provided in hours and may be fractional:

• 0.25 = 15 minutes

• 0.5 = 30 minutes

• 1 = 1 hour

• 3 = 3 hours

If the user requests a rolling window or lag that is smaller than the inferred climate resolution, the function stops with an error.

If a requested window is not an exact multiple of the inferred resolution, it is rounded to the nearest number of time steps and a warning is issued.

Value

A tibble of class "subdaily_clim" with timestamp-level climate features added. The inferred temporal resolution in hours is stored in attr(x, "resolution_hours").

Examples

data(ktm_clim_hourly)

clim_sub <- dm_subdaily_clim(
  ktm_clim_hourly,
  mean_vars = c("temp", "VPD", "RH"),
  sum_vars  = c("prec"),
  lag_vars  = c("temp", "VPD", "RH"),
  roll_hours = c(1, 3, 6, 24),
  lag_hours  = c(1, 3, 6, 24)
)

head(clim_sub)
attr(clim_sub, "resolution_hours")

Description

Performs continuous wavelet analysis on dendrometer time series.

The function can work with:

• raw dendrometer series from a data frame,

• detrended dendrometer series from dm.detrend.fit() output,

• first differences of either raw or detrended series.

It automatically:

• identifies the temporal resolution of the input series,

• regularizes the series to a complete time grid,

• optionally interpolates missing values,

• performs wavelet analysis separately for each selected tree/series,

• converts wavelet periods to hours for summary and plotting.

Usage

dm_wavelet(
  x,
  TreeNum = "all",
  source = c("auto", "raw", "detrended", "first_diff"),
  detrended_col = c("detrended_data"),
  na_action = c("interpolate", "fail"),
  loess_span = 0.75,
  dj = 1/20,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  make_pval = TRUE,
  n_sim = 10,
  verbose = TRUE
)

Arguments

Value

An object of class "dm_wavelet" with elements:

call

The matched function call.

input_type

Either "raw" or "dm_detrended".

source

Series source actually used.

series

Character vector of analyzed series names.

time_unit

Detected time unit of the input series.

dt

Detected time step in native units.

dt_hours

Detected time step expressed in hours.

resolution_seconds

Detected time step in seconds.

data_used

Regularized time series used for analysis.

results

Named list of wavelet results, one per series. Each entry contains the original WaveletComp object plus time and period-in-hours information.

settings

Analysis settings.

Description

Computes cross-wavelet power and wavelet coherence between dendrometer series and climate variables using WaveletComp::analyze.coherency().

The function:

• crops dendrometer and climate inputs to their common time window,

• detects their temporal resolutions,

• resamples both to the coarser detected resolution,

• optionally interpolates missing values,

• optionally uses first differences of the dendrometer series,

• computes pairwise coherence for all selected tree/climate combinations.

Usage

dm_wavelet_coherence(
  dm,
  clim,
  TreeNum = "all",
  clim_vars = "all",
  source = c("auto", "raw", "detrended", "first_diff"),
  detrended_col = c("detrended_data"),
  dm_fun = c("mean", "max", "min", "sum"),
  clim_funs = "mean",
  na_action = c("interpolate", "fail"),
  loess_span = 0,
  dj = 1/20,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  window.type.t = 1,
  window.type.s = 1,
  window.size.t = 5,
  window.size.s = 1/4,
  make.pval = TRUE,
  make_pval = NULL,
  method = "white.noise",
  n.sim = 10,
  n_sim = NULL,
  verbose = TRUE
)

Arguments

Details

WaveletComp::analyze.coherency() expects two aligned series in one data frame plus a dt value in the analysis time units, and returns cross-wavelet power, coherence, phase angles, p-values, Fourier periods, and cone-of-influence fields.

Value

An object of class "dm_wavelet_coherence".

Examples

wc <- dm_wavelet_coherence(
  dm = gf_nepa17,
  clim = ktm_clim_hourly,
  TreeNum = 1,
  clim_vars = c("temp", "VPD"),
  source = "raw",
  dm_fun = "mean",
  clim_funs = c(temp = "mean", VPD = "mean"),
  loess_span = 0,
  make.pval = TRUE,
  n.sim = 10,
  verbose = FALSE
)

plot(wc)
plot(wc, type = "cross_power")
plot(wc, type = "average_coherence")
plot(wc, type = "phase")
plot(wc, type = "series")

Description

Reconstructs a selected oscillatory component, or a selected period band, from a dm_wavelet object using WaveletComp::reconstruct().

Requested periods are supplied in hours. They are internally converted to the native wavelet period units used when dm_wavelet() was computed, then passed to WaveletComp::reconstruct().

The function supports two modes:

• mode = "extract" returns the selected cycle or band itself.

• mode = "remove" returns the original series with the selected cycle or band removed.

Usage

dm_wavelet_reconstruct(
  x,
  series = NULL,
  mode = c("extract", "remove"),
  period_hours = NULL,
  lower_hours = NULL,
  upper_hours = NULL,
  lvl = 0,
  only_sig = TRUE,
  siglvl = 0.05,
  only_coi = FALSE,
  only_ridge = FALSE,
  rescale = FALSE,
  verbose = TRUE
)

Arguments

Value

An object of class "dm_wavelet_reconstruct" with elements:

call

Matched function call.

series

Selected series names.

mode

Reconstruction mode, either "extract" or "remove".

selection

A list describing the requested selection in hours and in native wavelet units.

results

Named list of WaveletComp::reconstruct() outputs.

reconstructed_long

Tidy table with columns TIME, series, original, reconstructed, difference, and filtered.

used_periods

Per-series table of periods actually used in the reconstruction, in native units and in hours.

filtered_wide

Wide table with TIME in the first column and one filtered series column per selected tree/series.

parent

Minimal metadata copied from the parent dm_wavelet object.

Examples

wv <- dm_wavelet(
  x = gf_nepa17,
  TreeNum = 1:2,
  source = "raw",
  make_pval = TRUE,
  verbose = FALSE
)

# extract circadian component
rec_extract <- dm_wavelet_reconstruct(
  wv,
  mode = "extract",
  lower_hours = 20,
  upper_hours = 28,
  only_sig = TRUE
)

# remove circadian component
rec_remove <- dm_wavelet_reconstruct(
  wv,
  mode = "remove",
  lower_hours = 20,
  upper_hours = 28,
  only_sig = TRUE
)

head(rec_extract$filtered_wide)
head(rec_remove$filtered_wide)

Description

Creates detrended standardized dendrometer series from objects returned by [dm.growth.fit()] or [dm.growth.fit.double()].

The function compares the original daily dendrometer series ('x$original_daily_data') with the fitted growth curve from 'x$fitted_data'. Because fitted values are stored on the processed scale used for modelling, the function first reconstructs fitted values on the original daily scale by adding back the seasonal baseline (the first non-missing original daily value of each series within each vegetation season).

Residuals are then calculated as:

$residual = observed_{daily} - fitted_{original\ scale}$

To obtain a detrended standardized series with mean equal to 1 and no negative values, residuals are transformed within each series × season_label as:

$z = \frac{residual - \min(residual) + \epsilon}{\mathrm{mean}(residual - \min(residual) + \epsilon)}$

where $\epsilon > 0$ is a small constant ensuring strictly positive values. If all residuals within a season are identical, the standardized series becomes a constant vector of 1.

Usage

dm.detrend.fit(
  x,
  series = NULL,
  seasons = NULL,
  epsilon = 1e-06,
  keep_na_rows = FALSE
)

Arguments

Details

The function uses x$original_daily_data, which must be present in the input object. If the object was created by an older version of [dm.growth.fit()] or [dm.growth.fit.double()] that did not store original_daily_data, the function will stop with an informative error.

Standardization is carried out separately within each vegetation season. This means the mean of the detrended standardized series is 1 for each series × season_label, not necessarily across the entire dataset.

Value

A list of class "dm_detrended" with elements:

call

The matched function call.

detrended_data

Wide-format tibble with metadata columns and one detrended standardized series column per dendrometer.

detrended_long

Long-format tibble containing original daily values, reconstructed fitted values on the original scale, residuals, shifted residuals, and detrended standardized values.

parameters

Per-series and per-season summary table containing baseline values and residual standardization parameters.

source_fit_statistics

The original x$fit_statistics table.

Examples

data(gf_nepa17)

fit1 <- dm.growth.fit(
  df = gf_nepa17,
  TreeNum = 1:2,
  method = "gompertz",
  year_mode = "yearly",
  verbose = FALSE
)

det1 <- dm.detrend.fit(fit1)
head(det1$detrended_data)
head(det1$parameters)

fit2 <- dm.growth.fit.double(
  df = gf_nepa17,
  TreeNum = 1,
  method = "gompertz",
  year_mode = "yearly",
  verbose = FALSE
)

det2 <- dm.detrend.fit(fit2)
head(det2$detrended_long)

Description

This function modells the annual growth of dendrometer data using gompertz function.

Usage

dm.fit.gompertz(
  df,
  CalYear,
  TreeNum,
  f_derivative = F,
  start = list(b = 0.5, k = 0.005),
  verbose = FALSE
)

Arguments

Value

A data frame with the modelled dendrometer series. If verbose = TRUE, returns a list with two data frames. The fitted curve and parameters.

Examples

library(dendRoAnalyst)
data(gf_nepa17)
gomp_fitted<-dm.fit.gompertz(df=gf_nepa17, TreeNum = 1, CalYear=2017)
head(gomp_fitted,10)

Description

Fits one or more growth models to dendrometer series and returns a compact table of evaluation statistics only.

This function is intended for method comparison rather than data extraction. It runs the selected fitting methods, aligns observed and fitted values on all non-missing observation days, and calculates goodness-of-fit measures for each fitted series and vegetation-season fit.

Supported single-curve methods are '"gam"', '"gompertz"', '"logistic"', '"richards"', '"loess"', and '"spline"', which are fitted using [dm.growth.fit()]. Supported bimodal methods are '"double_gompertz"' and '"double_richards"', which are fitted using [dm.growth.fit.double()].

The function returns only an evaluation table and does not return fitted curves, processed data, or parameter objects. It is therefore useful for comparing alternative fitting methods across series, years, or sites before selecting a final modeling approach.

Usage

dm.growth.evaluate(
  df,
  TreeNum = "all",
  methods = c("gam", "gompertz", "logistic", "richards", "loess", "spline",
    "double_gompertz", "double_richards"),
  years = "all",
  year_mode = c("yearly", "pooled"),
  fit_GRO = TRUE,
  site_mode = c("NH", "SH", "CS"),
  custom_veg_season = c(275, 274),
  growth_fraction = c(0.1, 0.9),
  min_unique_growth = 10,
  rate_threshold_fraction = 0.1,
  peak_separation_min = 10,
  valley_ratio_max = 0.4,
  min_relative_peak = 0.05,
  start_value_gompertz_parameters = list(a = NA_real_, b = NA_real_, k = NA_real_),
  start_value_richards_parameters = list(a = NA_real_, k = NA_real_, t0 = NA_real_, v =
    1),
  start_value_double_gompertz_parameters = list(a = NA_real_, k = NA_real_, t0 =
    NA_real_, a2 = NA_real_, k2 = NA_real_, t02 = NA_real_),
  start_value_double_richards_parameters = list(a = NA_real_, k = NA_real_, t0 =
    NA_real_, v = 1, a2 = NA_real_, k2 = NA_real_, t02 = NA_real_, v2 = 1),
  loess_span = 0.2,
  spline_df = 10,
  verbose = TRUE
)

Arguments

Details

Evaluation statistics are calculated by comparing observed daily values against fitted daily values on all days where observed values are available.

The returned metrics have the following interpretation:

• 'rmse': root mean squared error. Smaller values indicate closer fit.

• 'mae': mean absolute error. Smaller values indicate closer fit and are less sensitive to large deviations than RMSE.

• 'bias': mean fitted minus observed value. Positive values indicate overestimation and negative values indicate underestimation.

• 'r2': coefficient of determination, computed from residual and total sums of squares. Larger values indicate better fit.

• 'correlation': Pearson correlation between observed and fitted values. Larger values indicate stronger agreement in shape.

• 'nrmse': normalized RMSE, calculated as RMSE divided by the observed value range. This allows comparison across series with different magnitudes.

• 'rss': residual sum of squares.

• 'aic_approx' and 'bic_approx': approximate information criteria based on RSS and an effective parameter count rather than the exact likelihood returned by each modeling function.

The columns 'aic_approx' and 'bic_approx' are labeled as approximate because they are not extracted from the original model objects through a unified likelihood interface. Instead, they are computed from the residual sum of squares and an effective number of fitted parameters. They are therefore most useful for relative comparison among methods fitted to the same dataset.

Negative values of 'aic_approx' or 'bic_approx' are not an error. They occur naturally when the average residual variance is smaller than 1, because the logarithmic term in the information-criterion formula becomes negative. In practice, the absolute sign is not important; only differences among methods fitted to the same data should be interpreted.

For methods with flexible smoothness, such as GAM or spline, the effective parameter count is approximate. Consequently, 'aic_approx' and 'bic_approx' should be treated as heuristic ranking measures rather than exact likelihood-based criteria.

Value

A tibble with one row per fitted series and fit, containing:

method

Fitting method used for the row.

series

Series name.

fit_id

Vegetation-season label or '"pooled"'.

n_compare

Number of observed days used for comparison.

rmse

Root mean squared error.

mae

Mean absolute error.

bias

Mean fitted minus observed value.

r2

Coefficient of determination.

correlation

Pearson correlation between observed and fitted values.

nrmse

RMSE divided by the observed range.

rss

Residual sum of squares.

aic_approx

Approximate AIC based on RSS and effective parameter count.

bic_approx

Approximate BIC based on RSS and effective parameter count.

k_effective

Effective parameter count used in the approximate information criteria.

converged

Logical convergence flag returned by the fitting function.

model_note

Model note, warning, or error message returned by the fitting function.

See Also

[dm.growth.fit()], [dm.growth.fit.double()]

Description

Fits cumulative growth curves to daily dendrometer series using one of several supported methods: generalized additive model "gam", Gompertz "gompertz", logistic "logistic", Richards "richards", local regression "loess", or smoothing spline "spline".

The function:

• resamples dendrometer data to daily maxima using [dendro.resample()],

• assigns each daily observation to a vegetation season,

• optionally converts daily stem-size values to cumulative growth with fit_GRO = TRUE,

• fits one curve per series and season with year_mode = "yearly" or one pooled curve across retained seasons with year_mode = "pooled",

• estimates growing-season timing from the fitted cumulative-growth curve,

• additionally identifies active-growth timing from the fitted growth-rate curve.

For Gompertz, logistic, and Richards fits, the asymptote parameter a, representing maximum seasonal growth, can optionally be fixed to the observed maximum cumulative growth for that series and vegetation season. This is controlled by fix_a_to_observed_max.

Usage

dm.growth.fit(
  df,
  TreeNum = "all",
  method = c("gam", "gompertz", "logistic", "richards", "loess", "spline"),
  years = "all",
  year_mode = c("yearly", "pooled"),
  fit_GRO = TRUE,
  site_mode = c("NH", "SH", "CS"),
  custom_veg_season = c(275, 274),
  growth_fraction = c(0.1, 0.9),
  min_unique_growth = 10,
  rate_threshold_fraction = 0.1,
  fix_a_to_observed_max = FALSE,
  fixed_a_multiplier = 1,
  start_value_gompertz_parameters = list(a = NA_real_, b = NA_real_, k = NA_real_),
  start_value_richards_parameters = list(a = NA_real_, k = NA_real_, t0 = NA_real_, v =
    1),
  loess_span = 0.2,
  spline_df = 10,
  verbose = TRUE
)

Arguments

Details

The first column of df is treated as the time column and renamed to "TIME" internally. If it is not already a date-time object, the function attempts to parse it using [lubridate::parse_date_time()].

growth_start_* and growth_end_* are based on cumulative fitted growth. rate_start_* and rate_end_* are based on the fitted growth-rate curve.

For Gompertz, logistic, and Richards models, a is the upper asymptote. When fix_a_to_observed_max = TRUE, this parameter is not estimated by nonlinear least squares. Instead, it is fixed to:

$a = max(y_{obs}) \times fixed\_a\_multiplier$

where $y_{obs}$ is the observed cumulative growth for that series and vegetation season.

Value

An object of class "dm_growth_fit" with elements:

call

The matched function call.

original_daily_data

Raw daily dendrometer data after resampling to daily maxima and assigning vegetation seasons, but before centering and optional cumulative-growth transformation.

processed_data

Daily processed data used for fitting.

fitted_data

Daily fitted values on the full vegetation-season grid.

fit_statistics

Table with fit-level statistics and estimated timing.

fit_parameters

Table with fit-level model parameters and convergence information.

season_table

Vegetation seasons retained for fitting.

See Also

[summary.dm_growth_fit()], [print.dm_growth_fit()]

Examples

# fit <- dm.growth.fit(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "gompertz",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE
# )

# fit2 <- dm.growth.fit(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "richards",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE,
#   fixed_a_multiplier = 1.02
# )

Description

Fits bimodal cumulative growth curves to daily dendrometer series using either a double-Gompertz or double-Richards model.

Overall growing-season timing is derived from the fitted cumulative-growth curve using growth_fraction. Pulse-specific timing is derived from the derivative of the fitted curve using a pulse-specific relative rate threshold given by rate_threshold_fraction.

Pulse-specific timing is returned as NA when the fitted curve does not show a convincing two-pulse pattern according to derivative-based criteria.

If fallback_to_single = TRUE and no convincing two-pulse pattern is found, the function refits a corresponding single growth curve and returns that fit instead. In that case, overall season timing is still returned, but pulse-specific timing remains NA.

For double-Gompertz and double-Richards fits, the total asymptote can optionally be fixed to the observed maximum cumulative growth of the corresponding series and vegetation season. In the double-curve case, this means a + a2 is fixed, while the relative contribution of the first and second pulse is estimated.

Usage

dm.growth.fit.double(
  df,
  TreeNum = "all",
  method = c("gompertz", "richards"),
  years = "all",
  year_mode = c("yearly", "pooled"),
  fit_GRO = TRUE,
  site_mode = c("NH", "SH", "CS"),
  custom_veg_season = c(275, 274),
  growth_fraction = c(0.1, 0.9),
  min_unique_growth = 10,
  rate_threshold_fraction = 0.1,
  peak_separation_min = 10,
  valley_ratio_max = 0.4,
  min_relative_peak = 0.05,
  fallback_to_single = TRUE,
  fix_a_to_observed_max = FALSE,
  fixed_a_multiplier = 1,
  start_value_double_gompertz_parameters = list(a = NA_real_, k = NA_real_, t0 =
    NA_real_, a2 = NA_real_, k2 = NA_real_, t02 = NA_real_),
  start_value_double_richards_parameters = list(a = NA_real_, k = NA_real_, t0 =
    NA_real_, v = 1, a2 = NA_real_, k2 = NA_real_, t02 = NA_real_, v2 = 1),
  verbose = TRUE
)

Arguments

Details

The second pulse is constrained to occur after the first pulse, which improves numerical stability and reduces label switching between the two components.

For double-Gompertz and double-Richards models, the total seasonal asymptote is:

$a_{total} = a + a2$

When fix_a_to_observed_max = TRUE, the function fits:

$a + a2 = max(y_{obs}) \times fixed\_a\_multiplier$

where $y_{obs}$ is the observed cumulative growth of the selected dendrometer series and vegetation season.

The fitted pulse contributions are still returned as a and a2, and their sum should equal fixed_a_value, apart from small numerical rounding.

Non-applicable parameters are returned as NA. For example, b and b2 are relevant for double-Gompertz, while v and v2 are relevant for double-Richards.

Value

An object of class "dm_growth_fit" with elements:

call

The matched function call.

original_daily_data

Raw daily dendrometer data after resampling to daily maxima and assigning vegetation seasons, but before centering and optional cumulative-growth transformation.

processed_data

Daily processed data used for fitting.

fitted_data

Daily fitted values on the full vegetation-season grid.

fit_statistics

Fit-level statistics and estimated timing.

fit_parameters

Fit-level model parameters and convergence information.

season_table

Vegetation seasons retained for fitting.

See Also

[dm.growth.fit()], [summary.dm_growth_fit()], [print.dm_growth_fit()]

Examples

# Double-Gompertz with total seasonal asymptote fixed
# fit_gomp <- dm.growth.fit.double(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "gompertz",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE
# )

# Double-Richards with the total asymptote set 2 percent above observed max
# fit_rich <- dm.growth.fit.double(
#   df = dendro_data,
#   TreeNum = "all",
#   method = "richards",
#   year_mode = "yearly",
#   fit_GRO = TRUE,
#   fix_a_to_observed_max = TRUE,
#   fixed_a_multiplier = 1.02
# )

Description

Detects missing timestamps (based on provided resolution), inserts rows with NA, and optionally interpolates missing values using either cubic spline interpolation (na.spline) or seasonal decomposition interpolation (na.interp).

Optionally, the function can test the reliability of interpolation for increasing gap lengths (e.g., 6 hours to 3 days) using real data. This allows the user to assess how well a given interpolation method recovers missing values over different durations.

Usage

dm.na.interpolation(
  df,
  resolution,
  fill = FALSE,
  method = "spline",
  assess = FALSE,
  assess_lengths_hours = seq(6, 72, by = 6),
  assess_samples_per_length = 10,
  assess_buffer_hours = 6,
  assess_seed = NULL,
  verbose = FALSE
)

Arguments

Details

The assessment simulates interpolation over artificial gaps of different durations. For each dendrometer series and each gap length:

1. Random windows (with clean data) are selected.

2. Data in the window is temporarily set to NA.

3. The gap is interpolated using the selected method.

4. The predicted values are compared to the original (true) values using:

   • MAPE — Mean Absolute Percentage Error.

   • MdAPE — Median Absolute Percentage Error.

   • RMSE_pct — Root Mean Square Error (%).

   • Bias_pct — Mean Percentage Error (%).

   • Max_diff_abs — Mean absolute difference in daily maximum.

   • Min_diff_abs — Mean absolute difference in daily minimum.

   • Time_max_diff_h — Mean absolute difference in time of daily maximum (hours).

   • Time_min_diff_h — Mean absolute difference in time of daily minimum (hours).

Value

A list of class "dm_na_interpolation" with components:

$data

Data frame containing the original or gap-filled series.

$gap_info

Table describing timestamp gaps and internal NA runs.

$assessment

A tibble summarizing interpolation accuracy for each series and gap length, or NULL when assess = FALSE.

$filled

Logical indicating whether interpolation was performed.

$assessed

Logical indicating whether interpolation assessment was performed.

$method

Interpolation method used.

$resolution

Temporal resolution in minutes.

Examples

library(dendRoAnalyst)
data(nepa17)

#res0 <- dm.na.interpolation(nepa17[1:1000, ], resolution = 60)
#plot(res0)
#plot(res0, type = "gaps")

#res1 <- dm.na.interpolation(
#  nepa17[1:1000, ],
#  resolution = 60,
#  fill = TRUE,
#  method = "spline"
#)
#plot(res1)
#plot(res1, type = "gaps")
#plot(res1, type = "interpolation", original = nepa17[1:1000, ])

#res2 <- dm.na.interpolation(
#  nepa17[1:1000, ],
#  resolution = 60,
#  fill = TRUE,
#  method = "seasonal",
#  assess = TRUE
# )
#plot(res2)
#plot(res2, type = "assessment", metric = "MdAPE")

Description

The dendrometer data from three Chir pine tree collected in hourly resolution for 2017.

Usage

gf_nepa17

Format

A data frame with 8760 rows and 3 variables:

Time

datetime time of data recording

T2

double reading for first tree

T3

double reading for second tree

Description

Dendrometers generally have limited memory capacity beyond which they stop recording. To keep the measurement ongoing, they should be adjusted periodically, which can cause positive or negative jumps in the data. This function locates these artefacts and interactively adjusts them one by one.

Usage

i.jump.locator(
  df,
  TreeNum,
  detection_method = c("manual", "auto"),
  manual_threshold = NULL,
  auto_method_penalty = 10,
  adjustment_method = c("window_median", "point_diff"),
  adjust_window = 5,
  plot_window = 20,
  auto_every_second = TRUE,
  set_jump_point_na = FALSE
)

Arguments

Value

A dataframe containing jump-free dendrometer data.

Description

Dendrometers generally have limited memory capacity beyond which they stop recording. To keep the measurement ongoing, they should be adjusted periodically, which can cause positive or negative jumps in the data. This function locates these artefacts and adjusts them automatically. Unlike i.jump.locator , it can handle datasets with more than one dendrometer.

Usage

jump.locator(
  df,
  detection_method = c("manual", "auto"),
  manual_threshold = NULL,
  auto_method_penalty = 10,
  adjustment_method = c("window_median", "point_diff"),
  adjust_window = 5,
  auto_every_second = TRUE,
  set_jump_point_na = FALSE
)

Arguments

Value

A dataframe containing jump-free dendrometer data.

Examples

library(dendRoAnalyst)
data(nepa)

# Manual detection
jump_free_nepa <- jump.locator(
  df = nepa,
  detection_method = "manual",
  manual_threshold = 1
)

# Automatic detection with cpt.mean() and penalty = "Manual"
jump_free_nepa2 <- jump.locator(
  df = nepa,
  detection_method = "auto",
  auto_method_penalty = 10
)

Description

Hourly near-surface climate data for Kathmandu, Nepal, extracted from the Copernicus Climate Change Service (C3S) ERA5-Land reanalysis. The dataset is included to demonstrate climate–dendrometer workflows in dendRoAnalyst, including joining hourly climate data with dendrometer observations, event-based analyses, and wavelet-based analyses.

Usage

ktm_clim_hourly

Format

A data frame with hourly observations and 5 variables:

TIME

Date-time stamp of the hourly observation.

temp

Air temperature in degree Celsius.

prec

Precipitation in millimetres.

VPD

Vapour pressure deficit in kPa.

RH

Relative humidity in percent.

Details

ktm_clim_hourly contains a single-location hourly climate time series for Kathmandu derived from ERA5-Land. ERA5-Land is a global land-surface reanalysis produced by replaying the land component of ERA5 at enhanced spatial resolution and is widely used for land-surface and ecohydrological applications.

This dataset is intended as an example climate input for dendRoAnalyst. It can be used, for example, with functions that join dendrometer and climate data, calculate phase-climate relations, run event analyses, or perform wavelet and wavelet-coherence analyses.

Users should check the exact temporal coverage of the object in their local installation, for example with:

range(ktm_clim_hourly$TIME)

Source

Extracted from the Copernicus Climate Change Service (C3S) Climate Data Store ERA5-Land reanalysis product:

Muñoz-Sabater, J. (2019). ERA5-Land hourly data from 1950 to present. Copernicus Climate Change Service (C3S) Climate Data Store (CDS).

References

Muñoz-Sabater, J., Dutra, E., Agustí-Panareda, A., Albergel, C., Arduini, G., Balsamo, G., Boussetta, S., Choulga, M., Harrigan, S., Hersbach, H., Martens, B., Miralles, D. G., Piles, M., Rodríguez-Fernández, N. J., Zsoter, E., Buontempo, C., and Thépaut, J.-N. (2021). ERA5-Land: a state-of-the-art global reanalysis dataset for land applications. Earth System Science Data, 13, 4349–4383.

Description

This file contains daily rainfall data of Kathmandu. The source of this data is 'Government of Nepal, Department of Hydrology and Meteorology'.

Usage

ktm_rain17

Format

A data frame with 365 rows and 2 variables:

TIME

Date in YYYY-MM-DD format.

rainfall

double rainfall in millimeters

Source

http://www.mfd.gov.np/city?id=31/

Description

Computes a mean detrended dendrometer series across multiple trees from the output of dm.detrend.fit().

This is useful for creating one representative detrended series for a species, site, or treatment group after detrending individual dendrometer series.

Optionally, the function can:

• calculate a robust mean using a trimmed mean across trees,

• remove temporal autocorrelation from the mean detrended series using forecast::auto.arima(),

• rescale the autocorrelation-removed series so it stays non-negative and has mean = 1 within each vegetation season.

Usage

mean_detrended.dm(
  detrended_dm,
  series = NULL,
  ac1.remove = TRUE,
  robust.mean = TRUE,
  trim = 0.15,
  seasonal_rescale = TRUE
)

Arguments

Value

A tibble of class "mean_dm_detrended" containing:

• metadata columns copied from the detrended input,

• STD_DDM: the mean detrended series,

• RES_DDM: the autocorrelation-removed mean detrended series (returned only when ac1.remove = TRUE).

Examples

fit1 <- dm.growth.fit(
  df = gf_nepa17,
  TreeNum = 1:2,
  method = "gompertz",
  year_mode = "yearly",
  verbose = FALSE
)

det1 <- dm.detrend.fit(fit1)

m_det <- mean_detrended.dm(det1)
head(m_det, 10)

Description

Calculates running correlations between a selected daily dendrometer summary and one or more climate variables. The user can select the daily dendrometer statistic, correlation method, optional bootstrap confidence intervals, and lagged / antecedent climate transformations.

Usage

mov.cor.dm(
  df,
  Clim,
  TreeNum,
  win_size,
  cor_method = c("pearson", "kendall", "spearman"),
  boot = FALSE,
  R = 1000,
  boot.ci = 0.05,
  set_seed = 1,
  dm_stat = c("mean", "min", "max", "median", "amplitude", "change"),
  clim_vars = NULL,
  lag_days = 0,
  accum_days = 1,
  clim_fun = "raw",
  min_complete = NULL,
  p_adjust_method = "BH"
)

Arguments

Details

The dendrometer series is first aggregated to daily resolution. The daily dendrometer statistic used for correlation is controlled by dm_stat:

• "mean": daily mean dendrometer value

• "min": daily minimum

• "max": daily maximum

• "median": daily median

• "amplitude": daily amplitude (max - min)

• "change": day-to-day change in the daily mean

Users can choose the climate variables to analyze via clim_vars. Climate transformation settings can be given as:

• a single value applied to all selected climate variables

• an unnamed vector with one value per selected climate variable

• a named vector mapping each selected climate variable to its own setting

This applies to clim_fun, lag_days, and accum_days.

Value

A list with class "mov_cor_dm" (and "mov_cor_dm_boot" if bootstrapped) containing:

• results: named list of tibbles, one per climate variable

• metadata: analysis metadata

• call: the matched function call

Examples

library(dendRoAnalyst)
data(gf_nepa17)
data(ktm_rain17)

# one common climate transformation for all selected variables
out_corr <- mov.cor.dm(
  df = gf_nepa17,
  Clim = ktm_rain17,
  TreeNum = 1,
  win_size = 21,
  clim_fun = "raw"
)
print(out_corr)
summary(out_corr)

# variable-specific climate transformations
out_varfun <- mov.cor.dm(
  df = gf_nepa17,
  Clim = ktm_rain17,
  TreeNum = 1,
  win_size = 21,
  clim_vars = c("rainfall"),
  clim_fun = c(rainfall = "sum"),
  lag_days = c(rainfall = 1),
  accum_days = c(rainfall = 7)
)

# bootstrap confidence intervals
out_boot <- mov.cor.dm(
  df = gf_nepa17,
  Clim = ktm_rain17,
  TreeNum = 1,
  win_size = 21,
  boot = TRUE,
  R = 250
)
summary(out_boot)

Description

Dendrometer data from three Chir pine trees collected in hourly resolution for 2 years.

Usage

nepa

Format

A data frame with 14534 rows and 3 variables:

Time

datetime time of data recording

T2

double reading for first tree

T3

double reading for second tree

Description

Dendrometer data from three Chir pine tree collected in hourly resolution for 2017.

Usage

nepa17

Format

A data frame with 8753 rows and 3 variables: