RuleTree.stumps.transformers package

Contents

RuleTree.stumps.transformers package#

Submodules#

RuleTree.stumps.transformers.BivariateTransformer module#

BivariateTransformer: oblique directions on the best pair of features.

class BivariateTransformer(ml_task='clf', n_orientations=10, tree_params=None)[source]#

Bases: ObliqueTransformer

Transformer into oblique directions on a pair of features: cos(a) * X_i + sin(a) * X_j for n_orientations angles a between 0 and 180 degrees.

The pair is chosen in fit: for each pair of numerical features, a depth-1 decision tree of the task is fitted on its projections, and the pair with the highest gain is kept. The splitter then chooses the angle and the threshold. The projections are computed on the features as they are: scale the data beforehand if the features have different scales.

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines the trees that choose the pair.

  • n_orientations (int, default=10) – Number of angles, evenly spaced in [0, 180) degrees.

  • tree_params (dict, default=None) – Parameters of the depth-1 decision trees that choose the pair (e.g. criterion, random_state).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_orientations)) – Coefficients of each direction: non-zero only on the chosen pair (only the chosen direction after select).

See also

HouseholderTransformer

oblique directions from a reflection of the principal component.

ObliqueDecisionTreeStumpClassifier, ObliqueDecisionTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import BivariateTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = BivariateTransformer(n_orientations=4, tree_params={"random_state": 0}).fit(X, y)
>>> transformer.transform(X).shape  # one column per angle
(150, 4)
>>> transformer.feature_id(1)  # the chosen pair of features
(0, 1)
set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → BivariateTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.HouseholderTransformer module#

HouseholderTransformer: oblique directions from the Householder reflection of the principal component.

class HouseholderTransformer(max_oblique_features=2, tau=0.0001, random_state=None)[source]#

Bases: ObliqueTransformer

Transformer into the oblique directions given by a Householder reflection: the reflection that maps the principal component of the instances of the node onto the closest axis.

The reflected axes H = I - 2 u u^T are the columns of the feature matrix: the splitter chooses the best threshold on one of them. The reflection vector u is restricted to the max_oblique_features features with the largest weights, so that each oblique direction combines at most that many features (plus the axis itself); the axes not involved in the reflection stay axis-parallel. The directions are computed on the numerical features of the node, as they are: scale the data beforehand if the features have different scales.

Parameters:

  • max_oblique_features (int, default=2) – Maximum number of features in the reflection vector.

  • tau (float, default=1e-4) – If the principal component is closer than tau to every axis, the directions are the axes (no reflection).

  • random_state (int, RandomState instance or None, default=None) – Seed of the randomized solver of the PCA, used on large nodes.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_directions)) – The columns of the reflection H (only the chosen one after select).

See also

BivariateTransformer

oblique directions on pairs of features.

ObliqueDecisionTreeStumpClassifier, ObliqueDecisionTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import HouseholderTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = HouseholderTransformer().fit(X, y)
>>> transformer.transform(X).shape  # one column per reflected axis
(150, 4)
>>> features, coefficients = transformer.combination(1)  # the reflected axis of feature 1
>>> features, [round(c, 3) for c in coefficients]
([1, 2], [-0.085, 0.857])
set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → HouseholderTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.MatrixTransformer module#

MatrixTransformer: the data used as feature matrix.

class MatrixTransformer[source]#

Bases: RuleTreeBaseTransformer

Transformer that uses the data as feature matrix: tabular data as they are, time series and images flattened into one feature per value.

The numerical and categorical columns are inferred once, on the whole data set, and cached in the tree. It has no parameters and no fitted state: it is the transformer of the decision tree stumps.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

See also

DecisionTreeStumpClassifier, DecisionTreeStumpRegressor

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import MatrixTransformer
>>> X_ts = np.zeros((10, 2, 5))  # 10 time series with 2 signals of length 5
>>> MatrixTransformer().fit(X_ts, None).transform(X_ts).shape
(10, 10)
supported_data_types = ('tabular', 'ts', 'image')#
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Compute the feature types of the (flattened) data on the whole data set.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

MatrixTransformer

transform(X)[source]#

The data: tabular data as they are, time series and images flattened.

Parameters:

X (numpy.ndarray) – Data of a supported type.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_features)

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → MatrixTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.MultiplePivotTransformer module#

MultiplePivotTransformer: which of two pivots is closer to each instance.

class MultiplePivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None, discriminative='tree', max_oblique_features=2, tau=0.0001, n_orientations=10)[source]#

Bases: PivotTransformer

Transformer of tabular data into pivot comparisons: for each pair of candidate pivots, whether the instance is closer to the second one than to the first.

The candidate pivots are selected as in PivotTransformer (with discriminative, also with oblique directions); for classification, only the pairs of pivots of different classes are compared. The feature matrix has one 0/1 column for each pair (see closer_to_second()). After the splitter has chosen a pair, only its two pivots are kept (select).

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots are selected and compared.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features.

  • k – Regression only: see PivotTransformer.

  • reg_contrast_lambda – Regression only: see PivotTransformer.

  • reg_max_thresholds – Regression only: see PivotTransformer.

  • tree_params (dict, default=None) – Parameters of the decision trees that select the discriminative pivots.

  • discriminative ({'tree', 'householder', 'bivariate'}, default='tree') – How the discriminative pivots are found (see PivotSelection).

  • max_oblique_features (int, default=2) – Householder only: maximum number of discriminative pivots of each class.

  • tau (float, default=1e-4) – Householder only: threshold of the reflection.

  • n_orientations (int, default=10) – Bivariate only: number of angles.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots (the two of the chosen pair after select), standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • pairs (list of tuple) – Pairs of candidates of the columns of the feature matrix.

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node.

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

MultiplePivotTreeStumpClassifier, MultipleObliquePivotTreeStumpClassifier

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import MultiplePivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = MultiplePivotTransformer(tree_params={"random_state": 0}).fit(X, y)
>>> len(transformer.candidate_names_), len(transformer.pairs_)  # pairs of pivots of different classes
(6, 12)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the candidate pivots of the node (see PivotTransformer.fit) and the pairs to compare.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

MultiplePivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature or there is no pair of pivots to compare.

transform(X)[source]#

Pivot comparisons of each instance for each pair of candidates (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed – 1 if the instance is closer to the second pivot of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]#

Keep only the two pivots of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

feature_id(feature)[source]#

