kernelmix 0.3.0__py3-none-any.whl

kernelmix/_kernel.py

@@ -0,0 +1,132 @@
+"""Dense Gaussian kernels and conditional latent-function moments."""
+import numpy as np
+from scipy.linalg import cho_solve
+
+
+def _matrix(value, name):
+    a = np.asarray(value, dtype=float)
+    if a.ndim != 2 or not np.isfinite(a).all() or not a.shape[0] or not a.shape[1]:
+        raise ValueError(f'{name} must be a nonempty finite matrix')
+    return a
+
+
+def gaussian_kernel(Z1, Z2=None, r=None):
+    """Return the Gaussian kernel between rows of Z1 and Z2.
+
+    For exposure profiles z and z', the kernel is
+    exp{-sum_m r_m * (z_m - z'_m)**2}. Each nonnegative r_m controls how much
+    exposure m changes similarity. If all r_m are zero, every kernel entry is one.
+    Inputs are used directly, without training standardization.
+    """
+    a = _matrix(Z1, 'Z1')
+    b = a if Z2 is None else _matrix(Z2, 'Z2')
+    if a.shape[1] != b.shape[1]:
+        raise ValueError('kernel inputs must have equal column counts')
+    weights = np.ones(a.shape[1]) if r is None else np.asarray(r, dtype=float)
+    if weights.shape != (a.shape[1],) or not np.isfinite(weights).all() or (weights < 0).any():
+        raise ValueError('r must be a finite nonnegative vector, one value per exposure')
+    # Accumulation avoids allocating an n1*n2*M tensor; direct differences
+    # avoid cancellation from the squared-norm identity for near-duplicate rows.
+    distance = np.zeros((len(a), len(b)))
+    with np.errstate(over='ignore', invalid='ignore'):
+        for j in np.flatnonzero(weights):
+            distance += weights[j] * np.square(a[:, j, None] - b[None, :, j])
+        kernel = np.exp(-distance)
+    if not np.isfinite(kernel).all():
+        raise ValueError('kernel calculation overflowed; rescale inputs')
+    return kernel
+
+
+def _cluster_codes(value, n, name):
+    codes = np.asarray(value)
+    if (codes.shape != (n,) or not np.issubdtype(codes.dtype, np.integer)
+            or (codes < 0).any()):
+        raise ValueError(f'{name} must be a nonnegative integer vector with one entry per row')
+    return codes
+
+
+def covariance_components(Z, r, lambda_, *, cluster_codes=None, lambda_cluster=None):
+    """Return kernel, marginal covariance and lower Cholesky, without jitter.
+
+    Covariance is I + lambda*K, plus lambda_cluster*J when cluster codes are
+    supplied, where J marks pairs of observations in the same cluster.
+    """
+    if not np.isscalar(lambda_) or not np.isfinite(lambda_) or lambda_ <= 0:
+        raise ValueError('lambda must be finite and positive')
+    kernel = gaussian_kernel(Z, r=r)
+    covariance = lambda_ * kernel
+    covariance.flat[::len(kernel) + 1] += 1.0
+    if cluster_codes is not None:
+        codes = _cluster_codes(cluster_codes, len(kernel), 'cluster_codes')
+        if (not np.isscalar(lambda_cluster) or not np.isfinite(lambda_cluster)
+                or lambda_cluster <= 0):
+            raise ValueError('lambda_cluster must be finite and positive for clustered covariance')
+        covariance += lambda_cluster * (codes[:, None] == codes[None, :])
+    elif lambda_cluster is not None:
+        raise ValueError('lambda_cluster requires cluster_codes')
+    if not np.isfinite(covariance).all():
+        raise ValueError('covariance overflowed')
+    try:
+        lower = np.linalg.cholesky(covariance)
+    except np.linalg.LinAlgError as exc:
+        raise np.linalg.LinAlgError('marginal covariance lost positive definiteness at floating-point precision; rescale or reduce variance amplitudes') from exc
+    return kernel, covariance, lower
+
+
+def psd_factor(covariance):
+    """Eigenfactor for PSD draws; clip roundoff only, reject real indefiniteness."""
+    value = np.asarray(covariance, dtype=float)
+    if value.ndim != 2 or value.shape[0] != value.shape[1] or not np.isfinite(value).all():
+        raise ValueError('covariance must be a finite square matrix')
+    value = (value + value.T) / 2
+    eig, vectors = np.linalg.eigh(value)
+    tolerance = 100 * np.finfo(float).eps * max(1, len(value)) * max(1.0, np.max(np.abs(eig), initial=0))
+    if np.min(eig, initial=0) < -tolerance:
+        raise np.linalg.LinAlgError('conditional covariance is materially indefinite')
+    return vectors * np.sqrt(np.maximum(eig, 0))
+
+
+def conditional_h(Z, Znew, y, X, beta, r, lambda_, sigma2, *,
+                  cluster_codes=None, lambda_cluster=None, cluster_new_codes=None):
+    """Conditional h moments, or h+u when ``cluster_new_codes`` is supplied.
+
+    New nonnegative integer codes share a random intercept exactly when equal.
+    Codes absent from training have zero prior cross covariance with training.
+    Omitting new codes conditions on clustered training but predicts h alone.
+    """
+    z = _matrix(Z, 'Z')
+    new = _matrix(Znew, 'Znew')
+    outcome, design, coefficients = np.asarray(y, dtype=float), np.asarray(X, dtype=float), np.asarray(beta, dtype=float)
+    if outcome.shape != (len(z),) or design.ndim != 2 or design.shape[0] != len(z) or coefficients.shape != (design.shape[1],):
+        raise ValueError('y, X, and beta have incompatible shapes')
+    if any(not np.isfinite(v).all() for v in (outcome, design, coefficients)):
+        raise ValueError('y, X, and beta must be finite')
+    if not np.isscalar(sigma2) or not np.isfinite(sigma2) or sigma2 <= 0:
+        raise ValueError('sigma2 must be finite and positive')
+    _, _, lower = covariance_components(z, r, lambda_, cluster_codes=cluster_codes,
+                                         lambda_cluster=lambda_cluster)
+    cross = gaussian_kernel(new, z, r)
+    if cluster_new_codes is None:
+        # Preserve the original no-cluster arithmetic and seed behavior.
+        solved = cho_solve((lower, True), cross.T, check_finite=False)
+        mean = lambda_ * cross @ cho_solve((lower, True), outcome - design @ coefficients, check_finite=False)
+        covariance = sigma2 * lambda_ * (gaussian_kernel(new, r=r) - lambda_ * cross @ solved)
+    else:
+        if cluster_codes is None:
+            raise ValueError('cluster_new_codes requires clustered training data')
+        train_codes = _cluster_codes(cluster_codes, len(z), 'cluster_codes')
+        new_codes = _cluster_codes(cluster_new_codes, len(new), 'cluster_new_codes')
+        cross = lambda_ * cross + lambda_cluster * (new_codes[:, None] == train_codes[None, :])
+        prior = (lambda_ * gaussian_kernel(new, r=r)
+                 + lambda_cluster * (new_codes[:, None] == new_codes[None, :]))
+        solved = cho_solve((lower, True), cross.T, check_finite=False)
+        mean = cross @ cho_solve((lower, True), outcome - design @ coefficients, check_finite=False)
+        covariance = sigma2 * (prior - cross @ solved)
+    covariance = (covariance + covariance.T) / 2
+    # Check here as well as at sampling, so moment-only prediction cannot hide
+    # a materially indefinite result. Retain eigen-projected roundoff repair.
+    factor = psd_factor(covariance)
+    covariance = factor @ factor.T
+    if not np.isfinite(mean).all() or not np.isfinite(covariance).all():
+        raise FloatingPointError('conditional moments overflowed')
+    return mean, covariance

