Package {fereg}

fereg: fast fixed-effects estimation with fixest's interface

Description

OLS, IV/2SLS, Poisson and logit estimation with any number of fixed effects, interactions and varying slopes, weights and iid / heteroskedasticity-robust / multiway-clustered variances. The interface and the numbers are those of fixest (feols(), fepois(), feglm(), etable(), fixef(), ...); estimation runs in a parallel Rust core that eliminates the largest fixed effect exactly and solves the rest by preconditioned conjugate gradient.

Details

Options: fereg.nthreads (threads, 0 = all cores; default all cores, capped at OMP_THREAD_LIMIT, and 2 under R CMD check) and fereg.notes (print notes on removed observations).

Author(s)

Maintainer: Leo Liu auleo.liu@gmail.com [copyright holder]

Authors:

• Leo Liu auleo.liu@gmail.com [copyright holder]

Other contributors:

• Authors of the bundled Rust crates (see inst/AUTHORS for each crate's authors and license) [contributor, copyright holder]

See Also

Useful links:

• https://github.com/leoliu0/fereg

• Report bugs at https://github.com/leoliu0/fereg/issues

Table of estimation results

Description

Side-by-side table of several estimations in fixest's etable() layout: coefficients with standard errors in parentheses and significance stars, fixed effects, variance type and fit statistics.

Usage

etable(
  ...,
  vcov = NULL,
  ssc = NULL,
  tex = FALSE,
  digits = 4,
  digits.stats = 5,
  fitstat = NULL,
  keep = NULL,
  drop = NULL,
  family = NULL
)

Arguments

Value

A data frame (class fereg_etable) or, with tex = TRUE, a character string (class fereg_etable_tex).

Examples

data(trade_toy, package = "fereg")
m1 <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
m2 <- fepois(count ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
etable(m1, m2, vcov = ~id)
etable(m1, tex = TRUE)

Fixed-effects OLS and IV estimation

Description

Drop-in replacement for fixest::feols(): same formula syntax, arguments and defaults, same numbers. Estimation runs in the fereg Rust core.

Usage

feols(
  fml,
  data,
  vcov,
  weights,
  offset,
  subset,
  split,
  fsplit,
  cluster,
  se,
  ssc,
  panel.id,
  fixef.rm = "perfect_fit",
  fixef.tol = 1e-08,
  fixef.iter = 16000,
  collin.tol = 1e-09,
  nthreads = getOption("fereg.nthreads", default_threads()),
  lean = FALSE,
  notes = getOption("fereg.notes", TRUE),
  ...
)

Arguments

Value

An object of class fereg (or fereg_multi for multiple estimations).

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
m
summary(m, vcov = ~id)

Fixed-effects Poisson and logit estimation

Description

Drop-in replacements for fixest::fepois() and fixest::feglm() (Poisson and logit families).

Usage

fepois(
  fml,
  data,
  vcov,
  offset,
  weights,
  subset,
  split,
  fsplit,
  cluster,
  se,
  ssc,
  panel.id,
  fixef.rm = "perfect_fit",
  fixef.tol = 1e-08,
  fixef.iter = 16000,
  glm.iter = 25,
  glm.tol = 1e-08,
  collin.tol = 1e-09,
  nthreads = getOption("fereg.nthreads", default_threads()),
  lean = FALSE,
  notes = getOption("fereg.notes", TRUE),
  ...
)

feglm(
  fml,
  data,
  family = "logit",
  vcov,
  offset,
  weights,
  subset,
  split,
  fsplit,
  cluster,
  se,
  ssc,
  panel.id,
  fixef.rm = "perfect_fit",
  fixef.tol = 1e-08,
  fixef.iter = 16000,
  glm.iter = 25,
  glm.tol = 1e-08,
  collin.tol = 1e-09,
  nthreads = getOption("fereg.nthreads", default_threads()),
  lean = FALSE,
  notes = getOption("fereg.notes", TRUE),
  ...
)

Arguments

Value

An object of class fereg (or fereg_multi).

Examples

data(trade_toy, package = "fereg")
p <- fepois(count ~ x1 | id + year, trade_toy, nthreads = 2)
p

Methods for fereg objects

Description

Accessors, post-hoc variances, predictions and fixed effects of feols(), fepois() and feglm() results, as in fixest.

Usage

## S3 method for class 'fereg'
summary(
  object,
  vcov = NULL,
  ssc = NULL,
  cluster = NULL,
  se = NULL,
  stage = 2,
  ...
)

## S3 method for class 'fereg'
coef(object, ...)

## S3 method for class 'fereg'
vcov(
  object,
  vcov = NULL,
  ssc = NULL,
  attr = FALSE,
  cluster = NULL,
  se = NULL,
  ...
)

## S3 method for class 'fereg'
confint(
  object,
  parm,
  level = 0.95,
  vcov = NULL,
  ssc = NULL,
  cluster = NULL,
  se = NULL,
  ...
)

## S3 method for class 'fereg'
nobs(object, ...)

## S3 method for class 'fereg'
residuals(
  object,
  type = c("response", "deviance", "pearson", "working"),
  na.rm = TRUE,
  ...
)

## S3 method for class 'fereg'
fitted(object, type = c("response", "link"), na.rm = TRUE, ...)

## S3 method for class 'fereg'
predict(object, newdata, type = c("response", "link"), ...)

## S3 method for class 'fereg'
logLik(object, ...)

## S3 method for class 'fereg'
AIC(object, ..., k = 2)

## S3 method for class 'fereg'
BIC(object, ...)

## S3 method for class 'fereg'
deviance(object, ...)

## S3 method for class 'fereg'
sigma(object, ...)

Arguments

Value

summary(): the fereg object with the requested variance (coefficient table in ⁠$coeftable⁠); for IV with stage = 1 or 1:2, the requested stages (a fereg_multi when there are several). coef(): named vector of coefficients. vcov(): variance matrix. confint(): data frame of lower and upper bounds, one row per coefficient. nobs(): number of observations. resid(), fitted(), predict(): numeric vectors. logLik(): object of class logLik. AIC(), BIC(), deviance(), sigma(): numbers.

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
summary(m, vcov = "hetero")
coef(m)
vcov(m, vcov = ~id)
confint(m, level = 0.9)
head(predict(m, newdata = trade_toy))
c(AIC = AIC(m), BIC = BIC(m))

Multiple estimations

Description

A fereg_multi object is a list of fereg objects (one per estimation, fixest order: sample, fixed effects, dependent variable, right-hand side). Methods apply to every estimation.

Usage

## S3 method for class 'fereg_multi'
print(x, ...)

## S3 method for class 'fereg_multi'
x[i]

## S3 method for class 'fereg_multi'
as.list(x, ...)

## S3 method for class 'fereg_multi'
summary(object, ...)

## S3 method for class 'fereg_multi'
coef(object, ...)

## S3 method for class 'fereg_multi'
nobs(object, ...)

Arguments

Value

print(): x, invisibly. [ and summary(): a fereg_multi object. as.list(): a list of fereg objects. coef(): data frame with one row per estimation and one column per coefficient. nobs(): number of observations of each estimation.

Examples

data(trade_toy, package = "fereg")
ms <- feols(y ~ csw(x1, x2) | id + year, trade_toy, nthreads = 2)
ms
coef(ms)
nobs(ms)
summary(ms[2], vcov = ~id)

Fit statistics

Description

Same types and names as fixest's fitstat(): n, rmse, r2, ar2, wr2, war2, ll, pr2, apr2, cor2 (sq.cor), aic, bic, f, my, g and, for IV, ivf1 (ivf), ivwald1 (ivwald), wh and sargan.

Usage

fitstat(x, type, simplify = FALSE, ...)

Arguments

Value

An object of class fereg_fitstat (a named list), or a vector if simplify.

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
fitstat(m, ~ n + r2 + wr2)

Fixed effects of an estimation

Description

Fixed-effect coefficients with fixest's normalization: the first fixed effect is free, and in every connected component one level of each other fixed effect is set to 0 (counted in the references attribute). Varying slopes are listed as fe[[x]].

Usage

fixef(object, ...)

Arguments

Value

A list (class fereg.fixef) of named vectors, one per fixed effect / slope.

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
fe <- fixef(m)
summary(fe)
head(fe$year)

R-squared variants

Description

R-squared variants

Usage

r2(x, type = "all")

Arguments

Value

A named numeric vector (NA where a type does not apply).

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
r2(m)

Coefficient table accessors

Description

se(), tstat(), pvalue() and coeftable() as in fixest.

Usage

se(object, ...)

tstat(object, ...)

pvalue(object, ...)

coeftable(object, ...)

Arguments

Value

Named vectors, or the coefficient matrix for coeftable().

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
se(m)
pvalue(m, vcov = "hetero")
coeftable(m, vcov = ~id)

Small-sample correction

Description

Same arguments and defaults as fixest's ssc(). As in fixest, the correction depends on the variance type: heteroskedasticity-robust, Newey-West, Driscoll-Kraay and Conley variances use K.fixef = "full" (no nesting), Newey-West and Driscoll-Kraay apply G.adj with G = the number of time periods, Conley uses n / (n - K), and HC2 / HC3 use no correction at all.

Usage

ssc(
  K.adj = TRUE,
  K.fixef = "nonnested",
  K.exact = FALSE,
  G.adj = TRUE,
  G.df = "min",
  t.df = "min",
  adj,
  fixef.K,
  cluster.adj,
  cluster.df
)

Arguments

Value

An object of class ssc.type.

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 + x2 | id + year, trade_toy, nthreads = 2)
summary(m, vcov = ~id, ssc = ssc(K.adj = FALSE, G.adj = FALSE))

Simulated panel for examples

Description

A small simulated panel: 600 observations of 60 units over 10 years.

Usage

data(trade_toy)

Format

A data frame with columns id, year, x1, x2, z (instrument), xe (endogenous regressor), y, count (Poisson outcome) and binary (0/1 outcome).

Variance requests

Description

fixest's request objects and helpers for the vcov argument of feols(), fepois(), feglm(), summary(), vcov(), confint() and etable(). They return objects of class fixest_vcov_request (the same structure as fixest's, so both packages' requests are accepted). Called with an estimation as first argument, the ⁠vcov_*()⁠ functions return its variance matrix instead, as in fixest.

Usage

NW(lag = NULL)

newey_west(lag = NULL)

DK(lag = NULL)

driscoll_kraay(lag = NULL)

conley(cutoff = NULL, pixel = NULL, distance = NULL)

vcov_hetero(
  x,
  type = "hc1",
  exact = TRUE,
  boot.size = NULL,
  ssc = NULL,
  vcov_fix = TRUE
)

vcov_cluster(x, cluster = NULL, ssc = NULL, vcov_fix = TRUE)

vcov_crv3(x, cluster = NULL, ssc = NULL)

vcov_NW(x, unit = NULL, time = NULL, lag = NULL, ssc = NULL, vcov_fix = TRUE)

vcov_DK(x, time = NULL, lag = NULL, ssc = NULL, vcov_fix = TRUE)

vcov_conley(
  x,
  lat = NULL,
  lon = NULL,
  cutoff = NULL,
  pixel = 0,
  distance = "triangular",
  ssc = NULL,
  vcov_fix = TRUE
)

Arguments

Details

• NW(lag) / newey_west(lag): Newey-West (Bartlett kernel). With a unit and a time variable (vcov = NW ~ id + period, or panel.id), only pairs of observations of the same unit enter; with a time variable only (NW ~ period without panel.id) it is the time-series estimator. Time is the dense rank of the time variable over the estimation sample (gaps are collapsed). Default lag: floor(T^(1/4)) for panels, fixest's sandwich::bwNeweyWest() rule for a time series. Label ⁠Newey-West (L=<lag>)⁠.

• DK(lag) / driscoll_kraay(lag): Driscoll-Kraay on the per-period score sums; default lag floor(T^(1/4)). Label ⁠Driscoll-Kraay (L=<lag>)⁠.

• conley(cutoff, pixel, distance): Conley spatial HAC with fixest's uniform kernel. cutoff is in kilometers (a number) or a string such as "100km" / "60mi"; NULL deduces it from the coordinates as fixest does. pixel (same unit as cutoff, default 0) aggregates the scores on a grid first; distance is "triangular" (default, fixest's flat-earth distance) or "spherical" (great-circle). Latitude and longitude come from the formula (conley(100) ~ lat + lon) or are guessed from the column names (lat, latitude, ⁠lat_*⁠; lon, lng, long, longitude, ⁠lon_*⁠, ...). Label ⁠Conley (<cutoff><km|mi>)⁠.

• vcov_hetero(type): "hc1" (heteroskedasticity-robust, default), "hc2" or "hc3". HC2 and HC3 use the exact leverage of the full model (fixed effects included) and no small-sample correction; they are not defined for IV estimations.

• vcov_cluster(cluster): clustering on up to four variables (names or a formula; a^b interacts).

• vcov_crv3(cluster): fereg extension (fixest has no CRV3): leave-one-cluster-out jackknife centered at the full-sample coefficients (pyfixest's CRV3), with fixest's cluster small-sample correction and multiway inclusion-exclusion. Also requested with vcov = "crv3" (clusters guessed as for "cluster") or vcov = crv3 ~ g1 + g2. CRV3 needs the leave-one-out refits: after estimation (summary(m, vcov = "crv3")) the model is re-estimated.

Value

A fixest_vcov_request object, or the variance matrix of x.

Examples

data(trade_toy, package = "fereg")
m <- feols(y ~ x1 | id + year, trade_toy, panel.id = ~id + year, nthreads = 2)
summary(m, vcov = NW(1))
summary(m, vcov = DK ~ year)
summary(m, vcov = vcov_hetero(type = "hc2"))