ebin 1.0__tar.gz

ebin-1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ebin
+Version: 1.0
+Summary: Posterior bin-expectation normalization for sorting-based MPRA
+Requires-Python: >=3.9
+Requires-Dist: jax>=0.4
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Provides-Extra: netcdf
+Requires-Dist: xarray; extra == "netcdf"
+Requires-Dist: h5netcdf; extra == "netcdf"

ebin-1.0/README.md

@@ -0,0 +1,316 @@
+# EBin: Normalization of MPRA data (FACS bins × replicates × sequences)
+
+Raw per-bin read counts are turned into one number per sequence per cell line —
+the **posterior-mean expected bin**, `E[bin]` — together with the posterior SD
+that states how far it can be trusted. The counts enter a compound NB–Poisson
+likelihood; what is estimated is the sequence's latent expression distribution.
+
+
+
+<img src="http://data.georgy.top/media/ebin_model_layers.png" alt="EBin model"/>
+
+
+```MPRA 
+X[n,s,b] | T[n,s,b] ~ NB(R[s,b] · T[n,s,b], P[s,b])       reads from cells
+T[n,s,b]            ~ Poisson(a_n · Pi[n,b] · lambda_s)   cells in bin b
+Pi[n,b]             = Phi((q_b − mu_n)/sigma_n) − Phi((q_{b−1} − mu_n)/sigma_n)
+```
+Each sequence `n` carries a latent Gaussian effect law `N(mu_n, sigma_n²)` — its
+expression distribution over cells — and an abundance `a_n`. The library's
+marginal effect law is the **`N`-component mixture** of those per-sequence
+normals, `G(x) = Σ_n w_n Phi((x − mu_n)/sigma_n)` with `w_n = 1/N`, and the `B`
+sorting bins are its quantile cells: the cut points `q_1 < … < q_{B−1}` solve
+`G(q_j) = j/B`. They are shared, and re-solved at every step, so every sequence
+is tied to the marginal through them. This approach has 2 benefits: first one is that
+it allows us to cut the number of params down to 2 instead of `B-1`, and the second one is that those params are further regularized, both by the normality assumption and the fact that they are all should form the global marginal distribution. 
+
+The activity that ships is the posterior **mean** of `E[bin] = Σ_b b·Pi[n,b]`,
+integrated over the posterior of `(mu_n, sigma_n)` with the abundance profiled
+per grid point. The plug-in point estimate is a posterior *mode*, and for a
+low-count sequence the mode sits at a simplex vertex — activity exactly 1 or
+`B`, regardless of depth.
+
+## Install
+```
+pip install ebin
+```
+or
+
+```bash
+pip install -e /path/to/package        # or place this directory on PYTHONPATH
+```
+
+`jax` (GPU-version strongly recommended: `pip install jax[cuda]`), `numpy`, `scipy` and `pandas` are required.
+`xarray` + `h5netcdf` are needed only for the netCDF export and `matplotlib`
+only for the diagnostics. Everything runs in float64 as some parts of the algorithm require high precision, namely the tridiagonal eigenvalue solver for orthogonal polynomials.
+
+## Input
+
+One row per sequence, a 3-level column header `(cell line, replicate, bin)`:
+
+```
+seq,       A549,A549,A549,A549,A549,...
+           rep1,rep1,rep1,rep1,rep2,...
+           bin1,bin2,bin3,bin4,bin1,...
+ACGT...,   112, 340, 88,  15,  97,  ...
+```
+(in other words, the tabular should be readable with `pd.read_csv(..., header=[0,1,2])`)
+
+
+Bins are ordered by the number in their name. Cell lines are fitted
+independently. **Empty fields are read as zero counts, not as missing data** —
+some exports write every zero as a blank, and treating those as missin
+
+## Install
+
+```bash
+pip install -e /path/to/package        # or place this directory on PYTHONPATH
+```
+
+`jax` (GPU strongly recommended), `numpy`, `scipy` and `pandas` are required.
+`xarray` + `h5netcdf` are needed only for the netCDF export and `matplotlib`
+only for the diagnostics. Everything runs in float64.
+
+## Input
+
+One row per sequence, a 3-level column header `(cell line, replicate, bin)`:
+
+```
+seq,       A549,A549,A549,A549,A549,...
+           rep1,rep1,rep1,rep1,rep2,...
+           bin1,bin2,bin3,bin4,bin1,...
+ACGT...,   112, 340, 88,  15,  97,  ...
+```
+
+Bins are ordered by the number in their name. Cell lines are fitted
+independently. **Empty fields are read as zero counts, not as missing data** —
+some exports write every zero as a blank, and treating those as missing deletes 
+the informative zeros of the low-abundance sequences.
+
+## Use
+
+```bash
+python -m ebin counts.csv -o activity.csv
+```
+
+```python
+from ebin import activity_table
+
+table, results = activity_table("counts.csv", out="activity.csv")
+table[("A549", "activity")]        # posterior-mean E[bin] per sequence
+```
+
+The CSV has two header rows, `(cell line, field)`, one row per sequence, and
+carries everything the model estimates per sequence:
+
+| field | meaning |
+| --- | --- |
+| `activity` | posterior-mean `E[bin]` — the normalized value intended for downstream use |
+| `activity_sd` | its posterior SD — per-sequence confidence |
+| `activity_map` | plug-in mode, kept for reference only |
+| `mu`, `mu_sd` | posterior-mean effect location and its standard error |
+| `sigma`, `sigma_sd` | posterior-mean effect scale and its standard error |
+| `abundance` | fitted size factor `a_n` |
+| `n_eff` | posterior grid support — large means the estimate is diffuse |
+| `tot` | total observed reads |
+
+All of it comes from the same posterior weights, so the columns are mutually
+consistent: `activity` is `Σ_b b·bin_prob`. `mu` and `sigma` are in gauge units
+(median cut 0, first cut −1), so they are comparable across sequences within a
+cell line. A subset is selected with `--fields activity,activity_sd,tot` (or
+`fields=[...]` in the API).
+
+The `B−1` cut points are a property of the cell line, not of a sequence, so
+they are not columns: `cuts_table(results)` returns them as one row per cell
+line, and the CLI writes them next to the activity table as
+`<out>_cuts.csv`. The gauge fixes the first two at −1 and 0, so what varies
+between lines is where the upper cuts land (A549 0.990, MDA-MB-231 0.964).
+
+Sequences with no reads at all in a cell line keep an activity (they are fitted
+as structural zeros and land near the neutral prior mean, ~2.5 for `B = 4`);
+sequences with no observed cell at all are `NaN`.
+
+Useful CLI options:
+
+```
+--groups A549,HepG2        cell lines to run, in output order
+--abundance gamma          integrate a_n out instead of fitting it
+--zero-truncation          drop all-zero rows instead of fitting them
+--grid 61x25               readout grid (n_mu x n_log_sigma)
+--save-fits fits.pkl       keep the fitted parameters
+--warm-from fits.pkl       start from an earlier fit of the same data
+--netcdf activity.nc       also write the full posterior (see below)
+--plots DIR                also write the diagnostic plots
+```
+
+### Per-bin distribution
+
+The one field too wide for a flat table is `bin_prob`, the posterior-mean
+probability of each bin — an `(N, B)` array per cell line. It is returned in
+`results`, and `--netcdf` writes it alongside every scalar field:
+
+```python
+from ebin import activity_table, write_netcdf
+
+table, results = activity_table("counts.csv")
+results["A549"]["bin_prob"]                    # (N, B), rows sum to 1
+write_netcdf("activity.nc", results, table.index)
+```
+
+Readouts can be redone from saved fits without refitting, which is the cheap
+way to try a different grid or prior:
+
+```python
+from ebin import readout_table
+table, results = readout_table("counts.csv", "fits.pkl")
+```
+
+## Diagnostics
+
+Three plots, one panel per cell line, drawn from the table alone (`--plots DIR`
+on the CLI writes all three):
+
+```python
+from ebin import (plot_marginal_distribution, plot_activity_vs_raw,
+                  plot_gc_vs_abundance)
+
+plot_marginal_distribution(table, out="marginal.png")
+plot_activity_vs_raw(table, "counts.csv", out="vs_raw.png")
+plot_gc_vs_abundance(table, out="gc.png")
+```
+
+**`plot_marginal_distribution`** — the marginal effect law: the `N`-component
+mixture `G(x) = Σ_n w_n Phi((x − mu_n)/sigma_n)`, one normal per sequence,
+drawn as the density it defines and sliced into the sorting bins, each in its
+own colour. The x ticks are the cut points with their values. Weights are
+uniform by default, as in the fit; `weights=` takes a per-sequence weight (the
+fitted abundances, say) to see the marginal over cells rather than over
+sequences. Every slice holds exactly `1/B` of the mass by construction, so the
+gauge (cuts at −1 and 0) and any unusual tightness or skew in a cell line's
+effect law are visible here.
+
+**`plot_activity_vs_raw`** — fitted activity against the depth-normalized raw
+mass centre (each replicate×bin column divided by its own library size, then
+`Σ_b b·p_b`), coloured by fitted abundance. Well-measured sequences sit on the
+diagonal; the horizontal band at the centre is the low-abundance tail, where the
+raw estimate is noise and the model shrinks toward neutral. A cell line whose
+*high*-abundance sequences leave the diagonal is a real warning sign.
+
+**`plot_gc_vs_abundance`** — GC content against the fitted size factor, with the
+binned median trend. A strong trend means `a_n` is absorbing a
+cloning/sequencing bias rather than biological abundance alone. GC is taken from
+the table index when the index is the sequence; otherwise it is supplied through
+`sequences=`.
+
+`raw_mass_center(counts)` and `gc_content(seqs)` are exported separately for
+cases where the raw numbers are more appropriate than a picture.
+
+## Configuration
+
+Defaults are the shipped configuration; they are not arbitrary and are worth
+understanding before they are changed.
+
+| option | default | why |
+| --- | --- | --- |
+| `conditional` | `False` | Zero **inflation**: all-zero rows are fitted with a structural-zero probability `phi`, so they enter the mixture that sets the cuts. Zero **truncation** (`True`) drops them, which sets the cuts on a zero-excluded distribution — measurably worse, both in-library and on transfer to an independent library. |
+| `abundance` | `True` | A free size factor `a_n` per sequence. Without one, every sequence has the same expected latent total, so real depth variation has nowhere to go but `Pi` — which tilts toward the bins with the largest channel scale, and `Pi` stops being a profile. |
+| `abundance_prior` | `None` | `'gamma'` integrates `a_n` out under `Gamma(kappa, mean=1)` instead: 2 parameters per sequence instead of 3, low-count sequences regularized, and the abundance uncertainty propagated into the effect. The activity profile is essentially unchanged (ρ ≈ 0.9996 against free `a_n`), so this is a parameter-economy. Costs ~2× runtime. |
+| `mu_prior` | `1.3` | SD of the prior on the effect location. Bounding the effect *spread* alone still lets a single-bin low-count sequence run `mu_n` large and walk `Pi` to a vertex. The gauge pins Q50 = 0 and Q25 = −1, so the population SD is ≈ 1.5 and the between-sequence SD ≈ 1.1 — the gauge-consistent `tau` is ~1.3. A larger value (2–3) is inconsistent with the gauge and under-regularizes. |
+| `sigma_prior` | `(0.0, 0.5)` | Prior on `log sigma_n`. The per-sequence MLE is unbounded: a sequence whose reads land only in the outer bins wants a two-point mass, reachable only as `sigma → ∞`. Without this, `sigma` hits its bound in several cell lines; those are bad optima, so the prior often *improves* the data likelihood. `(0, 1)` fits marginally better on well-behaved lines but leaves stuck ones stuck. |
+| `lambda_fix` | `50.0` | The latent Poisson level is not identified upward — it rides the `R·lambda` ridge, and only products like `R(1−P)/P · Pi · lambda` are identified. It is held fixed and `R` absorbs the scale. |
+| `a_max` | `15.0` | Bound on `a_n`; also sizes the truncated latent-count grid, so raising it costs runtime and memory. |
+| readout grid | `121 × 33` | `(mu, log sigma)` grid for the posterior mean. Converged in the bulk: doubling to `181 × 49` moves the median activity by 2e-6 (a handful of extreme low-count sequences move by up to 0.04), while halving to `61 × 25` moves it by 5e-3. |
+
+The readout re-uses the fit's own priors by default, so the posterior mean is
+coherent with the fitted model. A flat effect location is obtained with
+`readout=dict(tau_within=None)`, and `mu_center=<array>` shrinks toward a
+per-sequence target (for instance the same sequence's consensus across cell
+lines).
+
+## Reproducing the shipped tables
+
+The shipped `activity_zi_full.csv` (30k sequences × 20 cell lines) is the
+default configuration:
+
+```bash
+python -m ebin data.csv -o activity.csv --save-fits fits.pkl
+```
+
+Cell lines come out in the order they appear in the count table, and every field
+is written. The shipped table carried only `activity, activity_sd,
+activity_map, tot` in an explicit cell-line order, so
+
+```bash
+python -m ebin data.csv -o activity.csv \
+    --fields activity,activity_sd,activity_map,tot --groups A549,HepG2,MCF7,...
+```
+
+reproduces that exact layout. The extra columns are additional output, not a
+change to the numbers.
+
+Checked against the shipped table three ways:
+
+* **Readout.** Given the shipped fitted parameters, `readout_table` reproduces
+  `activity`, `activity_sd`, `activity_map` and `tot` to `4e-16` — exact up to
+  CSV round-off.
+* **Objective.** The log-likelihood and its gradient agree **bit for bit** with
+  the original implementation at the same parameter point, for zero inflation
+  and zero truncation, free and Gamma abundance — including the gradient
+  through the implicit cut-point solve.
+* **Full refit.** Most cell lines land on the shipped optimum (`max|Δ|` on
+  activity ≤ 1e-6). A few of the hardest lines do not: the objective is
+  multi-modal there, and the optimizer can settle in a neighbouring basin,
+  which moves individual sequences by up to ~1e-1 (Pearson r ≥ 0.9998 against
+  the shipped column). This is a property of the problem, not of the
+  repackaging — the original code has the same instability on the same lines
+  (re-fitting HCT116 with it lands 13 nats from its own shipped value), and
+  both implementations reproduce those lines when fitted on their own.
+
+The external-library (lib2) target used the same fit with a smaller readout
+grid, selected with `--grid 61x25`.
+
+The Gamma-abundance variant was warm-started from the shipped fits, which is
+what makes it affordable, and used a shorter finishing schedule:
+
+```python
+from ebin import activity_table
+activity_table("data.csv", out="activity_gamma.csv", warm_from="fits.pkl",
+               abundance=False, abundance_prior="gamma", n_abund_nodes=30,
+               max_outer=1, finish_maxiter=2000, finish_rounds=4)
+```
+
+The CLI runs the same variant on the default schedule:
+`--abundance gamma --nodes 30 --warm-from fits.pkl`.
+
+## Runtime
+
+One cell line of 30k sequences × 4 bins takes ~2–4 min on a GPU (fit + readout)
+and roughly 20× longer on CPU; the Gamma-abundance variant costs ~2× the
+free-`a_n` fit. Memory is dominated by the latent-count grid
+(`a_max · lambda_fix` wide); the likelihood scans over abundance/rate components
+so only one is live at a time. `XLA_PYTHON_CLIENT_PREALLOCATE=false` is set on
+import so JAX does not claim 75% of VRAM.
+
+
+## Parameters
+
+
+| symbol | shape | role | what it is | example (A549) |
+| --- | --- | --- | --- | --- |
+| `X[n,s,b]` | N×S×B | observed | reads counted for sequence n in channel (s,b) | 1686 median total |
+| `T[n,s,b]` | N×S×B | latent | cells of n that landed in bin b — never observed, summed out | ~63 cells |
+| `mu_n`, `sigma_n` | N each | per sequence | the sequence's expression law over cells, in gauge units | σ median 1.46 |
+| `a_n` | N | per sequence | size factor: how many cells n contributes at all. Geometric mean pinned to 1, capped at `a_max` | 1.42 median |
+| `Pi[n,b]` | N×B | derived | bin profile, rows sum to 1. Not free — read off `(mu_n, sigma_n)` and the cuts | — |
+| `q_j` | B−1 | shared | cut points = quantiles of the mixture `G` at `j/B`. Gauge pins `q_1 = −1`, `q_2 = 0` | −1, 0, 0.99 |
+| `lambda_s` | S | fixed | cell level of replicate s. Not identified — rides the `R·lambda` ridge, so held fixed while `R` absorbs the scale | 50 |
+| `R[s,b]` | S×B | per channel | NB size per latent cell: `R·T` is the shape of the read distribution | 12.7 11.4 11.6 20.1 |
+| `P[s,b]` | S×B | per channel | NB probability. Small `P` = a noisier channel at the same depth | .33 .32 .31 .52 |
+| `phi` | 1 | shared | probability a sequence is a structural zero (dropout, never a cell) | 8e−7 |
+| `kappa` | 1 | optional | Gamma shape when `a_n` is integrated out instead of fitted; CV = 1/√κ | 0.9 (variant) |
+
+so `X, T, R, P` are 3D arrays:
+<center>
+<img src="http://data.georgy.top/media/ebin_index_cube.png" alt="Index cube: n sequences, s replicates, b bins" width="196">
+</center>
+

