% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_fama_macbeth.R
\name{estimate_fama_macbeth}
\alias{estimate_fama_macbeth}
\title{Estimate Fama-MacBeth Regressions}
\usage{
estimate_fama_macbeth(
  data,
  model,
  vcov = "newey-west",
  vcov_options = NULL,
  data_options = NULL,
  detail = FALSE
)
}
\arguments{
\item{data}{A data frame containing the data for the regression. It must
include a column representing the time periods (defaults to \code{date}) and
the variables specified in the \code{model}.}

\item{model}{A character string describing the model to be estimated in
each cross-section (e.g., \code{"ret_excess ~ beta + bm + log_mktcap"}).}

\item{vcov}{A character string indicating the type of standard errors to
compute. Options are \code{"iid"} for independent and identically distributed
errors or \code{"newey-west"} for Newey-West standard errors. Default is
\code{"newey-west"}.}

\item{vcov_options}{A list of additional arguments to be passed to the
\code{NeweyWest()} function when \code{vcov = "newey-west"}. These can include
options such as \code{lag}, which specifies the number of lags to use in the
Newey-West covariance matrix estimation, and \code{prewhite}, which indicates
whether to apply a prewhitening transformation. Default is an empty list.}

\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"}.}

\item{detail}{A logical value indicating whether to return additional
summary statistics. If \code{FALSE} (default), the function returns only the
coefficient estimates. If \code{TRUE}, it returns a list with two elements:
\code{coefficients} (the usual estimates table) and \code{summary_statistics} (a
one-row tibble with the average cross-sectional R-squared and the average
number of observations per cross-section).}
}
\value{
If \code{detail = FALSE} (default), a tibble with columns
\code{factor}, \code{risk_premium}, \code{n} (number of time periods),
\code{standard_error}, and \code{t_statistic}.

If \code{detail = TRUE}, a named list with two elements:
\describe{
\item{coefficients}{The same tibble described above.}
\item{summary_statistics}{A one-row tibble with \code{r_squared} (mean
cross-sectional R-squared) and \code{n_obs} (mean cross-sectional
observation count).}
}
}
\description{
Estimates Fama-MacBeth regressions (Fama and MacBeth, 1973) by first running
cross-sectional regressions for each time period and then aggregating the
results over time to obtain average risk premia and corresponding
t-statistics.
}
\examples{
set.seed(1234)

data <- tibble::tibble(
  date = rep(seq.Date(from = as.Date("2020-01-01"),
                      to = as.Date("2020-12-01"), by = "month"), each = 50),
  permno = rep(1:50, times = 12),
  ret_excess = rnorm(600, 0, 0.1),
  beta = rnorm(600, 1, 0.2),
  bm = rnorm(600, 0.5, 0.1),
  log_mktcap = rnorm(600, 10, 1)
)

estimate_fama_macbeth(data, "ret_excess ~ beta + bm + log_mktcap")
estimate_fama_macbeth(
  data,
  "ret_excess ~ beta + bm + log_mktcap",
  vcov = "iid"
)
estimate_fama_macbeth(
  data,
  "ret_excess ~ beta + bm + log_mktcap",
  vcov = "newey-west",
  vcov_options = list(lag = 6, prewhite = FALSE)
)

# Return detailed output including R-squared and observation counts
estimate_fama_macbeth(
  data,
  "ret_excess ~ beta + bm + log_mktcap",
  detail = TRUE
)

# Use different column name for date
data |>
  dplyr::rename(month = date) |>
  estimate_fama_macbeth(
    "ret_excess ~ beta + bm + log_mktcap",
    data_options = data_options(date = "month")
 )

}
\references{
Fama, E. F., & MacBeth, J. D. (1973). Risk, return, and equilibrium:
Empirical tests. \emph{Journal of Political Economy}, 81(3), 607-636.
\doi{10.1086/260061}

Newey, W. K., & West, K. D. (1987). A simple, positive semi-definite,
heteroskedasticity and autocorrelation consistent covariance matrix.
\emph{Econometrica}, 55(3), 703-708.
\doi{10.2307/1913610}
}
\seealso{
Other estimation functions: 
\code{\link{estimate_betas}()},
\code{\link{estimate_model}()}
}
\concept{estimation functions}
