Metadata-Version: 2.4
Name: mtgarch
Version: 0.1.0
Summary: Censored GARCH(1,1) estimation under price limits / circuit breakers (Morgan & Trevor, 1999)
Author-email: Muhammad Uzair <uzairlovesironman@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/uzair1509/psx-censored-volatility
Project-URL: Repository, https://github.com/uzair1509/psx-censored-volatility
Project-URL: Preprint (SSRN), https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7527759
Keywords: garch,volatility,censored likelihood,price limits,econometrics,time series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Provides-Extra: fast
Requires-Dist: numba>=0.56; extra == "fast"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# mtgarch

Censored GARCH(1,1) estimation for markets with price limits or circuit
breakers -- an implementation of the expected-shock censored-GARCH approach
of Morgan & Trevor (1999), with three directly comparable estimators:

- **naive** -- ignores censoring; systematically understates shock
  sensitivity (alpha) when censoring is frequent.
- **censored** -- correct censored likelihood, but feeds the *clipped*
  observed return into the variance recursion; over-corrects alpha.
- **latent** -- correct censored likelihood *and* feeds the closed-form
  conditional expectation `E[r*^2 | r* censored]` into the recursion; the
  theoretically consistent member of the family.

Built for and validated on a full-exchange study of the Pakistan Stock
Exchange's daily price-limit rule (449 companies, 2016-2026); see the
accompanying paper and dataset below.

## Install

```bash
pip install mtgarch
```

Add the optional `fast` extra for a `numba`-accelerated inner loop
(recommended for large panels):

```bash
pip install "mtgarch[fast]"
```

## Usage

```python
import numpy as np
from mtgarch import fit_all

r = ...      # observed (possibly censored) log returns
r_up, r_lo = ...   # band edges on each day (only used where up/lo are True)
up, lo = ...       # bool masks: was day t censored at the upper/lower band?
use = ...          # bool mask: include day t in the likelihood at all?

result = fit_all(r, r_up, r_lo, up, lo, use)
result["naive"]["alpha"], result["latent"]["alpha"]
```

Each of `result["naive"]`, `result["censored"]`, `result["latent"]` is a
dict with `omega`, `alpha`, `beta`, `loglik`, `converged`.

Lower-level building blocks (`naive_nll`, `censored_nll`, `latent_nll`,
`garch_variance_path`, `garch_variance_path_breach`) are also exported for
custom optimization setups -- see `mtgarch.core` docstrings.

## Citing

If you use this package, please cite:

Uzair, M. (2026). *Price Limits Hide Volatility: Censored GARCH Evidence
from the Pakistan Stock Exchange*. SSRN Working Paper, Abstract ID 7527759.

## Links

- Paper / data / analysis code: https://github.com/uzair1509/psx-censored-volatility
- Preprint: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7527759

## License

MIT
