Skip to content

calc_model_likelihood

laser.cholera.calc_model_likelihood

Likelihood functions for scoring cholera model fits against observed data.

Translated from calc_model_likelihood.R. Scores model fits using Negative Binomial (NB) time-series log-likelihood per location and outcome (cases, deaths) with a weighted method-of-moments dispersion estimate and a k_min floor.

Optional shape terms are enabled by setting their weight > 0: peak timing (Normal), peak magnitude (log-Normal with adaptive sigma), cumulative progression (NB at cumulative fractions), and Weighted Interval Score (WIS). All weights default to 0.

Shape terms are internally T-normalized so that weight parameters share a common scale: weight=0.25 means the term contributes roughly 25% as much as the NB core.

The peak shape terms in the main function take an explicit epidemic_peaks DataFrame argument (columns iso_code, peak_date, loc_idx) together with date_start / date_stop. Peak rows whose peak_date falls outside [date_start, date_stop] are dropped before index assignment, so out-of-window calendar peaks contribute nothing rather than getting clamped to the simulation endpoints. The legacy helpers calc_multi_peak_timing_ll / calc_multi_peak_magnitude_ll accept the same DataFrame via their epidemic_peaks argument, apply the same in-window filter, and dispatch by iso_code; they do not require the loc_idx column.

Key design decisions:

Indexing: R uses 1-based indices; Python uses 0-based. All peak_indices stored and passed as 0-based. Window slices use [w_start:w_end] with w_end = peak_idx + 15 (exclusive) to match R's (peak_idx-14):(peak_idx+14) inclusive range.

NB distribution: R's dnbinom(x, size=k, mu=mu) → scipy.stats.nbinom.logpmf(x, n=k, p=k/(k+mu)). The p conversion is applied wherever NB distributions are evaluated.

MOSAIC::calc_log_likelihood: Implemented locally as _calc_log_likelihood_nb since it's not in the provided R source.

MOSAIC::epidemic_peaks: Replaced with an explicit pandas DataFrame argument — epidemic_peaks in both the main function and the legacy helpers.

logger module-attribute

logger = getLogger('laser.cholera')

nb_size_from_obs_weighted

nb_size_from_obs_weighted(
    x: ndarray,
    w: ndarray,
    k_min: float = 3,
    k_max: float = 100000.0,
) -> float

Estimate NB dispersion (size) from observed data via weighted method-of-moments.

Uses Bessel-corrected weighted variance (V1² / (V1² − V2) normalisation, where V1 = Σw and V2 = Σw²) to avoid underestimating variance with small or unequal-weight samples.

Parameters:

Name Type Description Default
x ndarray

Observed count time series (1-D array).

required
w ndarray

Non-negative weights, same length as x.

required
k_min float

Minimum dispersion floor. Defaults to 3.

3
k_max float

Maximum dispersion cap. Defaults to 1e5.

100000.0

Returns:

Type Description
float

Estimated NB size parameter k, clipped to [k_min, k_max]. Returns np.inf if

float

fewer than two finite, positive-weight observations exist or if the variance

float

does not exceed the mean (Poisson / sub-Poisson regime).

Source code in src/laser/cholera/calc_model_likelihood.py
def nb_size_from_obs_weighted(
    x: np.ndarray,
    w: np.ndarray,
    k_min: float = 3,
    k_max: float = 1e5,
) -> float:
    """Estimate NB dispersion (size) from observed data via weighted method-of-moments.

    Uses Bessel-corrected weighted variance (V1² / (V1² − V2) normalisation, where
    V1 = Σw and V2 = Σw²) to avoid underestimating variance with small or
    unequal-weight samples.

    Args:
        x: Observed count time series (1-D array).
        w: Non-negative weights, same length as x.
        k_min: Minimum dispersion floor. Defaults to 3.
        k_max: Maximum dispersion cap. Defaults to 1e5.

    Returns:
        Estimated NB size parameter k, clipped to [k_min, k_max]. Returns np.inf if
        fewer than two finite, positive-weight observations exist or if the variance
        does not exceed the mean (Poisson / sub-Poisson regime).
    """
    ok = np.isfinite(x) & np.isfinite(w) & (w > 0)
    if not np.any(ok):
        return np.inf
    x_ok = x[ok]
    w_ok = w[ok]
    sw = float(np.sum(w_ok))
    sw2 = float(np.sum(w_ok**2))
    m = float(np.sum(w_ok * x_ok) / sw)
    denom = sw - sw2 / sw
    if denom > 0:
        v = float(np.sum(w_ok * (x_ok - m) ** 2) / denom)
    else:
        v = float(np.sum(w_ok * (x_ok - m) ** 2) / sw)
    if not (np.isfinite(m) and np.isfinite(v) and m > 0 and v > m):
        return np.inf
    k = (m * m) / (v - m)
    return float(np.clip(k, k_min, k_max))

mask_weights

mask_weights(
    w: ndarray,
    obs_vec: ndarray,
    est_vec: ndarray | None = None,
) -> np.ndarray

Zero out weights where observations or estimates are non-finite.

Parameters:

Name Type Description Default
w ndarray

Weight vector, same length as obs_vec.

required
obs_vec ndarray

Observed values.

required
est_vec ndarray | None

Optional estimated values; non-finite entries also zero out weights.

None

Returns:

Type Description
ndarray

Copy of w with weights zeroed where obs_vec (or est_vec) is non-finite.

Source code in src/laser/cholera/calc_model_likelihood.py
def mask_weights(
    w: np.ndarray,
    obs_vec: np.ndarray,
    est_vec: np.ndarray | None = None,
) -> np.ndarray:
    """Zero out weights where observations or estimates are non-finite.

    Args:
        w: Weight vector, same length as obs_vec.
        obs_vec: Observed values.
        est_vec: Optional estimated values; non-finite entries also zero out weights.

    Returns:
        Copy of w with weights zeroed where obs_vec (or est_vec) is non-finite.
    """
    w2 = w.copy()
    bad = ~np.isfinite(obs_vec)
    if est_vec is not None:
        bad = bad | ~np.isfinite(est_vec)
    if np.any(bad):
        w2[bad] = 0.0
    return w2

weights_obs_row_trivial

weights_obs_row_trivial(
    wobs_row: ndarray | None, obs_vec: ndarray
) -> bool

Decide whether a per-cell confidence-weight row is trivial.

A row is "trivial" (and therefore must route through the unweighted code path for byte identity with the legacy weights_obs_* is None case) when:

  • wobs_row is None, or
  • every cell with a finite observation has wobs_row[i] == 1.0 AND is finite.

A non-finite weight on a finite-obs cell is NOT trivial — it is a real "no confidence" signal that must flow through the mass-preserving path. Non-finite weight cells where the observation is also non-finite are irrelevant because :func:mask_weights already zeroes them out.

Parameters:

Name Type Description Default
wobs_row ndarray | None

Per-cell weights for one location/channel, length matching obs_vec, or None.

required
obs_vec ndarray

Observation row (length T).

required

Returns:

Type Description
bool