kernelmix/_likelihoods.py

@@ -0,0 +1,151 @@
+"""Exact count and piecewise-exponential survival log likelihoods.
+
+Count predictors are log means (including any offset). Survival predictors
+are log relative hazards. All likelihoods retain parameter-dependent
+normalization terms; nonfinite candidate predictors return minus infinity.
+"""
+
+import numpy as np
+from scipy.special import betaln, gammaln
+
+
+def _vector(value, name, n=None):
+    a = np.asarray(value, dtype=float)
+    if a.ndim != 1 or (n is not None and len(a) != n):
+        raise ValueError(f'{name} must be a vector with one value per observation')
+    return a
+
+
+def _counts(y):
+    values = _vector(y, 'y')
+    if not np.isfinite(values).all() or np.any(values < 0) or np.any(values != np.floor(values)):
+        raise ValueError('counts must be finite nonnegative integers')
+    return values
+
+
+def _finite_sum(value):
+    total = float(np.sum(value))
+    return total if np.isfinite(total) else -np.inf
+
+
+def poisson_loglik(y, eta):
+    """Sum log Poisson PMFs for a log mean, including log-factorials."""
+    y = _counts(y)
+    eta = _vector(eta, 'eta', len(y))
+    if not np.isfinite(eta).all():
+        return -np.inf
+    with np.errstate(over='ignore', invalid='ignore', under='ignore'):
+        return _finite_sum(y * eta - np.exp(eta) - gammaln(y + 1))
+
+
+def negative_binomial_loglik(y, eta, dispersion):
+    """NB2 log PMF with mean exp(eta) and variance mu + mu**2/dispersion.
+
+    The beta-function identity avoids subtracting two large log gamma terms.
+    Log-add-exp expressions avoid exponentiating the count mean.
+    """
+    y = _counts(y)
+    eta = _vector(eta, 'eta', len(y))
+    if not np.isscalar(dispersion) or not np.isfinite(dispersion) or dispersion <= 0:
+        return -np.inf
+    if not np.isfinite(eta).all():
+        return -np.inf
+    log_d = np.log(dispersion)
+    with np.errstate(over='ignore', invalid='ignore', under='ignore', divide='ignore'):
+        normalizer = -betaln(dispersion, y + 1) - np.logaddexp(log_d, np.log(y))
+        terms = (normalizer - dispersion * np.logaddexp(0, eta - log_d)
+                 - y * np.logaddexp(0, log_d - eta))
+        return _finite_sum(terms)
+
+
+def _breaks(value):
+    cuts = np.asarray(value, dtype=float)
+    if cuts.ndim != 1 or not np.isfinite(cuts).all() or np.any(cuts <= 0) or np.any(np.diff(cuts) <= 0):
+        raise ValueError('baseline_breaks must be finite positive strictly increasing cutpoints')
+    return cuts.copy()
+
+
+def interval_durations(times, breaks):
+    """Time spent in intervals (0,b1], ..., (bJ,infinity).
+
+    Zero times are allowed for prediction. Times are never sorted or clipped.
+    """
+    times = _vector(times, 'times')
+    if not np.isfinite(times).all() or np.any(times < 0):
+        raise ValueError('times must be finite and nonnegative')
+    cuts = _breaks(breaks)
+    if 8 * len(times) * (len(cuts) + 1) > 512 * 1024**2:
+        raise ValueError('interval durations exceed the 512 MiB allocation budget')
+    left = np.concatenate(([0.], cuts))
+    right = np.concatenate((cuts, [np.inf]))
+    return np.maximum(np.minimum(times[:, None], right) - left, 0.)
+
+
+def prepare_survival(time, event, baseline_breaks=None):
+    """Create interval data; boundary events belong to the left interval.
+
+    Default cutpoints are unique event-time deciles below the largest retained
+    observed time. No observed events gives one exponential interval.
+    """
+    time = _vector(time, 'time')
+    event = _vector(event, 'event', len(time))
+    if not len(time) or not np.isfinite(time).all() or np.any(time <= 0):
+        raise ValueError('survival times must be positive and finite')
+    if not np.isfinite(event).all() or not np.isin(event, [0, 1]).all():
+        raise ValueError('event must contain only zero and one')
+    if baseline_breaks is None:
+        events = time[event == 1]
+        cuts = np.unique(np.quantile(events, np.arange(1, 10) / 10)) if len(events) else np.empty(0)
+        cuts = cuts[(cuts > 0) & (cuts < time.max())]
+    else:
+        cuts = _breaks(baseline_breaks)
+    return dict(event=event.astype(int), baseline_breaks=cuts,
+                durations=interval_durations(time, cuts),
+                event_bin=np.searchsorted(cuts, time, side='left'))
+
+
+def _survival_arrays(event, event_bin, durations, eta, baseline_hazard=None):
+    event = _vector(event, 'event')
+    eta = _vector(eta, 'eta', len(event))
+    bins = np.asarray(event_bin)
+    durations = np.asarray(durations, dtype=float)
+    if durations.ndim != 2 or durations.shape[0] != len(event) or durations.shape[1] < 1:
+        raise ValueError('durations must have one row per observation and one column per interval')
+    if not np.isfinite(durations).all() or np.any(durations < 0):
+        raise ValueError('durations must be finite and nonnegative')
+    if not np.isfinite(event).all() or not np.isin(event, [0, 1]).all():
+        raise ValueError('event must contain only zero and one')
+    if (bins.shape != event.shape or not np.issubdtype(bins.dtype, np.integer)
+            or np.any(bins < 0) or np.any(bins >= durations.shape[1])):
+        raise ValueError('event_bin must index one valid interval per observation')
+    if baseline_hazard is not None:
+        hazard = _vector(baseline_hazard, 'baseline_hazard', durations.shape[1])
+        if not np.isfinite(hazard).all() or np.any(hazard <= 0):
+            raise ValueError('baseline_hazard must be positive and finite')
+    return event, bins, durations, eta
+
+
+def survival_loglik(event, event_bin, durations, eta, baseline_hazard):
+    """Full right-censored piecewise PH log likelihood, not partial likelihood."""
+    event, bins, durations, eta = _survival_arrays(event, event_bin, durations, eta, baseline_hazard)
+    if not np.isfinite(eta).all():
+        return -np.inf
+    hazard = np.asarray(baseline_hazard, dtype=float)
+    with np.errstate(over='ignore', invalid='ignore', under='ignore'):
+        terms = event * (np.log(hazard[bins]) + eta) - np.exp(eta) * (durations @ hazard)
+        return _finite_sum(terms)
+
+
+def baseline_posterior_parameters(event, event_bin, durations, eta, shape, rate):
+    """Independent conditional Gamma shapes/rates for baseline hazard Gibbs draws."""
+    event, bins, durations, eta = _survival_arrays(event, event_bin, durations, eta)
+    if not np.isfinite(shape) or not np.isfinite(rate) or min(shape, rate) <= 0:
+        raise ValueError('baseline Gamma shape and rate must be positive and finite')
+    if not np.isfinite(eta).all():
+        raise FloatingPointError('nonfinite survival predictor in baseline update')
+    counts = np.bincount(bins, weights=event, minlength=durations.shape[1])
+    with np.errstate(over='ignore', invalid='ignore', under='ignore'):
+        rates = rate + durations.T @ np.exp(eta)
+    if not np.isfinite(rates).all() or np.any(rates <= 0):
+        raise FloatingPointError('baseline Gamma rates overflowed; rescale times or predictors')
+    return shape + counts, rates

