ActiLab.eu

ProMeta CLI usage

Using an AI assistant with the CLI? Read AI and statistical analysis first: what AI is good for around meta-analysis, where it is risky, and why a script beats a chat window.

prometa-cli is the command-line application for ProMeta workflows. It depends on the core statistics package, source interoperability package, plot packages, and plot adapters.

This is a full reference, but for the exact options a given command takes, run it with --help — that's always correct and up to date, unlike prose that has to be updated by hand. If you're an AI agent using this CLI on someone's behalf, check --help output for a command's exact flags rather than guess them; this doc is enough context to know which command to reach for.

prometa --help              # list every command
prometa <command> --help    # options for one command
prometa manual               # print this document to the console

Commands, by workflow

Source datasets

A source dataset (CSV or JSON) is the input everything else works from — one row per study, one column per raw effect-size input. These commands create, inspect, and maintain one.

Command What it does
source-init Create an empty source CSV or JSON dataset
source-add-row Append one row (study) to a source dataset
source-add-moderator Add one empty moderator column to a source dataset
source-schema Show which fields a given raw input format expects
inspect Summarize an existing dataset's structure
validate Check a dataset against the source-dataset schema
convert-source Convert a dataset between supported file formats (e.g. CSV ↔ JSON)
import-pm3 Extract a source CSV / modern project from a legacy ProMeta 3 .prm file
csv-to-prometa Turn a source CSV into a minimal .prometa project file (dataset rows only; --project-name names the project)
prometa-to-csv Extract the dataset of a .prometa project file as a source CSV; analyses, filters and the other project data are not exported, and the command says so

Analysis

Run on a validated source dataset to produce the pooled result and its diagnostics.

