"""Wasserman (2004), Chapter 2: Random Variables.

Reproduces the figures of Chapter 2 of L. Wasserman, All of Statistics: A Concise Course in
Statistical Inference (Springer, 2004), pp. 19-46, written from scratch with numpy, scipy and
matplotlib, and computes every number quoted in the lecture notes (../ch02-random-variables.html).
The functions are small and meant to be read next to the notes:

* Sections 2.1-2.2, distribution functions: cdf_discrete and quantile_discrete (the quantile
  function of Definition 2.16, inf{x : F(x) > q}, for a mass function on a finite or countable
  grid), quantile_lower (the other common convention, inf{x : F(x) >= q}), ks_distance (the
  largest gap between an empirical and a true cdf, for continuous, discrete and mixed laws).
* Sections 2.3-2.4, the standard families: the mass functions and densities written out
  (binom_pmf, poisson_pmf, geom_pmf, gamma_pdf, beta_pdf, t_pdf, chi2_pdf, ...), each confirmed
  against scipy.stats.
* Inverse-cdf sampling (Exercise 2.15): inverse_cdf_sample draws from any of the laws of the
  inverse-cdf demonstration by pushing uniforms through the quantile function; INVCDF_FAMILIES
  lists them, including the empirical cdf of the book's nerve data (which is the bootstrap).
* Sections 2.5-2.10, joint, marginal and conditional distributions: the numbers of Examples 2.22,
  2.32, 2.38-2.40 by numerical integration (examples_joint), the multinomial pmf (2.9) and the
  multivariate normal (2.10) with sampling by X = mu + Sigma^(1/2) Z (mvn_sqrt, mvn_sample) and
  the partitioned conditional of Theorem 2.44 (mvn_conditional).
* Sections 2.11-2.12, transformations: transform_cdf (the three-step cdf method, (2.11), for the
  transformations of the transformation demonstration), transform_pdf (the many-to-one form of
  (2.12): a sum over preimages of f_X(s) |ds/dy|), lattice_law and sum_lattice (the distribution
  of a sum by repeated discrete convolution, as in the convolution demonstration), irwin_hall_pdf,
  and the laws of the maximum and the minimum (max_pdf, min_pdf).
* The browser demonstrations draw their random numbers with a seeded generator (mulberry32 and
  Box-Muller, DK.rng in courses/demo-kit.js); js_uniforms and JSRandom reproduce that stream, so
  the numbers a demonstration shows can be recomputed here.

Figures reproduced (all six figures of the chapter): 2.1 (cdf of the number of heads in two
flips), 2.2 (its mass function), 2.3 (the Uniform(0,1) cdf), 2.4 (the standard Normal density),
2.5 (the support of the density of Example 2.22 and the event X >= Y) and 2.6 (the set A_y of
Example 2.48 for y < 1 and y > 1). Figures 2.5 and 2.6 are drawn from the exact regions.
Supplementary figures for the examples and exercises:
* 2.S1: the cdf of Exercise 2.2 (the exercise asks for the plot);
* 2.S2: the cdf method at work: Examples 2.46 and 2.47 and Exercise 2.4(b), densities against
  histograms of 20,000 simulated values;
* 2.S3: Exercise 2.13, the log-normal density against a histogram of 10,000 values e^X;
* 2.S4: Exercise 2.15, an exponential generator built from uniforms by the inverse cdf, with
  the probability integral transform F(X) of the result;
* 2.S5: sums by convolution, Example 2.48 and beyond (sums of 1, 2, 3 and 12 uniforms against
  the Irwin-Hall density), and the maximum and minimum of exponentials (Exercise 2.21);
* 2.S6: the bivariate Normal of Theorems 2.43-2.44: samples, a conditional slice and the
  chi-squared law of the Mahalanobis distance.
Nothing in the chapter is skipped. Run `python3 ch02_random_variables.py --list`, `python3
ch02_random_variables.py` (all figures, about ten seconds) or `python3 ch02_random_variables.py
--fig 2.5`. Files go to ../img/ch02/; the nerve data for the inverse-cdf demonstration go to
../data/ch02-nerve.json (export_demo_data).
"""
import json
import math
import os

import numpy as np
from scipy import integrate, special, stats

import common
from common import BLUE, GREEN, GREY, ORANGE, PURPLE, RED, savefig

CH = 2
HERE = os.path.dirname(os.path.abspath(__file__))
DATA_OUT = os.path.normpath(os.path.join(HERE, "..", "data"))
M32 = 0xFFFFFFFF


# =========================================================================== the demos' generator
def js_uniforms(seed, n, start=0):
    """n consecutive DK.rng(seed).u() values after `start` earlier calls.

    mulberry32 adds 0x6D2B79F5 to a 32-bit state at every call and returns a hash of the new
    state, so the j-th output depends only on seed + j * 0x6D2B79F5 (mod 2^32): it can be computed
    for all j at once."""
    j = np.arange(start + 1, start + n + 1, dtype=np.uint64)
    m = np.uint64(M32)
    a = (np.uint64(int(seed) & M32) + j * np.uint64(0x6D2B79F5)) & m
    t = ((a ^ (a >> np.uint64(15))) * (np.uint64(1) | a)) & m
    t = ((t + (((t ^ (t >> np.uint64(7))) * (np.uint64(61) | t)) & m)) & m) ^ t
    return ((t ^ (t >> np.uint64(14))) & m).astype(np.float64) / 4294967296.0


class JSRandom:
    """DK.rng(seed) call by call: u() (mulberry32), norm() (Box-Muller, cosine first, the sine
    kept for the next call) and exp(mean) (-mean log U with U > 0)."""

    def __init__(self, seed):
        self.a = int(seed) & M32
        self.spare = None

    def u(self):
        a = (self.a + 0x6D2B79F5) & M32
        self.a = a
        t = ((a ^ (a >> 15)) * (1 | a)) & M32
        t = ((t + (((t ^ (t >> 7)) * (61 | t)) & M32)) & M32) ^ t
        return ((t ^ (t >> 14)) & M32) / 4294967296.0

    def pos(self):
        x = 0.0
        while x == 0.0:
            x = self.u()
        return x

    def norm(self):
        if self.spare is not None:
            s, self.spare = self.spare, None
            return s
        r = math.sqrt(-2.0 * math.log(self.pos()))
        th = 2.0 * math.pi * self.u()
        self.spare = r * math.sin(th)
        return r * math.cos(th)

    def exp(self, mean):
        return -mean * math.log(self.pos())


# =========================================================================== Sections 2.2-2.4
def binom_pmf(x, n, p):
    """Binomial(n, p) mass function (Section 2.3)."""
    x = np.asarray(x)
    out = np.zeros(x.shape)
    ok = (x >= 0) & (x <= n) & (x == np.floor(x))
    xs = x[ok].astype(int)
    out[ok] = special.comb(n, xs) * p ** xs * (1 - p) ** (n - xs)
    return out


