matrices

This module contains all functions related to matrices (2D and 3D).

class AdditivePerformanceTable(data, scales=None, aggregated_scale=None, alternatives=None, criteria=None, stype=None, **kwargs)

Bases: PerformanceTable[QuantitativeScale]

This class defines a performance table with additive values.

Parameters

  • data –

  • scales (Union[QuantitativeScale, Mapping[Any, QuantitativeScale], None]) – data scale(s) (one per column or one shared, will be inferred from data if absent using Scale.fit())

  • aggregated_scale (Union[QuantitativeScale, None]) – output scale of row-wise aggregation (inferred if not provided)

  • alternatives (Union[List, None]) – if not set, inferred from data

  • criteria (Union[List, None]) – if not set, inferred from data

  • stype (Union[Type[QuantitativeScale], None]) – scales type used

Raises

  • KeyError –

    • if some indexes are duplicated

    • if some columns are duplicated

  • TypeError – if stype and scales types mismatch

Note

This class is not intended for general use, it can though be the output of some algorithms.

property alternatives: List

Return performance table alternatives

property alternatives_values: Mapping[Any, Values[S]]

Iterator on the table alternatives values

property bounds: Mapping[Any, S]

Return scales inferred from values.

property cell: Mapping[Tuple[Any, Any], Any]

Return matrix cell accessor.

Note

actually returns DataFrame.at() from data

property columns: List

Return column labels.

property columns_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table criteria values

classmethod concat(matrices, axis=0, **kwargs)

Concatenate multiple value matrices.

Parameters

  • matrices (Sequence[IValueMatrix]) –

  • axis (Literal[0, 1]) – axis along which to concatenate (0: add alternatives, 1: add criteria)

Returns

concatenated value matrix

Return type

Self

Warning

matrices objects are concatenated as is, no transformation of scales is applied.

copy()

Return a copy of the object

Return type

Self

property criteria: List

Return performance table criteria

property criteria_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table criteria values

property efficients: List

Return efficient alternatives.

This is the list of alternatives that are not strongly dominated by another one.

Returns

property is_numeric: bool

Check whether table is numeric.

Returns

Return type

bool

property is_ordinal: bool

Check whether scales are all ordinal.

Returns

property is_within_scales: bool

Check whether all values are within their respective scales.

Returns

property rows: List

Return row labels.

property rows_values: Mapping[Any, Values[S]]

Iterator on the table alternatives values

subtable(rows=None, columns=None)

Return the subtable containing given rows and columns.

Parameters

  • rows (Optional[List]) –

  • columns (Optional[List]) –

Returns

Return type

Self

sum(axis=None)

Return the sum of the data (all table, row or column-wise).

Parameters

axis (Optional[Literal[0, 1]]) –

  • 0: column-wise sum

  • 1: row-wise sum

  • None: complete sum

Returns

Return type

Union[CommensurableValues[QuantitativeScale], float]

Warning

it will raise a TypeError if data contains numeric and non-numeric values

Note

if axis is 1, aggregated_scale is used as the result scale

property to_numeric: PerformanceTable[QuantitativeScale]

Return numeric conversion of ordinal values.

Raises

TypeError – if scales are not ordinal

property union_bounds: S

Return one scale for whole matrix inferred from values.

property within_scales: DataFrame

Return a dataframe indicating which values are within their respective scale.

Returns

class AdjacencyValueMatrix(data, vertices=None, scale=None, stype=None, **kwargs)

Bases: IAdjacencyMatrix, IValueMatrix[S], Generic[S]

This class implements graphs as an adjacency value matrix.

The adjacency matrix is represented internally by a pandas.DataFrame with vertices as the indexes and columns.

Parameters

  • data – adjacency matrix in an array-like or dict-structure

  • vertices (Union[List, None]) –

  • scale (Union[S, None]) –

  • stype (Union[Type[S], None]) – scales type used

Raises

  • KeyError –

    • if columns and rows have different sets of labels

    • if some vertices are duplicated

  • TypeError – if stype and scale type mismatch

Note

the cells of the matrix can be of any type (not just numerics)

property bounds: Mapping[Any, S]

Return scales inferred from values.

property cell: Mapping[Tuple[Any, Any], Any]

Return matrix cell accessor.

Note

actually returns DataFrame.at() from data

property columns: List

Return column labels.

property columns_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table alternatives values

copy()

Return a copy of the object

Return type

Self

property cycle_reduction_matrix: AdjacencyValueMatrix[DiscreteQuantitativeScale]

Return matrix with cycles removed.

Returns

Raises

