Metadata-Version: 2.4
Name: brmspy
Version: 0.1.0
Summary: Pythonic interface to the brms R package using CmdStanPy
Author-email: Remi Sebastian Kits <remi.sebastian.kits@gmail.com>, Adam Haber <adamhaber@gmail.com>
Maintainer-email: Remi Sebastian Kits <remi.sebastian.kits@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/kaitumisuuringute-keskus/brmspy
Project-URL: Repository, https://github.com/kaitumisuuringute-keskus/brmspy
Project-URL: Documentation, https://kaitumisuuringute-keskus.github.io/brmspy/
Project-URL: Bug Tracker, https://github.com/kaitumisuuringute-keskus/brmspy/issues
Project-URL: Original Repository, https://github.com/adamhaber/brmspy
Project-URL: Changelog, https://github.com/kaitumisuuringute-keskus/brmspy/blob/master/CHANGELOG.md
Keywords: bayesian,regression,brms,stan,cmdstan,rpy2,multilevel-models,statistical-modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: R
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cmdstanpy>=1.2.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: rpy2>=3.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: jupyter>=1.0.0; extra == "docs"
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Provides-Extra: viz
Requires-Dist: arviz>=0.15.0; extra == "viz"
Requires-Dist: matplotlib>=3.5.0; extra == "viz"
Requires-Dist: seaborn>=0.12.0; extra == "viz"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Provides-Extra: all
Requires-Dist: brmspy[dev,docs,test,viz]; extra == "all"
Dynamic: license-file

# brmspy

**Pythonic interface to R's brms for Bayesian regression modeling**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

brmspy brings the power of [brms](https://paul-buerkner.github.io/brms/) (Bayesian Regression Models using Stan) to Python, providing proper parameter names and seamless integration with the Python Bayesian ecosystem.

## Quick Start

```bash
pip install brmspy
```

```python
import brmspy

# One-time setup: install brms and CmdStan
brmspy.install_brms()

# Load example data
epilepsy = brmspy.get_brms_data("epilepsy")

# Fit model - returns arviz InferenceData by default
model = brmspy.fit(
    formula="count ~ zAge + zBase * Trt + (1|patient)",
    data=epilepsy,
    family="poisson",
    chains=4,
    iter=2000
)
idata = model.idata

# Analyze with arviz
import arviz as az
az.plot_posterior(idata)
az.summary(idata)
```

## Key Features

- **Proper Parameter Names**: Returns `b_Intercept`, `b_zAge`, `sd_patient__Intercept` (not `b_dim_0`, `sd_1_dim_0`)
- **Pythonic by Default**: Returns `arviz.InferenceData` for seamless Python integration
- **Flexible**: Optional R `brmsfit` return for full brms functionality
- **Formula Syntax**: Use brms' intuitive formula interface
- **Modern Stack**: Python 3.8-3.14, brms + cmdstanr backend

## Installation

```bash
# Install from PyPI
pip install brmspy

# Install with optional dependencies
pip install brmspy[viz]    # includes arviz, matplotlib
pip install brmspy[all]    # includes all optional dependencies

# First-time setup (installs brms and CmdStan in R)
python -c "import brmspy; brmspy.install_brms()"
```

**Note:** The package is imported as `brmspy` but installed as `brmspy` from PyPI.

## Usage

### Basic Model

```python
import brmspy
import arviz as az

# Load data
kidney = brmspy.get_brms_data("kidney")

# Fit Gaussian model
idata = brmspy.fit(
    formula="time ~ age + disease",
    data=kidney,
    family="gaussian",
    return_type="idata"
)

# View summary
az.summary(idata)
```

### With Priors

```python
idata = brmspy.fit(
    formula="count ~ zAge + (1|patient)",
    data=epilepsy,
    family="poisson",
    priors=[
        ("normal(0, 0.5)", "b"),
        ("cauchy(0, 1)", "sd")
    ],
    return_type="idata"
)
```

### Return Type Options

```python
# Default: arviz InferenceData (Pythonic)
idata = brmspy.fit(..., return_type="idata")
az.plot_posterior(idata)

# R brmsfit object (for advanced R users)
fit = brmspy.fit(..., return_type="brmsfit")
import rpy2.robjects as ro
ro.globalenv['fit'] = fit
ro.r('summary(fit)')

# Both formats
result = brmspy.fit(..., return_type="both")
az.plot_posterior(result.idata)  # Python
# result.brmsfit for R methods
```

### Sampling Parameters

```python
model = brmspy.fit(
    formula="y ~ x",
    data=data,
    iter=2000,      # Total iterations per chain
    warmup=1000,    # Warmup iterations
    chains=4,       # Number of chains
    cores=4,        # Parallel cores
    seed=123        # Reproducibility
)
```

## Requirements

**Python**: 3.8+

**R Packages** (auto-installed):
- brms ≥ 2.20.0
- cmdstanr
- posterior

**Python Dependencies**:
- rpy2 ≥ 3.5.0
- pandas ≥ 1.3.0
- numpy ≥ 1.20.0
- arviz (optional, for InferenceData conversion)

## Development

```bash
# Clone repository
git clone https://github.com/kaitumisuuringute-keskus/brmspy.git
cd brmspy

# Setup environment (requires Python 3.8+)
./init-venv.sh

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=brmspy --cov-report=html
```

## License

Apache License 2.0

## Credits

- Original concept: [Adam Haber](https://github.com/adamhaber)
- v0.1.0 modernization: [Remi Sebastian Kits](https://github.com/braffolk)
- Powered by [brms](https://paul-buerkner.github.io/brms/) by Paul-Christian Bürkner