def poisson_pmf_list(lam, kmax):
    """[f(0), ..., f(kmax)] for Poisson(lam) by the recursion f(k) = f(k-1) lam / k (the order of
    operations of the demonstrations, so that both give the same floating-point numbers)."""
    p = [math.exp(-lam)]
    for k in range(1, kmax + 1):
        p.append(p[-1] * lam / k)
    return p


def geom_pmf(k, p):
    """Geom(p) on k = 1, 2, ...: P(X = k) = p (1 - p)^(k - 1)."""
    k = np.asarray(k, dtype=float)
    return np.where(k >= 1, p * (1 - p) ** (k - 1), 0.0)


def gamma_pdf(x, alpha, beta):
    """Gamma(alpha, beta) density in the book's scale parametrisation (mean alpha beta)."""
    x = np.asarray(x, dtype=float)
    with np.errstate(divide="ignore", invalid="ignore"):
        v = np.exp((alpha - 1) * np.log(x) - x / beta - alpha * np.log(beta) - special.gammaln(alpha))
    return np.where(x > 0, v, 0.0)


def beta_pdf(x, a, b):
    x = np.asarray(x, dtype=float)
    with np.errstate(divide="ignore", invalid="ignore"):
        v = np.exp((a - 1) * np.log(x) + (b - 1) * np.log1p(-x) - special.betaln(a, b))
    return np.where((x > 0) & (x < 1), v, 0.0)


def t_pdf(x, nu):
    """Student t density with the normalising constant Gamma((nu+1)/2) / (sqrt(nu pi) Gamma(nu/2));
    the factor 1/sqrt(nu pi) is missing in the book's first printing (listed in the author's errata)."""
    x = np.asarray(x, dtype=float)
    c = math.exp(special.gammaln((nu + 1) / 2) - special.gammaln(nu / 2)) / math.sqrt(nu * math.pi)
    return c * (1 + x * x / nu) ** (-(nu + 1) / 2)


def chi2_pdf(x, p):
    return gamma_pdf(x, p / 2, 2.0)


def normal_pdf(x, mu=0.0, sigma=1.0):
    z = (np.asarray(x, dtype=float) - mu) / sigma
    return np.exp(-0.5 * z * z) / (sigma * math.sqrt(2 * math.pi))


def Phi(z):
    return 0.5 * special.erfc(-np.asarray(z, dtype=float) / math.sqrt(2))


def qnorm(p):
    """Standard normal quantile by Acklam's rational approximation (relative error about 1e-9), as
    DK.qnorm in the demonstrations."""
    a = [-3.969683028665376e+01, 2.209460984245205e+02, -2.759285104469687e+02, 1.383577518672690e+02,
         -3.066479806614716e+01, 2.506628277459239e+00]
    b = [-5.447609879822406e+01, 1.615858368580409e+02, -1.556989798598866e+02, 6.680131188771972e+01,
         -1.328068155288572e+01]
    c = [-7.784894002430293e-03, -3.223964580411365e-01, -2.400758277161838e+00, -2.549732539343734e+00,
         4.374664141464968e+00, 2.938163982698783e+00]
    d = [7.784695709041462e-03, 3.224671290700398e-01, 2.445134137142996e+00, 3.754408661907416e+00]
    if p <= 0:
        return -math.inf
    if p >= 1:
        return math.inf
    if p < 0.02425:
        q = math.sqrt(-2 * math.log(p))
        return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
    if p > 1 - 0.02425:
        q = math.sqrt(-2 * math.log(1 - p))
        return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
    q = p - 0.5
    r = q * q
    return (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)


# ================================================================ the quantile function
def cdf_discrete(support, pmf):
    """Cumulative sums F(x_k) = sum_{j <= k} f(x_j) on a sorted support (sequential sums)."""
    cum, s = [], 0.0
    for v in pmf:
        s += v
        cum.append(s)
    return np.asarray(support, dtype=float), np.asarray(cum)


def quantile_discrete(u, support, cum):
    """Definition 2.16: F^{-1}(u) = inf{x : F(x) > u}, the first support point whose cumulative
    probability exceeds u. Returns +inf when no point does (u >= the total mass)."""
    u = np.atleast_1d(np.asarray(u, dtype=float))
    idx = np.searchsorted(cum, u, side="right")
    out = np.full(u.shape, np.inf)
    ok = idx < len(cum)
    out[ok] = np.asarray(support)[idx[ok]]
    return out


def quantile_lower(u, support, cum):
    """The other common convention, inf{x : F(x) >= u} (the left-continuous quantile)."""
    u = np.atleast_1d(np.asarray(u, dtype=float))
    idx = np.searchsorted(cum, u, side="left")
    out = np.full(u.shape, np.inf)
    ok = idx < len(cum)
    out[ok] = np.asarray(support)[idx[ok]]
    return out


def ks_distance(x, F, Fleft=None):
    """sup_t |F_n(t) - F(t)| for the empirical cdf F_n of the sample x.

    Between consecutive distinct sample values F_n is constant and F is non-decreasing, so the
    supremum is attained at a sample value v, either at v itself (right values) or just before it
    (left limits F_n(v-) and F(v-)). Fleft(v) = F(v-) must be given when F has jumps."""
    x = np.sort(np.asarray(x, dtype=float))
    n = len(x)
    v, first = np.unique(x, return_index=True)
    last = np.r_[first[1:], n]
    Fn_right = last / n
    Fn_left = first / n
    Fr = np.array([F(t) for t in v])
    Fl = np.array([Fleft(t) for t in v]) if Fleft is not None else Fr
    return float(max(np.max(np.abs(Fn_right - Fr)), np.max(np.abs(Fn_left - Fl))))


# =========================================================================== the inverse-cdf demonstration
INV_SEED = 2015


def nerve_times():
    """Waiting times (seconds) between 799 successive pulses along a nerve fibre, the book's
    nerve.dat (Cox and Lewis 1966), in file order."""
    with open(common.aos_file("nerve.dat")) as f:     # six per row, the last row shorter
        return np.array(f.read().split(), dtype=float)


