extensions

openml.extensions #

Extension #

Bases: ABC

Defines the interface to connect machine learning libraries to OpenML-Python.

See openml.extension.sklearn.extension for an implementation to bootstrap from.

can_handle_flow `abstractmethod` `classmethod` #

can_handle_flow(flow: OpenMLFlow) -> bool

Check whether a given flow can be handled by this extension.

This is typically done by parsing the external_version field.

PARAMETER	DESCRIPTION
`flow`	TYPE: `OpenMLFlow`

RETURNS	DESCRIPTION
`bool`

Source code in openml/extensions/extension_interface.py

@classmethod
@abstractmethod
def can_handle_flow(cls, flow: OpenMLFlow) -> bool:
    """Check whether a given flow can be handled by this extension.

    This is typically done by parsing the ``external_version`` field.

    Parameters
    ----------
    flow : OpenMLFlow

    Returns
    -------
    bool
    """

can_handle_model `abstractmethod` `classmethod` #

can_handle_model(model: Any) -> bool

Check whether a model flow can be handled by this extension.

This is typically done by checking the type of the model, or the package it belongs to.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`

RETURNS	DESCRIPTION
`bool`

Source code in openml/extensions/extension_interface.py

@classmethod
@abstractmethod
def can_handle_model(cls, model: Any) -> bool:
    """Check whether a model flow can be handled by this extension.

    This is typically done by checking the type of the model, or the package it belongs to.

    Parameters
    ----------
    model : Any

    Returns
    -------
    bool
    """

check_if_model_fitted `abstractmethod` #

check_if_model_fitted(model: Any) -> bool

Returns True/False denoting if the model has already been fitted/trained.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`

RETURNS	DESCRIPTION
`bool`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def check_if_model_fitted(self, model: Any) -> bool:
    """Returns True/False denoting if the model has already been fitted/trained.

    Parameters
    ----------
    model : Any

    Returns
    -------
    bool
    """

create_setup_string `abstractmethod` #

create_setup_string(model: Any) -> str

Create a string which can be used to reinstantiate the given model.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`

RETURNS	DESCRIPTION
`str`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def create_setup_string(self, model: Any) -> str:
    """Create a string which can be used to reinstantiate the given model.

    Parameters
    ----------
    model : Any

    Returns
    -------
    str
    """

flow_to_model `abstractmethod` #

flow_to_model(flow: OpenMLFlow, initialize_with_defaults: bool = False, strict_version: bool = True) -> Any

Instantiate a model from the flow representation.

PARAMETER	DESCRIPTION
`flow`	TYPE: `OpenMLFlow`
`initialize_with_defaults`	If this flag is set, the hyperparameter values of flows will be ignored and a flow with its defaults is returned. TYPE: `(bool, optional(default=False))` DEFAULT: `False`
`strict_version`	Whether to fail if version requirements are not fulfilled. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Any`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def flow_to_model(
    self,
    flow: OpenMLFlow,
    initialize_with_defaults: bool = False,  # noqa: FBT002
    strict_version: bool = True,  # noqa: FBT002
) -> Any:
    """Instantiate a model from the flow representation.

    Parameters
    ----------
    flow : OpenMLFlow

    initialize_with_defaults : bool, optional (default=False)
        If this flag is set, the hyperparameter values of flows will be
        ignored and a flow with its defaults is returned.

    strict_version : bool, default=True
        Whether to fail if version requirements are not fulfilled.

    Returns
    -------
    Any
    """

get_version_information `abstractmethod` #

get_version_information() -> list[str]

List versions of libraries required by the flow.

RETURNS	DESCRIPTION
`List`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def get_version_information(self) -> list[str]:
    """List versions of libraries required by the flow.

    Returns
    -------
    List
    """

instantiate_model_from_hpo_class `abstractmethod` #

instantiate_model_from_hpo_class(model: Any, trace_iteration: OpenMLTraceIteration) -> Any

Instantiate a base model which can be searched over by the hyperparameter optimization model.

PARAMETER	DESCRIPTION
`model`	A hyperparameter optimization model which defines the model to be instantiated. TYPE: `Any`
`trace_iteration`	Describing the hyperparameter settings to instantiate. TYPE: `OpenMLTraceIteration`

RETURNS	DESCRIPTION
`Any`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def instantiate_model_from_hpo_class(
    self,
    model: Any,
    trace_iteration: OpenMLTraceIteration,
) -> Any:
    """Instantiate a base model which can be searched over by the hyperparameter optimization
    model.

    Parameters
    ----------
    model : Any
        A hyperparameter optimization model which defines the model to be instantiated.
    trace_iteration : OpenMLTraceIteration
        Describing the hyperparameter settings to instantiate.

    Returns
    -------
    Any
    """

is_estimator `abstractmethod` #

is_estimator(model: Any) -> bool

Check whether the given model is an estimator for the given extension.

This function is only required for backwards compatibility and will be removed in the near future.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`

RETURNS	DESCRIPTION
`bool`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def is_estimator(self, model: Any) -> bool:
    """Check whether the given model is an estimator for the given extension.

    This function is only required for backwards compatibility and will be removed in the
    near future.

    Parameters
    ----------
    model : Any

    Returns
    -------
    bool
    """

model_to_flow `abstractmethod` #

model_to_flow(model: Any) -> OpenMLFlow

Transform a model to a flow for uploading it to OpenML.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`

RETURNS	DESCRIPTION
`OpenMLFlow`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def model_to_flow(self, model: Any) -> OpenMLFlow:
    """Transform a model to a flow for uploading it to OpenML.

    Parameters
    ----------
    model : Any

    Returns
    -------
    OpenMLFlow
    """

obtain_parameter_values `abstractmethod` #

obtain_parameter_values(flow: OpenMLFlow, model: Any = None) -> list[dict[str, Any]]

Extracts all parameter settings required for the flow from the model.

If no explicit model is provided, the parameters will be extracted from flow.model instead.

PARAMETER	DESCRIPTION
`flow`	OpenMLFlow object (containing flow ids, i.e., it has to be downloaded from the server) TYPE: `OpenMLFlow`
`model`	The model from which to obtain the parameter values. Must match the flow signature. If None, use the model specified in `OpenMLFlow.model`. TYPE: `Any` DEFAULT: `None`

RETURNS	DESCRIPTION
`list`	A list of dicts, where each dict has the following entries: - `oml:name` : str: The OpenML parameter name - `oml:value` : mixed: A representation of the parameter value - `oml:component` : int: flow id to which the parameter belongs

Source code in openml/extensions/extension_interface.py

@abstractmethod
def obtain_parameter_values(
    self,
    flow: OpenMLFlow,
    model: Any = None,
) -> list[dict[str, Any]]:
    """Extracts all parameter settings required for the flow from the model.

    If no explicit model is provided, the parameters will be extracted from `flow.model`
    instead.

    Parameters
    ----------
    flow : OpenMLFlow
        OpenMLFlow object (containing flow ids, i.e., it has to be downloaded from the server)

    model: Any, optional (default=None)
        The model from which to obtain the parameter values. Must match the flow signature.
        If None, use the model specified in ``OpenMLFlow.model``.

    Returns
    -------
    list
        A list of dicts, where each dict has the following entries:
        - ``oml:name`` : str: The OpenML parameter name
        - ``oml:value`` : mixed: A representation of the parameter value
        - ``oml:component`` : int: flow id to which the parameter belongs
    """

seed_model `abstractmethod` #

seed_model(model: Any, seed: int | None) -> Any

Set the seed of all the unseeded components of a model and return the seeded model.

Required so that all seed information can be uploaded to OpenML for reproducible results.

PARAMETER	DESCRIPTION
`model`	The model to be seeded TYPE: `Any`
`seed`	TYPE: `int`

RETURNS	DESCRIPTION
`model`

Source code in openml/extensions/extension_interface.py

@abstractmethod
def seed_model(self, model: Any, seed: int | None) -> Any:
    """Set the seed of all the unseeded components of a model and return the seeded model.

    Required so that all seed information can be uploaded to OpenML for reproducible results.

    Parameters
    ----------
    model : Any
        The model to be seeded
    seed : int

    Returns
    -------
    model
    """

get_extension_by_flow #

get_extension_by_flow(flow: OpenMLFlow, raise_if_no_extension: bool = False) -> Extension | None

Get an extension which can handle the given flow.

Iterates all registered extensions and checks whether they can handle the presented flow. Raises an exception if two extensions can handle a flow.

PARAMETER	DESCRIPTION
`flow`	TYPE: `OpenMLFlow`
`raise_if_no_extension`	Raise an exception if no registered extension can handle the presented flow. TYPE: `bool (optional` DEFAULT: `False)`

RETURNS	DESCRIPTION
`Extension or None`

Source code in openml/extensions/functions.py

