evtools-dst 0.27.0

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

evtools

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

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

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.

# 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

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

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

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

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)

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:

# 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).

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):

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.

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-β)

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.

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).

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

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.

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):

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]).

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).

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.

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.

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:

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

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:

git clone https://github.com/daviddavkanmercier/evtools.git
cd evtools
pip install -e .

Running tests

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

Tutorials

Five progressive tutorials in 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:

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.

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