def invcdf_family(name, par):
    """The laws of the inverse-cdf demonstration: returns a dict with the quantile Q (book
    convention), the cdf F, its left limit Fl, the mean (None if it does not exist), the support
    and mass function when discrete. `par` is the family's one parameter."""
    if name == "exp":                      # Exp(beta), Exercises 2.9 and 2.15
        beta = par
        return dict(Q=lambda u: -beta * np.log1p(-np.asarray(u)), F=lambda t: 0.0 if t < 0 else -math.expm1(-t / beta),
                    Fl=None, mean=beta, kind="cont")
    if name == "normal":                   # N(mu, 1)
        mu = par
        return dict(Q=lambda u: np.array([mu + qnorm(v) for v in np.atleast_1d(u)]), F=lambda t: float(Phi(t - mu)),
                    Fl=None, mean=mu, kind="cont")
    if name == "cauchy":
        return dict(Q=lambda u: np.tan(np.pi * (np.asarray(u) - 0.5)), F=lambda t: 0.5 + math.atan(t) / math.pi,
                    Fl=None, mean=None, kind="cont")
    if name in ("coin", "poisson", "geom"):
        if name == "coin":                 # number of heads in two flips, Example 2.6 (p = 1/2)
            p = par
            sup, pmf = [0, 1, 2], [(1 - p) ** 2, 2 * p * (1 - p), p * p]
            mean = 2 * p
        elif name == "poisson":
            lam = par
            kmax = int(math.ceil(lam + 12 * math.sqrt(lam) + 12))
            pmf = poisson_pmf_list(lam, kmax)
            sup, mean = list(range(kmax + 1)), lam
        else:                              # geometric on 1, 2, ...
            p = par
            kmax = int(math.ceil(40 / p))
            pmf, q = [], p
            for k in range(1, kmax + 1):
                pmf.append(q)
                q *= 1 - p
            sup, mean = list(range(1, kmax + 1)), 1 / p
        s, cum = cdf_discrete(sup, pmf)

        def F(t, s=s, cum=cum):
            i = np.searchsorted(s, t, side="right")
            return 0.0 if i == 0 else float(cum[i - 1])

        def Fl(t, s=s, cum=cum):
            i = np.searchsorted(s, t, side="left")
            return 0.0 if i == 0 else float(cum[i - 1])
        return dict(Q=lambda u: quantile_discrete(u, s, cum), F=F, Fl=Fl, mean=mean, kind="disc",
                    support=s, pmf=np.asarray(pmf), cum=cum)
    if name == "mixed":                    # Y = max(0, X), X ~ N(mu, 1): Exercise 2.8
        mu = par
        p0 = float(Phi(-mu))

        def Q(u):
            u = np.atleast_1d(u)
            return np.array([0.0 if v < p0 else max(0.0, mu + qnorm(v)) for v in u])

        def F(t):
            return 0.0 if t < 0 else float(Phi(t - mu))

        def Fl(t):
            return 0.0 if t <= 0 else float(Phi(t - mu))
        mean = mu * float(Phi(mu)) + float(normal_pdf(mu))     # E max(0, X)
        return dict(Q=Q, F=F, Fl=Fl, mean=mean, kind="mixed", p0=p0)
    if name in ("nerve", "nerve-exp"):
        x = np.sort(nerve_times())
        n = len(x)
        if name == "nerve-exp":
            return invcdf_family("exp", float(x.mean()))
        v, counts = np.unique(x, return_counts=True)
        cum = np.cumsum(counts) / n

        def Q(u):                          # inf{t : F_n(t) > u} = x_(floor(n u) + 1)
            u = np.atleast_1d(u)
            return x[np.minimum(np.floor(n * u).astype(int), n - 1)]

        def F(t):
            i = np.searchsorted(v, t, side="right")
            return 0.0 if i == 0 else float(cum[i - 1])

        def Fl(t):
            i = np.searchsorted(v, t, side="left")
            return 0.0 if i == 0 else float(cum[i - 1])
        return dict(Q=Q, F=F, Fl=Fl, mean=float(x.mean()), kind="disc", support=v, pmf=counts / n, cum=cum)
    raise ValueError(name)


def inverse_cdf_sample(name, par, n, seed=INV_SEED):
    """The demonstration's draws: n uniforms from DK.rng(seed), pushed through the quantile function."""
    fam = invcdf_family(name, par)
    u = js_uniforms(seed, n)
    return fam, u, np.asarray(fam["Q"](u), dtype=float)


def invcdf_summary(name, par, n, seed=INV_SEED):
    """Sample mean and Kolmogorov distance shown by the demonstration."""
    fam, u, x = inverse_cdf_sample(name, par, n, seed)
    D = ks_distance(x, fam["F"], fam["Fl"])
    return dict(mean=float(x.mean()), ks=D, first=x[:5].tolist(), true_mean=fam["mean"])


# =========================================================================== Sections 2.5-2.10
def examples_joint():
    """The numbers of Examples 2.21, 2.22, 2.32, 2.38, 2.40 and Exercise 2.17 by numerical integration."""
    out = {}
    out["2.21"] = integrate.dblquad(lambda y, x: x + y, 0, 1, 0, 1)[0]
    I = integrate.dblquad(lambda y, x: x * x * y, -1, 1, lambda x: x * x, 1)[0]
    out["2.22_c"] = 1 / I
    out["2.22_P"] = out["2.22_c"] * integrate.dblquad(lambda y, x: x * x * y, 0, 1, lambda x: x * x, lambda x: x)[0]
    out["2.32"] = integrate.dblquad(lambda y, x: 4 * x * y, 0, 1, 0, lambda x: 1 - x)[0]
    out["2.38"] = integrate.quad(lambda x: (x + 1 / 3) / (1 / 3 + 0.5), 0, 0.25)[0]
    fx = 21 / 8 * 0.25 * (1 - 0.5 ** 4)
    out["2.40"] = integrate.quad(lambda y: 21 / 4 * 0.25 * y / fx, 0.75, 1)[0]
    c17 = 1 / integrate.dblquad(lambda y, x: x + y * y, 0, 1, 0, 1)[0]
    fy = integrate.quad(lambda x: c17 * (x + 0.25), 0, 1)[0]
    out["ex17_c"] = c17
    out["ex17"] = integrate.quad(lambda x: c17 * (x + 0.25) / fy, 0, 0.5)[0]
    return out


def multinomial_pmf(x, p):
    """(2.9): n! / (x_1! ... x_k!) p_1^x_1 ... p_k^x_k with n = sum x."""
    x = np.asarray(x, dtype=int)
    n = int(x.sum())
    logc = special.gammaln(n + 1) - special.gammaln(x + 1).sum()
    return float(np.exp(logc + np.sum(x * np.log(np.asarray(p, dtype=float)))))


def mvn_sqrt(S):
    """The symmetric square root Sigma^(1/2) = V diag(sqrt(lambda)) V^T from the spectral theorem."""
    lam, V = np.linalg.eigh(S)
    return (V * np.sqrt(lam)) @ V.T


def mvn_sample(mu, S, n, rng):
    """X = mu + Sigma^(1/2) Z with Z ~ N(0, I) (Theorem 2.43)."""
    Z = rng.standard_normal((n, len(mu)))
    return np.asarray(mu) + Z @ mvn_sqrt(S).T


