asf 0.1.1__tar.gz

asf-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hadar Shavit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asf-0.1.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: asf
+Version: 0.1.1
+Summary: Algorithm selection framework
+Author-email: Hadar Shavit <shavit@aim.rwth-aachen.de>
+Maintainer-email: Hadar Shavit <shavit@aim.rwth-aachen.de>
+License: MIT License
+        
+        Copyright (c) 2025 Hadar Shavit
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: documentation, https://hadarshavit.github.io/asf/latest/
+Project-URL: repository, https://github.com/hadarshavit/asf
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+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 :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn
+Requires-Dist: pandas
+Requires-Dist: numpy
+Provides-Extra: aslib
+Requires-Dist: pyyaml; extra == "aslib"
+Requires-Dist: liac-arff; extra == "aslib"
+Provides-Extra: nn
+Requires-Dist: torch; extra == "nn"
+Provides-Extra: xgb
+Requires-Dist: xgboost; extra == "xgb"
+Provides-Extra: tune
+Requires-Dist: smac; extra == "tune"
+Provides-Extra: aspeed
+Requires-Dist: clingo; extra == "aspeed"
+Provides-Extra: survival
+Requires-Dist: scikit-survival; extra == "survival"
+Provides-Extra: all
+Requires-Dist: pyyaml; extra == "all"
+Requires-Dist: liac-arff; extra == "all"
+Requires-Dist: torch; extra == "all"
+Requires-Dist: xgboost; extra == "all"
+Requires-Dist: smac; extra == "all"
+Requires-Dist: clingo; extra == "all"
+Requires-Dist: scikit-survival; extra == "all"
+Dynamic: license-file
+
+[![PyPI - Version](https://img.shields.io/pypi/v/asf-lib)](https://pypi.org/project/asf-lib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/asf-lib)](https://pypi.org/project/asf-lib/)
+[![License](https://img.shields.io/pypi/l/asf-lib?color=informational)](LICENSE)
+[![Python application](https://github.com/hadarshavit/asf/actions/workflows/tests.yml/badge.svg)](https://github.com/hadarshavit/asf/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14957286.svg)](https://doi.org/10.5281/zenodo.14957286)
+
+# Algorithm Selection Framework (ASF)
+
+ASF is a lightweight yet powerful Python library for algorithm selection and empirical performance prediction. 
+It implements various algorithm selection methods, along with algorithm pre-selection, pre-solving schedules and more features to easily create algorithm selection pipeline.
+ASF is a modular framework that allows easy extensions to tailor made an algorithm selector for every use-case.
+While ASF includes several built-in machine learning models through scikit-learn and XGBoost, it supports every model that complies with the scikit-learn API.
+ASF also implements empirical performance prediction, allowing to use different performance scalings.
+
+ASF is written in Python 3 and is intended to use with Python 3.10+. It requires only scikit-learn, NumPy as Pandas as basic requirements. More advanced features (such as hyperparameter optimisation) requires additional dependencies. 
+
+You can find full documentation in: https://hadarshavit.github.io/asf/
+## Installation
+
+ASF is written in Python3 and requires Python version 3.10+.
+The basic installation is lightweight and requires only NumPy, Pandas and scikit-learn.
+
+ASF is currently tested on Linux machines. Mac and Windows (official) support will be released in the near future.
+
+To install the base version run 
+```bash
+pip install asf-lib
+```
+
+### Additional options
+
+Additional options include:
+
+- XGBoost model suppot `pip install asf-lib[xgb]`
+- PyTorch-based models `pip install asf-lib[nn]`
+- ASlib scenarios reading `pip install asf-lib[aslib]`
+
+## Quick start
+
+The first step is to define a the data. It can be either NumPy array or Pandas DataFrame.
+The data contains of (at least) two matrices. The first defines the instance features with a row for every instance and each column defines one feature.
+The second is the performance data, which for which every row describes an instance and each column the performance of a single algorithm.
+
+Here, we define some toy data on three instances, three features and three algorithms.
+
+```python
+data = np.array(
+    [
+        [10, 5, 1],
+        [20, 10, 2],
+        [15, 8, 1.5],
+    ]
+)
+features = pd.DataFrame(data, columns=["feature1", "feature2", "feature3"])
+performance = np.array(
+    [
+        [120, 100, 110],
+        [140, 150, 130],
+        [180, 170, 190],
+    ]
+)
+performance = pd.DataFrame(data, columns=["algo1", "algo2", "algo3"])
+
+```
+
+We can then define a selector:
+```python
+from asf.selectors import PairwiseClassifier
+from sklearn.ensemble import RandomForestClassifier
+
+selector = PairwiseClassifier(model_class=RandomForestClassifier)
+
+selector.fit(features, performance)
+```
+
+Next, we can use the selector to predict on unseen dta:
+```
+selector.predict(features)
+```
+Currently, ASF always returns the prediction in the ASlib format: a dictionary which has the instance id (row index, in case of a numpy array or the index of the row for a pandas dataframe) as keys and an array of tuples (predicted algorithm, budget).
+The selectors has only one tuple in the array, which is the selected algorithm. 
+An example output is:
+```
+{
+    0: [('algo2', None)], 
+    1: [('algo3', None)], 
+    2: [('algo2', None)]
+}
+```
+
+The budget is set by default to None. To change the budget, you can pass it as an argument for the selector initialisation.
+Similarly, ASF minimises the performance by default. To change it, pass `maxmimize=True` to the selector.
+
+
+
+
+## Cite Us
+
+If you use ASF, please cite the Zenodo DOI. We are currently working on publishing a paper on ASF, but by then a Zenodo citation will do it. 
+
+```bibtex
+@software{ASF,
+	author = {Hadar Shavit and Holger Hoos},
+	doi = {10.5281/zenodo.15288151},
+	title = {ASF: Algorithm Selection Framework},
+	url = {https://doi.org/10.5281/zenodo.15288151},
+	year = {in progress},
+}
+```

asf-0.1.1/README.md

@@ -0,0 +1,109 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/asf-lib)](https://pypi.org/project/asf-lib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/asf-lib)](https://pypi.org/project/asf-lib/)
+[![License](https://img.shields.io/pypi/l/asf-lib?color=informational)](LICENSE)
+[![Python application](https://github.com/hadarshavit/asf/actions/workflows/tests.yml/badge.svg)](https://github.com/hadarshavit/asf/actions/workflows/tests.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14957286.svg)](https://doi.org/10.5281/zenodo.14957286)
+
+# Algorithm Selection Framework (ASF)
+
+ASF is a lightweight yet powerful Python library for algorithm selection and empirical performance prediction. 
+It implements various algorithm selection methods, along with algorithm pre-selection, pre-solving schedules and more features to easily create algorithm selection pipeline.
+ASF is a modular framework that allows easy extensions to tailor made an algorithm selector for every use-case.
+While ASF includes several built-in machine learning models through scikit-learn and XGBoost, it supports every model that complies with the scikit-learn API.
+ASF also implements empirical performance prediction, allowing to use different performance scalings.
+
+ASF is written in Python 3 and is intended to use with Python 3.10+. It requires only scikit-learn, NumPy as Pandas as basic requirements. More advanced features (such as hyperparameter optimisation) requires additional dependencies. 
+
+You can find full documentation in: https://hadarshavit.github.io/asf/
+## Installation
+
+ASF is written in Python3 and requires Python version 3.10+.
+The basic installation is lightweight and requires only NumPy, Pandas and scikit-learn.
+
+ASF is currently tested on Linux machines. Mac and Windows (official) support will be released in the near future.
+
+To install the base version run 
+```bash
+pip install asf-lib
+```
+
+### Additional options
+
+Additional options include:
+
+- XGBoost model suppot `pip install asf-lib[xgb]`
+- PyTorch-based models `pip install asf-lib[nn]`
+- ASlib scenarios reading `pip install asf-lib[aslib]`
+
+## Quick start
+
+The first step is to define a the data. It can be either NumPy array or Pandas DataFrame.
+The data contains of (at least) two matrices. The first defines the instance features with a row for every instance and each column defines one feature.
+The second is the performance data, which for which every row describes an instance and each column the performance of a single algorithm.
+
+Here, we define some toy data on three instances, three features and three algorithms.
+
+```python
+data = np.array(
+    [
+        [10, 5, 1],
+        [20, 10, 2],
+        [15, 8, 1.5],
+    ]
+)
+features = pd.DataFrame(data, columns=["feature1", "feature2", "feature3"])
+performance = np.array(
+    [
+        [120, 100, 110],
+        [140, 150, 130],
+        [180, 170, 190],
+    ]
+)
+performance = pd.DataFrame(data, columns=["algo1", "algo2", "algo3"])
+
+```
+
+We can then define a selector:
+```python
+from asf.selectors import PairwiseClassifier
+from sklearn.ensemble import RandomForestClassifier
+
+selector = PairwiseClassifier(model_class=RandomForestClassifier)
+
+selector.fit(features, performance)
+```
+
+Next, we can use the selector to predict on unseen dta:
+```
+selector.predict(features)
+```
+Currently, ASF always returns the prediction in the ASlib format: a dictionary which has the instance id (row index, in case of a numpy array or the index of the row for a pandas dataframe) as keys and an array of tuples (predicted algorithm, budget).
+The selectors has only one tuple in the array, which is the selected algorithm. 
+An example output is:
+```
+{
+    0: [('algo2', None)], 
+    1: [('algo3', None)], 
+    2: [('algo2', None)]
+}
+```
+
+The budget is set by default to None. To change the budget, you can pass it as an argument for the selector initialisation.
+Similarly, ASF minimises the performance by default. To change it, pass `maxmimize=True` to the selector.
+
+
+
+
+## Cite Us
+
+If you use ASF, please cite the Zenodo DOI. We are currently working on publishing a paper on ASF, but by then a Zenodo citation will do it. 
+
+```bibtex
+@software{ASF,
+	author = {Hadar Shavit and Holger Hoos},
+	doi = {10.5281/zenodo.15288151},
+	title = {ASF: Algorithm Selection Framework},
+	url = {https://doi.org/10.5281/zenodo.15288151},
+	year = {in progress},
+}
+```

asf-0.1.1/asf/cli/cli_train.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""CLI entry point for training selectors.
+
+This script provides a command-line interface for training model-based selectors.
+It allows users to specify the selector type, model, budget, and other parameters
+to train and save the selector model.
+"""
+
+import argparse
+from pathlib import Path
+from functools import partial
+from typing import Dict, Callable, List
+
+import pandas as pd
+
+from asf import selectors
+
+import sklearn
+
+# Mapping of file extensions to pandas read functions
+pandas_read_map: Dict[str, Callable] = {
+    ".csv": pd.read_csv,
+    ".parquet": pd.read_parquet,
+    ".json": pd.read_json,
+    ".feather": pd.read_feather,
+    ".hdf": pd.read_hdf,
+    ".html": pd.read_html,
+    ".xml": pd.read_xml,
+}
+
+
+def parser_function() -> argparse.ArgumentParser:
+    """Define command line arguments for the CLI.
+
+    Returns:
+        argparse.ArgumentParser: The argument parser with defined arguments.
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--selector",
+        choices=selectors.__implemented__,
+        required=True,
+        help="Selector to train",
+    )
+    parser.add_argument(
+        "--model",
+        default="RandomForestClassifier",
+        help="Model to use for the selector. "
+        "Make sure to specify as an attribute of sklearn.ensemble.",
+    )
+    parser.add_argument(
+        "--budget",
+        type=int,
+        default=None,
+        required=False,
+        help="Budget for the solvers",
+    )
+    parser.add_argument(
+        "--maximize",
+        type=bool,
+        default=False,
+        required=False,
+        help="Maximize the objective",
+    )
+    parser.add_argument(
+        "--performance-metric",
+        type=str,
+        default="",
+        required=False,
+        help="Performance metric to optimize",
+    )
+    parser.add_argument(
+        "--feature-data",
+        type=Path,
+        required=True,
+        help="Path to feature data",
+    )
+    parser.add_argument(
+        "--performance-data",
+        type=Path,
+        required=True,
+        help="Path to performance data",
+    )
+    parser.add_argument(
+        "--model-path",
+        type=Path,
+        required=True,
+        help="Path to save model",
+    )
+    return parser
+
+
+def build_cli_command(
+    selector: selectors.AbstractModelBasedSelector,
+    feature_data: Path,
+    performance_data: Path,
+    destination: Path,
+) -> List[str]:
+    """Build a CLI command from variables for async jobs.
+
+    Args:
+        selector (selectors.AbstractModelBasedSelector): Selector to train.
+        feature_data (Path): Path to feature data DataFrame.
+        performance_data (Path): Path to performance data DataFrame.
+        destination (Path): Path to save the trained model.
+
+    Returns:
+        List[str]: A list of command-line arguments to execute the training job.
+    """
+    model_class = (
+        selector.model_class.args[0]
+        if isinstance(selector.model_class, partial)
+        else selector.model_class
+    )
+    return [
+        "python",
+        str(Path(__file__).absolute()),
+        "--selector",
+        type(selector).__name__,
+        "--model",
+        f"{model_class.__name__}",
+        "--budget",
+        str(selector.budget),
+        "--maximize",
+        str(selector.maximize),
+        "--performance-metric",
+        str(selector.performance_metric),
+        "--feature-data",
+        str(feature_data),
+        "--performance-data",
+        str(performance_data),
+        "--model-path",
+        str(destination),
+    ]
+
+
+if __name__ == "__main__":
+    parser = parser_function()
+    args = parser.parse_args()
+
+    # Parse selector into variable
+    selector_class = getattr(selectors, args.selector)
+    model_class = getattr(sklearn.ensemble, args.model)
+
+    # Parse training data into variables
+    features: pd.DataFrame = pandas_read_map[args.feature_data.suffix](
+        args.feature_data, index_col=0
+    )
+    performance_data: pd.DataFrame = pandas_read_map[args.performance_data.suffix](
+        args.performance_data, index_col=0
+    )
+
+    selector = selector_class(
+        model_class,
+        maximize=args.maximize,
+        budget=args.budget,
+    )
+    selector.fit(features, performance_data)
+
+    # Save the model to the specified path
+    selector.save(args.model_path)

asf-0.1.1/asf/epm/__init__.py

@@ -0,0 +1,4 @@
+from asf.epm.epm import EPM
+from asf.epm.epm_tuner import tune_epm
+
+__all__ = ["EPM", "tune_epm"]

asf-0.1.1/asf/epm/epm.py

@@ -0,0 +1,147 @@
+from functools import partial
+from typing import Type, Union, Optional
+
+import pandas as pd
+import numpy as np
+from sklearn.base import RegressorMixin
+
+from asf.preprocessing.performace_scaling import AbstractNormalization, LogNormalization
+from asf.predictors import SklearnWrapper
+from asf.preprocessing.sklearn_preprocessor import get_default_preprocessor
+from sklearn.base import TransformerMixin
+from asf.predictors.abstract_predictor import AbstractPredictor
+
+
+class EPM:
+    """
+    The EPM (Empirical Performance Model) class is a wrapper for machine learning models
+    that includes preprocessing, normalization, and optional inverse transformation of predictions.
+
+    Attributes:
+        predictor_class (Type[AbstractPredictor] | Type[RegressorMixin]): The class of the predictor to use.
+        normalization_class (Type[AbstractNormalization]): The normalization class to apply to the target variable.
+        transform_back (bool): Whether to apply inverse transformation to predictions.
+        features_preprocessing (Union[str, TransformerMixin]): Preprocessing pipeline for features.
+        predictor_config (Optional[dict]): Configuration for the predictor.
+        predictor_kwargs (Optional[dict]): Additional keyword arguments for the predictor.
+    """
+
+    def __init__(
+        self,
+        predictor_class: Union[Type[AbstractPredictor], Type[RegressorMixin]],
+        normalization_class: Type[AbstractNormalization] = LogNormalization,
+        transform_back: bool = True,
+        features_preprocessing: Union[str, TransformerMixin] = "default",
+        categorical_features: Optional[list] = None,
+        numerical_features: Optional[list] = None,
+        predictor_config: Optional[dict] = None,
+        predictor_kwargs: Optional[dict] = None,
+    ):
+        """
+        Initialize the EPM model.
+
+        Parameters:
+            predictor_class (Type[AbstractPredictor] | Type[RegressorMixin]): The class of the predictor to use.
+            normalization_class (Type[AbstractNormalization]): The normalization class to apply to the target variable.
+            transform_back (bool): Whether to apply inverse transformation to predictions.
+            features_preprocessing (Union[str, TransformerMixin]): Preprocessing pipeline for features.
+            categorical_features (Optional[list]): List of categorical feature names.
+            numerical_features (Optional[list]): List of numerical feature names.
+            predictor_config (Optional[dict]): Configuration for the predictor.
+            predictor_kwargs (Optional[dict]): Additional keyword arguments for the predictor.
+        """
+        if isinstance(predictor_class, type) and issubclass(
+            predictor_class, (RegressorMixin)
+        ):
+            self.model_class = partial(SklearnWrapper, predictor_class)
+        else:
+            self.model_class = predictor_class
+
+        self.predictor_class = predictor_class
+        self.normalization_class = normalization_class
+        self.transform_back = transform_back
+        self.predictor_config = predictor_config
+        self.predictor_kwargs = predictor_kwargs or {}
+        self.numpy = False
+
+        if features_preprocessing == "default":
+            self.features_preprocessing = get_default_preprocessor(
+                categorical_features=categorical_features,
+                numerical_features=numerical_features,
+            )
+        else:
+            self.features_preprocessing = features_preprocessing
+
+    def fit(
+        self,
+        X: Union[pd.DataFrame, pd.Series, list],
+        y: Union[pd.Series, list],
+        sample_weight: Optional[list] = None,
+    ) -> "EPM":
+        """
+        Fit the EPM model to the data.
+
+        Parameters:
+            X (Union[pd.DataFrame, pd.Series, list]): Features.
+            y (Union[pd.Series, list]): Target variable.
+            sample_weight (Optional[list]): Sample weights (optional).
+
+        Returns:
+            EPM: The fitted EPM model.
+        """
+        if isinstance(X, np.ndarray) and isinstance(y, np.ndarray):
+            X = pd.DataFrame(
+                X,
+                index=range(len(X)),
+                columns=[f"f_{i}" for i in range(X.shape[1])],
+            )
+            y = pd.Series(
+                y,
+                index=range(len(y)),
+            )
+            self.numpy = True
+
+        if self.features_preprocessing is not None:
+            X = self.features_preprocessing.fit_transform(X)
+
+        self.normalization = self.normalization_class()
+        self.normalization.fit(y)
+        y = self.normalization.transform(y)
+
+        if self.predictor_config is None:
+            self.predictor = self.predictor_class()
+        else:
+            self.predictor = self.predictor_class.get_from_configuration(
+                self.predictor_config, **self.predictor_kwargs
+            )()
+
+        self.predictor.fit(X, y, sample_weight=sample_weight)
+        return self
+
+    def predict(self, X: Union[pd.DataFrame, pd.Series, list]) -> list:
+        """
+        Predict using the fitted EPM model.
+
+        Parameters:
+            X (Union[pd.DataFrame, pd.Series, list]): Features.
+
+        Returns:
+            list: Predicted values.
+        """
+        if self.numpy:
+            if isinstance(X, np.ndarray):
+                X = pd.DataFrame(
+                    X,
+                    index=range(len(X)),
+                    columns=[f"f_{i}" for i in range(X.shape[1])],
+                )
+
+        if self.features_preprocessing is not None:
+            X = self.features_preprocessing.transform(X)
+
+        y_pred = self.predictor.predict(X)
+
+        if self.transform_back:
+            y_pred = self.normalization.inverse_transform(y_pred)
+
+        return y_pred