Create and explore imaginative 3D worlds with our new product Dreamfield (opens in a new tab)
Papers
Topics
Authors
Recent
Search
2000 character limit reached

Genriesz: Debiased ML via Riesz Regression

Updated 5 July 2026
  • Genriesz is an open-source Python package for automatic debiased machine learning that implements generalized Riesz regression to estimate causal and structural parameters.
  • It leverages the Riesz representation theorem and empirical Bregman divergence minimization to construct cross-fitted estimators with confidence intervals and p-values.
  • The package features Automatic Regressor Balancing (ARB) and a modular architecture that simplifies basis selection, generator configuration, and estimator calculation.

genriesz is an open-source Python package for automatic debiased machine learning (DML) with generalized Riesz regression, designed for efficient estimation of causal and structural parameters using the Riesz representation theorem and empirical Bregman-divergence minimization (Kato, 19 Feb 2026). It targets parameters expressible as linear functionals of a regression function, automates construction of compatible representer estimators, and returns regression adjustment, Riesz weighting, augmented Riesz weighting, and TMLE-style estimators with cross-fitting, confidence intervals, and pp-values. A central design principle is Automatic Regressor Balancing (ARB): given a Bregman generator gg and a representer model class, the package automatically constructs a compatible link function so that the generalized Riesz regression estimator satisfies balancing, or moment-matching, optimality conditions in a user-chosen basis (Kato, 19 Feb 2026).

1. Statistical target and Riesz-representer formulation

The package operates in an i.i.d. setting with data W=(X,Y)∼PW=(X,Y)\sim P, feature X∈RdX\in\mathbb{R}^d, outcome Y∈RY\in\mathbb{R}, and regression function γ0(x)=E[Y∣X=x]\gamma_0(x)=\mathbb{E}[Y\mid X=x] (Kato, 19 Feb 2026). The estimand is assumed to have the form

θ0=E[m(W,γ0)],\theta_0=\mathbb{E}\bigl[m(W,\gamma_0)\bigr],

where the user-supplied oracle m(W,γ)m(W,\gamma) is linear in γ\gamma (Kato, 19 Feb 2026).

By the Riesz representation theorem in L2(PX)L_2(P_X), there exists a unique Riesz representer α0(X)\alpha_0(X) such that

E[m(W,γ)]=E[α0(X) γ(X)]\mathbb{E}\bigl[m(W,\gamma)\bigr] = \mathbb{E}\bigl[\alpha_0(X)\,\gamma(X)\bigr]

for every square-integrable γ\gamma (Kato, 19 Feb 2026). This representation is the organizing device of the package: once α0\alpha_0 is estimated, inference proceeds through a Neyman-orthogonal score,

ψ(W;θ,γ,α)=m(W,γ)+α(X) {Y−γ(X)}−θ.\psi\bigl(W;\theta,\gamma,\alpha\bigr) = m\bigl(W,\gamma\bigr) + \alpha(X)\,\bigl\{Y-\gamma(X)\bigr\} -\theta.

The score is orthogonal, or locally insensitive, to small perturbations of the nuisance functions γ\gamma and α\alpha, and averaging plug-in scores yields a root-nn–consistent, asymptotically normal estimator under weak rates plus cross-fitting (Kato, 19 Feb 2026).

This setup places genriesz within the DML tradition while centering estimation of the representer itself. A plausible implication is that the package is especially useful when the main technical bottleneck is not outcome modeling alone, but accurate recovery of the linear functional’s representer under structured balance constraints.

2. Generalized Riesz regression via Bregman divergences

The package implements generalized Riesz regression as estimation of α\alpha through a pointwise convex generator g(x,α)g(x,\alpha), convex in α\alpha for each xx, and its associated Bregman divergence

