relations

This module gathers all classes used to represent binary relations between alternatives (P, I, R) and the preference structure based on those.

I

Type alias for user-friendly definition of IndifferenceRelation

class IncomparableRelation(a, b)

Bases: Relation

This class represents an incomparable relation between two elements.

A relation is read aRb.

Parameters

• a (Any) – first element

• b (Any) – second element

Raises

ValueError – if relation is reflexive

Attribute a

Attribute b

Attribute DRAW_STYLE

(class) key args for plotting all instances

Note

this relation is symmetric and irreflexive

DRAW_STYLE = {'arrowhead': 'none', 'style': 'dotted'}

compatible(other)

Check whether both relations can coexist in the same preference structure.

Relations are compatible if equal or having different elements pair.

Parameters

other (Relation) –

Returns

check result

Return type

bool

Warning

Does not check for relations’ validity!

property elements: Tuple[Any, Any]

Return elements of the relation

same_elements(relation)

Check whether the relations are about the same pair of alternatives.

Parameters

relation (Relation) – second relation

Returns

True if both relations share the same elements pair, False otherwise

Return type

bool

Warning

Does not check for relations’ validity!

static types()

Return list of relation types.

Returns

Return type

List

class IndifferenceRelation(a, b)

Bases: Relation

This class represents an indifference relation between two elements.

A relation is read aIb.

Parameters

• a (Any) – first element

• b (Any) – second element

Attribute a

Attribute b

Attribute DRAW_STYLE

(class) key args for plotting all instances

Note

this relation is symmetric and reflexive

DRAW_STYLE = {'arrowhead': 'none'}

compatible(other)

Check whether both relations can coexist in the same preference structure.

Relations are compatible if equal or having different elements pair.

Parameters

other (Relation) –

Returns

check result

Return type

bool

Warning

Does not check for relations’ validity!

property elements: Tuple[Any, Any]

Return elements of the relation

same_elements(relation)

Check whether the relations are about the same pair of alternatives.

Parameters

relation (Relation) – second relation

Returns

True if both relations share the same elements pair, False otherwise

Return type

bool

Warning

Does not check for relations’ validity!

static types()

Return list of relation types.

Returns

Return type

List

P

Type alias for user-friendly definition of PreferenceRelation

class PreferenceRelation(a, b)

Bases: Relation

This class represents a preference relation between two elements.

A relation is read aPb.

Parameters

• a (Any) – first element

• b (Any) – second element

Raises

ValueError – if relation is reflexive

Attribute a

Attribute b

Attribute DRAW_STYLE

(class) key args for plotting all instances

Note

this relation is antisymmetric and irreflexive

DRAW_STYLE: Dict[str, Any] = {}

compatible(other)

Check whether both relations can coexist in the same preference structure.

Relations are compatible if equal or having different elements pair.

Parameters

other (Relation) –

Returns

check result

Return type

bool

Warning

Does not check for relations’ validity!

property elements: Tuple[Any, Any]

Return elements of the relation

same_elements(relation)

Check whether the relations are about the same pair of alternatives.

Parameters

relation (Relation) – second relation

Returns

True if both relations share the same elements pair, False otherwise

Return type

bool

Warning

Does not check for relations’ validity!

static types()

Return list of relation types.

Returns

Return type

List

class PreferenceStructure(data=None, validate=True)

Bases: object

This class represents a list of relations.

Any type of relations is accepted, so this represents the union of P, I and R.

Parameters

• data (Union[List[Relation], Relation, PreferenceStructure, None]) –

• validate (bool) – whether to check compatibility of relations

Raises

ValueError – if relations are not compatible and validate is True

copy()

Copy preference structure into new object.

Returns

copy

Return type

PreferenceStructure

property elements: List

Return elements present in relations list.

property elements_pairs_relations: Mapping[Tuple[Any, Any], Optional[Relation]]

Return the relations keyed by elements pairs

property elements_structures: Mapping[Any, PreferenceStructure]

Return this preference structure viewed by each element

classmethod from_outranking_matrix(outranking_matrix)

Convert outranking matrix to preference structure.

Parameters

outranking_matrix (AdjacencyValueMatrix[DiscreteQuantitativeScale]) –

Returns

Return type

Self

classmethod from_ranking(ranking)

Convert ranking into preference structure.

Parameters

ranking (CommensurableValues[OrdinalScale]) –

Returns

Return type

Self

Note

The minimum number of relations representing the scores is returned (w.r.t transitivity of preference and indifference relations)

property is_total_order: bool

Check whether relations list is a total order or not

property is_total_preorder: bool

Check whether relations list is a total preorder or not

property outranking_matrix: AdjacencyValueMatrix[DiscreteQuantitativeScale]

Transform a preference structure into an outranking matrix.

Returns

outranking matrix

plot()

Create graph from preference structure and plot it.

Returns

graph

Return type

Digraph

Note

You need an environment that will actually display the graph (such as a jupyter notebook), otherwise the function only returns the graph.

property ranking: CommensurableValues[QuantitativeScale]

Convert preference structure to ranking.

Raises

ValueError – if preference_structure is not a total pre-order

Returns

Note

returned ranking goes for 0 to n-1 (with 0 the best rank)

property relations: List[Relation]

Return relations list.

save_plot()

Plot preference structure as a graph and save it.

Returns

file name where plot is saved

Return type

str

substructure(elements=None, types=None)

Return a new preference structure containing only set arguments.

Parameters

• elements (Optional[List]) – if None all elements are used

• types (Optional[List[Type[Relation]]]) – if None, all types of relations are used

Returns

Return type

PreferenceStructure

property transitive_closure: PreferenceStructure

Apply transitive closure to preference structure and return result.

Warning

Does not check for a valid preference structure!

property transitive_reduction: PreferenceStructure

Apply transitive reduction to preference structure and return result

Warning

Does not check for a valid preference structure!

Warning

This function may bundle together multiple elements

property typed_structures: Mapping[Type[Relation], PreferenceStructure]

Return the preference structures for each type of relation

R

Type alias for user-friendly definition of IncomparableRelation