Identifier of a pair: the indices of its two pivots in the training set.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]#

Fitted state: the two pivots and their indices, the candidates, the numerical features and the scaler.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

MultiplePivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → MultiplePivotTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.ObliquePivotTransformer module#

ObliquePivotTransformer: oblique directions on the distances from the candidate pivots.

class ObliquePivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None, oblique_split_type='householder', max_oblique_features=2, tau=0.0001, n_orientations=10)[source]#

Bases: PivotTransformer

Transformer of tabular data into oblique directions on the distances from the candidate pivots, e.g. 0.7 * P_12 - 0.3 * P_57 where P_i is the distance from the training instance i.

The candidate pivots are selected as in PivotTransformer, but the discriminative ones are the instances combined by an oblique direction (oblique_split_type, see PivotSelection). Then the distances of the instances of the node from the candidates are transformed by an oblique transformer of the same type (HouseholderTransformer or BivariateTransformer), whose directions are the columns of the feature matrix. After the splitter has chosen a column, only its direction is kept (select); the candidates are all kept.

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots and the directions are selected.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features.

  • k – Regression only: see PivotTransformer.

  • reg_contrast_lambda – Regression only: see PivotTransformer.

  • reg_max_thresholds – Regression only: see PivotTransformer.

  • tree_params (dict, default=None) – Parameters of the decision trees that select the pivots and the directions.

  • oblique_split_type ({'householder', 'bivariate'}, default='householder') – Type of the oblique directions.

  • max_oblique_features (int, default=2) – Householder only: maximum number of pivots combined by a direction.

  • tau (float, default=1e-4) – Householder only: threshold of the reflection.

  • n_orientations (int, default=10) – Bivariate only: number of angles.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots, standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • oblique (HouseholderTransformer or BivariateTransformer) – The oblique transformer of the distances from the candidates.

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node.

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

ObliquePivotTreeStumpClassifier

the stump that uses it.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import ObliquePivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = ObliquePivotTransformer(tree_params={"random_state": 0}).fit(X, y)
>>> transformer.transform(X).shape[1] == len(transformer.candidate_names_)  # one direction per candidate
True
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the candidate pivots of the node (see PivotTransformer.fit), then the oblique directions on the distances of the instances of the node from them.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ObliquePivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature, or (bivariate) there are fewer than two candidates.

transform(X)[source]#

Projection of the distances from the candidates on the oblique directions (on the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_directions)

select(feature)[source]#

Keep only the chosen direction.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the projection on the only direction kept.

Return type:

int

combination(feature)[source]#

Pivots and coefficients of a direction: the column is sum(c * P_i).

Parameters:

feature (int) – Column of the feature matrix.

Returns:

  • pivots (list of int) – Indices in the training set of the pivots with a non-zero coefficient.

  • coefficients (list of float) – Their coefficients.

feature_id(feature)[source]#

Identifier of a direction: the indices of the pivots it combines.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]#

Fitted state: the candidate pivots and their indices, the numerical features, the scaler and the state of the oblique transformer.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ObliquePivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ObliquePivotTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.ObliqueTransformer module#

ObliqueTransformer: linear combinations of the numerical features, the base of the oblique transformers.

class ObliqueTransformer[source]#

Bases: RuleTreeBaseTransformer, ABC

Base class of the transformers into linear combinations of the numerical features (oblique directions): each column of the feature matrix is X[:, numerical] @ coefficients_[:, j], so a threshold on it is an oblique hyperplane, e.g. 0.8 * X_2 - 0.6 * X_3 <= 1.5.

The subclasses choose the directions in fit() (_fit_directions). After the splitter has chosen a column, only its direction is kept (select).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix (all of them).

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data, the inputs of the combinations.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_directions)) – Coefficients of each direction (only the chosen one after select).

See also

HouseholderTransformer, BivariateTransformer

supported_data_types = ('tabular',)#
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Choose the oblique directions on the numerical features of the instances in the node.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ObliqueTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature.

transform(X)[source]#

Projection of the instances on the oblique directions (on the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_directions)

select(feature)[source]#

Keep only the chosen direction.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the projection on the only direction kept.

Return type:

int

combination(feature: int) → tuple[list, list][source]#

Features and coefficients of a direction: the column is sum(c * X[:, f]).

Parameters:

feature (int) – Column of the feature matrix.

Returns:

  • features (list of int) – Columns of the data with a non-zero coefficient.

  • coefficients (list of float) – Their coefficients.

oblique_features() → list[source]#

Columns of the data combined by the oblique directions, i.e. the ones with more than one non-zero coefficient (the axis-parallel directions are ignored). Used by the oblique pivot stumps to choose the discriminative pivots.

Returns:

features – Sorted columns; empty if every direction is parallel to an axis.

Return type:

list of int

feature_id(feature)[source]#

Identifier of a direction: the columns of the data it combines.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]#

Fitted state: the numerical features and the coefficients of the directions.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ObliqueTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ObliqueTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.PartialPivotTransformer module#

PartialPivotTransformer: distances from partial pivots (instances restricted to subsets of the features).

class PartialPivotTransformer(n_shapelets=8, n_ts_for_selection=100, n_features_strategy=2, selection='random', distance='euclidean', use_combination=True, random_state=42, n_jobs=1)[source]#

Bases: RuleTreeBaseTransformer

Transformer of tabular data into the distances from partial pivots, instances of the node restricted to subsets of the features.

The distance from a partial pivot is computed only on its features. After the splitter has chosen a column, only the chosen pivot is kept (select), and the splitter is fitted again on its distances (refit_after_select).

Parameters:

  • n_shapelets (int or numpy.inf, default=8) – Number of partial pivots selected at each node (numpy.inf with selection=’all’).

  • n_ts_for_selection (int, float or numpy.inf, default=100) – Number (int) or fraction (float) of the instances of the node used to select the pivots.

  • n_features_strategy (int, float, tuple or str, default=2) – Number of features of each partial pivot: an int, a fraction of the features (float), a range (min, max), or chosen from the feature importances of a random forest (‘elbow’, ‘drop’, ‘new’) or iteratively with depth-1 trees (‘iterative’).

  • selection ({'random', 'cluster', 'all'}, default='random') – How the pivots are selected among the candidates: at random, the instances closest to the k-means centroids, or all of them.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between an instance and a partial pivot, on the features of the pivot. The data are used as they are: scale them beforehand if the features have different scales.

  • use_combination (bool, default=True) – With the strategies based on feature importances, whether to use all the combinations of the important features or only the set of all of them.

  • random_state (int, default=42) – Seed of the random choices.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • st (TabularShapelets) – The fitted transform, with the partial pivots.

See also

PartialPivotTreeStumpClassifier

the stump that uses it.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import PartialPivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> PartialPivotTransformer(n_shapelets=4, random_state=0).fit(X, y).transform(X).shape
(150, 4)
supported_data_types = ('tabular',)#
refit_after_select = True#
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the partial pivots among the instances in the node.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

PartialPivotTransformer

Warns:

Warning – If sample_weight is given: it is not supported and ignored.

transform(X)[source]#

Distance of each instance from each partial pivot (from the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_pivots)

select(feature)[source]#

Keep only the chosen partial pivot.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the distance from the only partial pivot kept.

Return type:

int

get_state()[source]#

Fitted state: the partial pivots.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PartialPivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PartialPivotTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.PartialProximityTransformer module#

PartialProximityTransformer: which of two partial pivots is closer to each instance.

class PartialProximityTransformer(n_shapelets=8, n_ts_for_selection=100, n_features_strategy=2, selection='random', distance='euclidean', proximity_on_same_features=True, use_combination=True, random_state=42, n_jobs=1)[source]#

Bases: PartialPivotTransformer

Transformer of tabular data into proximity comparisons: for each pair of partial pivots (instances of the node restricted to a few features), whether the instance is closer to the second one than to the first.

The partial pivots are selected as in PartialPivotTransformer; the feature matrix has one 0/1 column for each pair of them (see closer_to_second()). After the splitter has chosen a pair, only its two pivots are kept (select).

Parameters:

  • n_shapelets (int or numpy.inf, default=8) – Number of partial pivots selected at each node (numpy.inf with selection=’all’).

  • n_ts_for_selection (int, float or numpy.inf, default=100) – Number (int) or fraction (float) of the instances of the node used to select the pivots.

  • n_features_strategy (int, float, tuple or str, default=2) – Number of features of each partial pivot (see PartialPivotTransformer).

  • selection ({'random', 'cluster', 'all'}, default='random') – How the pivots are selected among the candidates.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between an instance and a partial pivot, on the features of the pivot. The data are used as they are: scale them beforehand if the features have different scales.

  • proximity_on_same_features (bool, default=True) – Whether to compare only the pivots on the same features, whose distances are comparable.

  • use_combination (bool, default=True) – With the strategies based on feature importances, whether to use all the combinations of the important features or only the set of all of them.

  • random_state (int, default=42) – Seed of the random choices.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • st (TabularShapelets) – The fitted transform (only the two pivots of the chosen pair after select).

  • pairs (list of tuple) – Pairs of pivots of the columns of the feature matrix.

See also

PartialProximityTreeStumpClassifier

the stump that uses it.

ProximityTransformer

the same comparisons with shapelets, for time series.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import PartialProximityTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = PartialProximityTransformer(n_shapelets=4, random_state=0).fit(X, y)
>>> transformer.transform(X).shape[1] == len(transformer.pairs_)
True
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the partial pivots among the instances in the node, and the pairs to compare.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Not supported: ignored with a warning.

Returns:

self

Return type:

PartialProximityTransformer

Raises:

NoSplitFoundWarning – If there is no pair of pivots to compare.

transform(X)[source]#

Proximity comparisons of each instance for each pair of pivots (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed – 1 if the instance is closer to the second pivot of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]#

Keep only the two pivots of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

get_state()[source]#

Fitted state: the partial pivots and the pairs.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PartialProximityTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PartialProximityTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.PivotTransformer module#

PivotTransformer: distances from candidate pivots, and the cache of the pivot stumps.

class PivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None)[source]#

Bases: RuleTreeBaseTransformer

Transformer into the distances from candidate pivots, instances of the node that describe a class (medoids) or separate the classes.

The candidates are selected among the instances of the node, on the standardized numerical features; the scaler and the distance matrix of the whole data set are computed once and cached in the tree. After the splitter has chosen a column, only the chosen pivot is kept (select).

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots are selected.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features: any metric of sklearn.metrics.pairwise_distances.

  • k (int, default=None) – Regression only: number of nearest and farthest instances used to measure how well a candidate pivot contrasts close and distant instances. None for the square root of the number of instances of the node (between 5 and n - 1).

  • reg_contrast_lambda (float, default=0.2) – Regression only: weight of the contrast with respect to the gain of the split when the descriptive pivot is selected.

  • reg_max_thresholds (int, default=None) – Regression only: maximum number of thresholds tested on the distances from each candidate pivot (quantiles). None for max(256, sqrt(n)).

  • tree_params (dict, default=None) – Parameters of the decision trees that select the discriminative pivots.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots (only the chosen one after select), standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • candidate_labels (numpy.ndarray of shape (n_candidates,)) – Target of the candidate pivots (not saved by get_state).

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node (all of them, also after select).

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

PivotTreeStumpClassifier, PivotTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree import RuleTreeClassifier
>>> from RuleTree.stumps.Stump import Stump
>>> from RuleTree.stumps.splitters import ClassificationSplitter
>>> from RuleTree.stumps.transformers import PivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = PivotTransformer().fit(X, y)
>>> transformer.transform(X[:2]).shape  # distances from 6 candidate pivots
(2, 6)
>>> model = RuleTreeClassifier(max_depth=2, base_stumps=Stump(PivotTransformer(), ClassificationSplitter()))
>>> model = model.fit(X, y)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the candidate pivots of the node (see PivotSelection), on the standardized numerical features. The scaler and the distance matrix of the whole data set are taken from the cache.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

PivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature.

transform(X)[source]#

Distances of the instances from the candidate pivots (from the chosen pivot, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_candidates)

select(feature)[source]#

Keep only the chosen pivot.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the distance from the only pivot kept.

Return type:

int

feature_id(feature)[source]#

Identifier of a candidate pivot: the index of the instance in the training set.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

str

get_state()[source]#

Fitted state: the pivot, its index, the candidate pivots, the numerical features and the scaler.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PivotTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

scaler_state(scaler: StandardScaler) → dict[source]#

JSON-friendly state of a fitted StandardScaler, restored by scaler_from_state.

Parameters:

scaler (StandardScaler) – Fitted scaler.

Returns:

state

Return type:

dict

scaler_from_state(state: dict) → StandardScaler[source]#

Fitted StandardScaler from the state created by scaler_state.

Parameters:

state (dict) – State of the scaler.

Returns:

scaler

Return type:

StandardScaler

RuleTree.stumps.transformers.ProximityTransformer module#

ProximityTransformer: which of two shapelets is closer to each time series.

closer_to_second(distances: ndarray, pairs: list) → ndarray[source]#

For each pair (i, j) of columns of distances, 1 where distances[:, i] > distances[:, j] (the instance is closer to the second one), 0 otherwise.

A split column <= t with 0 <= t < 1 sends left the instances closer to the first one (or at the same distance from both).

Parameters:

  • distances (numpy.ndarray of shape (n_samples, n_references)) – Distance of each instance from each reference (shapelet, pivot, …).

  • pairs (list of tuple) – Pairs of columns.

Returns:

comparisons

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers.ProximityTransformer import closer_to_second
>>> closer_to_second(np.array([[1.0, 2.0], [3.0, 0.5]]), [(0, 1)])
array([[0.],
       [1.]])
class ProximityTransformer(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_clf', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1)[source]#

Bases: ShapeletTransformer

Transformer of time series into proximity comparisons: for each pair of shapelets, whether the time series is closer to the second one than to the first.

The shapelets are selected as in ShapeletTransformer; the feature matrix has one 0/1 column for each pair of them (see closer_to_second()), so that a split sends left the time series closer to the first shapelet of a pair. After the splitter has chosen a pair, only its two shapelets are kept (select).

Parameters:

  • n_shapelets (int, default=8) – Number of shapelets selected at each node (at least 2).

  • n_shapelets_for_selection (int, numpy.inf or 'stratified', default=500) – Number of candidate subsequences, among which the shapelets are selected.

  • n_ts_for_selection_per_class (int or numpy.inf, default=100) – Number of time series of each class from which the candidates are extracted.

  • sliding_window (int, default=50) – Length of the shapelets.

  • selection ({'random', 'mi_clf', 'mi_reg', 'cluster'}, default='mi_clf') – How the shapelets are selected among the candidates.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between a shapelet and a subsequence.

  • mi_n_neighbors (int, default=100) – Number of neighbors used to estimate the mutual information.

  • random_state (int, default=42) – Seed of the random choices of the candidates and of the shapelets.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • st (Shapelets) – The fitted shapelet transform (only the two shapelets of the chosen pair after select).

  • pairs (list of tuple) – Pairs of shapelets of the columns of the feature matrix.

See also

ProximityTreeStumpClassifier, ProximityTreeStumpRegressor

PartialProximityTransformer

the same comparisons with partial pivots, for tabular data.

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import ProximityTransformer
>>> rng = np.random.default_rng(0)
>>> X_ts, y = rng.normal(size=(20, 1, 30)), rng.integers(0, 2, size=20)
>>> transformer = ProximityTransformer(n_shapelets=4, sliding_window=5, selection="random").fit(X_ts, y)
>>> transformer.transform(X_ts).shape  # one column for each of the 6 pairs of shapelets
(20, 6)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the shapelets among the subsequences of the time series in the node.

Parameters:

  • X (numpy.ndarray) – Time series, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Not supported: must be None.

Returns:

self

Return type:

ProximityTransformer

Raises:
transform(X)[source]#

Proximity comparisons of each time series for each pair of shapelets (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Time series, of shape (n_samples, n_signals, length).

Returns:

X_transformed – 1 if the series is closer to the second shapelet of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]#

Keep only the two shapelets of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

get_state()[source]#

Fitted state: the shapelets and the pairs.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ProximityTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ProximityTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

RuleTree.stumps.transformers.ShapeletTransformer module#

ShapeletTransformer: distances of time series from shapelets.

class ShapeletTransformer(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_clf', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1)[source]#

Bases: RuleTreeBaseTransformer

Transformer of time series into their distances from shapelets, subsequences selected among the ones of the time series in the node.

The distance of a time series from a shapelet is the smallest distance between the shapelet and the subsequences of the series of the same length. After the splitter has chosen a column, only the chosen shapelet is kept (select).

Parameters:

  • n_shapelets (int, default=8) – Number of shapelets selected at each node.

  • n_shapelets_for_selection (int, numpy.inf or 'stratified', default=500) – Number of candidate subsequences extracted from the time series, among which the shapelets are selected. ‘stratified’ draws them according to the class distribution.

  • n_ts_for_selection_per_class (int or numpy.inf, default=100) – Number of time series of each class from which the candidates are extracted.

  • sliding_window (int, default=50) – Length of the shapelets.

  • selection ({'random', 'mi_clf', 'mi_reg', 'cluster'}, default='mi_clf') – How the shapelets are selected among the candidates: at random, by mutual information with the target, or as the medoids of a k-medoids clustering (requires scikit-learn-extra).

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between a shapelet and a subsequence; the distance of a time series from a shapelet is the minimum over the positions of the shapelet.

  • mi_n_neighbors (int, default=100) – Number of neighbors used to estimate the mutual information.

  • random_state (int, default=42) – Seed of the random choices of the candidates and of the shapelets.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • st (Shapelets) – The fitted shapelet transform, with the selected shapelets.

See also

ShapeletTreeStumpClassifier, ShapeletTreeStumpRegressor

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import ShapeletTransformer
>>> rng = np.random.default_rng(0)
>>> X_ts, y = rng.normal(size=(20, 1, 30)), rng.integers(0, 2, size=20)
>>> transformer = ShapeletTransformer(n_shapelets=3, sliding_window=5, selection="random").fit(X_ts, y)
>>> transformer.transform(X_ts).shape
(20, 3)
supported_data_types = ('ts',)#
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]#

Select the shapelets among the subsequences of the time series in the node.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ShapeletTransformer

Raises:

ValueError – If sample_weight is given.

transform(X)[source]#

Distance of each time series from each shapelet.

Parameters:

X (numpy.ndarray) – Time series, of shape (n_samples, 1, length).

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_shapelets)

get_state()[source]#

Fitted state: the shapelets.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]#

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ShapeletTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ShapeletTransformer#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

Module contents#

class MatrixTransformer[source]

Bases: RuleTreeBaseTransformer

Transformer that uses the data as feature matrix: tabular data as they are, time series and images flattened into one feature per value.

The numerical and categorical columns are inferred once, on the whole data set, and cached in the tree. It has no parameters and no fitted state: it is the transformer of the decision tree stumps.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

See also

DecisionTreeStumpClassifier, DecisionTreeStumpRegressor

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import MatrixTransformer
>>> X_ts = np.zeros((10, 2, 5))  # 10 time series with 2 signals of length 5
>>> MatrixTransformer().fit(X_ts, None).transform(X_ts).shape
(10, 10)
supported_data_types = ('tabular', 'ts', 'image')
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Compute the feature types of the (flattened) data on the whole data set.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

MatrixTransformer

transform(X)[source]

The data: tabular data as they are, time series and images flattened.

Parameters:

X (numpy.ndarray) – Data of a supported type.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_features)

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → MatrixTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class PivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None)[source]

Bases: RuleTreeBaseTransformer

Transformer into the distances from candidate pivots, instances of the node that describe a class (medoids) or separate the classes.

The candidates are selected among the instances of the node, on the standardized numerical features; the scaler and the distance matrix of the whole data set are computed once and cached in the tree. After the splitter has chosen a column, only the chosen pivot is kept (select).

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots are selected.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features: any metric of sklearn.metrics.pairwise_distances.

  • k (int, default=None) – Regression only: number of nearest and farthest instances used to measure how well a candidate pivot contrasts close and distant instances. None for the square root of the number of instances of the node (between 5 and n - 1).

  • reg_contrast_lambda (float, default=0.2) – Regression only: weight of the contrast with respect to the gain of the split when the descriptive pivot is selected.

  • reg_max_thresholds (int, default=None) – Regression only: maximum number of thresholds tested on the distances from each candidate pivot (quantiles). None for max(256, sqrt(n)).

  • tree_params (dict, default=None) – Parameters of the decision trees that select the discriminative pivots.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots (only the chosen one after select), standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • candidate_labels (numpy.ndarray of shape (n_candidates,)) – Target of the candidate pivots (not saved by get_state).

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node (all of them, also after select).

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

PivotTreeStumpClassifier, PivotTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree import RuleTreeClassifier
>>> from RuleTree.stumps.Stump import Stump
>>> from RuleTree.stumps.splitters import ClassificationSplitter
>>> from RuleTree.stumps.transformers import PivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = PivotTransformer().fit(X, y)
>>> transformer.transform(X[:2]).shape  # distances from 6 candidate pivots
(2, 6)
>>> model = RuleTreeClassifier(max_depth=2, base_stumps=Stump(PivotTransformer(), ClassificationSplitter()))
>>> model = model.fit(X, y)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the candidate pivots of the node (see PivotSelection), on the standardized numerical features. The scaler and the distance matrix of the whole data set are taken from the cache.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

PivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature.

transform(X)[source]

Distances of the instances from the candidate pivots (from the chosen pivot, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_candidates)

select(feature)[source]

Keep only the chosen pivot.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the distance from the only pivot kept.

Return type:

int

feature_id(feature)[source]

Identifier of a candidate pivot: the index of the instance in the training set.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

str

get_state()[source]

Fitted state: the pivot, its index, the candidate pivots, the numerical features and the scaler.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PivotTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class ShapeletTransformer(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_clf', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1)[source]

Bases: RuleTreeBaseTransformer

Transformer of time series into their distances from shapelets, subsequences selected among the ones of the time series in the node.

The distance of a time series from a shapelet is the smallest distance between the shapelet and the subsequences of the series of the same length. After the splitter has chosen a column, only the chosen shapelet is kept (select).

Parameters:

  • n_shapelets (int, default=8) – Number of shapelets selected at each node.

  • n_shapelets_for_selection (int, numpy.inf or 'stratified', default=500) – Number of candidate subsequences extracted from the time series, among which the shapelets are selected. ‘stratified’ draws them according to the class distribution.

  • n_ts_for_selection_per_class (int or numpy.inf, default=100) – Number of time series of each class from which the candidates are extracted.

  • sliding_window (int, default=50) – Length of the shapelets.

  • selection ({'random', 'mi_clf', 'mi_reg', 'cluster'}, default='mi_clf') – How the shapelets are selected among the candidates: at random, by mutual information with the target, or as the medoids of a k-medoids clustering (requires scikit-learn-extra).

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between a shapelet and a subsequence; the distance of a time series from a shapelet is the minimum over the positions of the shapelet.

  • mi_n_neighbors (int, default=100) – Number of neighbors used to estimate the mutual information.

  • random_state (int, default=42) – Seed of the random choices of the candidates and of the shapelets.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • st (Shapelets) – The fitted shapelet transform, with the selected shapelets.

See also

ShapeletTreeStumpClassifier, ShapeletTreeStumpRegressor

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import ShapeletTransformer
>>> rng = np.random.default_rng(0)
>>> X_ts, y = rng.normal(size=(20, 1, 30)), rng.integers(0, 2, size=20)
>>> transformer = ShapeletTransformer(n_shapelets=3, sliding_window=5, selection="random").fit(X_ts, y)
>>> transformer.transform(X_ts).shape
(20, 3)
supported_data_types = ('ts',)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the shapelets among the subsequences of the time series in the node.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ShapeletTransformer

Raises:

ValueError – If sample_weight is given.

transform(X)[source]

Distance of each time series from each shapelet.

Parameters:

X (numpy.ndarray) – Time series, of shape (n_samples, 1, length).

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_shapelets)

get_state()[source]

Fitted state: the shapelets.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ShapeletTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ShapeletTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class PartialPivotTransformer(n_shapelets=8, n_ts_for_selection=100, n_features_strategy=2, selection='random', distance='euclidean', use_combination=True, random_state=42, n_jobs=1)[source]

Bases: RuleTreeBaseTransformer

Transformer of tabular data into the distances from partial pivots, instances of the node restricted to subsets of the features.

The distance from a partial pivot is computed only on its features. After the splitter has chosen a column, only the chosen pivot is kept (select), and the splitter is fitted again on its distances (refit_after_select).

Parameters:

  • n_shapelets (int or numpy.inf, default=8) – Number of partial pivots selected at each node (numpy.inf with selection=’all’).

  • n_ts_for_selection (int, float or numpy.inf, default=100) – Number (int) or fraction (float) of the instances of the node used to select the pivots.

  • n_features_strategy (int, float, tuple or str, default=2) – Number of features of each partial pivot: an int, a fraction of the features (float), a range (min, max), or chosen from the feature importances of a random forest (‘elbow’, ‘drop’, ‘new’) or iteratively with depth-1 trees (‘iterative’).

  • selection ({'random', 'cluster', 'all'}, default='random') – How the pivots are selected among the candidates: at random, the instances closest to the k-means centroids, or all of them.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between an instance and a partial pivot, on the features of the pivot. The data are used as they are: scale them beforehand if the features have different scales.

  • use_combination (bool, default=True) – With the strategies based on feature importances, whether to use all the combinations of the important features or only the set of all of them.

  • random_state (int, default=42) – Seed of the random choices.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix.

  • st (TabularShapelets) – The fitted transform, with the partial pivots.

See also

PartialPivotTreeStumpClassifier

the stump that uses it.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import PartialPivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> PartialPivotTransformer(n_shapelets=4, random_state=0).fit(X, y).transform(X).shape
(150, 4)
supported_data_types = ('tabular',)
refit_after_select = True
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the partial pivots among the instances in the node.

Parameters:

  • X (numpy.ndarray) – Data of the transformer’s type, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

PartialPivotTransformer

Warns:

Warning – If sample_weight is given: it is not supported and ignored.

transform(X)[source]

Distance of each instance from each partial pivot (from the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_pivots)

select(feature)[source]

Keep only the chosen partial pivot.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the distance from the only partial pivot kept.

Return type:

int

get_state()[source]

Fitted state: the partial pivots.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PartialPivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PartialPivotTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class ObliqueTransformer[source]

Bases: RuleTreeBaseTransformer, ABC

Base class of the transformers into linear combinations of the numerical features (oblique directions): each column of the feature matrix is X[:, numerical] @ coefficients_[:, j], so a threshold on it is an oblique hyperplane, e.g. 0.8 * X_2 - 0.6 * X_3 <= 1.5.

The subclasses choose the directions in fit() (_fit_directions). After the splitter has chosen a column, only its direction is kept (select).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix (all of them).

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data, the inputs of the combinations.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_directions)) – Coefficients of each direction (only the chosen one after select).

See also

HouseholderTransformer, BivariateTransformer

supported_data_types = ('tabular',)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Choose the oblique directions on the numerical features of the instances in the node.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ObliqueTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature.

transform(X)[source]

Projection of the instances on the oblique directions (on the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_directions)

select(feature)[source]

Keep only the chosen direction.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the projection on the only direction kept.

Return type:

int

combination(feature: int) → tuple[list, list][source]

Features and coefficients of a direction: the column is sum(c * X[:, f]).

Parameters:

feature (int) – Column of the feature matrix.

Returns:

  • features (list of int) – Columns of the data with a non-zero coefficient.

  • coefficients (list of float) – Their coefficients.

oblique_features() → list[source]

Columns of the data combined by the oblique directions, i.e. the ones with more than one non-zero coefficient (the axis-parallel directions are ignored). Used by the oblique pivot stumps to choose the discriminative pivots.

Returns:

features – Sorted columns; empty if every direction is parallel to an axis.

Return type:

list of int

feature_id(feature)[source]

Identifier of a direction: the columns of the data it combines.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]

Fitted state: the numerical features and the coefficients of the directions.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ObliqueTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ObliqueTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class HouseholderTransformer(max_oblique_features=2, tau=0.0001, random_state=None)[source]

Bases: ObliqueTransformer

Transformer into the oblique directions given by a Householder reflection: the reflection that maps the principal component of the instances of the node onto the closest axis.

The reflected axes H = I - 2 u u^T are the columns of the feature matrix: the splitter chooses the best threshold on one of them. The reflection vector u is restricted to the max_oblique_features features with the largest weights, so that each oblique direction combines at most that many features (plus the axis itself); the axes not involved in the reflection stay axis-parallel. The directions are computed on the numerical features of the node, as they are: scale the data beforehand if the features have different scales.

Parameters:

  • max_oblique_features (int, default=2) – Maximum number of features in the reflection vector.

  • tau (float, default=1e-4) – If the principal component is closer than tau to every axis, the directions are the axes (no reflection).

  • random_state (int, RandomState instance or None, default=None) – Seed of the randomized solver of the PCA, used on large nodes.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_directions)) – The columns of the reflection H (only the chosen one after select).

See also

BivariateTransformer

oblique directions on pairs of features.

ObliqueDecisionTreeStumpClassifier, ObliqueDecisionTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import HouseholderTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = HouseholderTransformer().fit(X, y)
>>> transformer.transform(X).shape  # one column per reflected axis
(150, 4)
>>> features, coefficients = transformer.combination(1)  # the reflected axis of feature 1
>>> features, [round(c, 3) for c in coefficients]
([1, 2], [-0.085, 0.857])
set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → HouseholderTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class BivariateTransformer(ml_task='clf', n_orientations=10, tree_params=None)[source]

Bases: ObliqueTransformer

Transformer into oblique directions on a pair of features: cos(a) * X_i + sin(a) * X_j for n_orientations angles a between 0 and 180 degrees.

The pair is chosen in fit: for each pair of numerical features, a depth-1 decision tree of the task is fitted on its projections, and the pair with the highest gain is kept. The splitter then chooses the angle and the threshold. The projections are computed on the features as they are: scale the data beforehand if the features have different scales.

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines the trees that choose the pair.

  • n_orientations (int, default=10) – Number of angles, evenly spaced in [0, 180) degrees.

  • tree_params (dict, default=None) – Parameters of the depth-1 decision trees that choose the pair (e.g. criterion, random_state).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • num_pre_transformed (list of int) – Numerical columns of the data.

  • coefficients (numpy.ndarray of shape (n_numerical_features, n_orientations)) – Coefficients of each direction: non-zero only on the chosen pair (only the chosen direction after select).

See also

HouseholderTransformer

oblique directions from a reflection of the principal component.

ObliqueDecisionTreeStumpClassifier, ObliqueDecisionTreeStumpRegressor

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import BivariateTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = BivariateTransformer(n_orientations=4, tree_params={"random_state": 0}).fit(X, y)
>>> transformer.transform(X).shape  # one column per angle
(150, 4)
>>> transformer.feature_id(1)  # the chosen pair of features
(0, 1)
set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → BivariateTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class ProximityTransformer(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_clf', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1)[source]

Bases: ShapeletTransformer

Transformer of time series into proximity comparisons: for each pair of shapelets, whether the time series is closer to the second one than to the first.

The shapelets are selected as in ShapeletTransformer; the feature matrix has one 0/1 column for each pair of them (see closer_to_second()), so that a split sends left the time series closer to the first shapelet of a pair. After the splitter has chosen a pair, only its two shapelets are kept (select).

Parameters:

  • n_shapelets (int, default=8) – Number of shapelets selected at each node (at least 2).

  • n_shapelets_for_selection (int, numpy.inf or 'stratified', default=500) – Number of candidate subsequences, among which the shapelets are selected.

  • n_ts_for_selection_per_class (int or numpy.inf, default=100) – Number of time series of each class from which the candidates are extracted.

  • sliding_window (int, default=50) – Length of the shapelets.

  • selection ({'random', 'mi_clf', 'mi_reg', 'cluster'}, default='mi_clf') – How the shapelets are selected among the candidates.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between a shapelet and a subsequence.

  • mi_n_neighbors (int, default=100) – Number of neighbors used to estimate the mutual information.

  • random_state (int, default=42) – Seed of the random choices of the candidates and of the shapelets.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • st (Shapelets) – The fitted shapelet transform (only the two shapelets of the chosen pair after select).

  • pairs (list of tuple) – Pairs of shapelets of the columns of the feature matrix.

See also

ProximityTreeStumpClassifier, ProximityTreeStumpRegressor

PartialProximityTransformer

the same comparisons with partial pivots, for tabular data.

Examples

>>> import numpy as np
>>> from RuleTree.stumps.transformers import ProximityTransformer
>>> rng = np.random.default_rng(0)
>>> X_ts, y = rng.normal(size=(20, 1, 30)), rng.integers(0, 2, size=20)
>>> transformer = ProximityTransformer(n_shapelets=4, sliding_window=5, selection="random").fit(X_ts, y)
>>> transformer.transform(X_ts).shape  # one column for each of the 6 pairs of shapelets
(20, 6)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the shapelets among the subsequences of the time series in the node.

Parameters:

  • X (numpy.ndarray) – Time series, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Not supported: must be None.

Returns:

self

Return type:

ProximityTransformer

Raises:
transform(X)[source]

Proximity comparisons of each time series for each pair of shapelets (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Time series, of shape (n_samples, n_signals, length).

Returns:

X_transformed – 1 if the series is closer to the second shapelet of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]

Keep only the two shapelets of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

get_state()[source]

Fitted state: the shapelets and the pairs.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ProximityTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ProximityTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class PartialProximityTransformer(n_shapelets=8, n_ts_for_selection=100, n_features_strategy=2, selection='random', distance='euclidean', proximity_on_same_features=True, use_combination=True, random_state=42, n_jobs=1)[source]

Bases: PartialPivotTransformer

Transformer of tabular data into proximity comparisons: for each pair of partial pivots (instances of the node restricted to a few features), whether the instance is closer to the second one than to the first.

The partial pivots are selected as in PartialPivotTransformer; the feature matrix has one 0/1 column for each pair of them (see closer_to_second()). After the splitter has chosen a pair, only its two pivots are kept (select).

Parameters:

  • n_shapelets (int or numpy.inf, default=8) – Number of partial pivots selected at each node (numpy.inf with selection=’all’).

  • n_ts_for_selection (int, float or numpy.inf, default=100) – Number (int) or fraction (float) of the instances of the node used to select the pivots.

  • n_features_strategy (int, float, tuple or str, default=2) – Number of features of each partial pivot (see PartialPivotTransformer).

  • selection ({'random', 'cluster', 'all'}, default='random') – How the pivots are selected among the candidates.

  • distance ({'euclidean', 'sqeuclidean', 'cosine', 'cityblock'} or callable, default='euclidean') – Distance between an instance and a partial pivot, on the features of the pivot. The data are used as they are: scale them beforehand if the features have different scales.

  • proximity_on_same_features (bool, default=True) – Whether to compare only the pivots on the same features, whose distances are comparable.

  • use_combination (bool, default=True) – With the strategies based on feature importances, whether to use all the combinations of the important features or only the set of all of them.

  • random_state (int, default=42) – Seed of the random choices.

  • n_jobs (int, default=1) – Number of threads used to compute the distances (-1: all the CPUs).

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • st (TabularShapelets) – The fitted transform (only the two pivots of the chosen pair after select).

  • pairs (list of tuple) – Pairs of pivots of the columns of the feature matrix.

See also

PartialProximityTreeStumpClassifier

the stump that uses it.

ProximityTransformer

the same comparisons with shapelets, for time series.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import PartialProximityTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = PartialProximityTransformer(n_shapelets=4, random_state=0).fit(X, y)
>>> transformer.transform(X).shape[1] == len(transformer.pairs_)
True
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the partial pivots among the instances in the node, and the pairs to compare.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Not supported: ignored with a warning.

Returns:

self

Return type:

PartialProximityTransformer

Raises:

NoSplitFoundWarning – If there is no pair of pivots to compare.

transform(X)[source]

Proximity comparisons of each instance for each pair of pivots (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed – 1 if the instance is closer to the second pivot of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]

Keep only the two pivots of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

get_state()[source]

Fitted state: the partial pivots and the pairs.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

PartialProximityTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → PartialProximityTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class MultiplePivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None, discriminative='tree', max_oblique_features=2, tau=0.0001, n_orientations=10)[source]

Bases: PivotTransformer

Transformer of tabular data into pivot comparisons: for each pair of candidate pivots, whether the instance is closer to the second one than to the first.

The candidate pivots are selected as in PivotTransformer (with discriminative, also with oblique directions); for classification, only the pairs of pivots of different classes are compared. The feature matrix has one 0/1 column for each pair (see closer_to_second()). After the splitter has chosen a pair, only its two pivots are kept (select).

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots are selected and compared.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features.

  • k – Regression only: see PivotTransformer.

  • reg_contrast_lambda – Regression only: see PivotTransformer.

  • reg_max_thresholds – Regression only: see PivotTransformer.

  • tree_params (dict, default=None) – Parameters of the decision trees that select the discriminative pivots.

  • discriminative ({'tree', 'householder', 'bivariate'}, default='tree') – How the discriminative pivots are found (see PivotSelection).

  • max_oblique_features (int, default=2) – Householder only: maximum number of discriminative pivots of each class.

  • tau (float, default=1e-4) – Householder only: threshold of the reflection.

  • n_orientations (int, default=10) – Bivariate only: number of angles.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots (the two of the chosen pair after select), standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • pairs (list of tuple) – Pairs of candidates of the columns of the feature matrix.

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node.

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

MultiplePivotTreeStumpClassifier, MultipleObliquePivotTreeStumpClassifier

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import MultiplePivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = MultiplePivotTransformer(tree_params={"random_state": 0}).fit(X, y)
>>> len(transformer.candidate_names_), len(transformer.pairs_)  # pairs of pivots of different classes
(6, 12)
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the candidate pivots of the node (see PivotTransformer.fit) and the pairs to compare.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

MultiplePivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature or there is no pair of pivots to compare.

transform(X)[source]

Pivot comparisons of each instance for each pair of candidates (for the chosen pair, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed – 1 if the instance is closer to the second pivot of the pair, 0 otherwise.

Return type:

numpy.ndarray of shape (n_samples, n_pairs)

select(feature)[source]

Keep only the two pivots of the chosen pair.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the comparison of the only pair kept.

Return type:

int

feature_id(feature)[source]

Identifier of a pair: the indices of its two pivots in the training set.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]

Fitted state: the two pivots and their indices, the candidates, the numerical features and the scaler.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

MultiplePivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → MultiplePivotTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

class ObliquePivotTransformer(ml_task='clf', distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, tree_params=None, oblique_split_type='householder', max_oblique_features=2, tau=0.0001, n_orientations=10)[source]

Bases: PivotTransformer

Transformer of tabular data into oblique directions on the distances from the candidate pivots, e.g. 0.7 * P_12 - 0.3 * P_57 where P_i is the distance from the training instance i.

The candidate pivots are selected as in PivotTransformer, but the discriminative ones are the instances combined by an oblique direction (oblique_split_type, see PivotSelection). Then the distances of the instances of the node from the candidates are transformed by an oblique transformer of the same type (HouseholderTransformer or BivariateTransformer), whose directions are the columns of the feature matrix. After the splitter has chosen a column, only its direction is kept (select); the candidates are all kept.

Parameters:

  • ml_task ({MODEL_TYPE_CLF, MODEL_TYPE_REG}, default=MODEL_TYPE_CLF) – Task of the stump, which determines how the pivots and the directions are selected.

  • distance_measure (str or callable, default='euclidean') – Distance between the instances, computed on the standardized numerical features.

  • k – Regression only: see PivotTransformer.

  • reg_contrast_lambda – Regression only: see PivotTransformer.

  • reg_max_thresholds – Regression only: see PivotTransformer.

  • tree_params (dict, default=None) – Parameters of the decision trees that select the pivots and the directions.

  • oblique_split_type ({'householder', 'bivariate'}, default='householder') – Type of the oblique directions.

  • max_oblique_features (int, default=2) – Householder only: maximum number of pivots combined by a direction.

  • tau (float, default=1e-4) – Householder only: threshold of the reflection.

  • n_orientations (int, default=10) – Bivariate only: number of angles.

Variables:

  • numerical (list of int) – Numerical columns of the feature matrix.

  • categorical (list of int) – Categorical columns of the feature matrix (none).

  • candidates (numpy.ndarray of shape (n_candidates, n_numerical_features)) – The candidate pivots, standardized.

  • candidate_names (numpy.ndarray of shape (n_candidates,)) – Indices of the candidate pivots in the training set.

  • oblique (HouseholderTransformer or BivariateTransformer) – The oblique transformer of the distances from the candidates.

  • pivots (dict) – Indices in the training set of the descriptives, discriminatives and candidates pivots of the node.

  • scaler (StandardScaler) – Scaler of the numerical features, fitted on the whole data set.

See also

ObliquePivotTreeStumpClassifier

the stump that uses it.

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.transformers import ObliquePivotTransformer
>>> X, y = load_iris(return_X_y=True)
>>> transformer = ObliquePivotTransformer(tree_params={"random_state": 0}).fit(X, y)
>>> transformer.transform(X).shape[1] == len(transformer.candidate_names_)  # one direction per candidate
True
fit(X, y, idx=None, data_type=None, cache=None, sample_weight=None)[source]

Select the candidate pivots of the node (see PivotTransformer.fit), then the oblique directions on the distances of the instances of the node from them.

Parameters:

  • X (numpy.ndarray) – Tabular data, all the instances.

  • y (numpy.ndarray) – Target, all the instances.

  • idx (numpy.ndarray, default=None) – Indices of the instances in the node. If None, all the instances.

  • data_type (str, default=None) – Type of X, used as key of the cached values.

  • cache (dict, default=None) – Values shared among the splits of the tree.

  • sample_weight (numpy.ndarray, default=None) – Sample weights, all the instances.

Returns:

self

Return type:

ObliquePivotTransformer

Raises:

NoSplitFoundWarning – If the data have no numerical feature, or (bivariate) there are fewer than two candidates.

transform(X)[source]

Projection of the distances from the candidates on the oblique directions (on the chosen one, after select).

Parameters:

X (numpy.ndarray) – Tabular data.

Returns:

X_transformed

Return type:

numpy.ndarray of shape (n_samples, n_directions)

select(feature)[source]

Keep only the chosen direction.

Parameters:

feature (int) – Column chosen by the splitter.

Returns:

feature – Always 0: the projection on the only direction kept.

Return type:

int

combination(feature)[source]

Pivots and coefficients of a direction: the column is sum(c * P_i).

Parameters:

feature (int) – Column of the feature matrix.

Returns:

  • pivots (list of int) – Indices in the training set of the pivots with a non-zero coefficient.

  • coefficients (list of float) – Their coefficients.

feature_id(feature)[source]

Identifier of a direction: the indices of the pivots it combines.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id

Return type:

tuple of int

get_state()[source]

Fitted state: the candidate pivots and their indices, the numerical features, the scaler and the state of the oblique transformer.

Returns:

state – JSON-friendly dictionary, restored by set_state.

Return type:

dict

set_state(state)[source]

Restore the fitted state saved by get_state.

Parameters:

state (dict) – Dictionary created by get_state.

Returns:

self

Return type:

ObliquePivotTransformer

set_fit_request(*, cache: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → ObliquePivotTransformer

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

Parameters:

  • cache (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for cache parameter in fit.

  • data_type (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data_type parameter in fit.

  • idx (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for idx parameter in fit.

  • sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

Contents