Dg(α0(x) ∥ α(x))=g(x,α0(x))−g(x,α(x))−∂αg(x,α(x)) [α0(x)−α(x)].D_g\bigl(\alpha_0(x)\,\Vert\,\alpha(x)\bigr) = g\bigl(x,\alpha_0(x)\bigr) - g\bigl(x,\alpha(x)\bigr) - \partial_\alpha g\bigl(x,\alpha(x)\bigr)\, \bigl[\alpha_0(x)-\alpha(x)\bigr].

The empirical primal loss is, up to additive constants,

L^(α)=1n∑i=1n{− g(Xi,α(Xi))+∂αg(Xi,α(Xi)) α(Xi)−m(Wi,  ∂αg( ⋅,α(⋅) ))}+λ Ω(α),\widehat L(\alpha) = \frac{1}{n}\sum_{i=1}^n \Bigl\{ -\,g\bigl(X_i,\alpha(X_i)\bigr) + \partial_\alpha g\bigl(X_i,\alpha(X_i)\bigr)\,\alpha(X_i) - m\bigl(W_i,\;\partial_\alpha g(\,\cdot,\alpha(\cdot)\,)\bigr) \Bigr\} + \lambda\,\Omega(\alpha),

with Ω\Omega a convex penalty, for example an ℓp\ell_p penalty on coefficients (Kato, 19 Feb 2026).

The dual formulation is expressed in the coordinate v(x)=∂αg(x,α(x))v(x)=\partial_\alpha g(x,\alpha(x)), using the convex conjugate

g∗(x,v)=sup⁡α{α v−g(x,α)}.g^*(x,v)=\sup_\alpha\{\alpha\,v-g(x,\alpha)\}.

Then the dual loss is

L^∗(v)=1n∑i=1n{g∗(Xi,v(Xi))−m(Wi,v)}+λ Ω∗(v),\widehat L^*(v) = \frac{1}{n}\sum_{i=1}^n \Bigl\{ g^*\bigl(X_i,v(X_i)\bigr) - m(W_i,v) \Bigr\} + \lambda\,\Omega^*(v),

which the package describes as often more convenient to optimize (Kato, 19 Feb 2026).

For GLM-style estimation, genriesz approximates the dual coordinate by a linear predictor in a user-specified feature map ϕ(x)∈Rp\phi(x)\in\mathbb{R}^p: vβ(x)=ϕ(x)⊤β,αβ(x)=[∂αg(x,⋅)]−1(ϕ(x)⊤β).v_\beta(x)=\phi(x)^\top\beta, \qquad \alpha_\beta(x)=\bigl[\partial_\alpha g(x,\cdot)\bigr]^{-1}\bigl(\phi(x)^\top\beta\bigr). The fitted coefficient vector solves

β^=arg⁡min⁡β∈Rp{1n∑i=1n[g∗(Xi,ϕ(Xi)⊤β)−m(Wi,ϕ(⋅)⊤β)]+λ Ω(β)},\widehat\beta = \arg\min_{\beta\in\mathbb{R}^p} \Bigl\{ \frac{1}{n}\sum_{i=1}^n \bigl[ g^*\bigl(X_i,\phi(X_i)^\top\beta\bigr) - m\bigl(W_i,\phi(\cdot)^\top\beta\bigr) \bigr] +\lambda\,\Omega(\beta) \Bigr\},

after which

α^(x)=[∂αg(x,⋅)]−1 ⁣(ϕ(x)⊤β^)\widehat\alpha(x)=\bigl[\partial_\alpha g(x,\cdot)\bigr]^{-1}\!\bigl(\phi(x)^\top\widehat\beta\bigr)

is recovered (Kato, 19 Feb 2026).

This formulation unifies several procedures that the paper explicitly lists as special cases of the framework: covariate balancing, nearest-neighbor matching, calibrated estimation, and density ratio estimation (Kato, 19 Feb 2026).

3. Automatic Regressor Balancing

ARB is the package’s defining methodological principle. The key observation is that if the link is chosen as

ζ(x,α)=∂αg(x,α),ζ−1(x,⋅)=(∂αg(x,⋅))−1,\zeta(x,\alpha)=\partial_\alpha g(x,\alpha), \qquad \zeta^{-1}(x,\cdot)=(\partial_\alpha g(x,\cdot))^{-1},

