Skip to content

Moment

dstz.math.stat.moment

central_information_content(element, mass, ev)

Calculates the central information content of a focal element.

The central information content measures how much more or less informative a specific focal element is compared to the average informativeness of the entire evidence distribution. It is calculated by subtracting the mean information content (Deng Entropy) from the element's own information content.

Parameters:

Name Type Description Default
element Element

The focal element of interest.

 required
mass float

The belief mass associated with the element.

 required
ev Evidence

The entire evidence distribution, used to calculate the mean information content.

 required

Returns:

Name Type Description
float

The central information content value.
Source code in dstz/math/stat/moment.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def central_information_content(element, mass, ev):
    """Calculates the central information content of a focal element.

    The central information content measures how much more or less informative
    a specific focal element is compared to the average informativeness of the
    entire evidence distribution. It is calculated by subtracting the mean
    information content (Deng Entropy) from the element's own information
    content.

    Args:
        element (Element): The focal element of interest.
        mass (float): The belief mass associated with the element.
        ev (Evidence): The entire evidence distribution, used to calculate
            the mean information content.

    Returns:
        float: The central information content value.
    """
    center = high_order_moment(ev, information_content, 1)
    return information_content(element, mass) - center

deng_entropy(ev)

Calculates the Deng entropy of an evidence distribution.

Deng entropy is a measure of uncertainty in evidence theory. It is defined as the first-order moment of the information content across all focal elements in the distribution, which is equivalent to the expected value of the information content.

Parameters:

Name Type Description Default
ev Evidence

The evidence distribution.

 required

Returns:

Name Type Description
float

The Deng entropy of the distribution.
Source code in dstz/math/stat/moment.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def deng_entropy(ev):
    """Calculates the Deng entropy of an evidence distribution.

    Deng entropy is a measure of uncertainty in evidence theory. It is
    defined as the first-order moment of the information content across all
    focal elements in the distribution, which is equivalent to the expected
    value of the information content.

    Args:
        ev (Evidence): The evidence distribution.

    Returns:
        float: The Deng entropy of the distribution.
    """
    return high_order_moment(ev, information_content, 1)

high_order_moment(ev, func, order, *args)

Calculates a high-order moment for an evidence distribution.

This is a generalized function that computes statistical moments. It applies a given function func to each element in the evidence distribution, raises the result to the specified order, weights it by the element's mass, and sums the results.

Parameters:

Name Type Description Default
ev Evidence

The evidence distribution.

 required
func callable

A function that takes an element, its mass, and any additional arguments, and returns a numerical value.

 required
order int

The order of the moment to calculate (e.g., 1 for mean, 2 for variance if centered).

 required
*args

Additional arguments to pass to func.

 ()

Returns:

Name Type Description
float

The calculated high-order moment.
Source code in dstz/math/stat/moment.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def high_order_moment(ev, func, order, *args):
    """Calculates a high-order moment for an evidence distribution.

    This is a generalized function that computes statistical moments. It applies
    a given function `func` to each element in the evidence distribution,
    raises the result to the specified `order`, weights it by the element's
    mass, and sums the results.

    Args:
        ev (Evidence): The evidence distribution.
        func (callable): A function that takes an element, its mass, and any
            additional arguments, and returns a numerical value.
        order (int): The order of the moment to calculate (e.g., 1 for mean,
            2 for variance if centered).
        *args: Additional arguments to pass to `func`.

    Returns:
        float: The calculated high-order moment.
    """
    res = 0
    for element, mass in ev.items():
        res += (func(element, mass, *args) ** order) * mass
    return res

information_content(element, mass, event_generator=powerset, component_generator=set)

Calculates the information content of a single focal element.

Information content quantifies the amount of surprise or information conveyed by a piece of evidence. It is calculated based on the belief mass of the element and its cardinality (the number of possible outcomes it contains).

Parameters:

Name Type Description Default
element Element

The focal element of interest.

 required
mass float

The belief mass associated with the element.

 required
event_generator callable

A function to generate events from components. Defaults to powerset.

 powerset
component_generator callable

A function to generate components from an element. Defaults to set.

 set

Returns:

Name Type Description
float

The information content value.
Source code in dstz/math/stat/moment.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def information_content(element, mass, event_generator=powerset,
                        component_generator=set):
    """Calculates the information content of a single focal element.

    Information content quantifies the amount of surprise or information
    conveyed by a piece of evidence. It is calculated based on the belief
    mass of the element and its cardinality (the number of possible outcomes
    it contains).

    Args:
        element (Element): The focal element of interest.
        mass (float): The belief mass associated with the element.
        event_generator (callable, optional): A function to generate events
            from components. Defaults to `powerset`.
        component_generator (callable, optional): A function to generate
            components from an element. Defaults to `set`.

    Returns:
        float: The information content value.
    """
    return -math.log2(mass / len(event_generator(component_generator(element))))

information_var(ev)

Calculates the variance of the information content.

This function measures the spread or dispersion of information content across the elements of an evidence distribution. It is calculated as the second-order moment of the central information content.

Parameters:

Name Type Description Default
ev Evidence

The evidence distribution.

 required

Returns:

Name Type Description
float

The variance of the information content.
Source code in dstz/math/stat/moment.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def information_var(ev):
    """Calculates the variance of the information content.

    This function measures the spread or dispersion of information content
    across the elements of an evidence distribution. It is calculated as the
    second-order moment of the *central* information content.

    Args:
        ev (Evidence): The evidence distribution.

    Returns:
        float: The variance of the information content.
    """
    return high_order_moment(ev, central_information_content, 2, ev)