---
title: "News in latest version of 'dendRoAnalyst' package"
author: "Sugam Aryal"
date: "2026-04-06"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{News in latest version of 'dendRoAnalyst' package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

------------------------------------------------------------------------

## What's new in dendRoAnalyst 0.1.6

This release focuses on speed, clarity, and reproducibility. Many core
functions were refactored to be more consistent in their inputs and outputs,
several new utilities were added, and plotting responsibilities were split into
dedicated helpers. The package now follows a more workflow-oriented design:
import, quality control, conditioning, phase detection, climate integration,
growth modelling, detrending, and event-based analyses can be run in a more
transparent sequence.

The release also strengthens reproducibility by using explicit namespaces where
needed, clearer output classes, more dedicated summary/plot methods, and safer
handling of gaps, smoothing, and climate joins.

### 1. Core phase engines are now more modular

The two main phase engines concentrate on phase assignment and statistics,
while separate helpers handle visualization and climate integration:

- `phase.sc()` applies the Stem-Cycle approach and returns phase-level and
  cycle-level summaries for shrinkage, expansion, and increment.
- `phase.zg()` applies the Zero-Growth approach and returns timestamp-level,
  phase-level, and cycle-level summaries for GRO and TWD.
- `twd.maxima()` locates local maxima within TWD phases and helps bridge
  stem-water-deficit interpretation with phase-based workflows.

### 2. Dedicated plotting methods for phase outputs

Plotting is now separated from computation so users can calculate once and
visualize in multiple ways:

- `plot.SC_output()` plots stem-cycle outputs from `phase.sc()`.
- `plot.ZG_output()` plots GRO and TWD outputs from `phase.zg()`.
- `dm_plot_climate()` and `dm_plot_climate_compare()` provide climate-focused
  views for dendrometer–climate interpretation.
- `plot_event_climate_box()` and `plot_event_climate_relation()` add targeted
  visualization for event-based climate summaries.

### 3. Expanded data import, checking, and quality control

Several tools now support more robust input handling and early quality checks:

- `read.dendrometer()` reads TXT, CSV, TSV, and Excel dendrometer files with
  improved datetime parsing.
- `read.climate()` supports climate import in the same workflow style used for
  dendrometer data.
- `reso_dm()` detects the effective temporal resolution of a time series and
  flags irregularities.
- `jump.locator()` helps identify jumps or abrupt steps in dendrometer series.
- `i.jump.locator()` provides interactive jump inspection for manual review.

### 4. New and upgraded gap-handling tools

Gap handling has been expanded substantially:

- `dm.na.interpolation()` detects missing timestamps, inserts explicit gaps,
  interpolates missing values, and can test interpolation performance over
  multiple gap lengths.
- `plot.dm_na_interpolation()`, `plot_dm_gaps()`, `plot_dm_interpolation()`,
  and `plot_dm_assessment()` provide dedicated visual diagnostics for missing
  data and interpolation quality.
- `network.interpolation()` fills gaps in focal dendrometer series using a
  co-recorded network of reference trees.
- `plot.network_interpolation()` visualizes observed values, interpolated
  segments, donor-network behavior, and optional uncertainty bands.

Together, these functions make it easier to compare interpolation strategies
for both single-tree and site-network workflows.

### 5. Data conditioning tools are broader and clearer

Several conditioning functions were added or refined to make preprocessing more
explicit:

- `dendro.resample()` resamples dendrometer or climate data to coarser or finer
  temporal resolution.
- `dendro.truncate()` truncates a dataset by year and/or day-of-year windows.
- `smooth_dm()` provides compact smoothing options for dendrometer series,
  including median-mean, penalized spline, Savitzky–Golay, exponential moving
  average, and loess approaches.
- `dm_standardize()` standardizes dendrometer series for cross-tree comparison.

These functions make it easier to build reproducible preprocessing pipelines
before phase detection or modelling.

### 6. Daily summaries are now easier to compute and inspect

The package adds a more structured daily-analysis layer:

- `daily.data()` computes daily minima, maxima, timing of extrema, mean,
  median, amplitude, lag metrics, and day-to-day status.
- `plot.daily_output()` provides a unified plotting interface for objects
  returned by `daily.data()`.
- `dm_daily_clim()` summarizes climate variables at the daily scale.
- `dm_subdaily_clim()` derives subdaily climate summaries aligned to
  higher-frequency analyses.

### 7. Climate joining helpers support both daily and subdaily workflows

Climate can now be attached more directly to dendrometer outputs:

- `dm_join_daily_clim()` joins daily climate summaries to `daily.data()`
  outputs.
- `dm_join_subdaily_clim()` joins timestamp-level climate features to
  point-level dendrometer outputs.
- `dm_join_phase_clim()` summarizes climate conditions within phase windows
  from `phase.sc()` or `phase.zg()`.
- `dm_add_climate()` provides a higher-level helper to enrich dendrometer
  outputs with climate information.

These functions support more consistent dendrometer–climate analyses across
raw, daily, and phase-based outputs.

### 8. Event-based phase and climate tools were added

A new event-oriented layer helps summarize climate conditions during biological
or environmental events:

- `dm_event_climate()` extracts climate information for identified events.
- `dm_event_climate_summary()` summarizes climate statistics for event windows.
- `dm_event_climate_test()` supports inferential comparisons among event types
  or groups.

This makes it easier to move from descriptive phase detection to event-based
hypothesis testing.

### 9. Growth modelling is more flexible and easier to evaluate

Growth fitting has been extended well beyond a single legacy curve:

- `dm.fit.gompertz()` remains available as a legacy annual Gompertz option.
- `dm.growth.fit()` fits single-curve models such as GAM, Gompertz, logistic,
  Richards, loess, and spline by vegetation season.
- `dm.growth.fit.double()` fits bimodal growth trajectories using double
  Gompertz or double Richards formulations.
- `plot.dm_growth_fit()` provides multiple visual summaries of fitted growth
  trajectories, timing, residuals, and parameters.
- `dm.growth.evaluate()` compares alternative fitting methods using fit
  statistics.
- `plot.dm_growth_evaluation()` visualizes method-comparison metrics.
- `print.dm_growth_fit()`, `summary.dm_growth_fit()`, and
  `print.summary.dm_growth_fit()` improve interpretability of fitted objects.

This workflow makes it easier to compare competing models rather than relying
on a single default growth curve.

### 10. Detrending is now better linked to growth fitting

The detrending workflow is more explicit and more tightly integrated with the
new growth-fit objects:

- `dm.detrend.fit()` creates detrended standardized series from fitted growth
  models.
- `plot.dm_detrended()` visualizes original data, fitted curves, residuals,
  and detrended series.
- `mean_detrended.dm()` aggregates detrended series across trees, with options
  for robust averaging and autocorrelation-aware summaries.
- `plot.mean_dm_detrended()` visualizes the resulting mean detrended series.

This makes it easier to move from single-tree modelling to species-, site-, or
treatment-level detrended signals.

### 11. Superposed epoch analysis now has a fuller toolkit

The package now includes a more complete superposed-epoch workflow:

- `dm_event_times()` helps define event timing.
- `dm_epoch_extract()` extracts windows around those events.
- `dm_epoch_test()` performs superposed epoch analyses.
- `summary.dm_epoch()`, `print.summary.dm_epoch()`, and `plot.dm_epoch()`
  support inspection and presentation of epoch results.

These functions make it easier to study average dendrometer or climate
responses around recurring events.

### 12. Wavelet tools were added for time-frequency analysis

A new wavelet toolkit supports multiscale analysis of dendrometer dynamics:

- `dm_wavelet()` performs wavelet decomposition of dendrometer series.
- `summary.dm_wavelet()`, `print.summary.dm_wavelet()`, and `plot.dm_wavelet()`
  support interpretation of the decomposition.
- `dm_wavelet_reconstruct()` reconstructs selected components of the wavelet
  signal.
- `summary.dm_wavelet_reconstruct()`,
  `print.summary.dm_wavelet_reconstruct()`, and
  `plot.dm_wavelet_reconstruct()` help evaluate reconstruction output.
- `dm_wavelet_coherence()` analyzes coherence between dendrometer and climate
  signals across scales.
- `plot.dm_wavelet_coherence()` visualizes coherence structure.

These additions broaden the package from time-domain analyses to
multiscale time-frequency exploration.

### 13. Moving climate–growth correlations were upgraded

Running climate–growth relationships now have a more complete summary and
plotting framework:

- `mov.cor.dm()` calculates moving correlations between daily dendrometer
  summaries and climate variables.
- `summary.mov_cor_dm()`, `print.summary_mov_cor_dm()`, and
  `print.mov_cor_dm()` support object inspection.
- `plot.mov_cor_dm()`, `plot_mov.cor()`, `plot.mov.cor()`,
  `plot.mov.cor.boot()`, and `plot.summary_mov_cor_dm()` provide multiple
  ways to visualize running correlations, significance, and peak windows.

### 14. Harsh-climate analysis is more complete

The climate-stress workflow now covers detection, summarization, testing, and
plotting:

- `clim.twd()` identifies adverse climate periods and calculates relative
  dendrometer change.
- `clim.twd.stats` is available as `clim.twd.stats()` for grouped summaries at
  tree, species, or site level.
- `summary.clim_twd_stats()` and `print.summary.clim_twd_stats()` summarize
  grouped results.
- `plot.clim_twd_stats()` visualizes grouped climate-stress trajectories and
  event metrics.
- `clim.twd.test()` adds inferential comparison among groups or treatments.
- `summary.clim_twd_test()`, `print.summary.clim_twd_test()`, and
  `plot.clim_twd_test()` support reporting and visualization of test results.

This makes harsh-climate analysis more useful for both exploratory and
comparative studies.

### 15. Package design now emphasizes compute-first, plot-second workflows

Across the package, many functions now return richer objects with dedicated
print, summary, and plot methods. This makes analyses easier to reproduce,
compare, and document. In practice, users can now:

- compute a result once,
- inspect the returned object,
- summarize it with dedicated helpers, and
- generate multiple plot types without repeating the analysis.

This separation is especially visible in the phase, growth-fit, moving
correlation, harsh-climate, interpolation, and wavelet workflows.

### Heads-up on namespaces

The package now more consistently uses explicit namespace calls internally to
avoid clashes such as `stats::filter()` versus `dplyr::filter()`. If you work
interactively and use both packages, it can still be helpful to set:

```{r, eval=FALSE}
conflicted::conflict_prefer("filter", "dplyr")
```

### In short

`dendRoAnalyst` 0.1.6 is no longer just a collection of stand-alone utilities.
It now behaves more like a connected analysis framework for dendrometer data,
with clearer transitions among import, quality control, interpolation,
conditioning, phase classification, climate integration, growth modelling,
detrending, event analysis, moving correlations, wavelets, and climate-stress
assessment.