tempor.methods.core package¶

Submodules¶

Module contents¶

Package directory for the core functionality for the methods, mainly the base classes.

class tempor.methods.core.BaseEstimator(**params: Any)[source]¶

Bases: Plugin, ABC

Abstract base class for all estimators.

Defines some core methods, primarily: - fit: Fit the model to the data. - _fit: The implementation of fit. An abstract method. - hyperparameter_space: The hyperparameter search domain, used for tuning. A static method. - sample_hyperparameters: Sample hyperparameters. A class method.

The ParamsDefinition class attribute defines the parameters (in this context, this refers to __init__() method arguments) for the estimator. It must be a dataclass. The parameters will be validated, and the resulting parameters will accessible by the class instance in the self.params attribute (omegaconf.DictConfig).

Parameters:¶

**params : Any: The parameters for the estimator, as defined in the ParamsDefinition class attribute. If not provided, the default values will be used.

ParamsDefinition¶: alias of EmptyParamsDefinition

property is_fitted : bool¶: Check if the model was trained

fit(data: BaseDataset, *args: Any, **kwargs: Any) → Self[source]¶

Fit the method to the data.

Parameters:¶

data : dataset.BaseDataset¶: The dataset to fit the model to.
*args : Any: Additional arguments to pass to the _fit method.
**kwargs : Any: Additional keyword arguments to pass to the _fit method.

Returns:¶

The fitted model.

Return type:¶

Self

abstract static hyperparameter_space(*args: Any, **kwargs: Any) → list[Params][source]¶

The hyperparameter search domain, used for tuning.

Can provide variadics *args and **kwargs, these will be received from sample_hyperparameters.

classmethod sample_hyperparameters(*args: Any, override: list[Params] | None = None, **kwargs: Any) → dict[str, Any][source]¶

Sample hyperparameters. Hyperparameters will be sampled as defined in the hyperparameter_space static method, unless override is provided, in which case, they will be sampled from the override definition.

Can provide variadics *args and **kwargs, these will be passed on to the hyperparameter_space method.

Note

If using optuna as the hyperparameter optimizer, an additional argument, trial (optuna.Trial) must be passed either as an argument or keyword argument to this method, i.e. .sample_hyperparameters(trial, ...) or .sample_hyperparameters(..., trial=trial, ...).

Parameters:¶

*args : Any: Additional arguments to pass to the hyperparameter_space method.
override : Optional[List[Params]], optional¶: If this is not None, hyperparameters will be sampled from this list, rather than from those defined in the hyperparameter_space method. Defaults to None.
**kwargs : Any: Additional keyword arguments to pass to the hyperparameter_space method.

Returns:¶

_description_

Return type:¶

Dict[str, Any]

class tempor.methods.core.importing[source]¶

Bases: object

A namespace for plugin importing functionality.

static import_plugins(init_file: str) → None[source]¶

Import all plugin modules inside the package directory associated with init_file (__init__.py). Importing in this context means programmatic import and execution of the plugin modules.

Parameters:¶

init_file : str¶: The init file for the package directory containing the plugin modules (files).

Raises:¶

RuntimeError – Raised if there are import problems with any of the plugin modules.

static gather_modules_names(package_init_file: str) → list[str][source]¶

Gather the names of all plugin modules inside the package directory associated with init_file. Useful for e.g. setting the __all__ variable.

Parameters:¶

package_init_file : str¶: The init file for the package directory containing the plugin modules (files).

Returns:¶

A list of plugin module names.

Return type:¶

List[str]

class tempor.methods.core.Plugin[source]¶

Bases: object

The base class that all plugins must inherit from.

name : ClassVar[str] = 'NOT_SET'¶: Plugin name, such as 'my_nn_classifier'. Must be set by the plugin class using @register_plugin.

category : ClassVar[str] = 'NOT_SET'¶: Plugin category, such as 'prediction.one_off.classification'. Must be set by the plugin class using @register_plugin.

plugin_type : ClassVar[None | Literal[all] | str] = 'NOT_SET'¶: Plugin type, such as 'method'. May be optionally set by the plugin class using @register_plugin, else will set the default plugin type.

classmethod full_name() → str[source]¶

The full name of the plugin with its category: category.subcategory.name. There may be 0 or more subcategories.

Returns:¶: Plugin full name.
Return type:¶: plugin_typing.PluginFullName

class tempor.methods.core.PluginLoader[source]¶

Bases: object

A class to load plugins. Provides functionality to list and get plugins.

list(plugin_type: None | Literal[all] | str = None) → dict[source]¶

List all plugins of plugin_type as a nested dictionary, where the keys are the plugin categories and optional subcategories. The values of the dictionary are the plugin names.

If plugin_type is "all", will list for all plugin types, outputting inside a nested dictionary with plugin type keys.

Parameters:¶

plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type for which to list. Use default category if None. Defaults to None.

Returns:¶

A dictionary as described above.

Return type:¶

