gating-metrics 0.1.0__tar.gz

gating_metrics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liu Yuanshui and the ARDS gating-circuit study authors
+
+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.

gating_metrics-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: gating-metrics
+Version: 0.1.0
+Summary: Measurement toolkit for state-gated co-expression coupling: layer couplings, exact covariance partition, platform contrast, closed-form power planning
+Author: Liu Yuanshui
+License: MIT
+Project-URL: OSF registration, https://doi.org/10.17605/OSF.IO/4TZH9
+Project-URL: OSF project, https://osf.io/v8w5a
+Project-URL: Homepage, https://github.com/Shuiruolys-Liu/gating-metrics
+Keywords: co-expression,single-cell,gating,ARDS,inflammasome,measurement
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Dynamic: license-file
+
+# gating_metrics — measurement toolkit for state-gated co-expression coupling
+
+Open-source Python toolkit accompanying the ARDS gating-circuit study
+(manifest modules F1/F2/F3, registered 2026-08-18 before execution). It
+formalises the study's core measurement claim — that a state-gated
+hub–module coupling (e.g. KAT2A vs the inflammasome module) is an
+**individual-level, platform-dependent emergent measurement** — into
+reusable, tested routines.
+
+## What it provides
+
+| Module | Contents |
+|---|---|
+| `coupling.py` | Layer-wise Spearman coupling: `L_cell` (within-sample per-cell, with detected-gene-count partial sensitivity), `L_indiv` (between-individual pseudobulk), `L_bulk` (bulk-assay). |
+| `partition.py` | Exact method-of-moments (nested ANOVA cross-product) covariance partition: between-individual / between-compartment-within-individual / within components, with sample-level bootstrap CIs. |
+| `platform_contrast.py` (renamed from `platform.py` to avoid the stdlib collision) | Fisher-Z same-compartment cross-platform contrast (the "is it a platform artefact?" test) and the measurement-conditions compatibility report / atlas verdict (frozen classification thresholds: DOMINANT-NEGATIVE r≤−0.2 & p<0.05; DOMINANT-POSITIVE r≥+0.2 & p<0.05; else INDETERMINATE; atlas support = ≥80% DOMINANT-NEGATIVE within a condition class). |
+| `power.py` | Closed-form Fisher-Z planning tools: n for a target coupling, power at n, minimum detectable |r|. |
+
+## Quick start
+
+```python
+import pandas as pd
+from coupling import layer_cell, layer_indiv
+from partition import partition, bootstrap_share_between
+
+# cells: one row per cell with columns sample, compartment, x (hub gene),
+# y (module score), ng (detected-gene count)
+per_group, summary = layer_cell(cells, ["sample", "compartment"])
+r_indiv, p_indiv = layer_indiv(pseudobulk)          # one row per sample
+part = partition(cells, by=("sample", "compartment"))
+lo, hi = bootstrap_share_between(cells, by=("sample", "compartment"))
+```
+
+Self-tests (synthetic two-level data, seed 42; partition identity, power
+closed form, Fisher-Z sign reversal, classification thresholds):
+
+```
+python test_gating_metrics.py
+```
+
+## Registered falsifiable prediction (public test for the field)
+
+Any new **acute-inflammation whole-blood cohort assayed in bulk** (array or
+bulk RNA-seq) should reproduce a **negative reference-stratum hub–module
+coupling**; **scRNA pseudobulk and protein layers are expected non-negative**
+(same compartment). The F1/F2 tables in the companion manuscript are the
+current evidence base; the prediction is falsifiable by any cohort that
+violates the sign-by-condition pattern.
+
+**Public registration**: OSF Preregistration, 2026-08-18 —
+DOI [10.17605/OSF.IO/4TZH9](https://doi.org/10.17605/OSF.IO/4TZH9)
+(associated project https://osf.io/v8w5a).
+
+**External validation status (recorded 2026-08-19, honest)**: the authors'
+own value-blind external hold-out (module G1; four never-used
+acute-inflammation blood cohorts GSE66099/GSE40012/GSE57065/GSE37069)
+did **NOT** confirm the reference-stratum prediction (2/4 direction-negative;
+pooled fixed-effect r=+0.004). The registered text above is kept unchanged as
+the auditable record; by the external data, the reference-stratum claim is
+refuted and the inflamed-stratum negative coupling is supported (manuscript
+TableS36). Independent replication by other groups remains the intended
+falsification channel.
+
+## Installation
+
+```bash
+pip install gating-metrics     # once published on PyPI (pending author action)
+# or from source:
+git clone https://github.com/Shuiruolys-Liu/gating-metrics
+cd gating-metrics && pip install .
+```
+
+## Provenance
+
+Metric definitions are copied verbatim from the frozen F1 decomposition
+dictionary (`manifest.json -> preregistrations.modules.
+F1_variance_decomposition_gating`, registered 2026-08-18). No metric in this
+package was tuned after inspecting the outcome data.
+
+## Citing
+
+If you use this toolkit, please cite the companion manuscript (under
+preparation) and the OSF registration (DOI 10.17605/OSF.IO/4TZH9).

gating_metrics-0.1.0/README.md

@@ -0,0 +1,83 @@
+# gating_metrics — measurement toolkit for state-gated co-expression coupling
+
+Open-source Python toolkit accompanying the ARDS gating-circuit study
+(manifest modules F1/F2/F3, registered 2026-08-18 before execution). It
+formalises the study's core measurement claim — that a state-gated
+hub–module coupling (e.g. KAT2A vs the inflammasome module) is an
+**individual-level, platform-dependent emergent measurement** — into
+reusable, tested routines.
+
+## What it provides
+
+| Module | Contents |
+|---|---|
+| `coupling.py` | Layer-wise Spearman coupling: `L_cell` (within-sample per-cell, with detected-gene-count partial sensitivity), `L_indiv` (between-individual pseudobulk), `L_bulk` (bulk-assay). |
+| `partition.py` | Exact method-of-moments (nested ANOVA cross-product) covariance partition: between-individual / between-compartment-within-individual / within components, with sample-level bootstrap CIs. |
+| `platform_contrast.py` (renamed from `platform.py` to avoid the stdlib collision) | Fisher-Z same-compartment cross-platform contrast (the "is it a platform artefact?" test) and the measurement-conditions compatibility report / atlas verdict (frozen classification thresholds: DOMINANT-NEGATIVE r≤−0.2 & p<0.05; DOMINANT-POSITIVE r≥+0.2 & p<0.05; else INDETERMINATE; atlas support = ≥80% DOMINANT-NEGATIVE within a condition class). |
+| `power.py` | Closed-form Fisher-Z planning tools: n for a target coupling, power at n, minimum detectable |r|. |
+
+## Quick start
+
+```python
+import pandas as pd
+from coupling import layer_cell, layer_indiv
+from partition import partition, bootstrap_share_between
+
+# cells: one row per cell with columns sample, compartment, x (hub gene),
+# y (module score), ng (detected-gene count)
+per_group, summary = layer_cell(cells, ["sample", "compartment"])
+r_indiv, p_indiv = layer_indiv(pseudobulk)          # one row per sample
+part = partition(cells, by=("sample", "compartment"))
+lo, hi = bootstrap_share_between(cells, by=("sample", "compartment"))
+```
+
+Self-tests (synthetic two-level data, seed 42; partition identity, power
+closed form, Fisher-Z sign reversal, classification thresholds):
+
+```
+python test_gating_metrics.py
+```
+
+## Registered falsifiable prediction (public test for the field)
+
+Any new **acute-inflammation whole-blood cohort assayed in bulk** (array or
+bulk RNA-seq) should reproduce a **negative reference-stratum hub–module
+coupling**; **scRNA pseudobulk and protein layers are expected non-negative**
+(same compartment). The F1/F2 tables in the companion manuscript are the
+current evidence base; the prediction is falsifiable by any cohort that
+violates the sign-by-condition pattern.
+
+**Public registration**: OSF Preregistration, 2026-08-18 —
+DOI [10.17605/OSF.IO/4TZH9](https://doi.org/10.17605/OSF.IO/4TZH9)
+(associated project https://osf.io/v8w5a).
+
+**External validation status (recorded 2026-08-19, honest)**: the authors'
+own value-blind external hold-out (module G1; four never-used
+acute-inflammation blood cohorts GSE66099/GSE40012/GSE57065/GSE37069)
+did **NOT** confirm the reference-stratum prediction (2/4 direction-negative;
+pooled fixed-effect r=+0.004). The registered text above is kept unchanged as
+the auditable record; by the external data, the reference-stratum claim is
+refuted and the inflamed-stratum negative coupling is supported (manuscript
+TableS36). Independent replication by other groups remains the intended
+falsification channel.
+
+## Installation
+
+```bash
+pip install gating-metrics     # once published on PyPI (pending author action)
+# or from source:
+git clone https://github.com/Shuiruolys-Liu/gating-metrics
+cd gating-metrics && pip install .
+```
+
+## Provenance
+
+Metric definitions are copied verbatim from the frozen F1 decomposition
+dictionary (`manifest.json -> preregistrations.modules.
+F1_variance_decomposition_gating`, registered 2026-08-18). No metric in this
+package was tuned after inspecting the outcome data.
+
+## Citing
+
+If you use this toolkit, please cite the companion manuscript (under
+preparation) and the OSF registration (DOI 10.17605/OSF.IO/4TZH9).

gating_metrics-0.1.0/gating_metrics/__init__.py

@@ -0,0 +1 @@
+"""gating_metrics — see README.md; modules: coupling, partition, platform_contrast, power."""

gating_metrics-0.1.0/gating_metrics/coupling.py

@@ -0,0 +1,84 @@
+"""gating_metrics.coupling — layer-wise coupling metrics for state-gated
+co-expression structures (channel-B methodology of the ARDS gating study).
+
+Definitions are copied verbatim from the frozen F1 decomposition dictionary
+(manifest F1_variance_decomposition_gating, registered 2026-08-18):
+  coupling metric = Spearman correlation between the hub gene (e.g. KAT2A)
+  and the module (e.g. mean of the inflammasome genes), evaluated at three
+  layers:
+    L_cell  — within-sample, within-compartment, per-cell correlation, plus a
+              detected-gene-count partial sensitivity (library-complexity
+              background);
+    L_indiv — between-individual pseudobulk correlation across samples;
+    L_bulk  — bulk-assay correlation across samples.
+"""
+import numpy as np
+from scipy import stats
+
+
+def spearman_np(a, b, min_n=4):
+    """Spearman r and p over the jointly-finite values of a and b."""
+    a, b = np.asarray(a, float), np.asarray(b, float)
+    m = np.isfinite(a) & np.isfinite(b)
+    if m.sum() < min_n or np.std(a[m]) == 0 or np.std(b[m]) == 0:
+        return np.nan, np.nan
+    return stats.spearmanr(a[m], b[m])
+
+
+def partial_spearman(a, b, c, min_n=8):
+    """Rank-partial Spearman of a vs b controlling c (residualised ranks)."""
+    a, b, c = np.asarray(a, float), np.asarray(b, float), np.asarray(c, float)
+    m = np.isfinite(a) & np.isfinite(b) & np.isfinite(c)
+    if m.sum() < min_n:
+        return np.nan, np.nan
+    ra, rb, rc = (stats.rankdata(v[m]) for v in (a, b, c))
+
+    def resid(y):
+        X = np.column_stack([np.ones_like(rc), rc])
+        beta, *_ = np.linalg.lstsq(X, y, rcond=None)
+        return y - X @ beta
+
+    ea, eb = resid(ra), resid(rb)
+    if np.std(ea) == 0 or np.std(eb) == 0:
+        return np.nan, np.nan
+    return stats.pearsonr(ea, eb)
+
+
+def layer_cell(df, group_cols, x="x", y="y", background="ng", min_cells=30):
+    """L_cell: per-group within-sample Spearman (x vs y) and its partial
+    (controlling `background`, e.g. per-cell detected-gene count).
+
+    df: long dataframe with one row per CELL plus the group columns
+    (e.g. ['sample','compartment']); returns per-group r/p plus the
+    median-across-groups summary.
+    """
+    rows = []
+    for key, g in df.groupby(group_cols):
+        if len(g) < min_cells:
+            continue
+        r, p = spearman_np(g[x].values, g[y].values)
+        rp, pp = partial_spearman(g[x].values, g[y].values, g[background].values) \
+            if background in g else (np.nan, np.nan)
+        rows.append(dict(zip(group_cols, key if isinstance(key, tuple) else (key,)),
+                         n_cells=len(g), r=r, p=p, r_partial=r, p_partial=pp))
+    per = pd.DataFrame(rows) if rows else None
+    import pandas as pd
+    per = pd.DataFrame(rows)
+    if len(per):
+        summary = dict(median_r=float(np.nanmedian(per.r)),
+                       median_r_partial=float(np.nanmedian(per.r_partial)),
+                       n_groups=int(len(per)))
+    else:
+        summary = dict(median_r=np.nan, median_r_partial=np.nan, n_groups=0)
+    return per, summary
+
+
+def layer_indiv(pb, x="x", y="y", stratum=None, min_n=8):
+    """L_indiv: between-individual Spearman across sample-level pseudobulk
+    values (pb: one row per sample[ x stratum])."""
+    if stratum:
+        out = {}
+        for s, g in pb.dropna(subset=[x, y]).groupby(stratum):
+            out[s] = spearman_np(g[x].values, g[y].values) if len(g) >= min_n else (np.nan, np.nan)
+        return out
+    return spearman_np(pb[x].values, pb[y].values)

gating_metrics-0.1.0/gating_metrics/partition.py

@@ -0,0 +1,85 @@
+"""gating_metrics.partition — exact method-of-moments (nested ANOVA
+cross-product) decomposition of a two-variable covariance across hierarchy
+levels (frozen F1 dictionary): between-individual (between-sample),
+between-compartment-within-sample, and within-sample residual components.
+
+The partition is exact algebra:
+  SSP_tot        = sum_ij (x_ij - xbar)(y_ij - ybar)
+  SSP_between    = sum_s n_s (xbar_s - xbar)(ybar_s - ybar)
+  SSP_comp       = sum_{s,c} n_sc (xbar_sc - xbar_s)(ybar_sc - ybar_s)
+  SSP_within     = SSP_tot - SSP_between - SSP_comp
+with bootstrap CIs obtained by resampling INDIVIDUALS (samples), the
+independent units of the hierarchy.
+"""
+import numpy as np
+import pandas as pd
+
+
+def group_stats(df, x="x", y="y", by=("sample", "comp")):
+    d = df.copy()
+    d["xy"] = d[x] * d[y]
+    return d.groupby(list(by)).agg(n=(x, "size"), sx=(x, "sum"), sy=(y, "sum"),
+                                   sxy=("xy", "sum")).reset_index()
+
+
+def partition_from_gs(gs):
+    """Partition from per-group sufficient statistics (n, sx, sy, sxy)."""
+    N = gs.n.sum()
+    xbar, ybar = gs.sx.sum() / N, gs.sy.sum() / N
+    SSP_tot = gs.sxy.sum() - N * xbar * ybar
+    gs = gs.copy()
+    gs["mx"], gs["my"] = gs.sx / gs.n, gs.sy / gs.n
+    ss_rows = []
+    for s, g in gs.groupby("sample" if "sample" in gs.columns else gs.columns[0]):
+        ss_rows.append({"sample": s, "n": g.n.sum(),
+                        "mxs": np.average(g.mx, weights=g.n),
+                        "mys": np.average(g.my, weights=g.n)})
+    ss = pd.DataFrame(ss_rows)
+    gcol = "sample" if "sample" in gs.columns else gs.columns[0]
+    SSP_B = float((ss.n * (ss.mxs - xbar) * (ss.mys - ybar)).sum())
+    merged = gs.merge(ss[[gcol, "mxs", "mys"]], on=gcol)
+    if len(gs.columns) > 4:  # compartment level present
+        SSP_C = float((merged.n * (merged.mx - merged.mxs) *
+                       (merged.my - merged.mys)).sum())
+    else:
+        SSP_C = 0.0
+    SSP_W = SSP_tot - SSP_B - SSP_C
+    tot = SSP_tot if SSP_tot != 0 else np.nan
+    return dict(n_cells=int(N), n_groups=len(gs), SSP_tot=SSP_tot,
+                SSP_between_individual=SSP_B,
+                SSP_between_compartment_within=SSP_C, SSP_within=SSP_W,
+                share_between_individual=SSP_B / tot if tot == tot else np.nan,
+                share_between_compartment=SSP_C / tot if tot == tot else np.nan,
+                share_within=SSP_W / tot if tot == tot else np.nan)
+
+
+def partition(df, x="x", y="y", by=("sample", "comp")):
+    """Convenience wrapper: partition + algebraic identity assert."""
+    gs = group_stats(df, x, y, by)
+    out = partition_from_gs(gs)
+    if by == ("sample",):
+        assert abs(out["SSP_tot"] - out["SSP_between_individual"]
+                   - out["SSP_within"]) < 1e-6 * max(1, abs(out["SSP_tot"]))
+    else:
+        assert abs(out["SSP_tot"] - out["SSP_between_individual"]
+                   - out["SSP_between_compartment_within"]
+                   - out["SSP_within"]) < 1e-6 * max(1, abs(out["SSP_tot"]))
+    return out
+
+
+def bootstrap_share_between(df, x="x", y="y", by=("sample", "comp"),
+                            n_boot=1000, seed=42):
+    """Bootstrap CI of share_between_individual by resampling samples."""
+    rng = np.random.default_rng(seed)
+    gs = group_stats(df, x, y, by)
+    samples = gs["sample"].unique()
+    shares = []
+    for _ in range(n_boot):
+        draw = rng.choice(samples, len(samples), replace=True)
+        rep = pd.DataFrame({"sample": draw}).groupby("sample").size().rename("mult").reset_index()
+        g2 = gs.merge(rep, on="sample")
+        for c in ["n", "sx", "sy", "sxy"]:
+            g2[c] = g2[c] * g2.mult
+        shares.append(partition_from_gs(g2)["share_between_individual"])
+    lo, hi = np.nanpercentile(shares, [2.5, 97.5])
+    return float(lo), float(hi)

gating_metrics-0.1.0/gating_metrics/platform_contrast.py

@@ -0,0 +1,52 @@
+"""gating_metrics.platform_contrast — same-compartment cross-platform coupling
+contrast (the H3 natural-experiment test) and a measurement-condition
+compatibility report builder (frozen F1/F2 dictionary).
+"""
+import numpy as np
+from scipy import stats
+import pandas as pd
+
+
+def fisher_z_contrast(r1, n1, r2, n2):
+    """Fisher-Z test of two independent correlations (e.g. bulk-array vs
+    scRNA-pseudobulk coupling measured in the same biological compartment)."""
+    z = (np.arctanh(r1) - np.arctanh(r2)) / np.sqrt(1 / (n1 - 3) + 1 / (n2 - 3))
+    p = 2 * (1 - stats.norm.cdf(abs(z)))
+    return dict(fisher_z=float(z), p=float(p), sign_reversal=bool(r1 * r2 < 0))
+
+
+def compatibility_report(rows):
+    """Build the measurement-conditions range table (F2).
+
+    rows: list of dicts with keys dataset, platform, compartment, state_class,
+          stratum, r, p, n. Classification rule (frozen): DOMINANT-NEGATIVE
+          r<=-0.2 & p<0.05; DOMINANT-POSITIVE r>=+0.2 & p<0.05; else
+          INDETERMINATE.
+    """
+    df = pd.DataFrame(rows)
+    if len(df) == 0:
+        return df
+
+    def classify(r, p):
+        if not np.isfinite(r) or not np.isfinite(p):
+            return "NON-EVALUABLE"
+        if r <= -0.2 and p < 0.05:
+            return "DOMINANT-NEGATIVE"
+        if r >= 0.2 and p < 0.05:
+            return "DOMINANT-POSITIVE"
+        return "INDETERMINATE"
+    df["classification"] = [classify(r, p) for r, p in zip(df.r, df.p)]
+    return df
+
+
+def atlas_verdict(report, condition_filter):
+    """Frozen F2 atlas-level verdict: the individual-level axis principle is
+    supported at atlas level iff DOMINANT-NEGATIVE holds in >=80% of evaluable
+    cohorts of the given condition class (e.g. acute-inflammation blood)."""
+    sub = report[report.state_class.isin(condition_filter)]
+    sub = sub[sub.classification != "NON-EVALUABLE"]
+    if len(sub) == 0:
+        return dict(k=0, n=0, fraction=np.nan, supported=False)
+    k = int((sub.classification == "DOMINANT-NEGATIVE").sum())
+    frac = k / len(sub)
+    return dict(k=k, n=int(len(sub)), fraction=frac, supported=bool(frac >= 0.8))

gating_metrics-0.1.0/gating_metrics/power.py

@@ -0,0 +1,29 @@
+"""gating_metrics.power — closed-form power/sample-size for detecting a
+reference-stratum Spearman coupling (the gating-metric planning tool).
+"""
+import numpy as np
+from scipy import stats
+
+
+def n_for_coupling(r_target, alpha=0.05, power=0.8, two_sided=True):
+    """Minimum n to detect a true Spearman r at Fisher-Z (normal approx)."""
+    z_a = stats.norm.ppf(1 - alpha / 2 if two_sided else 1 - alpha)
+    z_b = stats.norm.ppf(power)
+    zr = np.arctanh(r_target)
+    return int(np.ceil((z_a + z_b) ** 2 / zr ** 2 + 3))
+
+
+def power_at_n(r_true, n, alpha=0.05, two_sided=True):
+    """Power of the Fisher-Z test for a true correlation r at sample size n."""
+    z_a = stats.norm.ppf(1 - alpha / 2 if two_sided else 1 - alpha)
+    se = 1 / np.sqrt(n - 3)
+    zr = np.arctanh(r_true)
+    return float(stats.norm.cdf(abs(zr) / se - z_a))
+
+
+def mde_at_n(n, alpha=0.05, power=0.8, two_sided=True):
+    """Minimum detectable |r| at given n."""
+    z_a = stats.norm.ppf(1 - alpha / 2 if two_sided else 1 - alpha)
+    z_b = stats.norm.ppf(power)
+    r = np.tanh((z_a + z_b) / np.sqrt(n - 3))
+    return float(r)

gating_metrics-0.1.0/gating_metrics/test_gating_metrics.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+"""gating_metrics self-tests (frozen F3 deliverable): run with
+    python test_gating_metrics.py
+Asserts (i) the method-of-moments partition equals the direct algebraic
+identity on a synthetic two-level dataset (seed 42), (ii) the closed-form
+power calculator reproduces the standard Fisher-Z n formula, (iii) the
+platform Fisher-Z contrast recovers a known sign reversal, and (iv) the
+compatibility-report classifier matches the frozen thresholds.
+"""
+import os, sys
+import numpy as np
+import pandas as pd
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from partition import partition, bootstrap_share_between
+from power import n_for_coupling, power_at_n, mde_at_n
+from platform_contrast import fisher_z_contrast, compatibility_report, atlas_verdict
+from coupling import spearman_np, partial_spearman
+
+
+def make_two_level(seed=42, n_samples=60, cells_per=40, r_between=-0.6,
+                   r_within=0.0):
+    rng = np.random.default_rng(seed)
+    mus = rng.multivariate_normal([0, 0], [[1, r_between], [r_between, 1]],
+                                  size=n_samples)
+    rows = []
+    for s, (mx, my) in enumerate(mus):
+        xy = rng.multivariate_normal([mx, my], [[1, r_within], [r_within, 1]],
+                                     size=cells_per)
+        for x, y in xy:
+            rows.append({"sample": f"S{s}", "x": x, "y": y})
+    return pd.DataFrame(rows)
+
+
+def main():
+    # (i) partition identity + between-individual share recovery
+    df = make_two_level()
+    p = partition(df[["sample", "x", "y"]], by=("sample",))
+    assert abs(p["SSP_tot"] - p["SSP_between_individual"] - p["SSP_within"]) \
+        < 1e-6 * max(1.0, abs(p["SSP_tot"]))
+    lo, hi = bootstrap_share_between(df[["sample", "x", "y"]], by=("sample",),
+                                     n_boot=200)
+    assert lo < p["share_between_individual"] < hi, (lo, p, hi)
+    print(f"partition OK: share_between={p['share_between_individual']:.3f} "
+          f"bootstrap95=[{lo:.3f},{hi:.3f}]")
+
+    # (ii) power calculators
+    n_req = n_for_coupling(0.3)
+    assert power_at_n(0.3, n_req) >= 0.8 - 1e-6
+    assert abs(mde_at_n(n_req) - 0.3) < 0.02
+    print(f"power OK: n(r=0.3, 80%)={n_req}, MDE at that n={mde_at_n(n_req):.3f}")
+
+    # (iii) Fisher-Z platform contrast with known sign reversal
+    c = fisher_z_contrast(-0.5, 40, +0.4, 200)
+    assert c["sign_reversal"] and c["p"] < 0.05
+    print(f"fisher-z OK: p={c['p']:.2e}, sign_reversal={c['sign_reversal']}")
+
+    # (iv) classification thresholds + atlas verdict
+    rows = [
+        dict(dataset="A", platform="array", compartment="whole_blood",
+             state_class="acute_blood", stratum="ref", r=-0.4, p=0.01, n=50),
+        dict(dataset="B", platform="array", compartment="whole_blood",
+             state_class="acute_blood", stratum="ref", r=-0.3, p=0.02, n=80),
+        dict(dataset="C", platform="scRNA", compartment="PBMC",
+             state_class="acute_blood", stratum="ref", r=+0.3, p=0.03, n=100),
+        dict(dataset="D", platform="array", compartment="whole_blood",
+             state_class="acute_blood", stratum="ref", r=-0.1, p=0.4, n=30),
+    ]
+    rep = compatibility_report(rows)
+    v = atlas_verdict(rep, ["acute_blood"])
+    assert v["k"] == 2 and v["n"] == 4 and not v["supported"]
+    print("classification OK:", dict(zip(rep.dataset, rep.classification)))
+    print("ALL gating_metrics SELF-TESTS PASSED")
+
+
+if __name__ == "__main__":
+    main()

gating_metrics-0.1.0/gating_metrics.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: gating-metrics
+Version: 0.1.0
+Summary: Measurement toolkit for state-gated co-expression coupling: layer couplings, exact covariance partition, platform contrast, closed-form power planning
+Author: Liu Yuanshui
+License: MIT
+Project-URL: OSF registration, https://doi.org/10.17605/OSF.IO/4TZH9
+Project-URL: OSF project, https://osf.io/v8w5a
+Project-URL: Homepage, https://github.com/Shuiruolys-Liu/gating-metrics
+Keywords: co-expression,single-cell,gating,ARDS,inflammasome,measurement
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Dynamic: license-file
+
+# gating_metrics — measurement toolkit for state-gated co-expression coupling
+
+Open-source Python toolkit accompanying the ARDS gating-circuit study
+(manifest modules F1/F2/F3, registered 2026-08-18 before execution). It
+formalises the study's core measurement claim — that a state-gated
+hub–module coupling (e.g. KAT2A vs the inflammasome module) is an
+**individual-level, platform-dependent emergent measurement** — into
+reusable, tested routines.
+
+## What it provides
+
+| Module | Contents |
+|---|---|
+| `coupling.py` | Layer-wise Spearman coupling: `L_cell` (within-sample per-cell, with detected-gene-count partial sensitivity), `L_indiv` (between-individual pseudobulk), `L_bulk` (bulk-assay). |
+| `partition.py` | Exact method-of-moments (nested ANOVA cross-product) covariance partition: between-individual / between-compartment-within-individual / within components, with sample-level bootstrap CIs. |
+| `platform_contrast.py` (renamed from `platform.py` to avoid the stdlib collision) | Fisher-Z same-compartment cross-platform contrast (the "is it a platform artefact?" test) and the measurement-conditions compatibility report / atlas verdict (frozen classification thresholds: DOMINANT-NEGATIVE r≤−0.2 & p<0.05; DOMINANT-POSITIVE r≥+0.2 & p<0.05; else INDETERMINATE; atlas support = ≥80% DOMINANT-NEGATIVE within a condition class). |
+| `power.py` | Closed-form Fisher-Z planning tools: n for a target coupling, power at n, minimum detectable |r|. |
+
+## Quick start
+
+```python
+import pandas as pd
+from coupling import layer_cell, layer_indiv
+from partition import partition, bootstrap_share_between
+
+# cells: one row per cell with columns sample, compartment, x (hub gene),
+# y (module score), ng (detected-gene count)
+per_group, summary = layer_cell(cells, ["sample", "compartment"])
+r_indiv, p_indiv = layer_indiv(pseudobulk)          # one row per sample
+part = partition(cells, by=("sample", "compartment"))
+lo, hi = bootstrap_share_between(cells, by=("sample", "compartment"))
+```
+
+Self-tests (synthetic two-level data, seed 42; partition identity, power
+closed form, Fisher-Z sign reversal, classification thresholds):
+
+```
+python test_gating_metrics.py
+```
+
+## Registered falsifiable prediction (public test for the field)
+
+Any new **acute-inflammation whole-blood cohort assayed in bulk** (array or
+bulk RNA-seq) should reproduce a **negative reference-stratum hub–module
+coupling**; **scRNA pseudobulk and protein layers are expected non-negative**
+(same compartment). The F1/F2 tables in the companion manuscript are the
+current evidence base; the prediction is falsifiable by any cohort that
+violates the sign-by-condition pattern.
+
+**Public registration**: OSF Preregistration, 2026-08-18 —
+DOI [10.17605/OSF.IO/4TZH9](https://doi.org/10.17605/OSF.IO/4TZH9)
+(associated project https://osf.io/v8w5a).
+
+**External validation status (recorded 2026-08-19, honest)**: the authors'
+own value-blind external hold-out (module G1; four never-used
+acute-inflammation blood cohorts GSE66099/GSE40012/GSE57065/GSE37069)
+did **NOT** confirm the reference-stratum prediction (2/4 direction-negative;
+pooled fixed-effect r=+0.004). The registered text above is kept unchanged as
+the auditable record; by the external data, the reference-stratum claim is
+refuted and the inflamed-stratum negative coupling is supported (manuscript
+TableS36). Independent replication by other groups remains the intended
+falsification channel.
+
+## Installation
+
+```bash
+pip install gating-metrics     # once published on PyPI (pending author action)
+# or from source:
+git clone https://github.com/Shuiruolys-Liu/gating-metrics
+cd gating-metrics && pip install .
+```
+
+## Provenance
+
+Metric definitions are copied verbatim from the frozen F1 decomposition
+dictionary (`manifest.json -> preregistrations.modules.
+F1_variance_decomposition_gating`, registered 2026-08-18). No metric in this
+package was tuned after inspecting the outcome data.
+
+## Citing
+
+If you use this toolkit, please cite the companion manuscript (under
+preparation) and the OSF registration (DOI 10.17605/OSF.IO/4TZH9).

gating_metrics-0.1.0/gating_metrics.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+gating_metrics/__init__.py
+gating_metrics/coupling.py
+gating_metrics/partition.py
+gating_metrics/platform_contrast.py
+gating_metrics/power.py
+gating_metrics/test_gating_metrics.py
+gating_metrics.egg-info/PKG-INFO
+gating_metrics.egg-info/SOURCES.txt
+gating_metrics.egg-info/dependency_links.txt
+gating_metrics.egg-info/requires.txt
+gating_metrics.egg-info/top_level.txt

gating_metrics-0.1.0/gating_metrics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gating_metrics-0.1.0/gating_metrics.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=1.24
+pandas>=2.0
+scipy>=1.10

gating_metrics-0.1.0/gating_metrics.egg-info/top_level.txt

@@ -0,0 +1 @@
+gating_metrics

gating_metrics-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gating-metrics"
+version = "0.1.0"
+description = "Measurement toolkit for state-gated co-expression coupling: layer couplings, exact covariance partition, platform contrast, closed-form power planning"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Liu Yuanshui" }]
+keywords = ["co-expression", "single-cell", "gating", "ARDS", "inflammasome", "measurement"]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = ["numpy>=1.24", "pandas>=2.0", "scipy>=1.10"]
+
+[project.urls]
+"OSF registration" = "https://doi.org/10.17605/OSF.IO/4TZH9"
+"OSF project" = "https://osf.io/v8w5a"
+Homepage = "https://github.com/Shuiruolys-Liu/gating-metrics"
+
+[tool.setuptools]
+packages = ["gating_metrics"]

gating_metrics-0.1.0/setup.cfg

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