Skip to content

extension_interface

openml.extensions.extension_interface #

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 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@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 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@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 
234
235
236
237
238
239
240
241
242
243
244
245
@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 
109
110
111
112
113
114
115
116
117
118
119
120
@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 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
@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 
100
101
102
103
104
105
106
107
@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 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
@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 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@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 
87
88
89
90
91
92
93
94
95
96
97
98
@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 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
@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 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
@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
    """