% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/phase.sc.R
\name{phase.sc}
\alias{phase.sc}
\title{Application of the stem-cycle approach to classify dendrometer phases}
\usage{
phase.sc(df, TreeNum, smoothing = NULL)
}
\arguments{
\item{df}{A data frame with the first column containing date-time in the format
\code{"yyyy-mm-dd HH:MM:SS"} (or convertible to \code{POSIXct}), followed by one or more
dendrometer measurement columns (mm).}

\item{TreeNum}{Integer. The index of the dendrometer column to analyze.
For example, \code{TreeNum = 1} selects the first dendrometer series after the time column.}

\item{smoothing}{Numeric or \code{NULL}. Length of the smoothing window in hours
(1–24). If \code{NULL} (default), no smoothing is applied. If provided, the
dendrometer series is smoothed using \code{smooth_dm(method = "median_mean")}
prior to phase classification.}
}
\value{
A list of class \code{"SC_output"} containing:
\describe{
  \item{SC_cycle}{A tibble with one row per contiguous phase, including:
    \itemize{
      \item \code{Phases} – Phase type (1 = Shrinkage, 2 = Expansion, 3 = Increment)
      \item \code{Start}, \code{End} – \code{POSIXct} start and end time of the phase
      \item \code{Duration_h}, \code{Duration_m} – Phase duration (hours, minutes)
      \item \code{Magnitude} – Change in dendrometer value during the phase (measurement unit)
      \item \code{rate} – Rate of change expressed in (\code{Magnitude*1000/Duration_h}) (eg. \eqn{\mu}m/hour)
      \item \code{DOY} – Day-of-year at phase start
    }}
  \item{SC_phase}{A tibble of point-level values including:
    \itemize{
      \item \code{TIME} – timestamp
      \item \code{dm} – dendrometer measurement
      \item \code{Phases} – phase assignment for each timestamp
    }}
}
}
\description{
Implements the \strong{stem-cycle approach} (Downes et al., 1999; Deslauriers et al., 2011)
to divide a dendrometer time series into three biologically meaningful phases:
\enumerate{
  \item \strong{Shrinkage} (phase = 1): the dendrometer reading decreases
        compared to the previous reading.
  \item \strong{Expansion} (phase = 2): the dendrometer reading increases
        compared to the previous reading, but remains below the previous maximum.
  \item \strong{Increment} (phase = 3): the dendrometer reading exceeds
        the previous maximum (irreversible stem growth).
}

For each contiguous phase, the function calculates duration, magnitude, rate,
and assigns day-of-year information. Optionally, the dendrometer series may be
smoothed before phase calculation to reduce noise and spurious phase changes.
}
\details{
Classification uses the cumulative maximum of the dendrometer series:
\itemize{
  \item If the cumulative maximum increases, the phase is labeled \emph{Increment} (3).
  \item If the cumulative maximum is constant and the first difference is positive,
        the phase is \emph{Expansion} (2).
  \item If the cumulative maximum is constant and the first difference is negative,
        the phase is \emph{Shrinkage} (1).
}

The function returns both phase-level summaries (\code{SC_cycle}) and point-level
labels (\code{SC_phase}). Optional smoothing uses \code{smooth_dm} with
\code{method = "median_mean"} and a window length between 1–24 hours.
}
\examples{
\donttest{
library(dendRoAnalyst)
data(gf_nepa17)

# Apply stem-cycle approach without smoothing
sc1 <- phase.sc(df = gf_nepa17, TreeNum = 1)
head(sc1$SC_cycle, 5)
head(sc1$SC_phase, 5)

# Apply with 12-hour smoothing to reduce noise
sc2 <- phase.sc(df = gf_nepa17, TreeNum = 1, smoothing = 12)
head(sc2$SC_cycle, 5)
}

}
\references{
Deslauriers A, Rossi S, Turcotte A, Morin H, Krause C (2011)
A three-step procedure in SAS to analyze the time series from automatic dendrometers.
\emph{Dendrochronologia} 29:151–161. \doi{10.1016/j.dendro.2011.01.008}

Downes G, Beadle C, Worledge D (1999)
Daily stem growth patterns in irrigated \emph{Eucalyptus globulus} and \emph{E. nitens} in relation to climate.
\emph{Trees} 14:102–111. \doi{10.1007/PL00009752}
}
\seealso{
\code{\link{phase.zg}} for the zero-growth approach;
\code{\link{smooth_dm}} for smoothing dendrometer series.
}