Dict

list_full_names(plugin_type: None | Literal[all] | str = None) → list[str] | dict[str, list[str]][source]¶

List all plugins of plugin_type as a list of plugin full names (including categories).

If plugin_type is "all", will list for all plugin types, outputting inside a nested dictionary with plugin type keys.

Parameters:¶

plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type for which to list. Use default category if None. Defaults to None.

Returns:¶

A list as described above (List[PluginFullName]) if plugin_type is not "all". Otherwise a nested dictionary with plugin type keys and such lists as values (Dict[str, List[PluginFullName]]]).

Return type:¶

Union[List[plugin_typing.PluginFullName], Dict[str, List[plugin_typing.PluginFullName]]]

list_classes(plugin_type: None | Literal[all] | str = None) → dict[source]¶

List all plugin classes of plugin_type as a nested dictionary, where the keys are the plugin categories and optional subcategories. The values of the dictionary are the plugin classes.

If plugin_type is "all", will list for all plugin types, outputting inside a nested dictionary with plugin type keys.

Parameters:¶

plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type for which to list. Use default category if None. Defaults to None.

Returns:¶

A dictionary as described above.

Return type:¶

Dict

list_categories(plugin_type: None | Literal[all] | str = None) → dict[str, type[Plugin]] | dict[str, dict[str, type[Plugin]]][source]¶

List all plugin categories of plugin_type as a dictionary, where the keys are the plugin category names (including optional subcategories) and the values are the expected plugin classes for that category.

If plugin_type is "all", will list for all plugin types, outputting inside a nested dictionary with plugin type keys.

Parameters:¶

plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type for which to list. Use default category if None. Defaults to None.

Returns:¶

A dictionary as described above (Dict[PluginFullName, Type[Plugin]]) if plugin_type is not "all". Otherwise a nested dictionary with plugin type keys and such dictionaries as values (Dict[PluginType, Dict[PluginFullName, Type[Plugin]]]).

Return type:¶

ListCategoriesReturn

list_plugin_types() → list[str][source]¶

List all plugin types.

Returns:¶: A list of plugin types.
Return type:¶: List[plugin_typing.PluginType]

get(name: str, *args: Any, **kwargs: Any) → type[source]¶

get(name: str, plugin_type: None | Literal[all] | str, *args: Any, **kwargs: Any) → type

get(name: str, *args: Any, plugin_type: None | Literal[all] | str = None, **kwargs: Any) → type

Get a plugin by its full name (including category, i.e. of form 'my_category.my_subcategory.my_plugin'). Use *args and **kwargs to pass arguments to the plugin initializer. The returned object is an instance of the plugin class. If the plugin is not of the default plugin type, must provide plugin_type also.

The method can be called with plugin_type and plugin initializer arguments, as follows:

As first positional argument after the plugin name:

plugin_instance = get(
    "my_category.my_subcategory.my_plugin",  # Plugin full name.
    "method",  # Plugin type provided as a positional argument (first).
    0.4,  # First positional argument to plugin initializer.
    123,  # Second positional argument to plugin initializer...
    kwarg=2,  # Keyword argument(s) to plugin initializer from here on.
)

As keyword argument:

plugin_instance = get(
    "my_category.my_subcategory.my_plugin",  # Plugin full name.
    0.4,  # First positional argument to plugin initializer.
    123,  # Second positional argument to plugin initializer...
    plugin_type="method",  # Plugin type provided as a keyword argument.
    kwarg=2,  # Keyword argument(s) to plugin initializer from here on.
)

Parameters:¶

name : plugin_typing.PluginFullName¶: Plugin full name including all (sub)categories, of form 'my_category.my_subcategory.my_plugin'
*args : Any: Arguments to pass to the plugin initializer.
plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type. If left as None, default plugin type is assumed. plugin_type must correctly correspond to the category implied by plugin full name. Defaults to None.
**kwargs : Any: Keyword arguments to pass to the plugin initializer.

Returns:¶

The plugin instance initialised with *args and **kwargs as provided.

Return type:¶

Any

get_class(name: str, plugin_type: None | Literal[all] | str = None) → type[source]¶

Get a plugin class (not instance) by its full name (including category, i.e. of form 'my_category.my_subcategory.my_plugin'). If the plugin is not of the default plugin type, must provide plugin_type.

Parameters:¶

name : plugin_typing.PluginFullName¶: Plugin full name including all (sub)categories, of form 'my_category.my_subcategory.my_plugin'
plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type. If left as None, default plugin type is assumed. plugin_type must correctly correspond to the category implied by plugin full name. Defaults to None.

Returns:¶

Plugin class (not instance).

Return type:¶

Type

class tempor.methods.core.BasePredictor(**params: Any)[source]¶

Bases: BaseEstimator

Abstract base class for all predictors.