ebin-1.0/ebin/__init__.py

@@ -0,0 +1,32 @@
+"""EBin -- posterior bin-expectation normalization for sorting-based MPRA.
+
+Reads raw per-bin read counts and returns, for every sequence in every cell
+line, the posterior-mean expected bin E[bin] (the activity) together with its
+posterior SD.  The model is a compound NB-Poisson likelihood over a latent
+Gaussian effect law per sequence; see model.py, effects.py and activity.py.
+
+    from ebin import activity_table
+    table, _ = activity_table("counts.csv", out="activity.csv")
+"""
+
+import os
+
+# jax grabs 75% of VRAM otherwise; float64 throughout (the likelihood sums
+# thousands of log terms per object)
+os.environ.setdefault("XLA_PYTHON_CLIENT_PREALLOCATE", "false")
+
+import jax  # noqa: E402
+
+jax.config.update("jax_enable_x64", True)
+
+from .data import GroupData, read_counts, load_groups, prep  # noqa: E402,F401
+from .initialize import initialize, init_from_fit, InitResult  # noqa: E402,F401
+from .fit import fit_effects, FitResult  # noqa: E402,F401
+from .activity import posterior_activity  # noqa: E402,F401
+from .pipeline import (activity_table, readout_table, save_fits,  # noqa: E402,F401
+                       load_fits, write_netcdf)
+from .plots import (plot_marginal_distribution, plot_activity_vs_raw,  # noqa: E402,F401
+                    plot_gc_vs_abundance, plot_all, raw_mass_center,
+                    gc_content, marginal_density)
+
+__version__ = "1.0"