def mvn_pdf(x, mu, S):
    """(2.10)."""
    x = np.atleast_2d(x)
    k = len(mu)
    d = x - mu
    Si = np.linalg.inv(S)
    q = np.einsum("ij,jk,ik->i", d, Si, d)
    return np.exp(-0.5 * q) / ((2 * np.pi) ** (k / 2) * math.sqrt(np.linalg.det(S)))


def mvn_conditional(mu, S, a_idx, xa):
    """Theorem 2.44(2): mean and covariance of X_b given X_a = x_a."""
    a_idx = np.asarray(a_idx)
    b_idx = np.setdiff1d(np.arange(len(mu)), a_idx)
    Saa, Sab = S[np.ix_(a_idx, a_idx)], S[np.ix_(a_idx, b_idx)]
    Sba, Sbb = S[np.ix_(b_idx, a_idx)], S[np.ix_(b_idx, b_idx)]
    K = Sba @ np.linalg.inv(Saa)
    return mu[b_idx] + K @ (np.asarray(xa) - mu[a_idx]), Sbb - K @ Sab


# =========================================================================== Sections 2.11-2.12
# The families and transformations of the transformation demonstration.
def tx_family(name):
    """pdf, cdf, quantile (book convention) and support of the input laws of the demonstration."""
    if name == "unif":          # Uniform(-1, 3), Example 2.47
        a, b = -1.0, 3.0
        return dict(f=lambda x: np.where((x > a) & (x < b), 1 / (b - a), 0.0),
                    F=lambda x: np.clip((np.asarray(x, dtype=float) - a) / (b - a), 0, 1),
                    Q=lambda q: a + (b - a) * q, lo=a, hi=b)
    if name == "normal":
        return dict(f=normal_pdf, F=Phi, Q=qnorm, lo=-np.inf, hi=np.inf)
    if name == "exp":           # Exp(1), Example 2.46
        return dict(f=lambda x: np.where(np.asarray(x) > 0, np.exp(-np.abs(x)), 0.0),
                    F=lambda x: np.where(np.asarray(x) > 0, -np.expm1(-np.maximum(x, 0)), 0.0),
                    Q=lambda q: -math.log1p(-q), lo=0.0, hi=np.inf)
    if name == "ex4":           # Exercise 2.4: 1/4 on (0,1), 3/8 on (3,5)
        def f(x):
            x = np.asarray(x, dtype=float)
            return np.where((x > 0) & (x < 1), 0.25, np.where((x > 3) & (x < 5), 0.375, 0.0))

        def F(x):
            x = np.asarray(x, dtype=float)
            return np.where(x <= 0, 0.0, np.where(x < 1, x / 4, np.where(x <= 3, 0.25,
                            np.where(x < 5, 0.25 + 0.375 * (x - 3), 1.0))))
        return dict(f=f, F=F, Q=lambda q: 4 * q if q < 0.25 else 3 + (q - 0.25) * 8 / 3, lo=0.0, hi=5.0)
    raise ValueError(name)


def tx_draw(name, n, seed):
    """X_1, ..., X_n as the transformation demonstration draws them from DK.rng(seed)."""
    r = JSRandom(seed)
    out = np.empty(n)
    for i in range(n):
        if name == "unif":
            out[i] = -1.0 + 4.0 * r.u()
        elif name == "normal":
            out[i] = r.norm()
        elif name == "exp":
            out[i] = r.exp(1.0)
        else:
            u = r.u()
            out[i] = 4 * u if u < 0.25 else 3 + (u - 0.25) * 8 / 3
    return out


def tx_r(rname, x, fname=None):
    """The maps of the demonstration; "cdf" is Y = F_X(X), the probability integral transform."""
    x = np.asarray(x, dtype=float)
    if rname == "cdf":
        return np.asarray(tx_family(fname)["F"](x), dtype=float)
    with np.errstate(divide="ignore", invalid="ignore"):
        return {"sq": x * x, "abs": np.abs(x), "exp": np.exp(x), "log": np.log(x), "recip": 1 / x}[rname]


def transform_cdf(fname, rname, y):
    """Step 2 of the cdf method, (2.11): F_Y(y) = P(X in A_y), A_y = {x : r(x) <= y}, with A_y
    written out for each transformation as a union of intervals."""
    fam = tx_family(fname)
    F = fam["F"]

    def P(a, b):
        return float(F(b) - F(a))
    inf = np.inf
    if rname in ("sq", "abs"):
        if y < 0:
            return 0.0
        s = math.sqrt(y) if rname == "sq" else y
        return P(-s, s)
    if rname == "exp":
        return 0.0 if y <= 0 else P(-inf, math.log(y))
    if rname == "log":                     # needs X > 0
        return P(0.0, math.exp(y))
    if rname == "recip":                   # 1/x <= y
        if y > 0:
            return P(-inf, 0.0) + P(1 / y, inf)
        if y == 0:
            return P(-inf, 0.0)
        return P(1 / y, 0.0)
    if rname == "cdf":                     # F(x) <= y  <=>  x <= sup{x : F(x) <= y} = F^{-1}(y) (book convention)
        if y < 0:
            return 0.0
        if y >= 1:
            return 1.0
        return P(-inf, fam["Q"](y))
    raise ValueError(rname)


def transform_pdf(fname, rname, y):
    """The many-to-one form of (2.12): f_Y(y) = sum over x with r(x) = y of f_X(x) / |r'(x)|.
    Returns the total and the list of (preimage, f_X(preimage), |ds/dy|)."""
    fam = tx_family(fname)
    f = fam["f"]
    terms = []
    if rname in ("sq", "abs") and y > 0:
        s = math.sqrt(y) if rname == "sq" else y
        jac = 1 / (2 * s) if rname == "sq" else 1.0
        terms = [(-s, float(f(-s)), jac), (s, float(f(s)), jac)]
    elif rname == "exp" and y > 0:
        terms = [(math.log(y), float(f(math.log(y))), 1 / y)]
    elif rname == "log":
        terms = [(math.exp(y), float(f(math.exp(y))), math.exp(y))]
    elif rname == "recip" and y != 0:
        terms = [(1 / y, float(f(1 / y)), 1 / (y * y))]
    elif rname == "cdf" and 0 < y < 1:
        q = fam["Q"](y)
        fq = float(f(q))
        terms = [(q, fq, 1 / fq if fq > 0 else 0.0)]
    return sum(t[1] * t[2] for t in terms), terms