kernelmix/_prediction.py

@@ -0,0 +1,43 @@
+"""Conditional GP calculations for explicitly saved latent functions."""
+import numpy as np
+
+from ._kernel import gaussian_kernel, psd_factor
+
+
+def _check_support(h, basis):
+    residual = h - basis @ (basis.T @ h)
+    if np.max(np.abs(residual), initial=0) > 1e-8 * max(1., np.max(np.abs(h), initial=0)):
+        raise ValueError('saved h lies outside the numerical training-kernel support')
+
+
+def conditional_saved_h(training, new, h, r, amplitude):
+    """Condition a Gaussian process on saved training h, including PSD kernels.
+
+    Eigenvalues at most 100*n*machine_epsilon*max(1, largest_eigenvalue)
+    define numerical null directions, where n is the training row count.
+    No diagonal jitter is added. Observed training profiles
+    retain their saved h exactly. This is floating-point rank handling, not a
+    low-rank approximation selected for computation speed.
+    """
+    kernel = gaussian_kernel(training, r=r)
+    eig, vectors = np.linalg.eigh(kernel)
+    tolerance = 100 * len(kernel) * np.finfo(float).eps * max(1., eig.max())
+    if eig.min() < -tolerance:
+        raise np.linalg.LinAlgError('training kernel is materially indefinite')
+    keep = eig > tolerance
+    basis = vectors[:, keep]
+    _check_support(h, basis)
+    cross = gaussian_kernel(new, training, r=r)
+    projected = cross @ basis
+    mean = (projected / eig[keep]) @ (basis.T @ h)
+    covariance = amplitude * (gaussian_kernel(new, r=r) - (projected/eig[keep]) @ projected.T)
+    covariance = (covariance + covariance.T)/2
+    active = np.asarray(r) > 0
+    for j, profile in enumerate(new):
+        matches = np.flatnonzero(np.all(training[:, active] == profile[active], axis=1))
+        if len(matches):
+            mean[j] = h[matches[0]]
+            covariance[j, :] = 0
+            covariance[:, j] = 0
+    factor = psd_factor(covariance)
+    return mean, factor @ factor.T

