PyIAML 1.0.0__py3-none-any.whl

iaml/logger.py

@@ -0,0 +1,138 @@
+"""Singleton used by IAML to generate nice logs"""
+from enum import Enum
+import warnings
+import rich.console
+import rich.progress
+import multiprocess
+from multiprocess.queues import Empty as MpEmpty
+
+try:
+    from queue import Empty as ThreadEmpty
+except ImportError:  # pragma: no cover
+    ThreadEmpty = MpEmpty
+
+from .meta_singleton import MetaSingleton
+
+
+class LogType(Enum):
+    """Types of log messages"""
+    INFO = 1
+    WARNING = 2
+    ERROR = 3
+
+
+class Logger(metaclass=MetaSingleton):
+    """Singleton used by IAML to generate nice logs
+    
+    :param int, optional verbose: Logger verbosity. Default to 1.
+    
+        * 0 -> No print
+        * 1 -> Progressbar only
+        * 2 -> progressbar + infos
+        * 3 -> progressbar + infos + warning
+        * 4 -> progressbar + infos + warning + error
+        * -1 -> error and progressbar
+    """
+    def __init__(self, verbose: int = 1) -> None:
+        self.console: rich.console = rich.console.Console(log_path=False)
+        """Console used by the logger"""
+
+        self.progress: rich.progress = rich.progress.Progress(console=self.console)
+        """Progress bar used by the logger"""
+
+        self.verbose: int = verbose
+        """Loagger verbosity"""
+
+        try:
+            self.log_queue = multiprocess.Queue()
+            self._queue_enabled = True
+        except (OSError, PermissionError) as exc:
+            warnings.warn(f"Logger running without multiprocess queue ({exc!r})")
+            self.log_queue = None
+            self._queue_enabled = False
+        """Queue used by the logger to handle log from various process"""
+
+        self.callback: callable = None
+        """Logger callback"""
+
+    @property
+    def verbose(self) -> int:
+        """Get logger verbosity
+        
+        :return: Logger verbosity
+        """
+        return self.__verbose
+
+    @verbose.setter
+    def verbose(self, value: int) -> int:
+        """Set logger verbosity
+        
+        :param int value: The new logger verbosity
+        :return: The new logger verbosity
+        """
+        self.__verbose = max(min(value, 4), -1)
+        self.console.quiet = self.__verbose == 0
+        return self.__verbose
+
+    def __log(self, log_type: LogType, *text: list[str]) -> None:
+        """Show text in console
+        
+        :param LogType log_type: Logger type
+        :param list[str] \\*text: Text to log in console
+        """
+        proc_name = multiprocess.current_process().name
+        if proc_name == 'MainProcess' or not self._queue_enabled:
+            if proc_name != 'MainProcess':
+                self.__print(f"[{proc_name}]", *text)
+            else:
+                self.__print(*text)
+        else:
+            self.log_queue.put((log_type, f"[{proc_name}]", *text))
+
+
+    def __print(self, *text: list[str]) -> None:
+        """Call logger callback or show text in console
+        
+        :param list[str] \\*text: Text to log in console
+        """
+        if self.callback is not None:
+            self.callback(*text)
+        else:
+            self.console.log(*text)
+
+
+    def info(self, *text: list[str]) -> None:
+        """Show info text in console
+        
+        :param list[str] \\*text: Info Text to log in console
+        """
+        if self.verbose > 1:
+            self.__log(LogType.INFO, *text)
+
+    def warning(self, *text: list[str]) -> None:
+        """Show warning text in console
+
+        :param list[str] \\*text: Warning Text to log in console
+        """
+        if self.verbose > 2:
+            self.__log(LogType.WARNING, *text)
+
+    def error(self, *text: list[str]) -> None:
+        """Show info text in console
+
+        :param list[str] \\*text: Error Text to log in console
+        """
+        if self.verbose > 3 or self.verbose == -1:
+            self.__log(LogType.ERROR, *text)
+
+    def print_queue(self):
+        """Print all texts from subProcess"""
+        if not self._queue_enabled or self.log_queue is None:
+            return
+
+        while not self.log_queue.empty():
+            try:
+                messages = self.log_queue.get(block=False)
+                self.__print(*messages)
+            except (MpEmpty, ThreadEmpty):
+                break

iaml/meta_explorer_step.py

@@ -0,0 +1,62 @@
+"""[METASTEP] Explore all sub steps in Thread and return one candidate by Sub Step"""
+from .metastep import MetaStep
+from .candidate import Candidate
+from .step import Step
+from .decorators.all import is_step, runner
+from .worker_manager import WorkerFuture, WorkerManager
+
+#
+# Inherit from MetaStep but will execute all steps at the same time.
+# The goal here is to explore many answer to a question. For example -> Try all Learning models
+#
+@is_step('meta')
+class MetaExplorerStep(MetaStep):
+    """[METASTEP] Explore all sub steps in Thread and return one candidate by Sub Step"""
+
+    name: str = "MetaExplorerStep"
+    _description: str = 'Execute all steps and keep the best result'
+    _description_long: str = None
+    _usage: str = "Use when running all child steps in parallel to pick the best result, rather than MetaOrderedStep or MetaPartialExplorerStep. Applicable to interchangeable steps on the same candidate input. Avoid when you need deterministic ordering, a single path, or lower compute."
+
+    def __init__(self, *args, also_explore_without: bool = False, **kwargs):  # pylint: disable=unused-argument
+        self.candidate = []
+        self.also_explore_without = also_explore_without
+
+    def json_pipeline(self) -> dict:
+        json = Step.json_pipeline(self)
+        json['children'] = list(map(lambda step: step.json_pipeline(), self.steps))
+        return json
+
+    def add_step(self, step: Step) -> None:
+        if Step in step.__class__.__mro__:
+            step.is_interchangeable = True
+
+            # Define enable only if False because True can generate strange behavior.
+            # True is default value anyway
+            if not self._enable:
+                step.enable = False
+
+            self.steps.append(self.configure_child(step))
+        else:
+            raise ValueError("step must be an occurrence of step (or inherited classes)")
+
+    # Explore all steps
+    @runner
+    def run(self, candidate: Candidate) -> Candidate:
+        output = []
+
+        # Try a candidate without any of explored steps
+        if self.also_explore_without:
+            output += [candidate.to_output()]
+
+        workers: list[WorkerFuture] = []
+
+        for step in self.steps:
+            future = WorkerManager().submit(step, step.run, candidate.to_input())
+            workers.append(future)
+
+        # Wait end of all threads
+        for worker in workers:
+            output += worker.result()
+
+        return output

iaml/meta_ordered_step.py

@@ -0,0 +1,28 @@
+"""
+    Group several Step and run them in list order
+"""
+from typing import TYPE_CHECKING
+
+from .decorators.all import is_step, runner
+from .metastep import MetaStep
+
+if TYPE_CHECKING:
+    from .candidate import Candidate
+
+#
+# Inherit from MetaStep but will execute all steps without priorize() method.
+#
+@is_step('meta')
+class MetaOrderedStep(MetaStep):
+    """
+    Group several Step and run them in list order
+    """
+    _usage: str = "Use when you need strict list-ordered execution of child steps instead of MetaStep prioritization. Applicable to pipelines where each step must run on the same Candidate in order. Avoid when steps are interchangeable and best-of exploration is needed (MetaExplorerStep)."
+    # Run steps self ordered by "priorize" function
+    @runner
+    def run(self, candidate:'Candidate') -> 'Candidate':
+        current_candidate: Candidate = candidate
+        for step in self.steps:
+            current_candidate = step.run(current_candidate)
+
+        return current_candidate

iaml/meta_partial_explorer_step.py

@@ -0,0 +1,34 @@
+"""[METASTEP] Generate pipeline without any exploration but optimizer 
+will be able to mutate into other steps
+"""
+from .meta_explorer_step import MetaExplorerStep
+from .step import Step
+from .void_step import VoidStep
+from .decorators.all import find_steps_by_tag, is_step
+
+@is_step('meta')
+class MetaPartialExplorerStep(MetaExplorerStep):
+    """[METASTEP] Generate pipeline without any exploration but optimizer will 
+    be able to mutate into other steps
+
+    :param Step, optional initial_step: Run this step initially instead of a no-op.
+        When a tag is supplied, the step must carry that tag.
+    """
+
+    name: str = "MetaPartialExplorerStep"
+    _usage: str = "Use when you want one initial choice that the optimizer can later replace. Starts with initial_step when supplied, otherwise a no-op matching the tag. Avoid when you need immediate exploration or an optimizer that cannot replace steps."
+
+    def __init__(self, *args, tag: str = None, initial_step: Step = None,
+                 **kwargs):  # pylint: disable=unused-argument
+        self.steps = []
+        # Partial exploration always emits a single branch, including for a no-op.
+        self.also_explore_without = False
+        if initial_step is not None:
+            if not isinstance(initial_step, Step):
+                raise TypeError("initial_step must be a Step")
+            if tag is not None and tag not in (initial_step.tags or set()):
+                raise ValueError("initial_step must match the exploration tag")
+            self.add_step(initial_step)
+        elif steps := find_steps_by_tag(tag):
+            representative = min(steps, key=lambda step: (step.__module__, step.__name__))
+            self.add_step(VoidStep(step_to_mimic=representative()))

iaml/meta_singleton.py

@@ -0,0 +1,24 @@
+"""Thread-safe implementation of Singleton"""
+from threading import Lock
+from typing import Any
+
+# Inspired by : https://refactoring.guru/fr/design-patterns/singleton/python/example#example-1
+class MetaSingleton(type):
+    """Thread-safe implementation of Singleton"""
+    _instances = {}
+    _lock: Lock = Lock() # Use to synchronize threads during first access
+
+    def __call__(cls, *args, **kwargs) -> Any:
+        with cls._lock:
+            if cls not in cls._instances:
+                instance = super().__call__(*args, **kwargs)
+                cls._instances[cls] = instance
+        return cls._instances[cls]
+
+    @classmethod
+    def reset(mcs: 'MetaSingleton') -> None:
+        """Delete saved instances -> Reset the singleton
+        
+        :param MetaSingleton mcs: The singleton to reset
+        """
+        mcs._instances = {}

iaml/metastep.py

@@ -0,0 +1,211 @@
+"""MetaStep is a direct child of Step and will carry and execute several other Steps
+-> MetaStep will execute Step one by one, using the candidate of a step as candidate of 
+the next one.
+
+The order of Step is defined by the priorize() method .
+
+There is children classes of MetaStep to execute Steps in a different way
+"""
+from typing import Any
+from .step import Step
+from .candidate import Candidate
+from .decorators.all import find_steps_by_tag, is_step, runner
+from .step_wrapper import StepWrapper
+
+
+@is_step('meta')
+class MetaStep(Step):
+    """MetaStep is a direct child of Step and will carry and execute several other Steps
+    -> MetaStep will execute Step one by one, using the candidate of a step as candidate of 
+    the next one.
+
+    The order of Step is defined by the priorize() method 
+
+    There is children classes of MetaStep to execute Steps in a different way
+    
+    :param tuple, optional \\*args: Additional parameters.
+    :param str, optional str: The tag of the meta step. Default to None.
+    :param StepWrapper, optional wrap: If exist, will wrap Steps with it. Default to None.
+    :param str, optional name: Name of the MetaStep. Default to None.
+    :param str, optional description: Description of the MetaStep. Default to None.
+    :param dict, optional \\**kwargs: Additional parameters.
+    """
+    name: str = "Steps group"
+    description: str = 'Execute steps one by one'
+    _usage: str = "Use when you need a meta step to run several child Steps and pass candidates between them. Applicable to pipelines with multiple child steps or tagged steps producing Candidate outputs. Avoid when you need fixed ordering or exploration; consider MetaOrderedStep or MetaExplorerStep."
+    description_long: str = None
+
+    def __init__(
+        self,
+        *args,
+        tag: str = None,
+        wrap: StepWrapper = None,
+        name: str = None,
+        description: str = None,
+        **kwargs) -> None:
+        self.tag: str | None = None
+        """Optional tag used to populate this meta step."""
+        self.steps: list[Step] = [] # Initialize steps to empty
+        """List of steps"""
+
+        # If there is a tag -> add all Steps with this tag
+        if tag:
+            self.tag = tag
+            self.add_step_by_tag(tag, wrap=wrap)
+            self.name = f"Steps from : {tag}"
+
+        if name:
+            self.name = name
+        if name:
+            self.description = description
+
+    @classmethod
+    def from_pipeline(cls, pipeline: dict[str, Any], *args, **kwargs) -> Step:
+        metastep = super().from_pipeline(pipeline)
+
+        if 'children' in pipeline:
+            for child in pipeline['children']:
+                metastep.add_step(Step.from_pipeline(child))
+
+        if 'tag' in pipeline:
+            metastep.add_step_by_tag(pipeline['tag'])
+
+        if not metastep.steps:
+            raise TypeError('invalid pipeline: MetaStep must have at least one child')
+
+        return metastep
+
+    def configure_parents(self, *parents: list[Step]) -> None:
+        for step in self.steps:
+            step.configure_parents(*parents)
+
+        super().configure_parents(*parents)
+
+    def add_step(self, step: Step) -> None:
+        """Add one step to the MetaStep. 
+        step must be a Step inherited class
+
+        :param Step step: Step to add
+        :raise ValueError: step must be an occurrence of step (or inherited classes)
+        """
+        if Step in step.__class__.__mro__:
+            step = self.configure_child(step)
+
+            # Define enable only if False because True can generate strange behavior.
+            # True is default value anyway
+            if not self._enable:
+                step.enable = False
+
+            self.steps.append(step)
+        else:
+            raise ValueError("step must be an occurrence of step (or inherited classes)")
+
+    def add_steps(self, steps: list[Step]) -> None:
+        """Add a list of Steps
+
+        :param list[Step] steps: List of steps to add to this MetaStep
+        """
+        for step in steps:
+            self.add_step(step)
+
+    def add_step_by_tag(self, tag: str, wrap: StepWrapper = None) -> None:
+        """Add all Step with this tag to the MetaStep
+        Wrap -> If exist, will wrap Steps with it. Check WrapperStep to know more 
+
+        :param str tag: tag to search Steps.
+        :param StepWrapper, optional wrap: Wrap Step in it. Default to None.
+        """
+        if self.tag is None:
+            self.tag = tag
+        steps_to_add = find_steps_by_tag(tag)
+
+        if wrap is not None:
+            steps_to_add = list(map(lambda step: wrap(step()), steps_to_add))
+        else:
+            steps_to_add = list(map(lambda step: step(), steps_to_add))
+
+        for step in steps_to_add:
+            self.add_step(step)
+
+    def all_configurations(self) -> list[dict[str, Any]]:
+        to_return = Step.all_configurations(self)
+
+        for step in self.steps:
+            to_return = to_return + step.all_configurations()
+
+        return to_return
+
+    def json_pipeline(self) -> dict[str, Any]:
+        payload = {
+            **Step.json_pipeline(self),
+            'children': [ step.json_pipeline() for step in self.steps ]
+        }
+        if self.tag:
+            payload['tag'] = self.tag
+        return payload
+
+    def all_steps(self) -> list[Step]:
+        children = []
+        for step in self.steps:
+            children += step.all_steps()
+
+        return [self, *children]
+
+    @runner
+    def run(self, candidate: Candidate) -> Candidate:
+        steps_to_run = self.steps.copy()
+        return self.__recursive_run(steps_to_run, [candidate])
+
+
+    def __recursive_run(self,
+            remain_steps: list[Step],
+            candidates: list[Candidate]) -> list[Candidate]:
+        """Recursive_run to manage Step with several candidates 
+
+        :param list[Step] remain_steps: Steps remaining.
+        :param list[Candidate] candidates: Candidate of previous Step.
+        :return: Results.
+        """
+        output_candidates = []
+        if remain_steps:
+            for current_candidate in candidates:
+                max_eval = remain_steps[0].priorize(current_candidate)
+                max_index = 0
+                for index, step in enumerate(remain_steps[1:]):
+                    current_eval = step.priorize(current_candidate)
+                    if current_eval > max_eval:
+                        max_eval = current_eval
+                        max_index = index+1
+
+                results = remain_steps[max_index].run(current_candidate)
+                futures_steps = remain_steps.copy()
+                futures_steps.pop(max_index)
+                output_candidates = output_candidates + \
+                    self.__recursive_run(futures_steps, results)
+
+            return output_candidates
+        return candidates
+
+    def conf_to_rich_str_list(self) -> str:
+        conf = super().conf_to_rich_str_list()
+        conf.append(f'steps={",".join({ step.__class__.__name__ for step in self.steps })}')
+
+        return conf
+
+    def count_steps(self) -> int:
+        return 1 + sum(map(lambda child: child.count_steps(), self.steps))
+
+
+    @property
+    def enable(self) -> bool:
+        return any(step.enable for step in self.steps) if hasattr(self, 'steps') else False
+
+    @enable.setter
+    def enable(self, value: bool) -> bool:
+        if hasattr(self, 'steps'):
+            for step in self.steps:
+                step.enable = value
+
+        self._enable = value # Only used has default value for new children
+
+        return self.enable

