Metadata-Version: 2.4
Name: aersn
Version: 0.1.0
Summary: Affine-equivariant adjusted-range self-normalization for time-series inference
Author: Yongmiao Hong, Zhuo Lin, Oliver Linton, Whitney K. Newey
Author-email: Jiajing Sun <jiajing.sun@gmail.com>
Maintainer-email: Jiajing Sun <jiajing.sun@gmail.com>
License-Expression: MIT
Project-URL: Paper, https://www.janeway.econ.cam.ac.uk/publication/affine-equivariant-adjusted-range-self-normalization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Requires-Dist: matplotlib>=3.7; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Dynamic: license-file

# 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:

```sh
python -m pip install aersn
```

To include two- and three-dimensional plotting:

```sh
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:

```sh
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

```python
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:

```sh
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

```sh
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](https://www.janeway.econ.cam.ac.uk/publication/affine-equivariant-adjusted-range-self-normalization).
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>.