then the dual coordinate v(x)=ζ(x,α(x))v(x)=\zeta(x,\alpha(x)) is exactly the linear predictor ϕ(x)⊤β\phi(x)^\top\beta, so no manual link construction is needed (Kato, 19 Feb 2026).

The balancing property arises from the KKT conditions. If

Ω(β)=1q∥β∥qq,\Omega(\beta)=\frac1q\|\beta\|_q^q,

then any minimizer β^\widehat\beta satisfies, for each feature jj,

1n∑i=1nα^(Xi) ϕj(Xi)−1n∑i=1nm(Wi,ϕj)+λ sj=0,sj∈∂ ⁣(1q∣βj∣q).\frac{1}{n}\sum_{i=1}^n \widehat\alpha(X_i)\,\phi_j(X_i) - \frac{1}{n}\sum_{i=1}^n m\bigl(W_i,\phi_j\bigr) + \lambda\,s_j = 0, \qquad s_j\in\partial\!\Bigl(\tfrac1q|\beta_j|^q\Bigr).

For q=1q=1, corresponding to the lasso penalty, this yields

∣1n∑i=1nα^(Xi) ϕj(Xi)−m(Wi,ϕj)∣≤λ.\biggl| \frac{1}{n}\sum_{i=1}^n \widehat\alpha(X_i)\,\phi_j(X_i) - m(W_i,\phi_j) \biggr| \le \lambda.

For q>1q>1, the package description states that one gets exact matching up to the multiplier βj q−1\beta_j^{\,q-1}. In particular, setting λ→0\lambda\to0 recovers exact balancing in the chosen basis (Kato, 19 Feb 2026).

This makes ARB more than an implementation convenience. It converts the choice of generator gg, basis ϕ\phi, and penalty Ω\Omega into an explicit balance geometry. A plausible implication is that the package can be interpreted as a convex balance engine whose estimand-specific content is supplied through the oracle mm.

4. Software design and representer-model specification

The package exposes a core API centered on a callable target functional, a basis object, and a Bregman generator. The basic pattern is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from genriesz import grr_functional

res = grr_functional(
    X=X,                       # (n,d) numpy array
    Y=Y,                       # (n,) array
    m=m,                       # callable functional
    basis=phi,                 # instance of Basis class
    generator=g,               # BregmanGenerator
    cross_fit=True, folds=5,   # enable cross–fitting
    estimators=("ra","rw","arw","tmle"),
    riesz_penalty="l1", riesz_lam=1e-3,
    outcome_models="shared",
    outcome_penalty="l2", outcome_lam=1e-3
)
print(res.summary_text())
(Kato, 19 Feb 2026)

The target functional is provided as a Python function or “oracle” of the form

1
2
3
4
def m(W, gamma):
    # W = (X_i, Y_i) or (D_i, Z_i)
    # gamma: user can evaluate gamma(x)
    # return a scalar m(W, gamma)
and all inner products with the basis ϕ\phi are handled automatically (Kato, 19 Feb 2026).

The built-in representer model classes include polynomial bases, treatment-interaction bases, random-forest leaf encodings, neural embeddings, a nearest-neighbor catchment basis, and kernel-feature approximations via random Fourier or Nyström features (Kato, 19 Feb 2026). The specific classes listed are:

  • PolynomialBasis(degree=k, include_bias=True)
  • TreatmentInteractionBasis(base_basis)
  • genriesz.sklearn_basis.RandomForestLeafBasis(forest_model)
  • genriesz.torch_basis.TorchEmbeddingBasis(torch_nn_module)
  • KNNCatchmentBasis(n_neighbors=M)
  • kernel-feature approximations via random Fourier or Nyström features

