# Plotting

Plotting is optional so the computational core can stay dependency-free.
Install the extra before using plotting:

```bash
pip install "evidencelib[plot]"
```

Every plotting function returns a Matplotlib `Axes` object and accepts an
existing `ax`.

## Mass bars

Use `MassFunction.plot()` for a compact horizontal bar chart.

```python
from evidencelib import Frame

frame = Frame.dst(["A", "B", "C"])
A, B, C = frame.symbols()

m = frame.mass({
    A: 0.35,
    B: 0.20,
    A | B: 0.25,
    C: 0.20,
})

ax = m.plot(title="Sensor mass assignment")
```

Function form:

```python
from evidencelib import plot_mass

ax = plot_mass(m, top_n=8, min_mass=0.02)
```

> **Use when:** you want to inspect where a single source placed its support.

Turn off labels or provide colors explicitly:

```python
ax = plot_mass(m, colors="#3f566a", annotate=False)
```

For proposition-kind coloring, pass a mapping:

```python
ax = plot_mass(
    m,
    colors={
        "singleton": "#222222",
        "union": "#ff7f0e",
        "compound": "#2ca02c",
        "empty": "#d62728",
        "total": "#7f7f7f",
    },
    show_kind_legend=True,
)
```

`colors` accepts any Matplotlib color, a list of colors, or a palette from
another library:

```python
import seaborn as sns

palette = sns.color_palette("colorblind", n_colors=4)
ax = plot_mass(m, colors=palette)
```

## Source comparison

```python
ax = m1.plot_comparison(m2, labels=["sensor", "expert"])
```

or:

```python
from evidencelib import plot_mass_comparison

ax = plot_mass_comparison([m1, m2], labels=["sensor", "expert"])
```

All compared mass functions must belong to the same `Frame` instance. The
default heatmap uses Matplotlib's `Greens` colormap.

```python
ax = plot_mass_comparison([m1, m2], cmap="viridis")
ax = plot_mass_comparison([m1, m2], cmap=["#ffffff", "#08519c"])
```

> **Use when:** you want to compare how several sources distribute mass over
> the same propositions.

Annotated heatmap cells automatically switch text color for contrast. Adjust
the switch point when needed:

```python
ax = plot_mass_comparison(
    [m1, m2],
    annotation_text_colors=("black", "white"),
    annotation_threshold=0.5,
)
```

## Venn regions

Use `MassFunction.plot_venn()` for compact one-, two-, or three-hypothesis
Venn-style diagrams.

```python
frame = Frame.dsmt(["A", "B"])
A, B = frame.symbols()

m = frame.mass({
    A: 0.2,
    B: 0.3,
    A & B: 0.4,
    A | B: 0.1,
})

ax = m.plot_venn()
```

By default, region values come from `pignistic_regions()`, so the labels show a
probability distribution over disjoint model regions. Pass `values="mass"` to
show only direct mass assigned to elementary Venn regions.

```python
ax = m.plot_venn(labels=["sensor A", "sensor B"], values="mass")
```

> **Use when:** you want to inspect how belief mass has been distributed over
> the disjoint regions of a small DSmT or hybrid DSm frame.

## Belief and decisions

```python
m.plot_belief_plausibility()
m.plot_pignistic_decision()
```

The first plot shows belief-plausibility support intervals for singleton
hypotheses. The second plot ranks singleton hypotheses by pignistic score.

```python
ax = m.plot_pignistic_decision(highlight_decision=False, annotate=False)
```

> **Use when:** you want a quick visual check before selecting a decision rule
> or threshold.

## Filtering and composition

Plot only selected propositions or hypotheses:

```python
plot_mass(m, top_n=5, min_mass=0.05, show_other=False)
plot_venn(m, show_region_labels=True)
plot_belief_plausibility(m, hypotheses=["A", "B"], show_pignistic=False)
plot_pignistic_decision(m, top_n=3)
plot_mass_comparison([m1, m2], top_n=6, min_total_mass=0.05)
```

Compose plots into your own figure:

```python
import matplotlib.pyplot as plt
from evidencelib import plot_mass, plot_venn, plot_belief_plausibility, plot_pignistic_decision

fig, axes = plt.subplots(1, 4, figsize=(17, 4.5))

plot_mass(m, ax=axes[0], title="Mass assignment")
plot_venn(m, ax=axes[1], title="Venn regions")
plot_belief_plausibility(m, ax=axes[2], title="Support intervals")
plot_pignistic_decision(m, ax=axes[3], title="Decision ranking")

fig.tight_layout()
```

## Example script

```bash
python examples/plotting.py --figure models --model dst
python examples/plotting.py --figure models --model hybrid --symbols A B C D
python examples/plotting.py --figure venn
python examples/plotting.py --figure belief
python examples/plotting.py --figure pignistic
```

Use `--save-dir` to save PNG files without opening interactive windows:

```bash
python examples/plotting.py --figure all --save-dir /tmp/evidencelib-plots
```