ebin-1.0/ebin/__main__.py

@@ -0,0 +1,76 @@
+"""Command line: python -m ebin counts.csv -o activity.csv"""
+
+import argparse
+
+from .pipeline import activity_table, write_netcdf, TABLE_FIELDS
+
+
+def _parse_args(argv=None):
+    p = argparse.ArgumentParser(
+        prog="python -m ebin",
+        description="Fit the EBin model to a bin-count table and write the "
+                    "per-cell-line activity table. Defaults are the shipped "
+                    "configuration.")
+    p.add_argument("data", help="count table, 3-level header "
+                                "(cell line, replicate, bin)")
+    p.add_argument("-o", "--out", default="activity.csv", help="output CSV")
+    p.add_argument("--groups", help="comma-separated cell lines to run, in "
+                                    "output order (default: all)")
+    p.add_argument("--zero-truncation", action="store_true",
+                   help="drop all-zero rows instead of fitting them as "
+                        "structural zeros")
+    p.add_argument("--abundance", choices=("free", "gamma"), default="free",
+                   help="per-object abundance: a free a_n, or integrated out "
+                        "under a Gamma prior")
+    p.add_argument("--nodes", type=int, default=24,
+                   help="quadrature nodes for the Gamma abundance integral")
+    p.add_argument("--a-max", type=float, default=15.0)
+    p.add_argument("--lambda-fix", type=float, default=50.0)
+    p.add_argument("--mu-prior", type=float, default=1.3,
+                   help="sd of the prior on the effect location (0 disables)")
+    p.add_argument("--sigma-prior", default="0,0.5",
+                   help="mean,sd of the prior on log sigma ('none' disables)")
+    p.add_argument("--grid", default="121x33",
+                   help="readout grid, n_mu x n_log_sigma")
+    p.add_argument("--fields", help="comma-separated subset of the output "
+                                    "fields (default: all of them)")
+    p.add_argument("--save-fits", help="pickle the fitted parameters here")
+    p.add_argument("--warm-from", help="warm-start from a fits pickle")
+    p.add_argument("--netcdf", help="also write the full posterior to netCDF")
+    p.add_argument("--plots", metavar="DIR",
+                   help="also write the diagnostic plots into DIR")
+    p.add_argument("-q", "--quiet", action="store_true")
+    return p.parse_args(argv)
+
+
+def main(argv=None):
+    a = _parse_args(argv)
+    n_mu, n_ls = (int(v) for v in a.grid.lower().split("x"))
+    sigma_prior = None if a.sigma_prior.lower() == "none" else \
+        tuple(float(v) for v in a.sigma_prior.split(","))
+    fit_kw = dict(conditional=a.zero_truncation, a_max=a.a_max,
+                  lambda_fix=a.lambda_fix, sigma_prior=sigma_prior,
+                  mu_prior=a.mu_prior or None)
+    if a.abundance == "gamma":
+        fit_kw.update(abundance=False, abundance_prior="gamma",
+                      n_abund_nodes=a.nodes)
+
+    table, results = activity_table(
+        a.data, groups=a.groups.split(",") if a.groups else None,
+        out=a.out, fits_out=a.save_fits, warm_from=a.warm_from,
+        readout=dict(n_mu=n_mu, n_ls=n_ls),
+        fields=tuple(a.fields.split(",")) if a.fields else TABLE_FIELDS,
+        verbose=not a.quiet, **fit_kw)
+    print(f"[saved] {a.out}  {table.shape[0]} sequences x "
+          f"{len(results)} cell lines")
+    if a.netcdf:
+        write_netcdf(a.netcdf, results, table.index, order=list(results),
+                     attrs=dict(model="EBin", readout=f"{n_mu}x{n_ls} grid"))
+        print(f"[saved] {a.netcdf}")
+    if a.plots:
+        from .plots import plot_all
+        plot_all(table, a.data, a.plots, groups=list(results))
+
+
+if __name__ == "__main__":
+    main()