def transform_mc(fname, rname, y, n, seed):
    """Fraction of the demonstration's simulated r(X_i) that are <= y, and their number."""
    x = tx_draw(fname, n, seed)
    with np.errstate(divide="ignore", invalid="ignore"):
        yy = tx_r(rname, x, fname)
    ok = np.isfinite(yy)
    return float(np.mean(yy[ok] <= y)), int(ok.sum())


# ================================================================ sums by convolution
def lattice_law(name, par):
    """X rounded to a lattice: returns (h, o, k0, p) with p[j] = P(X in cell k0 + j), the cell k
    standing for the value (k + o) h. Continuous laws use cells [k h, (k + 1) h) (o = 1/2) and
    masses from the cdf; discrete laws on the integers use h = 1, o = 0 and their exact pmf."""
    if name == "unif":
        h = 0.01
        k = np.arange(0, 100)
        return h, 0.5, 0, np.diff(np.clip(np.r_[k, 100] * h, 0, 1))
    if name == "exp":
        beta = par
        h = 0.05 * beta
        K = 500
        edges = np.arange(K + 1) * h
        return h, 0.5, 0, np.diff(-np.expm1(-edges / beta))
    if name == "normal":
        mu = par
        h = 0.05
        k0 = int(math.floor((mu - 8) / h))
        k1 = int(math.ceil((mu + 8) / h))
        edges = np.arange(k0, k1 + 1) * h
        return h, 0.5, k0, np.diff(Phi(edges - mu))
    if name == "cauchy":
        h = 0.25
        k0, k1 = -1000, 1000
        edges = np.arange(k0, k1 + 1) * h
        return h, 0.5, k0, np.diff(0.5 + np.arctan(edges) / np.pi)
    if name == "bern":
        return 1.0, 0.0, 0, np.array([1 - par, par])
    if name == "poisson":
        lam = par
        kmax = int(math.ceil(lam + 12 * math.sqrt(lam) + 12))
        return 1.0, 0.0, 0, np.array(poisson_pmf_list(lam, kmax))
    raise ValueError(name)


def conv_value_range(name, par, n):
    """Values [a, b] kept for S_n (mass outside is dropped and reported)."""
    if name == "unif":
        return 0.0, float(n)
    if name == "exp":
        return 0.0, par * (n + 12 * math.sqrt(n) + 25)
    if name == "normal":
        return n * par - 8 * math.sqrt(n), n * par + 8 * math.sqrt(n)
    if name == "cauchy":
        return -250.0, 250.0
    if name == "bern":
        return 0.0, float(n)
    if name == "poisson":
        return 0.0, n * par + 12 * math.sqrt(n * par) + 12
    raise ValueError(name)


def conv_window(name, par, n, h, o):
    """Index window [lo, hi] of the cells of S_n whose values lie in conv_value_range."""
    a, b = conv_value_range(name, par, n)
    return int(math.floor(a / h - n * o + 1e-9)), int(math.ceil(b / h - n * o - 1e-9))


def sum_lattice(name, par, n):
    """Lattice laws of S_1, ..., S_n by repeated discrete convolution, f_{S_m} = f_{S_{m-1}} * f_X,
    each restricted to its window. Returns h, o and a list of (lo, p) with p[j] = P(S_m cell lo + j);
    cell K of S_m stands for the value (K + m o) h."""
    h, o, k0, p = lattice_law(name, par)
    laws = [(k0, p)]
    for m in range(2, n + 1):
        lo_prev, q = laws[-1]
        full = np.convolve(q, p)
        lo_full = lo_prev + k0
        wlo, whi = conv_window(name, par, m, h, o)
        a = max(wlo, lo_full)
        b = min(whi, lo_full + len(full) - 1)
        laws.append((a, full[a - lo_full: b - lo_full + 1]))
    return h, o, laws


def sum_lattice_density(name, par, n, z):
    """Read the lattice law of S_n at z: the density, the cdf P(S_n <= z) and the mass kept in the
    window. For continuous laws the density is interpolated linearly between cell centres (mass
    over h) and the cdf between cell edges (the lattice cdf at the upper edge of a cell is the mass
    of the cells up to it). For integer laws: the mass at z and the sum over values <= z."""
    h, o, laws = sum_lattice(name, par, n)
    lo, p = laws[-1]
    vals = (lo + np.arange(len(p)) + n * o) * h
    if o == 0:
        K = int(round(z))
        j = K - lo
        pj = p[j] if 0 <= j < len(p) and abs(z - K) < 1e-9 else 0.0
        return float(pj), float(p[vals <= z + 1e-9].sum()), float(p.sum())
    edges = np.r_[vals[0] - h / 2, vals + h / 2]
    C = np.r_[0.0, np.cumsum(p)]
    dens = float(np.interp(z, vals, p / h, left=0.0, right=0.0))
    return dens, float(np.interp(z, edges, C)), float(p.sum())


def irwin_hall_pdf(s, n):
    """Density of the sum of n independent Uniform(0,1): (1/(n-1)!) sum_k (-1)^k C(n,k) (s-k)_+^(n-1)."""
    s = np.asarray(s, dtype=float)
    out = np.zeros_like(s)
    for k in range(n + 1):
        out += (-1) ** k * special.comb(n, k) * np.where(s > k, (s - k), 0.0) ** (n - 1)
    out /= math.factorial(n - 1)
    return np.where((s >= 0) & (s <= n), out, 0.0)


def conv_exact_pdf(name, par, n, z):
    """The exact density (or mass) of S_n where a closed form exists."""
    if name == "unif":
        return float(irwin_hall_pdf(np.array([z]), n)[0])
    if name == "exp":
        return float(gamma_pdf(np.array([z]), n, par)[0])
    if name == "normal":
        return float(normal_pdf(z, n * par, math.sqrt(n)))
    if name == "cauchy":
        return n / (math.pi * (n * n + z * z))
    if name == "bern":
        return float(binom_pmf(np.array([z]), n, par)[0])
    if name == "poisson":
        return float(stats.poisson.pmf(z, n * par))
    raise ValueError(name)


CONV_SEED = 2048


def conv_draw_one(r, name, par):
    """One draw of X as the convolution demonstration makes it."""
    if name == "unif":
        return r.u()
    if name == "exp":
        return r.exp(par)
    if name == "normal":
        return par + r.norm()
    if name == "cauchy":
        return math.tan(math.pi * (r.u() - 0.5))
    if name == "bern":
        return 1.0 if r.u() < par else 0.0
    if name == "poisson":
        u = r.u()
        pk = math.exp(-par)
        c = pk
        k = 0
        while u >= c and k < 10000:     # inf{k : F(k) > u}
            k += 1
            pk = pk * par / k
            c += pk
        return float(k)
    raise ValueError(name)


