mlrl.common.learners module

Author: Michael Rapp (michael.rapp.ml@gmail.com)

Provides base classes for implementing single- or multi-label classifiers or rankers.

class mlrl.common.learners.IncrementalLearner

Bases: ABC

A base class for all single- or multi-label classifiers or rankers that support incremental prediction. For example, when dealing with ensemble models that consist of several ensemble members, it is possible to consider only a subset of the ensemble members for prediction.

class IncrementalPredictor

Bases: ABC

A base class for all classes that allow to obtain incremental predictions from a IncrementalLearner.

abstract apply_next(step_size: int)

Updates the current predictions by considering several of the remaining ensemble members. If not enough ensemble members are remaining, only the available ones will be used for updating the current predictions.

Parameters:

step_size – The number of additional ensemble members to be considered for prediction

Returns:

A numpy.ndarray or scipy.sparse matrix of shape (num_examples, num_labels), that stores the updated prediction for individual examples and labels

abstract get_num_next() → int

Returns the number of remaining ensemble members that have not been used yet.

Returns:

The number of remaining ensemble members

has_next() → bool

Returns whether there are any remaining ensemble members that have not been used yet or not.

Returns:

True, if there are any remaining ensemble members, False otherwise

predict_incrementally(x, **kwargs) → IncrementalPredictor

Returns an IncrementalPredictor that allows to obtain predictions for given query examples incrementally.

Parameters:

  • x – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_features), that stores the feature values of the query examples

  • predict_scores – True, if regression scores should be obtained, False, if binary predictions should be obtained

Returns:

The IncrementalPredictor that has been created

predict_proba_incrementally(x, **kwargs) → IncrementalPredictor

Returns an IncrementalPredictor that allows to obtain probability estimates for given query examples incrementally.

Parameters:

x – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_features), that stores the feature values of the query examples

Returns:

The IncrementalPredictor that has been created

class mlrl.common.learners.Learner

Bases: BaseEstimator, ABC

A base class for all single- or multi-label classifiers or rankers.

fit(x, y, **kwargs)

Fits a model to given training examples and their corresponding ground truth labels.

Parameters:

  • x – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_features), that stores the feature values of the training examples

  • y – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_labels), that stores the labels of the training examples according to the ground truth

Returns:

The fitted learner

predict(x, **kwargs)

Obtains and returns predictions for given query examples. If the optional keyword argument predict_scores is set to True, regression scores are obtained instead of binary predictions.

Parameters:

x – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_features), that stores the feature values of the query examples

Returns:

A numpy.ndarray or scipy.sparse matrix of shape (num_examples, num_labels), that stores the prediction for individual examples and labels

predict_proba(x, **kwargs)

Obtains and returns probability estimates for given query examples.

Parameters:

x – A numpy.ndarray or scipy.sparse matrix, shape (num_examples, num_features), that stores the feature values of the query examples

Returns:

A numpy.ndarray or scipy.sparse matrix of shape (num_examples, num_labels), that stores the probabilities for individual examples and labels

set_fit_request(*, x: bool | None | str = '$UNCHANGED$') → Learner

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in fit.

Returns

selfobject

The updated object.

set_predict_proba_request(*, x: bool | None | str = '$UNCHANGED$') → Learner

Request metadata passed to the predict_proba method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict_proba if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict_proba.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in predict_proba.

Returns

selfobject

The updated object.

set_predict_request(*, x: bool | None | str = '$UNCHANGED$') → Learner

Request metadata passed to the predict method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to predict if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to predict.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in predict.

Returns

selfobject

The updated object.

class mlrl.common.learners.NominalAttributeLearner

Bases: ABC

A base class for all single- or multi-label classifiers or rankers that natively support nominal attributes.

nominal_attribute_indices: List[int] | None = None
set_nominal_attribute_indices(indices)

Sets the indices of all nominal attributes.

Parameters:

indices – A np.ndarray or Iterable that stores the indices to be set

class mlrl.common.learners.OrdinalAttributeLearner

Bases: ABC

A base class for all single- or multi-label classifiers or rankers that natively support ordinal attributes.

ordinal_attribute_indices: List[int] | None = None
set_ordinal_attribute_indices(indices)

Sets the indices of all ordinal attributes.

Parameters:

indices – A np.ndarray or Iterable that stores the indices to be set