% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_normalize.R
\name{dm_standardize}
\alias{dm_standardize}
\title{Standardize dendrometer series within seasonal years}
\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{
\item{df}{A data frame whose first column contains date-time
(\code{yyyy-mm-dd HH:MM:SS}, \code{POSIXct}, or \code{Date}) and all
remaining columns are dendrometer series.}

\item{season_type}{One of \code{"NH"}, \code{"SH"}, or \code{"CS"}.}

\item{CS_doys}{Optional numeric vector of length 2 defining the start and end
DOY for \code{season_type = "CS"}.}

\item{method}{Standardization method. One of:
\itemize{
  \item \code{"center"}: subtract seasonal reference value
  \item \code{"amplitude"}: subtract reference and divide by seasonal range
  \item \code{"robust_amplitude"}: subtract reference and divide by
        \code{Q_high - Q_low}
  \item \code{"minmax"}: rescale to \code{(x - min)/(max - min)}
  \item \code{"zscore"}: seasonal z-score
  \item \code{"robust_zscore"}: robust seasonal z-score using median and MAD
  \item \code{"percentile"}: convert seasonal values to percentiles in \eqn{[0,1]}
}}

\item{ref_type}{Reference-value definition for methods that need a reference
(\code{"center"}, \code{"amplitude"}, \code{"robust_amplitude"}). One of:
\itemize{
  \item \code{"first_value"}: first non-missing value in the seasonal year
  \item \code{"first_n_days"}: mean of the first \code{ref_n_days} unique days
  \item \code{"ref_window"}: mean of values within \code{ref_doys}
}}

\item{ref_n_days}{Number of initial days used when \code{ref_type = "first_n_days"}.}

\item{ref_doys}{Optional numeric vector of length 2 defining a DOY reference
window when \code{ref_type = "ref_window"}.}

\item{q_low}{Lower quantile used by \code{method = "robust_amplitude"}.}

\item{q_high}{Upper quantile used by \code{method = "robust_amplitude"}.}
}
\value{
A list of class \code{"dm_standardized"} containing:
\itemize{
  \item \code{data}: wide data frame with columns
    \code{TIME}, \code{season_year}, \code{in_season}, and standardized dendrometer series
  \item \code{parameters}: tibble with one row per tree and seasonal year,
    summarizing the reference value and scaling denominator used
  \item \code{metadata}: method and seasonal-year settings
}

For \code{season_type = "CS"}, observations outside the custom season are
retained in \code{data}, but their standardized values are set to \code{NA}
and \code{in_season = FALSE}.
}
\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:
\itemize{
  \item \code{"NH"}: Northern Hemisphere year, from \strong{01 Jan} to \strong{31 Dec}
  \item \code{"SH"}: Southern Hemisphere year, from \strong{01 Jul} to \strong{30 Jun} of the next year
  \item \code{"CS"}: Custom season defined by \code{CS_doys = c(doy1, doy2)}
}

For \code{season_type = "CS"}:
\itemize{
  \item if \code{CS_doys[1] <= CS_doys[2]}, the season stays within one calendar year
  \item if \code{CS_doys[1] > CS_doys[2]}, the season wraps across years
}

Standardization is applied separately for each dendrometer series and each
seasonal year.
}
\examples{
\donttest{
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)
}

}
