aersn 0.1.0__tar.gz

aersn-0.1.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changes
+
+## 0.1.0
+
+- First public-release build, following the 0.1.0a3 Windows checks and TestPyPI
+  download-and-install verification.
+- Update the version and installation instructions for PyPI, including optional
+  plotting, exact-version installation and local wheel/source installation.
+- Retain the 0.1.0a3 statistical implementation, numerical safeguards, tests and
+  examples without changes. The package remains an early release (Beta classifier).
+
+## 0.1.0a3
+
+- Preserve missing-value masks in lists and tuples of array rows before numeric
+  conversion. Reject masked rows through the mean, OLS and influence interfaces;
+  retain identical results for unmasked lists, tuples and arrays.
+- Explain how to construct a justified lower-dimensional target when the full
+  fit is rejected before an object exists. Full-model nuisance effects must be
+  retained; neither the conditioning limit nor the statistical model is changed.
+- Qualify boundary-membership guidance for large centers and ill-conditioned
+  paths. The gauge tolerance and hypothesis-test rule are unchanged.
+- Update installation instructions for this local candidate and distinguish them
+  from commands to use after an announced PyPI release.
+- Print the tested artifact version and a final pass summary in the platform
+  runner; verify that the installed version matches the selected artifact.
+
+This candidate passed 150 tests after both wheel and source installation on
+Windows and was uploaded to TestPyPI on 27 September 2026. Both downloaded
+artifacts matched the tested files and passed 150 tests each on macOS.
+
+## 0.1.0a2
+
+- Reject masked observations before converting NumPy arrays. Fully unmasked
+  masked-array containers remain accepted; no observations are silently removed.
+- Check the path's condition number after coordinate range scaling. Values above
+  1e8 now raise `NumericalError`; exactly/numerically rank-deficient paths retain
+  `DegeneratePathError`. Original-coordinate dual constraints and objectives are
+  checked after the LP. No regularization is introduced.
+- Add high-precision stress fixtures, including the actual Windows failure, and
+  explicit tests of rejection outside the supported numerical range. Tighten
+  ordinary R comparisons and supported affine-transformation tolerances.
+- Default plots to independent axis scales; add `equal_scale=True`, reduce 3D
+  tick crowding, and explain how to install the optional Matplotlib dependency.
+- Make the user guide's runnable examples work in order, distinguish the
+  model-specific schematic call, and test README and guide examples automatically.
+- Document membership tolerance versus strict test decisions. Scalar candidate
+  lists now accept one candidate per element.
+- Give wheel installation instructions and remove repository-relative Markdown
+  links from the package-index description. Preserve the illustrative random seed.
+- Select artifacts by the current package version in the Windows runner. Keep
+  old-version logs separate. The unchanged external audit can be requested with
+  `--legacy-audit`; its expected-failure marks and unconditional acceptance of
+  extremely ill-conditioned paths describe 0.1.0a1, not the revised contract.
+
+This version has not been uploaded to TestPyPI or PyPI. It does not modify the
+separately submitted R 0.2.3 package.

aersn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yongmiao Hong, Zhuo Lin, Oliver Linton, Whitney K. Newey and Jiajing Sun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aersn-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md USER_GUIDE.md VALIDATION.md CHANGELOG.md
+recursive-include tests *.py *.json
+recursive-include examples *.py
+recursive-include tools *.R

aersn-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+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>.

aersn-0.1.0/README.md

@@ -0,0 +1,146 @@
+# 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>.

aersn-0.1.0/USER_GUIDE.md

