ams-meta-analysis 0.1.56

AMS Meta-Analysis Streamlit app by Anuraj Sudhakaran for R-backed evidence synthesis workflows.

AMS Meta-Analysis Streamlit App

Created by Anuraj Sudhakaran.

An installable Streamlit GUI for R-backed Python meta-analysis workflows, including workbook routing, pairwise analyses, diagnostic accuracy analyses, network meta-analysis, LLM-assisted study assessment, and in-app output review.

What It Runs

• Workbook-level auto routing through the original main.py
• Binary pairwise meta-analysis
• Continuous pairwise meta-analysis
• Single-arm proportion and mean meta-analysis
• Diagnostic accuracy meta-analysis
• Frequentist and Bayesian network meta-analysis
• LM Studio model detection, with manual study-characteristic controls when LM Studio is not reachable
• Ollama local model support at http://localhost:11434/v1, with hardware-aware model suggestions and CLI setup guidance when no local LLM is available

Install From PyPI

Use the PyPI package page:

https://pypi.org/project/ams-meta-analysis/

Install or upgrade the Python package:

python -m pip install --upgrade ams-meta_analysis

Install or repair the external R runtime and R packages:

meta-analysis-install-r --dry-run
meta-analysis-install-r --yes
meta-analysis-doctor

Launch the Streamlit GUI:

ams-meta_analysis

Example complete first-time setup:

python -m pip install --upgrade ams-meta_analysis
meta-analysis-install-r --yes
meta-analysis-doctor
ams-meta_analysis

If R is installed but Rscript is not on PATH, the app and command-line runner automatically try common R install locations and add the discovered Rscript folder to the current process and analysis runs. To add it permanently in your shell too, run the command shown by meta-analysis-doctor, for example:

export PATH="/Library/Frameworks/R.framework/Resources/bin:$PATH"

Images And Forest Plots

The PyPI package itself does not include study-specific screenshots or example forest plots because those are generated from the user's workbook. When an analysis produces images, the Streamlit app shows them in the Forest Plots viewer with previous/next controls and the selected image name. The same images are also saved in the selected output folder and included in the downloadable output zip.

The app also includes a Forest plot images to RM5 workflow. Use the sidebar workflow selector, choose a vision-capable LLM provider/model, then upload individual forest plot images or select a local image folder. The converter extracts dichotomous study event/total rows and writes per-outcome plus combined CSV files with the TSA Java RM5-converter headers. If a local LM Studio vision runtime rejects image preprocessing, the converter can fall back to local Tesseract OCR and send text only. It also writes incidence_by_study.csv and incidence_by_outcome.csv with event/total percentages while keeping the RM5 CSV layout TSA-compatible.

Examples

Binary adverse events. Upload a sheet with study labels plus treatment and control event/total columns. Choose Binary pairwise or let the app assess the sheet, then run to generate summaries, forest plots, and logs.

Multi-outcome workbook. Upload an Excel workbook with sheets such as Adverse Events, Clinical Success, Reintervention, and Length of Stay. Choose Select all sheets with Auto route workbook so the app can route each outcome to the appropriate runner and collect outputs.

Subgroups and meta-regression. Use the GUI to select columns such as etiology, control type, study design, publication year, or sample size. Supported pairwise runners pass those choices into subgroup and meta-regression analyses.

Local model assistance. If neither LM Studio nor Ollama is available, the sidebar shows local setup guidance. The app suggests an Ollama model based on available hardware and shows the CLI commands to install Ollama and pull the model.

Updates

The Streamlit sidebar includes a Package updates panel. It checks PyPI for a newer ams-meta_analysis release and can run the upgrade command from inside the app. When an update is available, the panel also shows a short What's included list with the release highlights:

python -m pip install --upgrade ams-meta_analysis

After an in-app update, use the Restart Streamlit App button so the running process loads the new package files.

The Streamlit run form includes an Analysis engine selector for auto-route, binary pairwise, continuous pairwise, single-arm, and diagnostic analyses. Use auto for LLM/runner recommendations, or choose frequentist, bayesian, or both. Network meta-analysis keeps a separate Network engine selector.

Local LLM Options

The app first checks LM Studio and Ollama. It only shows local install guidance when neither local provider is reachable. The sidebar estimates whether the machine has GPU support and suggests one Ollama model:

• CPU-only or lower-memory systems: llama3.2:3b
• GPU systems with typical memory: llama3.1:8b
• Higher-memory GPU systems: qwen3:14b

Install and start Ollama from the command line, then pull the suggested model:

# macOS with Homebrew
brew install --cask ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
winget install Ollama.Ollama

ollama serve
ollama pull llama3.2:3b

Run the original workbook orchestrator from the installed package:

meta-analysis-runner "/path/to/workbook.xlsx" --yes

Check the local environment:

meta-analysis-doctor

Install or repair the external R runtime after pip install:

meta-analysis-install-r --dry-run
meta-analysis-install-r

