tombolo

Python interface to R statistics via Docker.

Statistical computations run inside a Docker container using R. Pull the image before use:

docker pull ethandavisecd/tombolo:latest

See the Docker Hub image for details.

 1"""Python interface to R statistics via Docker.
 2
 3Statistical computations run inside a Docker container using R. Pull the image before use:
 4
 5```
 6docker pull ethandavisecd/tombolo:latest
 7```
 8
 9See the [Docker Hub image](https://hub.docker.com/r/ethandavisecd/tombolo) for details.
10"""
11
12from .run import bnma, nma
13from . import plots
14
15__all__ = ["nma", "bnma", "plots"]
def nma(data: list[dict], greater_is_better: bool = True) -> dict: 
34def nma(data: list[dict], greater_is_better: bool = True) -> dict:
35    """Run a frequentist random-effects network meta-analysis.
36
37    Uses the `netmeta` R package (DL estimator, t-distribution confidence intervals).
38
39    Parameters:
40    - `data`: Pairwise contrast data. Each element requires `studlab` (str), `treat1` (str),
41      `treat2` (str), `TE` (float, mean difference treat1 − treat2), `seTE` (float).
42    - `greater_is_better`: If `True`, higher values rank better (e.g. accuracy).
43      If `False`, lower values rank better (e.g. error rate).
44
45    Returns a dict with:
46    - `ranking`: P-score per treatment (0–1, higher = better rank).
47    - `league`: Pairwise `md`, `lower`, `upper`, `z`, `pval` — each a treatment × treatment matrix.
48    - `heterogeneity`: `tau2`, `tau`, `i2`, `i2_lower`, `i2_upper`, `q`, `q_df`, `q_pval`.
49    - `prediction`: Prediction interval `lower` and `upper` — each a treatment × treatment matrix.
50
51    Raises `jsonschema.ValidationError` if `data` does not match the expected schema,
52    or `RuntimeError` if the R process returns an error.
53    """
54    _schema = {
55        "type": "array",
56        "items": {
57            "type": "object",
58            "properties": {
59                "studlab": {"type": "string"},
60                "treat1": {"type": "string"},
61                "treat2": {"type": "string"},
62                "TE": {"type": "number"},
63                "seTE": {"type": "number"},
64            },
65            "required": ["studlab", "treat1", "treat2", "TE", "seTE"],
66            "additionalProperties": False,
67        },
68    }
69    jsonschema.validate(instance=data, schema=_schema)
70    return _run("nma", data, greater_is_better)

Run a frequentist random-effects network meta-analysis.

Uses the netmeta R package (DL estimator, t-distribution confidence intervals).

Parameters:

  • data: Pairwise contrast data. Each element requires studlab (str), treat1 (str), treat2 (str), TE (float, mean difference treat1 − treat2), seTE (float).
  • greater_is_better: If True, higher values rank better (e.g. accuracy). If False, lower values rank better (e.g. error rate).

Returns a dict with:

  • ranking: P-score per treatment (0–1, higher = better rank).
  • league: Pairwise md, lower, upper, z, pval — each a treatment × treatment matrix.
  • heterogeneity: tau2, tau, i2, i2_lower, i2_upper, q, q_df, q_pval.
  • prediction: Prediction interval lower and upper — each a treatment × treatment matrix.

Raises jsonschema.ValidationError if data does not match the expected schema, or RuntimeError if the R process returns an error.

def bnma(data: list[dict], greater_is_better: bool = True) -> dict: 
 73def bnma(data: list[dict], greater_is_better: bool = True) -> dict:
 74    """Run a Bayesian random-effects network meta-analysis.
 75
 76    Uses the `gemtc` R package with JAGS (normal likelihood, identity link).
 77
 78    Parameters:
 79    - `data`: Arm-level summary data. Each element requires `study` (str), `treatment` (str),
 80      `mean` (float), `std.dev` (float), `sampleSize` (int).
 81    - `greater_is_better`: If `True`, higher values rank better (e.g. accuracy).
 82      If `False`, lower values rank better (e.g. error rate).
 83
 84    Returns a dict with:
 85    - `ranking`: SUCRA per treatment (0–1, higher = better rank).
 86    - `league`: Pairwise posterior median `md` and 95% credible interval `lower`, `upper` — each a treatment × treatment matrix.
 87    - `heterogeneity`: Posterior `sd`, `sd_lower`, `sd_upper` (2.5th–97.5th percentile).
 88    - `convergence`: `rhat_max`, `ess_bulk_min`, `ess_tail_min` across all model parameters.
 89
 90    Raises `jsonschema.ValidationError` if `data` does not match the expected schema,
 91    or `RuntimeError` if the R process returns an error.
 92    """
 93    _schema = {
 94        "type": "array",
 95        "items": {
 96            "type": "object",
 97            "properties": {
 98                "study": {"type": "string"},
 99                "treatment": {"type": "string"},
100                "mean": {"type": "number"},
101                "std.dev": {"type": "number"},
102                "sampleSize": {"type": "integer"},
103            },
104            "required": ["study", "treatment", "mean", "std.dev", "sampleSize"],
105            "additionalProperties": False,
106        },
107    }
108    jsonschema.validate(instance=data, schema=_schema)
109    return _run("bnma", data, greater_is_better)

Run a Bayesian random-effects network meta-analysis.

Uses the gemtc R package with JAGS (normal likelihood, identity link).

Parameters:

  • data: Arm-level summary data. Each element requires study (str), treatment (str), mean (float), std.dev (float), sampleSize (int).
  • greater_is_better: If True, higher values rank better (e.g. accuracy). If False, lower values rank better (e.g. error rate).

Returns a dict with:

  • ranking: SUCRA per treatment (0–1, higher = better rank).
  • league: Pairwise posterior median md and 95% credible interval lower, upper — each a treatment × treatment matrix.
  • heterogeneity: Posterior sd, sd_lower, sd_upper (2.5th–97.5th percentile).
  • convergence: rhat_max, ess_bulk_min, ess_tail_min across all model parameters.

Raises jsonschema.ValidationError if data does not match the expected schema, or RuntimeError if the R process returns an error.