ebin 1.0__py3-none-any.whl

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/__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/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)

ebin/data.py

@@ -0,0 +1,93 @@
+"""Reading the sorting-bin count table.
+
+The expected layout is a table with one row per sequence and a 3-level column
+header ``(cell_line, replicate, bin)``:
+
+    seq,   A549,A549,A549,A549,A549,...    <- cell line
+           rep1,rep1,rep1,rep1,rep2,...    <- replicate
+           bin1,bin2,bin3,bin4,bin1,...    <- expression bin
+
+Each cell line is loaded as an independent (N, S, B) tensor of counts.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class GroupData:
+    name: str
+    X: np.ndarray          # (N, S, B) counts
+    mask: np.ndarray       # (N, S, B) bool, True = observed
+    index: pd.Index
+    s_names: list
+    b_names: list
+
+
+def read_counts(path, sep=None):
+    """Read the count table; ``sep`` defaults to tab for .tsv, comma otherwise."""
+    if sep is None:
+        sep = "\t" if str(path).endswith((".tsv", ".txt")) else ","
+    return pd.read_csv(path, sep=sep, index_col=0, header=[0, 1, 2])
+
+
+def load_groups(path_or_df, groups=None, verbose=False):
+    """Split the count table into per-cell-line (N, S, B) tensors.
+
+    Empty fields are read as counts of ZERO, not as missing cells.  Some
+    export formats write every zero as a blank; treating those as unobserved
+    deletes exactly the informative zeros of the low-abundance sequences (an
+    object recorded as (0,0,0,14) would reach the likelihood as (-,-,-,14),
+    which carries no information about its bin profile at all).  Only rows that
+    are zero everywhere are meant to drop out, and the likelihood handles those.
+
+    Rows keep file order, so the returned index aligns with the fit output.
+    """
+    df = path_or_df if isinstance(path_or_df, pd.DataFrame) \
+        else read_counts(path_or_df)
+    n_blank = int(df.isna().to_numpy().sum())
+    if n_blank and verbose:
+        print(f"[data] {n_blank} empty fields read as zero counts")
+    df = df.fillna(0.0)
+
+    out = {}
+    all_groups = list(dict.fromkeys(df.columns.get_level_values(0)))
+    unknown = [g for g in (groups or ()) if g not in all_groups]
+    if unknown:
+        raise ValueError(f"unknown cell line(s) {unknown}; "
+                         f"the table has {all_groups}")
+    for g in (groups or all_groups):
+        sub = df[g]
+        s_names = list(dict.fromkeys(sub.columns.get_level_values(0)))
+        b_names = list(dict.fromkeys(sub.columns.get_level_values(1)))
+        cols = pd.MultiIndex.from_product([s_names, b_names])
+        missing = [c for c in cols if c not in sub.columns]
+        if missing:
+            raise ValueError(f"group {g}: non-rectangular columns {missing}")
+        sub = sub[cols]
+        X = sub.to_numpy(dtype=np.float64).reshape(
+            len(sub), len(s_names), len(b_names))
+        out[g] = GroupData(name=g, X=X, mask=~np.isnan(X), index=sub.index,
+                           s_names=s_names, b_names=b_names)
+    return out
+
+
+def bin_order(b_names):
+    """Column order that sorts bins by the number in their name (bin1 < bin2)."""
+    key = lambda b: int("".join(c for c in str(b) if c.isdigit()) or 0)
+    return sorted(range(len(b_names)), key=lambda i: key(b_names[i]))
+
+
+def prep(gd):
+    """(X, mask, measured) with bins in ascending order.
+
+    ``measured`` marks the objects with at least one read; the all-zero rows
+    carry no activity signal (they are either silent or unsampled).
+    """
+    bo = bin_order(gd.b_names)
+    X, mask = gd.X[:, :, bo], gd.mask[:, :, bo]
+    measured = mask.any((1, 2)) & (np.where(mask, np.nan_to_num(X), 0)
+                                   .sum((1, 2)) > 0)
+    return X, mask, measured

ebin/effects.py

@@ -0,0 +1,161 @@
+"""Normal-effects parameterization of the bin profile Pi.
+
+Each object carries a latent Gaussian effect law E_n ~ Normal(mu_n, sigma_n^2)
+-- how the cells of that sequence spread over the measured phenotype.  The
+library's marginal effect law is then the N-component mixture of those per-
+sequence normals, and the B sorting bins are its quantile cells:
+
+    G(x) = sum_n w_n * Phi((x - mu_n) / sigma_n),      w_n = 1 / N_observed,
+
+with cut points q_1 < ... < q_{B-1} solving G(q_j) = j / B, so that
+
+    Pi[n, b] = Phi((q_b - mu_n)/sigma_n) - Phi((q_{b-1} - mu_n)/sigma_n).
+
+That spends 2 parameters per object instead of B-1, and ties every object to
+the global marginal through the shared cuts (which move when any object moves).
+The cuts are an implicit function of all (mu, sigma); gradients flow through the
+root solve by the implicit function theorem.
+
+Gauge freedom: the likelihood sees the parameters only through the z-scores
+(q_j - mu_n)/sigma_n, so it is exactly invariant under
+(mu, sigma, q) -> (a + k*mu, k*sigma, a + k*q), k > 0.  Location and scale of
+the effect axis are conventions; ``gauge_normalize`` pins them (median cut = 0,
+first cut = -1).  B >= 3 is required for per-object sigma to mean anything.
+"""
+
+from functools import partial
+
+import numpy as np
+import jax
+import jax.numpy as jnp
+from jax.scipy.stats import norm as _jnorm
+from scipy.special import ndtri as _ndtri
+
+jax.config.update("jax_enable_x64", True)
+
+# Solver constants in standardized (mixture sd = 1) coordinates.  The step clamp
+# tames Newton in flat CDF regions; the bracket contains any p-quantile with
+# p in [1/2500, 1 - 1/2500] by Chebyshev, far wider than any 1/B.
+_STEP_CLAMP = 3.0
+_BRACKET = 50.0
+_XATOL = 1e-13
+_MAX_ITER = 200
+
+
+@partial(jax.custom_jvp, nondiff_argnums=(0, 1))
+def _newton_root(fun, dfun, args, x0):
+    """Solve fun(x, args) = 0 by bracketed Newton from x0.
+
+    ``fun`` must be increasing in x with derivative ``dfun``, and the root must
+    lie in [x0 - _BRACKET, x0 + _BRACKET].  Every iterate tightens the sign
+    bracket; a clamped Newton candidate that leaves the bracket is replaced by
+    bisection, so isolated modes of a spiky mixture cannot be jumped over.
+    """
+    def cond(state):
+        x_prev, i, x, lo, hi = state
+        return (jnp.abs(x - x_prev) > _XATOL) & (i < _MAX_ITER)
+
+    def body(state):
+        _, i, x, lo, hi = state
+        f = fun(x, args)
+        lo = jnp.where(f < 0, jnp.maximum(lo, x), lo)
+        hi = jnp.where(f >= 0, jnp.minimum(hi, x), hi)
+        step = jnp.clip(f / dfun(x, args), -_STEP_CLAMP, _STEP_CLAMP)
+        x_newton = x - step
+        inside = (x_newton > lo) & (x_newton < hi)
+        x_next = jnp.where(inside, x_newton, 0.5 * (lo + hi))
+        return (x, i + 1, x_next, lo, hi)
+
+    state = (x0 + 1.0, 0, x0, x0 - _BRACKET, x0 + _BRACKET)
+    return jax.lax.while_loop(cond, body, state)[2]
+
+
+@_newton_root.defjvp
+def _newton_root_jvp(fun, dfun, primals, tangents):
+    args, x0 = primals
+    t_args, _ = tangents                       # the root is independent of x0
+    x_star = _newton_root(fun, dfun, args, x0)
+    # implicit function theorem: dx*/dargs = -(dfun/dargs) / (dfun/dx)
+    _, j_args = jax.jvp(lambda a: fun(x_star, a), (args,), (t_args,))
+    return x_star, -j_args / dfun(x_star, args)
+
+
+def _mix_resid(t, args, p):
+    """G(m0 + s0*t) - p for the weighted normal mixture."""
+    mu, sigma, w, m0, s0 = args
+    x = m0 + s0 * t
+    return jnp.sum(w * _jnorm.cdf((x - mu) / sigma)) - p
+
+
+def _mix_slope(t, args):
+    """d/dt of _mix_resid (floored: a quantile in a density gap is genuinely
+    ill-conditioned; the floor only prevents NaNs)."""
+    mu, sigma, w, m0, s0 = args
+    x = m0 + s0 * t
+    dens = jnp.sum(w * _jnorm.pdf((x - mu) / sigma) / sigma)
+    return jnp.maximum(dens * s0, 1e-300)
+
+
+def mixture_quantiles(mu, sigma, weights, target_probs):
+    """Cut points q_j with sum_n w_n Phi((q_j - mu_n)/sigma_n) = p_j.
+
+    Differentiable in (mu, sigma) and in ``weights`` through the implicit
+    function theorem; ``target_probs`` are constants.  The solve runs in
+    standardized coordinates, so Newton's start and step clamp are scale-free;
+    freezing the standardization costs nothing since the root is exact either
+    way and all derivatives flow through the root.
+    """
+    target_probs = np.asarray(target_probs, dtype=float)
+    m = jnp.sum(weights * mu)
+    v = jnp.sum(weights * (sigma ** 2 + mu ** 2)) - m ** 2
+    m0 = jax.lax.stop_gradient(m)
+    s0 = jax.lax.stop_gradient(jnp.sqrt(jnp.clip(v, 1e-30, None)))
+    args = (mu, sigma, weights, m0, s0)
+    cuts = []
+    for p in target_probs:
+        fun = partial(_mix_resid, p=float(p))
+        t0 = jnp.asarray(float(_ndtri(p)), dtype=jnp.float64)
+        t_star = _newton_root(fun, _mix_slope, args, t0)
+        cuts.append(m0 + s0 * t_star)
+    return jnp.stack(cuts)
+
+
+def normal_bin_probs(mu, sigma, cuts, floor=1e-12):
+    """(N, B) bin probabilities Pi[n,b] = Phi(z_{n,b}) - Phi(z_{n,b-1}).
+
+    Rows sum to 1 exactly; ``floor`` keeps every cell strictly positive (an
+    object far outside the cuts would otherwise underflow whole bins to 0 and
+    give -inf loglik for nonzero counts there).
+    """
+    z = (cuts[None, :] - mu[:, None]) / sigma[:, None]       # (N, B-1)
+    cdf = _jnorm.cdf(z)
+    zero = jnp.zeros((cdf.shape[0], 1), dtype=cdf.dtype)
+    one = jnp.ones((cdf.shape[0], 1), dtype=cdf.dtype)
+    raw = jnp.maximum(jnp.concatenate([cdf, one], axis=1)
+                      - jnp.concatenate([zero, cdf], axis=1), 0.0)
+    B = raw.shape[1]
+    return (raw + floor) / (1.0 + B * floor)
+
+
+def gauge_normalize(mu, sigma, cuts, pin_median=0.0, pin_left=-1.0):
+    """Exact affine normalization of the (unidentified) effect-axis gauge.
+
+    Maps (mu, sigma, cuts) -> (a + k*mu, k*sigma, a + k*cuts) so the middle cut
+    equals ``pin_median`` and (if ``pin_left`` is given and B >= 3) the first cut
+    equals ``pin_left``.  The likelihood is exactly invariant under this map.
+    """
+    mu = np.asarray(mu, dtype=float)
+    sigma = np.asarray(sigma, dtype=float)
+    cuts = np.asarray(cuts, dtype=float)
+    mid = len(cuts) // 2
+    if pin_left is not None and mid > 0:
+        if pin_median <= pin_left:
+            raise ValueError("pin_median must exceed pin_left")
+        k = (cuts[mid] - cuts[0]) / (pin_median - pin_left)
+        if k <= 0:
+            raise ValueError("cuts must be increasing")
+    else:
+        k = 1.0
+    mu2 = pin_median + (mu - cuts[mid]) / k
+    cuts2 = pin_median + (cuts - cuts[mid]) / k
+    return mu2, sigma / k, cuts2