RuleTree.stumps package

RuleTree.stumps package#

Subpackages#

Submodules#

RuleTree.stumps.ObliqueTreeStump module#

ObliqueTreeStump: what the oblique stumps for classification and regression have in common.

check_oblique_split_type(oblique_split_type: str)[source]#

Check the type of oblique split of a stump.

Parameters:: oblique_split_type (str) – ‘householder’ or ‘bivariate’.
Raises:: ValueError – For any other value.

format_combination(names: list, coefficients: list, float_precision=3) → str[source]#

Text of a linear combination, e.g. 0.8 * X_2 - 0.6 * X_3; a single term with coefficient 1 (an axis-parallel direction) is just its name.

Parameters:

names (list of str) – Names of the terms.
coefficients (list of float) – Their coefficients.
float_precision (int, default=3) – Number of decimals of the coefficients. If None, they are not rounded.

Returns:

text

Return type:

str

Examples

>>> from RuleTree.stumps.ObliqueTreeStump import format_combination
>>> format_combination(["X_0", "X_3"], [0.5, -0.25])
'0.5 * X_0 - 0.25 * X_3'
>>> format_combination(["X_3"], [1.0])
'X_3'

combination_rule(feature_idx, names, coefficients, threshold, float_precision=3) → dict[source]#

Rule of a threshold on a linear combination: combination <= threshold goes left.

Parameters:

feature_idx (object) – Identifier of the combination, stored in feature_idx.
names (list of str) – Names of the terms.
coefficients (list of float) – Their coefficients.
threshold (float) – Threshold of the split.
float_precision (int, default=3) – Number of decimals of the coefficients and of the threshold. If None, they are not rounded.

Returns:

rule – See RuleTreeBaseStump.get_rule; also coefficients.

Return type:

dict

class ObliqueTreeStump[source]#

Bases: object

Mixin of the oblique stumps (ObliqueDecisionTreeStumpClassifier and ObliqueDecisionTreeStumpRegressor): the oblique transformer built from the parameters of the stump, and the rule of the split.

The subclass defines the parameters and the splitter, by deriving also from the decision tree stump of its task (class ObliqueDecisionTreeStumpClassifier(ObliqueTreeStump, DecisionTreeStumpClassifier)).

property coefficients#: Coefficients of the combination of the split, None if not fitted.

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

Rule of the split, e.g. 0.8 * X_2 - 0.6 * X_3 <= 1.5.

Parameters:

columns_names (list of str, default=None) – Names of the columns of the data, used instead of X_<index>.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Number of decimals of the coefficients and of the threshold; None for no rounding.

Returns:

rule – feature_idx (the columns of the combination), coefficients, threshold, is_categorical, feature_name (the combination), the condition of the left child (textual_rule, blob_rule, graphviz_rule) and its negation. Empty if the stump is not fitted.

Return type:

dict

Raises:

ValueError – If a scaler is given.

RuleTree.stumps.PivotTreeStump module#

PivotTreeStump, MultiplePivotTreeStump and ObliquePivotTreeStump: what the pivot stumps have in common.

class PivotTreeStump[source]#

Bases: object

Mixin of the pivot stumps (PivotTreeStumpClassifier and PivotTreeStumpRegressor): the PivotTransformer built from the parameters of the stump, the pivots of the split and its rule.

The subclass defines the parameters and the splitter, by deriving also from the decision tree stump of its task (class PivotTreeStumpClassifier(PivotTreeStump, DecisionTreeStumpClassifier)).

property X_split_instance#: The pivot of the split (standardized numerical features), None if not fitted.

get_pivots()[source]#

Pivots of the node, as indices of instances of the training set.

Returns:: pivots – descriptives (medoids), discriminatives and candidates (both) pivots of the node, and the pivot used by the split.
Return type:: dict

Examples

>>> from sklearn.datasets import load_iris
>>> from RuleTree.stumps.classification import PivotTreeStumpClassifier
>>> X, y = load_iris(return_X_y=True)
>>> pivots = PivotTreeStumpClassifier(random_state=0).fit(X, y).get_pivots()
>>> pivots["descriptives"], pivots["discriminatives"], pivots["used"]
([7, 96, 112], [27, 77, 127], 112)

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

Rule of the split, P_ <= threshold, where P_ is the distance from the training instance i.

Parameters:

columns_names (list of str, default=None) – Not used: the rule does not name the features.
scaler (TransformerMixin, default=None) – Not used: the distances are computed on the data standardized by the stump.
float_precision (int, default=3) – Number of decimals of the threshold; None for no rounding.

Returns:

rule – feature_idx (the pivot), threshold, is_categorical, feature_name, the condition of the left child (textual_rule, blob_rule, graphviz_rule) and its negation (not_textual_rule, not_blob_rule, not_graphviz_rule). Empty if the stump is not fitted.

Return type:

dict

class MultiplePivotTreeStump[source]#

Bases: object

