Package {xtife}

Compute Bias-Corrected IFE Coefficients (Bai 2009)

Description

Applies the two-term asymptotic bias correction from Bai (2009) Theorems 7.1 and 7.2 to the raw IFE coefficient vector:

\hat{\beta}^\dagger = \hat{\beta} - \hat{B}/N - \hat{C}/T

where \hat{B} corrects for cross-sectional heteroskedasticity (Equation 17) and \hat{C} corrects for time-varying heteroskedasticity (Equation 19). Both terms require T/N^2 \to 0 and N/T^2 \to 0 respectively (Theorem 7.2). For panels of the scale used in the package examples (N \approx 50, T \approx 30) both conditions hold approximately.

Usage

.bias_correct(beta, F_hat, Lambda_hat, X_dm_arr, X_tilde, e_mat, N, TT, p, r)

Arguments

Value

list with elements: beta_bc p-vector: bias-corrected coefficients B_hat p-vector: estimated cross-section BIAS (Bai sign convention, B/N scale): beta_bc = beta - B_hat/N - C_hat/T holds exactly C_hat p-vector: estimated time-heteroskedasticity BIAS (C/T scale)

Compute Bias-Corrected Coefficients for the Dynamic IFE Estimator

Description

Applies the three-term asymptotic bias correction from Moon and Weidner (2017) Corollary 4.5 to the raw dynamic IFE coefficient vector:

\hat{\beta}^* = \hat{\beta} + W^{-1}\!\left(\hat{B}_1/T + \hat{B}_2/N + \hat{B}_3/T\right)

where \hat{B}_1 corrects for the Nickell-type bias arising from predetermined (lagged) regressors using a lag-truncation bandwidth M1, and \hat{B}_2, \hat{B}_3 correct for cross-sectional and time-series heteroskedasticity respectively. The latter two terms are algebraically equivalent to the Bai (2009) \hat{B} and \hat{C} terms.

Usage

.bias_correct_mw(
  beta,
  F_hat,
  Lambda_hat,
  X_dm_arr,
  X_tilde,
  e_mat,
  N,
  TT,
  p,
  r,
  M1 = 1L
)

Arguments

Value

list: beta_bc p-vector: bias-corrected coefficients B1_hat p-vector: dynamic-term contribution W^-1 B1/T (additive) B2_hat p-vector: cross-section-het contribution W^-1 B2/N B3_hat p-vector: time-het contribution W^-1 B3/T The decomposition identity beta_bc = beta + B1_hat + B2_hat + B3_hat holds exactly (all scalings and the W^-1 weighting are inside).

Compute Information Criteria for a Given Number of Factors (Internal)

Description

Evaluates five information criteria for a fitted IFE model with r factors, given the mean squared residual V_r. Returns IC1, IC2, and IC3 from Bai and Ng (2002) Proposition 1 (ICp1/ICp2/ICp3), applied to IFE residuals as suggested by Bai (2009) Section 9.4, plus a BIC-style criterion (IC_bic) and a small-sample-corrected prediction criterion (PC) as implemented in the fect package (C++ source, lines 196–224). Called once per candidate r inside ife_select_r().

Usage

.compute_ic(V_r, r, N, TT, p, force)

Arguments

Value

named list: IC1, IC2, IC3 (Bai & Ng 2002), IC_bic and PC (Bai 2009/fect)

Demean Panel Matrices for Additive Fixed Effects

Description

Removes additive unit and/or time fixed effects from a T x N outcome matrix and a T x N x p covariate array using the within-group transformation. Supports four specifications: no demeaning ("none"), unit-only ("unit"), time-only ("time"), and two-way ("two-way").

Usage

.demean_panel(Y_mat, X_arr, force)

Arguments

Value

list with: Y_dm T x N demeaned outcome X_dm T x N x p demeaned covariate array (or NULL) mu_Y grand mean of Y alpha_Y N x 1 unit means of Y (after grand mean removal) xi_Y T x 1 time means of Y (after grand mean removal)

Core IFE Estimation via SVD-Based Alternating Projections

Description

Estimates the Interactive Fixed Effects model by iterating between an OLS step for the regression coefficients (given current factor estimates) and an SVD step for the factor matrix (given current coefficients). Convergence is declared when the maximum absolute change in the coefficient vector falls below tol. Handles the degenerate case r = 0 (standard OLS on demeaned data) as a special case. Supports both the strictly-exogenous ("static", Bai 2009) and the predetermined-regressor ("dynamic", Moon and Weidner 2017) projection schemes.