TypeError – if matrix is not binary

classmethod from_ordered_alternatives_groups(categories)

Convert a ranking of categories of alternatives into an outranking matrix.

Parameters

categories (List[List]) – the ranked categories (each category is a list of alternatives)

Returns

outranking matrix

Return type

AdjacencyValueMatrix[DiscreteQuantitativeScale]

property graph_condensation: AdjacencyValueMatrix[DiscreteQuantitativeScale]

Return the condensation graph

Returns

Raises

TypeError – if matrix is not binary

Note

the matrix output by this function is acyclic

Warning

this function changes the matrix shape

property is_binary: bool

Check whether adjacency value matrix is binary.

Returns

property is_numeric: bool

Check whether table is numeric.

Returns

Return type

bool

property is_ordinal: bool

Check whether scales are all ordinal.

Returns

property is_within_scales: bool

Check whether all values are within their respective scales.

Returns

property kernel: List

Return the kernel of the graph if existing.

The kernel is a stable and dominant set of nodes. Dominant nodes are the origin of edges, dominated ones are the target.

Returns

the kernel (if existing), else an empty list

Raises

TypeError – if matrix is not binary

plot(edge_label=False, self_loop=False)

Plot adjacency matrix as a graph.

Parameters

  • edge_label (bool) – (optional) parameter to display the value of edges

  • self_loop (bool) – (optional) parameter to display self looping edges

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 rows: List

Return row labels.

property rows_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table alternatives values

save_plot(edge_label=False, self_loop=False)

Plot adjacency matrix as a graph and save it.

Parameters

  • edge_label (bool) – (optional) parameter to display the value of edges

  • self_loop (bool) – (optional) parameter to display self looping edges

Returns

file name where plot is saved

Return type

str

subtable(vertices)

Return the subtable containing given vertices.

Parameters

vertices (List) –

Returns

Return type

Self

sum(axis=None)

Return the sum of the data (all table, row or column-wise).

Parameters

axis (Optional[Literal[0, 1]]) –

  • 0: column-wise sum

  • 1: row-wise sum

  • None: complete sum

Returns

Return type

Union[CommensurableValues[QuantitativeScale], float]

Warning

it will raise a TypeError if data contains numeric and non-numeric values

to_graph(edge_label=False, self_loop=False)

Create a graph for adjacency matrix.

This function creates a Graph using graphviz.

Parameters

  • edge_label (bool) – (optional) parameter to display the value of edges

  • self_loop (bool) – (optional) parameter to display self looping edges

Returns

graph

Return type

Digraph

property to_numeric: AdjacencyValueMatrix[QuantitativeScale]

Return numeric conversion of ordinal values.

Raises

TypeError – if scales are not ordinal

property transitive_closure: AdjacencyValueMatrix[DiscreteQuantitativeScale]

Return transitive closure of matrix.

Returns

Raises

TypeError – if matrix is not binary

property transitive_reduction: AdjacencyValueMatrix[DiscreteQuantitativeScale]

Return transitive reduction of matrix.

Returns

Raises

TypeError – if matrix is not binary

Note

this function can change the matrix shape

property union_bounds: S

Return one scale for whole matrix inferred from values.

property vertices: List

Return list of vertices

property within_scales: DataFrame

Return a dataframe indicating which values are within their respective scale.

Returns

class PartialValueMatrix(data, vertices=None, criteria=None, scales=None, stype=None, **kwargs)

Bases: IAdjacencyMatrix, Generic[S]

This class describes a matrix of partial values.

Parameters

  • data –

  • vertices (Union[List, None]) – labels used to identify both rows and columns

  • criteria (Union[List, None]) – labels used for the values in each cell

  • scales (Union[S, Mapping[Any, S], None]) –

  • stype (Union[Type[S], None]) – scales type used

Raises

  • KeyError –

    • if columns and rows have different sets of labels

    • if some vertices are duplicated

  • TypeError – if stype and scale type mismatch

property bounds: Mapping[Any, S]

Infer common scales for each values cell.

Returns

inferred scales

property cell: Mapping[Tuple[Any, Any], Values[S]]

Return matrix cell accessor

property column_matrices: Mapping[Any, PerformanceTable[S]]

Iterator on the table columns.

property columns: List

Return column labels.

copy()

Return a copy of the object

Return type

Self

property criteria: List
property criteria_matrices: Mapping[Any, AdjacencyValueMatrix[S]]

Iterator on the table criteria.

property is_numeric: bool

Check whether table is numeric.

Returns

Return type

bool

property is_ordinal: bool

