Metadata-Version: 2.4
Name: ams-meta_analysis
Version: 0.1.10
Summary: Installable Streamlit GUI for R-backed Python meta-analysis runners.
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"

# Meta-Analysis Streamlit App

An installable Streamlit GUI for the R-backed Python meta-analysis runners in
`/Volumes/Firecuda-4TB/R-code_to-python`.

Author: Anuraj Sudhakaran.

The original source directory is treated as read-only. The runner files were
copied into this package under `meta_analysis_streamlit/runners/` so the app can
be installed and launched without editing the source folder.

## 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 LM Studio is not available

## Install

From PyPI after the first release:

```bash
python3 -m pip install ams-meta_analysis
meta-analysis-install-r --dry-run
meta-analysis-install-r
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"
```

From this folder:

```bash
python3 -m pip install -e ".[dev]"
```

For a normal local wheel install:

```bash
python3 -m pip install .
```

Launch the GUI:

```bash
ams-meta_analysis
```

## 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 LM Studio is unavailable, select Ollama in the
sidebar. The app suggests a local 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. If LM Studio is not reachable, it can use
Ollama as a local OpenAI-compatible provider. The sidebar estimates whether the
machine has GPU support and suggests one 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.

The project is ready to commit and push from
`/Volumes/Firecuda-4TB/meta-streamlit-app`.
