set_functions
This module gathers classes and utilities to define set functions.
- class HashableSet
Bases:
setThis class adds the hashable property to a set object.
It is intended as a replacement of the native set structure whenever a set needs to be hashed (e.g when using sets as dictionary keys).
- add()
Add an element to a set.
This has no effect if the element is already present.
- classmethod cardinal_range(*args)
Return range iterator ordered by cardinality and set content.
This corresponds to the natural order in which to read a list of values
- Parameters
args (int) – argument available to built-in
range()function- Returns
- Return type
List[int]
- clear()
Remove all elements from this set.
- copy()
Return a shallow copy of a set.
- difference()
Return the difference of two or more sets as a new set.
(i.e. all elements that are in this set but not the others.)
- difference_update()
Remove all elements of another set from this set.
- discard()
Remove an element from a set if it is a member.
If the element is not a member, do nothing.
- classmethod from_index(i, ensemble=None)
Convert integer mask index into hashable set.
- Parameters
i (int) –
ensemble (Optional[List]) – ensemble from which to build the set (its default value is \(\mathbf{Z}^+\))
- Raises
ValueError – if i is out of bounds for ensemble
- Return type
- classmethod from_mask(mask, ensemble=None)
Convert binary mask to hashable set.
- Parameters
mask (str) – contains only the binary mask read from left to right
ensemble (Optional[List]) – ensemble from which to build the set (its default value is \(\mathbf{Z}^+\))
- Returns
binary set
- Return type
- intersection()
Return the intersection of two sets as a new set.
(i.e. all elements that are in both sets.)
- intersection_update()
Update a set with the intersection of itself and another.
- isdisjoint()
Return True if two sets have a null intersection.
- issubset()
Report whether another set contains this set.
- issuperset()
Report whether this set contains another set.
- classmethod logical_order(ensemble)
Return list of hashable sets in the logical order
The logical order corresponds in the order of the integer representation of the sets binary masks.
- Returns
- Parameters
ensemble (List) –
- Return type
List[HashableSet]
- classmethod natural_order(ensemble)
Return list of hashable sets in the natural order
The natural order is by set cardinality first, ensemble order second.
- Returns
- Parameters
ensemble (List) –
- Return type
List[HashableSet]
- pop()
Remove and return an arbitrary set element. Raises KeyError if the set is empty.
- remove()
Remove an element from a set; it must be a member.
If the element is not a member, raise a KeyError.
- symmetric_difference()
Return the symmetric difference of two sets as a new set.
(i.e. all elements that are in exactly one of the sets.)
- symmetric_difference_update()
Update a set with the symmetric difference of itself and another.
- union()
Return the union of sets as a new set.
(i.e. all elements that are in either set.)
- update()
Update a set with the union of itself and others.
- class Mobius(values, ensemble=None, validate=True)
Bases:
ISetFunctionThis class represents the Möbius transform of a set function.
- Parameters
values (Union[List, Dict, ISetFunction]) –
- values of the function as either:
a list ordered as a binary mask on the ensemble
a dictionary with
HashableSetas keysanother
SetFunctionobject (used for casting)
ensemble (Union[List, None]) – ensemble from which to build the set (its default value is \(\mathbf{Z}^+\))
validate (bool) –
- __call__(*args, **kwargs)
Call this set function on the set composed of all provided arguments
- Returns
value
- property as_capacity: Self
Return the instance if it respects its properties.
- The properties are the following:
the set function is defined on a power set
the set function is a game
the set function is monotonous
the set function is normal
- Raises
KeyError –
if set function is not defined on a power set
ValueError –
if set function is not a game
if set function is not monotonous
if set function is not normal
- property ensemble: List
Return a copy of the ensemble of this set function.
- Returns
- property interaction_index: DataFrame
Return interaction index matrix.
- Returns
Note
Formula is based on [GKM08].
- property is_additive: bool
Check if this is the Möbius of an additive set function.
- Returns
Note
use
is_k_additive()for computation
- property is_capacity: bool
Check if the instance is a capacity.
- The properties are the following:
the set function is defined on a power set
the set function is a game
the set function is monotonous
the set function is normal
- Returns
Trueif instance is a capacity,Falseotherwise
- property is_cardinality_based: bool
Check if this is the Möbius of a cardinality-based set function.
- Returns
- property is_game: bool
Check if the set function is a game.
Check \(\nu(\emptyset) = 0\)
- Returns
- is_k_additive(k)
Check if it is the Möbius of a k-additive set function.
- Parameters
k (int) –
- Returns
- Return type
bool
Note
use
math.isclose()to add absolute tolerance
- property is_monotonous: bool
Check if this is the Möbius of a monotonous set function.
Check set_function is a game, and that \(\sum_{\stackrel{T \subseteq S}{T \ni i}} m(T) \geq 0, \forall S \subseteq N, \forall i \in S\)
- Returns
Note
use
math.isclose()to add absolute tolerance
- property is_normal: bool
Check if the set function is a normalized Möbius.
Check set_function is a möbius capacity, and that \(\sum_{T \subseteq N} m(T) = 1\)
- Returns
Note
use
math.isclose()to add tolerance
- property is_powerset_function: bool
Check if the set function is defined on a power set.
Check length of set_function is a power of 2.
- Returns
- property set_function: SetFunction
Return set function from it Möbius transform.
- Returns
Note
Formula is based on [GKM08].
- property size: int
Return the size of the ensemble of this set function.
- Returns
- property values: Dict
Return a copy of the dictionary defining this set function.
- Returns
- class SetFunction(values, ensemble=None, validate=True)
Bases:
ISetFunctionThis class represents a set function.
- Parameters
values (Union[List, Dict, ISetFunction]) –
- values of the function as either:
a list ordered as a binary mask on the ensemble
a dictionary with
HashableSetas keysanother
SetFunctionobject (used for casting)
ensemble (Union[List, None]) – ensemble from which to build the set (its default value is \(\mathbf{Z}^+\))
validate (bool) –
- __call__(*args, **kwargs)
Call this set function on the set composed of all provided arguments
- Returns
value
- property as_capacity: Self
Return the instance if it respects its properties.
- The properties are the following:
the set function is defined on a power set
the set function is a game
the set function is monotonous
the set function is normal
- Raises
KeyError –
if set function is not defined on a power set
ValueError –
if set function is not a game
if set function is not monotonous
if set function is not normal
- property ensemble: List
Return a copy of the ensemble of this set function.
- Returns
- property interaction_index: DataFrame
Return interaction index matrix.
- Returns
Note
Formula is based on [GKM08].
- property is_additive: bool
Check if the set function is additive or not.
Check that \(\forall S, T \subseteq N, S \cap T = \emptyset, \mu(S \cup T) = \mu(S) + \mu(T)\)
- Returns
Note
use
math.isclose()to add tolerance
- property is_capacity: bool
Check if the instance is a capacity.
- The properties are the following:
the set function is defined on a power set
the set function is a game
the set function is monotonous
the set function is normal
- Returns
Trueif instance is a capacity,Falseotherwise
- property is_cardinality_based: bool
Check if the set function is cardinality-based.
Check that \(\forall T \subseteq N, \mu(T)\) only depends on T cardinality.
- Returns
Note
use
math.isclose()to add tolerance
- property is_game: bool
Check if the set function is a game.
Check \(\nu(\emptyset) = 0\)
- Returns
- is_k_additive(k)
Check if it is a k-additive capacity.
- Parameters
k (int) –
- Returns
- Return type
bool
Note
use
math.isclose()to add absolute tolerance
- property is_monotonous: bool
Check if the set function is monotonous.
Check that \(\forall S, T \subseteq N, S \subseteq T \Rightarrow \nu(S) \leq \nu(T)\)
- Returns
Note
use
math.isclose()to add tolerance
- property is_normal: bool
Check if the set function is normalized.
Check set_function is a capacity, and that \(\nu(N) = 1\)
- Returns
Note
use
math.isclose()to add tolerance
- property is_powerset_function: bool
Check if the set function is defined on a power set.
Check length of set_function is a power of 2.
- Returns
- property mobius: Mobius
Return Möbius transform of a set function.
- Returns
Note
Formula is based on [GKM08].
- property size: int
Return the size of the ensemble of this set function.
- Returns
- static uniform_capacity(ensemble)
Return uniform capacity of given ensemble.
The uniform capacity on an ensemble N of size size is given by:
\[\mu^*(T) = t/n, \forall T \subseteq N\]- Parameters
ensemble (List) –
- Returns
- Return type
Note
Formula is based on [GKM08].
- property values: Dict
Return a copy of the dictionary defining this set function.
- Returns