% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cat2cat_agg.R
\name{cat2cat_agg}
\alias{cat2cat_agg}
\title{Manual mapping for an aggregated panel dataset}
\usage{
cat2cat_agg(
  data = list(old = NULL, new = NULL, cat_var_old = NULL, cat_var_new = NULL, time_var =
    NULL, freq_var = NULL),
  ...
)
}
\arguments{
\item{data}{Named list with 5-6 fields describing the datasets:
\describe{
  \item{\code{old}}{\code{data.frame} - older time period (one row per category).}
  \item{\code{new}}{\code{data.frame} - newer time period (one row per category).}
  \item{\code{cat_var}}{\code{character(1)} - (deprecated) category variable name
    if identical in both periods. Use \code{cat_var_old}/\code{cat_var_new} instead.}
  \item{\code{cat_var_old}}{\code{character(1)} - category variable name in old period.}
  \item{\code{cat_var_new}}{\code{character(1)} - category variable name in new period.}
  \item{\code{time_var}}{\code{character(1)} - time variable name.}
  \item{\code{freq_var}}{\code{character(1)} - frequency/count variable used to
    compute proportions when splitting one category into many.}
}}

\item{...}{Mapping equations specifying how categories relate across periods.
See **Equation syntax** in Details.}
}
\value{
A named list with two elements:
\describe{
  \item{\code{$old}}{\code{data.frame} - old period with \code{prop_c2c} column added.
    Categories may be replicated if split by backward equations.}
  \item{\code{$new}}{\code{data.frame} - new period with \code{prop_c2c} column added.
    Categories may be replicated if split by forward equations.}
}
The \code{prop_c2c} column contains the proportion (0-1) to apply when
aggregating. For rows not affected by any equation, \code{prop_c2c = 1}.
For split categories, proportions sum to 1 within the original category.
}
\description{
Applies user-defined mapping equations to redistribute aggregated counts
(and other numeric columns) when categorical encodings change between
time periods. Unlike \code{\link{cat2cat}}, which works on micro-data,
this function operates on pre-aggregated data where each row represents
a category with associated counts/totals.
}
\details{
\strong{Equation syntax}

Each equation has the form:
\preformatted{OLD_SIDE  DIRECTION  NEW_SIDE}

where:
\itemize{
  \item \strong{OLD_SIDE} - one or more old-period category names
    (use \code{c(A, B)} for multiple)
  \item \strong{DIRECTION} - one of:
    \itemize{
      \item \code{\%>\%} or \code{>} - \strong{forward}: replicates the NEW period,
        renaming/splitting new categories to match old encoding
      \item \code{\%<\%} or \code{<} - \strong{backward}: replicates the OLD period,
        renaming/splitting old categories to match new encoding
    }
  \item \strong{NEW_SIDE} - one or more new-period category names
}

\strong{How proportions are calculated}

When one category maps to multiple:
\itemize{
  \item \strong{Backward} (\code{\%<\%}): proportions come from \code{freq_var}
    in the \strong{new} period (the target encoding)
  \item \strong{Forward} (\code{\%>\%}): proportions come from \code{freq_var}
    in the \strong{old} period (the target encoding)
}

\strong{Examples of valid equations}

\describe{
  \item{\code{Automotive \%<\% c(Automotive1, Automotive2)}}{
    Backward: the old "Automotive" row is split into two rows
    ("Automotive1", "Automotive2") with proportions from new-period counts.}
  \item{\code{c(Kids1, Kids2) \%>\% c(Kids)}}{
    Forward: the new "Kids" row is split into two rows
    ("Kids1", "Kids2") with proportions from old-period counts.}
  \item{\code{Home \%>\% c(Home, Supermarket)}}{
    Forward: the new "Home" and "Supermarket" rows are each renamed to
    "Home" (1-to-many from new perspective; after aggregation they merge).}
}

\strong{Typical workflow}

1. Call \code{cat2cat_agg()} with all mapping equations.
2. Bind \code{$old} and \code{$new} together.
3. Group by time and the (now unified) category variable.
4. Summarise numeric columns as \code{sum(value * prop_c2c)}.
}
\note{
\itemize{
  \item All equations must be valid - unknown category names cause an error.
  \item Each equation must have exactly one category on one side
    (the "one" in one-to-many). Many-to-many within a single equation
    is not allowed.
  \item Each category in \code{old} and \code{new} must appear exactly once
    (no duplicates allowed before mapping).
}
}
\examples{
data("verticals", package = "cat2cat")
agg_old <- verticals[verticals$v_date == "2020-04-01", ]
agg_new <- verticals[verticals$v_date == "2020-05-01", ]

# cat2cat_agg - can map in both directions at once
# although usually we want to have the old or the new representation

agg <- cat2cat_agg(
  data = list(
    old = agg_old,
    new = agg_new,
    cat_var_old = "vertical",
    cat_var_new = "vertical",
    time_var = "v_date",
    freq_var = "counts"
  ),
  Automotive \%<\% c(Automotive1, Automotive2),
  c(Kids1, Kids2) \%>\% c(Kids),
  Home \%>\% c(Home, Supermarket)
)

## possible processing
library("dplyr")
agg \%>\%
  bind_rows() \%>\%
  group_by(v_date, vertical) \%>\%
  summarise(
    sales = sum(sales * prop_c2c),
    counts = sum(counts * prop_c2c),
    v_date = first(v_date)
  )
}
\seealso{
\code{vignette("cat2cat_advanced")} for a complete workflow example.
}
