scmgen 0.10.0__py3-none-any.whl

scmgen/__init__.py

@@ -0,0 +1,39 @@
+"""SCM-генератор синтетических данных для uplift/CATE-бенчмарка.
+
+Спецификация: `docs/model.md`; контракт полей истины и фазы патологий (0.5.0) —
+см. CHANGELOG 0.5.0; объект SCM, уровни seed, provenance, оси 0.6.0 — `docs/model.md`;
+контракт истины 0.7.0, рецепт/replay, версионная публикация — `docs/truth-contract.md`;
+реестр патологий — `docs/pathology-catalog.md`.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from . import scenarios
+from .config import (PATHOLOGY_NUMBERS, GraphConfig, MechanismConfig, MediatorConfig, OutcomeConfig,
+                     PathologyConfig, ScenarioConfig, SegmentConfig, TauConfig, TreatmentConfig, pathology_number,
+                     pathology_phase)
+from .diagnostics import data_properties
+from .generate import Dataset, generate, generate_pair, generate_split
+from .graph import SampledGraph, graph_properties, sample_graph
+from .io import load_dataset, load_scm, prune_versions, replay, save_dataset
+from .pathologies import apply_pathologies
+from .reference import pehe, segment_dim, t_learner_ridge
+from .scm import SCM, sample_scm
+from .segments import build_segments
+from .truth import refresh_truth, truth_targets
+
+try:
+    __version__ = _pkg_version("scmgen")
+except PackageNotFoundError:          # запуск из дерева исходников без установки
+    __version__ = "0.10.0"
+
+__all__ = [
+    "ScenarioConfig", "GraphConfig", "MechanismConfig", "TauConfig",
+    "TreatmentConfig", "OutcomeConfig", "SegmentConfig", "PathologyConfig", "MediatorConfig",
+    "Dataset", "generate", "generate_pair", "generate_split", "apply_pathologies",
+    "SCM", "sample_scm", "load_scm", "replay", "prune_versions", "PATHOLOGY_NUMBERS", "pathology_number",
+    "build_segments", "SampledGraph", "sample_graph", "graph_properties",
+    "save_dataset", "load_dataset", "t_learner_ridge", "segment_dim", "pehe",
+    "data_properties", "pathology_phase", "refresh_truth", "truth_targets",
+    "scenarios", "__version__",
+]

scmgen/betafn.py

@@ -0,0 +1,158 @@
+"""Бета-распределение на numpy (0.8.0, см. CHANGELOG 0.8.0): ln Γ, регуляризованная неполная
+бета-функция I_x(a, b) и обратная к ней по x. scipy в зависимости не входит (как и для Φ⁻¹ в truth.py).
+
+Все функции поэлементны в строгом смысле: результат элемента зависит только от его аргументов. Итерации
+(цепная дробь, уточнение квантиля) идут до сходимости каждого элемента отдельно, сошедшиеся элементы
+замораживаются — поэтому вложенные выборки (`scm.sample(n₁)` — префикс `scm.sample(n₂)`) совпадают бит в бит.
+Область: a, b ∈ [1e-3, 1e4], x, p ∈ [0, 1]; точность закреплена тестами (tests/test_v080.py).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+_LANCZOS_G = 7.0
+_LANCZOS = (0.99999999999980993, 676.5203681218851, -1259.1392167224028, 771.32342877765313,
+            -176.61502916214059, 12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6,
+            1.5056327351493116e-7)
+_HALF_LOG_2PI = 0.5 * np.log(2.0 * np.pi)
+_CF_EPS = 1e-16
+_CF_TINY = 1e-300
+_CF_MAXIT = 2000
+_INV_MAXIT = 200
+
+
+def gammaln(x) -> np.ndarray:
+    """ln Γ(x), x > 0 (Ланцош g = 7, 9 членов; x < 0.5 — через Γ(x + 1) = x Γ(x))."""
+    x = np.asarray(x, dtype=float)
+    small = x < 0.5
+    z = np.where(small, x + 1.0, x) - 1.0
+    acc = np.full(x.shape, _LANCZOS[0])
+    for i in range(1, 9):
+        acc = acc + _LANCZOS[i] / (z + i)
+    t = z + _LANCZOS_G + 0.5
+    out = _HALF_LOG_2PI + (z + 0.5) * np.log(t) - t + np.log(acc)
+    return np.where(small, out - np.log(np.where(small, x, 1.0)), out)
+
+
+def betaln(a, b) -> np.ndarray:
+    """ln B(a, b)."""
+    return gammaln(a) + gammaln(b) - gammaln(np.add(a, b))
+
+
+def _betacf(a: np.ndarray, b: np.ndarray, x: np.ndarray) -> np.ndarray:
+    """Цепная дробь неполной бета-функции (модифицированный метод Ленца); одномерные массивы равной длины.
+    Каждый элемент итерируется до |Δ − 1| < eps и замораживается."""
+    out = np.empty(x.size)
+    idx = np.arange(x.size)
+    qab, qap, qam = a + b, a + 1.0, a - 1.0
+    c = np.ones(x.size)
+    d = 1.0 - qab * x / qap
+    d = 1.0 / np.where(np.abs(d) < _CF_TINY, _CF_TINY, d)
+    h = d.copy()
+    for m in range(1, _CF_MAXIT + 1):
+        m2 = 2.0 * m
+        aa = m * (b - m) * x / ((qam + m2) * (a + m2))
+        d = 1.0 + aa * d
+        d = 1.0 / np.where(np.abs(d) < _CF_TINY, _CF_TINY, d)
+        c = 1.0 + aa / c
+        c = np.where(np.abs(c) < _CF_TINY, _CF_TINY, c)
+        h = h * d * c
+        aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
+        d = 1.0 + aa * d
+        d = 1.0 / np.where(np.abs(d) < _CF_TINY, _CF_TINY, d)
+        c = 1.0 + aa / c
+        c = np.where(np.abs(c) < _CF_TINY, _CF_TINY, c)
+        delta = d * c
+        h = h * delta
+        done = np.abs(delta - 1.0) < _CF_EPS
+        if done.any():
+            out[idx[done]] = h[done]
+            keep = ~done
+            if not keep.any():
+                return out
+            idx, a, b, x, c, d, h = idx[keep], a[keep], b[keep], x[keep], c[keep], d[keep], h[keep]
+            qab, qap, qam = qab[keep], qap[keep], qam[keep]
+    out[idx] = h                                           # не сошлось за _CF_MAXIT: вне заявленной области
+    return out
+
+
+def betainc(a, b, x, lnb=None) -> np.ndarray:
+    """Регуляризованная неполная бета-функция I_x(a, b) = P(Beta(a, b) ≤ x); x вне [0, 1] обрезается.
+    lnb — заранее посчитанный ln B(a, b) (той же формы после broadcast), иначе считается здесь."""
+    a, b, x = np.broadcast_arrays(np.asarray(a, dtype=float), np.asarray(b, dtype=float),
+                                  np.asarray(x, dtype=float))
+    shape = x.shape
+    lnb = betaln(a, b) if lnb is None else np.broadcast_to(np.asarray(lnb, dtype=float), shape)
+    a, b, x, lnb = a.ravel(), b.ravel(), np.clip(x.ravel(), 0.0, 1.0), lnb.ravel()
+    out = np.where(x >= 1.0, 1.0, 0.0)
+    inner = np.flatnonzero((x > 0.0) & (x < 1.0))
+    if inner.size:
+        a, b, x, lnb = a[inner], b[inner], x[inner], lnb[inner]
+        front = np.exp(a * np.log(x) + b * np.log1p(-x) - lnb)
+        direct = x < (a + 1.0) / (a + b + 2.0)
+        aa, bb, xx = np.where(direct, a, b), np.where(direct, b, a), np.where(direct, x, 1.0 - x)
+        val = front * _betacf(aa, bb, xx) / aa
+        out[inner] = np.where(direct, val, 1.0 - val)
+    return out.reshape(shape)
+
+
+def _initial_guess(a, b, p):
+    """Начальное приближение квантиля (Numerical Recipes, invbetai)."""
+    with np.errstate(divide="ignore", invalid="ignore", over="ignore"):
+        pp = np.where(p < 0.5, p, 1.0 - p)
+        t = np.sqrt(-2.0 * np.log(pp))
+        z = (2.30753 + t * 0.27061) / (1.0 + t * (0.99229 + t * 0.04481)) - t
+        z = np.where(p < 0.5, -z, z)
+        al = (z * z - 3.0) / 6.0
+        ia, ib = 1.0 / (2.0 * a - 1.0), 1.0 / (2.0 * b - 1.0)
+        hh = 2.0 / (ia + ib)
+        w = z * np.sqrt(al + hh) / hh - (ib - ia) * (al + 5.0 / 6.0 - 2.0 / (3.0 * hh))
+        big = a / (a + b * np.exp(2.0 * w))
+        lna, lnbb = np.log(a / (a + b)), np.log(b / (a + b))
+        ta, tb = np.exp(a * lna) / a, np.exp(b * lnbb) / b
+        ww = ta + tb
+        small = np.where(p < ta / ww, np.power(a * ww * p, 1.0 / a), 1.0 - np.power(b * ww * (1.0 - p), 1.0 / b))
+        x = np.where((a >= 1.0) & (b >= 1.0), big, small)
+    return np.where(np.isfinite(x), x, 0.5)
+
+
+def betaincinv(a, b, p) -> np.ndarray:
+    """Квантиль бета-распределения: x с I_x(a, b) = p. Шаги Галлея с вилкой [lo, hi] (вне вилки — бисекция),
+    каждый элемент — до сходимости шага и замораживается."""
+    a, b, p = np.broadcast_arrays(np.asarray(a, dtype=float), np.asarray(b, dtype=float),
+                                  np.asarray(p, dtype=float))
+    shape = p.shape
+    a, b, p = a.ravel(), b.ravel(), p.ravel()
+    out = np.where(p >= 1.0, 1.0, 0.0)
+    idx = np.flatnonzero((p > 0.0) & (p < 1.0))
+    if not idx.size:
+        return out.reshape(shape)
+    a, b, p = a[idx], b[idx], p[idx]
+    lnb = betaln(a, b)
+    a1, b1 = a - 1.0, b - 1.0
+    lo, hi = np.zeros(p.size), np.ones(p.size)
+    x = np.clip(_initial_guess(a, b, p), 1e-300, 1.0 - 1e-16)
+    for _ in range(_INV_MAXIT):
+        err = betainc(a, b, x, lnb) - p
+        lo = np.where(err < 0.0, x, lo)
+        hi = np.where(err > 0.0, x, hi)
+        with np.errstate(divide="ignore", invalid="ignore", over="ignore"):
+            dens = np.exp(a1 * np.log(x) + b1 * np.log1p(-x) - lnb)
+            u = err / dens
+            step = u / (1.0 - 0.5 * np.clip(u * (a1 / x - b1 / (1.0 - x)), -1.0, 1.0))
+            new = x - step
+        bad = ~np.isfinite(new) | (new <= lo) | (new >= hi) | ~np.isfinite(dens) | (dens <= 0.0)
+        new = np.where(bad, 0.5 * (lo + hi), new)
+        done = (err == 0.0) | (np.abs(new - x) <= 4e-16 * x) | (hi - lo <= 4e-16 * hi)
+        x = np.where(err == 0.0, x, new)
+        if done.any():
+            out[idx[done]] = x[done]
+            keep = ~done
+            if not keep.any():
+                break
+            idx, a, b, p, lnb, a1, b1 = idx[keep], a[keep], b[keep], p[keep], lnb[keep], a1[keep], b1[keep]
+            lo, hi, x = lo[keep], hi[keep], x[keep]
+    else:
+        out[idx] = x
+    return out.reshape(shape)