Metadata-Version: 2.4
Name: evtools-dst
Version: 0.27.1
Summary: Evidence Theory Tools — a Python library for working with belief functions in the Dempster-Shafer theory
Project-URL: Homepage, https://github.com/evtools-team/evtools
Project-URL: Repository, https://github.com/evtools-team/evtools
Project-URL: Issues, https://github.com/evtools-team/evtools
Keywords: belief functions,Dempster-Shafer,evidence theory,mass function,plausibility,commonality,implicability,transferable belief model,Fast Möbius Transform,combination rules,conjunctive rule,disjunctive rule,cautious rule,discounting,contextual discounting,contextual reinforcement,contextual correction,de-discounting,negating,information fusion
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: tf
Requires-Dist: tensorflow>=2.10; extra == "tf"
Provides-Extra: optuna
Requires-Dist: optuna>=3.0; extra == "optuna"

# evtools

**Evidence Theory Tools** — a Python library for working with belief functions
in the Dempster-Shafer theory. Version 0.27.1.

## Modules

| Module | Description |
|--------|-------------|
| `evtools.dsvector` | `DSVector` — unified container for any belief function representation |
| `evtools.classifiers` | Evidential pattern classifiers: `EkNN` (k-NN), `ENN` (NumPy / L-BFGS-B), `ENNTorch` / `ENNTF` (PyTorch / TF deep-pipeline heads), `ThetaCDENNTorch` (Θ-contextual discounting ENN, Diène et al. 2026) |
| `evtools.combinations` | Combination rules: CRC, Dempster, DRC, Cautious, Bold, and decombinations |
| `evtools.corrections` | Correction mechanisms: discounting, reinforcement, negating |
| `evtools.decision` | Decision criteria: maximin, maximax, pignistic, plp, hurwicz, dominance |
| `evtools.metrics` | Performance metrics: discounted_accuracy, u65, u80, pl_loss + aggregators; selective-classification helpers (uncertainty_max_bel, error_rejection_curve, auerc) |
| `evtools.learning` | Learning of contextual corrections (fit_cd, fit_cr, fit_cn), per-group learning (fit_per_group, apply_per_group), and soft-label generation (hard_to_soft_labels) |
| `evtools.display` | Display formats: ANSI terminal, plain text, HTML, LaTeX |
| `evtools.conversions` | Low-level conversions via the Fast Möbius Transform |
| `evtools.constants` | Numerical tolerance constants |

---

## `evtools.dsvector`

`DSVector` is the central object of evtools. It represents any belief function
as a vector on `2^Ω`, in both **sparse** (dict) and **dense** (numpy array)
forms. The sparse representation is the master; the dense array is computed
on demand and cached.

### Kind enum

| `Kind` | Symbol | Name |
|--------|--------|------|
| `Kind.M`   | `m`   | Basic Belief Assignment (mass function) |
| `Kind.BEL` | `bel` | Belief function |
| `Kind.PL`  | `pl`  | Plausibility function |
| `Kind.B`   | `b`   | Implicability function |
| `Kind.Q`   | `q`   | Commonality function |
| `Kind.V`   | `v`   | Disjunctive weight function |
| `Kind.W`   | `w`   | Conjunctive weight function |

### Constructors

```python
from evtools.dsvector import DSVector, Kind

# Human-friendly: name focal elements as strings
# Missing mass is automatically assigned to Ω
m = DSVector.from_focal(["a", "b", "c"], {"a": 0.3, "b,c": 0.5})

# From a dense numpy array (binary index ordering, Smets 2002)
m = DSVector.from_dense(["a", "b", "c"], np.array([0, 0.3, 0, 0, 0.5, 0, 0, 0.2]))

# From a sparse dict of frozensets
m = DSVector.from_sparse(["a", "b", "c"], {
    frozenset({"a"}):         0.3,
    frozenset({"b","c"}):     0.5,
    frozenset({"a","b","c"}): 0.2,
})
```

### Simple MF constructors

Simple MFs are the elementary building blocks of correction mechanisms.

```python
# Simple MF A^β — focal sets Ω (mass β) and A (mass 1-β)
# Used in Contextual Reinforcement (CR), CdR, CN
s = DSVector.simple(["a", "b", "c"], frozenset({"a"}), beta=0.6)

# Negative simple MF A_β — focal sets ∅ (mass β) and A (mass 1-β)
# Used in Contextual Discounting (CD), CdD
ns = DSVector.negative_simple(["a", "b", "c"], frozenset({"a"}), beta=0.4)
```

### Conversions