kernelmix/_structure.py

@@ -0,0 +1,326 @@
+"""Gaussian block correlations, log-variance scaling and residual prediction.
+
+Correlation operates only within observation clusters. The covariance is
+sigma2 * D R D, where D has diagonal exp(log_variance/2). No diagonal jitter
+is added. Conditional prediction returns a residual mean and covariance;
+the caller controls random draws.
+"""
+
+import numpy as np
+from scipy.linalg import cho_solve, solve_triangular
+
+_LIMIT = 512 * 1024**2
+
+
+def _budget(elements):
+    if 8 * int(elements) > _LIMIT:
+        raise ValueError('Gaussian residual working arrays exceed the 512 MiB budget')
+
+
+def _vector(value, name, n=None):
+    result = np.asarray(value, dtype=float)
+    if result.ndim != 1 or (n is not None and len(result) != n) or not np.isfinite(result).all():
+        raise ValueError(f'{name} must be a finite vector with one entry per observation')
+    return result
+
+
+def _codes(value, name, n=None):
+    codes = np.asarray(value)
+    if (codes.ndim != 1 or (n is not None and len(codes) != n)
+            or not np.issubdtype(codes.dtype, np.integer) or np.any(codes < 0)):
+        raise ValueError(f'{name} must be a nonnegative integer cluster-code vector')
+    return codes
+
+
+def _kind(kind, matrix):
+    if isinstance(kind, np.ndarray):
+        if matrix is not None:
+            raise ValueError('supply a correlation matrix only once')
+        matrix, kind = kind, 'fixed'
+    if matrix is not None:
+        if kind not in (None, 'fixed', 'matrix'):
+            raise ValueError('matrix cannot be combined with a parametric correlation')
+        kind = 'fixed'
+    if kind in (None, 'independent'):
+        return None, matrix
+    if kind not in ('ar1', 'exponential', 'fixed', 'matrix'):
+        raise ValueError('correlation kind must be ar1, exponential, fixed or None')
+    return 'fixed' if kind == 'matrix' else kind, matrix
+
+
+def _parameter(kind, parameter):
+    if kind not in ('ar1', 'exponential'):
+        if parameter is not None:
+            raise ValueError('correlation parameter applies only to ar1 or exponential')
+        return None
+    if (isinstance(parameter, (bool, np.bool_)) or not np.isscalar(parameter)
+            or not np.isfinite(parameter)):
+        raise ValueError('correlation parameter must be finite')
+    if kind == 'ar1' and not -1 < parameter < 1:
+        raise ValueError('AR1 correlation must lie strictly between -1 and one')
+    if kind == 'exponential' and parameter <= 0:
+        raise ValueError('exponential correlation range must be positive')
+    return float(parameter)
+
+
+def _times(times, n, kind, name):
+    times = _vector(times, name, n)
+    if kind == 'ar1' and np.any(times != np.floor(times)):
+        raise ValueError('AR1 observation times must be integer valued')
+    return times
+
+
+def _parametric(a, b, kind, parameter):
+    with np.errstate(over='ignore', invalid='ignore', under='ignore'):
+        distance = np.abs(a[:, None] - b[None, :])
+        if kind == 'ar1':
+            result = np.power(parameter, distance)
+        else:
+            result = np.exp(-distance / parameter)
+    if not np.isfinite(result).all():
+        raise FloatingPointError('residual correlation calculation overflowed')
+    return result
+
+
+def _correlation_matrix(value, n, codes, name, *, positive_definite=True):
+    matrix = np.asarray(value, dtype=float)
+    if matrix.shape != (n, n) or not np.isfinite(matrix).all():
+        raise ValueError(f'{name} must be a finite square matrix matching its observations')
+    _budget(4*n*n)
+    if not np.allclose(matrix, matrix.T, rtol=0, atol=1e-12):
+        raise ValueError(f'{name} must be symmetric')
+    if not np.allclose(np.diag(matrix), 1., rtol=0, atol=1e-12):
+        raise ValueError(f'{name} must have unit diagonal')
+    if np.any(np.abs(matrix) > 1+1e-12):
+        raise ValueError(f'{name} entries must lie between minus one and one')
+    # Check block separation without allocating a second n-by-n identity mask.
+    for group in np.unique(codes):
+        rows = np.flatnonzero(codes == group)
+        other = np.flatnonzero(codes != group)
+        if len(other) and np.any(np.abs(matrix[np.ix_(rows, other)]) > 1e-12):
+            raise ValueError(f'{name} must be zero between clusters')
+        block = (matrix[np.ix_(rows, rows)] + matrix[np.ix_(rows, rows)].T) / 2
+        if positive_definite:
+            try:
+                np.linalg.cholesky(block)
+            except np.linalg.LinAlgError as exc:
+                raise ValueError(f'{name} must be positive definite within each cluster') from exc
+        else:
+            _psd(block, name)
+    return matrix
+
+
+def _psd(covariance, name):
+    covariance = (covariance + covariance.T) / 2
+    if not np.isfinite(covariance).all():
+        raise FloatingPointError(f'{name} is nonfinite')
+    if not len(covariance):
+        return covariance
+    values, vectors = np.linalg.eigh(covariance)
+    scale = max(1., float(np.max(np.abs(values), initial=0)))
+    tolerance = 100 * len(covariance) * np.finfo(float).eps * scale
+    if values.min(initial=0) < -tolerance:
+        raise ValueError(f'{name} is materially indefinite')
+    # Remove negative roundoff only; retain legitimate small positive variance.
+    return (vectors * np.maximum(values, 0.)) @ vectors.T
+
+
+def correlation_blocks(codes, times=None, kind=None, parameter=None, matrix=None):
+    """Return (indices, R, lower-Cholesky) for each correlated cluster.
+
+    Independent errors use an empty fast path. AR1 requires distinct integer
+    times within each training cluster; exponential correlation requires
+    distinct finite times. A fixed matrix must be positive definite and zero
+    between clusters. Inputs refer to already retained rows.
+    """
+    kind, matrix = _kind(kind, matrix)
+    parameter = _parameter(kind, parameter)
+    if kind is None:
+        return []
+    if codes is None:
+        raise ValueError('residual correlation requires observation clusters')
+    codes = _codes(codes, 'codes')
+    if not len(codes):
+        raise ValueError('correlation requires at least one observation')
+    sizes = [np.count_nonzero(codes == group) for group in np.unique(codes)]
+    _budget(5*sum(int(size)**2 for size in sizes))
+    if kind == 'fixed':
+        if matrix is None:
+            raise ValueError('fixed correlation requires a matrix')
+        matrix = _correlation_matrix(matrix, len(codes), codes, 'matrix')
+    else:
+        times = _times(times, len(codes), kind, 'times')
+    result = []
+    for group in np.unique(codes):
+        indices = np.flatnonzero(codes == group)
+        if kind == 'fixed':
+            block = matrix[np.ix_(indices, indices)].copy()
+        else:
+            local = times[indices]
+            if len(np.unique(local)) != len(local):
+                raise ValueError('duplicate within-cluster times give singular residual correlation')
+            block = _parametric(local, local, kind, parameter)
+        try:
+            lower = np.linalg.cholesky((block + block.T) / 2)
+        except np.linalg.LinAlgError as exc:
+            raise ValueError('within-cluster residual correlation is not positive definite') from exc
+        result.append((indices, block, lower))
+    return result
+
+
+def _standardized_residual(y, eta, sigma2, log_variance):
+    with np.errstate(over='ignore', invalid='ignore', divide='ignore', under='ignore'):
+        residual = y - eta
+        exponent = np.full_like(residual, -np.inf)
+        np.log(np.abs(residual), out=exponent, where=residual != 0)
+        standardized = np.sign(residual) * np.exp(exponent - .5*(np.log(sigma2)+log_variance))
+    return standardized
+
+
+def gaussian_loglik(y, eta, sigma2, log_variance, blocks):
+    """Normalized Gaussian log density with block correlation and log variance.
+
+    Invalid candidate scales/predictors return minus infinity. Covariances are
+    factored as D R D, so large variance ratios do not require a scaled dense
+    covariance factorization. Zero residuals remain zero even at tiny scales.
+    """
+    y = _vector(y, 'y')
+    eta = np.asarray(eta, dtype=float)
+    lv = np.asarray(log_variance, dtype=float)
+    if eta.shape != y.shape or lv.shape != y.shape:
+        raise ValueError('eta and log_variance must have one entry per observation')
+    if (isinstance(sigma2, (bool, np.bool_)) or not np.isscalar(sigma2)
+            or not np.isfinite(sigma2) or sigma2 <= 0
+            or not np.isfinite(eta).all() or not np.isfinite(lv).all()):
+        return -np.inf
+    standardized = _standardized_residual(y, eta, sigma2, lv)
+    if not np.isfinite(standardized).all():
+        return -np.inf
+    assigned = np.zeros(len(y), dtype=bool)
+    quadratic, logdet = 0., 0.
+    with np.errstate(over='ignore', invalid='ignore'):
+        for indices, correlation, lower in blocks:
+            indices = np.asarray(indices)
+            if (indices.ndim != 1 or not np.issubdtype(indices.dtype, np.integer)
+                    or np.any(indices < 0) or np.any(indices >= len(y))
+                    or len(np.unique(indices)) != len(indices) or assigned[indices].any()):
+                raise ValueError('correlation blocks must contain disjoint valid indices')
+            if np.shape(correlation) != (len(indices), len(indices)) or np.shape(lower) != np.shape(correlation):
+                raise ValueError('correlation block factors have incompatible shapes')
+            assigned[indices] = True
+            local = solve_triangular(lower, standardized[indices], lower=True, check_finite=False)
+            quadratic += float(local @ local)
+            logdet += 2*float(np.log(np.diag(lower)).sum())
+        quadratic += float(standardized[~assigned] @ standardized[~assigned])
+        total = -.5*(len(y)*np.log(2*np.pi) + len(y)*np.log(sigma2) + lv.sum() + logdet + quadratic)
+    return float(total) if np.isfinite(total) else -np.inf
+
+
+def residual_prediction(y, eta_train, sigma2, logvar_train, logvar_new,
+                        train_codes, new_codes, train_time, new_time, kind, parameter, rng,
+                        *, matrix=None, cross=None, new_matrix=None, observation=True):
+    """Return joint conditional residual (mean, covariance), without drawing.
+
+    ``cross`` is a new-by-training correlation matrix; ``new_matrix`` is a
+    new-by-new correlation matrix. For fixed training correlations, omitted
+    cross correlations mean independent new residuals. Equal known cluster/time
+    points share the conditioned residual process. ``observation=False`` keeps
+    the conditional mean and returns zero covariance. ``rng`` is accepted for
+    interface consistency and is not consumed.
+    """
+    y = _vector(y, 'y')
+    eta = _vector(eta_train, 'eta_train', len(y))
+    lv_train = _vector(logvar_train, 'logvar_train', len(y))
+    lv_new = _vector(logvar_new, 'logvar_new')
+    if not isinstance(observation, (bool, np.bool_)):
+        raise ValueError('observation must be boolean')
+    if isinstance(sigma2, (bool, np.bool_)) or not np.isscalar(sigma2) or not np.isfinite(sigma2) or sigma2 <= 0:
+        raise ValueError('sigma2 must be finite and positive')
+    n, count = len(y), len(lv_new)
+    _budget(3*count*count + 5*(n+count))
+    kind, matrix = _kind(kind, matrix)
+    parameter = _parameter(kind, parameter)
+    with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+        scale_new = np.exp(.5*(np.log(sigma2)+lv_new))
+    if not np.isfinite(scale_new).all() or np.any(scale_new <= 0):
+        raise FloatingPointError('new residual scales exceed floating-point range')
+    standardized = _standardized_residual(y, eta, sigma2, lv_train)
+    if not np.isfinite(standardized).all():
+        raise FloatingPointError('training standardized residuals exceed floating-point range')
+    mean = np.zeros(count)
+    covariance = np.zeros((count, count))
+    if kind is None:
+        if cross is not None or new_matrix is not None:
+            raise ValueError('custom residual correlation inputs require fixed correlation')
+        if observation:
+            np.fill_diagonal(covariance, scale_new**2)
+            if not np.isfinite(covariance).all():
+                raise FloatingPointError('new residual covariance overflowed')
+        return mean, covariance
+    if train_codes is None or new_codes is None:
+        raise ValueError('correlated prediction requires training and new cluster codes')
+    train_codes = _codes(train_codes, 'train_codes', n)
+    new_codes = _codes(new_codes, 'new_codes', count)
+    training = correlation_blocks(train_codes, train_time, kind, parameter, matrix=matrix)
+    factors = {int(train_codes[indices[0]]): (indices, block, lower) for indices, block, lower in training}
+    stored_elements = 2*sum(len(indices)**2 for indices, _, _ in training)
+    if kind != 'fixed':
+        if cross is not None or new_matrix is not None:
+            raise ValueError('custom correlation matrices require fixed training correlation')
+        train_time = _times(train_time, n, kind, 'train_time')
+        new_time = _times(new_time, count, kind, 'new_time')
+    else:
+        if cross is None:
+            cross = None
+        else:
+            cross = np.asarray(cross, dtype=float)
+            if cross.shape != (count, n) or not np.isfinite(cross).all():
+                raise ValueError('cross must be a finite new-by-training correlation matrix')
+            _budget(stored_elements + 3*count*count + 2*count*n)
+            for code in np.unique(new_codes):
+                rows = np.flatnonzero(new_codes == code)
+                other = np.flatnonzero(train_codes != code)
+                if len(other) and np.any(np.abs(cross[np.ix_(rows, other)]) > 1e-12):
+                    raise ValueError('cross must be zero between different clusters')
+        if new_matrix is not None:
+            new_matrix = _correlation_matrix(new_matrix, count, new_codes, 'new_matrix', positive_definite=False)
+    for code in np.unique(new_codes):
+        rows = np.flatnonzero(new_codes == code)
+        size = len(rows)
+        if int(code) in factors:
+            columns, _, lower = factors[int(code)]
+        else:
+            columns, lower = np.empty(0, dtype=int), None
+        _budget(stored_elements + 3*count*count + 10*(len(columns)+size)**2)
+        if kind == 'fixed':
+            prior = np.eye(size) if new_matrix is None else new_matrix[np.ix_(rows, rows)]
+            shared = np.zeros((size, len(columns))) if cross is None else cross[np.ix_(rows, columns)]
+        else:
+            prior = _parametric(new_time[rows], new_time[rows], kind, parameter)
+            shared = _parametric(new_time[rows], train_time[columns], kind, parameter)
+        conditional = prior.copy()
+        if len(columns):
+            whitened = solve_triangular(lower, shared.T, lower=True, check_finite=False)
+            conditional -= whitened.T @ whitened
+            local_mean = shared @ cho_solve((lower, True), standardized[columns], check_finite=False)
+            mean[rows] = scale_new[rows] * local_mean
+        conditional = _psd(conditional, 'joint residual correlation Schur complement')
+        if len(columns):
+            for local_row, row in enumerate(rows):
+                # Correlation exactly one identifies the same standardized residual.
+                # Preserve that identity instead of sampling Schur roundoff.
+                matches = (np.flatnonzero(shared[local_row] == 1.) if kind == 'fixed'
+                           else np.flatnonzero(new_time[row] == train_time[columns]))
+                if len(matches):
+                    mean[row] = scale_new[row] * standardized[columns[matches[0]]]
+                    conditional[local_row, :] = 0.
+                    conditional[:, local_row] = 0.
+        if observation:
+            with np.errstate(over='ignore', invalid='ignore'):
+                local_covariance = scale_new[rows, None] * conditional * scale_new[None, rows]
+            if not np.isfinite(local_covariance).all():
+                raise FloatingPointError('conditional residual covariance overflowed')
+            covariance[np.ix_(rows, rows)] = local_covariance
+    if not np.isfinite(mean).all():
+        raise FloatingPointError('conditional residual mean overflowed')
+    return mean, covariance