If R is already installed outside PATH, meta-analysis-install-r uses the discovered absolute Rscript path automatically when installing R packages. When R is missing, the Streamlit sidebar also shows an Install R Runtime button that runs the same setup helper from inside the app.

External Requirements

Python dependencies are installed by pip, but the statistical analyses still need R and the R packages used by the original generated scripts. The package does not silently install system software during pip install; instead it installs a helper command that shows and runs the platform-specific R setup:

meta-analysis-install-r --dry-run
meta-analysis-install-r

If you prefer to manage R yourself, install R, make sure Rscript is on PATH, then install the common R packages:

packages <- c(
  "meta",
  "metafor",
  "readxl",
  "dplyr",
  "ggplot2",
  "netmeta",
  "gemtc",
  "rjags",
  "RTSA"
)
if (.Platform$OS.type == "windows") {
  options(install.packages.compile.from.source = "never")
  install.packages(packages, repos = "https://cloud.r-project.org", type = "binary")
} else {
  install.packages(packages, repos = "https://cloud.r-project.org")
}

On older Windows R installations, the binary install path avoids CRAN choosing newer source packages that can fail during compilation.

Bayesian network meta-analysis also needs JAGS installed on the system.

Trial sequential analysis can use the external TSA engine expected by the original code. If needed, point to it with:

export TSA_ANALYSIS_PY="/path/to/tsa_analysis.py"

For a Java-TSA-style binary TSA directly from a forest plot image or binary event-count CSV, use:

meta-analysis-tsa-forestplot \
  --forest-plot "/path/to/forestplot.png" \
  --outcome-name "Mortality" \
  --output-dir "/path/to/tsa-output" \
  --write-ocr-text

The script writes .jpeg and .tiff figures plus the extracted TSA input rows, Z-curve CSV, boundary CSV, and JSON summary. Its dichotomous defaults mirror the TSA Java dialog settings: two-sided alpha 5%, power 80%, O'Brien-Fleming boundary, sample-size information axis, observed event incidences from the forest plot counts, and a model-variance-based required-information-size correction using DerSimonian-Laird with the Hartung-Knapp-Sidik-Jonkman variance, matching RTSA's default random-effects calculation path. Use --incidence-source specified to use manually supplied incidence percentages instead.

Continuous mean-difference outcomes use the same 5% type-I error, 80% power, two-sided O'Brien-Fleming boundary, sample-size information axis, inner-wedge style figure, empirical mean difference, empirical variance, and model-variance-based heterogeneity correction by default:

meta-analysis-tsa-forestplot \
  --outcome-type continuous \
  --forest-plot "/path/to/continuous-forestplot.png" \
  --outcome-name "Length of stay" \
  --output-dir "/path/to/tsa-output" \
  --plot-style tsa-software

To reproduce the continuous dialog values shown in TSA, add:

--mean-difference-source user-defined \
--mean-difference -6.7004 \
--variance-source user-defined \
--continuous-variance 335.3726 \
--heterogeneity-correction user-defined \
--heterogeneity-correction-percent 10

LLM Provider Behavior

By default, the app checks http://localhost:1234/v1 for LM Studio. If LM Studio is not available, it can use OpenAI-compatible hosted APIs instead.

Supported GUI options:

• LM Studio: http://localhost:1234/v1
• OpenAI: https://api.openai.com/v1
• Gemini through Google's OpenAI-compatible endpoint: https://generativelanguage.googleapis.com/v1beta/openai
• Custom OpenAI-compatible endpoint
• Manual/no LLM

The app auto-selects the first available option in this order: LM Studio, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY, META_ANALYSIS_LLM_API_KEY, then manual mode.

For command-line runs, hosted APIs can also be used with the original --lmstudio-url option because the packaged runners now support OpenAI-compatible authentication headers:

export META_ANALYSIS_LLM_API_KEY="$OPENAI_API_KEY"
meta-analysis-runner "/path/to/workbook.xlsx" \
  --lmstudio-url "https://api.openai.com/v1" \
  --model "your-model" \
  --yes

For Gemini:

export META_ANALYSIS_LLM_API_KEY="$GEMINI_API_KEY"
meta-analysis-runner "/path/to/workbook.xlsx" \
  --lmstudio-url "https://generativelanguage.googleapis.com/v1beta/openai" \
  --model "your-gemini-model" \
  --yes

When no provider is reachable, the GUI still works: it passes --no-lmstudio and asks you to choose basic study characteristics such as analysis route, binary effect size, single-arm outcome type, diagnostic mode, and network model settings.

Output Location

Uploaded workbooks and generated outputs are staged under:

~/.meta_analysis_streamlit/runs/

The app writes a run log and offers a zip download for completed outputs.

Development

Run the tests:

pytest

Build a wheel:

python3 -m build
python3 -m twine check dist/*

See PUBLISHING.md for PyPI release steps, including Trusted Publishing through GitHub Actions.