```python
pl  = m.to(Kind.PL)   # returns a new DSVector with kind=Kind.PL
bel = m.to_bel()      # shortcut
b   = m.to_b()        # implicability
q   = m.to_q()        # commonality
v   = m.to_v()        # disjunctive weights (requires subnormal BBA, m(∅) > 0)
w   = m.to_w()        # conjunctive weights (requires non-dogmatic BBA, m(Ω) > 0)
```

### Accessing values

```python
m.sparse                     # dict[frozenset, float]
m.dense                      # np.ndarray of length 2^n
m.is_valid                   # True if all masses ≥ 0 and sum = 1 (Kind.M only)
m[frozenset({"a"})]          # value for a given subset (0.0 if absent)
for subset, value in m: ...  # iterate over non-zero focal elements
```

### Display

```python
m.to_ansi()    # colored terminal (also used by __repr__)
m.to_string()  # plain text, no colors
m.to_html()    # HTML table (Jupyter renders this automatically)
m.to_latex()   # LaTeX tabular for papers

# Multi-representation table: m + bel + pl + b + q (+ v if subnormal, + w if non-dogmatic)
m.to_string(all_kinds=True)
m.to_latex(all_kinds=True)
```

---

## `evtools.classifiers`

Evidential pattern classifiers — Dempster-Shafer alternatives to standard
sklearn classifiers. All share an sklearn-style API (`fit`, `predict`,
`predict_bba`) and return BBAs as `DSVector` instances, so they integrate
naturally with the rest of evtools (decision criteria, metrics, corrections).

| Class       | Backend       | Use case |
|-------------|---------------|----------|
| `EkNN`      | NumPy / SciPy | Evidential k-Nearest Neighbor (Denoeux 1995, Zouhal & Denoeux 1998). Stores the training set; the K nearest neighbors of a query produce K BBAs combined with Dempster's rule. |
| `ENN`       | NumPy / SciPy | Evidential Neural Network (Denoeux 2000). K learned prototypes, each producing a BBA; jointly optimized with L-BFGS-B and an analytical gradient (~25× faster than finite differences). |
| `ENNTorch`  | PyTorch       | Same architecture as `ENN`, trained via autograd. Suitable as a head on top of a deep feature extractor (CNN, ViT, ...). Optional — requires `pip install evtools-dst[torch]`. |
| `ENNTF`     | TensorFlow / Keras | TF/Keras mirror of `ENNTorch`. Same API, same architecture. Optional — requires `pip install evtools-dst[tf]`. |
| `ThetaCDENNTorch` | PyTorch | **Θ-Contextual Discounting ENN** (Diène et al. 2026). Generalizes both `ENN` (recovered with `theta="trivial"`) and CDENN (`theta="singletons"`) to any partition Θ of the frame. Output BBAs can have any focal subset of Ω. Optional — requires `[torch]`. |

### EkNN

```python
from evtools.classifiers import EkNN

clf = EkNN(k=5, optimize=True).fit(X_train, y_train)
y_pred = clf.predict(X_test)              # hard labels
bbas   = clf.predict_bba(X_test)          # list[DSVector]
```

### ENN (NumPy reference)

```python
from evtools.classifiers import ENN

# Default: loss="ce_plp" (cross-entropy of plausibility transform)
clf = ENN(n_prototypes=10, max_iter=300, random_state=0).fit(X_train, y_train)
y_pred = clf.predict(X_test)
bbas   = clf.predict_bba(X_test)

# Alternative: loss="pl_loss" (Pl-MSE form, historical default of Denoeux 2000)
clf_pl = ENN(loss="pl_loss", lambda_=1.0,
             n_prototypes=10, random_state=0).fit(X_train, y_train)

# Built-in prototype pruning via L1 regularization on the activations alpha_k
# (Denoeux 2000, App. B). Useful when n_prototypes is intentionally oversized.
clf_sparse = ENN(n_prototypes=20, mu=0.05, random_state=0).fit(X_train, y_train)
n_active = (clf_sparse.alphas_ > 0.1).sum()  # e.g. 7 / 20 — prototypes pruned

# Soft labels: pass a list[DSVector] sharing the same frame
from evtools.dsvector import DSVector
soft_labels = [DSVector.from_focal(["A", "B", "C"], {"A": 0.7}) for _ in y_train]
clf_soft = ENN(n_prototypes=10, random_state=0).fit(X_train, soft_labels)
```

### ENNTorch / ENNTF (deep-pipeline heads)

The PyTorch and TensorFlow versions expose the same sklearn-style wrapper,
plus access to the underlying `torch.nn.Module` (resp. `tf.keras.Model`) for
plugging into deeper pipelines:

```python
# PyTorch — plug ENNNet behind any feature extractor
from evtools.classifiers.enn_torch import ENNNet, ce_plp_loss_torch, pl_loss_torch

backbone = MyResNet()                       # outputs (N, 128) features
head     = ENNNet(K=20, M=10, d=128)        # ENN head
optimizer = torch.optim.Adam(
    list(backbone.parameters()) + list(head.parameters()), lr=1e-3)
for x, y_one_hot in loader:
    bbas = head(backbone(x))                # (N, M+1) tensor
    # CE-plp (default): cross-entropy of plausibility transform
    loss = ce_plp_loss_torch(bbas, y_one_hot)
    # Or Pl-loss: loss = pl_loss_torch(bbas, y_one_hot, lambda_=1.0)
    loss.backward(); optimizer.step()
```

The `ENNTorch` and `ENNTF` wrappers also provide `.load_from_enn(enn_np)` and
`.export_to_enn()` to transfer parameters back and forth with the NumPy `ENN`,
so you can train with autograd then export for an analytical-gradient setup
with no Torch / TF dependency.

### Θ-CDENN (Diène et al. 2026)

`ThetaCDENNTorch` generalizes `ENN` and CDENN by allowing **any partition
Θ of the frame Ω** as the granularity at which prototype reliability is
modeled (Mercier et al. 2008's Θ-contextual discounting). For a partition
of size L, each prototype carries one γ per partition element (so L γ
parameters per prototype, vs 1 for `ENN` and `M` for CDENN).

```python
from evtools.classifiers import ThetaCDENNTorch

# theta="trivial" (Θ = {Ω})       → recovers ENN
# theta="singletons" (Θ = {{c}})  → recovers CDENN
# theta = list of sets/frozensets → custom coarsening
clf = ThetaCDENNTorch(theta=[{"a", "b"}, {"c"}],
                      n_prototypes=10, loss="ce_plp",
                      max_iter=200, lr=0.05, random_state=0).fit(X, y)
clf.predict_contour(X_test)        # (N, M)  fast plausibility transform
clf.predict_bba(X_test)            # list[DSVector] full BBA (any focal subset)
```

**Selecting Θ via nested CV (1-SE rule)** — the partition is a
hyper-parameter of Θ-CDENN. Following Diène et al. (2026, §4.1):

```python
from evtools.classifiers.theta_cdenn_selector import select_best_theta

sel = select_best_theta(
    X, y,
    n_prototypes_range=range(M, 3*M),
    theta_search="exhaustive",          # or "optuna" for M > 4 (needs `pip install optuna`)
    one_se_rule=True,                   # paper's 1-SE rule
    loss="ce_plp", max_iter=100, lr=0.05,
)
print(sel.selected_model)               # 'ENN', 'CDENN', or 'Theta-CDENN'
clf = sel.fit(X, y, loss="ce_plp", max_iter=200)
```

The 1-SE rule favors the simpler ENN/CDENN reference unless a
non-trivial Θ improves AUERC by more than one inner-CV standard error.

### Training criteria

All three ENN variants (`ENN`, `ENNTorch`, `ENNTF`) accept the same
``loss`` parameter, with two options:

**`loss="ce_plp"` (default)** — Cross-entropy of the plausibility
transform (Denœux et al. 2019, Eq. 31/33; Diène et al. 2025):

$$L(θ) = -\tfrac{1}{N} \sum_n \ln A_n + μ\,\sum_k α_k,
\quad A_n = \sum_c plp_n(c)\,T[c, n],
\quad plp(c) = \frac{m(c) + m(Ω)}{\sum_{c'} m(c') + M\,m(Ω)}$$

In the **fully supervised** case, $T[c, n]$ is one-hot and $A_n =
plp_n(y_n)$, recovering the standard CE on the plausibility transform.
In the **partially supervised** case (soft labels), $T[c, n]$ is the
contour function of a `DSVector` label, realizing the conditional
evidential likelihood (Eq. 33 of Denœux et al. 2019).

**`loss="pl_loss"`** — Pl-loss (Pl-MSE form), historical default of ENN
(Denœux 2000) and EkNN (Zouhal & Denœux 1998), also used by
`evtools.metrics.pl_loss`:

$$L(θ) = \tfrac{1}{2N} \sum_n \| T_λ(\tilde{m}_n) - T_n \|^2 + μ\,\sum_k α_k,
\quad T_λ(\{c\}) = m(\{c\}) + λ\,m(Ω)$$

Special cases of `λ`: `0` → Bel-loss, `1/M` → BetP-loss, `1` → Pl-loss.

### Regularization (`mu`)

Both losses share an optional $L^1$ regularization term $μ\,\sum_k α_k$
on the effective activations $α_k \in (0, α_\text{max})$
(Denœux 2000, Appendix B). Since $α_k → 0$ makes prototype $k$
contribute the vacuous BBA (neutral for Dempster's rule), this penalty
acts like a Lasso: useless prototypes are switched off automatically,
giving **built-in prototype pruning**. The default is `mu=0` (no
regularization); typical pruning values are in `[1e-3, 1e-1]`, tuned
by cross-validation. With `K` large (e.g. `K = N/10`), `mu > 0` often
improves AUERC by keeping only the most informative prototypes — see
`examples/tutorial_03_classifiers.py` §5 for a concrete demo on Iris.

### Soft labels

Both `ENN`, `ENNTorch` and `ENNTF` accept a list of `DSVector` (sharing
the same frame) as `y` in `fit(X, y)`, in addition to standard hard
labels (1-D sequence). The two formats use the **same internal target
tensor** $T[c, n]$ — hard labels are encoded as one-hot rows; soft
labels as the per-instance contour function (Mutmainah 2021).
Both `loss="ce_plp"` and `loss="pl_loss"` handle soft labels
transparently via this unified $T$.

---

## `evtools.combinations`

Combination rules for aggregating beliefs from multiple sources.

```python
from evtools.combinations import crc, dempster, drc, cautious, bold
from evtools.combinations import decombine_crc, decombine_drc

m12 = crc(m1, m2)        # m1 & m2  — Conjunctive Rule (TBM), distinct reliable sources
m12 = dempster(m1, m2)   # m1 @ m2  — Dempster's normalized rule
m12 = drc(m1, m2)        # m1 | m2  — Disjunctive Rule, at least one reliable
m12 = cautious(m1, m2)   # Cautious rule, nondistinct reliable sources (idempotent)
m12 = bold(m1, m2)       # Bold disjunctive rule, nondistinct possibly unreliable (idempotent)

# Decombination — inverse operations (result may not be valid, check .is_valid)
m1 = decombine_crc(m12, m2)  # m12 6∩ m2 — removes m2 from a conjunctive combination
m1 = decombine_drc(m12, m2)  # m12 6∪ m2 — removes m2 from a disjunctive combination

# Conditioning and deconditioning (Smets 2002, Section 9)
A  = frozenset({"a", "h"})
m_cond   = condition(m, A)             # m[A]: B → B ∩ A
m_decond = decondition(m_cond, A)      # m*:   B → B ∪ Ā

# Conditioning matrices (dense mode)
from evtools.conversions import conditioning_matrix, deconditioning_matrix
CA = conditioning_matrix(frame, A)     # 2^n x 2^n specialization matrix
DA = deconditioning_matrix(frame, A)   # 2^n x 2^n generalization matrix
```

Choice of rule:

|                         | All sources reliable   | At least one reliable |
|-------------------------|------------------------|-----------------------|
| **Distinct sources**    | `crc` / `dempster`     | `drc`                 |
| **Nondistinct sources** | `cautious`             | `bold`                |

Both `crc` and `drc` support `method="sparse"` (default) or `method="dense"`.

---

## `evtools.corrections`

Correction mechanisms for adjusting a BBA based on knowledge about the
quality of a source (reliability, truthfulness).

Notation:
- **A^β** — simple MF: focal sets Ω (mass β) and A (mass 1-β)
- **A_β** — negative simple MF: focal sets ∅ (mass β) and A (mass 1-β)

```python
from evtools.corrections import (
    discount,
    contextual_discount,
    theta_contextual_discount,
    contextual_reinforce,
    contextual_dediscount,
    contextual_dereinforce,
    contextual_negate,
)

# Classical discounting — source reliable with degree β ∈ [0,1]
# β=1: unchanged; β=0: vacuous BBA
m_disc = discount(m, beta=0.6)

# Contextual discounting (CD) — reliability per singleton context
# Uses negative simple MFs A_β and the DRC
betas = {frozenset({"a"}): 0.6, frozenset({"h"}): 1.0, frozenset({"r"}): 1.0}
m_cd = contextual_discount(m, betas)

# Θ-contextual discounting — reliability per coarsening partition
betas_theta = {frozenset({"a"}): 0.4, frozenset({"h","r"}): 0.9}
m_theta = theta_contextual_discount(m, betas_theta)

# Contextual Reinforcement (CR) — dual of CD, uses simple MFs A^β and the CRC
m_cr = contextual_reinforce(m, betas)

# Inverse operations (result may not be valid — check .is_valid)
m_cdd = contextual_dediscount(m_cd, betas)    # reverses CD
m_cdr = contextual_dereinforce(m_cr, betas)   # reverses CR

# Contextual Negating (CN) — source non-truthful with probability 1-β
m_cn = contextual_negate(m, {frozenset({"a"}): 0.7})
```

Hierarchy of discounting:

```
discount(m, β)
  └── theta_contextual_discount(m, {Ω: β})

contextual_discount(m, β)
  └── theta_contextual_discount(m, β)   [Θ = singletons]

theta_contextual_discount(m, β)         [general Θ partition]
```

---

## `evtools.decision`

Decision criteria for selecting an act from a BBA. Two families:

- **Complete preference relations** return a single optimal act `(index, atom)`.
- **Partial preference relations** return a `frozenset[str]` of non-dominated atoms.

```python
from evtools.decision import (
    maximin, maximax, pignistic_decision, plp_decision, probability_decision,
    hurwicz, strong_dominance, weak_dominance,
)

# Complete preference relations — return (index, atom)
maximin(m)             # pessimistic: max lower expected utility
maximax(m)             # optimistic:  max upper expected utility
pignistic_decision(m)  # MEU with BetP (Smets pignistic)
plp_decision(m)        # MEU with PlP  (Cobb & Shenoy plausibility-prob.)
hurwicz(m, alpha=0.5)  # convex combination of maximin and maximax

# Generic MEU — pass any m → probability transform
from evtools.conversions import betp, plp
probability_decision(m, transform=betp)        # ≡ pignistic_decision
probability_decision(m, transform=plp)         # ≡ plp_decision
probability_decision(m, transform=my_custom)   # bring your own

# With a custom utility matrix U of shape (n, n)
import numpy as np
U = np.array([[1, 0, 0],
              [0, 2, 0],
              [0, 0, 1]])  # u(a_i, ω_j)
maximin(m, U)

# Partial preference relations — return frozenset of non-dominated atoms
strong_dominance(m)    # ω ≻ ω'  ⟺  Bel({ω}) ≥ Pl({ω'})
weak_dominance(m)      # ω ≻ ω'  ⟺  Bel({ω}) ≥ Bel({ω'}) and Pl({ω}) ≥ Pl({ω'})

```

Default utility (when `U` is omitted) is the identity matrix (0-1 utility, the
standard classification setting). With identity utility, `pignistic_decision`
returns the atom with maximum BetP.

---

## `evtools.metrics`

Performance metrics for evaluating decisions and predictions.

### Per-instance metrics on partial decisions

Score a partial decision `d ⊆ Ω` against a true class `ω` using the discounted
accuracy `x = I(ω ∈ d) / |d|` (Zaffalon et al. 2012).

```python
from evtools.metrics import discounted_accuracy, u65, u80, utility_score

discounted_accuracy(d, omega)             # x
u65(d, omega)                             # 1.6·x - 0.6·x²  (≡ 0.65 if |d|=2 correct)
u80(d, omega)                             # 2.2·x - 1.2·x²  (≡ 0.80 if |d|=2 correct)
utility_score(d, omega, a=1.6, b=0.6)     # generic a·x - b·x²
```

### Mean aggregators over a dataset

```python
from evtools.metrics import mean_u65, mean_u80, mean_discounted_accuracy

predictions = [strong_dominance(m_i) for m_i in classifier_outputs]
print(mean_u65(predictions, true_labels))
print(mean_u80(predictions, true_labels))
```

### BBA-valued predictions: pl-based discrepancy

The `pl_loss` metric is the discrepancy criterion minimized when learning
contextual correction parameters β (Mercier et al. 2008, Mutmainah 2021).
It is also used as a performance measure (lower is better):

$$L = \sum_{i=1}^{n} \sum_{k=1}^{K} \bigl(pl_i(\omega_k) - \delta_{i,k}\bigr)^2$$

where `pl_i` is the contour function of prediction *i* (= `m_i.contour()`)
and `δ_{i,k}` is either an indicator (hard label) or the contour function
of a soft label (BBA). The same function handles both cases, and they can
be mixed within the same call.

```python
from evtools.metrics import pl_loss, mean_pl_loss

# Hard labels (E_pl, Eq. 2.24 of Mutmainah 2021)
pl_loss(predictions, ["a", "h", "r", "a", ...])

# Soft labels (Ẽ_pl, Eq. 5.6 of Mutmainah 2021)
pl_loss(predictions, [m_label_1, m_label_2, ...])

# Mixed: each instance can be hard or soft
pl_loss(predictions, ["a", m_label_2, "r", ...])

# Mean over the dataset
mean_pl_loss(predictions, labels)
```

The `DSVector.contour()` method returns the length-K vector of singleton
plausibilities — the basic building block for both `pl_loss` and the
strong/weak dominance decision criteria. Works regardless of the source
kind (m, bel, pl, b, q, v, w).

### Hard-classification metrics: use scikit-learn

For ROC, AUC, accuracy, precision/recall, etc. on hard predictions, extract a
probability vector (e.g. via `m.to_betp()` or `m.to_plp()`) and feed it to
`sklearn.metrics`. See `examples/tutorial_02_pipeline.py` and
`tutorial_03_classifiers.py` for end-to-end examples.

### Selective classification: AUERC

The Area Under the Error-Rejection Curve quantifies how well a model's
uncertainty correlates with its errors (lower is better; Diène et al. 2026
§3.2):

```python
from evtools.metrics import (
    auerc,                       # Area Under Error-Rejection Curve
    error_rejection_curve,       # raw curve (rejection_rates, error_rates)
    uncertainty_max_bel,         # 1 - max_c Bel({c}) — uncertainty per BBA
)

# Default: metric="R_plp" (paper-aligned with Diène et al. 2026
# reference code: confidence = max_c plp(c), decision = argmax_c plp(c)).
auerc(predictions, labels)

# Alternative: metric="R_sup" (matches paper §3.2 prose:
# confidence = max_c Bel({c}), decision = argmax_c Bel({c})).
auerc(predictions, labels, metric="R_sup")
```

For ENN-style outputs (singletons + Ω focals), `R_plp` and `R_sup`
coincide. They differ only for models with non-singleton focals (CDENN,
Θ-CDENN), where the choice of metric becomes meaningful.

---

## `evtools.learning`

Learning of contextual correction parameters β from labeled data, by
**closed-form least-squares minimization** of `pl_loss` (Pichon et al.
2016, Propositions 12, 14, 16). The K parameters decouple per atom, so
each β_k has an analytical expression (then clipped to [0, 1]).

```python
from evtools.learning import fit_cd, fit_cr, fit_cn
from evtools.corrections import contextual_discount, contextual_reinforce, contextual_negate

# predictions: list[DSVector]   — source BBA outputs (training set)
# labels:      list[str | DSVector]  — hard or soft labels

betas_cd = fit_cd(predictions, labels)   # → contextual_discount(m, betas_cd)
betas_cr = fit_cr(predictions, labels)   # → contextual_reinforce(m, betas_cr)
betas_cn = fit_cn(predictions, labels)   # → contextual_negate   (m, betas_cn)

# Apply the learnt correction to a new instance
m_corrected = contextual_discount(m_test, betas_cd)
```

**Hard / soft labels**: same polymorphism as `pl_loss` — strings minimize
E_pl, DSVectors minimize Ẽ_pl, and they can be mixed in the same call.

**Validation**: the test suite reproduces the worked example of Pichon
2016 (Tables 4 & 6) numerically — both the optimal β vectors and the
attained `pl_loss` values, for both sensors and all three corrections.

### Generating soft labels from hard labels

When only hard labels are available, soft labels can be synthesized to
study the soft-label setting (Mutmainah 2021, Algorithm 2 — based on
Côme et al. 2009 and Quost et al. 2017).

```python
from evtools.learning import hard_to_soft_labels
import numpy as np

rng  = np.random.default_rng(42)
soft = hard_to_soft_labels(
    hard_labels=["a", "h", "r", "a"],
    frame=["a", "h", "r"],
    mu=0.5,                 # mean of the Beta from which p_i is drawn
    var=0.04,               # variance of the Beta
    rng=rng,
)
# soft is a list[DSVector] usable directly as labels for pl_loss / fit_*
betas_cd_soft = fit_cd(predictions, soft)
```

For each instance `i`, the algorithm draws `p_i ~ Beta(μ, v)` and
`b_i ~ Bernoulli(p_i)`; if `b_i = 1` the soft label becomes a simple MF
with `m({ω_{k_i}}) = 1 - p_i` and `m(Ω) = p_i` for a uniformly random
class `k_i`, otherwise the hard label is preserved.

### Per-group learning of contextual corrections

`fit_per_group` implements **Algorithm 1 of Mutmainah (2021)** — both the
hard-label version (Chapter 4) and the soft-label extension (Section 5.3)
share the same code path thanks to the polymorphic `pl_loss` and `fit_*`
underneath. Source outputs are partitioned by their partial decision
(strong or weak dominance), and the best of CD/CR/CN is fitted on each
group; a fallback correction is also learnt on the whole training set
for unseen partial decisions at predict time.

```python
from evtools.learning import fit_per_group, apply_per_group
from evtools.decision  import strong_dominance, weak_dominance

# Train: predictions and labels from a labeled set, dominance criterion of choice
model = fit_per_group(
    predictions_train,
    labels_train,                  # hard (str), soft (DSVector), or mixed
    dominance=strong_dominance,    # or weak_dominance
)

# Inspect what was learnt
for d, gc in model.groups.items():
    print(d, gc.kind, gc.loss)     # which correction fits best on each group
print("fallback:", model.fallback.kind, model.fallback.loss)

# Apply on new BBA outputs
predictions_test_corrected = apply_per_group(model, predictions_test)
```

The model is a small `NamedTuple` (`GroupedCorrectionModel`) with three
fields: `groups`, `fallback`, `dominance`.

## `evtools.display`

Four output formats, all adapting the column header to the kind (`m`, `bel`, `pl`, ...).
Each is exposed both as a module function and as a `DSVector` method.
In Jupyter notebooks, `DSVector._repr_html_()` is called automatically.

```python
from evtools.display import to_string, to_ansi, to_html, to_latex

# Module functions
print(to_string(m))   # plain text, no colors
print(to_latex(m))    # LaTeX tabular for papers

# DSVector methods (equivalent)
m.to_ansi()           # colored terminal (also used by __repr__)
m.to_html()           # HTML table

# Multi-representation table — m + bel + pl + b + q in a single table.
# v added if m is subnormal (m(∅) > 0); w added if m is non-dogmatic (m(Ω) > 0).
print(m.to_string(all_kinds=True))
print(m.to_latex(all_kinds=True))
```

---

## `evtools.conversions`

Low-level conversion functions operating on plain numpy arrays (length `2^n`),
using the Fast Möbius Transform (Smets 2002). Every conversion is available as
`<source>to<target>`, e.g. `mtob`, `pltom`, `qtow`, `beltov`, etc.

Also includes conditioning matrices and probability transformations:

```python
from evtools.conversions import mtob, mtopl, mtobel, mtoq
from evtools.conversions import betp, plp
from evtools.conversions import conditioning_matrix, deconditioning_matrix

m = np.array([0.0, 0.5, 0.0, 0.0, 0.5, 0.0, 0.0, 0.0])
print(mtoq(m))    # commonality function
print(mtopl(m))   # plausibility function

# Probability transformations (return np.ndarray of length n, not 2^n)
print(betp(m))    # pignistic probability BetP (Smets & Kennes 1994)
print(plp(m))     # plausibility probability PlP (Cobb & Shenoy 2006)

# Equivalently via DSVector methods
m_vec = DSVector.from_dense(frame, m)
print(m_vec.to_betp())  # np.ndarray of length n
print(m_vec.to_plp())

# Conditioning matrices
CA = conditioning_matrix(frame, frozenset({"a", "h"}))  # 2^n x 2^n
DA = deconditioning_matrix(frame, frozenset({"a", "h"}))
```

Array indices follow the binary ordering of Smets (2002): index `i` corresponds
to the subset whose members are the frame atoms at the bit positions set in `i`.

---

## Installation

```bash
pip install evtools-dst                  # core
pip install "evtools-dst[torch]"         # adds ENNTorch + ThetaCDENNTorch (PyTorch)
pip install "evtools-dst[tf]"            # adds ENNTF (TensorFlow / Keras)
pip install "evtools-dst[optuna]"        # enables theta_search="optuna" for ThetaCDENN
```

Or from source:

```bash
git clone https://github.com/evtools-team/evtools.git
cd evtools
pip install -e .
```

## Running tests

```bash
pip install -e ".[dev]"
pytest tests/
```

## Tutorials

Five progressive tutorials in [`examples/`](examples/), each available as
both a runnable Python script (`.py`) and a Jupyter notebook (`.ipynb`):

| File | Topic | Requires |
|------|-------|----------|
| `tutorial_01_bba.py` | `DSVector`: build, inspect, convert, display | core |
| `tutorial_02_pipeline.py` | Combinations, corrections, decision, metrics, learning | core |
| `tutorial_03_classifiers.py` | `EkNN` and `ENN` end-to-end on Iris / Wine / UCI benchmarks, with learned contextual corrections | core + scikit-learn |
| `tutorial_04_enn_torch.py` | `ENNTorch` — sklearn-style use, training dynamics, native head behind a deep backbone, NumPy ↔ Torch bridge | `[torch]` |
| `tutorial_05_enn_tf.py` | `ENNTF` — TensorFlow / Keras mirror of `tutorial_04` | `[tf]` |
| `tutorial_06_theta_cdenn.py` | `ThetaCDENNTorch` (Diène et al. 2026) — equivalences with ENN/CDENN, comparison of all Bell(M) partitions on Iris with both losses, and partition selection via the 1-SE rule | `[torch]` |

Run as scripts:

```bash
python examples/tutorial_01_bba.py
```

Or open the matching `.ipynb` in Jupyter for inline rendering of tables
and matplotlib figures. The two formats are kept in sync via
[jupytext](https://jupytext.readthedocs.io/).

## References

- P. Smets. *The application of the matrix calculus to belief functions*, International Journal of Approximate Reasoning, 31(1–2):1–30, 2002.
- T. Denœux. *Conjunctive and disjunctive combination of belief functions induced by non-distinct bodies of evidence*, Artificial Intelligence, 172:234–264, 2008.
- D. Mercier, B. Quost, T. Denœux. *Refined modeling of sensor reliability in the belief function framework using contextual discounting*, Information Fusion, Vol. 9, Issue 2, pp 246-258, April 2008.
- F. Pichon, D. Mercier, É. Lefèvre, F. Delmotte. *Proposition and learning of some belief function contextual correction mechanisms*, International Journal of Approximate Reasoning, Vol. 72, pp 4-42, May 2016.
- T. M. Strat. *Decision analysis using belief functions*, International Journal of Approximate Reasoning, Vol. 4, Issues 5-6, pp 391-417, 1990.
- M. C. M. Troffaes. *Decision making under uncertainty using imprecise probabilities*, International Journal of Approximate Reasoning, Vol. 45, Issue 1, pp 17-29, 2007.
- L. Ma, T. Denœux. *Partial classification in the belief function framework*, Knowledge-Based Systems, Vol. 214, 106742, 2021.
- M. Zaffalon, G. Corani, D. Mauá. *Evaluating credal classifiers by utility-discounted predictive accuracy*, International Journal of Approximate Reasoning, Vol. 53, Issue 8, pp 1282-1301, 2012.
- S. Mutmainah, S. Hachour, F. Pichon, D. Mercier. *On learning evidential contextual corrections from soft labels using a measure of discrepancy between contour functions*, 13th International Conference on Scalable Uncertainty Management, SUM 2019, N. Ben Amor, B. Quost and M. Theobald (Eds.), Springer, Volume 11940 of Lecture Notes in Computer Science, pp 405–411, Compiègne, France, December 16-18, 2019.
- S. Mutmainah, S. Hachour, F. Pichon, D. Mercier. *Improving an Evidential Source of Information Using Contextual Corrections Depending on Partial Decisions*, 6th International Conference on Belief Functions, BELIEF 2021, T. Denœux, É. Lefèvre, Z. Liu and F. Pichon (Eds.), pp 247-256, Shanghai, China, October 15-19, 2021.
- S. Mutmainah. *Learning to adjust an evidential source of information using partially labeled data and partial decisions*, PhD thesis, Université d'Artois, 2021.
- T. Denœux. *A k-nearest neighbor classification rule based on Dempster-Shafer theory*, IEEE Transactions on Systems, Man, and Cybernetics, 25(5):804–813, 1995.
- L. M. Zouhal, T. Denœux. *An evidence-theoretic k-NN rule with parameter optimization*, IEEE Transactions on Systems, Man, and Cybernetics — Part C, 28(2):263–271, 1998.
- T. Denœux. *A neural network classifier based on Dempster-Shafer theory*, IEEE Transactions on Systems, Man and Cybernetics — Part A, 30(2):131–150, 2000.
- T. Denœux, O. Kanjanatarakul, S. Sriboonchitta. *A new evidential K-nearest neighbor rule based on contextual discounting with partially supervised learning*, International Journal of Approximate Reasoning, 113:287–302, 2019.
- S. M. Diène, S. Ramel, F. Pichon, D. Mercier. *An extension of the Evidential Neural Network classifier based on contextual discounting*, ICTAI 2025.
- S. M. Diène, S. Ramel, F. Pichon, D. Mercier. *A generalization of the Evidential Neural Network based on Θ-contextual discounting*, IUKM 2026 (Θ-CDENN).

## License

MIT
