pymcdm.io

class pymcdm.io.MCDA_problem(matrix: ndarray | list | tuple, weights: ndarray | list | tuple, types: Sequence[{1, -1}], criteria_names: Sequence[str] = None, criteria_units: Sequence[str] = None, cvalues: ndarray | list | tuple = None, bounds: ndarray | list | tuple = None, esp: Sequence[float] = None, ref_ideal: ndarray | list | tuple = None)

Bases: object

Represents a Multi-Criteria Decision Analysis (MCDA) problem by aggregating elements of the decision problem and presenting them in a tabular format as text or LaTeX code. The matrix argument is used solely for validating the consistency of other parameters.

Parameters:

matrix (np.ndarray | list | tuple) – Decision matrix for validating dimensions and consistency of the problem. It will not be stored or outputted by to_latex() and to_string() methods.
weights (np.ndarray | list | tuple) – Array of weights assigned to each criterion.
types (Sequence[{1, -1}]) – Sequence indicating the optimization direction for each criterion (1 for maximization/profit, -1 for minimization/cost).
criteria_names (Sequence[str], optional) – List of names for each criterion, by default None.
criteria_units (Sequence[str], optional) – List of units for each criterion, by default None.
cvalues (np.ndarray | list | tuple, optional) – Array of characteristic values associated with each criterion, by default None. Normally used in the COMET method.
bounds (np.ndarray | list | tuple, optional) – Array of bounds for each criterion, by default None. Normally used in such methods as SPOTIS and RIM.
esp (Sequence[float or int], optional) – Expected values for each criterion, by default None. Normally used in the ESPExpert class.
ref_ideal (np.ndarray | list | tuple, optional) – Reference ideal values for each criterion, by default None. Normally used in the RIM method.

Raises:

ValueError – If matrix or types size does not match weights. If criteria_names or criteria_units length does not match weights. If esp, or ref_ideal are provided without bounds for validation. If the shape of cvalues is not supported.

df

A DataFrame containing the criteria description, including weights, types, names, units, cvalues, bounds, expected values, and reference ideals.

Type:: pandas.DataFrame

columns_order

The default order of columns for display in the DataFrame.

Type:: list of str

__str__()

Returns a string representation of the criteria description, equivalent to to_string().

Returns:: String representation of the criteria description.
Return type:: str

to_csv(filename, float_fmt: str = '%0.4f')

Writes the MCDA_problem table to csv with an option to change floating-point format.

Parameters:

filename (str) – Name of the file where data should be written. File will be overwritten.
float_fmt (str or None, optional) – A formatting string specifying the precision of floating-point numbers in the table. Defaults to ‘%0.4f’, storing four decimal places.

Return type:

None

to_json()

Returns a JSON string representation of the MCDA_problem table.

This method generates a JSON string representation of the table. MCDA_problem is represented as a JSON object, with fields:

‘label’ - ‘crit_desc’.
‘caption’ - ‘Criteria description.’
‘symbol’ - Empty string.
‘columns’ - Names of the columns as (list of strings).
‘data’ - Rows of the table (list of mixed values: string, float or int). First element will be row’s label (name of the criterion), other elements are data of the row.

Returns:: A JSON string representation of the table.
Return type:: str

to_latex(float_fmt: str = '%0.4f')

Returns a LaTeX-formatted table of the criteria description.

Parameters:: float_fmt (str or None, optional) – Format for floating-point numbers, by default ‘%0.4f’.
Returns:: LaTeX-formatted string of the criteria description table.
Return type:: str

to_string(float_fmt: str = '%0.4f')

Returns a plain text table of the criteria description.

Parameters:: float_fmt (str or None, optional) – Format for floating-point numbers, by default ‘%0.4f’.
Returns:: Plain text representation of the criteria description table.
Return type:: str

class pymcdm.io.MCDA_results(method: MCDA_method, matrix: ndarray | list | tuple, results: List[Table])

Bases: object

Represents the results of a Multi-Criteria Decision Analysis (MCDA) method, including the decision matrix, processed results tables, and optional ranking.

Parameters:

method (MCDA_method) – The MCDA method used for analysis.
matrix (np.ndarray | list | tuple) – The decision matrix used as input for the analysis.
results (list of Table) – A list of Table objects representing the analysis results.

method

The MCDA method used to generate the results.

Type:: MCDA_method

method_name

The name of the MCDA method class.

Type:: str

matrix

The decision matrix used as input for the MCDA method.

Type:: np.ndarray | list | tuple

results

A list of Table objects representing the analysis results.

Type:: list of Table

__str__()

Returns the string representation of the MCDA results, equivalent to to_string().

Returns:: String representation of the MCDA results.
Return type:: str

prepare_tables(group_tables: bool = True, ranking: bool = True, matrix: bool = True, fix_integers=True, **kwargs)

Prepares the resulted Tables according to the arguments, with options for grouping tables, including rankings, and displaying the decision matrix.

Parameters:

group_tables (bool, optional) – Whether to group tables with similar structure, by default True.
ranking (bool, optional) – Whether to include the ranking table in the output, by default True.
matrix (bool, optional) – Whether to include the decision matrix in the output, by default True.
fix_integers (bool, optional) – Whether to round integer values in tables, by default True. Applied only to decision matrix and ranking. Work only if all column is integer.
**kwargs – Used to omit errors when function is called with more arguments than defined.

Returns:

List of the Tables which can be processed further.

Return type:

list[Table]

to_csv(output_dir, **kwargs)

Returns the MCDA results formatted as a LaTeX string.

Parameters:

output_dir (str) – Output folder where csv files should be written.
**kwargs (dict) – Additional keyword arguments passed to prepare_tables() or to to_latex() functions.

Return type:

None

to_dict()

Returns a dictionary of the results with captions as keys and np.array objects as values.

Returns:: Dictionary where keys are captions of the tables in results and values are the np.array objects.
Return type:: dict

to_json(**kwargs)

Returns a JSON string representation of the decision analysis results.

This method generates a JSON string representation of the results. JSON contains list of JSON objects, where each object represents Table and have the following fields:

‘label’ - Short label described content of the table (string).
‘caption’ - Description of the table, in case of grouped tables captions are concatenated (string).
‘symbol’ - Symbol of the data in the data, according to the method’s algorithm (string).
‘columns’ - Names of the columns as (list of strings).
‘data’ - Rows of the table (list of mixed values: string, float or int). First element will be row’s label, other elements are data of the row.

Returns:: JSON representation of the MCDA results.
Return type:: str

to_latex(**kwargs)

Returns the MCDA results formatted as a LaTeX string.

Parameters:: **kwargs (dict) – Additional keyword arguments passed to prepare_tables() or to to_latex() functions.
Returns:: LaTeX-formatted string of the MCDA results.
Return type:: str

to_string(**kwargs)

Returns the MCDA results formatted as a plain text string.

Parameters:: **kwargs (dict) – Additional keyword arguments passed to prepare_output().
Returns:: Plain text string of the MCDA results.
Return type:: str

class pymcdm.io.Table(data: ndarray | list | tuple, desc: TableDesc)

Bases: object

Represents a table containing data for Multi-Criteria Decision Analysis (MCDA) processes, supporting LaTeX export and formatted row and column labeling.

Parameters:

data (np.ndarray | list | tuple) – The data for the table, either a 1D or 2D array, representing different data. This data is automatically converted to a NumPy array.
desc (TableDesc) – Metadata for the table, provided as a TableDesc instance, including caption, label, and symbol information used in LaTeX representations.

Raises:

ValueError – If the shape of data is not supported (only 1D or 2D arrays are allowed).

data

The primary data of the table, stored as a NumPy array.

Type:: np.ndarray

desc

The metadata description of the table, including caption and label information.

Type:: TableDesc

row_labels

List of labels for the table’s rows. Can be Callable with signature foo(n: int) -> List[str]. Size of the returned list should be same as number of rows in the Table (n).

Type:: List[str] or Callable

col_labels

List of labels for the table’s columns. Can be Callable with signature foo(n: int) -> List[str]. Size of the returned list should be same as number of columns in the Table (n).

Type:: List[str] or Callable

row_labels_name

The name or title of the row labels column in the table.

Type:: str

caption

Caption of the table. Caption with symbol from TableDesc will be used or only caption if no symbol is provided. Symbol will be added only if table is 2d.

Type:: str

df

A pandas DataFrame representation of the table, including row and column labels as well as data.

Type:: pd.DataFrame

fix_integers(): Converts columns in the table’s DataFrame to integer type if all values in the column are integers.

static from_group(group: List)

Creates a new Table instance by combining data from a group of existing Table objects.

This method aggregates the data attributes of multiple Table instances into a single table, where each original table contributes a column in the new table. Metadata for the new table, including a combined caption and label, is generated based on the metadata of the individual Table objects in the group. Aggregated tables should contain only 1d data.

Parameters:: group (list of Table) – A list of Table instances to be combined. Each table in the group should share compatible dimensions and metadata.
Returns:: A new Table instance containing the combined data and generated metadata.
Return type:: Table
Raises:: ValueError – If the group if the tables have incompatible data shapes.

generate_col_labels()

Generates or validates column labels for the table based on the provided labels in metadata.

Returns:: A list of column labels, either validated custom labels or automatically generated labels based on the table’s data shape.
Return type:: list of str
Raises:: ValueError – If cols is provided but does not match the number of columns in the data. If provided value’s type is wrong.

generate_row_labels()

Generates or validates row labels for the table based on the provided labels in metadata.

Returns:: A list of row labels, either validated custom labels or automatically generated labels based on the table’s data shape.
Return type:: list of str
Raises:: ValueError – If rows is provided as sequence but does not match the number of rows in the data. If provided value’s type is wrong.

generate_row_labels_name()

Generates or returns a row label name based on provided metadata.

Returns:: The row labels name.
Return type:: str

to_csv(filename, float_fmt: str = '%0.4f')

Writes the table to csv with an option to change floating-point format.

Parameters:

filename (str) – Name of the file where data should be written. File will be overwritten.
float_fmt (str or None, optional) – A formatting string specifying the precision of floating-point numbers in the table. Defaults to ‘%0.4f’, storing four decimal places.

Return type:

None

to_json()

Returns a JSON string representation of the table.

This method generates a JSON string representation of the table. Table is represented as a JSON object, with fields:

‘label’ - Short label described content of the table (string).
‘caption’ - Description of the table, in case of grouped tables captions are concatenated (string).
‘symbol’ - Symbol of the data in the data, according to the method’s algorithm (string).
‘columns’ - Names of the columns as (list of strings).
‘data’ - Rows of the table (list of mixed values: string, float or int). First element will be row’s label, other elements are data of the row.

Returns:: A JSON string representation of the table.
Return type:: str

to_latex(float_fmt: str = '%0.4f', label_prefix='')

Exports the table as a LaTeX-formatted string, with optional floating-point formatting.

This method generates a LaTeX tabular representation of the table’s DataFrame, including metadata such as a caption and label for referencing. The float format can be specified to control the precision of numeric values in the output.

Parameters:

float_fmt (str or None, optional) – A formatting string that specifies the precision of floating-point numbers in the table. Defaults to ‘%0.4f’ for four decimal places.
label_prefix (str, optional) – Add prefix to the label, for example if label_prefix=’topsis’ label will be ‘tab:topsis_matrix’ instead of ‘tab:matrix’. If used with MCDA_results class, name of the method will be used as the prefix.

Returns:

A string containing the table in LaTeX tabular format, ready for use in LaTeX documents.

Return type:

str

to_string(float_fmt: str = '%0.4f')

Returns a string representation of the table with an optional floating-point format.

This method generates a plain-text string representation of the table’s DataFrame, including the table’s caption as a header. The float format can be specified to control the precision of numeric values in the output.

Parameters:: float_fmt (str or None, optional) – A formatting string specifying the precision of floating-point numbers in the table. Defaults to ‘%0.4f’, showing four decimal places.
Returns:: A string representation of the table with the caption followed by the table data.
Return type:: str

class pymcdm.io.TableDesc(caption: str, label: str, symbol: str = None, rows: str = None, cols: str = None)

Bases: object

Represents metadata for a table used in the decision process, describing various attributes of the table including its caption, label, symbol, and orientation of rows and columns. Mostly for internal use.

Parameters:

caption (str) – A descriptive caption for the table, used as the main title or explanation in text or LaTeX representation.
label (str) – A short reference label for the table, primarily used in LaTeX for referencing purposes.
symbol (str or None, optional) – A mathematical symbol representing the data in the table as in the referenced paper. Defaults to None if no symbol is specified.
rows (str or list[str] or None) – Defines the labels of data stored in the rows of the table. Use ‘C’ to indicate criteria, or ‘A’ to indicate alternatives. Usage of custom symbol will result in labels like: $S_1$, $S_2$, etc. If list provided, then labels from the list will be used. Defaults to None if unspecified.
cols (str or list[str] or None) – Defines the labels of data stored in the columns of the table. Use ‘C’ to indicate criteria, or ‘A’ to indicate alternatives. Usage of custom symbol will result in labels like: $S_1$, $S_2$, etc. If list provided, then labels from the list will be used.

caption

The description or caption of the table.

Type:: str

label

The short reference label for the table in LaTeX or other references.

Type:: str

symbol

Mathematical symbol associated with the table data.

Type:: str or None

rows

Defines the labels of data stored in the rows of the table. Use ‘C’ to indicate criteria, or ‘A’ to indicate alternatives. Usage of custom symbol will result in labels like: $S_1$, $S_2$, etc. If list provided, then labels from the list will be used. Defaults to None if unspecified.

Type:: str or list[str] or None

cols

Defines the labels of data stored in the columns of the table. Use ‘C’ to indicate criteria, or ‘A’ to indicate alternatives. Usage of custom symbol will result in labels like: $S_1$, $S_2$, etc. If list provided, then labels from the list will be used.

Type:: str or list[str] or None

create_table(data: ndarray | list | tuple)

Creates Table object using this table description.

Parameters:: data (np.ndarray | list | tuple) – Data to create table from.
Returns:: Table object with provided data and current TableDesc as description.
Return type:: Table

static validate_option(opt: str)

Validates the provided option for row or column designation in a table.

This method ensures that the input opt is valid for designating rows or columns in a table. The valid options are: - “C” for criteria - “A” for alternatives - Any other str which will be changed in the list of labels with lower index. - None if not used - A callable with a signature foo(n: int) -> list[str] - A list of strings, where each string represents a valid label.

If the input does not meet these criteria, a ValueError is raised.

Parameters:

opt (str | list[str] | Callable | None) –

The option to validate. This can be:

A string: “C” (criteria) or “A” (alternatives) or other string.
A callable object with signature foo(n: int) -> list[str].
A list of strings, where all elements are valid labels.
None

Returns:

The validated option, returned unchanged if it is valid.

Return type:

str | list[str] | Callable | None

Raises:

ValueError – If opt is not one of the required types.