API Reference

Frame

class evidencelib.Frame(atoms, *, empty=(), exclusive=False, model='hybrid')[source]

A finite frame of discernment.

The internal representation uses Venn regions. This lets the same proposition algebra represent Shafer’s exclusive DST model, the free DSmT model, and constrained hybrid DSm models.

Parameters:

atoms (Sequence[str]) – Names of the elementary hypotheses.
empty (Iterable[str | Proposition]) – Propositions that are constrained to be empty in a hybrid model.
exclusive (bool | Iterable[Sequence[str]]) – If True, all atom pairs are mutually exclusive. An iterable of atom groups may be supplied to mark only selected intersections as empty.
model (str) – Descriptive model name stored on the frame.

atom(name)[source]

Return the singleton proposition for an atom name.

Parameters:: name (str)
Return type:: Proposition

classmethod dsmt(atoms)[source]

Create the free DSm model where hypotheses may overlap.

Parameters:: atoms (Sequence[str])
Return type:: Frame

classmethod dst(atoms)[source]

Create Shafer’s DST model with mutually exclusive hypotheses.

Parameters:: atoms (Sequence[str])
Return type:: Frame

elements(*, max_count=100000)[source]

Generate the model’s closure under union and intersection.

The result is the power set for DST and the hyper-power set for the free DSm model. DSmT cardinality grows very quickly; pass max_count=None only when you really want the full closure.

Parameters:: max_count (int | None)
Return type:: tuple[Proposition, …]

format(prop)[source]

Format a proposition as a compact expression using frame atom names.

Parameters:: prop (Proposition)
Return type:: str

classmethod hybrid(atoms, *, empty=(), exclusive=False)[source]

Create a constrained DSm model.

Parameters:

atoms (Sequence[str])
empty (Iterable[str | Proposition])
exclusive (bool | Iterable[Sequence[str]])

Return type:

Frame

mass(values, **kwargs)[source]

Create a mass function on this frame.

Parameters:

values (Mapping[Any, float]) – Mapping from propositions, proposition expressions, or iterables of atom names to assigned masses.
**kwargs (Any) – Additional options passed to evidencelib.MassFunction.

Return type:

MassFunction

property model_signature: tuple[int, ...]: Stable structural signature of the model’s possible Venn regions.

proposition(value)[source]

Coerce a string, proposition, or iterable of atoms into a proposition.

Parameters:: value (str | Proposition | Iterable[str])
Return type:: Proposition

property region_count: int: Number of non-empty disjoint Venn regions in the current model.

symbols(names=None)[source]

Return atom propositions.

names may be omitted to return all frame atoms, or supplied as a whitespace/comma-separated subset.

Parameters:: names (str | None)
Return type:: tuple[Proposition, …]

MassFunction

class evidencelib.MassFunction(frame, values, *, validate=True, tolerance=1e-09)[source]

A basic belief assignment over a frame.

Parameters:

frame (Frame) – Frame of discernment that owns all propositions in the assignment.
values (Mapping[Any, float]) – Mapping from propositions, proposition expressions, or iterables of atom names to assigned masses.
validate (bool) – Validate that masses are non-negative and sum to one.
tolerance (float) – Numerical tolerance used when cleaning and validating masses.

belief(key)[source]

Return belief, the mass of propositions contained in key.

Parameters:: key (str | Proposition | Iterable[str])
Return type:: float

commonality(key)[source]

Return commonality, the mass of propositions containing key.

Parameters:: key (str | Proposition | Iterable[str])
Return type:: float

property conflict: float: Mass assigned to the empty proposition.

conjunctive(*others, model=None)[source]

Unnormalized conjunctive rule.

On a free DSm frame this is the classic DSm rule (DSmC). On Shafer’s DST model, contradictory intersections are accumulated on empty.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

decision()[source]

Return the singleton with the largest pignistic probability.

Return type:: str

dempster(*others, model=None)[source]

Dempster’s normalized rule of combination.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

dsmc(*others)[source]

Alias for the classic conjunctive DSm rule.

Parameters:: others (MassFunction)
Return type:: MassFunction

dsmh(*others, model=None)[source]

Apply the hybrid DSm rule, including its S1, S2, and S3 terms.

For a dynamic model change, create the source assignments on their original frame and pass the constrained target frame as model. This preserves each focal proposition and u(X) until constraints are applied. With no explicit model, the rule operates statically on the sources’ existing frame and rejects mass already collapsed onto empty.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

