`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.DecisionMatrix(data_df, objectives, weights)[source]

Bases: DiffEqualityMixin

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:
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]

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.

From this array you can also access the values of the alternatives as pandas.Series.

property criteria

Names of the criteria.

From this array you can also access the values of the criteria as pandas.Series.

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 objectives 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.

constant_criteria(std_kws=None, isclose_kws=None)[source]

Identifies criteria with constant values based on std deviation.

This method calculates the standard deviation of each column and determines which are effectively constant (standard deviation ~ 0) using numerical comparison with tolerance.

Parameters:

std_kws (dict, optional) – Additional keyword arguments for pandas.DataFrame.std(). Default: {}
isclose_kws (dict, optional) – Additional keyword arguments for numpy.isclose(). Default: {}

Returns:

Boolean series where True indicates the column is constant. Index corresponds to DataFrame column names. Series name is ‘ConstantsCriteria’.

Return type:

pandas.Series

copy(**kwargs)[source]

Create a copy of the current DecisionMatrix instance.

Deprecated since version 0.9: Using kwargs with copy() is deprecated. Use DecisionMatrix.replace() instead.

Parameters:: **kwargs (dict, optional (deprecated)) – Keyword arguments to modify attributes in the copied instance. This parameter is deprecated.
Returns:: A new DecisionMatrix instance with the same data as the original.
Return type:: DecisionMatrix

See also

replace: Preferred method to create a copy with modifications.

replace(**kwargs)[source]

Create a new DecisionMatrix instance with updated attributes.

Creates a copy of the current DecisionMatrix and updates it with the provided keyword arguments.

Parameters:: **kwargs (dict) – Keyword arguments specifying attributes to modify in the new instance. Any valid DecisionMatrix attribute can be updated.
Returns:: A new DecisionMatrix instance with the updated attributes.
Return type:: DecisionMatrix

Examples

>>> dm = DecisionMatrix(...)
>>> new_dm = dm.replace(weights=[0.3, 0.7])

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.

to_latex(bold_columns=True, **kwargs)[source]

Generate LaTeX table.

Parameters:

bold_columns (bool, default=True) – If True, bold the columns.
pandas.DataFrame.to_latex(). (Same parameters as)

Returns:

LaTeX table.

Return type:

str

Notes

By default, this method uses bold_rows=True.

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.

Deprecated since version 0.6: Use DecisionMatrix.stats(), DecisionMatrix.stats('describe) or DecisionMatrix.stats.describe() instead.

Parameters:: pandas.DataFrame.describe(). (Same parameters as)
Returns:: Summary statistics of DecisionMatrix provided.
Return type:: pandas.DataFrame

to_dmsy(filepath_or_buffer=None)[source]

Save a DecisionMatrix to a DMSY format file or buffer.

Parameters:: filepath_or_buffer (str or file-like object or None) – Path where to save the DMSY file or a file-like object to write to. if None, return the DMSY data as a string
Returns:: DMSY data as a string if filepath_or_buffer is None else None
Return type:: str

Examples

>>> import skcriteria as skc
>>> dm = skc.mkdm([[1, 2], [3, 4]], [max, min])
>>> skc.io.to_dmsy(dm, "output.dmsy")

property shape

Return a tuple with (number_of_alternatives, number_of_criteria).

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

diff(other, rtol=1e-05, atol=1e-08, equal_nan=True, check_dtypes=False)[source]

Return the difference between two objects within a tolerance.

This method should be implemented by subclasses to define how differences between objects are calculated.

The tolerance parameters rtol and atol, equal_nan, and check_dtypes are provided to be used by the numpy and pandas equality functions. These parameters allow you to customize the behavior of the equality comparison, such as setting the relative and absolute tolerance for numeric comparisons, considering NaN values as equal, and checking for the data type of the objects being compared.

Parameters:

other (object) – The object to compare to.
rtol (float, optional) – The relative tolerance parameter. Default is 1e-05.
atol (float, optional) – The absolute tolerance parameter. Default is 1e-08.
equal_nan (bool, optional) – Whether to consider NaN values as equal. Default is True.
check_dtypes (bool, optional) – Whether to check the data type of the objects. Default is False.

Returns:

The difference between the current and the other object.

Return type:

the_diff

See also

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

Notes

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.

property loc

Access a group of alternatives and criteria by label(s) or a boolean array.

.loc[] is primarily alternative label based, but may also be used with a boolean array.

Unlike DataFrames, ìloc` of DecisionMatrix always returns an instance of DecisionMatrix.

property iloc

Purely integer-location based indexing for selection by position.

.iloc[] is primarily integer position based (from 0 to length-1 of the axis), but may also be used with a boolean array.

Unlike DataFrames, ìloc` of DecisionMatrix always returns an instance of DecisionMatrix.

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.

skcriteria.core.data module

`skcriteria.core.data` module