aersn for Python

Affine-equivariant adjusted-range self-normalization for time-series inference.

Version 0.1.0. This is a native NumPy/SciPy implementation: installation and use require neither R nor the R package. The related R package has its own version and release process.

What it does

Given an estimate and observation-level influence contributions, aersn computes an adjusted-range test and joint confidence region without estimating the long-run covariance matrix. It also reports simultaneous intervals for linear contrasts. Built-in entry points cover sample means and ordinary least squares (OLS). Other asymptotically linear estimators can use from_influence.

For vector parameters, the self-normalizer is the convex hull of increments of the centered influence path. The gauge of a vector is the smallest nonnegative multiple of this hull that contains the vector. It is computed by linear programming; the support in each direction is the range of the projected path. The construction is affine equivariant. Two- and three-dimensional regions are polygons and polyhedra, not fitted ellipses or ellipsoids.

Install

Python 3.11 or newer is required. Install from PyPI, preferably in a virtual environment:

python -m pip install aersn

To include two- and three-dimensional plotting:

python -m pip install "aersn[plot]"

The base installation needs NumPy and SciPy. The plot extra adds Matplotlib. To reproduce results with this specific version:

python -m pip install "aersn[plot]==0.1.0"

For an offline copy supplied by the authors, run python -m pip install "./aersn-0.1.0-py3-none-any.whl[plot]" from the directory containing the wheel. To install an extracted source distribution instead, run python -m pip install ".[plot]" from its top-level directory.

A first example

import numpy as np
import aersn

rng = np.random.default_rng(10)
y = rng.normal(size=(300, 2))
for t in range(1, len(y)):
    y[t] += 0.35 * y[t - 1]

fit = aersn.mean(y, names=["Mean 1", "Mean 2"])
ref = fit.reference(draws=2_000, seed=71)
test = fit.test([0, 0], reference=ref)
print(test.statistic, test.pvalue, test.mcse)
print(fit.confint(reference=ref))

region = fit.region(reference=ref)
ax = region.plot()
ax.figure.savefig("joint-region.png", dpi=180)

The small reference simulation above is for illustration. The default is 10,000 draws; increase it when Monte Carlo uncertainty affects a substantive decision. Reuse a reference for the same dimension and grid, rather than simulating it again for each null hypothesis. Reusing a reference from a different sample size, dimension or grid raises an error. The particular random sample may reject its generating mean; the example is not a demonstration of an exact finite-sample rejection rate.

Statistical interpretation

• The input convention is sqrt(n) * (estimate - theta) = sum(psi_true) / sqrt(n) + o_p(1). Rows of psi are observations in time order, not resampled or sorted records.
• A functional central limit theorem, asymptotic linearity and a valid estimated influence path are required. Numerical full rank does not verify these assumptions.
• Matched-grid Brownian quantiles account for the grid used to evaluate the reference path. They do not make inference finite-sample exact for general dependent data.
• confint and contrast project a joint region. These are simultaneous intervals, not separately constructed marginal intervals.
• A supplied nonlinear variance-accumulation profile needs a model-specific justification. Merely substituting such a profile for a sample mean does not construct the required path. See USER_GUIDE.md in the source distribution.
• Missing values, including masked NumPy entries, are rejected. Paths that remain extremely ill-conditioned after coordinate scaling raise an error; the package does not regularize them silently.

Documentation and examples

The source distribution includes:

• USER_GUIDE.md: statistical interpretation and API conventions.
• VALIDATION.md: numerical validation and release checks.
• examples/mean_regions.py: executable 2D and 3D example.
• examples/regression.py: OLS and influence-contribution example.

Run the examples from this directory:

python examples/mean_regions.py
python examples/regression.py

Figures are saved in examples/output/ with labeled axes. Function and class docstrings are also available through Python's help(). Plots use independent axis scales by default, which is useful for parameters measured in different units. Use region.plot(equal_scale=True) for equal distance per data unit. Both choices display the same computed vertices.

Development

python -m pip install -e ".[plot,test,dev]"
python -m pytest --cov=aersn
python -m ruff check .
python -m build
python -m twine check dist/*

Tests use fixed inputs and results exported from R aersn 0.2.3. They do not require R. The LP is also checked against an independent primal calculation. This release implements the adjusted-range method, not the five comparison methods or every model-specific interface in the R package.

Paper and authors

Yongmiao Hong, Zhuo Lin, Oliver Linton, Whitney K. Newey and Jiajing Sun (2026), Affine-Equivariant Adjusted-Range Self-Normalization, Cambridge Working Papers in Economics, No. 2678. The paper is available as a Cambridge working paper. This citation does not imply journal acceptance.

Copyright belongs to the five authors. Distributed under the MIT license. Maintainer: Jiajing Sun, jiajing.sun@gmail.com.