gcisens

gcisens is a Python library for analysing how individual criteria influence the results of MCDA models. It uses Sobol' sensitivity analysis to compare declared criteria weights with their actual impact, helping identify hidden nonlinear effects and interactions in ESP-COMET and ESP-SPOTIS models.

Documentation: Read the Docs

PyPI: gcisens

Features

Analysis

• Global sensitivity analysis — calculates first-order (S1), total-order (ST) and pairwise interaction (S2) Sobol' indices with confidence intervals.
• Global and local criterion importance — estimates the model's overall criterion weights and can examine importance around a selected reference point.
• Ranking comparison — compares rankings produced by criterion weights, S1 and ST, including Spearman rank correlations.

Diagnosis and validation

• Sensitivity Discrepancy Report — identifies hidden criterion influence, interaction dominance, moderate discrepancies and agreement between weights and observed sensitivity.
• External validation — evaluates model scores against known labels using group differences and lift at selected cut-offs.
• Configuration comparison — presents results from multiple model setups side by side.

Visualisation and reporting

• Visual analysis — includes index charts, S2 interaction heatmaps, ranking flows, decision surfaces with ESPs and score distributions.
• Reusable outputs — exports results to CSV, LaTeX and standalone HTML reports.

Analysis pipeline

The workflow combines gcisens code with established implementations from SALib, pymcdm and scikit-learn.

Supported models

The COMET, SPOTIS and ESPExpert implementations are provided by pymcdm and re-exported by gcisens for a consistent interface.

Installation

You can install gcisens from PyPI using pip:

pip install gcisens

Quick start

The example below builds an ESP-COMET model with three criteria and one expected solution point, runs a Sobol' sensitivity analysis and shows how to inspect and export the results:

import numpy as np
from gcisens import esp_comet, SobolStudy

bounds = np.array([[18, 60], [1, 29], [1009, 19999]], float)
esps = np.array([[25, 25, 2000]])          # expected solution point(s)

model = esp_comet(esps=esps, bounds=bounds,
                  criteria_names=["Age", "Distance", "Income"])

result = SobolStudy(model, n_samples=2048, seed=42).run()

result.table()        # weights, S1, ST, ranks, category per criterion
result.diagnosis()    # Sensitivity Discrepancy Report
result.summary()      # R², ΣS1, ΣST, Spearman correlations
result.plot_indices() # w vs S1 vs ST bar chart
result.to_latex()     # publication-ready table

Alternatively, the model can be constructed directly with the re-exported pymcdm classes and passed to SobolStudy:

from gcisens import COMET, ESPExpert, SobolStudy

expert = ESPExpert(esps=esps, bounds=bounds)
model = COMET(expert.make_cvalues_psi(), expert)
result = SobolStudy(model, bounds=bounds).run()

Examples

The repository includes ready-to-run examples based on the bundled IBM HR Attrition dataset:

• article_esp_comet.py - analyses multiple ESP-COMET configurations and generates CSV, LaTeX and HTML reports.
• esp_spotis_demo.py - compares ESP-SPOTIS with ESP-COMET using the same expected solution point.

References

• Sobol', I. M. (2001). Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation, 55(1-3), 271-280.
• Saltelli, A., Annoni, P., Azzini, I., Campolongo, F., Ratto, M., & Tarantola, S. (2010). Variance based sensitivity analysis of model output: Design and estimator for the total sensitivity index. Computer Physics Communications, 181(2), 259-270.
• Herman, J., & Usher, W. (2017). SALib: An open-source Python library for sensitivity analysis. Journal of Open Source Software, 2(9), 97.
• Kizielewicz, B., Shekhovtsov, A., & Sałabun, W. (2023). pymcdm - The universal library for solving multi-criteria decision-making problems. SoftwareX, 22, 101368.
• Sałabun, W. (2015). The Characteristic Objects Method: A new distance-based approach to multicriteria decision-making problems. Journal of Multi-Criteria Decision Analysis, 22(1-2), 37-50.
• Shekhovtsov, A., Kizielewicz, B., & Sałabun, W. (2023). Advancing individual decision-making: An extension of the Characteristic Objects Method using Expected Solution Point. Information Sciences, 647, 119456.
• Dezert, J., Tchamova, A., Han, D., & Tacnet, J.-M. (2020). The SPOTIS rank reversal free method for multi-criteria decision-making support. 2020 IEEE 23rd International Conference on Information Fusion (FUSION), 1-8.
• IBM HR Analytics Employee Attrition & Performance - IBM Watson Analytics sample dataset used in the examples.

License

gcisens is available under the MIT License. You may use, modify and distribute it under its terms. See the LICENSE file for details.