Package {feols.asv}

Type:	Package
Title:	Average Shared Variance (ASV) Decomposition for Multiple Fixed-Effects Models
Version:	0.0-1
Date:	2026-10-10
Depends:	R (≥ 3.4.0),fixest,ggplot2,vegan
Maintainer:	Jiangshan Lai <lai@njfu.edu.cn>
Description:	Conducts average shared variance to calculate individual contributions of predictors (groups) towards within R2 for Multiple Fixed-Effects Models.
License:	GPL-2 | GPL-3 [expanded from: GPL]
Encoding:	UTF-8
RoxygenNote:	7.3.1
NeedsCompilation:	no
Packaged:	2026-10-10 14:15:58 UTC; lai
Author:	Jiangshan Lai [aut, cre]
Repository:	CRAN
Date/Publication:	2026-10-21 14:50:08 UTC

Average Shared Variance (ASV) Decomposition for Two-Way Fixed-Effects Models Estimated with 'fixest::feols'

Description

Average Shared Variance (ASV) Decomposition for Two-Way Fixed-Effects Models Estimated with 'fixest::feols'

Usage

feols.asv(mod, iv = NULL, commonality = FALSE)

Arguments

Details

This function implements the average shared variance (ASV) approach for linear models fitted with 'fixest::feols', including models with two-way fixed effects. It fits all non-empty combinations of explanatory variables (or groups) while retaining the fixed effects specified in the original model, and uses each model's within \(R^2\) to quantify explained variation.

ASV allocates explained variation among predictors by assigning shared fractions equally among the predictors involved in each fraction. The resulting individual contributions are additive and order-independent; their sum equals the full model's within \(R^2\), subject to numerical precision and model-estimation constraints. This provides an interpretable allocation of explained variation when predictors share explanatory information.

The optional 'commonality = TRUE' output provides the underlying commonality decomposition, partitioning explained variation into unique and shared fractions. Negative commonality fractions can occur.

Interaction terms are not currently supported. The model formula must include at least one fixed effect, and the data used to fit the model must be available when the function is called.

Value

A list of class 'feolsasv' containing:

Author(s)

Jiangshan Lai lai@njfu.edu.cn

References

• Lai, J., Zou, Y., Zhang, J. & Peres-Neto, P. (2022). Generalizing hierarchical and variation partitioning in multiple regression and canonical analyses using the rdacca.hp R package. *Methods in Ecology and Evolution*, 13(4), 782–788. doi:10.1111/2041-210X.13800

• Lai, J., Zou, Y., Zhang, S., Zhang, X. & Mao, L. (2022). glmm.hp: an R package for computing individual effect of predictors in generalized linear mixed models. *Journal of Plant Ecology*, 15(6), 1302–1307. doi:10.1093/jpe/rtac096

• Lai, J., Zhu, W., Cui, D. & Mao, L. (2023). Extension of the glmm.hp package to zero-inflated generalized linear mixed models and multiple regression. *Journal of Plant Ecology*, 16(6), rtad038. doi:10.1093/jpe/rtad038

• Chevan, A. & Sutherland, M. (1991). Hierarchical partitioning. *The American Statistician*, 45, 90–96. doi:10.1080/00031305.1991.10475776

• Nimon, K., Oswald, F. L. & Roberts, J. K. (2013). Yhat: Interpreting regression effects. R package version 2.0.0.

• Nimon, K., Ho, L. S. T. & Ane, C. (2014). A linear-time algorithm for Gaussian and non-Gaussian trait evolution models. *Systematic Biology*, 63(3), 397–408.

Examples

library(fixest)

# Use base_did, a balanced panel dataset supplied with fixest.
# It contains 104 individuals observed over 10 periods.
data("base_did", package = "fixest")

# Create the treatment-by-post interaction used in a difference-in-differences
# model. The main effects of treat and post are absorbed by id and period
# fixed effects, respectively.
base_did$did <- base_did$treat * base_did$post

# Estimate a two-way fixed-effects model.
mod <- feols(y ~ x1 + did | id + period,
             data = base_did, cluster = ~id)

# Average shared variance (ASV) decomposition of within R-squared.
asv <- feols.asv(mod)
asv

# Optional commonality decomposition.
ca <- feols.asv(mod, commonality = TRUE)
ca

# Evaluate grouped predictor contributions.
iv <- list(Control = "x1", Treatment = "did")
feols.asv(mod, iv = iv)

Plot for a feols.asv object

Description

Plot for a feols.asv object

Usage

## S3 method for class 'feolsasv'
plot(x, plot.perc = FALSE, color = NULL, n = 1, dig = 4, ...)

Arguments

Value

a ggplot object

Author(s)

Jiangshan Lai lai@njfu.edu.cn