iaml/metric.py

@@ -0,0 +1,111 @@
+"""[METRIC] Parent of all others Metrics, implement the default behavior"""
+from typing import Any
+import pandas as pd
+from .reference import Reference
+
+
+class Metric:
+    """[METRIC] Parent of all others Metrics, implement the default behavior"""
+
+    greater_is_better: bool = True
+    """Whether larger values are better. Set to False for error metrics."""
+
+    name: str = ""
+    """Name of the metric"""
+
+    _description: str = ""
+    """Short description of the metric"""
+
+    _description_long: str = ""
+    """Long description of the metric"""
+
+    refs: list[dict[str, Any]] = []
+    """List of references for this metric."""
+
+    @classmethod
+    def all_subclasses(cls) -> list['Metric']:
+        """Return all metrics subclasses
+        
+        :return: List of all metrics.
+        """
+        subclasses = cls.__subclasses__()
+        for subclass in subclasses:
+            subclasses += subclass.all_subclasses()
+        return subclasses
+
+    @classmethod
+    def get_refs(cls) -> list[Reference]:
+        """Get bibliography references
+        
+        :return: List of references for this metric.
+        """
+        if hasattr(cls, 'refs'):
+            return [Reference(ref, cls.__name__) for ref in cls.refs]
+        return []
+
+    @property
+    def description(self) -> str:
+        """Formats the description of a step with its configuration.
+
+        :return: Formatted description.
+        """
+        return self._description.replace('\n', '')
+
+    @property
+    def description_long(self) -> str:
+        """Formats the longer description of a step with its configuration.
+        
+        :return: Formatted description.
+        """
+        return self._description_long.replace('\n', '')
+
+    def __str__(self) -> str:
+        """Metric name
+        
+        :return: Metric name.
+        """
+        return 'base_metric'
+
+    def explain(self) -> str:
+        """Describe metric
+
+        :return:    Metric description
+        """
+        return self.description_long
+
+    def compute(self, y: pd.DataFrame, y_pred: pd.DataFrame, **kwargs) -> float:
+        """Compute metric given y, y_pred. 
+        Must be overridden by children classes
+        
+        :param pd.DataFrame y: Ground truth to compute the metric.
+        :param pd.DataFrame y_pred: Prediction to compute the metric.
+        :param dict, optional \\**kwargs: Additional parameters
+        :return: Computed value
+        """
+        raise NotImplementedError('Subclass must implement abstract method')
+
+    def suitable(self, X: pd.DataFrame, y: pd.DataFrame, type_of_target: str) -> bool:  # pylint: disable=unused-argument
+        """Is this metric usable given X and y ?
+        
+        :param pd.DataFrame X: The dataset we try to compute metrics on.
+        :param pd.DataFrame y: The dataset target we try to compute metrics on
+        :param str type_of_target: The type of target we are trying to predict
+        :return: Suitable ?
+        """
+        return False
+
+    @property
+    def needed_prediction(self) -> str:
+        """Which kind of predict is needed by the metric
+
+        :return: Method name.
+        """
+        return "predict"
+
+    @property
+    def name(self) -> str:
+        """Return the metric formatted name
+        
+        :return: Formatted name.
+        """
+        return ' '.join(x.title() for x in str(self).split('_'))

