Metadata-Version: 2.5
Name: pysensmcda
Version: 2.0.0
Summary: Python Sensitivity Analysis Multi-Criteria Decision Analysis Package
Project-URL: Homepage, https://github.com/jwieckowski/pysensmcda
Project-URL: Bug Reports, https://github.com/jwieckowski/pysensmcda/issues
Project-URL: Source, https://github.com/jwieckowski/pysensmcda
Author-email: Jakub Więckowski <j.wieckowski@il-pib.pl>, Bartosz Paradowski <b.paradowski@il-pib.pl>
Maintainer-email: Jakub Więckowski <j.wieckowski@il-pib.pl>, Bartosz Paradowski <b.paradowski@il-pib.pl>
License-Expression: MIT
License-File: LICENSE
Keywords: decision-making,mcda,python,robustness,sensitivity analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: joblib<2,>=1.3
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: npy-append-array<1,>=0.9
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas<3,>=2.2
Requires-Dist: pymcdm<=1.4,>=1.2
Requires-Dist: scipy<2,>=1.11
Requires-Dist: seaborn<1,>=0.13
Requires-Dist: tqdm<5,>=4.65
Provides-Extra: docs
Requires-Dist: ipython; extra == 'docs'
Requires-Dist: ipywidgets; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: nbsphinx; extra == 'docs'
Requires-Dist: nbsphinx-link; extra == 'docs'
Requires-Dist: sphinx-autoapi; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sympy; extra == 'docs'
Description-Content-Type: text/markdown

