% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compute_rolling_value.R
\name{compute_rolling_value}
\alias{compute_rolling_value}
\title{Compute a Rolling Value by Period}
\usage{
compute_rolling_value(
  data,
  .f,
  period = "month",
  periods = 12,
  min_obs = periods,
  data_options = NULL
)
}
\arguments{
\item{data}{A data frame with a date column of class \code{Date}, named according
to \code{data_options$date} (default \code{"date"}).}

\item{.f}{A function applied to each window. Receives a data-frame slice
(complete cases only) and must return a single scalar value.}

\item{period}{A string specifying the period for rolling windows
(e.g., \code{"month"}, \code{"quarter"}, \code{"year"}).}

\item{periods}{Number of periods to include in the rolling window.}

\item{min_obs}{Minimum number of non-missing rows required per window.
Defaults to \code{periods}.}

\item{data_options}{A list of class \code{tidyfinance_data_options} (created via
\code{\link[=data_options]{data_options()}}) specifying column name mappings. The \code{date} element is
used to specify the date column. Uses \code{\link[=data_options]{data_options()}} default if \code{NULL}:
\code{"date" = "date"}.}
}
\value{
A numeric vector aligned with the rows of \code{data}.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

Applies an arbitrary summary function over rolling time-period windows.
Each window spans \code{periods} units of \code{period} (e.g., 12 months). Before
calling \code{.f}, rows with any missing values are dropped from the window;
if fewer than \code{min_obs} rows remain, the result is \code{NA_real_} instead.
}
\examples{
library(dplyr)

# Rolling standard deviation
set.seed(42)
df <- tibble(
  date = seq.Date(
    from = as.Date("2020-01-01"),
    by = "month",
    length.out = 24
  ),
  value = rnorm(24)
)

df |>
  mutate(
    rolling_sd = compute_rolling_value(
      pick(everything()),
      .f = ~ sd(.x$value, na.rm = TRUE),
      period = "month",
      periods = 4,
      min_obs = 2
    )
  )

# Rolling last residual from a regression
set.seed(42)
df_reg <- tibble(
  date = seq.Date(
    from = as.Date("2020-01-01"),
    by = "month",
    length.out = 60
  ),
  ret_excess = rnorm(60, 0, 0.05),
  mkt_excess = rnorm(60, 0, 0.04),
  smb = rnorm(60, 0, 0.03),
  hml = rnorm(60, 0, 0.03)
)

df_reg |>
  mutate(
    residual = compute_rolling_value(
      pick(everything()),
      .f = \(x) {
        last(lm(ret_excess ~ mkt_excess + smb + hml, data = x)$residuals)
      },
      period = "month",
      periods = 24,
      min_obs = 12
    )
  )

# Rolling cumulative-return-to-SD ratio
set.seed(42)
df_resid <- tibble(
  date = seq.Date(
    from = as.Date("2020-01-01"),
    by = "month",
    length.out = 24
  ),
  int_roll_residual = rnorm(24, 0, 0.02)
)

df_resid |>
  mutate(
    return_to_sd = compute_rolling_value(
      pick(everything()),
      .f = ~ (prod(1 + .x$int_roll_residual) - 1) / sd(.x$int_roll_residual),
      period = "month",
      periods = 12,
      min_obs = 12
    )
  )

}
\seealso{
Other rolling and lagging functions: 
\code{\link{add_lagged_columns}()},
\code{\link{join_lagged_values}()}
}
\concept{rolling and lagging functions}
