desdeo 1.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

desdeo/explanations/utils.py

@@ -0,0 +1,90 @@
+"""Utilities specific to explainable multiobjective optimization."""
+
+import cvxpy as cp
+import numpy as np
+
+
+def generate_biased_mean_data(
+    data: np.ndarray, target_means: np.ndarray, min_size: int = 2, max_size: int | None = None, solver: str = "SCIP"
+) -> list | None:
+    r"""Finds a subset of the provided data that has a mean value close to provided target values.
+
+    Finds a subset of the provided data that has a mean value close to the
+    provided target values.  Formulates a mixed-integer quadratic programming problem to
+    find a subset of `data` with a mean as close as possible to `target_values`
+    and a size between `min_size` and `max_size`. In other words, the following problems is solved:
+
+    \begin{align}
+        &\min_{\mathbf{x}} & f(\mathbf{x}) & = \sum_{i=1}^m \left[ \left(\frac{1}{k}
+            \sum_{j=1}^n x_j \times \text{data}_j\right)_i - \text{target}_i \right]^2 \\
+        &\text{s.t.,}   & k & = \sum_{i=1}^n x_i,\\
+        &               & k & \leq \text{max_size},\\
+        &               & k & \geq \text{min_size},\\
+    \end{align},
+    where $n$ is the number of rows in `data`, $m$ is the number of columns in
+    `data`, and $k$ is the size of the subset. Notice that the closeness to the
+    target means is based on the Euclidean distance.
+
+    Note:
+        Be mindful that this functions can take a long time with a very large
+            data set and large upper bound for the desired subset.
+
+    Args:
+        data (np.ndarray): the data from which to generate the subset with a
+            biased mean. Should be a 2D array with each row representing a sample
+            and each column the value of the variables in the sample.
+        target_means (np.ndarray): the target mean values for each column the
+            generated subset should have values close to.
+        min_size (int, optional): the minimum size of the generated subset. Defaults to 2.
+        max_size (int | None, optional): the maximum size of the generated
+            subset. If None, then the maximum size is bound by the numbers of rows
+            in `data`. Defaults to None.
+        solver (str, optional): the selected solver to be used by cvxpy. The
+            solver should support mixed-integer quadratic programming. Defaults to
+            "SCIP".
+
+    Returns:
+        list | None: the indices of the samples of the generated subset respect to
+            `data`, i.e., the generated subset is `data[indices]`. If optimization is not successful,
+            returns None instead.
+    """
+    # Number of rows and columns
+    n_rows, n_cols = data.shape
+    max_size = n_rows if max_size is None else max_size
+
+    # Big M used to penalize the auxiliary variable z
+    big_m = data.max(axis=0)
+
+    # Binary variables to select rows from the data
+    x = cp.Variable(n_rows, boolean=True)
+
+    # Auxiliary variables, z represents the mean. phi is the weighted sum of the data (weighted by x)
+    z = cp.Variable(n_cols)
+    phi = cp.Variable((n_rows, n_cols))
+
+    # The objective function, squared values of the difference between the mean
+    # of the currently selected subset and the target values.
+    objective = cp.sum_squares(z - target_means)
+
+    # Define the constraints
+    constraints = [
+        # Sets the value of phi
+        *[cp.sum(phi[:, col]) == cp.sum(cp.multiply(x, data[:, col])) for col in range(n_cols)],
+        # Constraints the values of phi using big M, in practice setting z to be the mean values
+        *[phi[:, col] <= cp.multiply(big_m[col], x) for col in range(n_cols)],
+        *[phi[:, col] <= z[col] for col in range(n_cols)],
+        *[phi[:, col] >= z[col] - cp.multiply(big_m[col], 1 - x) for col in range(n_cols)],
+        phi >= 0,
+        # Bounds the size of the set: min_size <= k <= max_size
+        cp.sum(x) >= min_size,
+        cp.sum(x) <= max_size,
+    ]
+
+    # Create the problem model
+    problem = cp.Problem(cp.Minimize(objective), constraints)
+
+    # Solve the problem
+    problem.solve(solver=solver)
+
+    # Return the indices of the found subset
+    return [i for i in range(n_rows) if x.value[i] == 1]

desdeo/gdm/__init__.py

@@ -0,0 +1,22 @@
+"""Imports available from the desdeo-gdm package."""
+
+__all__ = [
+    "dict_of_rps_to_list_of_rps",
+    "list_of_rps_to_dict_of_rps",
+    "majority_rule",
+    "plurality_rule",
+    "agg_aspbounds",
+    "scale_delta",
+]
+
+from .gdmtools import (
+    dict_of_rps_to_list_of_rps,
+    list_of_rps_to_dict_of_rps,
+    agg_aspbounds,
+    scale_delta,
+)
+
+from .voting_rules import (
+    majority_rule,
+    plurality_rule,
+)

desdeo/gdm/gdmtools.py

@@ -0,0 +1,45 @@
+""" This module contains tools for group decision making such as manipulating set of preferences. """
+
+from desdeo.problem import Problem
+
+# Below two are tools for GDM, have needed them in both projects
+def dict_of_rps_to_list_of_rps(reference_points: dict[str, dict[str, float]]) -> list[dict[str, float]]:
+    """
+    Convert dict containing the DM key to an ordered list.
+    """
+    return list(reference_points.values())
+
+def list_of_rps_to_dict_of_rps(reference_points: list[dict[str, float]]) -> dict[str, dict[str, float]]:
+    """
+    Convert the ordered list to a dict contain the DM keys. TODO: Later maybe get these keys from somewhere.
+    """
+    return {f"DM{i+1}": rp for i, rp in enumerate(reference_points)}
+
+# TODO:(@jpajasmaa) document
+def agg_aspbounds(po_list: list[dict[str, float]], problem: Problem):
+    agg_aspirations = {}
+    agg_bounds = {}
+
+    for obj in problem.objectives:
+        if obj.maximize:
+            agg_aspirations.update({obj.symbol: max(s[obj.symbol] for s in po_list)})
+            agg_bounds.update({obj.symbol: min(s[obj.symbol] for s in po_list)})
+        else:
+            agg_aspirations.update({obj.symbol: min(s[obj.symbol] for s in po_list)})
+            agg_bounds.update({obj.symbol: max(s[obj.symbol] for s in po_list)})
+
+    return agg_aspirations, agg_bounds
+
+
+# TODO:(@jpajasmaa) comments
+def scale_delta(problem: Problem, d: float):
+    delta = {}
+    ideal = problem.get_ideal_point()
+    nadir = problem.get_nadir_point()
+
+    for obj in problem.objectives:
+        if obj.maximize:
+            delta.update({obj.symbol: d*(ideal[obj.symbol] - nadir[obj.symbol])})
+        else:
+            delta.update({obj.symbol: d*(nadir[obj.symbol] - ideal[obj.symbol])})
+    return delta

desdeo/gdm/score_bands.py

@@ -0,0 +1,114 @@
+"""Implements a interactive SCORE bands based GDM."""
+
+from typing import Literal
+
+import polars as pl
+from pydantic import BaseModel, ConfigDict, Field
+
+from desdeo.gdm.voting_rules import consensus_rule
+from desdeo.tools.score_bands import SCOREBandsConfig, SCOREBandsResult, score_json
+
+
+class SCOREBandsGDMConfig(BaseModel):
+    """Configuration for the SCORE bands based GDM."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    score_bands_config: SCOREBandsConfig = Field(default_factory=lambda: SCOREBandsConfig())
+    """Configuration for the SCORE bands method."""
+    minimum_votes: int = Field(default=1, gt=0)
+    """Minimum number of votes required to select a cluster."""
+    from_iteration: int | None
+    """The iteration number from which to consider the clusters. Set to None if method is initializing."""
+
+
+class SCOREBandsGDMResult(BaseModel):
+    """Result of the SCORE bands based GDM."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    votes: dict[str, int] | None = Field(default=None)
+    """The votes given by the decision makers."""
+    score_bands_result: SCOREBandsResult
+    """Result of the SCORE bands method."""
+    relevant_ids: list[int]
+    """IDs of the relevant solutions in the current iteration. Assumes that data is not modified between iterations."""
+    # If the data keeps changing, we need to store the actual data instead of just the IDs.
+    iteration: int
+    previous_iteration: int | None
+    """The previous iteration number, if any."""
+
+
+def score_bands_gdm(
+    data: pl.DataFrame,
+    config: SCOREBandsGDMConfig,
+    state: list[SCOREBandsGDMResult],
+    votes: dict[str, int] | None = None,
+) -> list[SCOREBandsGDMResult]:
+    """Run the SCORE bands based interactive GDM.
+
+    Args:
+        data (pl.DataFrame): The data to run the GDM on.
+        config (SCOREBandsGDMConfig): Configuration for the GDM.
+        state (list[SCOREBandsGDMResult]): List of previous state of the GDM. Empty list if first iteration.
+        votes (dict[str, int] | None, optional): Votes from the decision makers. Defaults to None.
+
+    Raises:
+        ValueError: Both state and votes must be provided or neither.
+
+    Returns:
+        list[SCOREBandsGDMResult]: The updated state of the GDM.
+    """
+    if bool(state) != bool(votes):
+        raise ValueError("Both state and votes must be provided or neither.")
+    if votes is None:
+        # First iteration. No votes yet.
+        score_bands_result = score_json(data, config.score_bands_config)
+        return [
+            SCOREBandsGDMResult(
+                score_bands_result=score_bands_result,
+                relevant_ids=list(range(len(data))),
+                iteration=1,
+                previous_iteration=None,
+            )
+        ]
+    if not state:
+        raise ValueError("State must be provided if votes are provided.")
+    elif config.from_iteration is None:
+        raise ValueError("from_iteration must be set in the config for subsequent iterations.")
+
+    winning_clusters = consensus_rule(votes, config.minimum_votes)
+
+    index_column_name = "index"
+    if index_column_name in data.columns:
+        index_column_name = "index_"
+    cluster_column_name = "cluster"
+    if cluster_column_name in data.columns:
+        cluster_column_name = "cluster_"
+
+    current_iteration = state[-1].iteration + 1
+
+    clusters = state[config.from_iteration - 1].score_bands_result.clusters
+    relevant_data = (
+        data.with_row_index(name=index_column_name)  # Add index column
+        .filter(
+            pl.col(index_column_name).is_in(state[config.from_iteration - 1].relevant_ids)
+        )  # Get the solutions from previous iteration
+        .with_columns(pl.Series(cluster_column_name, clusters))  # Add clustering information from last iteration
+        .filter(pl.col(cluster_column_name).is_in(winning_clusters))  # Keep only winning clusters
+        .drop(cluster_column_name)  # Drop cluster column
+    )
+
+    relevant_ids = relevant_data[index_column_name].to_list()
+    relevant_data = relevant_data.drop(index_column_name)  # Drop index column
+
+    return [
+        *state,
+        SCOREBandsGDMResult(
+            votes=votes,
+            score_bands_result=score_json(relevant_data, config.score_bands_config),
+            relevant_ids=relevant_ids,
+            iteration=current_iteration,
+            previous_iteration=config.from_iteration,
+        ),
+    ]