Usage

.ife_fit(Y_dm, X_dm, r, tol = 1e-09, max_iter = 10000L, method = "static")

Arguments

Value

list: beta p x 1 coefficient vector (numeric(0) if p = 0) F_hat T x r factor matrix (normalized F'F/T = I_r) Lambda_hat N x r loading matrix X_tilde T x N x p factor-projected covariates (for SE computation) e_mat T x N residual matrix E = Y_dm - X_dm * beta - F Lambda' n_iter number of iterations used converged logical

Compute Standard Errors for the IFE Estimator

Description

Constructs the sandwich variance-covariance matrix for the IFE coefficient vector using the Frisch-Waugh-Lovell principle. The effective regressors are the factor-projected covariates \tilde{X}_{it} (i.e., demeaned X after removing the factor space). Three estimators are supported: homoskedastic ("standard"), HC1 heteroskedasticity-robust ("robust"), and cluster-robust by unit ("cluster"), following Cameron, Gelbach and Miller (2011). Degrees of freedom account for regression coefficients, interactive FE parameters, and additive FE parameters.

Usage

.ife_se(beta, X_tilde, u_mat, N, TT, r, force, se_type)

Arguments

Value

list: vcov_mat p x p estimated variance-covariance matrix df residual degrees of freedom

Dataset on US Cigarette Demand Panel

Description

Balanced panel of cigarette sales and prices across 46 US states for 30 years (1963–1992). Originally used in Baltagi (1995) and widely used as a benchmark dataset for panel estimators.

Usage

cigar

Format

A data frame with 1,380 rows and 9 variables:

state

US state identifier (integer, 1–46)

year

year (integer, 1963–1992)

price

cigarette price index

pop

state population

pop16

population aged 16 and over

cpi

consumer price index

ndi

per-capita disposable income

sales

per-capita cigarette sales (packs per person per year)

pimin

minimum cigarette price in adjoining states

Source

Baltagi, B.H. (1995) Econometric Analysis of Panel Data. Wiley. Distributed with the plm R package (Croissant and Millo 2008).

References

Baltagi, B.H. (1995). Econometric Analysis of Panel Data. Wiley.

Croissant, Y. and Millo, G. (2008). Panel data econometrics in R: the plm package. Journal of Statistical Software, 27(2), 1–43. doi:10.18637/jss.v027.i02

Estimate Interactive Fixed Effects Model (Bai 2009)

Description

Fits the panel model

y_{it} = \alpha_i + \xi_t + X_{it}'\beta + \lambda_i'F_t + u_{it}

for balanced panel data with analytical standard errors.

Usage

ife(
  formula,
  data,
  index,
  r = 1L,
  force = "two-way",
  se = "standard",
  bias_corr = FALSE,
  method = "static",
  M1 = 1L,
  tol = 1e-09,
  max_iter = 10000L
)

Arguments

Value

An S3 object of class "ife" with the following components:

• coef – named p-vector of estimated coefficients

• vcov – p x p variance-covariance matrix

• se – named p-vector of standard errors

• tstat – named p-vector of t-statistics

• pval – named p-vector of two-sided p-values

• ci – p x 2 matrix of 95% confidence intervals (CI.lower, CI.upper)

• table – data.frame coefficient table (Estimate, Std.Error, t.value, Pr.t, CI.lower, CI.upper)

• F_hat – T x r estimated factor matrix

• Lambda_hat – N x r estimated loading matrix

• residuals – T x N residual matrix (full model)

• sigma2 – estimated error variance

• df – residual degrees of freedom

• n_iter – iterations to convergence

• converged – logical

• N, T, r, force, se_type – model dimensions and options

• call – matched call

References

Bai, J. (2009). Panel data models with interactive fixed effects. Econometrica, 77(4), 1229–1279. doi:10.3982/ECTA6135

Moon, H.R. and Weidner, M. (2017). Dynamic linear panel regression models with interactive fixed effects. Econometric Theory, 33, 158–195. doi:10.1017/S0266466615000328

Bai, J. and Ng, S. (2002). Determining the number of factors in approximate factor models. Econometrica, 70(1), 191–221. doi:10.1111/1468-0262.00273

Examples

data(cigar, package = "xtife")
fit <- ife(sales ~ price, data = cigar, index = c("state", "year"),
           r = 2, force = "two-way", se = "standard")
print(fit)

Select the Number of Factors via Information Criteria

Description

Fits the IFE model for r = 0, 1, ..., r_max and evaluates five information criteria at each value of r. Returns IC1, IC2, and IC3 from Bai and Ng (2002) Proposition 1, applied to IFE residuals per Bai (2009) Section 9.4, plus a BIC-style penalty (IC_bic) and a small-sample-corrected prediction criterion (PC) from Bai (2009). The criterion-minimising r for each IC is flagged with "*" in the printed table, and a data-driven recommendation (favouring IC_bic when the Bai-Ng criteria decrease monotonically) is displayed.

Usage

ife_select_r(
  formula,
  data,
  index,
  r_max = NULL,
  force = "two-way",
  verbose = TRUE,
  tol = 1e-09,
  max_iter = 10000L
)

Arguments

Value

(invisibly) a data.frame with columns r, V_r, IC1, IC2, IC3, IC_bic, PC, converged, and attribute "suggested" (named integer vector giving the IC-minimising r for each criterion).

References

Bai, J. (2009). Panel data models with interactive fixed effects. Econometrica, 77(4), 1229–1279. doi:10.3982/ECTA6135

Bai, J. and Ng, S. (2002). Determining the number of factors in approximate factor models. Econometrica, 70(1), 191–221. doi:10.1111/1468-0262.00273

Examples

  data(cigar, package = "xtife")
  sel <- ife_select_r(sales ~ price, data = cigar,
                      index = c("state", "year"), r_max = 4)

Factor Number Selection for Unbalanced Panel IFE via SVT

Description

Estimates the number of interactive factors in an unbalanced panel by the singular value thresholding (SVT) rule of Su, Wang and Wang (2025), applied to the nuclear-norm-regularised (soft-imputed) matrix — a missing-data counterpart of the information-criterion rules of Bai and Ng (2002).

Usage

ife_select_r_unb(formula, data, index, c_f = 0.6, nu_NT = NULL, verbose = TRUE)

Arguments

Value

Invisibly returns a list with components r_hat, sv (normalised singular values), threshold, c_f, c_NT, and nu_used.

References

Su, L., Wang, F. and Wang, Y. (2025). Estimation and inference for interactive fixed effects panel data models with unbalanced panels. SSRN Working Paper No. 5177283. doi:10.2139/ssrn.5177283

Bai, J. and Ng, S. (2002). Determining the number of factors in approximate factor models. Econometrica, 70(1), 191–221. doi:10.1111/1468-0262.00273

Bai, J. and Ng, S. (2021). Matrix completion, counterfactuals, and factor analysis of missing data. Journal of the American Statistical Association, 116(536), 1746–1763. doi:10.1080/01621459.2021.1967163

Examples

  data(cigar, package = "xtife")
  set.seed(42)
  cigar_unb <- cigar[sample(nrow(cigar), 1200L), ]
  ife_select_r_unb(sales ~ price, data = cigar_unb,
                   index = c("state", "year"))

Unbalanced Panel Interactive Fixed Effects Estimator

Description

Fits the interactive fixed effects model

Y_{it} = \alpha_i + \xi_t + X_{it}'\beta + \lambda_i'F_t + u_{it}

for unbalanced panels (units observed at different sets of time periods), where the additive unit effects \alpha_i and time effects \xi_t are controlled by force. The estimation and inference theory follows Su, Wang and Wang (2025). Estimation uses an alternating outer loop that updates \hat\beta and the structure (\hat\alpha, \hat\xi, \hat\lambda, \hat F), with an expectation-maximisation (EM) inner loop — in the spirit of Bai (2009, Appendix B) and the missing-data factor / matrix-completion framework of Bai and Ng (2021) — that imputes the unobserved cells from the current structure and re-estimates the additive and interactive components on the completed panel. An optional nuclear-norm-regularised (soft-impute) warm start (Mazumder, Hastie and Tibshirani 2010) is available via init = "nnr".

Usage

ife_unbalanced(
  formula,
  data,
  index,
  r = 1L,
  force = "none",
  se = "standard",
  init = "ols",
  bias_corr = FALSE,
  exog = "strict",
  L_T = NULL,
  c_f = 0.6,
  nu_NT = NULL,
  tol = 1e-09,
  max_iter = 10000L,
  tol_em = 1e-07,
  max_iter_em = 500L
)

Arguments

Details

Inference. Standard errors use a sandwich estimator on factor-projected regressors (the unbalanced analogue of the balanced formula of Bai 2009), following Su, Wang and Wang (2025), with heteroskedasticity-robust, cluster-robust (Arellano 1987; Cameron, Gelbach and Miller 2011) and HAC (Newey and West 1987) variants. The optional analytical bias correction of Su, Wang and Wang (2025) removes the leading incidental-parameter bias, extending the corrections of Bai (2009) and Moon and Weidner (2017) to the unbalanced and predetermined-regressor case.

Additive fixed effects. With force = "none" (default) the model is intercept-free and all heterogeneity is carried by the interactive factors. Setting force = "unit", "time" or "two-way" estimates the additive effects jointly with the factors by demeaning the imputed (completed) panel inside the EM loop, which is robust to informative missingness; the degrees-of-freedom adjustment is propagated to the standard errors.

Value

An S3 object of class "ife_unb" with components:

coef

Named p-vector of estimated coefficients \hat\beta (bias-corrected when bias_corr = TRUE).

coef_raw

Named p-vector of uncorrected coefficients (only when bias_corr = TRUE).

vcov

p x p variance-covariance matrix.

se

Named p-vector of standard errors.

tstat

Named p-vector of t-statistics.

pval

Named p-vector of two-sided p-values.

ci

p x 2 matrix of 95 percent confidence intervals.

table

Data frame coefficient table.

F_hat

TT x r estimated factor matrix (normalised F'F/TT = I_r).

Lambda_hat

N x r estimated loading matrix.

residuals

n_obs numeric vector of full-model residuals at observed cells.

sigma2

Estimated error variance (sum(u^2)/df).

df

Residual degrees of freedom.

n_obs

Number of observed unit-time cells.

n_iter

Outer-loop iterations to convergence.

converged

Logical.

N, TT, r, se_type

Model dimensions and options.

init, bias_corr, exog, L_T

Options used.

b_hat, b2, b3, b4, b5, b6

Bias components (only when bias_corr = TRUE). b2 is a zero vector when exog = "strict".

y_name, x_names, id_col, time_col

Variable names.

unit_vals, time_vals

Unique unit and time identifiers.

unit_idx, time_idx

Integer index vectors for residuals.

call

Matched call.

References

Su, L., Wang, F. and Wang, Y. (2025). Estimation and inference for interactive fixed effects panel data models with unbalanced panels. SSRN Working Paper No. 5177283. doi:10.2139/ssrn.5177283

Bai, J. (2009). Panel data models with interactive fixed effects. Econometrica, 77(4), 1229–1279. doi:10.3982/ECTA6135

Bai, J. and Ng, S. (2021). Matrix completion, counterfactuals, and factor analysis of missing data. Journal of the American Statistical Association, 116(536), 1746–1763. doi:10.1080/01621459.2021.1967163

Mazumder, R., Hastie, T. and Tibshirani, R. (2010). Spectral regularization algorithms for learning large incomplete matrices. Journal of Machine Learning Research, 11, 2287–2322.

Moon, H. R. and Weidner, M. (2017). Dynamic linear panel regression models with interactive fixed effects. Econometric Theory, 33, 158–195. doi:10.1017/S0266466615000328

Examples

data(cigar, package = "xtife")
# Drop ~10 % of rows to create an unbalanced panel
set.seed(1)
cigar_unb <- cigar[sample(nrow(cigar), 1200L), ]
fit <- ife_unbalanced(sales ~ price, data = cigar_unb,
                      index = c("state", "year"), r = 2L)
print(fit)

Print an IFE Model Summary

Description

Prints a formatted summary of an object of class "ife", including panel dimensions, number of factors, additive fixed effect specification, SE type, and a coefficient table with standard errors, t-statistics, p-values, and 95% confidence intervals. If bias correction was applied, bias terms are also reported. Information criteria are printed when the object contains them (i.e., when called from ife_select_r()).

Usage

## S3 method for class 'ife'
print(x, digits = 4, ...)

Arguments

Value

x invisibly.

Examples

data(cigar, package = "xtife")
fit <- ife(sales ~ price, data = cigar, index = c("state", "year"),
           r = 2, force = "two-way", se = "standard")
print(fit)