Mixin of the multiple pivot stumps (MultiplePivotTreeStumpClassifier and MultipleObliquePivotTreeStumpClassifier): the MultiplePivotTransformer built from the parameters of the stump, the pivots of the split and its rule, P_<a> <= P_ (closer to the training instance a than to b).

get_pivots()[source]#

Pivots of the node, as indices of instances of the training set.

Returns:: pivots – descriptives, discriminatives and candidates pivots of the node, and the two pivots used by the split.
Return type:: dict

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

Rule of the split, P_<a> <= P_: the instances closer to the training instance a than to b go left.

Parameters:

columns_names (list of str, default=None) – Not used: the rule does not name the features.
scaler (TransformerMixin, default=None) – Not used: the distances are computed on the data standardized by the stump.
float_precision (int, default=3) – Not used: the rule has no number.

Returns:

rule – See RuleTreeBaseStump.get_rule. Empty if the stump is not fitted.

Return type:

dict

class ObliquePivotTreeStump[source]#

Bases: object

Mixin of the oblique pivot stumps (ObliquePivotTreeStumpClassifier): the ObliquePivotTransformer built from the parameters of the stump, the pivots of the split and its rule, e.g. 0.7 * P_12 - 0.3 * P_57 <= 1.2.

property coefficients#: Coefficients of the combination of the split, None if not fitted.

get_pivots()[source]#

Pivots of the node, as indices of instances of the training set.

Returns:: pivots – descriptives, discriminatives and candidates pivots of the node, and the pivots used by the combination of the split.
Return type:: dict

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

Rule of the split, e.g. 0.7 * P_12 - 0.3 * P_57 <= 1.2, where P_ is the distance from the training instance i.

Parameters:

columns_names (list of str, default=None) – Not used: the rule does not name the features.
scaler (TransformerMixin, default=None) – Not used: the distances are computed on the data standardized by the stump.
float_precision (int, default=3) – Number of decimals of the coefficients and of the threshold; None for no rounding.

Returns:

rule – See RuleTreeBaseStump.get_rule; also coefficients. Empty if the stump is not fitted.

Return type:

dict

RuleTree.stumps.ProximityTreeStump module#

ProximityTreeStump and PartialProximityTreeStump: what the proximity stumps have in common.

proximity_rule(feature_idx, first: str, second: str, threshold) → dict[source]#

Rule of a proximity split: first <= second goes left, where first and second are the distances from the two references of the split.

Parameters:

feature_idx (object) – Identifier of the pair, stored in feature_idx.
first (str) – Text of the distances from the first and from the second reference.
second (str) – Text of the distances from the first and from the second reference.
threshold (float) – Threshold of the split on the 0/1 comparison (between 0 and 1).

Returns:

rule – See RuleTreeBaseStump.get_rule.

Return type:

dict

class ProximityTreeStump[source]#

Bases: object

Mixin of the proximity stumps for time series (ProximityTreeStumpClassifier and ProximityTreeStumpRegressor): the ProximityTransformer built from the parameters of the stump, the rule and its drawing.

The subclass defines the parameters and the splitter, by deriving also from the shapelet stump of its task (class ProximityTreeStumpClassifier(ProximityTreeStump, ShapeletTreeStumpClassifier)).

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

Rule of the split, euclidean(TS, green_shp) <= euclidean(TS, red_shp): the time series closer to the first shapelet (green in the drawing, st.shapelets[0]) than to the second one (red, st.shapelets[1]) go left.

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Not used: the rule has no number.

Returns:

rule – See RuleTreeBaseStump.get_rule.

Return type:

dict

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: the rule above a plot of the two shapelets, green and red, drawn into a temporary PNG file (requires matplotlib).

Parameters:

columns_names (list of str, default=None) – Not used.
scaler (TransformerMixin, default=None) – Not supported: must be None.
float_precision (int, default=3) – Not used.

Returns:

attributes – Attributes of the Graphviz node.

Return type:

dict

Raises:

MissingOptionalDependencyError – If matplotlib is not installed.

class PartialProximityTreeStump[source]#

Bases: object

Mixin of the proximity stumps for tabular data (PartialProximityTreeStumpClassifier): the PartialProximityTransformer built from the parameters of the stump and the rule.

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

Rule of the split, e.g. euclidean(x, SP0(d: petal length=1.3)) <= euclidean(x, SP1(d: petal length=5.1)): the instances closer to the first partial pivot than to the second one go left.

Parameters:

columns_names (list of str, default=None) – Names of the features. If None, Feat. <index>.
scaler (TransformerMixin, default=None) – Scaler used to preprocess the data: the values of the pivots are shown in the original scale.
float_precision (int, default=3) – Not used: the values of the pivots are not rounded.

Returns:

rule – See RuleTreeBaseStump.get_rule.

Return type:

dict

RuleTree.stumps.Stump module#

File: Stump.py

The stump made of a transformer (how the data are represented, see RuleTreeBaseTransformer) and a splitter (how the split is chosen, see RuleTreeBaseSplitter).

