RevMan Forest Plot

Overview

Generates a RevMan-style forest plot from study-level effect data. Uses a Python script with matplotlib for deterministic rendering.

Command

revman forest [--outcome <id>] [--output <file>]

Procedure:

1. If --outcome specified, read the outcome data from the active review's study data.

   • Determine active review from .revmanrc.
   • Read study files in {REVIEW_DIR}/.revman/studies/.
   • For each study with the specified outcome, extract TE and seTE.
   • Compute pooled estimate via inverse-variance meta-analysis.
   • If not, proceed with manual input.

2. If no outcome specified, ask the user for input method:

   Forest plot data source:
     1. Auto-generate from study outcome data in active review
     2. Manual entry (enter studies one by one)
   

3. For manual entry, collect studies interactively:

   • "Study label:" → label
   • "Effect estimate (TE):" → TE
   • "Standard error (seTE):" → seTE
   • "Weight (%):" → weight
   • "Events experimental / total:" → events_exp, total_exp
   • "Events control / total:" → events_ctrl, total_ctrl
   • "Add another study? (y/n):"
   • Then ask for effect measure (OR/RR/RD/MD/SMD) and scale (log/natural).

4. If ≥ 2 studies and no pooled data provided, compute fixed-effects pooled estimate:

   pooled_TE = Σ(w_i × TE_i) / Σ(w_i)  where w_i = 1/seTE_i²
   pooled_se = 1 / √Σ(w_i)
   

5. Build the JSON input:

   {
     "studies": [
       {"label": "Smith 2020", "TE": -0.5, "seTE": 0.3, "weight": 40,
        "events_exp": 10, "total_exp": 50, "events_ctrl": 20, "total_ctrl": 50}
     ],
     "pooled": {"TE": -0.52, "seTE": 0.2, "ci_lower": -0.91, "ci_upper": -0.13},
     "heterogeneity": {"i2": 28.3, "tau2": 0.01, "p_value": 0.21},
     "effect_measure": "OR",
     "scale": "log",
     "x_label": "Odds Ratio"
   }
   

6. Run:

   echo '<json>' | python3 scripts/revman-forest.py -o {output_path}
   

7. Output defaults to forest_plot.png in the review root (next to .revman/).

8. Confirm and display:

   Forest plot saved to reviews/{name}/forest_plot.png
   Studies: {N}  |  Pooled: {est} [{ci_low}, {ci_high}]
   Heterogeneity: I² = {i2}% | τ² = {tau2} | p = {p}
   

---

Script Location

scripts/revman-forest.py — Python 3. Accepts JSON on stdin, writes PNG.

---

Error Handling

| Situation | Response | |-----------|----------| | < 2 studies | "Need at least 2 studies for a forest plot." | | Script not found | "Forest plot script not found." | | No active review | "No active review. Use revman new or revman open first." | | No studies with that outcome | "No study data found for outcome {id}." |