True if the unweighted code path is appropriate for this row.

Source code in src/laser/cholera/calc_model_likelihood.py
def weights_obs_row_trivial(
    wobs_row: np.ndarray | None,
    obs_vec: np.ndarray,
) -> bool:
    """Decide whether a per-cell confidence-weight row is trivial.

    A row is "trivial" (and therefore must route through the unweighted code
    path for byte identity with the legacy ``weights_obs_* is None`` case)
    when:

    - ``wobs_row is None``, or
    - every cell with a finite observation has ``wobs_row[i] == 1.0`` AND is
      finite.

    A non-finite weight on a finite-obs cell is NOT trivial — it is a real
    "no confidence" signal that must flow through the mass-preserving path.
    Non-finite weight cells where the observation is also non-finite are
    irrelevant because :func:`mask_weights` already zeroes them out.

    Args:
        wobs_row: Per-cell weights for one location/channel, length matching
            ``obs_vec``, or ``None``.
        obs_vec: Observation row (length T).

    Returns:
        ``True`` if the unweighted code path is appropriate for this row.
    """
    if wobs_row is None:
        return True
    fin = np.isfinite(obs_vec)
    if not np.any(fin):
        return True
    wf = wobs_row[fin]
    return bool(np.all(np.isfinite(wf) & (wf == 1.0)))

weights_obs_effective

weights_obs_effective(
    weights_time: ndarray,
    wobs_row: ndarray,
    obs_vec: ndarray,
    est_vec: ndarray,
) -> np.ndarray

Build the mass-preserving effective weight vector for one location / channel.

Combines the (length-T) weights_time (after masking on non-finite obs / est) with the per-cell confidence row wobs_row, then rescales so the resulting vector sums to the masked-weights_time total. This preserves each location's total LL mass exactly as in the unweighted path — only the shape of which cells are trusted changes, so weights_location stays the sole cross-location lever.

Non-finite entries in wobs_row are treated as zero (no per-cell trust). A fully-zero w_raw (e.g. an all-zero wobs_row) returns a zero vector, which contributes zero LL.

Parameters:

Name Type Description Default
weights_time ndarray

Length-T time weights (raw, not masked).

required
wobs_row ndarray

Length-T per-cell confidence weights, values in [0, 1] or NaN.

required
obs_vec ndarray

Length-T observation row.

required
est_vec ndarray

Length-T estimate row.

required

Returns:

Type Description
ndarray

Length-T effective weight vector (zeros on masked / zero-confidence cells).

Source code in src/laser/cholera/calc_model_likelihood.py
def weights_obs_effective(
    weights_time: np.ndarray,
    wobs_row: np.ndarray,
    obs_vec: np.ndarray,
    est_vec: np.ndarray,
) -> np.ndarray:
    """Build the mass-preserving effective weight vector for one location / channel.

    Combines the (length-T) ``weights_time`` (after masking on non-finite obs
    / est) with the per-cell confidence row ``wobs_row``, then rescales so the
    resulting vector sums to the masked-``weights_time`` total. This preserves
    each location's total LL mass exactly as in the unweighted path — only
    the *shape* of which cells are trusted changes, so ``weights_location``
    stays the sole cross-location lever.

    Non-finite entries in ``wobs_row`` are treated as zero (no per-cell
    trust). A fully-zero ``w_raw`` (e.g. an all-zero ``wobs_row``) returns a
    zero vector, which contributes zero LL.

    Args:
        weights_time: Length-T time weights (raw, not masked).
        wobs_row: Length-T per-cell confidence weights, values in ``[0, 1]``
            or NaN.
        obs_vec: Length-T observation row.
        est_vec: Length-T estimate row.

    Returns:
        Length-T effective weight vector (zeros on masked / zero-confidence cells).
    """
    masked_wt = mask_weights(weights_time, obs_vec, est_vec)
    target_j = float(np.sum(masked_wt))
    wobs_use = np.where(np.isfinite(wobs_row), wobs_row, 0.0)
    w_raw = masked_wt * wobs_use
    s = float(np.sum(w_raw))
    if s <= 0.0 or not np.isfinite(target_j) or target_j <= 0.0:
        return np.zeros(len(weights_time), dtype=float)
    return w_raw / s * target_j

calc_multi_peak_timing_ll

calc_multi_peak_timing_ll(
    obs_vec: ndarray,
    est_vec: ndarray,
    iso_code: str | None = None,
    date_start: str | None = None,
    date_stop: str | None = None,
    sigma_peak_time: float = 1,
    epidemic_peaks: DataFrame | None = None,
) -> float

Compute peak timing log-likelihood using epidemic peaks data (legacy interface).

Matches epidemic peak dates to the time series via a date sequence, then scores estimated peak timing within ±14-step windows using a Normal prior. Unlike the main calc_model_likelihood function, this helper dispatches by iso_code against the supplied DataFrame and does not require a loc_idx column.

Parameters:

Name Type Description Default
obs_vec ndarray

Observed time series for one location (1-D array).

required
est_vec ndarray

Estimated time series for one location (1-D array).

required
iso_code str | None

ISO country code used to look up peaks in epidemic_peaks.

None
date_start str | None

Start date of the time series (string or date-like).

None
date_stop str | None

End date of the time series (string or date-like).

None
sigma_peak_time float

SD in weeks for the Normal timing prior. Defaults to 1.

1
epidemic_peaks DataFrame | None

pandas DataFrame with at least iso_code and peak_date columns. A loc_idx column, if present, is ignored. Returns 0.0 if None.

None

Returns:

Type Description
float

Sum of Normal log-PDFs for timing offsets. Returns 0.0 if required inputs

float

are missing, no peaks are found, or the date sequence cannot be built.

Raises:

Type Description
KeyError

If epidemic_peaks is supplied but lacks an iso_code or peak_date column — propagated from pandas indexing.

