Metadata-Version: 2.4
Name: drisk
Version: 0.1.0
Summary: Composable tools for quick Monte Carlo modelling and distribution elicitation.
Project-URL: Documentation, https://nick-dorsch.github.io/drisk/
Project-URL: Repository, https://github.com/nick-dorsch/drisk
Project-URL: Issues, https://github.com/nick-dorsch/drisk/issues
Author: Nicholas Dorsch
License: MIT
License-File: LICENSE
Keywords: distributions,elicitation,monte-carlo,probability,simulation,uncertainty
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.12
Requires-Dist: matplotlib>=3.11.0
Requires-Dist: numpy>=2.2.4
Requires-Dist: pandas>=3.0.3
Requires-Dist: pydantic>=2.13.4
Requires-Dist: scipy>=1.17.1
Description-Content-Type: text/markdown

# drisk

Composable tools for quick Monte Carlo modelling, with an emphasis on distribution
elicitation and model composition.

`drisk` provides a compact, notebook-friendly API for probability distributions,
elicitation workflows, correlated sampling, decision trees, sensitivity analysis, and
composable Monte Carlo models.

> `drisk` is currently in alpha. APIs may change before a stable release.

## Links

- Documentation: <https://nick-dorsch.github.io/drisk/>
- Repository: <https://github.com/nick-dorsch/drisk>
- Issues: <https://github.com/nick-dorsch/drisk/issues>

## Installation

Install from PyPI:

```bash
pip install drisk
```

Or with `uv`:

```bash
uv add drisk
```

`drisk` requires Python 3.12 or newer.

## Quick start

```python
import drisk as dr

# Elicit a distribution from intuitive inputs.
dist = dr.LogitNormal.elicit(low=0.1, high=0.25)

# Draw Monte Carlo samples.
samples = dist.sample(1_000)
```

## Features

- Continuous distributions such as `Normal`, `LogNormal`, `LogitNormal`, `Beta`, `PERT`, `Gamma`, and `Exponential`
- Discrete distributions such as `Bernoulli`, `Binomial`, `Poisson`, `Geometric`, and `NegativeBinomial`
- Distribution elicitation, fitting, sampling, plotting, and serialization-friendly parameters
- Mixture distributions with `UvMixture`
- Correlation matrix helpers and Gaussian / Student-t copulas
- Composable Monte Carlo models via `MCModel`, `MCOperation`, and `where`
- Decision tree modelling with chance, decision, and outcome nodes
- One-at-a-time sensitivity analysis helpers

## Documentation

The documentation site includes examples and API reference pages:

<https://nick-dorsch.github.io/drisk/>

## Developer setup

This repository uses:

- [mise](https://mise.jdx.dev/) to install local development tools and run common project tasks
- [uv](https://docs.astral.sh/uv/) for Python dependency management and command execution

### 1. Install tools with mise

Install `mise` if you do not already have it, then install the tools pinned in
`.mise.toml`:

```bash
mise install
```

This installs the project Python version, `uv`, `ruff`, and other helper tools for the
repository.

### 2. Install Python dependencies with uv

Sync the project environment from `pyproject.toml` and `uv.lock`:

```bash
uv sync --all-groups
```

Use `uv run ...` for commands that should execute inside the managed environment:

```bash
uv run pytest
uv run ruff check .
uv run python -c "import drisk as dr; print(dr.Normal.elicit(0, 1))"
```

When adding dependencies, use `uv add` so `pyproject.toml` and `uv.lock` stay in sync:

```bash
uv add numpy
uv add --dev pytest
uv add --group docs jupyter
```

### 3. Run project tasks with mise

List available tasks:

```bash
mise tasks
```

Common tasks:

```bash
mise run test      # run the test suite
mise run lint      # run ruff checks
mise run format    # format the codebase
mise run check     # run lint and tests
mise run docs      # preview the Quarto documentation site
```

## Project layout

```text
src/drisk/
  copulas/                  # copula interfaces and implementations
  correlations/             # correlation matrix helpers
  decision/                 # decision tree nodes, branches, and trees
  distributions/            # distribution interfaces and implementations
  models/                   # composable Monte Carlo model helpers
  sensitivity/              # sensitivity analysis utilities
  arithmetic.py             # arithmetic/composition helpers
  random.py                 # seed/RNG helpers
  summary.py                # summary helpers

tests/                      # pytest suite
docs/                       # Quarto documentation site
```

## License

`drisk` is distributed under the MIT License. See [LICENSE](LICENSE) for details.
