From 61a44fe77b7377c220749e3f2aa64e3185c69ccf Mon Sep 17 00:00:00 2001
From: Leonidas Zhak <70497898+LeonidasZhak@users.noreply.github.com>
Date: Sat, 6 Jun 2026 23:55:32 +0800
Subject: [PATCH] docs: add panel data example to summary-index.Rd

Add a grouped rolling mean example showing the Stata-to-R migration
pattern for panel data. This is the most common use case for users
migrating from Stata's rangestat/bysort + rolling operations.

The example shows:
- Panel data with two firms and irregular dates
- 3-day rolling mean within each firm using slide_index_mean()
- Date-aware windows that respect gaps in the series

Related: #193
---
 R/summary-index.R    | 24 ++++++++++++++++++++++++
 man/summary-index.Rd | 24 ++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/R/summary-index.R b/R/summary-index.R
index c59368a..fe3ba76 100644
--- a/R/summary-index.R
+++ b/R/summary-index.R
@@ -63,6 +63,30 @@
 #'
 #' # Only evaluate the sum on windows that have the potential to be complete
 #' slide_index_sum(x, i, before = 2, after = 1, complete = TRUE)
+#'
+#' # ---------------------------------------------------------------------------
+#' # Panel data (grouped rolling operations)
+#'
+#' # In Stata, the equivalent of grouped rolling means is:
+#' #   rangestat (mean) roll_mean = sales, int(date -2 0) by(firm)
+#'
+#' # slider + dplyr replicates this pattern with group_by():
+#' df <- data.frame(
+#'   firm = rep(c("A", "B"), each = 4),
+#'   date = as.Date(c(
+#'     "2020-01-01", "2020-01-02", "2020-01-05", "2020-01-06",
+#'     "2020-01-01", "2020-01-03", "2020-01-04", "2020-01-07"
+#'   )),
+#'   sales = c(10, 12, 15, 13, 20, 22, 18, 25)
+#' )
+#'
+#' # 3-day rolling mean within each firm, respecting irregular date gaps
+#' df$roll_mean <- unlist(
+#'   lapply(split(df, df$firm), function(g) {
+#'     slide_index_mean(g$sales, g$date, before = 2)
+#'   })
+#' )
+#' df
 slide_index_sum <- function(
   x,
   i,
diff --git a/man/summary-index.Rd b/man/summary-index.Rd
index e1ed27a..7d4af46 100644
--- a/man/summary-index.Rd
+++ b/man/summary-index.Rd
@@ -183,6 +183,30 @@ slide_index_mean(x, i, before = 2)
 
 # Only evaluate the sum on windows that have the potential to be complete
 slide_index_sum(x, i, before = 2, after = 1, complete = TRUE)
+
+# ---------------------------------------------------------------------------
+# Panel data (grouped rolling operations)
+
+# In Stata, the equivalent of grouped rolling means is:
+#   rangestat (mean) roll_mean = sales, int(date -2 0) by(firm)
+
+# slider + dplyr replicates this pattern with group_by():
+df <- data.frame(
+  firm = rep(c("A", "B"), each = 4),
+  date = as.Date(c(
+    "2020-01-01", "2020-01-02", "2020-01-05", "2020-01-06",
+    "2020-01-01", "2020-01-03", "2020-01-04", "2020-01-07"
+  )),
+  sales = c(10, 12, 15, 13, 20, 22, 18, 25)
+)
+
+# 3-day rolling mean within each firm, respecting irregular date gaps
+df$roll_mean <- unlist(
+  lapply(split(df, df$firm), function(g) {
+    slide_index_mean(g$sales, g$date, before = 2)
+  })
+)
+df
 }
 \seealso{
 \code{\link[=slide_sum]{slide_sum()}}