% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scf_deflate.R
\name{scf_deflate}
\alias{scf_deflate}
\title{Convert SCF Dollar Estimates to Real Terms}
\usage{
scf_deflate(x, base_year = 2022)
}
\arguments{
\item{x}{An object of class \code{scf_mean}, \code{scf_median},
\code{scf_percentile}, or \code{scf_ttest}.}

\item{base_year}{Integer. Reference year for real dollars. Must be a valid
SCF survey year (1989--2022, triennial). Default is \code{2022}.}
}
\value{
The input object with dollar estimates, standard errors, and
confidence intervals rescaled to \code{base_year} dollars. Attributes
\code{"deflated"} (logical) and \code{"base_year"} (integer) are set on
the returned object.
}
\description{
Multiplies dollar-valued point estimates and their standard errors by the
CPI-U-RS deflation factor \code{CPI[base_year] / CPI[survey_year]},
converting nominal survey-year dollars to real dollars of the chosen base
year. The CPI-U-RS September values are taken directly from the Federal
Reserve Board's SCF Bulletin SAS macro.
}
\details{
Standard errors rescale correctly under linear multiplication, so both
estimates and SEs are multiplied by the same factor. Confidence intervals
and group means are also rescaled. The t-statistic, degrees of freedom,
and p-value in \code{scf_ttest} results are invariant to this rescaling
and are left unchanged.

\strong{Supported functions:} \code{scf_mean}, \code{scf_median},
\code{scf_percentile}, and \code{scf_ttest} return dollar-valued estimates
that transform correctly under scalar multiplication.
\code{scf_freq}, \code{scf_xtab}, and \code{scf_prop_test} return
proportions and are not supported. \code{scf_corr} returns a dimensionless
coefficient and is not supported. The regression functions
(\code{scf_ols}, \code{scf_glm}, \code{scf_logit}, \code{scf_quantreg})
are not supported because deflating coefficients post hoc is ambiguous
when a model mixes dollar and non-dollar variables; for real-dollar
regression results, deflate variables upstream with \code{scf_update()}
before fitting.

\strong{Income note:} SCF income is measured in the prior calendar year,
so a mean income estimate from the 2019 survey is in 2018 dollars, not
2019 dollars. \code{scf_deflate()} applies \code{CPI[base] / CPI[2019]},
which is a close but not exact conversion for income. This is documented
in the Federal Reserve's SAS macro, which applies a separate lag
adjustment to income before the main deflation step.
}
\section{Conditions}{

\describe{
\item{Warning — double deflation}{If the input object has already been
deflated (\code{attr(x, "deflated")} is \code{TRUE}), \code{scf_deflate()}
issues a warning and proceeds. Applying the function twice compounds the
CPI adjustment and produces incorrect results. Check
\code{attr(result, "deflated")} and \code{attr(result, "base_year")}
before calling.}
\item{Error — stale result object}{If the result object does not carry a
survey year (\code{x$aux$year} is \code{NULL}), the function stops with
a message asking you to re-run the originating function (\code{scf_mean()},
\code{scf_median()}, etc.) under the current package version. This field
was introduced in version 1.0.6.}
\item{Error — unsupported class}{Passing an object of an unsupported class
(e.g., a regression result or a frequency table) stops with a message
listing the supported classes: \code{scf_mean}, \code{scf_median},
\code{scf_percentile}, and \code{scf_ttest}.}
\item{Error — year not in CPI table}{If \code{base_year} is not one of
the valid triennial SCF survey years (1989--2022), the function stops
and lists the valid options.}
}
}

\examples{
# Do not implement these lines in real analysis:
# Use functions `scf_download()` and `scf_load()`
td <- tempfile("deflate_")
dir.create(td)

src <- system.file("extdata", "scf2022_mock_raw.rds", package = "scf")
file.copy(src, file.path(td, "scf2022.rds"), overwrite = TRUE)
scf2022 <- scf_load(2022, data_directory = td)

# Deflate a mean estimate to real 2022 dollars
result <- scf_mean(scf2022, ~networth)
result_real <- scf_deflate(result, base_year = 2022)

# Works with median and percentile results
med <- scf_median(scf2022, ~networth)
med_real <- scf_deflate(med, base_year = 2022)

# Do not implement these lines in real analysis: Cleanup for package check
unlink(td, recursive = TRUE, force = TRUE)

}
\seealso{
\code{\link[=scf_mean]{scf_mean()}}, \code{\link[=scf_median]{scf_median()}}, \code{\link[=scf_percentile]{scf_percentile()}}, \code{\link[=scf_ttest]{scf_ttest()}},
\code{\link[=scf_update]{scf_update()}}
}