@@ -0,0 +1,275 @@
+# Using aersn in Python
+
+## 1. Observations, estimates and influence contributions
+
+Let `estimate` contain q estimated parameters. The input `psi` is an n-by-q
+matrix: row t is the estimated influence contribution of observation t, and
+column j corresponds to parameter j. Observations must remain in time order.
+The sample size is always the number of rows; it is not the number of grid
+nodes, regression coefficients or reference draws.
+
+The centered path is
+
+```text
+G[k] = (sum(psi[:k]) - nodes[k] * sum(psi)) / sqrt(n),  k=0,...,n.
+```
+
+With the default `nodes[k]=k/n`, this is calendar-time centering. Both endpoints
+are zero. The increment hull is `K = conv{G[i]-G[j]}`. For a null vector v,
+the statistic is `gamma_K(sqrt(n)*(estimate-v))`. Larger values provide greater
+evidence against the null.
+The gauge `gamma_K(z)` is the smallest nonnegative number a such that z belongs
+to a*K.
+
+For the sample mean, use `aersn.mean(y)`; it calculates the mean and contributions
+`y-y.mean(axis=0)`. The following equivalent influence-contribution construction
+also provides the runnable example used in Sections 2 and 3:
+
+```python
+import numpy as np
+import aersn
+
+y = np.random.default_rng(10).normal(size=(300, 2))
+estimate = y.mean(axis=0)
+psi = y - estimate
+fit = aersn.from_influence(estimate, psi, names=["parameter 1", "parameter 2"])
+```
+
+The contributions must account for all estimated nuisance parameters. For
+example, the influence contribution of an ordinary least squares (OLS) slope
+depends on the inverse moment matrix of the full regression, not just that
+slope's regressor. Missing values (including NumPy masked entries) and nonfinite
+values are rejected rather than silently
+dropped; deleting time observations can change the statistical problem.
+
+## 2. Tests and reference distributions
+
+```python
+ref = fit.reference(draws=10_000, seed=1)
+result = fit.test([0, 0], reference=ref, level=0.95)
+print(result.statistic, result.critical_value, result.reject)
+print(result.pvalue, result.mcse, result.tail_interval)
+```
+
+Here `level=0.95` means a 5 percent test and a 95 percent confidence region.
+The default alternative is `"two-sided"`. Rejection occurs when the statistic
+strictly exceeds the estimated reference quantile. For a scalar parameter,
+`alternative="greater"` or `"less"` uses the signed endpoint-to-range ratio.
+One-sided alternatives are not available for a joint vector hypothesis.
+
+For each reference draw, Brownian increments have variances equal to the grid
+spacings. They form a Brownian bridge at those nodes. An independent standard
+normal vector provides the numerator. The same gauge calculation is used for
+data and reference paths. A failed draw stops the calculation instead of being
+discarded. The generator is a local NumPy PCG64 generator; the global random
+state is unchanged. With the same environment, seed, dimension and grid, the
+first B draws remain the same when more draws are requested.
+
+Empirical quantiles use the median-unbiased convention, equivalent to R's
+`quantile(..., type=8)`. Reference p-values are the fraction of draws at least
+as large as the observed statistic, matching R `aersn` 0.2.3. They do not use
+a plus-one correction. `mcse` is the binomial Monte Carlo standard error, and
+`tail_interval` is a 95 percent binomial interval for the reference tail
+probability. A reported zero p-value does not establish that the true tail
+probability is zero. These quantities describe simulation error, not the
+accuracy of the statistical approximation for the observed data.
+
+```python
+print(ref.quantile([0.90, 0.95, 0.99]))
+print(ref.quantile_mcse([0.90, 0.95, 0.99]))
+```
+
+Quantile standard errors are estimated using interleaved batches. Tail counts
+and interpolated quantiles need not give exactly identical decisions at a
+finite Monte Carlo boundary. The reported `reject` always uses the critical
+value comparison.
+
+For a scalar parameter only, an analytic alternative is available:
+
+```python
+ref_continuous = aersn.Reference.continuous()
+print(aersn.scalar_quantile([0.90, 0.95, 0.99]))
+# approximately 1.397390, 1.705776, 2.367378
+```
+
+This is the continuous-path reference, not the matched finite-grid reference.
+`scalar_cdf` and `scalar_quantile` describe the absolute ratio; `scalar_density`
+is the density of the signed ratio. Its density integrates to one over the
+whole real line.
+
+## 3. Confidence regions and linear contrasts
+
+At a reference quantile c, the joint region is
+
+```text
+C = estimate + c/sqrt(n) * K.
+```
+
+```python
+region = fit.region(reference=ref, level=0.95)
+print(region.contains([0, 0]))
+print(region.confint())
+intervals = region.contrast([[1, -1], [0.5, 0.5]])
+print(intervals.estimate, intervals.lower, intervals.upper)
+```
+
+Each contrast interval is `a @ estimate +/- c*range(G @ a)/sqrt(n)`.
+These intervals use the q-dimensional critical value and inherit simultaneous
+coverage from the joint region. They are not tests of a single contrast using
+a one-dimensional critical value. For that different question, first form a
+lower-dimensional target and then generate the corresponding reference:
+
+```python
+target = fit.transform([[1, -1]], names=["difference"])
+target_ref = target.reference(draws=10_000, seed=1)
+target.test(0, reference=target_ref)
+```
+
+`region.contains` permits a default tolerance of 1e-9 in region-gauge units;
+`fit.test` uses the strict critical-value rule.
+Their Boolean answers can differ within numerical rounding distance of a
+boundary. `region.contains(..., tol=0)` removes the membership tolerance but
+does not remove floating-point roundoff. Computed vertices can fall outside
+this tolerance when the estimate is large relative to the region width or
+the path is ill-conditioned; membership at such boundary points is sensitive
+to rounding.
+
+For a nonsingular q-by-q transformation H, `fit.transform(H, offset=b)` implements
+`H @ estimate + b` and `psi @ H.T`. The corresponding confidence region is the
+same affine transformation of the original region, up to numerical precision.
+The original reference can then be reused because q and the grid are unchanged.
+
+## 4. Regression
+
+```python
+import numpy as np
+import aersn
+
+rng = np.random.default_rng(19)
+x = rng.normal(size=(200, 2))
+y_ols = 1 + x @ [0.5, -0.3] + rng.normal(size=200)
+fit_ols = aersn.ols(y_ols, x)  # an intercept is added
+print(fit_ols.names, fit_ols.estimate)
+# For two regressors, select the first slope, retaining nuisance effects:
+slope = fit_ols.transform([[0, 1, 0]], names=["first slope"])
+```
+
+To use a design matrix that already contains an intercept, set `intercept=False`.
+The interface uses QR decomposition and calendar-time centering. It assumes
+the usual asymptotic linear representation and strong identification. Generalized
+method of moments (GMM) and conditional-likelihood convenience interfaces are
+not yet included. Their appropriately constructed influence contributions can
+be supplied through `from_influence`; the package does not fit those models.
+
+## 5. Two- and three-dimensional figures
+
+```python
+import numpy as np
+import aersn
+
+data3 = np.random.default_rng(21).normal(size=(200, 3))
+fit3 = aersn.mean(data3, names=["Mean 1", "Mean 2", "Mean 3"])
+ref3 = fit3.reference(draws=2_000, seed=7)
+region3 = fit3.region(reference=ref3)
+ax = region3.plot()
+ax.figure.savefig("region.png", dpi=180)
+```
+
+For a coordinate projection, specify two or three coordinate indices. For
+example, project this three-dimensional region onto its first and third axes:
+
+```python
+ax = region3.plot(coords=[0, 2])  # Python uses zero-based indices
+vertices = region3.projection([0, 1, 2])
+```
+
+This is a projection of the full joint region, not a slice holding other
+parameters fixed. Axis labels use the parameter names. Boundaries come from
+actual hull vertices, with straight edges and planar faces wherever present.
+No smoothing is applied. There is no general requirement that the region
+become an ellipse or ellipsoid as the sample grows.
+Axes have independent scales by default. `region3.plot(equal_scale=True)` gives
+equal distance per data unit instead. Changing this option changes the display,
+not the numerical region, and can make coefficients with different units harder
+to compare visually.
+
+The gauge uses only the path values. Explicit plotting computes differences
+of path-hull vertices; it can be more expensive. A `max_pairs` guard on
+`region.vertices()` prevents unexpectedly large allocations. It does not
+restrict the gauge calculation.
+
+## 6. Nonuniform variance accumulation
+
+`from_influence` accepts a function of k/n or a vector of n+1 nodes. This is a
+schematic call: `estimate` and `justified_psi` must come from an appropriate
+model-specific construction, not the sample-mean example above.
+
+```text
+fit = aersn.from_influence(estimate, justified_psi, profile=lambda r: r**3)
+ref = fit.reference(draws=10_000, seed=1)
+```
+
+This interface is appropriate only when the model satisfies a common scalar
+variance-accumulation condition and the estimated path consistently approximates
+the required profile-centered path. The code checks nondecreasing nodes and
+endpoints, not these statistical conditions. In particular, demeaned sample-mean
+contributions sum to zero. Changing the nodes then leaves the fitted path
+unchanged and generally does not construct the required profile-centered path.
+For this reason `mean` and `ols` use calendar centering rather than offering
+a profile argument. Consult the paper's conditional-score construction for an
+example where feasible profile inference is justified.
+
+## 7. Rank, numerical accuracy and reproducibility
+
+`fit.hull.rank`, `condition_number` and `coordinate_ranges` describe the path.
+The condition number is the ratio of largest to smallest singular values of
+the original centered path matrix, not of a covariance estimator. Numerical
+rank is assessed after coordinate range scaling. The LP also uses pivoted QR
+to handle unequal units and near collinearity. No ridge or random jitter is
+added to singular paths. Such paths raise `DegeneratePathError`.
+
+`scaled_condition_number` reports the condition number after dividing each
+coordinate by its range. Values above 1e8 raise `NumericalError`, even if the
+path has numerical full rank. This conservative double-precision limit does
+not claim an exact error bound. Unit differences alone do not trigger it.
+The recovered LP direction is also checked in the original coordinates.
+When a path is rejected, inspect near-dependent parameters and consider a
+lower-dimensional target only when it is justified by the scientific question.
+No unreliable statistic, confidence region, or reference draw is returned.
+
+If `mean`, `ols` or `from_influence` raises during construction, no `fit` object
+exists, so `fit.transform(A)` is not available. With a reliably computed
+full-model estimate and influence contributions obtained separately, construct
+the target directly as `aersn.from_influence(A @ estimate, psi @ A.T)`.
+For OLS, the contributions must come from the full regression and retain
+nuisance-parameter effects; simply dropping regressors changes the model.
+The target path must itself pass the numerical checks, and its statistical
+validity still requires the assumptions stated above.
+
+R and Python use different random generators and LP solvers. Equal seed values
+do not yield equal reference draws across languages. The distributed tests
+instead share fixed contributions, paths, directions and reference draws.
+Record the package, NumPy and SciPy versions along with the seed and grid for
+reproducibility. Bitwise agreement across different numerical-library versions
+is not promised.
+
+## API overview
+
+| Entry point | Purpose |
+|---|---|
+| `mean(data, names=None)` | Sample-mean estimate and influence path |
+| `ols(y, x, intercept=True, names=None)` | Full OLS coefficient inference |
+| `from_influence(estimate, psi, profile=None, names=None)` | Other estimators |
+| `InfluencePath(psi, profile=None)` | Inspect centered partial sums |
+| `IncrementHull(path)` | Gauge, support and vertices |
+| `simulate_reference(q, n, profile=None, draws=..., seed=...)` | Matched-grid reference |
+| `Reference(q, nodes, draws, batches=20)` | Import known reference draws |
+| `Reference.continuous()` | Scalar continuous-path reference |
+| `fit.test(null, reference=ref)` | Test and Monte Carlo uncertainty |
+| `fit.region(reference=ref)` | Joint confidence region |
+| `fit.confint(reference=ref)` | Simultaneous coordinate intervals |
+| `fit.contrast(A, reference=ref)` | Simultaneous contrast intervals |
+| `fit.transform(A, offset=None)` | Linear reparameterization or lower-dimensional target |
+
+Arguments after the first required arguments are generally keyword-only; see
+`help(aersn.ols)` and other docstrings for exact signatures.