RuleTree.stumps.regression package

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.FairTreeStumpRegressor module#

FairTreeStumpRegressor: the split for regression under a fairness constraint.

class FairTreeStumpRegressor(penalty: str = None, sensible_attribute: int = -1, penalization_weight: float = 0.3, ideal_distribution: dict = None, k_anonymity: int | float = 2, l_diversity: int | float = 2, t_closeness: float = 0.2, strict: bool = True, use_t: bool = True, n_jobs: int = 2, criterion='squared_error')[source]#

Fair stump for regression: the threshold on a numerical feature with the highest gain, penalized by how unfair the split is with respect to a sensitive attribute.

The sensitive attribute is a column of the data (sensible_attribute), never used by the splits. The fairness criterion (penalty) is statistical parity of the children, a maximum fairness cost with respect to an ideal distribution, or privacy constraints (k-anonymity, l-diversity, t-closeness). It is a Stump made of a MatrixTransformer and a FairSplitter; it supports only tabular data.

Parameters:

penalty ({'balance', 'mfc', 'privacy'}, default=None) –
Fairness criterion, which penalizes the gain of the splits:
- ’balance’: the children should have the same distribution of the sensitive attribute (statistical parity);
- ’mfc’: maximum fairness cost with respect to ideal_distribution;
- ’privacy’: the children must satisfy k-anonymity, l-diversity and t-closeness on the sensitive attribute (with strict=True, the splits that violate them are discarded).
sensible_attribute (int, default=-1) – Column of the data with the sensitive attribute. It is never used by the splits.
penalization_weight (float, default=0.3) – Weight of the penalty: the gain of a split is sigmoid(gain) * (1 - penalty * weight).
ideal_distribution (dict, default=None) – Value of the sensitive attribute -> ideal fraction, required by penalty=’mfc’.
k_anonymity (int or float, default=2) – Minimum number of instances in each child (penalty=’privacy’).
l_diversity (int or float, default=2) – Minimum number of distinct values of the sensitive attribute in each child (penalty=’privacy’).
t_closeness (float, default=0.2) – Maximum distance between the distribution of the sensitive attribute in a child and in the node (penalty=’privacy’).
strict (bool, default=True) – Whether the privacy constraints discard the splits that violate them, instead of only penalizing them.
use_t (bool, default=True) – Whether t-closeness is part of the privacy constraints.
n_jobs (int, default=number of physical CPUs) – Number of processes used to evaluate the features.
criterion ({'squared_error', 'absolute_error', 'poisson'} or callable, default='squared_error') – Impurity measure (see RegressionSplitter).

Variables:

transformer (MatrixTransformer) – The fitted transformer.
splitter (FairSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Column of the data used by the split.
threshold_original (float) – Threshold of the split.

See also

FairSplitter: the splitter, usable with other transformers (e.g. pivots).

Examples

>>> import numpy as np
>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import FairTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> X = np.column_stack([X, X[:, 1] > 0])  # last column: the sensitive attribute
>>> stump = FairTreeStumpRegressor(penalty="balance", sensible_attribute=-1, n_jobs=1).fit(X, y)
>>> stump.get_rule()["textual_rule"]
'X_4 <= -0.03'

supported_data_types = ('tabular',)#

get_rule(columns_names=None, scaler=None, float_precision=3)[source]#

Get a human-readable rule representation of the tree stump.

Parameters:

columns_names (array-like, default=None) – Names of the features. If None, generic feature names are used.
scaler (object, default=None) – If not None, the scaler is used to transform the threshold values back to the original scale.
float_precision (int, default=3) – Number of decimal places to use when rounding threshold values.

Returns:

rule – Dictionary representation of the learned rule.

Return type:

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.ObliqueDecisionTreeStumpRegressor module#

ObliqueDecisionTreeStumpRegressor: a threshold on a linear combination of features, for regression.

class ObliqueDecisionTreeStumpRegressor(oblique_split_type='householder', max_oblique_features=2, tau=0.0001, n_orientations=10, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, random_state=None, min_impurity_decrease=0.0)[source]#

Bases: ObliqueTreeStump, DecisionTreeStumpRegressor

Oblique stump for regression of tabular data: a threshold on a linear combination of a few numerical features (0.8 * X_2 - 0.6 * X_3 <= t goes left).

The directions are chosen as in ObliqueDecisionTreeStumpClassifier ('householder' or 'bivariate'). As a regression stump, it can also be used by the clustering trees. It is a Stump made of an oblique transformer and a RegressionSplitter.

Parameters:

oblique_split_type ({'householder', 'bivariate'}, default='householder') – How the oblique directions are chosen.
max_oblique_features (int, default=2) – Householder only: maximum number of features in the reflection vector.
tau (float, default=1e-4) – Householder only: if the principal component is closer than tau to every axis, the directions are the axes.
n_orientations (int, default=10) – Bivariate only: number of angles, evenly spaced in [0, 180) degrees.
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float).
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of directions considered for the split, drawn at random; None for all.
random_state (int, RandomState instance or None, default=None) – Seed of the PCA (Householder), of the choice of the directions (max_features) and of the ties between directions with the same gain. With None, a tree gives the stump its own random_state.
min_impurity_decrease (float, default=0.0) – A split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (HouseholderTransformer or BivariateTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (tuple of int) – Columns of the data combined by the split.
coefficients (list of float) – Their coefficients.
threshold_original (float) – Threshold of the split.

See also

ObliqueDecisionTreeStumpClassifier: the same stump for classification.
DecisionTreeStumpRegressor: the axis-parallel splits.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ObliqueDecisionTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> model = RuleTreeRegressor(max_depth=2, random_state=0,
...                           base_stumps=ObliqueDecisionTreeStumpRegressor("bivariate")).fit(X, y)
>>> model.get_rules()["textual_rule"]
'0.588 * X_2 + 0.809 * X_8 <= 0.005'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.PivotTreeStumpRegressor module#

PivotTreeStumpRegressor: the split on the distance from a pivot instance, for regression.

class PivotTreeStumpRegressor(distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, random_state=None, min_impurity_decrease=0.0)[source]#

Bases: PivotTreeStump, DecisionTreeStumpRegressor

Pivot stump for regression: a threshold on the distance from a pivot, an instance of the training set (distance <= t goes left).

At each node, the candidate pivots are selected among the instances of the node: the instance whose distance best separates high and low values of the target (descriptive pivot) and the one found by a regression tree on the distances (discriminative pivot). The split is the best threshold on the distance from one of the candidates. Distances are computed on the standardized numerical features; the distance matrix of the training set is computed once and cached in the tree. In the rules, P_<i> is the distance from the training instance i.

It is a Stump made of a PivotTransformer and a RegressionSplitter; it supports only tabular data.

Parameters:

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)).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
random_state (int, RandomState instance or None, default=None) – Seed of the choice of the features (max_features) and of the ties between features with the same gain. With None, a tree gives the stump its own random_state.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (PivotTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Index (in the training set) of the pivot of the split.
threshold_original (float) – Threshold of the split.
X_split_instance (numpy.ndarray) – The pivot, as standardized numerical features.

See also

PivotTreeStumpClassifier: the same stump for classification.
PivotTransformer: the selection of the pivots and the distances.
PivotTreeStump: the methods shared by the pivot stumps, e.g. get_pivots.

Notes

The parameters of the split (criterion, min_samples_leaf, …) are also used by the decision trees that select the discriminative pivots.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import PivotTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = PivotTreeStumpRegressor(random_state=0).fit(X[:200], y[:200])
>>> stump.get_rule()["textual_rule"]  # distance from the training instance 62
'P_62 <= 4.311'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.ProximityTreeStumpRegressor module#

ProximityTreeStumpRegressor: which of two shapelets is closer to the time series, for regression.

class ProximityTreeStumpRegressor(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_reg', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, min_impurity_decrease=0.0)[source]#

Bases: ProximityTreeStump, ShapeletTreeStumpRegressor

Proximity stump for regression of time series: the time series closer to one shapelet than to another one go left (euclidean(TS, green_shp) <= euclidean(TS, red_shp)).

At each node, n_shapelets shapelets are selected as in ShapeletTreeStumpRegressor, and the split is the pair of shapelets whose comparison best splits the node. Unlike the shapelet stump, the rule has no threshold: it only says which shapelet the time series resembles more. In the Graphviz drawing, the first shapelet is green and the second one red.

It is a Stump made of a ProximityTransformer and a RegressionSplitter. The time series have shape (n_samples, n_signals, length) and are passed to the trees as X_ts.

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 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_reg', 'cluster'}, default='mi_reg') – 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).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (ProximityTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
st (Shapelets) – The shapelets of the split: st.shapelets[0] (green) and st.shapelets[1] (red).

See also

ProximityTreeStumpClassifier: the same stump for classification.
ShapeletTreeStumpRegressor: the distance from a single shapelet.

Examples

>>> import numpy as np
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ProximityTreeStumpRegressor
>>> rng = np.random.default_rng(0)
>>> X_ts = rng.normal(scale=0.3, size=(60, 1, 30))  # 60 time series of length 30
>>> y = rng.integers(0, 2, size=60)
>>> X_ts[y == 1, 0, 10:20] += 2  # a bump for the class 1
>>> stump = ProximityTreeStumpRegressor(n_shapelets=4, sliding_window=10, selection="random")
>>> model = RuleTreeRegressor(max_depth=1, base_stumps=stump).fit(X_ts=X_ts, y=y.astype(float))
>>> model.get_rules()["textual_rule"]
'euclidean(TS, green_shp) <= euclidean(TS, red_shp)'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.ShapeletTreeStumpRegressor module#

ShapeletTreeStumpRegressor: the split on the distance from a shapelet, for regression of time series.

class ShapeletTreeStumpRegressor(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_reg', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, min_impurity_decrease=0.0)[source]#

Shapelet stump for regression of time series: a threshold on the distance of the time series from a shapelet (distance <= t goes left).

A shapelet is a subsequence of one of the time series of the node; the distance of a time series from it is the smallest distance between the shapelet and the subsequences of the series, so it does not depend on where the pattern occurs. At each node, n_shapelets shapelets are selected among candidate subsequences, and the split is the best threshold on the distance from one of them. In the rules, euclidean(TS, shp) is the distance from the shapelet.

It is a Stump made of a ShapeletTransformer and a RegressionSplitter. The time series have shape (n_samples, n_signals, length) and are passed to the trees as X_ts.

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_reg', 'cluster'}, default='mi_reg') – 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).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (ShapeletTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Index of the shapelet of the split among the selected ones.
threshold_original (float) – Threshold of the split.

See also

ShapeletTreeStumpClassifier: the same stump for classification.
RuleTree.utils.shapelet_transform.Shapelets.Shapelets: the selection of the shapelets.

Examples

>>> import numpy as np
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ShapeletTreeStumpRegressor
>>> rng = np.random.default_rng(0)
>>> X_ts = rng.normal(size=(60, 1, 30))  # 60 time series of length 30
>>> y = X_ts[:, 0, 10:20].mean(axis=1)
>>> stump = ShapeletTreeStumpRegressor(n_shapelets=5, sliding_window=10, selection="random")
>>> model = RuleTreeRegressor(max_depth=2, base_stumps=stump).fit(X_ts=X_ts, y=y)
>>> model.predict(X_ts=X_ts).shape
(60,)

property st#: The fitted shapelet transform.

get_rule(columns_names=None, scaler=None, float_precision: int | None = 3)[source]#

Rule of the split, e.g. euclidean(TS, shp) <= 1.2.

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Number of decimals of the threshold. If None, it is not rounded.

Returns:

rule – See RuleTreeBaseStump.get_rule.

Return type:

Raises:

ValueError – If a scaler is given.

get_graphviz_rule(columns_names=None, scaler=None, float_precision: int | None = 3)[source]#

Attributes of the Graphviz node of the split, with a plot of the shapelet (see ShapeletTreeStumpClassifier.get_graphviz_rule).

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Number of decimals of the threshold. If None, it is not rounded.

Returns:

attributes – Attributes of the Graphviz node.

Return type:

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

RuleTree.stumps.regression.XGBoostStumpRegressor module#

XGBoostStumpRegressor: the split of the trees of XGBoost.

class XGBoostStumpRegressor(lam, approximation=None, n_quantiles=32, min_cover=1, n_jobs=1)[source]#

Stump of the XGBoost trees (regression): the threshold with the highest XGBoost gain, the similarity score of the two children minus the one of the node.

It is a Stump made of a MatrixTransformer and an XGBoostSplitter, used by RuleTreeXGBoostRegressor, whose target are the residuals of the previous trees.

Parameters:

lam (float) – L2 regularization of the leaf values: the similarity score of a node is sum(residuals) ** 2 / (n + lam).
approximation ({None, 'quantile'}, default=None) – With ‘quantile’, only n_quantiles thresholds (quantiles) are tested on each numerical feature, instead of all the values.
n_quantiles (int, default=32) – Number of thresholds tested with approximation=’quantile’.
min_cover (float, default=1) – Minimum cover (number of instances) of each child.
n_jobs (int, default=1) – Not used.

Variables:

transformer (MatrixTransformer) – The fitted transformer.
splitter (XGBoostSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Column of the data used by the split.
threshold_original (float) – Threshold of the split.

See also

RuleTree.tree.RuleTreeXGBoostRegressor.RuleTreeXGBoostRegressor: the tree that uses this stump.
RuleTree.ensemble.XGBoostRegressor.XGBoostRegressor: the boosting of these trees.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import XGBoostStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = XGBoostStumpRegressor(lam=1).fit(X, y - y.mean())  # residuals of the mean
>>> stump.get_rule()["textual_rule"]
'X_8 <= -0.004'

property gain#: XGBoost gain of the split, used by the gamma pruning of RuleTreeXGBoostRegressor.

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

Module contents#

class DecisionTreeStumpRegressor(criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, random_state=None, min_impurity_decrease=0.0)[source]

Bases: Stump

Decision tree stump for regression: a threshold on a numerical feature (x <= t) or a value of a categorical feature (x == v), chosen to maximize the decrease of impurity.

It works on tabular data, time series and images; time series and images are flattened into one feature per value. It is a Stump made of a MatrixTransformer and a RegressionSplitter, and the default stump of RuleTreeRegressor.

Parameters:

criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
random_state (int, RandomState instance or None, default=None) – Seed of the choice of the features (max_features) and of the ties between features with the same gain. With None, a tree gives the stump its own random_state.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (MatrixTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Column of the data used by the split.
threshold_original (float or object) – Threshold of a numerical split, or value of a categorical split.

See also

DecisionTreeStumpClassifier: the same stump for classification.
sklearn.tree.DecisionTreeRegressor: the tree used to split the numerical features.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import DecisionTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = DecisionTreeStumpRegressor(min_samples_leaf=20, random_state=0).fit(X, y)
>>> stump.get_rule()["textual_rule"]
'X_8 <= -0.004'

get_rule(columns_names=None, scaler=None, float_precision=3)[source]

Extract the decision rule from the stump in human-readable format.

Parameters:

columns_names (array-like, optional) – Names of the features. If provided, feature names are used instead of indices.
scaler (object, optional) – Scaler object used to transform features. If provided, threshold values are transformed back to the original scale.
float_precision (int, optional) – Number of decimal places to round threshold values to.

Returns:

Dictionary containing rule information including feature index, threshold, textual representation of the rule, and visualization properties.

Return type:

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class PivotTreeStumpRegressor(distance_measure='euclidean', k=None, reg_contrast_lambda=0.2, reg_max_thresholds=None, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, random_state=None, min_impurity_decrease=0.0)[source]

Bases: PivotTreeStump, DecisionTreeStumpRegressor

Pivot stump for regression: a threshold on the distance from a pivot, an instance of the training set (distance <= t goes left).

At each node, the candidate pivots are selected among the instances of the node: the instance whose distance best separates high and low values of the target (descriptive pivot) and the one found by a regression tree on the distances (discriminative pivot). The split is the best threshold on the distance from one of the candidates. Distances are computed on the standardized numerical features; the distance matrix of the training set is computed once and cached in the tree. In the rules, P_<i> is the distance from the training instance i.

It is a Stump made of a PivotTransformer and a RegressionSplitter; it supports only tabular data.

Parameters:

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)).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
random_state (int, RandomState instance or None, default=None) – Seed of the choice of the features (max_features) and of the ties between features with the same gain. With None, a tree gives the stump its own random_state.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (PivotTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Index (in the training set) of the pivot of the split.
threshold_original (float) – Threshold of the split.
X_split_instance (numpy.ndarray) – The pivot, as standardized numerical features.

See also

PivotTreeStumpClassifier: the same stump for classification.
PivotTransformer: the selection of the pivots and the distances.
PivotTreeStump: the methods shared by the pivot stumps, e.g. get_pivots.

Notes

The parameters of the split (criterion, min_samples_leaf, …) are also used by the decision trees that select the discriminative pivots.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import PivotTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = PivotTreeStumpRegressor(random_state=0).fit(X[:200], y[:200])
>>> stump.get_rule()["textual_rule"]  # distance from the training instance 62
'P_62 <= 4.311'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class ShapeletTreeStumpRegressor(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_reg', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, min_impurity_decrease=0.0)[source]

Shapelet stump for regression of time series: a threshold on the distance of the time series from a shapelet (distance <= t goes left).

A shapelet is a subsequence of one of the time series of the node; the distance of a time series from it is the smallest distance between the shapelet and the subsequences of the series, so it does not depend on where the pattern occurs. At each node, n_shapelets shapelets are selected among candidate subsequences, and the split is the best threshold on the distance from one of them. In the rules, euclidean(TS, shp) is the distance from the shapelet.

It is a Stump made of a ShapeletTransformer and a RegressionSplitter. The time series have shape (n_samples, n_signals, length) and are passed to the trees as X_ts.

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_reg', 'cluster'}, default='mi_reg') – 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).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (ShapeletTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Index of the shapelet of the split among the selected ones.
threshold_original (float) – Threshold of the split.

See also

ShapeletTreeStumpClassifier: the same stump for classification.
RuleTree.utils.shapelet_transform.Shapelets.Shapelets: the selection of the shapelets.

Examples

>>> import numpy as np
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ShapeletTreeStumpRegressor
>>> rng = np.random.default_rng(0)
>>> X_ts = rng.normal(size=(60, 1, 30))  # 60 time series of length 30
>>> y = X_ts[:, 0, 10:20].mean(axis=1)
>>> stump = ShapeletTreeStumpRegressor(n_shapelets=5, sliding_window=10, selection="random")
>>> model = RuleTreeRegressor(max_depth=2, base_stumps=stump).fit(X_ts=X_ts, y=y)
>>> model.predict(X_ts=X_ts).shape
(60,)

property st: The fitted shapelet transform.

get_rule(columns_names=None, scaler=None, float_precision: int | None = 3)[source]

Rule of the split, e.g. euclidean(TS, shp) <= 1.2.

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Number of decimals of the threshold. If None, it is not rounded.

Returns:

rule – See RuleTreeBaseStump.get_rule.

Return type:

Raises:

ValueError – If a scaler is given.

get_graphviz_rule(columns_names=None, scaler=None, float_precision: int | None = 3)[source]

Attributes of the Graphviz node of the split, with a plot of the shapelet (see ShapeletTreeStumpClassifier.get_graphviz_rule).

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Number of decimals of the threshold. If None, it is not rounded.

Returns:

attributes – Attributes of the Graphviz node.

Return type:

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class FairTreeStumpRegressor(penalty: str = None, sensible_attribute: int = -1, penalization_weight: float = 0.3, ideal_distribution: dict = None, k_anonymity: int | float = 2, l_diversity: int | float = 2, t_closeness: float = 0.2, strict: bool = True, use_t: bool = True, n_jobs: int = 2, criterion='squared_error')[source]

Fair stump for regression: the threshold on a numerical feature with the highest gain, penalized by how unfair the split is with respect to a sensitive attribute.

The sensitive attribute is a column of the data (sensible_attribute), never used by the splits. The fairness criterion (penalty) is statistical parity of the children, a maximum fairness cost with respect to an ideal distribution, or privacy constraints (k-anonymity, l-diversity, t-closeness). It is a Stump made of a MatrixTransformer and a FairSplitter; it supports only tabular data.

Parameters:

penalty ({'balance', 'mfc', 'privacy'}, default=None) –
Fairness criterion, which penalizes the gain of the splits:
- ’balance’: the children should have the same distribution of the sensitive attribute (statistical parity);
- ’mfc’: maximum fairness cost with respect to ideal_distribution;
- ’privacy’: the children must satisfy k-anonymity, l-diversity and t-closeness on the sensitive attribute (with strict=True, the splits that violate them are discarded).
sensible_attribute (int, default=-1) – Column of the data with the sensitive attribute. It is never used by the splits.
penalization_weight (float, default=0.3) – Weight of the penalty: the gain of a split is sigmoid(gain) * (1 - penalty * weight).
ideal_distribution (dict, default=None) – Value of the sensitive attribute -> ideal fraction, required by penalty=’mfc’.
k_anonymity (int or float, default=2) – Minimum number of instances in each child (penalty=’privacy’).
l_diversity (int or float, default=2) – Minimum number of distinct values of the sensitive attribute in each child (penalty=’privacy’).
t_closeness (float, default=0.2) – Maximum distance between the distribution of the sensitive attribute in a child and in the node (penalty=’privacy’).
strict (bool, default=True) – Whether the privacy constraints discard the splits that violate them, instead of only penalizing them.
use_t (bool, default=True) – Whether t-closeness is part of the privacy constraints.
n_jobs (int, default=number of physical CPUs) – Number of processes used to evaluate the features.
criterion ({'squared_error', 'absolute_error', 'poisson'} or callable, default='squared_error') – Impurity measure (see RegressionSplitter).

Variables:

transformer (MatrixTransformer) – The fitted transformer.
splitter (FairSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Column of the data used by the split.
threshold_original (float) – Threshold of the split.

See also

FairSplitter: the splitter, usable with other transformers (e.g. pivots).

Examples

>>> import numpy as np
>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import FairTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> X = np.column_stack([X, X[:, 1] > 0])  # last column: the sensitive attribute
>>> stump = FairTreeStumpRegressor(penalty="balance", sensible_attribute=-1, n_jobs=1).fit(X, y)
>>> stump.get_rule()["textual_rule"]
'X_4 <= -0.03'

supported_data_types = ('tabular',)

get_rule(columns_names=None, scaler=None, float_precision=3)[source]

Get a human-readable rule representation of the tree stump.

Parameters:

columns_names (array-like, default=None) – Names of the features. If None, generic feature names are used.
scaler (object, default=None) – If not None, the scaler is used to transform the threshold values back to the original scale.
float_precision (int, default=3) – Number of decimal places to use when rounding threshold values.

Returns:

rule – Dictionary representation of the learned rule.

Return type:

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class XGBoostStumpRegressor(lam, approximation=None, n_quantiles=32, min_cover=1, n_jobs=1)[source]

Stump of the XGBoost trees (regression): the threshold with the highest XGBoost gain, the similarity score of the two children minus the one of the node.

It is a Stump made of a MatrixTransformer and an XGBoostSplitter, used by RuleTreeXGBoostRegressor, whose target are the residuals of the previous trees.

Parameters:

lam (float) – L2 regularization of the leaf values: the similarity score of a node is sum(residuals) ** 2 / (n + lam).
approximation ({None, 'quantile'}, default=None) – With ‘quantile’, only n_quantiles thresholds (quantiles) are tested on each numerical feature, instead of all the values.
n_quantiles (int, default=32) – Number of thresholds tested with approximation=’quantile’.
min_cover (float, default=1) – Minimum cover (number of instances) of each child.
n_jobs (int, default=1) – Not used.

Variables:

transformer (MatrixTransformer) – The fitted transformer.
splitter (XGBoostSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int) – Column of the data used by the split.
threshold_original (float) – Threshold of the split.

See also

RuleTree.tree.RuleTreeXGBoostRegressor.RuleTreeXGBoostRegressor: the tree that uses this stump.
RuleTree.ensemble.XGBoostRegressor.XGBoostRegressor: the boosting of these trees.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree.stumps.regression import XGBoostStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = XGBoostStumpRegressor(lam=1).fit(X, y - y.mean())  # residuals of the mean
>>> stump.get_rule()["textual_rule"]
'X_8 <= -0.004'

property gain: XGBoost gain of the split, used by the gamma pruning of RuleTreeXGBoostRegressor.

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class ObliqueDecisionTreeStumpRegressor(oblique_split_type='householder', max_oblique_features=2, tau=0.0001, n_orientations=10, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, random_state=None, min_impurity_decrease=0.0)[source]

Bases: ObliqueTreeStump, DecisionTreeStumpRegressor

Oblique stump for regression of tabular data: a threshold on a linear combination of a few numerical features (0.8 * X_2 - 0.6 * X_3 <= t goes left).

The directions are chosen as in ObliqueDecisionTreeStumpClassifier ('householder' or 'bivariate'). As a regression stump, it can also be used by the clustering trees. It is a Stump made of an oblique transformer and a RegressionSplitter.

Parameters:

oblique_split_type ({'householder', 'bivariate'}, default='householder') – How the oblique directions are chosen.
max_oblique_features (int, default=2) – Householder only: maximum number of features in the reflection vector.
tau (float, default=1e-4) – Householder only: if the principal component is closer than tau to every axis, the directions are the axes.
n_orientations (int, default=10) – Bivariate only: number of angles, evenly spaced in [0, 180) degrees.
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float).
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of directions considered for the split, drawn at random; None for all.
random_state (int, RandomState instance or None, default=None) – Seed of the PCA (Householder), of the choice of the directions (max_features) and of the ties between directions with the same gain. With None, a tree gives the stump its own random_state.
min_impurity_decrease (float, default=0.0) – A split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (HouseholderTransformer or BivariateTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (tuple of int) – Columns of the data combined by the split.
coefficients (list of float) – Their coefficients.
threshold_original (float) – Threshold of the split.

See also

ObliqueDecisionTreeStumpClassifier: the same stump for classification.
DecisionTreeStumpRegressor: the axis-parallel splits.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ObliqueDecisionTreeStumpRegressor
>>> X, y = load_diabetes(return_X_y=True)
>>> model = RuleTreeRegressor(max_depth=2, random_state=0,
...                           base_stumps=ObliqueDecisionTreeStumpRegressor("bivariate")).fit(X, y)
>>> model.get_rules()["textual_rule"]
'0.588 * X_2 + 0.809 * X_8 <= 0.005'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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:

class ProximityTreeStumpRegressor(n_shapelets=8, n_shapelets_for_selection=500, n_ts_for_selection_per_class=100, sliding_window=50, selection='mi_reg', distance='euclidean', mi_n_neighbors=100, random_state=42, n_jobs=1, criterion='squared_error', min_samples_leaf=1, min_weight_fraction_leaf=0.0, max_features=None, min_impurity_decrease=0.0)[source]

Bases: ProximityTreeStump, ShapeletTreeStumpRegressor

Proximity stump for regression of time series: the time series closer to one shapelet than to another one go left (euclidean(TS, green_shp) <= euclidean(TS, red_shp)).

At each node, n_shapelets shapelets are selected as in ShapeletTreeStumpRegressor, and the split is the pair of shapelets whose comparison best splits the node. Unlike the shapelet stump, the rule has no threshold: it only says which shapelet the time series resembles more. In the Graphviz drawing, the first shapelet is green and the second one red.

It is a Stump made of a ProximityTransformer and a RegressionSplitter. The time series have shape (n_samples, n_signals, length) and are passed to the trees as X_ts.

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 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_reg', 'cluster'}, default='mi_reg') – 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).
criterion ({'squared_error', 'absolute_error', 'poisson'}, default='squared_error') – Impurity measure.
min_samples_leaf (int or float, default=1) – Minimum number of instances in each child (a fraction of the instances of the node if float). Applies to the numerical features.
min_weight_fraction_leaf (float, default=0.0) – Minimum fraction of the sample weights of the node in each child. Applies to the numerical features.
max_features (int, float, {'sqrt', 'log2'} or None, default=None) – Number of numerical features considered for the split, drawn at random; None for all.
min_impurity_decrease (float, default=0.0) – A numerical split is kept only if it decreases the weighted impurity by at least this value.

Variables:

transformer (ProximityTransformer) – The fitted transformer.
splitter (RegressionSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
st (Shapelets) – The shapelets of the split: st.shapelets[0] (green) and st.shapelets[1] (red).

See also

ProximityTreeStumpClassifier: the same stump for classification.
ShapeletTreeStumpRegressor: the distance from a single shapelet.

Examples

>>> import numpy as np
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.regression import ProximityTreeStumpRegressor
>>> rng = np.random.default_rng(0)
>>> X_ts = rng.normal(scale=0.3, size=(60, 1, 30))  # 60 time series of length 30
>>> y = rng.integers(0, 2, size=60)
>>> X_ts[y == 1, 0, 10:20] += 2  # a bump for the class 1
>>> stump = ProximityTreeStumpRegressor(n_shapelets=4, sliding_window=10, selection="random")
>>> model = RuleTreeRegressor(max_depth=1, base_stumps=stump).fit(X_ts=X_ts, y=y.astype(float))
>>> model.get_rules()["textual_rule"]
'euclidean(TS, green_shp) <= euclidean(TS, red_shp)'

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:

check_input (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for check_input parameter in fit.
context (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for context parameter in fit.
data (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for data 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: