VISTA — VISualization of relation Topologies of Alternatives

Overview

VISTA is a visualization framework for Multi-Criteria Decision Analysis (MCDA) ranking methods. For a given ranking method it sweeps a test alternative across a 2-D criteria space and classifies every point by its pairwise relation to a fixed reference alternative:

The resulting colour-coded map reveals decision boundaries and structural differences between MCDA ranking methods at a glance.

Installation

Install directly from PyPI:

pip install mcda-vista

To include the interactive Streamlit dashboard:

pip install mcda-vista[app]

For development (linting, type-checking, tests):

git clone https://github.com/dabrze/mcda-vista.git
cd mcda-vista
pip install -e ".[dev]"

Quick Start

from mcda_vista import generate_vista, plot_vista

result = generate_vista("topsis", resolution=101, delta=0.10, progress=True)
fig = plot_vista(result, point_size=7)
fig.savefig("topsis_vista.png", dpi=300)

generate_vista sweeps a 101 × 101 grid of alternatives over the criterion space, evaluates the ranking method (in this case TOPSIS) at every point, and returns a VistaResult dataclass. plot_vista renders it as a scatter plot coloured by the relation type - adjust the point_size parameter to the resolution and size of the image.

You will find practical examples of how to use vistas in the notebooks folders. A portion of that functionality is highlighted below.

Available Ranking Methods

The package works with pyDecision's built-in methods and any custom method that follows the expected interface. The following methods are registered by default:

List registered methods programmatically:

from mcda_vista.methods import list_methods
print(list_methods())

If a pyDecision method is not available by default, you can add it by creating an adapter with register_method() or use a custom callable (see below).

Custom Methods

You can pass any callable that accepts a dataset, weights, and keyword parameters and returns a Relation:

from mcda_vista import generate_vista, plot_vista, Relation
import numpy as np

def my_method(dataset, weights, **params):
    # dataset[0] = reference, dataset[1] = test point
    score_ref = np.dot(dataset[0], weights)
    score_test = np.dot(dataset[1], weights)
    delta = params.get("delta", 0.05)
    if abs(score_ref - score_test) < delta:
        return Relation.INDIFFERENT
    return Relation.BETTER if score_test > score_ref else Relation.WORSE

result = generate_vista(my_method, resolution=101, delta=0.05)
fig = plot_vista(result)
fig.savefig("custom_method.png", dpi=300)

Exploratory Diagnostic Protocol

The VISTA exploratory protocol is a systematic six-step checklist that assesses whether a ranking method meets the decision maker's expectations:

1. Dominance relation — no violations in dominating/dominated cones
2. Self-indifference — identical alternatives are indifferent
3. Diagonal preference change — at most one transition along the diagonal
4. Radial preference change — at most one transition along any ray
5. Preference ratio — shows whether the Better/Worse ratio is balanced or not
6. Third alternative stability (IIA check) — verifies whether the VISTA remains stable when a third alternative is added

from mcda_vista.protocol import run_protocol, plot_protocol_report

report = run_protocol("topsis", resolution=101, delta=0.10)
fig = plot_protocol_report(report, point_size=3)
fig.savefig("protocol_report.png", dpi=300)
print(report.summary())

VISTA Protocol Report: topsis
=============================
  ✓ PASS  Dominance relation: No violations (2500 dominating, 2500 dominated points).
  ✗? FAIL  Self-indifference: Reference point is Error — likely a numerical issue (nearest grid point at distance 0.0000).
  ✓ PASS  Diagonal preference change: Upper-right: 1 transition(s), lower-left: 1 transition(s).
  ✓ PASS  Radial preference change: All 36 rays have at most 1 transition.
  ● IMBALANCED  Preference ratio: Imbalanced (56.8% worse, 37.9% better than reference).
  ✗ FAIL  Third alternative stability: Max change 14.4% > 5%. Changes: [0.5, 0.5]: 4.5%, [0.25, 0.5]: 10.3%, [0.5, 0.75]: 4.5%, [0.25, 0.25]: 7.4%, [0.25, 0.75]: 14.4%.

The protocol uses equal weights and the midpoint as reference by default. Optionally pass extra_weights to test weight sensitivity (e.g., extra_weights=[[0.25, 0.75], [0.25, 0.50], [0.50, 0.50], [0.50, 0.25], [0.75, 0.25]]). See notebooks/12_protocol_check.ipynb for a full walkthrough with Fuzzy TOPSIS.

VISTA Grid

Use plot_vista_grid to compare multiple methods in a single faceted figure. The example below contrasts different PROMETHEE I function types side by side:

from mcda_vista import generate_vista
from mcda_vista.plotting import plot_vista_grid

weights = [[0.25, 0.50], [0.50, 0.50], [0.50, 0.25]]
promethee_types = ["t1", "t2", "t3", "t4"]

results = [
  [
    generate_vista("promethee_i", resolution=101, weights=w, f=ptype, q=0.05, p=0.20)
    for ptype in promethee_types
  ]
  for w in weights
]

fig = plot_vista_grid(
  results,
  row_labels=[f"w={w}" for w in weights],
  col_labels=["PROMETHEE I (t1)", "PROMETHEE I (t2)", "PROMETHEE I (t3)","PROMETHEE I (t4)"],
  title="Comparison of PROMETHEE I versions",
  point_size=1.5,
)
fig.savefig("vista_grid_promethee.png", dpi=300)

Experiments

Reproducible experiments are configured via YAML files stored in experiments/configs/. Each config specifies the method, parameter ranges, resolution, and output paths. To run an experiment:

python experiments/run_experiments.py experiments/configs/my_config.yaml --plot

Results (CSV grids + metadata JSON) are written to the configured output directory and can be reloaded with load_vista().

Dashboard

The optional Streamlit dashboard provides an interactive UI for exploring VISTA maps interactively. Launch it with:

streamlit run src\mcda_vista\app\dashboard.py

Select a method, adjust parameters with sliders, and watch the VISTA map update live. Install the dashboard extra to enable it:

pip install .[app]

License

This project is licensed under the MIT License.

Support and Citation

If you have questions or run into problems, please open an issue on GitHub.

If you use VISTA in your research, please cite:

@article{vista,
  author  = {Susmaga, Robert and Szcz\c{e}ch, Izabela and Brzezinski, Dariusz},
  title   = {Visualization of Preferential Relations in Analyses of Multicriteria Ranking Methods},
  note    = {In review},
  year    = {2026}
}