The implemented Bregman generators include SquaredGenerator, UKLGenerator, BKLGenerator, BPGenerator, and PUGenerator; user-defined generators may be supplied by providing g(x,α), grad_g(x,α), inv_grad_g(x,v), and optionally grad2_g (Kato, 19 Feb 2026). The package summary also states that SquaredGenerator corresponds to g(α)=(α−C)2g(\alpha)=(\alpha-C)^2 (Kato, 19 Feb 2026).

The package is available on GitHub and on PyPI, and installation is via

1
pip install genriesz
(Kato, 19 Feb 2026)

5. Estimators, orthogonalization, and inference

Given cross-fitted estimates γ^\widehat\gamma and α^\widehat\alpha, genriesz reports four estimators (Kato, 19 Feb 2026).

Regression Adjustment (RA) is

θ^RA=1n∑i=1nm(Wi,γ^).\widehat\theta^{\mathrm{RA}} = \frac{1}{n}\sum_{i=1}^n m\bigl(W_i,\widehat\gamma\bigr).

Riesz Weighting (RW) is

θ^RW=1n∑i=1nα^(Xi) Yi.\widehat\theta^{\mathrm{RW}} = \frac{1}{n}\sum_{i=1}^n \widehat\alpha(X_i)\,Y_i.

Augmented Riesz Weighting (ARW) is

θ^ARW=1n∑i=1n[α^(Xi) (Yi−γ^(Xi))+m(Wi,γ^)].\widehat\theta^{\mathrm{ARW}} = \frac{1}{n}\sum_{i=1}^n \Bigl[ \widehat\alpha(X_i)\,\bigl(Y_i-\widehat\gamma(X_i)\bigr) + m\bigl(W_i,\widehat\gamma\bigr) \Bigr].

The TMLE-style procedure updates γ^→γ^(1)\widehat\gamma\to\widehat\gamma^{(1)} by a one-dimensional fluctuation along α^\widehat\alpha, then plugs in the updated regression (Kato, 19 Feb 2026). For Gaussian outcomes,

γ^(1)(x)=γ^(x)+ε^ α^(x),ε^=1n∑α^(Xi){Yi−γ^(Xi)}1n∑α^(Xi)2.\widehat\gamma^{(1)}(x) = \widehat\gamma(x) + \widehat\varepsilon\,\widehat\alpha(x), \qquad \widehat\varepsilon = \frac {\tfrac1n\sum \widehat\alpha(X_i)\{Y_i-\widehat\gamma(X_i)\}} {\tfrac1n\sum \widehat\alpha(X_i)^2}.

For binary outcomes, the package description states that one solves a small logistic score equation in ε\varepsilon (Kato, 19 Feb 2026).

Inference is based on KK-fold cross-fitting. The workflow described in the paper is:

1
2
3
4
5
6
7
for k in 1…K:
    train nuisance (α,γ) on all but fold k
    predict on fold k
stack predictions → full-sample α_i, γ_i
compute score ψ_i = ψ(W_i; …)
estimate Var = sample variance of ψ_i
form Wald CIs and p-values

Under the rate condition

∥α^−α0∥2 ∥γ^−γ0∥2=op(n−1/2),\|\widehat\alpha-\alpha_0\|_2\,\|\widehat\gamma-\gamma_0\|_2=o_p(n^{-1/2}),

the ARW and TMLE estimators are asymptotically normal (Kato, 19 Feb 2026).

This combination of orthogonal scoring and automatic representer estimation suggests that genriesz is built to support both causal and structural functionals without requiring a bespoke orthogonal-score derivation for each new estimand, provided the estimand can be encoded through the oracle mm.

6. Canonical workflows and empirical examples

The package highlights representative workflows for the average treatment effect (ATE), average treatment effect on the treated (ATT), panel difference-in-differences, average marginal effects (AME), and nearest-neighbor matching (Kato, 19 Feb 2026).

For ATE with polynomial features and an unnormalized-KL generator, the documented pattern is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from genriesz import (
    grr_ate,
    PolynomialBasis,
    TreatmentInteractionBasis,
    UKLGenerator
)