def conv_mc(name, par, n, z, nsim, seed=CONV_SEED):
    """Fraction of nsim simulated sums S_n <= z (the demonstration's Monte Carlo histogram)."""
    r = JSRandom(seed)
    S = np.empty(nsim)
    for i in range(nsim):
        s = 0.0
        for _ in range(n):
            s += conv_draw_one(r, name, par)
        S[i] = s
    return float(np.mean(S <= z)), S


def max_pdf(y, n, f, F):
    """Density of the maximum of n iid draws: n F(y)^(n-1) f(y)."""
    return n * F(y) ** (n - 1) * f(y)


def min_pdf(y, n, f, F):
    """Density of the minimum of n iid draws: n (1 - F(y))^(n-1) f(y)."""
    return n * (1 - F(y)) ** (n - 1) * f(y)


# =========================================================================== figures
def _step_cdf(ax, xs, Fs, lo, hi, colour=BLUE):
    """A step cdf drawn as in the book: horizontal pieces, a closed dot at the value taken at each
    jump and an open dot at the left limit."""
    pts = [lo] + list(xs) + [hi]
    vals = [0.0] + list(Fs)
    for i in range(len(pts) - 1):
        ax.plot([pts[i], pts[i + 1]], [vals[i], vals[i]], color=colour, lw=1.8)
    for i, x in enumerate(xs):
        ax.plot([x], [Fs[i]], "o", color=colour, ms=5)
        ax.plot([x], [vals[i]], "o", mfc="white", mec=colour, ms=5)


def fig_2_1(out_dir=None):
    """cdf of the number of heads in two fair flips (Example 2.6)."""
    fig, ax = common.plt.subplots(figsize=(4.4, 3.0))
    _step_cdf(ax, [0, 1, 2], [0.25, 0.75, 1.0], -0.8, 2.8)
    ax.set_xlim(-0.8, 2.8)
    ax.set_ylim(-0.04, 1.08)
    ax.set_xticks([0, 1, 2])
    ax.set_yticks([0, 0.25, 0.5, 0.75, 1])
    ax.set_xlabel("$x$")
    ax.set_ylabel("$F_X(x)$")
    ax.annotate("$F_X(1.4)=0.75$", xy=(1.4, 0.75), xytext=(1.25, 0.45), fontsize=9, color=GREY,
                arrowprops=dict(arrowstyle="->", color=GREY, lw=0.8))
    savefig(fig, CH, "fig2-1", out_dir)


def fig_2_2(out_dir=None):
    """Mass function of the number of heads in two fair flips."""
    fig, ax = common.plt.subplots(figsize=(4.4, 3.0))
    xs, f = [0, 1, 2], [0.25, 0.5, 0.25]
    ax.vlines(xs, 0, f, color=BLUE, lw=2)
    ax.plot(xs, f, "o", color=BLUE, ms=6)
    ax.set_xlim(-0.8, 2.8)
    ax.set_ylim(0, 0.8)
    ax.set_xticks(xs)
    ax.set_yticks([0, 0.25, 0.5, 0.75])
    ax.set_xlabel("$x$")
    ax.set_ylabel("$f_X(x)$")
    savefig(fig, CH, "fig2-2", out_dir)


def fig_2_3(out_dir=None):
    """cdf of the Uniform(0,1) distribution."""
    fig, ax = common.plt.subplots(figsize=(4.4, 3.0))
    ax.plot([-0.5, 0, 1, 1.5], [0, 0, 1, 1], color=BLUE, lw=1.8)
    ax.set_xlim(-0.5, 1.5)
    ax.set_ylim(-0.04, 1.08)
    ax.set_xticks([0, 1])
    ax.set_yticks([0, 1])
    ax.set_xlabel("$x$")
    ax.set_ylabel("$F_X(x)$")
    savefig(fig, CH, "fig2-3", out_dir)


def fig_2_4(out_dir=None):
    """Density of a standard Normal."""
    z = np.linspace(-3.2, 3.2, 600)
    fig, ax = common.plt.subplots(figsize=(4.6, 3.0))
    ax.plot(z, normal_pdf(z), color=BLUE)
    ax.fill_between(z, normal_pdf(z), where=np.abs(z) <= 1, color=BLUE, alpha=0.12, lw=0)
    ax.text(0, 0.12, "%.3f" % (Phi(1) - Phi(-1)), ha="center", fontsize=9, color=BLUE)
    ax.set_xlim(-3.2, 3.2)
    ax.set_ylim(0, 0.43)
    ax.set_xticks([-2, -1, 0, 1, 2])
    ax.set_xlabel("$z$")
    ax.set_ylabel(r"$\phi(z)$")
    savefig(fig, CH, "fig2-4", out_dir)


def fig_2_5(out_dir=None):
    """Support of f(x, y) = (21/4) x^2 y on x^2 <= y <= 1, and the event X >= Y."""
    x = np.linspace(-1.3, 1.3, 400)
    fig, ax = common.plt.subplots(figsize=(4.6, 3.8))
    xx = np.linspace(-1, 1, 400)
    ax.fill_between(xx, xx ** 2, 1, color=GREY, alpha=0.35, lw=0)
    x1 = np.linspace(0, 1, 200)
    ax.fill_between(x1, x1 ** 2, x1, facecolor="none", edgecolor=RED, hatch="xxxx", lw=0)
    ax.plot(x, x ** 2, color="black", lw=1.4)
    ax.plot(np.linspace(-0.2, 1.3, 50), np.linspace(-0.2, 1.3, 50), color=RED, lw=1.2)
    ax.text(1.05, 1.32, "$y=x^2$", fontsize=9)
    ax.text(1.25, 1.1, "$y=x$", fontsize=9, color=RED)
    ax.axhline(0, color="black", lw=0.6)
    ax.set_xlim(-1.3, 1.45)
    ax.set_ylim(-0.1, 1.5)
    ax.set_xticks([-1, 0, 1])
    ax.set_yticks([0, 1])
    ax.set_xlabel("$x$")
    ax.set_ylabel("$y$")
    savefig(fig, CH, "fig2-5", out_dir)