[![github](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)](https://github.com/jwieckowski/pysensmcda)
[![Read the Docs](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=fff)](https://pysensmcda.readthedocs.io/en/latest/)
[![Version](https://img.shields.io/pypi/v/pysensmcda)](https://pypi.org/project/pysensmcda/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- [![DOI:10.1016/j.softx.2022.101271](http://img.shields.io/badge/DOI-10.1016/j.softx.2022.101271-0f81c2.svg)](https://doi.org/10.1016/j.softx.2022.101271) -->

<!-- [![License](https://img.shields.io/github/license/nlesc/pyfdm)]() -->

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

```Bash
pip install pysensmcda
```

## Development

This project uses [`uv`](https://docs.astral.sh/uv/) for dependency and environment management.

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

## Testing

The modules performance can be verified with `pytest` library

```Bash
pip install pytest
pytest tests
```

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

```Bash
pytest -m "not slow"
```

## Citation

If you use `PySensMCDA` in you work, please cite the following [publication](https://www.sciencedirect.com/science/article/pii/S2352711024001171):

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

```Python
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:

```Python
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.

```Python
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

<br/>

- ### Alternative:

| Name                    |   Reference    |
| ----------------------- | :------------: |
| Discrete modification   |       -        |
| Percentage modification | [[14]](#ref14) |
| Range modification      |       -        |
| Alternative removal     |  [[8]](#ref8)  |

<br/>

- ### Criteria:

| Name                                             |   Reference    |
| ------------------------------------------------ | :------------: |
| Random distribution - weights generation         |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Chisquare distribution  |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Laplace distribution    |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Normal distribution     |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Random distribution     |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Triangular distribution |       -        |
| &nbsp;&nbsp;&nbsp;&nbsp; Uniform distribution    |       -        |
| Percentage modification                          | [[15]](#ref15) |
| Range modification                               |       -        |
| Weights scenarios                                |       -        |
| Criteria identification                          |  [[6]](#ref6)  |
| Criteria removal                                 | [[13]](#ref13) |

<br/>

- ### Probabilistic:

| Name                           |   Reference    |
| ------------------------------ | :------------: |
| Monte carlo weights generation | [[10]](#ref10) |
| Perturbed matrix               | [[12]](#ref12) |
| Perturbed weights              | [[11]](#ref11) |

<br/>

- ### Ranking:

| Name               |  Reference   |
| ------------------ | :----------: |
| Ranking alteration | [[7]](#ref7) |
| Demotion           |      -       |
| Promotion          | [[9]](#ref9) |
| Fuzzy ranking      |      -       |

<br/>

- ### Compromise:

| Name                                         |  Reference   |
| -------------------------------------------- | :----------: |
| Borda                                        | [[3]](#ref3) |
| Improved Borda                               | [[4]](#ref4) |
| Dominance directed graph                     | [[2]](#ref2) |
| Half-quadratic compromise                    | [[5]](#ref5) |
| ICRA - Iterative Compromise Ranking Analysis | [[1]](#ref1) |
| Rank position method                         | [[3]](#ref3) |

<br/>

- ### Sampling:

| Name                                         |                  Reference                   |
| -------------------------------------------- | :------------------------------------------: |
| Uniform simplex sampling                     |        [[20]](#ref20) [[31]](#ref31)         |
| Dirichlet weights                            |                      -                       |
| Ordered simplex - ordinal preference         | [[17]](#ref17) [[30]](#ref30) [[31]](#ref31) |
| Spherical simplex - alternative weight space |        [[17]](#ref17) [[31]](#ref31)         |
| Weight constraints - preference information  |                [[17]](#ref17)                |
| Hit-And-Run - constrained weight generation  | [[21]](#ref21) [[22]](#ref22) [[23]](#ref23) |
| Simplex grid - exhaustive weight enumeration |                [[25]](#ref25)                |
| Uniform matrix - uncertain criteria values   |                [[16]](#ref16)                |
| Ordinal values simulation                    |                [[18]](#ref18)                |
| Euclidean projection onto the simplex        |                [[24]](#ref24)                |

<br/>

- ### SMAA:

| Name                                     |   Reference    |
| ---------------------------------------- | :------------: |
| Simulation over the weight space         | [[20]](#ref20) |
| Rank acceptability indices               | [[17]](#ref17) |
| Central weight vectors                   | [[16]](#ref16) |
| Favourable weight bounds                 | [[16]](#ref16) |
| Confidence factors                       | [[16]](#ref16) |
| Cross confidence factors                 | [[19]](#ref19) |
| Holistic acceptability & metaweights     | [[17]](#ref17) |
| _k_ best ranks acceptability             | [[17]](#ref17) |
| Central _k_ best ranks weight vectors    | [[17]](#ref17) |
| SMAA-2                                   | [[17]](#ref17) |
| SMAA-O - ordinal criteria                | [[18]](#ref18) |
| Exact acceptability - linear programming | [[16]](#ref16) |
| Exact efficiency test                    | [[16]](#ref16) |
| Exact favourable weight bounds           | [[16]](#ref16) |

<br/>

- ### EORS:

| Name                           |           Reference           |
| ------------------------------ | :---------------------------: |
| Exhaustive objective ranking   | [[26]](#ref26) [[27]](#ref27) |
| KDE preference modes           |        [[27]](#ref27)         |
| Degrees of confidence          | [[26]](#ref26) [[27]](#ref27) |
| Local weight-space sensitivity |        [[28]](#ref28)         |
| Criterion sensitivity index    |        [[28]](#ref28)         |
| Fragility index                |        [[28]](#ref28)         |

<br/>

- ### Robustness:

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

<br/>

- ### 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`](./examples/examples.ipynb)
- Graphs submodule usage examples see [`graphs_examples.ipynb`](./examples/graphs_examples.ipynb)
- Literature example analysis see [`literature_example.ipynb`](./examples/literature_example.ipynb)
- Weight space exploration, acceptability analysis and robustness metrics see [`robustness_examples.ipynb`](./examples/robustness_examples.ipynb)

## Related work

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

- [Make-Decision.it](http://make-decision.it/): Web application offering users a graphical interface for prototyping structural decision models
- [PyFDM](https://pypi.org/project/pyfdm/): package with Fuzzy Decision Making (PyFDM) methods based on Triangular Fuzzy Numbers (TFN).
- [PyIFDM](https://pypi.org/project/pyifdm/): package to perform Multi-Criteria Decision Analysis in the Intuitionistic Fuzzy environment.
- [PyMCDM](https://pypi.org/project/pymcdm/): Python 3 library for solving multi-criteria decision-making (MCDM) problems.

### References

<a name="ref1">**[1]**</a> 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.

<a name="ref2">**[2]**</a> 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.

<a name="ref3">**[3]**</a> 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.

<a name="ref4">**[4]**</a> 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.

<a name="ref5">**[5]**</a> Mohammadi, M., & Rezaei, J. (2020). Ensemble ranking: Aggregation of rankings produced by different multi-criteria decision-making methods. Omega, 96, 102254.

<a name="ref6">**[6]**</a> 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.

<a name="ref7">**[7]**</a> 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.

<a name="ref8">**[8]**</a> 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.

<a name="ref9">**[9]**</a> 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.

<a name="ref10">**[10]**</a> Baležentis, T., & Streimikiene, D. (2017). Multi-criteria ranking of energy generation scenarios with Monte Carlo simulation. Applied energy, 185, 862-871.

<a name="ref11">**[11]**</a> 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.

<a name="ref12">**[12]**</a> 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.

<a name="ref13">**[13]**</a> 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.

<a name="ref14">**[14]**</a> 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.

<a name="ref15">**[15]**</a> Triantaphyllou, E., & Sánchez, A. (1997). A sensitivity analysis approach for some deterministic multi‐criteria decision‐making methods. Decision sciences, 28(1), 151-194.

<a name="ref16">**[16]**</a> Lahdelma, R., Hokkanen, J., & Salminen, P. (1998). SMAA-stochastic multiobjective acceptability analysis. European journal of operational research, 106(1), 137-143.

<a name="ref17">**[17]**</a> Lahdelma, R., & Salminen, P. (2001). SMAA-2: Stochastic multicriteria acceptability analysis for group decision making. Operations research, 49(3), 444-454.

<a name="ref18">**[18]**</a> Lahdelma, R., Miettinen, K., & Salminen, P. (2003). Ordinal criteria in stochastic multicriteria acceptability analysis (SMAA). European Journal of Operational Research, 147(1), 117-127.

<a name="ref19">**[19]**</a> Lahdelma, R., & Salminen, P. (2006). Classifying efficient alternatives in SMAA using cross confidence factors. European Journal of Operational Research, 170(1), 228-240.

<a name="ref20">**[20]**</a> Tervonen, T., & Lahdelma, R. (2007). Implementing stochastic multicriteria acceptability analysis. European journal of operational research, 178(2), 500-513.

<a name="ref21">**[21]**</a> Smith, R. L. (1984). Efficient Monte Carlo procedures for generating points uniformly distributed over bounded regions. Operations Research, 32(6), 1296-1308.

<a name="ref22">**[22]**</a> 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.

<a name="ref23">**[23]**</a> 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.

<a name="ref24">**[24]**</a> 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).

<a name="ref25">**[25]**</a> Scheffé, H. (1958). Experiments with mixtures. Journal of the Royal Statistical Society: Series B (Methodological), 20(2), 344-360.

<a name="ref26">**[26]**</a> 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.

<a name="ref27">**[27]**</a> Paradowski, B. (2025). Towards robust objective decision-making: sensitivity analysis and comparative evaluation of the EORS approach. Procedia Computer Science, 270, 6223-6232.

<a name="ref28">**[28]**</a> 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.

<a name="ref29">**[29]**</a> 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.

<a name="ref30">[30]</a> Barron, F. H., & Barrett, B. E. (1996). Decision quality using ranked attribute weights. Management science, 42(11), 1515-1523.

<a name="ref31">[31]</a> 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.