psi = PolynomialBasis(degree=2, include_bias=True)
phi = TreatmentInteractionBasis(base_basis=psi)

gen = UKLGenerator(C=1.0,
      branch_fn=lambda x: int(x[0]==1.0)
      ).as_generator()

res = grr_ate(
    X=X, Y=Y,
    basis=phi,
    generator=gen,
    cross_fit=True, folds=5,
    estimators=("ra","rw","arw","tmle"),
    riesz_penalty="l2", riesz_lam=1e-3
)
print(res.summary_text())
(Kato, 19 Feb 2026)

For ATT and panel DID, the package provides grr_att and grr_did with SquaredGenerator (Kato, 19 Feb 2026). For AME, grr_ame accepts a coordinate index for the derivative target:

1
2
3
4
5
6
7
8
9
10
11
from genriesz import grr_ame, SquaredGenerator

phi = PolynomialBasis(degree=2, include_bias=True)
res_ame = grr_ame(
    X=X, Y=Y,
    coordinate=2,    # derivative w.r.t. X[:,2]
    basis=phi,
    generator=SquaredGenerator().as_generator(),
    cross_fit=True, folds=5,
    estimators=("ra","rw","arw","tmle")
)
(Kato, 19 Feb 2026)

The nearest-neighbor matching mode uses riesz_method="nn_matching" and KNNCatchmentBasis, with the note that the basis is unused when outcome_models="none" (Kato, 19 Feb 2026).

These examples illustrate the intended division of labor. The estimand enters through a task-specific wrapper or oracle; the representer model is chosen through a basis; and the balance geometry is controlled by the generator and penalty. This suggests a deliberately modular architecture rather than separate implementations for each estimand.

7. Hyperparameters, scaling, and practical usage

The package description gives specific practical guidance on λ\lambda, basis design, and computational scaling (Kato, 19 Feb 2026). In ℓ1\ell_1-penalized fitting, λ\lambda directly controls the maximum sample imbalance in each basis moment; setting λ→0\lambda\to0 enforces near exact balancing. In ℓ2\ell_2-penalized fitting, λ\lambda stabilizes the system of equations when the basis is high-dimensional or collinear (Kato, 19 Feb 2026).

For basis selection, low-degree polynomial or random Fourier features are said often to suffice in moderate dimensions. For very large pp, one can embed through a random-forest leaf encoder or a frozen neural network via genriesz.torch_basis; the final Riesz solver remains a convex ℓp\ell_p-problem in β\beta (Kato, 19 Feb 2026).

On scaling, the core relies on SciPy’s L-BFGS-B for smooth penalties and a smooth approximation of the ℓ1\ell_1 penalty, and the package description states that it comfortably handles thousands of parameters (Kato, 19 Feb 2026). For very large pp or nn, suggested mitigations are subsampling, sparse features, and parallel cross-fitting (Kato, 19 Feb 2026).

The paper also includes empirical guidance from usage experiments: if results are unstable, increase λ\lambda or reduce basis dimension; when the true representer is believed sparse in ϕ\phi, ℓ1\ell_1 penalty plus small λ\lambda can recover approximate sparsity; and the default squared generator is described as robust and often a good first try, while KL-type generators are suggested when entropy balancing or positivity constraints are desired (Kato, 19 Feb 2026).

In summary, genriesz presents a single coherent interface for defining an estimand mm, choosing a basis ϕ\phi, picking a Bregman generator gg, and solving the resulting convex generalized Riesz regression problem (Kato, 19 Feb 2026). Its distinguishing contribution is the automation of representer estimation through ARB, coupled with cross-fitted DML-style inference for a family of causal and structural targets.

Definition Search Book Streamline Icon: https://streamlinehq.com
References (1)

Topic to Video (Beta)

No one has generated a video about this topic yet.

Whiteboard

No one has generated a whiteboard explanation for this topic yet.

Follow Topic

Get notified by email when new papers are published related to genriesz.