mtgarch 0.1.0__tar.gz

mtgarch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Uzair
+
+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.

mtgarch-0.1.0/PKG-INFO

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

mtgarch-0.1.0/README.md

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

mtgarch-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mtgarch"
+version = "0.1.0"
+description = "Censored GARCH(1,1) estimation under price limits / circuit breakers (Morgan & Trevor, 1999)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Muhammad Uzair", email = "uzairlovesironman@gmail.com" }
+]
+keywords = ["garch", "volatility", "censored likelihood", "price limits", "econometrics", "time series"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy>=1.8",
+]
+
+[project.optional-dependencies]
+fast = ["numba>=0.56"]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/uzair1509/psx-censored-volatility"
+Repository = "https://github.com/uzair1509/psx-censored-volatility"
+"Preprint (SSRN)" = "https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7527759"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mtgarch-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mtgarch-0.1.0/src/mtgarch/__init__.py

@@ -0,0 +1,37 @@
+"""mtgarch: censored-GARCH(1,1) estimation under price limits.
+
+An implementation of the expected-shock censored-GARCH approach of
+Morgan & Trevor (1999), extended with an explicit, numerically stable
+comparison against the naive (censoring-ignoring) and censored
+(clipped-recursion) alternatives.
+
+See :mod:`mtgarch.core` for the full estimator API and references.
+"""
+from .core import (
+    X0,
+    censored_nll,
+    fit_all,
+    fit_censored,
+    fit_latent,
+    fit_naive,
+    garch_variance_path,
+    garch_variance_path_breach,
+    latent_nll,
+    naive_nll,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "X0",
+    "garch_variance_path",
+    "garch_variance_path_breach",
+    "naive_nll",
+    "censored_nll",
+    "latent_nll",
+    "fit_naive",
+    "fit_censored",
+    "fit_latent",
+    "fit_all",
+]

mtgarch-0.1.0/src/mtgarch/core.py