def fig_2_6(out_dir=None):
    """The set A_y = {x1 + x2 <= y} inside the unit square, for y < 1 and y > 1 (Example 2.48)."""
    fig, axes = common.panel_grid(1, 2, size=(2.9, 2.9))
    for ax, y in zip(axes[0], (0.6, 1.4)):
        ax.plot([0, 1, 1, 0, 0], [0, 0, 1, 1, 0], color="black", lw=1)
        if y <= 1:
            poly = [(0, 0), (y, 0), (0, y)]
            pts = [(y, 0), (0, y)]
            labs = ["$(y,0)$", "$(0,y)$"]
        else:
            poly = [(0, 0), (1, 0), (1, y - 1), (y - 1, 1), (0, 1)]
            pts = [(1, y - 1), (y - 1, 1)]
            labs = ["$(1,y-1)$", "$(y-1,1)$"]
        ax.fill(*zip(*poly), color=GREY, alpha=0.6, lw=0)
        ax.plot(*zip(*pts), "o", color="black", ms=4)
        for (px, py), lab in zip(pts, labs):
            ax.annotate(lab, (px, py), textcoords="offset points", xytext=(4, 4) if px < 1 else (-8, 8),
                        ha="left" if px < 1 else "right", fontsize=8.5)
        area = y * y / 2 if y <= 1 else 1 - (2 - y) ** 2 / 2
        ax.set_title("$y=%.1f$: area $%.2f$" % (y, area))
        ax.set_xlim(-0.05, 1.12)
        ax.set_ylim(-0.05, 1.12)
        ax.set_aspect("equal")
        ax.set_xticks([0, 1])
        ax.set_yticks([0, 1])
        ax.set_xlabel("$x_1$")
        ax.set_ylabel("$x_2$")
    fig.tight_layout()
    savefig(fig, CH, "fig2-6", out_dir)


def fig_2_s1(out_dir=None):
    """Exercise 2.2: the cdf of P(X=2)=P(X=3)=1/10, P(X=5)=8/10."""
    fig, ax = common.plt.subplots(figsize=(4.6, 3.0))
    _step_cdf(ax, [2, 3, 5], [0.1, 0.2, 1.0], 0.5, 6.5)
    ax.axvline(4.8, color=GREY, lw=0.8, ls="--")
    ax.text(4.75, 0.5, "$x=4.8$", ha="right", fontsize=9, color=GREY)
    ax.set_xlim(0.5, 6.5)
    ax.set_ylim(-0.04, 1.08)
    ax.set_xticks([1, 2, 3, 4, 5, 6])
    ax.set_yticks([0, 0.1, 0.2, 0.5, 1])
    ax.set_xlabel("$x$")
    ax.set_ylabel("$F(x)$")
    savefig(fig, CH, "fig2-S1", out_dir)


def fig_2_s2(out_dir=None):
    """The cdf method: Examples 2.46, 2.47 and Exercise 2.4(b) against simulation."""
    rng = np.random.default_rng(246)
    n = 20000
    fig, axes = common.panel_grid(1, 3, size=(3.1, 2.6))
    # Example 2.46: X ~ Exp(1), Y = log X
    y = np.log(rng.exponential(1.0, n))
    g = np.linspace(-7, 2.5, 400)
    ax = axes[0, 0]
    ax.hist(y, bins=60, range=(-7, 2.5), density=True, color=BLUE, alpha=0.3)
    ax.plot(g, np.exp(g - np.exp(g)), color=BLUE)
    ax.set_title(r"Ex. 2.46: $Y=\log X$, $X\sim$Exp(1)")
    ax.set_xlabel("$y$")
    # Example 2.47: X ~ Uniform(-1, 3), Y = X^2
    y = rng.uniform(-1, 3, n) ** 2
    g = np.linspace(0.005, 9, 600)
    ax = axes[0, 1]
    ax.hist(y, bins=90, range=(0, 9), density=True, color=GREEN, alpha=0.3)
    ax.plot(g, np.where(g < 1, 1 / (4 * np.sqrt(g)), 1 / (8 * np.sqrt(g))), color=GREEN)
    ax.set_ylim(0, 1.2)
    ax.set_title(r"Ex. 2.47: $Y=X^2$, $X\sim$U$(-1,3)$")
    ax.set_xlabel("$y$")
    # Exercise 2.4(b): Y = 1/X
    u = rng.uniform(size=n)
    x = np.where(u < 0.25, 4 * u, 3 + (u - 0.25) * 8 / 3)
    y = 1 / x
    ax = axes[0, 2]
    ax.hist(y, bins=np.r_[np.linspace(0.2, 1 / 3, 9), np.linspace(1, 6, 51)], density=True, color=PURPLE, alpha=0.3)
    g1 = np.linspace(0.2, 1 / 3, 50)
    g2 = np.linspace(1.0, 6, 300)
    ax.plot(g1, 3 / (8 * g1 ** 2), color=PURPLE)
    ax.plot(g2, 1 / (4 * g2 ** 2), color=PURPLE)
    ax.set_yscale("log")
    ax.set_xlim(0, 6)
    ax.set_ylim(0.005, 20)
    ax.set_title(r"Ex. 2.4(b): $Y=1/X$ (log scale)")
    ax.set_xlabel("$y$")
    fig.tight_layout()
    savefig(fig, CH, "fig2-S2", out_dir)


def fig_2_s3(out_dir=None):
    """Exercise 2.13: Y = e^X with X ~ N(0,1), density against 10,000 simulated values."""
    rng = np.random.default_rng(213)
    y = np.exp(rng.standard_normal(10000))
    g = np.linspace(1e-3, 8, 800)
    fy = normal_pdf(np.log(g)) / g
    fig, ax = common.plt.subplots(figsize=(4.8, 3.1))
    ax.hist(y, bins=np.arange(0, 8.05, 0.1), density=True, color=BLUE, alpha=0.3,
            label="histogram of $e^{x_i}$, $n=10{,}000$")
    ax.plot(g, fy, color=RED, label=r"$f_Y(y)=\phi(\log y)/y$")
    ax.set_xlim(0, 8)
    ax.set_xlabel("$y$")
    ax.set_ylabel("density")
    ax.legend(frameon=False)
    savefig(fig, CH, "fig2-S3", out_dir)


def fig_2_s4(out_dir=None):
    """Exercise 2.15: an Exp(beta) generator from uniforms, and the probability integral transform."""
    beta = 2.0
    u = js_uniforms(INV_SEED, 10000)
    x = -beta * np.log1p(-u)
    fig, axes = common.panel_grid(1, 2, size=(3.4, 2.7))
    ax = axes[0, 0]
    ax.hist(x, bins=np.arange(0, 16.1, 0.4), density=True, color=BLUE, alpha=0.3, label=r"$-\beta\log(1-U_i)$")
    g = np.linspace(0, 16, 400)
    ax.plot(g, np.exp(-g / beta) / beta, color=RED, label=r"Exp($\beta$) density")
    ax.set_title(r"$X=F^{-1}(U)$, $\beta=2$, $n=10{,}000$")
    ax.set_xlabel("$x$")
    ax.legend(frameon=False, fontsize=8)
    ax = axes[0, 1]
    rng = np.random.default_rng(215)
    xg = rng.gamma(3.0, 1.0, 10000)
    ax.hist(stats.gamma.cdf(xg, 3.0), bins=20, range=(0, 1), density=True, color=GREEN, alpha=0.35)
    ax.axhline(1, color=RED)
    ax.set_ylim(0, 1.5)
    ax.set_title(r"$F(X)$ for $X\sim$Gamma(3,1)")
    ax.set_xlabel("$F(x)$")
    fig.tight_layout()
    savefig(fig, CH, "fig2-S4", out_dir)