class Stump(transformer=None, splitter=None)[source]#

Bases: RuleTreeBaseStump

Stump made of a transformer and a splitter: the transformer turns the data of one type into a feature matrix, the splitter finds the best split of that matrix.

Any transformer can be combined with any splitter. The data types supported by the stump are the ones of the transformer, and its task (classification or regression) is the one of the splitter. The stumps of the library are subclasses that build the two components from their own parameters (_make_transformer and _make_splitter); see Extending the library to write new ones.

Parameters:

transformer (RuleTreeBaseTransformer, default=None) – Transformer of the data into a feature matrix; it is cloned at each fit.
splitter (RuleTreeBaseSplitter, default=None) – Splitter of the feature matrix; it is cloned at each fit.

Variables:

transformer (RuleTreeBaseTransformer) – The fitted transformer.
splitter (RuleTreeBaseSplitter) – The fitted splitter (feature, threshold, gain and impurity of the split).
data_type (str) – Data type the stump was fitted on.
feature_original (int or str) – Feature of the split, as identified by the transformer: a column of the data, a pivot, …
threshold_original (float or object) – Threshold of a numerical split, or value of a categorical split.

Examples

>>> from sklearn.datasets import load_diabetes
>>> from RuleTree import RuleTreeRegressor
>>> from RuleTree.stumps.Stump import Stump
>>> from RuleTree.stumps.splitters import FairSplitter, RegressionSplitter
>>> from RuleTree.stumps.transformers import MatrixTransformer, PivotTransformer
>>> from RuleTree.utils.define import MODEL_TYPE_REG
>>> X, y = load_diabetes(return_X_y=True)
>>> stump = Stump(PivotTransformer(MODEL_TYPE_REG), RegressionSplitter())
>>> stump.task, stump.supported_data_types
('reg', ('tabular',))
>>> model = RuleTreeRegressor(max_depth=2, base_stumps=stump).fit(X[:100], y[:100])

property supported_data_types#

the ones of its transformer.

Type:: Data types supported by the stump

property task#

the one of its splitter (MODEL_TYPE_CLF or MODEL_TYPE_REG).

Type:: Task of the stump

fit(data, y, idx=None, context=None, data_type=None, sample_weight=None, check_input=True)[source]#

Fit the stump on the instances idx of data: the transformer on the whole data set of the selected type (with the indices of the node and the cache of the tree), the splitter on the feature matrix of the node; then the transformer keeps only what is needed by the chosen feature (and the splitter is fitted again if the feature matrix changes).

Parameters:

data (dict or numpy.ndarray) – Whole data set, as {data_type: array}.
y (numpy.ndarray) – Target of the whole data set.
idx (numpy.ndarray, default=None) – Indices of the instances reaching the node. If None, all the instances.
context (RuleTree, default=None) – Tree being built, whose cache is shared by the stumps of the same class.
data_type (str, default=None) – Data type to use. If None, the first supported data type available in data.
sample_weight (numpy.ndarray, default=None) – Sample weights of the whole data set.
check_input (bool, default=True) – Whether to check the input data.

Returns:

self – The fitted stump.

Return type:

Stump

Raises:

NoSplitFoundWarning – If the instances cannot be split.

property feature_original#

a column of the data (int), or a name such as a pivot. None if not fitted.

Type:: Feature of the split, as identified by the transformer

property threshold_original#: Threshold (numerical split) or value (categorical split). None if not fitted.

property is_categorical#: Whether the split is categorical (x == value). None if not fitted.

property impurity#: Impurity of the node and of the two children, if computed by the splitter. None if not fitted.

property gain_#: Gain of the split, used by the trees with stump_selection=’best’.

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

Rule of the split, e.g. X_2 <= 4.5: the feature is named after the transformer’s feature id.

Parameters:

columns_names (list of str, default=None) – Names of the columns of the tabular data, used for the features that are columns.
scaler (TransformerMixin, default=None) – Scaler used to preprocess the data: the threshold is also given in the original scale.
float_precision (int, default=3) – Number of decimals of the threshold; None for no rounding.

Returns:

rule – The textual, blob and Graphviz forms of the condition of the left child and of its negation (see RuleTreeBaseStump.get_rule()).

Return type:

dict

node_to_dict()[source]#: Dictionary representation of the stump: constructor arguments and, if fitted, the rule, the data type and the state of the transformer and of the splitter.

classmethod dict_to_node(node_dict)[source]#

Create a stump from a dictionary created by node_to_dict().

Parameters:: node_dict (dict) – Dictionary representation of the stump.
Returns:: stump – The stump, fitted if it was fitted when saved.
Return type:: Stump

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:

object

RuleTree.stumps package

Contents

RuleTree.stumps package#

Subpackages#

Submodules#

RuleTree.stumps.ObliqueTreeStump module#

RuleTree.stumps.PivotTreeStump module#

RuleTree.stumps.ProximityTreeStump module#

RuleTree.stumps.Stump module#

Module contents#