pysensmcda 2.0.0

PySensMCDA

PySensMCDA is a comprehensive Python package tailored specifically for Multi-Criteria Decision Analysis (MCDA) sensitivity analysis. MCDA is a powerful tool used in decision-making processes to evaluate alternatives based on multiple conflicting criteria. PySensMCDA empowers users to delve deeper into the robustness and reliability of their decision models by exploring the sensitivity of results to variations in input parameters.

In essence, this package offers tools for:

• Decision matrix sensitivity analysis
• Weights sensitivity analysis
• Ranking sensitivity analysis
• Perturbation generation
• Weights generation
• Weight space exploration under partial or absent preference information
• Stochastic and exhaustive acceptability analysis
• Robustness and stability metrics
• Visualizations of sensitivity analysis

Installation

The package can be downloaded using pip:

pip install pysensmcda

Development

This project uses uv for dependency and environment management.

# install uv: https://docs.astral.sh/uv/getting-started/installation/
uv sync

Testing

The modules performance can be verified with pytest library

pip install pytest
pytest tests

Regression against published results is marked as slow and can be skipped:

pytest -m "not slow"

Citation

If you use PySensMCDA in you work, please cite the following publication:

Paradowski, B., Więckowski, J., & Sałabun, W. (2024). PySensMCDA: A novel tool for sensitivity analysis in multi-criteria problems. SoftwareX, 27, 101746.

As BibTeX:

@article{paradowski2024pysensmcda,
  title={PySensMCDA: A novel tool for sensitivity analysis in multi-criteria problems},
  author={Paradowski, Bartosz and Wi{\k{e}}ckowski, Jakub and Sa{\l}abun, Wojciech},
  journal={SoftwareX},
  volume={27},
  pages={101746},
  year={2024},
  publisher={Elsevier}
}

What's new in 2.0

Version 1 answered the question "what happens to the ranking if this input changes?" by perturbing a decision problem and observing the result. Version 2 adds the complementary direction: "what would the inputs have to be for this alternative to win?" - and the machinery to summarise many rankings at once, whatever produced them.

Four new submodules

• sampling - everything that generates weight vectors or uncertain decision matrices, kept separate from the analyses that consume them. Uniform and Dirichlet sampling of the weight simplex, ordinal preference information, arbitrary linear constraints via Hit-And-Run, exhaustive simplex grids, and criteria uncertainty with absolute or relative tolerances.
• smaa - the Stochastic Multicriteria Acceptability Analysis family: rank acceptability indices, central weight vectors, confidence factors, holistic and k-best-ranks measures, ordinal criteria, and an exact linear-programming route for additive models.
• eors - the Exhaustive Objective Ranking Solution: a deterministic, reproducible exploration of the weight space with kernel density smoothing, degrees of confidence, and local sensitivity diagnostics.
• robustness - metrics summarising a collection of rankings: stability coefficients, decision entropy, pairwise winning indices.

A common contract

Every function in robustness takes the same input - an (n_rankings, m) array of rankings — and nothing else. The same metric therefore applies to a SMAA simulation, an EORS weight grid, several MCDA methods compared side by side, or the perturbation functions of version 1:

from pysensmcda.robustness import rs_coefficient

rs_coefficient(simulation.rankings)   # from pysensmcda.smaa.simulate
rs_coefficient(results.rankings)      # from pysensmcda.eors.eors

Any MCDA method, including your own

pysensmcda.methods defines the calling convention shared by every function that takes a method argument:

method(matrix, weights, types) -> preferences

Any pymcdm method instance satisfies it directly, and so does any plain function or callable object — no inheritance, registration or wrapper required. The ranking direction is read from the method where it advertises one, so methods ranking by lowest preference value, such as VIKOR or SPOTIS, need no special handling. It can always be set explicitly through the reverse_ranking argument.

from pymcdm.methods import TOPSIS, VIKOR
from pysensmcda.smaa import simulate

simulate(TOPSIS(), matrix, types, num_samples=10000, seed=0)
simulate(VIKOR(), matrix, types, num_samples=10000, seed=0)     # direction detected automatically
simulate(lambda m, w, t: m @ w, matrix, types, num_samples=10000, seed=0)

Breaking changes

• compromise.iterative_compromise now takes methods as a mapping from a name to a ready-to-call method, dict[str, MCDAMethod], replacing the nested dictionary of initialisation and call parameters used in version 1. Methods needing one-time setup, such as COMET, are wrapped in a plain function following the same convention — see the docstring for an example.
• Results of the new submodules are returned as dataclasses rather than tuples. Existing version 1 functions are unchanged.

Modules and functionalities

• Alternative:

Name	Reference
Discrete modification	-
Percentage modification	[14]
Range modification	-
Alternative removal	[8]

• Criteria:

Name	Reference
Random distribution - weights generation	-
Chisquare distribution	-
Laplace distribution	-
Normal distribution	-
Random distribution	-
Triangular distribution	-
Uniform distribution	-
Percentage modification	[15]
Range modification	-
Weights scenarios	-
Criteria identification	[6]
Criteria removal	[13]

• Probabilistic:

Name	Reference
Monte carlo weights generation	[10]
Perturbed matrix	[12]
Perturbed weights	[11]

• Ranking:

Name	Reference
Ranking alteration	[7]
Demotion	-
Promotion	[9]
Fuzzy ranking	-

• Compromise:

Name	Reference
Borda	[3]
Improved Borda	[4]
Dominance directed graph	[2]
Half-quadratic compromise	[5]
ICRA - Iterative Compromise Ranking Analysis	[1]
Rank position method	[3]

• Sampling:

Name	Reference
Uniform simplex sampling	[20] [31]
Dirichlet weights	-
Ordered simplex - ordinal preference	[17] [30] [31]
Spherical simplex - alternative weight space	[17] [31]
Weight constraints - preference information	[17]
Hit-And-Run - constrained weight generation	[21] [22] [23]
Simplex grid - exhaustive weight enumeration	[25]
Uniform matrix - uncertain criteria values	[16]
Ordinal values simulation	[18]
Euclidean projection onto the simplex	[24]

• SMAA:

Name	Reference
Simulation over the weight space	[20]
Rank acceptability indices	[17]
Central weight vectors	[16]
Favourable weight bounds	[16]
Confidence factors	[16]
Cross confidence factors	[19]
Holistic acceptability & metaweights	[17]
k best ranks acceptability	[17]
Central k best ranks weight vectors	[17]
SMAA-2	[17]
SMAA-O - ordinal criteria	[18]
Exact acceptability - linear programming	[16]
Exact efficiency test	[16]
Exact favourable weight bounds	[16]

• EORS:

Name	Reference
Exhaustive objective ranking	[26] [27]
KDE preference modes	[27]
Degrees of confidence	[26] [27]
Local weight-space sensitivity	[28]
Criterion sensitivity index	[28]
Fragility index	[28]

• Robustness:

Name	Reference
Ranking stability (RS)	[29]
Balance point (BP)	[29]
Pairwise winning indices	-
Decision entropy - choice	-
Decision entropy - ranking	-

• Graphs:

Name
Heatmap
Promotion-demotion ranking graph
Preference distribution
Rankings distribution
Values distribution
Weights barplot
Rank acceptability barplot
Central weights plot
Preference density
Sensitivity heatmap
Coefficient barplot
Ranking ranges

Usage example

• General usage examples see examples.ipynb
• Graphs submodule usage examples see graphs_examples.ipynb
• Literature example analysis see literature_example.ipynb
• Weight space exploration, acceptability analysis and robustness metrics see robustness_examples.ipynb

Related work

Don't forget to check out these other amazing software packages!

• Make-Decision.it: Web application offering users a graphical interface for prototyping structural decision models
• PyFDM: package with Fuzzy Decision Making (PyFDM) methods based on Triangular Fuzzy Numbers (TFN).
• PyIFDM: package to perform Multi-Criteria Decision Analysis in the Intuitionistic Fuzzy environment.
• PyMCDM: Python 3 library for solving multi-criteria decision-making (MCDM) problems.

References

[1] Paradowski, B., Kizielewicz, B., Shekhovtsov, A., & Sałabun, W. (2022, September). The Iterative Compromise Ranking Analysis (ICRA)-The New Approach to Make Reliable Decisions. In Special Sessions in the Advances in Information Systems and Technologies Track of the Conference on Computer Science and Intelligence Systems (pp. 151-170). Cham: Springer Nature Switzerland.

[2] Xiao, J., Xu, Z., & Wang, X. (2023). An improved MULTIMOORA with CRITIC weights based on new equivalent transformation functions of nested probabilistic linguistic term sets. Soft Computing, 1-18.

[3] Altuntas, S., Dereli, T., & Yilmaz, M. K. (2015). Evaluation of excavator technologies: application of data fusion based MULTIMOORA methods. Journal of Civil Engineering and Management, 21(8), 977-997.

[4] Wu, X., Liao, H., Xu, Z., Hafezalkotob, A., & Herrera, F. (2018). Probabilistic linguistic MULTIMOORA: A multicriteria decision making method based on the probabilistic linguistic expectation function and the improved Borda rule. IEEE transactions on Fuzzy Systems, 26(6), 3688-3702.

[5] Mohammadi, M., & Rezaei, J. (2020). Ensemble ranking: Aggregation of rankings produced by different multi-criteria decision-making methods. Omega, 96, 102254.

[6] Kizielewicz, B., Wątróbski, J., & Sałabun, W. (2020). Identification of relevant criteria set in the MCDA process—Wind farm location case study. Energies, 13(24), 6548.

[7] Maliene, V., Dixon-Gough, R., & Malys, N. (2018). Dispersion of relative importance values contributes to the ranking uncertainty: Sensitivity analysis of Multiple Criteria Decision-Making methods. Applied Soft Computing, 67, 286-298.

[8] Nabavi, S. R., Wang, Z., & Rangaiah, G. P. (2023). Sensitivity Analysis of Multi-Criteria Decision-Making Methods for Engineering Applications. Industrial & Engineering Chemistry Research, 62(17), 6707-6722.

[9] Wolters, W. T. M., & Mareschal, B. (1995). Novel types of sensitivity analysis for additive MCDM methods. European Journal of Operational Research, 81(2), 281-290.

[10] Baležentis, T., & Streimikiene, D. (2017). Multi-criteria ranking of energy generation scenarios with Monte Carlo simulation. Applied energy, 185, 862-871.

[11] Zhang, C., Wang, Q., Zeng, S., Baležentis, T., Štreimikienė, D., Ališauskaitė-Šeškienė, I., & Chen, X. (2019). Probabilistic multi-criteria assessment of renewable micro-generation technologies in households. Journal of Cleaner Production, 212, 582-592.

[12] Barker, K., & Haimes, Y. Y. (2009). Assessing uncertainty in extreme events: Applications to risk-based decision making in interdependent infrastructure sectors. Reliability Engineering & System Safety, 94(4), 819-829.

[13] Więckowski, J., Kizielewicz, B., Shekhovtsov, A., & Sałabun, W. (2023). How do the criteria affect sustainable supplier evaluation?-A case study using multi-criteria decision analysis methods in a fuzzy environment. Journal of Engineering Management and Systems Engineering, 2(1), 37-52.

[14] Kolbowicz, M., Nowak, M., & Więckowski, J. (2024). A multi-criteria system for performance assessment and support decision-making based on the example of Premier League top football strikers.

[15] Triantaphyllou, E., & Sánchez, A. (1997). A sensitivity analysis approach for some deterministic multi‐criteria decision‐making methods. Decision sciences, 28(1), 151-194.

[16] Lahdelma, R., Hokkanen, J., & Salminen, P. (1998). SMAA-stochastic multiobjective acceptability analysis. European journal of operational research, 106(1), 137-143.

[17] Lahdelma, R., & Salminen, P. (2001). SMAA-2: Stochastic multicriteria acceptability analysis for group decision making. Operations research, 49(3), 444-454.

[18] Lahdelma, R., Miettinen, K., & Salminen, P. (2003). Ordinal criteria in stochastic multicriteria acceptability analysis (SMAA). European Journal of Operational Research, 147(1), 117-127.

[19] Lahdelma, R., & Salminen, P. (2006). Classifying efficient alternatives in SMAA using cross confidence factors. European Journal of Operational Research, 170(1), 228-240.

[20] Tervonen, T., & Lahdelma, R. (2007). Implementing stochastic multicriteria acceptability analysis. European journal of operational research, 178(2), 500-513.

[21] Smith, R. L. (1984). Efficient Monte Carlo procedures for generating points uniformly distributed over bounded regions. Operations Research, 32(6), 1296-1308.

[22] Tervonen, T., van Valkenhoef, G., Baştürk, N., & Postmus, D. (2013). Hit-and-run enables efficient weight generation for simulation-based multiple criteria decision analysis. European Journal of Operational Research, 224(3), 552-559.

[23] van Valkenhoef, G., Tervonen, T., & Postmus, D. (2014). Notes on ‘Hit-And-Run enables efficient weight generation for simulation-based multiple criteria decision analysis’. European Journal of Operational Research, 239(3), 865-867.

[24] Duchi, J., Shalev-Shwartz, S., Singer, Y., & Chandra, T. (2008, July). Efficient projections onto the l 1-ball for learning in high dimensions. In Proceedings of the 25th international conference on Machine learning (pp. 272-279).

[25] Scheffé, H. (1958). Experiments with mixtures. Journal of the Royal Statistical Society: Series B (Methodological), 20(2), 344-360.

[26] Paradowski, B., & Salabun, W. (2024, December). Enhancing objective decision-making with exhaustive objective ranking solution (EORS). In 2024 IEEE 63rd Conference on Decision and Control (CDC) (pp. 8908-8913). IEEE.

[27] Paradowski, B. (2025). Towards robust objective decision-making: sensitivity analysis and comparative evaluation of the EORS approach. Procedia Computer Science, 270, 6223-6232.

[28] Paradowski, B. (2026, June). From Exhaustive Robustness to Local Sensitivity: An Extension of the EORS Framework. In International Conference on Computational Science (pp. 434-447). Cham: Springer Nature Switzerland.

[29] Paradowski, B., Wątróbski, J., & Sałabun, W. (2025). Novel coefficients for improved robustness in multi-criteria decision analysis. Artificial Intelligence Review, 58(10), 298.

[30] Barron, F. H., & Barrett, B. E. (1996). Decision quality using ranked attribute weights. Management science, 42(11), 1515-1523.

[31] Rubinstein, R. Y. (1982). Generating random vectors uniformly distributed inside and on the surface of different regions. European Journal of Operational Research, 10(2), 205-209.