def fig_2_s5(out_dir=None):
    """Sums of uniforms by convolution (Example 2.48 onward) and the max/min of exponentials."""
    fig, axes = common.panel_grid(1, 2, size=(3.5, 2.8))
    ax = axes[0, 0]
    cols = [GREY, BLUE, GREEN, RED]
    for n, c in zip((1, 2, 3, 12), cols):
        h, o, laws = sum_lattice("unif", None, n)
        lo, p = laws[-1]
        v = (lo + np.arange(len(p)) + n * o) * h
        s = np.linspace(0, n, 600)
        ax.plot(s / n, n * irwin_hall_pdf(s, n), color=c, lw=1.6, label="$n=%d$" % n)
        ax.plot(v[::max(1, len(v) // 40)] / n, n * p[::max(1, len(v) // 40)] / h, ".", color=c, ms=3)
    ax.set_xlabel(r"$\bar x=s/n$")
    ax.set_ylabel(r"density of $S_n/n$")
    ax.set_title("sums of $n$ uniforms: exact (lines), convolution (dots)", fontsize=9)
    ax.legend(frameon=False, fontsize=8)
    ax = axes[0, 1]
    beta, n = 1.0, 5
    g = np.linspace(0, 6, 400)
    f = lambda t: np.exp(-t / beta) / beta
    F = lambda t: 1 - np.exp(-t / beta)
    ax.plot(g, f(g), color=GREY, label="one Exp(1)")
    ax.plot(g, max_pdf(g, n, f, F), color=RED, label="max of 5")
    ax.plot(g, min_pdf(g, n, f, F), color=BLUE, label="min of 5")
    rng = np.random.default_rng(221)
    X = rng.exponential(beta, (20000, n))
    ax.hist(X.max(1), bins=60, range=(0, 6), density=True, color=RED, alpha=0.2)
    ax.hist(X.min(1), bins=60, range=(0, 6), density=True, color=BLUE, alpha=0.2)
    ax.set_xlim(0, 6)
    ax.set_xlabel("$y$")
    ax.set_title("maximum and minimum of 5 exponentials", fontsize=9)
    ax.legend(frameon=False, fontsize=8)
    fig.tight_layout()
    savefig(fig, CH, "fig2-S5", out_dir)


MVN_MU = np.array([1.0, 2.0])
MVN_S = np.array([[2.0, 1.2], [1.2, 1.0]])


def fig_2_s6(out_dir=None):
    """Bivariate Normal: X = mu + Sigma^(1/2) Z, a conditional slice and the chi-squared law of V."""
    rng = np.random.default_rng(243)
    X = mvn_sample(MVN_MU, MVN_S, 40000, rng)
    fig, axes = common.panel_grid(1, 2, size=(3.4, 2.9))
    ax = axes[0, 0]
    ax.plot(X[:4000, 0], X[:4000, 1], ".", color=BLUE, ms=1.5, alpha=0.35, rasterized=True)
    for c in (1, 2):
        ex, ey = common.ellipse_xy(MVN_MU, MVN_S, nsd=c)
        ax.plot(ex, ey, color=BLUE, lw=1)
    xa = 2.5
    m, v = mvn_conditional(MVN_MU, MVN_S, [0], [xa])
    sl = np.abs(X[:, 0] - xa) < 0.05
    ax.plot(X[sl, 0][:300], X[sl, 1][:300], ".", color=RED, ms=2.5, rasterized=True)
    xs = np.linspace(-3, 5, 2)
    ax.plot(xs, MVN_MU[1] + MVN_S[1, 0] / MVN_S[0, 0] * (xs - MVN_MU[0]), color=RED, lw=1, ls="--")
    ax.set_xlim(-3.5, 5.5)
    ax.set_ylim(-1.2, 5.2)
    ax.set_xlabel("$x_1$")
    ax.set_ylabel("$x_2$")
    ax.set_title(r"$X=\mu+\Sigma^{1/2}Z$; slice $|x_1-2.5|<0.05$", fontsize=9)
    ax = axes[0, 1]
    ax.hist(X[sl, 1], bins=25, density=True, color=RED, alpha=0.3, label="$x_2$ in the slice")
    g = np.linspace(0, 5, 300)
    ax.plot(g, normal_pdf(g, m[0], math.sqrt(v[0, 0])), color=RED, label="Theorem 2.44(2)")
    d = X - MVN_MU
    V = np.einsum("ij,jk,ik->i", d, np.linalg.inv(MVN_S), d)
    ins = ax.inset_axes([0.64, 0.5, 0.34, 0.36])
    ins.hist(V, bins=40, range=(0, 10), density=True, color=GREEN, alpha=0.35)
    gg = np.linspace(0.01, 10, 200)
    ins.plot(gg, chi2_pdf(gg, 2), color=GREEN)
    ins.text(0.95, 0.9, r"$V\sim\chi^2_2$", transform=ins.transAxes, ha="right", va="top", fontsize=8)
    ins.tick_params(labelsize=6)
    ax.set_xlabel("$x_2$")
    ax.legend(frameon=False, fontsize=7.5, loc="upper left")
    fig.tight_layout()
    savefig(fig, CH, "fig2-S6", out_dir)


# =========================================================================== demo data
def export_demo_data():
    """The nerve data for the inverse-cdf demonstration (799 waiting times, seconds)."""
    os.makedirs(DATA_OUT, exist_ok=True)
    x = nerve_times()
    out = dict(note="Waiting times (seconds) between 799 successive pulses along a nerve fibre "
                    "(Cox and Lewis 1966), the data set nerve.dat of Wasserman (2004), from "
                    "https://www.stat.cmu.edu/~larry/all-of-statistics/", x=[round(float(v), 2) for v in x])
    path = os.path.join(DATA_OUT, "ch02-nerve.json")
    with open(path, "w") as f:
        json.dump(out, f, separators=(",", ":"))
    print("wrote", os.path.relpath(path, os.getcwd()))


def fig_data(out_dir=None):
    """Export the demonstration data (no figure)."""
    export_demo_data()


FIGURES = {"2.1": fig_2_1, "2.2": fig_2_2, "2.3": fig_2_3, "2.4": fig_2_4, "2.5": fig_2_5, "2.6": fig_2_6,
           "2.S1": fig_2_s1, "2.S2": fig_2_s2, "2.S3": fig_2_s3, "2.S4": fig_2_s4, "2.S5": fig_2_s5,
           "2.S6": fig_2_s6, "data": fig_data}

if __name__ == "__main__":
    common.run(FIGURES, CH)
