Metadata-Version: 2.4
Name: ams-meta_analysis
Version: 0.1.26
Summary: AMS Meta-Analysis Streamlit app by Anuraj Sudhakaran for R-backed evidence synthesis workflows.
Author: Anuraj Sudhakaran
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/your-org/ams-meta_analysis
Project-URL: Repository, https://github.com/your-org/ams-meta_analysis
Project-URL: Issues, https://github.com/your-org/ams-meta_analysis/issues
Keywords: streamlit,meta-analysis,lm-studio,r,evidence-synthesis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: streamlit>=1.34
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: xlrd>=2.0
Requires-Dist: python-docx>=1.1
Requires-Dist: Pillow>=10.0
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"

# 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/](https://pypi.org/project/ams-meta-analysis/)

Install or upgrade the Python package:

```bash
python -m pip install --upgrade ams-meta_analysis
```

Install or repair the external R runtime and R packages:

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

Launch the Streamlit GUI:

```bash
ams-meta_analysis
```

Example complete first-time setup:

```bash
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:

```bash
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.

## 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:

```bash
python -m pip install --upgrade ams-meta_analysis
```

After an in-app update, restart Streamlit so the running process loads the new
package files.

## 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:

```bash
# 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:

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

Check the local environment:

```bash
meta-analysis-doctor
```

Install or repair the external R runtime after pip install:

```bash
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:

```bash
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:

```r
install.packages(c(
  "meta",
  "metafor",
  "readxl",
  "dplyr",
  "ggplot2",
  "netmeta",
  "gemtc",
  "rjags",
  "RTSA"
))
```

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:

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

## 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:

```bash
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:

```bash
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:

```text
~/.meta_analysis_streamlit/runs/
```

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

## Development

Run the tests:

```bash
pytest
```

Build a wheel:

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

See [PUBLISHING.md](PUBLISHING.md) for PyPI release steps, including Trusted
Publishing through GitHub Actions.