Command What it does
summary Estimate the pooled effect size. With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less
heterogeneity Heterogeneity report for the chosen model and estimator: pooled effect, Q, tau²/tau, I², prediction interval, by-level I² (multilevel he, che)
prediction-interval Prediction interval for the effect of a new study (--plot-csv/--plot-json/--plot-svg give the forest plot rows: studies, overall, interval)
sensitivity Leave-one-out sensitivity analysis. With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less
influence Case-deletion influence diagnostics (rstudent, DFFITS, Cook's distance, hat values, covariance ratio)
cumulative Cumulative meta-analysis (studies added one at a time; with --model multilevel, one whole study per step). With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less
pre-analysis Explore subgroup, comparison, timepoint, and outcome dimensions before committing to a model. Fixed-effect and random-effects models only: --model multilevel stops with an error. With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less

Moderators

For testing whether a categorical or continuous moderator explains some of the heterogeneity.

Command What it does
moderator-levels Compare effect sizes across levels of a categorical moderator. Fixed-effect and random-effects models only: --model multilevel stops with an error. With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less
multi-moderator-regression Regress on one or more moderators at once (--moderators a,b,a:b for interactions), with a joint significance test; with a single numerical moderator --plot-svg draws the scatter plot with the regression line (--template customizes it). Variance components by REML, ML or, for the random-effects model, DL (--tau2-method) or, for the multilevel models HE and CE with --cluster-robust, the method of moments (--approximate-weights); cluster-robust variance with the CR1, CR2 or CR3 adjustment (--cluster-robust-variant). With --model multilevel it also fits subgroup correlated effects (--category-moderator), CHE+ with the studies grouped by a categorical moderator (--group-moderator) and ACHE with the time of each effect from a numerical moderator (--time-moderator --autocorrelation); each replaces --multilevel-model and they exclude one another. --base-terms compares the model with a nested smaller one by a likelihood-ratio test (both fitted by ML). The output also gives AIC/BIC, residual heterogeneity and R², and warns about collinear predictors and few studies per characteristic
permutation-test Permutation test of the regression coefficients and of the omnibus test (--moderators, --model fixed|random, --tau2-method REML|ML, --permutations, 1000 by default, fixed seed; exact when all permutations can be enumerated). Not available for the multilevel models; slow with many studies
moderator-cumulative Cumulative meta-analysis ordered by a moderator, instead of by time. With --cluster-robust (CR2, or --cluster-robust-variant CR1 or CR3) each pooled estimate has a cluster-robust variance clustered by study (standard error, interval and p value from the Satterthwaite degrees of freedom, column df), replacing --knapp-hartung; it warns when the degrees of freedom are 4 or less

Publication bias

Command What it does
publication-bias Fail-Safe N, Egger's regression, PET-PEESE, Begg and Mazumdar's test, trim-and-fill, in one pass. With several effects per study the tests that assume independence print a warning; the mixed-effects Egger test and PET-PEESE use the hierarchical-effects model by default (--model multilevel --multilevel-model … to change it) and take --precision-measure sampleSize for standardized mean differences. --egger-variant chooses Egger's test: classic, mixedEffects, or sandwich (cluster-robust, for dependent effects)
limit-meta-analysis Treatment effect adjusted for small-study effects, by the limit meta-analysis of Rücker et al. (2011): limit expectation (β₀), limit regression slope (β_lim), limit mean (μ_lim) and small-study effect (α_R), each with standard error, confidence interval and p-value; also Q, Q − Q', Q' (with p-values) and G² (heterogeneity left once small-study effects are allowed for). --tau2-method (default DL); --plot-svg also draws the original, generalized and limit radial plots (one SVG each, the plot's name added to the file name); --output-csv is one long table with the same columns on every row, its group column telling the section (adjusted effect, small-study effect, heterogeneity); assumes independent effects and warns below 10 studies
peters-test Peters et al. (2006) test of funnel-plot asymmetry for log odds ratios: weighted regression of the log odds ratio on the inverse of the total sample size, with the weights (a+b)(c+d)/n of Macaskill et al. (2001) and a t-test on the slope (--z-test for a Wald z-test). Needs -e Log_Odds_ratio and the 2×2 table of every study (a raw effect size from events and non-events or sample sizes); refuses other effect sizes and studies without one; --plot-svg draws the log odds ratios against 1/n with the fitted line
time-lag Time-lag bias (decline effect): mixed-effects regression of the effect size on the years elapsed since the first study, with the publication year as numerical --moderator. --time-lag-transform linear|log|inverse (Nakagawa et al. 2022); the three-level (HE) model handles several effects per study; --time-lag-z-test for a Wald z-test; --plot-svg draws the effect sizes against the year with the fitted line or curve (--template customizes it)
trim-and-fill Trim-and-fill on its own, optionally saving a funnel plot
selection-model Selection-model based publication-bias correction
copas Copas & Shi (2000) selection-model sensitivity analysis for publication bias: fits the model over a grid of selection parameters (--copas-ngrid, --copas-side, --copas-rho-bound, --copas-residual-bias-threshold; the --copas-gamma0-range and --copas-gamma1-range are advanced)

Plots

Render analysis results as SVG. The render-* commands only draw what they are given: they compute nothing, and read plain CSV files (plus the optional TOML --template), never an app file. The analysis commands that draw a plot can write those CSVs with --plot-csv (see --help). Template checkers and renderers live in the standalone plot packages (prometa-forest-plot, prometa-funnel-plot, prometa-scatter-plot); analysis-to-plot conversion lives in prometa-plot-adapters.

Command What it does
render-forest Forest plot from forest-plot rows (from an analysis command's --plot-csv, or written by hand: a type of Study, Overall or PredictionInterval; graph.display.predictionIntervals = false in the template hides the latter). forest-plot is its former name, kept as a deprecated alias
render-funnel Funnel plot from a studies CSV with the columns group (observed or imputed), name, effectSize, standardError, with --overall (and --adjusted-overall for --show-estimate); --title, --z-score (default 1.96). trim-and-fill and publication-bias write the CSV with --plot-csv and print the two effects
render-scatter Scatter plot from a points CSV with the columns name, moderatorValue, effectSize, weight (the point size), with the regression line --slope and --intercept, or a fitted curve from --curve-csv (columns x, y); --title. multi-moderator-regression (single numerical moderator) and time-lag write the CSVs with --plot-csv and print the coefficients
render-radial Radial plot from a studies CSV (name, effectSize, precision) and an elements CSV (--elements-csv) with one row per line (slope, intercept, optional role origin/fitted and dashed), at most one cone (slope, intercept, zCritical) and at most one arc (estimate, ciLowerBound, ciUpperBound); the other columns stay empty. --x-axis-label, --z-axis-label. radial-plot and limit-meta-analysis write both with --plot-csv (the elements as <name>-elements.csv)
radial-plot Radial (Galbraith) plot: standardized effect vs. precision, with a confidence cone — a heterogeneity-outlier diagnostic; generalized (τ² in the weights) with a random-effects model; --intercept-line adds the best-fitting line with an intercept (not with fewer than 3 studies or almost equal precisions); --no-arc drops the cone and the reading arc
plot-template Write the default TOML template of a plot type (forest, funnel, scatter, radial) to customize it

Reference / lookup

Don't touch your data — list what the CLI supports, for scripting or documentation purposes.

Command What it does
effect-sizes List output effect-size metrics accepted by --effect-size
raw-formats List raw effect-size input formats source datasets can use
formula-references List documented formulas/algorithms with their citations
bibliography List the real-world sources cited by the underlying formulas

Inputs and outputs

Common inputs are CSV, JSON, TOML template files, and CLI options. Source dataset commands use the JSON schema in docs/schemas/prometa-source-dataset.schema.json. Commands write human-readable text, CSV/JSON datasets, or SVG plots depending on the command; plot commands use TOML templates where supported.

Most analysis commands (summary, heterogeneity, sensitivity, …) print a human-readable table by default, but also accept --output-json <path> (and --plot-json <path> for the forest-plot rows a command generates). If something downstream — a script, another command, an AI agent — is going to read the result back, use the JSON output instead of parsing the printed table: it's structured, and its field names don't change between a terminal-width table and a redirected file the way column alignment can.

heterogeneity is the exception to "same data on screen and in the file": it prints the same complete tables (chosen-model effect sizes, heterogeneity, prediction interval), but --output-csv / --output-json hold only the essential figures as one flat record — model, tau² estimator, rho (the assumed within-study correlation, multilevel ce and che models only), Q, df, p, tau²/tau, I² (T²/(T² + s²) with the chosen tau², so it equals (Q − df)/Q only for DL; null for the he and che models), its confidence interval I2_lower/I2_upper and the method behind it I2_intervalMethod (testBased for the fixed-effect model, qProfile for the random-effects model; empty for the multilevel models, and when the interval does not exist), sigma2Within and the by-level I² (he and che models only), and the prediction interval limits. A value that does not exist for the chosen model is empty (CSV) or null (JSON). For the per-study rows, export a summary instead (summary --model fixed).

Interactive mode

Every command that needs input accepts -i / --interactive to be prompted for missing values instead of passing them as options. Interactive prompts collect the same values as the non-interactive options and run the same schema/range checks, so scripted and interactive use behave consistently — anything you do pass as an option is used as-is and simply not prompted for.

For example, prometa source-add-row --input-csv studies.csv --raw-effect-size-id 1100 --interactive prompts, in order: Study, then Subgroup / Comparison / Timepoint / Outcome (each defaults to its placeholder if left blank), then one prompt per raw field for format 1100 — Mean group A, Standard deviation group A, Sample size group A, Mean group B, Standard deviation group B, Sample size group B, and Effect direction (allowed: auto | positive | negative), defaulting to auto. Leaving --raw-effect-size-id off too would add one more prompt in front for it.

A typical pipeline

prometa source-init --output-csv studies.csv --raw-effect-size-id 1100
# ... fill in studies.csv, one row per study ...
prometa validate --input-csv studies.csv -e Hedges_s_g
prometa summary --input-csv studies.csv -e Hedges_s_g --plot-csv forest-rows.csv
prometa render-forest --input-csv forest-rows.csv --output-svg forest.svg --null-value 0

summary --prediction-interval adds the prediction interval to the forest plot rows, after the overall row (with the multilevel hierarchical-effects model, two rows); --prediction-interval-label sets its label ({level} stands for the confidence level, default {level}% prediction interval), and the prediction-interval command accepts the same label option.

Exact option names vary by command and by effect-size type — --help on each command is the source of truth.

Worked example: adding a row to a source CSV

Every source row needs a raw effect-size format id, which tells the CLI which columns (--data fields) that row needs. List the formats:

prometa raw-formats

This prints every supported format grouped by category and design, each with its numeric id and required field keys — for example 1100 under "Means → Two Independent Groups, Cross Sectional". Get the exact column names and types for one format with:

prometa raw-formats --format 1100
Field Type Description
group_a_mean number Mean group A
group_a_sd StandardDeviation Standard deviation group A
group_a_n SampleSize Sample size group A
group_b_mean number Mean group B
group_b_sd StandardDeviation Standard deviation group B
group_b_n SampleSize Sample size group B
effect_direction EffectDirection Effect direction

The Field column (group_a_mean, group_a_sd, …) is exactly what --data expects as NAME=VALUE pairs. With that, create the dataset and add one row:

prometa source-init --output-csv studies.csv --raw-effect-size-id 1100

prometa source-add-row \
  --input-csv studies.csv \
  --raw-effect-size-id 1100 \
  --study "Smith2020" \
  --data group_a_mean=12.4 \
  --data group_a_sd=3.1 \
  --data group_a_n=30 \
  --data group_b_mean=9.8 \
  --data group_b_sd=2.9 \
  --data group_b_n=28 \
  --data effect_direction=auto

studies.csv now has a header and one row:

study,rawEffectSizeId,group_a_mean,group_a_sd,group_a_n,group_b_mean,group_b_sd,group_b_n,effect_direction,subgroup,comparison,timepoint,outcome
Smith2020,1100,12.4,3.1,30,9.8,2.9,28,auto,NO-SUBGROUP,NO-COMPARISON,NO-TIMEPOINT,UNKNOWN-OUTCOME

A few things worth knowing about the fields above:

Or just edit the file directly

source-add-row isn't the only way to add rows — the source file is a plain CSV, so once you know the column names for your raw effect-size format (from raw-formats --format <id>, same as above), you can just open it in a text editor or a spreadsheet program (Excel, LibreOffice Calc, Google Sheets) and fill in rows directly, exactly like any other CSV. source-init still saves a step by writing the correct header row for you; after that, pasting or typing values into the spreadsheet is often faster than one source-add-row command per study, especially with many rows. Run prometa validate --input-csv studies.csv -e Hedges_s_g afterwards either way, to catch typos or out-of-range values before running an analysis.