Defines some core methods, primarily: - predict: Predicts the target variable for the given data. - predict_proba: Predicts the probability of the target variable for the given data. - predict_counterfactuals: Predicts the counterfactuals for the given data. - The _ versions of the above methods are the implementations of the above methods in the derived classes.

predict(data: PredictiveDataset, *args: Any, **kwargs: Any) → Any[source]¶

Predicts the target variable for the given data.

Parameters:¶

data : dataset.PredictiveDataset¶: The dataset to predict on.
*args : Any: Additional positional arguments passed to the implementation (_predict).
**kwargs : Any: Additional keyword arguments passed to the implementation (_predict).

Returns:¶

The predictions.

Return type:¶

Any

predict_proba(data: PredictiveDataset, *args: Any, **kwargs: Any) → Any[source]¶

Predicts the probability of the target variable for the given data.

Parameters:¶

data : dataset.PredictiveDataset¶: The dataset to predict on.
*args : Any: Additional positional arguments passed to the implementation (_predict_proba).
**kwargs : Any: Additional keyword arguments passed to the implementation (_predict_proba).

Returns:¶

The predicted probabilities.

Return type:¶

Any

predict_counterfactuals(data: PredictiveDataset, *args: Any, **kwargs: Any) → Any[source]¶

Predicts the counterfactuals for the given data.

Parameters:¶

data : dataset.PredictiveDataset¶: The dataset to predict on.
*args : Any: Additional positional arguments passed to the implementation (_predict_counterfactuals).
**kwargs : Any: Additional keyword arguments passed to the implementation (_predict_counterfactuals).

Returns:¶

The predicted counterfactuals.

Return type:¶

Any

fit_predict(data: PredictiveDataset, *args: Any, **kwargs: Any) → Any[source]¶

Fit the model to the data and then predict on the same data. Equivalent to calling fit and then predict.

Parameters:¶

data : dataset.PredictiveDataset¶: The dataset to fit and predict on.
*args : Any: Additional positional arguments passed to the implementations (_fit and _predict).
**kwargs : Any: Additional keyword arguments passed to the implementations (_fit and _predict).

Returns:¶

The predictions.

Return type:¶

Any

tempor.methods.core.register_plugin_category(category: str, expected_class: type, plugin_type: None | Literal[all] | str = None) → None[source]¶

A decorator to register a plugin category (with optional subcategories). If plugin_type is provided, this will also be assigned (or created, if such plugin type doesn’t yet exist), otherwise the default plugin type will be used.

Parameters:¶

category : plugin_typing.PluginCategory¶: Plugin category, dot-separated, with optional subcategories, such as 'prediction.one_off.classification'.
expected_class : Type¶: The expected plugin class for this category. The plugin class must be a subclass of this class. Note that this class must itself be a subclass of Plugin.
plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type to register the category under. Different plugin types should be used to indicate different domains of your code (e.g. methods vs metrics vs datasets). Defaults to None.

Raises:¶

TypeError – If the expected_class is not correctly defined.

tempor.methods.core.register_plugin(name: str, category: str, plugin_type: None | Literal[all] | str = None) → Callable[[Callable[[P], T]], Callable[[P], T]][source]¶

A decorator to register a plugin class. If plugin_type is provided, this will also be assigned, otherwise the default plugin type will be used. The category must have already been registered with @register_plugin_category before this can be used to register a plugin.

Parameters:¶

name : str¶: Plugin name, such as 'my_nn_classifier'.
category : plugin_typing.PluginCategory¶: Plugin category, dot-separated, with optional subcategories, such as 'prediction.one_off.classification'.
plugin_type : plugin_typing.PluginTypeArg, optional¶: Plugin type of the category. If left as None, default plugin type is assumed. plugin_type must correctly correspond to the category being specified. Defaults to None.

Returns:¶

Decorated class.

Return type:¶

Callable[[Callable[P, T]], Callable[P, T]]

class tempor.methods.core.BaseTransformer(**params: Any)[source]¶

Bases: BaseEstimator

Abstract base class for all transformers.

Defines some core methods, primarily: - transform: Transforms the given data. - _transform: The implementation of the above method in the derived classes.

transform(data: BaseDataset, *args: Any, **kwargs: Any) → Any[source]¶

Transforms the given data.

Parameters:¶

data : dataset.BaseDataset¶: The dataset to transform.
*args : Any: Additional positional arguments passed to the implementation (_transform).
**kwargs : Any: Additional keyword arguments passed to the implementation (_transform).

Returns:¶

The transformed data.

Return type:¶

Any

fit_transform(data: BaseDataset, *args: Any, **kwargs: Any) → BaseDataset[source]¶

Fit the method to the data and transform it. Equivalent to calling fit and then transform.

Parameters:¶

data : dataset.BaseDataset¶: The dataset to fit and transform.
*args : Any: Additional arguments to pass to the _fit and _transform methods.
**kwargs : Any: Additional keyword arguments to pass to the _fit and _transform methods.

Returns:¶

The transformed dataset.

Return type:¶

dataset.BaseDataset