Metadata-Version: 2.4
Name: mcda-core
Version: 0.3.0
Summary: Foundation data structures and interfaces for the MCDA Python ecosystem
Author-email: Gilles Dejaegere <gilles.dejaegere@ulb.be>
License-Expression: MIT
Project-URL: Repository, https://gitlab.ulb.be/smg/mcda-core
Keywords: mcda,mcdm,multi-criteria,decision,promethee,electre
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.25
Requires-Dist: pandas>=2.0
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

# mcda-core

Foundation library for the MCDA Python ecosystem. Provides the shared data structures, abstract interfaces, and data transformations that all other libraries in the ecosystem build on.

## Installation

```bash
pip install mcda-core
```

Python ≥ 3.9, NumPy ≥ 1.25, pandas ≥ 2.0.

## Quick start

```python
import numpy as np
import pandas as pd
from mcda_core import PerformanceTable, minmax, zscore

# Build a performance table from raw values
table = PerformanceTable(
    values=np.array([
        [80.0, 20.0, 10.0],
        [65.0, 35.0, 18.0],
        [90.0, 15.0, 14.0],
    ]),
    alternatives=["A", "B", "C"],
    criteria=["cost", "quality", "CO2"],
    directions=[-1, 1, -1],  # minimise cost and CO2, maximise quality
)

# Or load from a CSV
df = pd.read_csv("data.csv", index_col="alternative")
table = PerformanceTable.from_dataframe(df, directions=[-1, 1, -1])

# Normalise — returns a new (immutable) PerformanceTable
norm = minmax(table)

# Convert minimisation criteria to maximisation before passing to a method
table_max = table.as_maximization()
```

## What's included

### `PerformanceTable`

The central data structure — a frozen dataclass wrapping a `(n, c)` float array of `n` alternatives × `c` criteria, together with:

| attribute | type | default |
|-----------|------|---------|
| `values` | `NDArray` shape `(n, c)` | required |
| `alternatives` | `list[str]` | `None` |
| `criteria` | `list[str]` | `None` |
| `criteria_types` | `list[str]` | all `"cardinal"` |
| `directions` | `list[int]` | all `+1` (maximise) |

Key methods: `from_dataframe()`, `as_maximization()`, `to_dataframe()`, `.shape`.

### Interfaces

| class | purpose |
|-------|---------|
| `MCDAMethod[P]` | Abstract base for all MCDA methods — requires `fit()` and `result()` |
| `MCDAParameters` | Abstract base for method parameters |

`KEY_WEIGHTS` is the shared string constant for the weights key.

### Transformations

All transformations take a `PerformanceTable` and return a new one (metadata preserved):

| function | description |
|----------|-------------|
| `minmax(table)` | `(x − min) / (max − min)` → [0, 1] |
| `zscore(table)` | `(x − μ) / σ` |
| `sum_normalization(table)` | `x / Σx` |
| `max_scaling(table)` | `x / max(\|x\|)` |
| `invert_criteria(table)` | Flip criteria with `direction = −1`; method: `"range"` (default) or `"sign"` |
| `scores_to_ranking(scores)` | Indices of alternatives sorted best → worst; `higher_is_better=True` (default) |

All table transformations accept an optional `criteria` argument (list of column indices) to apply the transformation to a subset of criteria.

## Ecosystem

This library is the foundation of a modular MCDA ecosystem:

| library | role | repository |
|---------|------|------------|
| mcda-core | ← you are here | [gitlab.ulb.be/smg/mcda-core](https://gitlab.ulb.be/smg/mcda-core) |
| promethee | PROMETHEE I/II/Gamma/Sort | [gitlab.ulb.be/smg/promethee](https://gitlab.ulb.be/smg/promethee) |
| mcda-methods | ELECTRE I, MAUT | [gitlab.ulb.be/smg/mcda-methods](https://gitlab.ulb.be/smg/mcda-methods) |
| mcda-viz | Visualization dashboards (Dash/Plotly) | [gitlab.ulb.be/smg/mcda-viz](https://gitlab.ulb.be/smg/mcda-viz) |

New method libraries only need to depend on `mcda-core` and inherit from `MCDAMethod` to be fully compatible with the rest of the ecosystem.

## License

MIT — see [LICENSE](LICENSE).
