moabbr.plots

32def league_table(data: dict) -> plt.Figure:
33    """Grid of pairwise treatment comparisons.
34
35    Parameters:
36    - `data`: Result dict from `tombolo.nma` or `tombolo.bnma`. Only `league` is used.
37
38    Each cell shows the mean difference and confidence (or credible) interval for the row
39    treatment relative to the column treatment. Diagonal cells show the treatment name.
40    P-values are included for NMA results.
41    """
42    _matrix = {
43        "type": "object",
44        "additionalProperties": {
45            "type": "object",
46            "additionalProperties": {"type": ["number", "null"]},
47        },
48    }
49
50    _schema = {
51        "type": "object",
52        "required": ["league"],
53        "properties": {
54            "league": {
55                "type": "object",
56                "required": ["md", "lower", "upper"],
57                "properties": {
58                    "md": _matrix,
59                    "lower": _matrix,
60                    "upper": _matrix,
61                    "pval": _matrix,
62                },
63            }
64        },
65    }
66
67    jsonschema.validate(instance=data, schema=_schema)
68    return _grid(data["league"])

126def forest_plot(data: dict, reference: str) -> plt.Figure:
127    """Forest plot of all treatments relative to a reference.
128
129    Parameters:
130    - `data`: Result dict from `tombolo.nma` or `tombolo.bnma`. Only `league` is used.
131    - `reference`: Name of the reference treatment. All other treatments are plotted
132      relative to it, sorted by effect size. Non-alphanumeric characters are normalized to underscores.
133
134    Returns mean differences and confidence (or credible) intervals for each treatment
135    versus the reference. P-values are included for NMA results.
136
137    Raises `RuntimeError` if `reference` is not found in the data.
138    """
139    _matrix = {
140        "type": "object",
141        "additionalProperties": {
142            "type": "object",
143            "additionalProperties": {"type": ["number", "null"]},
144        },
145    }
146
147    _schema = {
148        "type": "object",
149        "required": ["league"],
150        "properties": {
151            "league": {
152                "type": "object",
153                "required": ["md", "lower", "upper"],
154                "properties": {
155                    "md": _matrix,
156                    "lower": _matrix,
157                    "upper": _matrix,
158                    "pval": _matrix,
159                },
160            }
161        },
162    }
163
164    jsonschema.validate(instance=data, schema=_schema)
165    ref = re.sub(r"[^A-Za-z0-9_]", "_", reference)
166    if ref not in data["league"]["md"]:
167        raise RuntimeError("Missing reference")
168
169    label = "[95% CI]" if "pval" in data["league"] else "[95% CrI]"
170    return _forest(data["league"], ref, interval_label=label)

10def ranking_plot(data: dict) -> plt.Figure:
11    """Horizontal bar chart of treatment rankings.
12
13    Parameters:
14    - `data`: Result dict from `tombolo.nma` or `tombolo.bnma`. Only `ranking` is used.
15
16    Returns treatments sorted by rank score (P-score for NMA, SUCRA for BNMA).
17    """
18    _schema = {
19        "type": "object",
20        "required": ["ranking"],
21        "properties": {
22            "ranking": {
23                "type": "object",
24                "additionalProperties": {"type": "number", "minimum": 0, "maximum": 1},
25            }
26        },
27    }
28    jsonschema.validate(instance=data, schema=_schema)
29    return _barh(data["ranking"])

 71def heterogeneity_table(data: dict) -> plt.Figure:
 72    """Summary table of heterogeneity statistics.
 73
 74    Parameters:
 75    - `data`: Result dict from `tombolo.nma` or `tombolo.bnma`. Only `heterogeneity` is used.
 76
 77    For NMA results: Q statistic, p-value, I², and τ.
 78    For BNMA results: posterior SD and 95% credible interval.
 79    """
 80    _nma_heterogeneity = {
 81        "type": "object",
 82        "required": [
 83            "tau2",
 84            "tau",
 85            "i2",
 86            "i2_lower",
 87            "i2_upper",
 88            "q",
 89            "q_df",
 90            "q_pval",
 91        ],
 92        "properties": {
 93            "tau2": {"type": "number", "minimum": 0},
 94            "tau": {"type": "number", "minimum": 0},
 95            "i2": {"type": "number", "minimum": 0, "maximum": 1},
 96            "i2_lower": {"type": "number", "minimum": 0, "maximum": 1},
 97            "i2_upper": {"type": "number", "minimum": 0, "maximum": 1},
 98            "q": {"type": "number", "minimum": 0},
 99            "q_df": {"type": "integer", "minimum": 0},
100            "q_pval": {"type": "number", "minimum": 0, "maximum": 1},
101        },
102    }
103
104    _bnma_heterogeneity = {
105        "type": "object",
106        "required": ["sd", "sd_lower", "sd_upper"],
107        "properties": {
108            "sd": {"type": "number", "minimum": 0},
109            "sd_lower": {"type": "number", "minimum": 0},
110            "sd_upper": {"type": "number", "minimum": 0},
111        },
112    }
113
114    _schema = {
115        "type": "object",
116        "required": ["heterogeneity"],
117        "properties": {
118            "heterogeneity": {"oneOf": [_nma_heterogeneity, _bnma_heterogeneity]}
119        },
120    }
121
122    jsonschema.validate(instance=data, schema=_schema)
123    return _table(data["heterogeneity"])

173def prediction_table(data: dict) -> plt.Figure:
174    """Grid of prediction intervals. Only applicable to NMA results.
175
176    Parameters:
177    - `data`: Result dict from `tombolo.nma`. Only `prediction` is used.
178
179    Each cell shows the 95% prediction interval for the row treatment relative to the column treatment.
180    """
181    _matrix = {
182        "type": "object",
183        "additionalProperties": {
184            "type": "object",
185            "additionalProperties": {"type": ["number", "null"]},
186        },
187    }
188
189    _schema = {
190        "type": "object",
191        "required": ["prediction"],
192        "properties": {
193            "prediction": {
194                "type": "object",
195                "required": ["lower", "upper"],
196                "properties": {"lower": _matrix, "upper": _matrix},
197            }
198        },
199    }
200
201    jsonschema.validate(instance=data, schema=_schema)
202    return _grid(data["prediction"])

205def convergence_table(data: dict) -> plt.Figure:
206    """Summary table of MCMC convergence diagnostics. Only applicable to BNMA results.
207
208    Parameters:
209    - `data`: Result dict from `tombolo.bnma`. Only `convergence` is used.
210
211    Returns R̂ (max), ESS bulk (min), and ESS tail (min) across all model parameters.
212    """
213    _schema = {
214        "type": "object",
215        "required": ["convergence"],
216        "properties": {
217            "convergence": {
218                "type": "object",
219                "required": ["rhat_max", "ess_bulk_min", "ess_tail_min"],
220                "properties": {
221                    "rhat_max": {"type": "number"},
222                    "ess_bulk_min": {"type": "number"},
223                    "ess_tail_min": {"type": "number"},
224                },
225            }
226        },
227    }
228    jsonschema.validate(instance=data, schema=_schema)
229    return _table(data["convergence"])