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.
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
mask_weights
¶
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
weights_obs_row_trivial
¶
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.0AND 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
|
required |
obs_vec
|
ndarray
|
Observation row (length T). |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|
Source code in src/laser/cholera/calc_model_likelihood.py
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 |
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
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 |
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 |
Source code in src/laser/cholera/calc_model_likelihood.py
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 |
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 |
Source code in src/laser/cholera/calc_model_likelihood.py
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
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
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 | |
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 |
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 |
None
|
weights_obs_cases
|
ndarray | None
|
Optional per-cell confidence weights for the case
observations, shape |
None
|
weights_obs_deaths
|
ndarray | None
|
Same as |
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
|
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
|
date_stop
|
datetime | None
|
Calendar date of the final time-step. Used together with
|
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
618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 | |