ebin-1.0/ebin/activity.py

@@ -0,0 +1,158 @@
+"""Posterior-mean activity E[bin] and its uncertainty.
+
+The plug-in readout E[bin] = sum_b b * Pi[n,b] at the fitted (mu_n, sigma_n) is
+a MODE.  For a low-information object the posterior over (mu_n, sigma_n) is
+diffuse and skewed, so its mode sits near a simplex vertex (activity 1 or B,
+regardless of depth) while the posterior MEAN is a mild tilt with a large SD --
+the honest summary, and the one that ships.
+
+E[bin] is a functional of theta = (mu_n, sigma_n), so its posterior mean is
+
+    activity_n = sum_j w_{n,j} ebin(theta_j),  w_{n,j} ~ p(X_n | theta_j) p(theta_j)
+
+on a shared (mu, log sigma) grid.  The abundance is PROFILED per grid point (a
+size factor a = total_n / E[total | a = 1, theta_j]), so a deep object's
+likelihood is sharply peaked and a 3-read object's is flat: depth enters
+honestly instead of being frozen at the joint mode.  The prior is the same
+penalty the fit used, so the posterior mean is coherent with the fitted model.
+"""
+
+import numpy as np
+import jax
+import jax.numpy as jnp
+
+from .model import LoglikBuilder
+from .effects import normal_bin_probs
+from .truncation import log_zero_prob, log1mexp
+
+jax.config.update("jax_enable_x64", True)
+
+
+def posterior_activity(res, X, mask, *, mu_center=0.0, tau_within="auto",
+                       sigma_prior="auto", conditional="auto",
+                       n_mu=121, n_ls=33,
+                       mu_lim=12.0, ls_lim=(0.2, 5.0)):
+    """Posterior summary of every object of one cell line.
+
+    res         : a fitted ``FitResult`` (supplies R, P, rates, cuts, config).
+    X, mask     : the same (N, S, B) arrays the fit saw.
+    mu_center   : scalar or (N,) shrinkage target of the mu prior (0 = neutral).
+    tau_within  : sd of the mu prior; "auto" takes the fit's ``mu_prior``,
+                  None gives a flat effect location.
+    sigma_prior : (m, s) log-sigma prior; "auto" takes the fit's.
+    conditional : whether the per-object likelihood is zero-truncated; "auto"
+                  takes the fit's.  Under zero inflation phi is a global
+                  constant and drops out of the per-object weights.
+
+    Everything comes from the SAME posterior weights, so the summaries are
+    mutually consistent (activity == bin_prob @ [1..B], q2 == mu).  Returns a
+    dict of (N,) arrays, NaN off ``res.observed``:
+
+      activity, activity_sd   posterior mean and SD of E[bin]
+      activity_map            the plug-in mode, for reference
+      mu, sigma               posterior-mean effect location and scale
+      mu_sd, sigma_sd         their posterior SDs (standard errors)
+      q1, q2, q3              quartiles of the posterior-mean effect law
+      abundance               posterior-mean profiled size factor a_n
+      n_eff                   posterior grid support (larger = more diffuse)
+      tot                     observed reads
+      observed                (N,) bool
+
+    plus bin_prob, the (N, B) posterior-mean distribution over bins.
+    """
+    cfg = res.config
+    X = np.asarray(X)
+    N, S, B = X.shape
+    bvec = np.arange(1, B + 1, dtype=float)
+    lambda_fix = cfg["lambda_fix"]
+    # profile the abundance up to a_max whenever the fit modelled one, whether
+    # as a free a_n or integrated out under the Gamma prior
+    a_max = (cfg["a_max"]
+             if (cfg["abundance"] or cfg.get("abundance_prior")) else 1.0)
+    rate_max = lambda_fix * a_max
+    if tau_within == "auto":
+        tau_within = cfg.get("mu_prior")
+    if isinstance(sigma_prior, str):
+        sigma_prior = cfg.get("sigma_prior")
+    if conditional == "auto":
+        conditional = cfg.get("conditional", True)
+
+    cuts = jnp.asarray(res.cuts)
+    R, P = jnp.asarray(res.R), jnp.asarray(res.P)
+    rates, log_w = jnp.asarray(res.rates), jnp.asarray(res.log_w)
+    lam = np.asarray(res.rates)[:, 0]                          # (S,) K = 1
+    c = np.asarray(res.R) * (1 - np.asarray(res.P)) / np.asarray(res.P)
+
+    builder = LoglikBuilder(X, mask=mask, rate_max=rate_max)
+    kept = np.asarray(res.observed)
+    Xz = np.where(np.asarray(builder.mask), np.nan_to_num(X, nan=0.0), 0.0)
+    total = Xz.sum((1, 2))                                     # observed reads
+
+    # shared (mu, log sigma) grid, its activity readout and expected total
+    mu_g = np.linspace(-mu_lim, mu_lim, n_mu)
+    ls_g = np.linspace(np.log(ls_lim[0]), np.log(ls_lim[1]), n_ls)
+    MU, LS = np.meshgrid(mu_g, ls_g, indexing="ij")
+    MU, LS = MU.ravel(), LS.ravel()
+    G = MU.size
+    Pi_g = np.asarray(normal_bin_probs(jnp.asarray(MU), jnp.exp(jnp.asarray(LS)),
+                                       cuts))
+    ebin_g = Pi_g @ bvec                                        # (G,)
+    denom_g = (c[None] * Pi_g[:, None, :]).sum(2) @ lam         # E[tot | a = 1]
+
+    @jax.jit
+    def ll_grid(pi_row, a_col):
+        M = a_col[:, None] * pi_row[None, :]
+        obj = builder.object_loglik(R, P, M, rates, log_w, 0.0)
+        if not conditional:
+            return obj
+        lz = jnp.minimum(log_zero_prob(R, P, M, rates, log_w, builder.mask),
+                         -1e-12)
+        return obj - log1mexp(lz)
+
+    ll = np.empty((N, G))
+    a_grid = np.empty((N, G))
+    for j in range(G):
+        a_col = np.clip(total / max(denom_g[j], 1e-12), 1e-4, a_max)
+        a_grid[:, j] = a_col
+        ll[:, j] = np.asarray(ll_grid(jnp.asarray(Pi_g[j]), jnp.asarray(a_col)))
+
+    # per-object prior over the grid: N(mu; center_n, tau^2) * N(ls; m_s, s_s)
+    logprior = np.zeros((N, G))
+    if tau_within is not None:
+        center = np.broadcast_to(np.asarray(mu_center, float), (N,))
+        logprior = logprior - (MU[None, :] - center[:, None]) ** 2 \
+            / (2.0 * tau_within ** 2)
+    if sigma_prior is not None:
+        m_s, s_s = sigma_prior
+        logprior = logprior - ((LS - m_s) ** 2 / (2.0 * s_s ** 2))[None, :]
+
+    logpost = ll + logprior
+    logpost -= logpost.max(1, keepdims=True)
+    w = np.exp(logpost)
+    w /= w.sum(1, keepdims=True)
+    ebin_pm = w @ ebin_g
+    ebin_sd = np.sqrt(np.clip(w @ (ebin_g ** 2) - ebin_pm ** 2, 0, None))
+
+    sig_g = np.exp(LS)
+    mu_pm = w @ MU
+    sigma_pm = w @ sig_g
+    z25 = 0.6744897501960817                           # N(0,1) third quartile
+    return dict(
+        activity=np.where(kept, ebin_pm, np.nan),
+        activity_sd=np.where(kept, ebin_sd, np.nan),
+        activity_map=np.where(kept, np.asarray(res.Pi) @ bvec, np.nan),
+        mu=np.where(kept, mu_pm, np.nan),
+        mu_sd=np.where(kept, np.sqrt(np.clip(w @ (MU ** 2) - mu_pm ** 2,
+                                             0, None)), np.nan),
+        sigma=np.where(kept, sigma_pm, np.nan),
+        sigma_sd=np.where(kept, np.sqrt(np.clip(w @ (sig_g ** 2)
+                                                - sigma_pm ** 2, 0, None)),
+                          np.nan),
+        q1=np.where(kept, w @ (MU - z25 * sig_g), np.nan),
+        q2=np.where(kept, mu_pm, np.nan),
+        q3=np.where(kept, w @ (MU + z25 * sig_g), np.nan),
+        abundance=np.where(kept, (w * a_grid).sum(1), np.nan),
+        n_eff=np.where(kept, 1.0 / (w ** 2).sum(1), np.nan),
+        tot=np.where(kept, total, np.nan),
+        bin_prob=np.where(kept[:, None], w @ Pi_g, np.nan),
+        observed=kept)