skcriteria.core.data module

Data abstraction layer.

This module defines the DecisionMatrix object, which internally encompasses the alternative matrix, weights and objectives (MIN, MAX) of the criteria.

class skcriteria.core.data.Objective(value)[source]

Bases: enum.Enum

Representation of criteria objectives (Minimize, Maximize).

MIN = -1

Internal representation of minimize criteria

MAX = 1

Internal representation of maximize criteria

classmethod construct_from_alias(alias)[source]

Return the alias internal representation of the objective.

to_string()[source]

Return the printable representation of the objective.

class skcriteria.core.data.DecisionMatrix(data_df, objectives, weights)[source]

Bases: object

Representation of all data needed in the MCDA analysis.

This object gathers everything necessary to represent a data set used in MCDA:

  • An alternative matrix where each row is an alternative and each column is of a different criteria.

  • An optimization objective (Minimize, Maximize) for each criterion.

  • A weight for each criterion.

  • An independent type of data for each criterion

DecisionMatrix has two main forms of construction:

  1. Use the default constructor of the DecisionMatrix class pandas.DataFrame where the index is the alternatives and the columns are the criteria; an iterable with the objectives with the same amount of elements that columns/criteria has the dataframe; and an iterable with the weights also with the same amount of elements as criteria.

    
    
    >>> import pandas as pd
    >>> from skcriteria import DecisionMatrix, mkdm
    
    >>> data_df = pd.DataFrame(
    ...     [[1, 2, 3], [4, 5, 6]],
    ...     index=["A0", "A1"],
    ...     columns=["C0", "C1", "C2"]
    ... )
    >>> objectives = [min, max, min]
    >>> weights = [1, 1, 1]
    
    >>> dm = DecisionMatrix(data_df, objectives, weights)
    >>> dm
       C0[▼ 1.0] C1[▲ 1.0] C2[▲ 1.0]
    A0         1         2         3
    A1         4         5         6
    [2 Alternatives x 3 Criteria]
    
  1. Use the classmethod DecisionMatrix.from_mcda_data which requests the data in a more natural way for this type of analysis (the weights, the criteria / alternative names, and the data types are optional)

    >>> DecisionMatrix.from_mcda_data(
    ...     [[1, 2, 3], [4, 5, 6]],
    ...     [min, max, min],
    ...     [1, 1, 1])
       C0[▼ 1.0] C1[▲ 1.0] C2[▲ 1.0]
    A0         1         2         3
    A1         4         5         6
    [2 Alternatives x 3 Criteria]
    

    For simplicity a function is offered at the module level analogous to from_mcda_data called mkdm (make decision matrix).

Parameters
  • data_df (pandas.DatFrame) – Dataframe where the index is the alternatives and the columns are the criteria.

  • objectives (numpy.ndarray) – Aan iterable with the targets with sense of optimality of every criteria (You can use any alias defined in Objective) the same length as columns/criteria has the data_df.

  • weights (numpy.ndarray) – An iterable with the weights also with the same amount of elements as criteria.

classmethod from_mcda_data(matrix, objectives, weights=None, alternatives=None, criteria=None, dtypes=None)[source]

Create a new DecisionMatrix object.

This method receives the parts of the matrix, in what conceptually the matrix of alternatives is usually divided

Parameters
  • matrix (Iterable) – The matrix of alternatives. Where every row is an alternative and every column is a criteria.

  • objectives (Iterable) – The array with the sense of optimality of every criteria. You can use any alias provided by the objective class.

  • weights (Iterable o None (default None)) – Optional weights of the criteria. If is None all the criteria are weighted with 1.

  • alternatives (Iterable o None (default None)) – Optional names of the alternatives. If is None, al the alternatives are names “A[n]” where n is the number of the row of matrix statring at 0.

  • criteria (Iterable o None (default None)) – Optional names of the criteria. If is None, al the alternatives are names “C[m]” where m is the number of the columns of matrix statring at 0.

  • dtypes (Iterable o None (default None)) – Optional types of the criteria. If is None, the type is inferred automatically by pandas.

Returns

A new decision matrix.

Return type

DecisionMatrix

Example

>>> DecisionMatrix.from_mcda_data(
...     [[1, 2, 3], [4, 5, 6]],
...     [min, max, min],
...     [1, 1, 1])
   C0[▼ 1.0] C1[▲ 1.0] C2[▲ 1.0]
A0         1         2         3
A1         4         5         6
[2 Alternatives x 3 Criteria]

For simplicity a function is offered at the module level analogous to from_mcda_data called mkdm (make decision matrix).

Notes

This functionality generates more sensitive defaults than using the constructor of the DecisionMatrix class but is slower.

property alternatives

Names of the alternatives.

property criteria

Names of the criteria.

property weights

Weights of the criteria.

property objectives

Objectives of the criteria as Objective instances.

property minwhere

Mask with value True if the criterion is to be minimized.

property maxwhere

Mask with value True if the criterion is to be maximized.

property iobjectives

Objectives of the criteria as int.

  • Minimize = Objective.MIN.value

  • Maximize = Objective.MAX.value

property matrix

Alternatives matrix as pandas DataFrame.

The matrix excludes weights and objectives.

If you want to create a DataFrame with objetvies and weights, use DecisionMatrix.to_dataframe()

property dtypes

Dtypes of the criteria.

property plot

Plot accessor.

property stats

Descriptive statistics accessor.

property dominance

Dominance information accessor.

copy(**kwargs)[source]

Return a deep copy of the current DecisionMatrix.

This method is also useful for manually modifying the values of the DecisionMatrix object.

Parameters

kwargs – The same parameters supported by from_mcda_data(). The values provided replace the existing ones in the object to be copied.

Returns

A new decision matrix.

Return type

DecisionMatrix

to_dataframe()[source]

Convert the entire DecisionMatrix into a dataframe.

The objectives and weights ara added as rows before the alternatives.

Returns

A Decision matrix as pandas DataFrame.

Return type

pd.DataFrame

Example

>>> dm = DecisionMatrix.from_mcda_data(
>>> dm
...     [[1, 2, 3], [4, 5, 6]],
...     [min, max, min],
...     [1, 1, 1])
    C0[▼ 1.0] C1[▲ 1.0] C2[▲ 1.0]
A0         1         2         3
A1         4         5         6

>>> dm.to_dataframe()
            C0   C1   C2
objectives  MIN  MAX  MIN
weights     1.0  1.0  1.0
A0            1    2    3
A1            4    5    6
to_dict()[source]

Return a dict representation of the data.

All the values are represented as numpy array.

describe(**kwargs)[source]

Generate descriptive statistics.

Descriptive statistics include those that summarize the central tendency, dispersion and shape of a dataset’s distribution, excluding NaN values.

Parameters

pandas.DataFrame.describe(). (Same parameters as) –

Returns

Summary statistics of DecisionMatrix provided.

Return type

pandas.DataFrame

property shape

Return a tuple with (number_of_alternatives, number_of_criteria).

dm.shape <==> np.shape(dm)

equals(other)[source]

Return True if the decision matrix are equal.

This method calls DecisionMatrix.aquals whitout tolerance.

Parameters

other (skcriteria.DecisionMatrix) – Other instance to compare.

Returns

equals – Returns True if the two dm are equals.

Return type

bool:py:class:

See also

aequals, numpy.isclose(), numpy.all(), numpy.any(), numpy.equal(), numpy.allclose()

aequals(other, rtol=1e-05, atol=1e-08, equal_nan=False)[source]

Return True if the decision matrix are equal within a tolerance.

The tolerance values are positive, typically very small numbers. The relative difference (rtol * abs(b)) and the absolute difference atol are added together to compare against the absolute difference between a and b.

NaNs are treated as equal if they are in the same place and if equal_nan=True. Infs are treated as equal if they are in the same place and of the same sign in both arrays.

The proceeds as follows:

  • If other is the same object return True.

  • If other is not instance of ‘DecisionMatrix’, has different shape ‘criteria’, ‘alternatives’ or ‘objectives’ returns False.

  • Next check the ‘weights’ and the matrix itself using the provided tolerance.

Parameters
  • other (skcriteria.DecisionMatrix) – Other instance to compare.

  • rtol (float) – The relative tolerance parameter (see Notes in numpy.allclose()).

  • atol (float) – The absolute tolerance parameter (see Notes in numpy.allclose()).

  • equal_nan (bool) – Whether to compare NaN’s as equal. If True, NaN’s in dm will be considered equal to NaN’s in other in the output array.

Returns

aequals – Returns True if the two dm are equal within the given tolerance; False otherwise.

Return type

bool:py:class:

See also

equals, numpy.isclose(), numpy.all(), numpy.any(), numpy.equal(), numpy.allclose()

skcriteria.core.data.mkdm(matrix, objectives, weights=None, alternatives=None, criteria=None, dtypes=None)[source]

Create a new DecisionMatrix object.

This method receives the parts of the matrix, in what conceptually the matrix of alternatives is usually divided

Parameters
  • matrix (Iterable) – The matrix of alternatives. Where every row is an alternative and every column is a criteria.

  • objectives (Iterable) – The array with the sense of optimality of every criteria. You can use any alias provided by the objective class.

  • weights (Iterable o None (default None)) – Optional weights of the criteria. If is None all the criteria are weighted with 1.

  • alternatives (Iterable o None (default None)) – Optional names of the alternatives. If is None, al the alternatives are names “A[n]” where n is the number of the row of matrix statring at 0.

  • criteria (Iterable o None (default None)) – Optional names of the criteria. If is None, al the alternatives are names “C[m]” where m is the number of the columns of matrix statring at 0.

  • dtypes (Iterable o None (default None)) – Optional types of the criteria. If is None, the type is inferred automatically by pandas.

Returns

A new decision matrix.

Return type

DecisionMatrix

Example

>>> DecisionMatrix.from_mcda_data(
...     [[1, 2, 3], [4, 5, 6]],
...     [min, max, min],
...     [1, 1, 1])
   C0[▼ 1.0] C1[▲ 1.0] C2[▲ 1.0]
A0         1         2         3
A1         4         5         6
[2 Alternatives x 3 Criteria]

For simplicity a function is offered at the module level analogous to from_mcda_data called mkdm (make decision matrix).

Notes

This functionality generates more sensitive defaults than using the constructor of the DecisionMatrix class but is slower.