Check whether scales are all ordinal.

Returns

property is_within_scales: bool

Check whether all values are within their respective scales.

Returns

property row_matrices: Mapping[Any, PerformanceTable[S]]

Iterator on the table rows.

property rows: List

Return row labels.

subtable(vertices=None, criteria=None)

Return the subtable containing given rows and columns.

Parameters

  • rows –

  • columns –

  • vertices (Optional[List]) –

  • criteria (Optional[List]) –

Returns

Return type

Self

property to_numeric: PartialValueMatrix[QuantitativeScale]

Return numeric conversion of ordinal values.

Raises

TypeError – if scales are not ordinal

property vertices: List

Return list of vertices

property within_scales: DataFrame

Return a dataframe indicating which values are within their respective scale.

Returns

class PerformanceTable(data, scales=None, alternatives=None, criteria=None, stype=None, **kwargs)

Bases: IValueMatrix[S], Generic[S]

This class defines a performance table.

Parameters

  • data –

  • scales (Union[S, Mapping[Any, S], None]) – data scale(s) (one per column or one shared, will be inferred from data if absent using Scale.fit())

  • alternatives (Union[List, None]) – if not set, inferred from data

  • criteria (Union[List, None]) – if not set, inferred from data

  • stype (Union[Type[S], None]) – scales type used

Raises

  • KeyError –

    • if some indexes are duplicated

    • if some columns are duplicated

  • TypeError – if stype and scales types mismatch

property alternatives: List

Return performance table alternatives

property alternatives_values: Mapping[Any, Values[S]]

Iterator on the table alternatives values

property bounds: Mapping[Any, S]

Return scales inferred from values.

property cell: Mapping[Tuple[Any, Any], Any]

Return matrix cell accessor.

Note

actually returns DataFrame.at() from data

property columns: List

Return column labels.

property columns_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table criteria values

classmethod concat(matrices, axis=0, **kwargs)

Concatenate multiple value matrices.

Parameters

  • matrices (Sequence[IValueMatrix]) –

  • axis (Literal[0, 1]) – axis along which to concatenate (0: add alternatives, 1: add criteria)

Returns

concatenated value matrix

Return type

Self

Warning

matrices objects are concatenated as is, no transformation of scales is applied.

copy()

Return a copy of the object

Return type

Self

property criteria: List

Return performance table criteria

property criteria_values: Mapping[Any, CommensurableValues[S]]

Iterator on the table criteria values

property efficients: List

Return efficient alternatives.

This is the list of alternatives that are not strongly dominated by another one.

Returns

property is_numeric: bool

Check whether table is numeric.

Returns

Return type

bool

property is_ordinal: bool

Check whether scales are all ordinal.

Returns

property is_within_scales: bool

Check whether all values are within their respective scales.

Returns

property rows: List

Return row labels.

property rows_values: Mapping[Any, Values[S]]

Iterator on the table alternatives values

subtable(rows=None, columns=None)

Return the subtable containing given rows and columns.

Parameters

  • rows (Optional[List]) –

  • columns (Optional[List]) –

Returns

Return type

Self

sum(axis=None)

Return the sum of the data (all table, row or column-wise).

Parameters

axis (Optional[Literal[0, 1]]) –

  • 0: column-wise sum

  • 1: row-wise sum

  • None: complete sum

Returns

Return type

Union[CommensurableValues[QuantitativeScale], float]

Warning

it will raise a TypeError if data contains numeric and non-numeric values

property to_numeric: PerformanceTable[QuantitativeScale]

Return numeric conversion of ordinal values.

Raises

TypeError – if scales are not ordinal

property union_bounds: S

Return one scale for whole matrix inferred from values.

property within_scales: DataFrame

Return a dataframe indicating which values are within their respective scale.

Returns

create_outranking_matrix(data, vertices=None, **kwargs)

Create an outranking matrix.

Parameters

  • data – adjacency matrix in an array-like or dict-structure

  • vertices (Optional[List]) –

Raises

  • KeyError –

    • if columns and rows have different sets of labels

    • if some vertices are duplicated

  • TypeError – if data is not binary

Return type

AdjacencyValueMatrix[DiscreteQuantitativeScale]

Note

This function is just an easier way to create AdjacencyValueMatrix with binary scale

dataframe_equals(df1, df2)

Check if two dataframes have the same values.

It will realign the indexes and columns if they are ordered differently.

Parameters

  • df1 (DataFrame) –

  • df2 (DataFrame) –

Returns

Return type

bool

Todo

integrate into mcda/core.adjacency_matrix.Matrix