desdeo/gdm/voting_rules.py

@@ -0,0 +1,50 @@
+"""This module contains voting rules for group decision making such as majority rule."""
+
+from collections import Counter
+
+
+def majority_rule(votes: dict[str, int]) -> int | None:
+    """Choose the option that has more than half of the votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+
+    Returns:
+        int | None: The option that has more than half of the votes, or None if no such option exists.
+    """
+    counts = Counter(votes.values())
+    all_votes = sum(counts.values())
+    for vote, c in counts.items():
+        if c > all_votes // 2:
+            return vote
+    return None
+
+
+def plurality_rule(votes: dict[str, int]) -> list[int]:
+    """Choose the option that has the most votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+
+    Returns:
+        list[int]: A list of options that have the most votes (in case of a tie).
+    """
+    counts = Counter(votes.values())
+    max_votes = max(counts.values())
+    return [vote for vote, c in counts.items() if c == max_votes]
+
+
+def consensus_rule(votes: dict[str, int], min_votes: int) -> list[int]:
+    """Choose all options that have at least min_votes votes.
+
+    Args:
+        votes (dict[str, int]): A dictionary mapping voter IDs to their votes.
+        min_votes (int): The minimum number of votes required for an option to be selected.
+
+    """
+    if min_votes <= 0:
+        raise ValueError("min_votes must be greater than 0.")
+    if min_votes > len(votes):
+        raise ValueError("min_votes cannot be greater than the number of voters.")
+    counts = Counter(votes.values())
+    return [vote for vote, c in counts.items() if c >= min_votes]

desdeo/mcdm/__init__.py

@@ -0,0 +1,41 @@
+"""Imports available from the desdeo-mcdm package."""
+
+__all__ = [
+    "ENautilusResult",
+    "NimbusError",
+    "enautilus_get_representative_solutions",
+    "enautilus_step",
+    "calculate_closeness",
+    "calculate_intermediate_points",
+    "calculate_lower_bounds",
+    "calculate_reachable_subset",
+    "generate_starting_point",
+    "infer_classifications",
+    "prune_by_average_linkage",
+    "solve_intermediate_solutions",
+    "solve_sub_problems",
+    "solve_group_sub_problems",
+    "voting_procedure",
+    "rpm_solve_solutions",
+    "rpm_intermediate_solutions",
+]
+
+from .enautilus import (
+    ENautilusResult,
+    calculate_closeness,
+    calculate_intermediate_points,
+    calculate_lower_bounds,
+    calculate_reachable_subset,
+    enautilus_get_representative_solutions,
+    enautilus_step,
+    prune_by_average_linkage,
+)
+from .nimbus import (
+    NimbusError,
+    generate_starting_point,
+    infer_classifications,
+    solve_intermediate_solutions,
+    solve_sub_problems,
+)
+from .gnimbus import solve_group_sub_problems, voting_procedure
+from .reference_point_method import rpm_solve_solutions, rpm_intermediate_solutions