@@ -0,0 +1,294 @@
+"""Censored-GARCH(1,1) estimation under price limits / circuit breakers.
+
+Three estimators, all Gaussian-innovation GARCH(1,1), differing only in how
+they handle observations censored by a symmetric or asymmetric price band
+(e.g. an exchange daily price limit):
+
+  naive     : ignores censoring entirely -- treats the clipped observed
+              return as if it were the true return. Systematically
+              underestimates alpha (shock sensitivity) when censoring is
+              frequent, since large true shocks get truncated before they
+              reach the likelihood.
+
+  censored  : uses the correct censored likelihood (upper/lower tail
+              probabilities in place of a density on censored days), but
+              feeds the *observed* (clipped) return back into next period's
+              variance recursion. This is a natural implementation
+              shortcut, but it systematically over-corrects: Monte Carlo
+              validation shows it inflates alpha, because it treats a
+              possibly-far-out-in-the-tail latent shock as if it were
+              exactly at the band edge.
+
+  latent    : uses the correct censored likelihood AND feeds the correct
+              conditional expectation E[r*^2 | r* censored] into next
+              period's variance recursion, exploiting the closed-form
+              truncated-normal second moment. This is the theoretically
+              consistent (up to a small non-vanishing bias -- see the
+              accompanying paper) member of the family and the one that
+              should be used for inference.
+
+  This is an implementation of the expected-shock censored-GARCH approach
+  of Morgan & Trevor (1999), with the ``latent`` and ``censored`` maths
+  spelled out explicitly here so both are directly comparable, plus a
+  numerically robust breach-day convention shared across all three
+  estimators (see ``garch_variance_path_breach``).
+
+All three share the same GARCH(1,1) variance recursion:
+
+    sigma2[t] = omega + alpha * e2[t-1] + beta * sigma2[t-1]
+
+differing only in what e2[t-1] is on a censored or "breach" day (a day
+excluded from the likelihood entirely -- a bad tick, an ex-dividend date,
+etc.): naive uses the raw observed r^2; censored uses the clipped observed
+r^2; latent uses E[r*^2 | r* censored]; and all three, on a breach day, use
+the model's own current variance forecast sigma2[t] (there being no
+information to do otherwise), rather than zeroing the return -- a
+convention that keeps naive/censored and latent comparable on days neither
+model actually observes.
+
+Basic usage
+-----------
+>>> import numpy as np
+>>> from mtgarch import fit_all
+>>> r = np.random.default_rng(0).normal(0, 0.02, 2000)
+>>> # up/lo: boolean masks marking days where the true return was censored
+>>> # at the upper / lower band; r_up/r_lo: the band edges on those days;
+>>> # use: boolean mask of days to include in the likelihood (False on
+>>> # 'breach' days such as bad ticks or corporate-action jumps).
+>>> up = lo = np.zeros(len(r), dtype=bool)
+>>> r_up = r_lo = np.zeros(len(r))
+>>> use = np.ones(len(r), dtype=bool)
+>>> result = fit_all(r, r_up, r_lo, up, lo, use)
+>>> sorted(result.keys())
+['censored', 'latent', 'naive']
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from scipy.optimize import minimize
+from scipy.signal import lfilter
+from scipy.stats import norm
+
+try:  # optional speed-up; pure Python fallback is fine (~1s per series)
+    from numba import njit
+except ImportError:  # pragma: no cover - exercised only without numba installed
+    def njit(*a, **k):
+        return (lambda f: f) if not (a and callable(a[0])) else a[0]
+
+__all__ = [
+    "X0",
+    "garch_variance_path",
+    "garch_variance_path_breach",
+    "naive_nll",
+    "censored_nll",
+    "latent_nll",
+    "fit_naive",
+    "fit_censored",
+    "fit_latent",
+    "fit_all",
+]
+
+#: Default GARCH(1,1) starting point (omega, alpha, beta) for the optimizer.
+X0 = np.array([1e-4, 0.10, 0.85])
+
+_OPTS = dict(method="Nelder-Mead", options={"maxiter": 4000, "xatol": 1e-7, "fatol": 1e-6})
+
+
+def garch_variance_path(r, omega, alpha, beta):
+    """GARCH(1,1) variance path via ``scipy.signal.lfilter``.
+
+    sigma2[0] = var(r); sigma2[t] = omega + alpha*r[t-1]**2 + beta*sigma2[t-1].
+
+    Fast path for series with no breach days. Use
+    :func:`garch_variance_path_breach` when a breach mask needs to be
+    honored -- it falls back to this function automatically when there is
+    nothing to handle.
+    """
+    s0 = np.var(r)
+    x = omega + alpha * np.asarray(r)[:-1] ** 2
+    y = lfilter([1.0], [1.0, -beta], x, zi=[beta * s0])[0]
+    return np.concatenate(([s0], y))
+
+
+@njit(cache=True)
+def _variance_path_breach_loop(w, a, b, r, breach):
+    n = len(r)
+    s2 = np.empty(n)
+    s2[0] = np.var(r)
+    for t in range(1, n):
+        e2 = s2[t - 1] if breach[t - 1] else r[t - 1] * r[t - 1]
+        s2[t] = w + a * e2 + b * s2[t - 1]
+    return s2
+
+
+def garch_variance_path_breach(r, omega, alpha, beta, breach):
+    """Breach-aware GARCH(1,1) variance path.
+
+    On a breach day (``breach[t]`` True -- a day excluded from the
+    likelihood entirely, e.g. a bad tick or an ex-dividend jump), the shock
+    fed forward into period t+1 is the model's own current variance
+    forecast (``e2 = sigma2[t]``), not the raw (possibly huge, spurious)
+    ``r[t]**2``, and not zero. Falls back to the faster
+    :func:`garch_variance_path` when there are no breach days (the common
+    case).
+    """
+    r = np.asarray(r, dtype=float)
+    breach = np.asarray(breach, dtype=bool)
+    if not breach[:-1].any():
+        return garch_variance_path(r, omega, alpha, beta)
+    return _variance_path_breach_loop(omega, alpha, beta, r, breach)
+
+
+def _valid(p):
+    w, a, b = p
+    return w > 0 and a >= 0 and b >= 0 and a + b < 1
+
+
+def naive_nll(p, r, use, breach=None):
+    """Negative log-likelihood for the naive (censoring-ignoring) model."""
+    if not _valid(p):
+        return 1e10
+    r = np.asarray(r)
+    use = np.asarray(use, dtype=bool)
+    if breach is None:
+        s = np.sqrt(garch_variance_path(r, *p))
+    else:
+        s = np.sqrt(garch_variance_path_breach(r, *p, breach))
+    return -norm.logpdf(r[use], scale=s[use]).sum()
+
+
+def censored_nll(p, r, r_up, r_lo, up, lo, use, breach=None):
+    """Negative log-likelihood for the censored (clipped-recursion) model."""
+    if not _valid(p):
+        return 1e10
+    r = np.asarray(r)
+    up = np.asarray(up, dtype=bool)
+    lo = np.asarray(lo, dtype=bool)
+    use = np.asarray(use, dtype=bool)
+    if breach is None:
+        s = np.sqrt(garch_variance_path(r, *p))
+    else:
+        s = np.sqrt(garch_variance_path_breach(r, *p, breach))
+    mid = use & ~up & ~lo
+    ll = norm.logpdf(r[mid], scale=s[mid]).sum()
+    ll += norm.logsf(np.asarray(r_up)[up & use] / s[up & use]).sum()   # P(latent >= upper)
+    ll += norm.logcdf(np.asarray(r_lo)[lo & use] / s[lo & use]).sum()  # P(latent <= lower)
+    return -ll
+
+
+@njit(cache=True)
+def _latent_nll(w, a, b, r, ru, rl, up, lo, use):
+    n = len(r)
+    s2 = np.var(r)
+    ll = 0.0
+    c = math.sqrt(2 * math.pi)
+    for t in range(n):
+        s = math.sqrt(s2)
+        if use[t]:
+            if up[t]:
+                z = ru[t] / s
+                tail = max(0.5 * math.erfc(z / math.sqrt(2)), 1e-300)
+                ll += math.log(tail)
+                e2 = s2 * (1 + z * math.exp(-0.5 * z * z) / c / tail)   # E[r*^2 | r* >= upper]
+            elif lo[t]:
+                z = rl[t] / s
+                tail = max(0.5 * math.erfc(-z / math.sqrt(2)), 1e-300)
+                ll += math.log(tail)
+                e2 = s2 * (1 - z * math.exp(-0.5 * z * z) / c / tail)   # E[r*^2 | r* <= lower]
+            else:
+                ll += -0.5 * math.log(2 * math.pi * s2) - 0.5 * r[t] * r[t] / s2
+                e2 = r[t] * r[t]
+        else:
+            e2 = s2  # breach day: no information, carry the forecast forward
+        s2 = w + a * e2 + b * s2
+    return -ll
+
+
+def latent_nll(p, r, r_up, r_lo, up, lo, use):
+    """Negative log-likelihood for the latent (expected-shock) model.
+
+    This is the theoretically consistent member of the family: it feeds
+    E[r*^2 | r* censored] -- the closed-form truncated-normal conditional
+    second moment -- into the variance recursion on censored days.
+    """
+    if not _valid(p):
+        return 1e10
+    r = np.asarray(r, dtype=float)
+    r_up = np.asarray(r_up, dtype=float)
+    r_lo = np.asarray(r_lo, dtype=float)
+    up = np.asarray(up, dtype=bool)
+    lo = np.asarray(lo, dtype=bool)
+    use = np.asarray(use, dtype=bool)
+    return _latent_nll(p[0], p[1], p[2], r, r_up, r_lo, up, lo, use)
+
+
+def _fit(nll_fn, args, x0=X0, extra_starts=()):
+    starts = [x0, *extra_starts]
+    fits = [minimize(nll_fn, s, args=args, **_OPTS) for s in starts]
+    return min(fits, key=lambda z: z.fun)
+
+
+def fit_naive(r, use, breach=None, x0=X0):
+    """Fit the naive GARCH(1,1) model. Returns a ``scipy.optimize`` result."""
+    return _fit(naive_nll, (r, use, breach), x0=x0)
+
+
+def fit_censored(r, r_up, r_lo, up, lo, use, breach=None, x0=X0, extra_starts=()):
+    """Fit the censored (clipped-recursion) model. Returns an optimizer result."""
+    return _fit(censored_nll, (r, r_up, r_lo, up, lo, use, breach), x0=x0, extra_starts=extra_starts)
+
+
+def fit_latent(r, r_up, r_lo, up, lo, use, x0=X0, extra_starts=()):
+    """Fit the latent (expected-shock) model. Returns an optimizer result."""
+    return _fit(latent_nll, (r, r_up, r_lo, up, lo, use), x0=x0, extra_starts=extra_starts)
+
+
+def fit_all(r, r_up, r_lo, up, lo, use, breach=None):
+    """Fit naive, censored, and latent models, warm-starting from the naive fit.
+
+    Parameters
+    ----------
+    r : array_like
+        Observed (possibly censored) log returns.
+    r_up, r_lo : array_like
+        Upper/lower band edges on each day, in the same units as ``r``.
+        Only used where ``up``/``lo`` are True.
+    up, lo : array_like of bool
+        Whether the true return on day t was censored at the upper/lower
+        band (i.e. the true return is only known to be >= r_up[t] or
+        <= r_lo[t]).
+    use : array_like of bool
+        Whether day t should be included in the likelihood at all (False
+        for a "breach" day -- a bad tick, a corporate-action jump, etc.).
+    breach : array_like of bool, optional
+        Same length as ``r``; True marks a breach day for the purpose of
+        the variance recursion (see :func:`garch_variance_path_breach`).
+        Defaults to ``~use`` if not given.
+
+    Returns
+    -------
+    dict with keys "naive", "censored", "latent", each mapping to a dict
+    with keys "omega", "alpha", "beta", "loglik", "converged".
+    """
+    r = np.asarray(r, dtype=float)
+    use = np.asarray(use, dtype=bool)
+    if breach is None:
+        breach = ~use
+
+    n = fit_naive(r, use, breach)
+    starts = [n.x] if _valid(n.x) else []
+    c = fit_censored(r, r_up, r_lo, up, lo, use, breach, extra_starts=starts)
+    L = fit_latent(r, r_up, r_lo, up, lo, use, extra_starts=starts)
+
+    def _pack(res):
+        return {
+            "omega": float(res.x[0]),
+            "alpha": float(res.x[1]),
+            "beta": float(res.x[2]),
+            "loglik": float(-res.fun),
+            "converged": bool(res.success),
+        }
+
+    return {"naive": _pack(n), "censored": _pack(c), "latent": _pack(L)}

mtgarch-0.1.0/src/mtgarch.egg-info/PKG-INFO

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

mtgarch-0.1.0/src/mtgarch.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/mtgarch/__init__.py
+src/mtgarch/core.py
+src/mtgarch.egg-info/PKG-INFO
+src/mtgarch.egg-info/SOURCES.txt
+src/mtgarch.egg-info/dependency_links.txt
+src/mtgarch.egg-info/requires.txt
+src/mtgarch.egg-info/top_level.txt
+tests/test_core.py

mtgarch-0.1.0/src/mtgarch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mtgarch-0.1.0/src/mtgarch.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.22
+scipy>=1.8
+
+[fast]
+numba>=0.56
+
+[test]
+pytest>=7.0

mtgarch-0.1.0/src/mtgarch.egg-info/top_level.txt

@@ -0,0 +1 @@
+mtgarch

mtgarch-0.1.0/tests/test_core.py

@@ -0,0 +1,99 @@
+import numpy as np
+from scipy.optimize import minimize
+
+from mtgarch import (
+    X0,
+    fit_all,
+    garch_variance_path,
+    garch_variance_path_breach,
+    latent_nll,
+    naive_nll,
+)
+
+
+def _loop(r, w, a, b):
+    s = np.zeros(len(r))
+    s[0] = np.var(r)
+    for t in range(1, len(r)):
+        s[t] = w + a * r[t - 1] ** 2 + b * s[t - 1]
+    return s
+
+
+def test_lfilter_matches_original_loop():
+    r = np.random.default_rng(0).normal(0, 0.02, 500)
+    assert np.allclose(
+        garch_variance_path(r, 2e-5, 0.12, 0.83), _loop(r, 2e-5, 0.12, 0.83)
+    )
+
+
+def test_latent_model_recovers_alpha_on_simulated_limits():
+    rng = np.random.default_rng(1)
+    w, a, b, T, L = 2e-5, 0.15, 0.80, 3000, 0.04
+    s2 = w / (1 - a - b)
+    lat = np.zeros(T)
+    for t in range(T):
+        lat[t] = np.sqrt(s2) * rng.standard_normal()
+        s2 = w + a * lat[t] ** 2 + b * s2
+    r = np.clip(lat, -L, L)
+    up, lo, use = r >= L, r <= -L, np.ones(T, bool)
+    ru, rl = np.full(T, L), np.full(T, -L)
+    opts = dict(method="Nelder-Mead", options={"maxiter": 4000})
+    n = minimize(naive_nll, X0, args=(r, use), **opts).x
+    l = minimize(latent_nll, n, args=(r, ru, rl, up, lo, use), **opts).x
+    assert n[1] < a  # naive attenuates alpha
+    assert abs(l[1] - a) < 0.03, (n, l)  # latent model recovers it
+
+
+def test_breach_day_uses_variance_forecast_not_zero():
+    # A breach day (ex-date jump, bad tick, etc.) feeds the model's own
+    # current variance forecast into next period's recursion (e2 = s2[t]),
+    # not a zeroed return and not the raw spurious shock.
+    w, a, b = 2e-5, 0.15, 0.80
+    r = np.array([0.01, 0.5, -0.02, 0.03, 0.015])  # index 1 is a breach
+    breach = np.array([False, True, False, False, False])
+    s2 = garch_variance_path_breach(r, w, a, b, breach)
+    expected_s2_1 = np.var(r)
+    expected_s2_1 = w + a * (r[0] ** 2) + b * expected_s2_1
+    expected_s2_2 = w + a * expected_s2_1 + b * expected_s2_1
+    assert np.isclose(s2[2], expected_s2_2)
+    assert not np.isclose(s2[2], w + a * (r[1] ** 2) + b * expected_s2_1)
+
+
+def test_no_breach_matches_fast_lfilter_path():
+    r = np.random.default_rng(3).normal(0, 0.02, 300)
+    breach = np.zeros(len(r), dtype=bool)
+    assert np.allclose(
+        garch_variance_path_breach(r, 2e-5, 0.12, 0.83, breach),
+        garch_variance_path(r, 2e-5, 0.12, 0.83),
+    )
+
+
+def test_fit_all_returns_three_models_with_expected_keys():
+    rng = np.random.default_rng(2)
+    r = rng.normal(0, 0.02, 800)
+    up = lo = np.zeros(len(r), dtype=bool)
+    r_up = r_lo = np.zeros(len(r))
+    use = np.ones(len(r), dtype=bool)
+    result = fit_all(r, r_up, r_lo, up, lo, use)
+    assert set(result) == {"naive", "censored", "latent"}
+    for name, fit in result.items():
+        assert set(fit) == {"omega", "alpha", "beta", "loglik", "converged"}
+        assert fit["omega"] > 0
+        assert 0 <= fit["alpha"]
+        assert 0 <= fit["beta"]
+
+
+def test_fit_all_naive_understates_alpha_under_censoring():
+    rng = np.random.default_rng(4)
+    w, a, b, T, L = 2e-5, 0.15, 0.80, 2000, 0.04
+    s2 = w / (1 - a - b)
+    lat = np.zeros(T)
+    for t in range(T):
+        lat[t] = np.sqrt(s2) * rng.standard_normal()
+        s2 = w + a * lat[t] ** 2 + b * s2
+    r = np.clip(lat, -L, L)
+    up, lo = r >= L, r <= -L
+    use = np.ones(T, dtype=bool)
+    r_up, r_lo = np.full(T, L), np.full(T, -L)
+    result = fit_all(r, r_up, r_lo, up, lo, use)
+    assert result["naive"]["alpha"] < result["latent"]["alpha"]