def get_extension_by_flow(
    flow: OpenMLFlow,
    raise_if_no_extension: bool = False,  # noqa: FBT002
) -> Extension | None:
    """Get an extension which can handle the given flow.

    Iterates all registered extensions and checks whether they can handle the presented flow.
    Raises an exception if two extensions can handle a flow.

    Parameters
    ----------
    flow : OpenMLFlow

    raise_if_no_extension : bool (optional, default=False)
        Raise an exception if no registered extension can handle the presented flow.

    Returns
    -------
    Extension or None
    """
    # import openml_sklearn to register SklearnExtension
    if importlib.util.find_spec("openml_sklearn"):
        import openml_sklearn  # noqa: F401

    candidates = []
    for extension_class in openml.extensions.extensions:
        if extension_class.can_handle_flow(flow):
            candidates.append(extension_class())
    if len(candidates) == 0:
        if raise_if_no_extension:
            install_instruction = ""
            if flow.name.startswith("sklearn"):
                install_instruction = SKLEARN_HINT
            raise ValueError(
                f"No extension registered which can handle flow: {flow.flow_id} ({flow.name}). "
                f"{install_instruction}"
            )

        return None

    if len(candidates) == 1:
        return candidates[0]

    raise ValueError(
        f"Multiple extensions registered which can handle flow: {flow}, but only one "
        f"is allowed ({candidates}).",
    )

get_extension_by_model #

get_extension_by_model(model: Any, raise_if_no_extension: bool = False) -> Extension | None

Get an extension which can handle the given flow.

Iterates all registered extensions and checks whether they can handle the presented model. Raises an exception if two extensions can handle a model.

PARAMETER	DESCRIPTION
`model`	TYPE: `Any`
`raise_if_no_extension`	Raise an exception if no registered extension can handle the presented model. TYPE: `bool (optional` DEFAULT: `False)`

RETURNS	DESCRIPTION
`Extension or None`

Source code in openml/extensions/functions.py

def get_extension_by_model(
    model: Any,
    raise_if_no_extension: bool = False,  # noqa: FBT002
) -> Extension | None:
    """Get an extension which can handle the given flow.

    Iterates all registered extensions and checks whether they can handle the presented model.
    Raises an exception if two extensions can handle a model.

    Parameters
    ----------
    model : Any

    raise_if_no_extension : bool (optional, default=False)
        Raise an exception if no registered extension can handle the presented model.

    Returns
    -------
    Extension or None
    """
    # import openml_sklearn to register SklearnExtension
    if importlib.util.find_spec("openml_sklearn"):
        import openml_sklearn  # noqa: F401

    candidates = []
    for extension_class in openml.extensions.extensions:
        if extension_class.can_handle_model(model):
            candidates.append(extension_class())
    if len(candidates) == 0:
        if raise_if_no_extension:
            install_instruction = ""
            if type(model).__module__.startswith("sklearn"):
                install_instruction = SKLEARN_HINT
            raise ValueError(
                f"No extension registered which can handle model: {model}. {install_instruction}"
            )

        return None

    if len(candidates) == 1:
        return candidates[0]

    raise ValueError(
        f"Multiple extensions registered which can handle model: {model}, but only one "
        f"is allowed ({candidates}).",
    )

register_extension #

register_extension(extension: type[Extension]) -> None

Register an extension.

Registered extensions are considered by get_extension_by_flow and get_extension_by_model, which are used by openml.flow and openml.runs.

PARAMETER	DESCRIPTION
`extension`	TYPE: `Type[Extension]`

RETURNS	DESCRIPTION
`None`

Source code in openml/extensions/functions.py

def register_extension(extension: type[Extension]) -> None:
    """Register an extension.

    Registered extensions are considered by ``get_extension_by_flow`` and
    ``get_extension_by_model``, which are used by ``openml.flow`` and ``openml.runs``.

    Parameters
    ----------
    extension : Type[Extension]

    Returns
    -------
    None
    """
    openml.extensions.extensions.append(extension)

extensions

openml.extensions #

Extension #

can_handle_flow abstractmethod classmethod #

can_handle_model abstractmethod classmethod #

check_if_model_fitted abstractmethod #

create_setup_string abstractmethod #

flow_to_model abstractmethod #

get_version_information abstractmethod #

instantiate_model_from_hpo_class abstractmethod #

is_estimator abstractmethod #

model_to_flow abstractmethod #

obtain_parameter_values abstractmethod #

seed_model abstractmethod #

get_extension_by_flow #

get_extension_by_model #

register_extension #

can_handle_flow `abstractmethod` `classmethod` #

can_handle_model `abstractmethod` `classmethod` #

check_if_model_fitted `abstractmethod` #

create_setup_string `abstractmethod` #

flow_to_model `abstractmethod` #

get_version_information `abstractmethod` #

instantiate_model_from_hpo_class `abstractmethod` #

is_estimator `abstractmethod` #

model_to_flow `abstractmethod` #

obtain_parameter_values `abstractmethod` #

seed_model `abstractmethod` #