dubois_prade(*others, model=None)[source]

Apply the static Dubois-Prade conflict-transfer rule.

Dubois-Prade is a static rule. Passing a distinct target model denotes a dynamic model change and is rejected rather than silently returning a DSmH result.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

focal()[source]

Return propositions with non-zero assigned mass.

Return type:: tuple[Proposition, …]

classmethod from_csv(frame, text, *, has_header=True, **kwargs)[source]

Create a mass function from CSV text with proposition and mass columns.

Parameters:

frame (Frame)
text (str)
has_header (bool)
kwargs (Any)

Return type:

MassFunction

classmethod from_dict(frame, data, **kwargs)[source]

Create a mass function from a plain or schema-wrapped dictionary.

data may be a direct mapping such as {"A": 0.2, "A|B": 0.8} or the object produced by to_json() after JSON decoding.

Parameters:

frame (Frame)
data (Mapping[Any, Any])
kwargs (Any)

Return type:

MassFunction

classmethod from_json(frame, text, **kwargs)[source]

Create a mass function from JSON produced by to_json().

Parameters:

frame (Frame)
text (str | bytes)
kwargs (Any)

Return type:

MassFunction

items()[source]

Return focal propositions and masses sorted by proposition label.

Return type:: tuple[tuple[Proposition, float], …]

mass(key)[source]

Return the direct mass assigned to a proposition.

Parameters:: key (str | Proposition | Iterable[str])
Return type:: float

normalization_tolerance = 1e-06

normalize()[source]

Normalize a conjunctive result by removing empty-set conflict.

Return type:: MassFunction

pcr5(other)[source]

PCR5 for two sources.

Parameters:: other (MassFunction)
Return type:: MassFunction

pcr6(*others)[source]

PCR6 proportional conflict redistribution for two or more sources.

Parameters:: others (MassFunction)
Return type:: MassFunction

pignistic(*, normalize_conflict=True)[source]

Return pignistic scores for singleton hypotheses.

This is the classical pignistic transformation on DST frames. On free or hybrid DSmT frames, singleton hypotheses can overlap, so the returned event scores are useful for decisions but do not have to sum to one.

If normalize_conflict is true, mass assigned to the empty proposition is ignored and the remaining scores are rescaled by 1 - conflict. This makes TBM/Smets results usable for pignistic decisions while still allowing raw unnormalized scores with normalize_conflict=False.

Parameters:: normalize_conflict (bool)
Return type:: dict[str, float]

pignistic_of(key, *, normalize_conflict=True)[source]

Return the generalized pignistic probability of one proposition.

This implements C_M(X & A) / C_M(X) for arbitrary A in the frame’s hyper-power set. Empty-set conflict is normalized consistently with pignistic() and pignistic_regions().

Parameters:

key (str | Proposition | Iterable[str])
normalize_conflict (bool)

Return type:

float

pignistic_regions(*, normalize_conflict=True)[source]

Return a probability distribution over model Venn regions.

If normalize_conflict is true, empty-set conflict is excluded and the non-empty region probabilities are rescaled by 1 - conflict.

Parameters:: normalize_conflict (bool)
Return type:: dict[str, float]

plausibility(key)[source]

Return plausibility, the mass of propositions intersecting key.

Parameters:: key (str | Proposition | Iterable[str])
Return type:: float

plot(*, ax=None, **kwargs)[source]

Plot this mass assignment as a horizontal bar chart.

This method requires the optional plotting dependency. Install it with pip install 'evidencelib[plot]'.

Parameters:

ax (Any)
kwargs (Any)

Return type:

Any

plot_belief_plausibility(*, ax=None, **kwargs)[source]

Plot belief-plausibility intervals for this mass assignment.

Parameters:

ax (Any)
kwargs (Any)

Return type:

Any

plot_comparison(*others, labels=None, ax=None, **kwargs)[source]

Plot a heatmap comparing this mass assignment with other sources.

Parameters:

others (MassFunction)
labels (Sequence[str] | None)
ax (Any)
kwargs (Any)

Return type:

Any

plot_pignistic_decision(*, ax=None, **kwargs)[source]

Plot the pignistic decision ranking for this mass assignment.

Parameters:

ax (Any)
kwargs (Any)

Return type:

Any

plot_venn(*, ax=None, **kwargs)[source]