iaml/metric_plot.py

@@ -0,0 +1,82 @@
+"""[PLOT] Parent for all metrics plots."""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Type
+
+import io
+import pandas as pd
+
+from yellowbrick.base import Visualizer
+
+from .plot import capture, Plot
+
+if TYPE_CHECKING:
+    from .iaml_pipeline import IAMLPipeline
+
+
+class MetricPlot(Plot):
+    """To be used by performance Explainer"""
+
+    def compute(
+        self,
+        estimator: IAMLPipeline,
+        X: pd.DataFrame,
+        y: pd.Series,
+        X_train: pd.DataFrame = None,
+        y_train: pd.Series = None,
+        **kwargs) -> 'MetricPlot':
+        """Compute plot given X, y. 
+        Must be overridden by children classes
+        
+        :param IAMLPipeline estimator: The pipeline we compute the plot on.
+        :param pd.DataFrame X: The dataset we wanna compute plot on.
+        :param pd.Series y: The dataset target we wanna compute plot on.
+        :param pd.DataFrame, optional X_train: The dataframe used for training.
+        :param pd.Series, optional y_train: The dataframe target used for training.
+        :param optional \\**kwargs: Additional parameters for plotting.
+        :return: A MetricPlot object.
+        """
+        raise NotImplementedError('Subclass must implement abstract method')
+
+
+def _estimator_is_fitted(estimator) -> bool:
+    checker = getattr(estimator, "__sklearn_is_fitted__", None)
+    if callable(checker):
+        try:
+            fitted = bool(checker())
+        except Exception:  # noqa: BLE001
+            return False
+        if fitted and hasattr(estimator, "predictor"):
+            predictor = getattr(estimator, "predictor", None)
+            if predictor and isinstance(predictor, tuple):
+                model = getattr(predictor[1], "model", None)
+                if model is None:
+                    return False
+        return fitted
+    return False
+
+
+def yellowbrick_plot(yellowbrick_visualizer: Type[Visualizer]):
+    """Decorator for creating metric plots based on Yellowbrick visualizers.
+
+    :param Type[Visualizer] yellowbrick_visualizer: Base Yellowbrick visualizer.
+    """
+    def decorator(cls):
+        @capture
+        def compute(self, estimator, X, y, X_train = None, y_train = None, **kwargs): # pylint: disable=missing-function-docstring, unused-argument
+            self._binary_image = io.BytesIO() # pylint: disable=protected-access
+            already_fitted = _estimator_is_fitted(estimator)
+            visualizer = yellowbrick_visualizer(estimator, is_fitted=already_fitted)
+
+            if X_train is not None and y_train is not None and not already_fitted:
+                visualizer.fit(X_train, y_train)
+
+            visualizer.score(X, y)
+            visualizer.poof(self._binary_image) # pylint: disable=protected-access
+
+            return self
+
+        cls.compute = compute
+
+        return cls
+
+    return decorator