Source code in src/laser/cholera/calc_model_likelihood.py
def calc_multi_peak_timing_ll(
    obs_vec: np.ndarray,
    est_vec: np.ndarray,
    iso_code: str | None = None,
    date_start: str | None = None,
    date_stop: str | None = None,
    sigma_peak_time: float = 1,
    epidemic_peaks: pd.DataFrame | None = None,
) -> float:
    """Compute peak timing log-likelihood using epidemic peaks data (legacy interface).

    Matches epidemic peak dates to the time series via a date sequence, then scores
    estimated peak timing within ±14-step windows using a Normal prior. Unlike the
    main ``calc_model_likelihood`` function, this helper dispatches by ``iso_code``
    against the supplied DataFrame and does *not* require a ``loc_idx`` column.

    Args:
        obs_vec: Observed time series for one location (1-D array).
        est_vec: Estimated time series for one location (1-D array).
        iso_code: ISO country code used to look up peaks in epidemic_peaks.
        date_start: Start date of the time series (string or date-like).
        date_stop: End date of the time series (string or date-like).
        sigma_peak_time: SD in weeks for the Normal timing prior. Defaults to 1.
        epidemic_peaks: pandas DataFrame with at least ``iso_code`` and
            ``peak_date`` columns. A ``loc_idx`` column, if present, is ignored.
            Returns 0.0 if None.

    Returns:
        Sum of Normal log-PDFs for timing offsets. Returns 0.0 if required inputs
        are missing, no peaks are found, or the date sequence cannot be built.

    Raises:
        KeyError: If ``epidemic_peaks`` is supplied but lacks an ``iso_code`` or
            ``peak_date`` column — propagated from pandas indexing.
    """
    if epidemic_peaks is None or iso_code is None or date_start is None or date_stop is None:
        return 0.0

    loc_peaks = epidemic_peaks[epidemic_peaks["iso_code"] == iso_code]
    if len(loc_peaks) == 0:
        return 0.0

    date_seq = pd.date_range(start=date_start, end=date_stop, freq="D")
    timestep_to_weeks = 7
    if len(date_seq) != len(obs_vec):
        date_seq = pd.date_range(start=date_start, end=date_stop, freq="W")
        if len(date_seq) != len(obs_vec):
            return 0.0
        timestep_to_weeks = 1

    # Drop peaks outside the simulation window; otherwise `np.argmin` snaps
    # them to t=0 or t=len(obs_vec)-1 and biases the LL term.
    date_lo = pd.Timestamp(date_start)  # date_seq[0]
    date_hi = pd.Timestamp(date_stop)  # date_seq[-1]
    peak_indices = []
    for peak_date in loc_peaks["peak_date"]:
        peak_ts = pd.Timestamp(peak_date)
        if pd.isna(peak_ts) or peak_ts < date_lo or peak_ts > date_hi:
            continue
        idx = int(np.argmin(np.abs(date_seq - peak_ts)))
        if 0 <= idx < len(obs_vec):
            peak_indices.append(idx)

    if not peak_indices:
        return 0.0

    return _calc_peak_timing_from_indices(est_vec, peak_indices, sigma_peak_time, timestep_to_weeks)

calc_multi_peak_magnitude_ll

calc_multi_peak_magnitude_ll(
    obs_vec: ndarray,
    est_vec: ndarray,
    iso_code: str | None = None,
    date_start: str | None = None,
    date_stop: str | None = None,
    sigma_peak_log: float = 0.5,
    epidemic_peaks: DataFrame | None = None,
) -> float

Compute peak magnitude log-likelihood using epidemic peaks data (legacy interface).

Matches epidemic peak dates to the time series via a date sequence, then scores estimated peak magnitudes within ±14-step windows using an adaptive log-Normal prior. Unlike the main calc_model_likelihood function, this helper dispatches by iso_code against the supplied DataFrame and does not require a loc_idx column.

Parameters:

Name Type Description Default
obs_vec ndarray

Observed time series for one location (1-D array).

required
est_vec ndarray

Estimated time series for one location (1-D array).

required
iso_code str | None

ISO country code used to look up peaks in epidemic_peaks.

None
date_start str | None

Start date of the time series (string or date-like).

None
date_stop str | None

End date of the time series (string or date-like).

None
sigma_peak_log float

Base SD on the log scale. Defaults to 0.5.

0.5
epidemic_peaks DataFrame | None

pandas DataFrame with at least iso_code and peak_date columns. A loc_idx column, if present, is ignored. Returns 0.0 if None.

None

Returns:

Type Description
float

Sum of Normal log-PDFs for log-ratio peak magnitudes. Returns 0.0 if required

float

inputs are missing, no peaks are found, or the date sequence cannot be built.

Raises:

Type Description
KeyError

If epidemic_peaks is supplied but lacks an iso_code or peak_date column — propagated from pandas indexing.

Source code in src/laser/cholera/calc_model_likelihood.py
def calc_multi_peak_magnitude_ll(
    obs_vec: np.ndarray,
    est_vec: np.ndarray,
    iso_code: str | None = None,
    date_start: str | None = None,
    date_stop: str | None = None,
    sigma_peak_log: float = 0.5,
    epidemic_peaks: pd.DataFrame | None = None,
) -> float:
    """Compute peak magnitude log-likelihood using epidemic peaks data (legacy interface).

    Matches epidemic peak dates to the time series via a date sequence, then scores
    estimated peak magnitudes within ±14-step windows using an adaptive log-Normal
    prior. Unlike the main ``calc_model_likelihood`` function, this helper
    dispatches by ``iso_code`` against the supplied DataFrame and does *not*
    require a ``loc_idx`` column.

    Args:
        obs_vec: Observed time series for one location (1-D array).
        est_vec: Estimated time series for one location (1-D array).
        iso_code: ISO country code used to look up peaks in epidemic_peaks.
        date_start: Start date of the time series (string or date-like).
        date_stop: End date of the time series (string or date-like).
        sigma_peak_log: Base SD on the log scale. Defaults to 0.5.
        epidemic_peaks: pandas DataFrame with at least ``iso_code`` and
            ``peak_date`` columns. A ``loc_idx`` column, if present, is ignored.
            Returns 0.0 if None.

    Returns:
        Sum of Normal log-PDFs for log-ratio peak magnitudes. Returns 0.0 if required
        inputs are missing, no peaks are found, or the date sequence cannot be built.

    Raises:
        KeyError: If ``epidemic_peaks`` is supplied but lacks an ``iso_code`` or
            ``peak_date`` column — propagated from pandas indexing.
    """
    if epidemic_peaks is None or iso_code is None or date_start is None or date_stop is None:
        return 0.0

    loc_peaks = epidemic_peaks[epidemic_peaks["iso_code"] == iso_code]
    if len(loc_peaks) == 0:
        return 0.0

    date_seq = pd.date_range(start=date_start, end=date_stop, freq="D")
    if len(date_seq) != len(obs_vec):
        date_seq = pd.date_range(start=date_start, end=date_stop, freq="W")
        if len(date_seq) != len(obs_vec):
            return 0.0

    # Drop peaks outside the simulation window; otherwise `np.argmin` snaps
    # them to t=0 or t=len(obs_vec)-1 and biases the LL term.
    date_lo = pd.Timestamp(date_start)  # date_seq[0]
    date_hi = pd.Timestamp(date_stop)  # date_seq[-1]
    peak_indices = []
    for peak_date in loc_peaks["peak_date"]:
        peak_ts = pd.Timestamp(peak_date)
        if pd.isna(peak_ts) or peak_ts < date_lo or peak_ts > date_hi:
            continue
        idx = int(np.argmin(np.abs(date_seq - peak_ts)))
        if 0 <= idx < len(obs_vec):
            peak_indices.append(idx)

    if not peak_indices:
        return 0.0

    return _calc_peak_magnitude_from_indices(obs_vec, est_vec, peak_indices, sigma_peak_log)

ll_cumulative_progressive_nb

ll_cumulative_progressive_nb(
    obs_vec: ndarray,
    est_vec: ndarray,
    timepoints: ndarray = np.array([0.25, 0.5, 0.75, 1.0]),
    k_data: float | None = None,
    weights_time: ndarray | None = None,
    k_fallback: float = 10.0,
) -> float