Plot pignistic or direct mass values over disjoint Venn regions.

Parameters:

ax (Any)
kwargs (Any)

Return type:

Any

smets(*others, model=None)[source]

Smets/TBM unnormalized rule, keeping conflict on the empty set.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

to_csv(*, include_header=True, float_format=None)[source]

Serialize this mass assignment to CSV text.

The CSV has two columns: proposition and mass. It is intended for data exchange and round trips, not for presentation tables.

Parameters:

include_header (bool)
float_format (str | None)

Return type:

str

to_dict(*, string_keys=True)[source]

Return the mass assignment as a plain dictionary.

Parameters:: string_keys (bool)
Return type:: dict[str | Proposition, float]

to_json(*, indent=2)[source]

Serialize this mass function to a JSON string.

The JSON stores the mass assignment and lightweight frame metadata for validation. Import still requires the caller to provide the target frame, because hybrid DSm constraints are model semantics rather than just mass data.

Parameters:: indent (int | None)
Return type:: str

to_latex(*, columns=('mass',), rows='focal', caption=None, label=None, float_format='.4f', booktabs=True, position='htbp')[source]

Export this mass function as a LaTeX table string.

Parameters:

columns (Sequence[str]) – Any of mass, belief, plausibility, or commonality. Short aliases m, bel, pl, and q are accepted.
rows (str) – "focal" for stored non-zero masses, or "all" for every proposition generated by the frame. "all" can be large for DSmT frames.
caption (str | None) – Optional LaTeX table metadata.
label (str | None) – Optional LaTeX table metadata.
float_format (str | None) – Python format specifier such as ".4f". Percent-style formats such as "%0.4f" are also accepted.
booktabs (bool) – Use toprule/midrule/bottomrule instead of hline.
position (str) – LaTeX table position specifier.

Return type:

str

property total_mass: float: Sum of all stored masses.

yager(*others, model=None)[source]

Yager’s rule: transfer total conflict to total ignorance.

Parameters:

others (MassFunction)
model (Frame | None)

Return type:

MassFunction

Proposition

class evidencelib.Proposition(frame, regions)[source]

A canonical proposition represented by possible Venn regions.

Users normally create propositions through a evidencelib.Frame and combine them with | for union and & for intersection.

Parameters:

frame (Frame)
regions (FrozenSet[int])

property cardinality: int

number of non-empty model regions.

Type:: DSm cardinality

frame: Frame

intersects(other)[source]

Return whether two propositions share at least one model region.

Parameters:: other (Proposition)
Return type:: bool

property is_empty: bool: Whether this proposition contains no possible model regions.

regions: FrozenSet[int]

union_atoms()[source]

Return the disjunction of singleton hypotheses involved in this proposition.

Return type:: Proposition

Plotting

Matplotlib-based visualizations for belief mass functions.

evidencelib.plotting.plot_belief_plausibility(mass, *, hypotheses=None, ax=None, title=None, show_pignistic=True, show_decision=True, sort_by='pignistic', annotate_intervals=False, interval_color='#1F77B4', decision_color='#1F77B4', pignistic_color='#FF7F0E', show_legend=True)[source]

Draw belief-plausibility intervals for singleton hypotheses.

The interval for each hypothesis starts at belief and ends at plausibility. When enabled, pignistic scores are drawn as point markers.

Parameters:

interval_color (str) – Matplotlib colors for support intervals, selected-decision interval, and pignistic markers.
decision_color (str) – Matplotlib colors for support intervals, selected-decision interval, and pignistic markers.
pignistic_color (str) – Matplotlib colors for support intervals, selected-decision interval, and pignistic markers.
show_legend (bool) – Display the compact explanation legend.
mass (MassFunction)
hypotheses (Sequence[str | Proposition | Iterable[str]] | None)
ax (Any)
title (str | None)
show_pignistic (bool)
show_decision (bool)
sort_by (SortBy)
annotate_intervals (bool)

Return type:

Any

evidencelib.plotting.plot_mass(mass, *, ax=None, title=None, sort=True, top_n=None, min_mass=None, show_other=True, colors=None, show_kind_legend=False, annotate=True)[source]

Draw a horizontal bar plot for one mass assignment.

Parameters:

mass (MassFunction) – Mass function to visualize.
ax (Any) – Optional matplotlib axes. If omitted, a new figure and axes are created.
title (str | None) – Optional custom title.
sort (bool) – Sort focal propositions by descending mass.
top_n (int | None) – Keep only the largest top_n visible propositions.
min_mass (float | None) – Hide propositions below this direct mass threshold.
show_other (bool) – Aggregate hidden propositions into an Other propositions bar.
colors (ColorSpec) – Optional color override. Pass a single matplotlib color for all bars, a sequence to cycle through bars, or a mapping keyed by proposition kind (singleton, union, compound, empty, total, other) or displayed label. By default all regular bars use one color, and the aggregated other bar is muted.
show_kind_legend (bool) – Display a legend for proposition kinds. Disabled by default to keep plots compact.
annotate (bool) – Draw numeric mass labels at the end of bars.

Returns:

Axes containing the plot.

Return type:

matplotlib.axes.Axes

evidencelib.plotting.plot_mass_comparison(masses, *, labels=None, ax=None, title=None, sort=True, top_n=None, min_total_mass=None, annotate=True, vmax=None, cmap=None, colorbar=True, annotation_text_colors=('#222222', '#FFFFFF'), annotation_threshold=0.45)[source]

Draw a heatmap comparing mass assignments across sources.

Rows represent mass functions, columns represent propositions that appear in at least one source, and cell values are assigned masses.

Parameters:

cmap (Any) – Optional matplotlib colormap name/object or a sequence of colors used to build a linear colormap.
colorbar (bool) – Draw the assigned-mass colorbar.
annotation_text_colors (Sequence[str]) – Pair of matplotlib colors used for annotated values on light and dark heatmap cells.
annotation_threshold (float) – Normalized cell intensity, from 0 to 1, where annotations switch from the first text color to the second text color.
masses (Sequence[MassFunction])
labels (Sequence[str] | None)
ax (Any)
title (str | None)
sort (bool)
top_n (int | None)
min_total_mass (float | None)
annotate (bool)
vmax (float | None)

Return type:

Any

evidencelib.plotting.plot_pignistic_decision(mass, *, ax=None, title=None, top_n=None, colors=None, highlight_decision=True, decision_color='#1F77B4', annotate=True, show_legend=False)[source]

Draw a horizontal ranking of pignistic decision scores.

Parameters:

colors (ColorSpec) – Optional color override. Pass a single matplotlib color for all bars, a sequence to cycle through bars, or a mapping keyed by hypothesis label, decision, hypothesis, or default.
highlight_decision (bool) – Emphasize the top pignistic score. Disable for a neutral ranking plot.
decision_color (str) – Matplotlib color for the selected decision when highlighting is active.
annotate (bool) – Draw numeric pignistic scores at the end of bars.
show_legend (bool) – Display a legend for the decision highlight.
mass (MassFunction)
ax (Any)
title (str | None)
top_n (int | None)

Return type:

Any

evidencelib.plotting.plot_venn(mass, *, ax=None, title=None, labels=None, values='pignistic', colors=None, alpha=0.32, annotate=True, show_zero_values=True, show_region_labels=False, value_formatter=None)[source]

Draw a compact Venn-style diagram for one to three hypotheses.

The diagram labels disjoint model regions, so it is most useful for DSmT and hybrid DSm frames where overlaps are meaningful. By default, region values come from the pignistic transformation over Venn regions. Pass values="mass" to show only direct mass assigned to each elementary region.

Parameters:

labels (Sequence[str] | None) – Optional display labels for the frame atoms.
values (VennValues) – "pignistic" for distributed pignistic region probabilities, or "mass" for direct mass assigned to elementary Venn regions.
colors (ColorSpec) – Optional circle color override. Pass a single Matplotlib color, a sequence cycled across circles, or a mapping keyed by atom label.
alpha (float) – Circle fill opacity.
annotate (bool) – Draw region values inside the diagram.
show_zero_values (bool) – Display zero-valued possible regions as 0.00. Disable to hide them.
show_region_labels (bool) – Include the region name above each numeric value.
value_formatter (Callable[[float], str] | None) – Optional callable used to format region values.
mass (MassFunction)
ax (Any)
title (str | None)

Return type:

Any

Exceptions

Package-specific exceptions.

exception evidencelib.exceptions.EvidenceLibError[source]: Base exception for evidencelib.

exception evidencelib.exceptions.InvalidMassError[source]: Raised when a mass assignment is invalid.

exception evidencelib.exceptions.TotalConflictError[source]: Raised when normalization is undefined due to total conflict.