% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/revenue.R
\name{cog_revenue}
\alias{cog_revenue}
\title{Summarized revenue by category}
\usage{
cog_revenue(
  govid,
  years,
  category = NULL,
  per_capita = FALSE,
  adjust_to_year = NULL,
  basis = c("harmonized", "raw"),
  recipe = NULL
)
}
\arguments{
\item{govid}{Character vector of `canonical_govid` values.}

\item{years}{Integer vector of years.}

\item{category}{Character vector of category names (from
`summary_categories.category`), or `NULL` for all categories.}

\item{per_capita}{If `TRUE`, adds `amt_per_capita_nominal` (and
`amt_per_capita_real` when `adjust_to_year` is set) using the per-year
Census F-33 population from `gov_population_yearly`. Result also gains
a `pop_source` column with values `"census_f33"` or `"unavailable"`
(the latter for gov types 4/5 and any row whose population is missing
in that year).}

\item{adjust_to_year}{Integer base year for CPI-U real-dollar conversion,
or `NULL` for nominal only.}

\item{basis}{`"harmonized"` (default) sums item codes through the
cross-vintage harmonization mapping (folding series-break-affected
codes onto a comparable target and excluding aggregate / discontinued
rows -- see the `harmonization` block in `cog_explain()`); `"raw"`
reproduces the pre-Phase-R2 behavior (published item codes, no
folding). On a corpus with `schema_version < 5` (no harmonization
tables), `basis` silently resolves to `"raw"` when left at its default
and the resolution is recorded in the provenance; explicitly passing
`basis = "harmonized"` on such a corpus aborts.}

\item{recipe}{Optional harmonization recipe id (see [cog_recipes()]) for
multi-code cross-vintage series that a 1:1 harmonized_code mapping
can't express (e.g. a wide-era aggregate that only splits into leaf
codes in the modern era). Mutually exclusive with `category`. The
result's subtype column reads `"recipe"` and `category` reads the
recipe's label. Requires `schema_version >= 5`.}
}
\value{
Tibble with columns `year`, `canonical_govid`, `gov_name`,
  `revenue_subtype`, `category`, `amt_nominal`, optional `amt_real`,
  optional `amt_per_capita_nominal`, optional `amt_per_capita_real`,
  optional `pop_source`, `codes_included`, `aggregate_fallback`, `notes`.
}
\description{
Mirror of [cog_spending()] for revenue categories. One row per
`(year, canonical_govid, revenue_subtype, category)`. Amounts are returned
in **full U.S. dollars** (raw Census values are in $1,000s; this verb
multiplies by 1000 and records the conversion in `provenance`).
}