Compute cumulative-progression NB log-likelihood at fractional timepoints.

Evaluates the NB log-PMF at cumulative sums of obs/est at each fractional timepoint. The NB size is scaled proportionally to the number of summed timesteps (k * end_idx), reflecting variance scaling of summed NB variables. Each timepoint contribution is normalized by end_idx to yield a per-observation LL, making it scale-compatible with other shape components at assembly.

Parameters:

Name Type Description Default
obs_vec ndarray

Observed count time series (1-D array).

required
est_vec ndarray

Estimated count time series (1-D array).

required
timepoints ndarray

Fractional timepoints at which cumulative sums are evaluated. Defaults to [0.25, 0.5, 0.75, 1.0].

array([0.25, 0.5, 0.75, 1.0])
k_data float | None

Data-driven NB dispersion from nb_size_from_obs_weighted. If None or non-finite, falls back to k_fallback.

None
weights_time ndarray | None

Retained for API compatibility with the R version; not used in the cumulative sum computation.

None
k_fallback float

Fallback k when k_data is unavailable. Defaults to 10.0.

10.0

Returns:

Type Description
float

Mean per-observation LL across valid timepoints. Returns 0.0 if no valid

float

timepoints exist.

Source code in src/laser/cholera/calc_model_likelihood.py
def ll_cumulative_progressive_nb(
    obs_vec: np.ndarray,
    est_vec: np.ndarray,
    timepoints: np.ndarray = np.array([0.25, 0.5, 0.75, 1.0]),  # noqa: B008
    k_data: float | None = None,
    weights_time: np.ndarray | None = None,
    k_fallback: float = 10.0,
) -> float:
    """Compute cumulative-progression NB log-likelihood at fractional timepoints.

    Evaluates the NB log-PMF at cumulative sums of obs/est at each fractional
    timepoint. The NB size is scaled proportionally to the number of summed
    timesteps (k * end_idx), reflecting variance scaling of summed NB variables.
    Each timepoint contribution is normalized by end_idx to yield a per-observation
    LL, making it scale-compatible with other shape components at assembly.

    Args:
        obs_vec: Observed count time series (1-D array).
        est_vec: Estimated count time series (1-D array).
        timepoints: Fractional timepoints at which cumulative sums are evaluated.
            Defaults to [0.25, 0.5, 0.75, 1.0].
        k_data: Data-driven NB dispersion from nb_size_from_obs_weighted. If None
            or non-finite, falls back to k_fallback.
        weights_time: Retained for API compatibility with the R version; not used
            in the cumulative sum computation.
        k_fallback: Fallback k when k_data is unavailable. Defaults to 10.0.

    Returns:
        Mean per-observation LL across valid timepoints. Returns 0.0 if no valid
        timepoints exist.
    """
    n = len(obs_vec)

    vals = []

    for tp in timepoints:
        end_idx = int(np.clip(round(n * tp), 1, n))

        cum_k = k_data * end_idx if (k_data is not None and np.isfinite(k_data)) else k_fallback

        o_cum = float(np.nansum(obs_vec[:end_idx]))
        e_cum = float(np.nansum(est_vec[:end_idx]))

        if not (np.isfinite(o_cum) and np.isfinite(e_cum)):
            continue

        if e_cum <= 0 and o_cum > 0:
            vals.append((-round(o_cum) * np.log(1e6)) / end_idx)
            continue

        e_cum = max(e_cum, 1e-10)
        p_nb = cum_k / (cum_k + e_cum)
        ll_tp = float(scipy.stats.nbinom.logpmf(round(o_cum), n=cum_k, p=p_nb))

        if not np.isfinite(ll_tp):
            vals.append((-round(o_cum) * np.log(1e6)) / end_idx)
            continue

        vals.append(ll_tp / end_idx)

    if not vals:
        return 0.0
    return float(np.mean(vals))

compute_wis_parametric_row

compute_wis_parametric_row(
    y: ndarray,
    est: ndarray,
    w_time: ndarray,
    probs: ndarray,
    k_use: float,
) -> float

Compute Weighted Interval Score (WIS) for a single time-series row.

Uses NB (or Poisson when k_use is infinite) quantile functions evaluated at each time step to score the observed series against the estimated series. The final score is the weighted average over time of interval scores across all symmetric quantile pairs, plus a median absolute error term.

Parameters:

Name Type Description Default
y ndarray

Observed time series (1-D array).

required
est ndarray

Estimated means (1-D array, same length as y).

required
w_time ndarray

Per-timestep weights (non-negative).

required
probs ndarray

Quantile levels. Symmetric pairs (p, 1-p) are matched for interval scoring; the 0.5 quantile is used for the median AE term.

required
k_use float

NB dispersion. Use np.inf to fall back to Poisson.

required

Returns:

Type Description
float

WIS score (lower is better). Returns np.nan if all observations are

float

non-finite or total weight is zero.

Source code in src/laser/cholera/calc_model_likelihood.py
def compute_wis_parametric_row(
    y: np.ndarray,
    est: np.ndarray,
    w_time: np.ndarray,
    probs: np.ndarray,
    k_use: float,
) -> float:
    """Compute Weighted Interval Score (WIS) for a single time-series row.

    Uses NB (or Poisson when k_use is infinite) quantile functions evaluated at each
    time step to score the observed series against the estimated series. The final
    score is the weighted average over time of interval scores across all symmetric
    quantile pairs, plus a median absolute error term.

    Args:
        y: Observed time series (1-D array).
        est: Estimated means (1-D array, same length as y).
        w_time: Per-timestep weights (non-negative).
        probs: Quantile levels. Symmetric pairs (p, 1-p) are matched for interval
            scoring; the 0.5 quantile is used for the median AE term.
        k_use: NB dispersion. Use np.inf to fall back to Poisson.

    Returns:
        WIS score (lower is better). Returns np.nan if all observations are
        non-finite or total weight is zero.
    """
    if not (np.any(np.isfinite(y)) and np.any(np.isfinite(est))):
        return np.nan

    w_use = w_time.copy().astype(float)
    bad = ~np.isfinite(y) | ~np.isfinite(est)
    if np.any(bad):
        w_use[bad] = 0.0
    if np.sum(w_use) == 0:
        return np.nan

    est_eval = np.maximum(est, 1e-12)

    def qfun(p_val: float) -> np.ndarray:
        if np.isinf(k_use):
            return scipy.stats.poisson.ppf(p_val, mu=est_eval)
        p_nb = k_use / (k_use + est_eval)
        return scipy.stats.nbinom.ppf(p_val, n=k_use, p=p_nb)

    probs_sorted = np.sort(np.unique(probs))
    has_med = np.any(np.abs(probs_sorted - 0.5) < 1e-8)
    mae_term = 0.0
    if has_med:
        q_med = qfun(0.5)
        mae_term = 0.5 * float(np.nansum(np.abs(y - q_med) * w_use) / np.sum(w_use))

    lowers = probs_sorted[probs_sorted < 0.5]
    uppers = probs_sorted[probs_sorted > 0.5]

    pairs = []
    for p in lowers:
        complement = 1.0 - p
        match_idx = np.where(np.abs(uppers - complement) < 1e-8)[0]
        if len(match_idx) > 0:
            pairs.append((p, uppers[match_idx[0]]))
        else:
            pairs.append((p, uppers[int(np.argmin(np.abs(uppers - complement)))]))

    k_pairs = len(pairs)
    sum_is = 0.0
    for p_l, p_u in pairs:
        q_l = qfun(p_l)
        q_u = qfun(p_u)
        alpha = 1.0 - (p_u - p_l)
        width = q_u - q_l
        under = np.maximum(0.0, q_l - y) * (2.0 / alpha)
        over = np.maximum(0.0, y - q_u) * (2.0 / alpha)
        contrib = float(np.nansum((width + under + over) * w_use) / np.sum(w_use))
        sum_is += (alpha / 2.0) * contrib

    return float((mae_term + sum_is) / (k_pairs + 0.5))

calc_model_likelihood

calc_model_likelihood(
    obs_cases: ndarray,
    est_cases: ndarray,
    obs_deaths: ndarray,
    est_deaths: ndarray,
    weight_cases: float = 1.0,
    weight_deaths: float = 1.0,
    weights_location: ndarray | None = None,
    weights_time: ndarray | None = None,
    weights_obs_cases: ndarray | None = None,
    weights_obs_deaths: ndarray | None = None,
    weight_peak_timing: float = 0,
    weight_peak_magnitude: float = 0,
    weight_cumulative_total: float = 0,
    weight_wis: float = 0,
    sigma_peak_time: float = 1,
    sigma_peak_log: float = 0.5,
    epidemic_peaks: DataFrame | None = None,
    date_start: datetime | None = None,
    date_stop: datetime | None = None,
    wis_quantiles: ndarray = np.array(
        [0.025, 0.25, 0.5, 0.75, 0.975]
    ),
    cumulative_timepoints: ndarray = np.array(
        [0.25, 0.5, 0.75, 1.0]
    ),
    nb_k_min_cases: float = 3,
    nb_k_min_deaths: float = 3,
) -> float

Compute total model log-likelihood against observed cases and deaths.

Scores model fits using a weighted Negative Binomial time-series log-likelihood per location and outcome. The NB dispersion k is estimated from observed data via weighted method-of-moments with a k_min floor, making it a property of the observation process rather than the model fit.

Optional shape terms (all off by default) are T-normalized so that a weight of 0.25 contributes roughly 25% as much as the NB core:

  • Peak timing: Normal(0, sigma_peak_time) on the timing offset in weeks.
  • Peak magnitude: log-Normal with adaptive sigma on the observed/estimated peak ratio.
  • Cumulative progression: NB on cumulative sums at fractional timepoints.
  • WIS: Negated Weighted Interval Score using NB quantile functions.

The peak shape terms require an epidemic_peaks DataFrame (with the loc_idx column identifying the simulation row each peak belongs to) and the simulation calendar bounds date_start and date_stop. If any of the three is None (or no peak weights are set), the peak terms are skipped.

Assembly formula per location j::

ll_loc = wc * NB_cases + wd * NB_deaths
       + (N_obs/N_peaks)    * w_pt  * (wc*pt_c  + wd*pt_d)
       + (N_obs/N_peaks)    * w_pm  * (wc*pm_c  + wd*pm_d)
       + (N_obs/N_eval_pts) * w_cum * (wc*cum_c + wd*cum_d)
       + (N_obs/N_quant)    * w_wis * (wc*wis_c + wd*wis_d)

Parameters:

Name Type Description Default
obs_cases ndarray

Observed case counts, shape (n_locations, n_time_steps).

required
est_cases ndarray

Estimated case counts, shape (n_locations, n_time_steps).

required
obs_deaths ndarray

Observed death counts, shape (n_locations, n_time_steps).

required
est_deaths ndarray

Estimated death counts, shape (n_locations, n_time_steps).

required
weight_cases float

Scalar weight multiplier for all case components. Defaults to 1.

1.0
weight_deaths float

Scalar weight multiplier for all death components. Defaults to 1.

1.0
weights_location ndarray | None

Non-negative location weights, length n_locations. Defaults to ones. Must contain at least one positive entry; an all-zero vector raises ValueError (see Raises).

None
weights_time ndarray | None

Non-negative time weights, length n_time_steps. Defaults to ones. Must contain at least one positive entry; an all-zero vector raises ValueError (see Raises).

None
weights_obs_cases ndarray | None

Optional per-cell confidence weights for the case observations, shape (n_locations, n_time_steps), values in [0, 1] or NaN. Affects ONLY the NB core (shape terms remain unweighted in v1). None or an all-1.0 matrix on finite-obs cells routes through the unweighted code path and is byte-identical to the legacy behaviour. Non-trivial weights apply a per-location, mass-preserving renormalisation: each location's total NB log-likelihood mass equals the unweighted equivalent — only the shape of which cells are trusted changes; weights_location remains the sole cross-location lever. The ESS-style observation gate on the weighted path requires sum(weights_obs_cases[finite, positive-weights_time]) >= 3 (cases and deaths gate independently). Defaults to None.

None
weights_obs_deaths ndarray | None

Same as weights_obs_cases but for the death observations. Defaults to None.

None
weight_peak_timing float

Weight for peak timing term (T-normalized). Defaults to 0.

0
weight_peak_magnitude float

Weight for peak magnitude term (T-normalized). Defaults to 0.

0
weight_cumulative_total float

Weight for cumulative progression term. Defaults to 0.

0
weight_wis float

Weight for WIS term (T-normalized). Defaults to 0.

0
sigma_peak_time float

SD in weeks for the peak timing Normal prior. Defaults to 1.

1
sigma_peak_log float

Base SD on log-scale for peak magnitude prior. Defaults to 0.5.

0.5
epidemic_peaks DataFrame | None

Optional pandas DataFrame of epidemic peaks with columns iso_code, peak_date, and loc_idx (0-based row index into obs/est arrays). When None, peak shape terms are skipped regardless of their weights.

None
date_start datetime | None

Calendar date of time-step 0 (any value pandas can promote to a Timestamp). Required for the peak shape terms. Defaults to None.

None
date_stop datetime | None

Calendar date of the final time-step. Used together with date_start to build the daily/weekly index lookup. Defaults to None.

None
wis_quantiles ndarray

Quantile levels for WIS scoring. Defaults to [0.025, 0.25, 0.5, 0.75, 0.975].

array([0.025, 0.25, 0.5, 0.75, 0.975])
cumulative_timepoints ndarray

Fractional timepoints for cumulative progression. Defaults to [0.25, 0.5, 0.75, 1.0].

array([0.25, 0.5, 0.75, 1.0])
nb_k_min_cases float

Minimum NB dispersion floor for cases. Defaults to 3.

3
nb_k_min_deaths float

Minimum NB dispersion floor for deaths. Defaults to 3.

3

Returns:

Type Description
float

Scalar total log-likelihood. Returns -np.inf if the total is non-finite and

float

np.nan if all locations contribute NA (e.g., all have too few observations).

Raises:

Type Description
ValueError

If any input is not a 2-D array, dimensions are inconsistent, estimated values are negative, weights are negative, or weight vectors sum to zero.

Example

Compute the core NB log-likelihood for a small two-location, four-timestep toy problem with no shape terms:

import numpy as np from laser.cholera.calc_model_likelihood import calc_model_likelihood obs_cases = np.array([[5, 8, 12, 7], [3, 6, 9, 4]], dtype=float) est_cases = np.array([[6, 9, 11, 7], [4, 6, 8, 5]], dtype=float) obs_deaths = np.zeros_like(obs_cases) est_deaths = np.zeros_like(est_cases) ll = calc_model_likelihood(obs_cases, est_cases, obs_deaths, est_deaths) ll < 0 True

Source code in src/laser/cholera/calc_model_likelihood.py
def calc_model_likelihood(
    obs_cases: np.ndarray,  # [n_locs x n_steps]
    est_cases: np.ndarray,  # [n_locs x n_steps]
    obs_deaths: np.ndarray,  # [n_locs x n_steps]
    est_deaths: np.ndarray,  # [n_locs x n_steps]
    weight_cases: float = 1.0,
    weight_deaths: float = 1.0,
    weights_location: np.ndarray | None = None,  # [n_locs] | None
    weights_time: np.ndarray | None = None,  # [n_steps] | None
    # --- per-observation confidence weights ([n_locs x n_steps], in [0, 1] or NaN); affect ONLY the NB core ---
    weights_obs_cases: np.ndarray | None = None,
    weights_obs_deaths: np.ndarray | None = None,
    # -- shape term weights (0 = OFF; 0.25 = 25% of NB core influence) ---
    weight_peak_timing: float = 0,
    weight_peak_magnitude: float = 0,
    weight_cumulative_total: float = 0,
    weight_wis: float = 0,
    # --- peak controls ---
    sigma_peak_time: float = 1,
    sigma_peak_log: float = 0.5,
    epidemic_peaks: pd.DataFrame | None = None,
    date_start: datetime.datetime | None = None,
    date_stop: datetime.datetime | None = None,
    # --- WIS ---
    wis_quantiles: np.ndarray = np.array([0.025, 0.25, 0.5, 0.75, 0.975]),  # noqa: B008
    # --- cumulative ---
    cumulative_timepoints: np.ndarray = np.array([0.25, 0.5, 0.75, 1.0]),  # noqa: B008
    # --- NB controls ---
    nb_k_min_cases: float = 3,
    nb_k_min_deaths: float = 3,
) -> float:
    """Compute total model log-likelihood against observed cases and deaths.

    Scores model fits using a weighted Negative Binomial time-series log-likelihood
    per location and outcome. The NB dispersion k is estimated from observed data via
    weighted method-of-moments with a k_min floor, making it a property of the
    observation process rather than the model fit.

    Optional shape terms (all off by default) are T-normalized so that a weight of
    0.25 contributes roughly 25% as much as the NB core:

    - **Peak timing**: Normal(0, sigma_peak_time) on the timing offset in weeks.
    - **Peak magnitude**: log-Normal with adaptive sigma on the observed/estimated
      peak ratio.
    - **Cumulative progression**: NB on cumulative sums at fractional timepoints.
    - **WIS**: Negated Weighted Interval Score using NB quantile functions.

    The peak shape terms require an ``epidemic_peaks`` DataFrame (with the
    ``loc_idx`` column identifying the simulation row each peak belongs to) and
    the simulation calendar bounds ``date_start`` and ``date_stop``. If any of the
    three is ``None`` (or no peak weights are set), the peak terms are skipped.

    Assembly formula per location j::

        ll_loc = wc * NB_cases + wd * NB_deaths
               + (N_obs/N_peaks)    * w_pt  * (wc*pt_c  + wd*pt_d)
               + (N_obs/N_peaks)    * w_pm  * (wc*pm_c  + wd*pm_d)
               + (N_obs/N_eval_pts) * w_cum * (wc*cum_c + wd*cum_d)
               + (N_obs/N_quant)    * w_wis * (wc*wis_c + wd*wis_d)

    Args:
        obs_cases: Observed case counts, shape (n_locations, n_time_steps).
        est_cases: Estimated case counts, shape (n_locations, n_time_steps).
        obs_deaths: Observed death counts, shape (n_locations, n_time_steps).
        est_deaths: Estimated death counts, shape (n_locations, n_time_steps).
        weight_cases: Scalar weight multiplier for all case components. Defaults to 1.
        weight_deaths: Scalar weight multiplier for all death components. Defaults to 1.
        weights_location: Non-negative location weights, length n_locations. Defaults
            to ones. Must contain at least one positive entry; an all-zero vector
            raises ``ValueError`` (see Raises).
        weights_time: Non-negative time weights, length n_time_steps. Defaults to
            ones. Must contain at least one positive entry; an all-zero vector
            raises ``ValueError`` (see Raises).
        weights_obs_cases: Optional per-cell confidence weights for the case
            observations, shape ``(n_locations, n_time_steps)``, values in
            ``[0, 1]`` or NaN. Affects ONLY the NB core (shape terms remain
            unweighted in v1). ``None`` or an all-1.0 matrix on finite-obs
            cells routes through the unweighted code path and is byte-identical
            to the legacy behaviour. Non-trivial weights apply a per-location,
            mass-preserving renormalisation: each location's total NB
            log-likelihood mass equals the unweighted equivalent — only the
            *shape* of which cells are trusted changes; ``weights_location``
            remains the sole cross-location lever. The ESS-style observation
            gate on the weighted path requires ``sum(weights_obs_cases[finite,
            positive-weights_time]) >= 3`` (cases and deaths gate
            independently). Defaults to ``None``.
        weights_obs_deaths: Same as ``weights_obs_cases`` but for the death
            observations. Defaults to ``None``.
        weight_peak_timing: Weight for peak timing term (T-normalized). Defaults to 0.
        weight_peak_magnitude: Weight for peak magnitude term (T-normalized). Defaults to 0.
        weight_cumulative_total: Weight for cumulative progression term. Defaults to 0.
        weight_wis: Weight for WIS term (T-normalized). Defaults to 0.
        sigma_peak_time: SD in weeks for the peak timing Normal prior. Defaults to 1.
        sigma_peak_log: Base SD on log-scale for peak magnitude prior. Defaults to 0.5.
        epidemic_peaks: Optional pandas DataFrame of epidemic peaks with columns
            ``iso_code``, ``peak_date``, and ``loc_idx`` (0-based row index into
            obs/est arrays). When ``None``, peak shape terms are skipped regardless
            of their weights.
        date_start: Calendar date of time-step 0 (any value pandas can promote to
            a Timestamp). Required for the peak shape terms. Defaults to ``None``.
        date_stop: Calendar date of the final time-step. Used together with
            ``date_start`` to build the daily/weekly index lookup. Defaults to ``None``.
        wis_quantiles: Quantile levels for WIS scoring. Defaults to
            [0.025, 0.25, 0.5, 0.75, 0.975].
        cumulative_timepoints: Fractional timepoints for cumulative progression.
            Defaults to [0.25, 0.5, 0.75, 1.0].
        nb_k_min_cases: Minimum NB dispersion floor for cases. Defaults to 3.
        nb_k_min_deaths: Minimum NB dispersion floor for deaths. Defaults to 3.

    Returns:
        Scalar total log-likelihood. Returns -np.inf if the total is non-finite and
        np.nan if all locations contribute NA (e.g., all have too few observations).

    Raises:
        ValueError: If any input is not a 2-D array, dimensions are inconsistent,
            estimated values are negative, weights are negative, or weight vectors
            sum to zero.

    Example:
        Compute the core NB log-likelihood for a small two-location,
        four-timestep toy problem with no shape terms:

        >>> import numpy as np
        >>> from laser.cholera.calc_model_likelihood import calc_model_likelihood
        >>> obs_cases = np.array([[5, 8, 12, 7], [3, 6, 9, 4]], dtype=float)
        >>> est_cases = np.array([[6, 9, 11, 7], [4, 6, 8, 5]], dtype=float)
        >>> obs_deaths = np.zeros_like(obs_cases)
        >>> est_deaths = np.zeros_like(est_cases)
        >>> ll = calc_model_likelihood(obs_cases, est_cases, obs_deaths, est_deaths)
        >>> ll < 0
        True
    """
    if (
        not (isinstance(obs_cases, np.ndarray) and obs_cases.ndim == 2)
        or not (isinstance(est_cases, np.ndarray) and est_cases.ndim == 2)
        or not (isinstance(obs_deaths, np.ndarray) and obs_deaths.ndim == 2)
        or not (isinstance(est_deaths, np.ndarray) and est_deaths.ndim == 2)
    ):
        raise ValueError("All inputs must be 2-D arrays (n_locations x n_time_steps).")

    if np.any(est_cases < 0) or np.any(est_deaths < 0):
        raise ValueError("Estimated values must be non-negative.")

    n_locations, n_time_steps = obs_cases.shape

    if (
        est_cases.shape != (n_locations, n_time_steps)
        or obs_deaths.shape != (n_locations, n_time_steps)
        or est_deaths.shape != (n_locations, n_time_steps)
    ):
        raise ValueError("All arrays must have the same shape (n_locations x n_time_steps).")

    if weights_location is None:
        weights_location = np.ones(n_locations)
    else:
        weights_location = np.asarray(weights_location, dtype=float)
    if weights_time is None:
        weights_time = np.ones(n_time_steps)
    else:
        weights_time = np.asarray(weights_time, dtype=float)

    if len(weights_location) != n_locations:
        raise ValueError("weights_location must match n_locations.")
    if len(weights_time) != n_time_steps:
        raise ValueError("weights_time must match n_time_steps.")
    if np.any(weights_location < 0) or np.any(weights_time < 0):
        raise ValueError("All weights must be >= 0.")
    if np.sum(weights_location) == 0 or np.sum(weights_time) == 0:
        raise ValueError("weights_location and weights_time must not all be zero.")

    def _validate_weights_obs(name: str, w_in: np.ndarray | None) -> np.ndarray | None:
        if w_in is None:
            return None
        if not isinstance(w_in, np.ndarray) or w_in.ndim != 2:
            raise ValueError(f"{name} must be a 2-D ndarray (matrix), got type={type(w_in).__name__}")
        if w_in.shape != (n_locations, n_time_steps):
            raise ValueError(f"{name} must have the same dimensions as the observation matrices ({n_locations}, {n_time_steps}); got {w_in.shape}")
        arr = np.asarray(w_in, dtype=float)
        finite = np.isfinite(arr)
        if np.any(finite & (arr < 0)):
            raise ValueError(f"{name} must be >= 0 (NaN permitted; negative values are not)")
        return arr

    weights_obs_cases = _validate_weights_obs("weights_obs_cases", weights_obs_cases)
    weights_obs_deaths = _validate_weights_obs("weights_obs_deaths", weights_obs_deaths)

    # --- precompute peak indices per location (once, not per call) ---
    # `_peak_idx_lists[j]` will hold the 0-based time-step indices of known peaks
    # for location j, or stay None if the peak terms cannot run.
    _peak_idx_lists = None
    timestep_to_weeks = 7
    if (weight_peak_timing > 0 or weight_peak_magnitude > 0) and epidemic_peaks is not None and date_start is not None and date_stop is not None:
        date_seq = pd.date_range(start=date_start, end=date_stop, freq="D")
        if len(date_seq) != n_time_steps:
            date_seq = pd.date_range(start=date_start, end=date_stop, freq="W")
            if len(date_seq) != n_time_steps:
                date_seq = None
            else:
                timestep_to_weeks = 1

        if date_seq is not None:
            logger.info("Precomputing peak indices for %d locations.", n_locations)
            _peak_idx_lists = [[] for _ in range(n_locations)]
            date_lo = pd.Timestamp(date_start)  # date_seq[0]
            date_hi = pd.Timestamp(date_stop)  # date_seq[-1]
            for row in epidemic_peaks.itertuples(index=False):
                loc_idx = getattr(row, "loc_idx", None)
                # Rows with missing or out-of-range `loc_idx` silently contribute
                # no peaks rather than raising; the likelihood is still
                # well-defined for the remaining rows.
                if loc_idx is None or not (0 <= int(loc_idx) < n_locations):
                    continue
                peak_ts = pd.Timestamp(row.peak_date)
                # Drop peaks outside the simulation window; otherwise
                # `np.argmin` snaps them to t=0 or t=n_time_steps-1 and biases
                # the peak-shape terms.
                if pd.isna(peak_ts) or peak_ts < date_lo or peak_ts > date_hi:
                    continue
                idx = int(np.argmin(np.abs(date_seq - peak_ts)))
                if 0 <= idx < n_time_steps:
                    _peak_idx_lists[int(loc_idx)].append(idx)

    # --- main loop ---
    ll_locations = np.full(n_locations, np.nan)

    min_obs_for_likelihood = 3

    for j in range(n_locations):
        obs_c = obs_cases[j, :]
        est_c = est_cases[j, :]
        obs_d = obs_deaths[j, :]
        est_d = est_deaths[j, :]

        # Per-cell confidence-weight rows for this location, if any.
        wobs_c_row = weights_obs_cases[j, :] if weights_obs_cases is not None else None
        wobs_d_row = weights_obs_deaths[j, :] if weights_obs_deaths is not None else None

        # Trivial rows (None or all-1.0 on finite obs) route through the legacy
        # unweighted path for byte-identical results.
        triv_c = weights_obs_row_trivial(wobs_c_row, obs_c)
        triv_d = weights_obs_row_trivial(wobs_d_row, obs_d)

        # Observation gate. Trivial / None path: raw finite-count >= 3
        # (back-compat). Weighted path: effective-sample-size gate
        # `sum(wobs_row[finite & positive weights_time]) >= 3`.
        if triv_c:
            have_cases = int(np.sum(np.isfinite(obs_c))) >= min_obs_for_likelihood
        else:
            sel_c = np.isfinite(obs_c) & np.isfinite(weights_time) & (weights_time > 0)
            wobs_c_for_sum = np.where(np.isfinite(wobs_c_row), wobs_c_row, 0.0)
            have_cases = float(np.sum(wobs_c_for_sum[sel_c])) >= min_obs_for_likelihood
        if triv_d:
            have_deaths = int(np.sum(np.isfinite(obs_d))) >= min_obs_for_likelihood
        else:
            sel_d = np.isfinite(obs_d) & np.isfinite(weights_time) & (weights_time > 0)
            wobs_d_for_sum = np.where(np.isfinite(wobs_d_row), wobs_d_row, 0.0)
            have_deaths = float(np.sum(wobs_d_for_sum[sel_d])) >= min_obs_for_likelihood

        # Effective scoring weights per channel. Trivial -> exact unweighted
        # (masked weights_time); weighted -> mass-preserving renorm.
        if have_cases:
            w_eff_c = mask_weights(weights_time, obs_c, est_c) if triv_c else weights_obs_effective(weights_time, wobs_c_row, obs_c, est_c)
        else:
            w_eff_c = None
        if have_deaths:
            w_eff_d = mask_weights(weights_time, obs_d, est_d) if triv_d else weights_obs_effective(weights_time, wobs_d_row, obs_d, est_d)
        else:
            w_eff_d = None

        # k-coherence: on the trivial path k uses raw `weights_time` (exact
        # prior behaviour); on the weighted path k uses the same masked,
        # mass-preserving `w_eff` it is scored under, so the dispersion is
        # anchored to the cells the LL actually weights.
        if have_cases:
            k_c = nb_size_from_obs_weighted(obs_c, weights_time if triv_c else w_eff_c, k_min=nb_k_min_cases)
        else:
            k_c = np.inf
        if have_deaths:
            k_d = nb_size_from_obs_weighted(obs_d, weights_time if triv_d else w_eff_d, k_min=nb_k_min_deaths)
        else:
            k_d = np.inf

        ll_cases = _calc_log_likelihood_nb(observed=obs_c, estimated=est_c, weights=w_eff_c, k=k_c, k_min=nb_k_min_cases) if have_cases else 0.0
        ll_deaths = _calc_log_likelihood_nb(observed=obs_d, estimated=est_d, weights=w_eff_d, k=k_d, k_min=nb_k_min_deaths) if have_deaths else 0.0

        ll_peak_time_c = ll_peak_time_d = 0.0
        ll_peak_mag_c = ll_peak_mag_d = 0.0

        if (weight_peak_timing > 0 or weight_peak_magnitude > 0) and _peak_idx_lists is not None:
            loc_peak_idx = _peak_idx_lists[j]
            if loc_peak_idx:
                if weight_peak_timing > 0:
                    if have_cases:
                        ll_peak_time_c = _calc_peak_timing_from_indices(est_c, loc_peak_idx, sigma_peak_time, timestep_to_weeks)
                    if have_deaths:
                        ll_peak_time_d = _calc_peak_timing_from_indices(est_d, loc_peak_idx, sigma_peak_time, timestep_to_weeks)
                if weight_peak_magnitude > 0:
                    if have_cases:
                        ll_peak_mag_c = _calc_peak_magnitude_from_indices(obs_c, est_c, loc_peak_idx, sigma_peak_log)
                    if have_deaths:
                        ll_peak_mag_d = _calc_peak_magnitude_from_indices(obs_d, est_d, loc_peak_idx, sigma_peak_log)

        ll_cum_tot_c = ll_cum_tot_d = 0.0
        if weight_cumulative_total > 0:
            if have_cases:
                ll_cum_tot_c = ll_cumulative_progressive_nb(obs_c, est_c, cumulative_timepoints, k_c, weights_time)
            if have_deaths:
                ll_cum_tot_d = ll_cumulative_progressive_nb(obs_d, est_d, cumulative_timepoints, k_d, weights_time)

        ll_wis_cases = ll_wis_deaths = 0.0
        if weight_wis > 0:
            if have_cases:
                wis_c = compute_wis_parametric_row(obs_c, est_c, weights_time, wis_quantiles, k_use=k_c)
                if np.isfinite(wis_c):
                    ll_wis_cases = -wis_c
            if have_deaths:
                wis_d = compute_wis_parametric_row(obs_d, est_d, weights_time, wis_quantiles, k_use=k_d)
                if np.isfinite(wis_d):
                    ll_wis_deaths = -wis_d

        # N_obs: timesteps with at least one finite observation
        n_obs = int(np.sum(np.isfinite(obs_c) | np.isfinite(obs_d)))

        n_peaks_j = len(_peak_idx_lists[j]) if _peak_idx_lists is not None else 0
        n_wis_quant = len(wis_quantiles)
        n_cum_points = len(cumulative_timepoints)

        # Scale factors: N_obs / N_component_obs (T-normalization)
        peak_scale = (n_obs / n_peaks_j) if n_peaks_j > 0 else 0.0
        wis_scale = (n_obs / n_wis_quant) if n_wis_quant > 0 else 0.0
        cum_scale = (n_obs / n_cum_points) if n_cum_points > 0 else 0.0

        ll_loc_core = weight_cases * ll_cases + weight_deaths * ll_deaths
        ll_loc_peaks = peak_scale * weight_peak_timing * (
            weight_cases * ll_peak_time_c + weight_deaths * ll_peak_time_d
        ) + peak_scale * weight_peak_magnitude * (weight_cases * ll_peak_mag_c + weight_deaths * ll_peak_mag_d)
        ll_loc_cum = cum_scale * weight_cumulative_total * (weight_cases * ll_cum_tot_c + weight_deaths * ll_cum_tot_d)
        ll_loc_wis = wis_scale * weight_wis * (weight_cases * ll_wis_cases + weight_deaths * ll_wis_deaths)

        ll_loc_total = ll_loc_core + ll_loc_peaks + ll_loc_cum + ll_loc_wis

        if not np.isfinite(ll_loc_total):
            ll_locations[j] = -np.inf
            continue

        ll_locations[j] = weights_location[j] * ll_loc_total
        logger.info(
            "Location %d: core=%.2f | peaks=%.2f | cum=%.2f | wis=%.2f -> weighted=%.2f",
            j + 1,
            ll_loc_core,
            ll_loc_peaks,
            ll_loc_cum,
            ll_loc_wis,
            float(ll_locations[j]),
        )

    if np.all(np.isnan(ll_locations)):
        logger.info("All locations contributed NA — returning nan.")
        return float("nan")

    ll_total = float(np.nansum(ll_locations))
    if not np.isfinite(ll_total):
        ll_total = -np.inf
    logger.info("Overall total log-likelihood: %.2f", ll_total)
    return ll_total