RuleTree.base package

RuleTree.base package#

API reference#

RuleTree.base.RuleTreeBase.RuleTreeBase()

Base class for RuleTree estimators.

RuleTree.base.RuleTreeBaseSplitter.RuleTreeBaseSplitter()

Abstract base class of the splitters, the component of a stump that finds the best split of a feature matrix: a threshold on a numerical feature (x <= threshold goes to the left child) or a value of a categorical feature (x == value goes to the left child).

RuleTree.base.RuleTreeBaseGainSplitter.RuleTreeBaseGainSplitter()

Base class of the splitters that test every candidate split and keep the one with the highest gain: a new splitter only defines the task (task) and the gain of a split (gain()).

RuleTree.base.RuleTreeBaseStump.RuleTreeBaseStump()

Abstract base class of the stumps, the splits of the nodes of a RuleTree.

RuleTree.base.RuleTreeBaseTransformer.RuleTreeBaseTransformer()

Abstract base class of the transformers, the component of a stump that turns the data of one type into a feature matrix.

Submodules#

RuleTree.base.RuleTreeBase module#

Base classes for RuleTree estimators.

class RuleTreeBase[source]

Bases: BaseEstimator, ABC

Base class for RuleTree estimators.

RuleTree estimators may receive one input container for each supported data type: X for tabular data, X_ts for time series, X_img for images, and X_txt for text. The only assumption made by this base class is that the first dimension of every provided container is the number of samples. This is enough to validate that all provided inputs, and y when available, refer to the same set of instances.

Internally, the inputs are handled as a single dictionary {data_type: array} (see RuleTree.utils.define.DATA_INPUT_TYPES), built by _validate_inputs().

Notes

The class follows the scikit-learn estimator API by inheriting from sklearn.base.BaseEstimator. The base implementation only validates inputs; concrete estimators are expected to implement the actual fitting and prediction behavior.

See also

RuleTree.tree.RuleTree.RuleTree

the base class of the trees.

fit(X=None, y=None, X_ts=None, X_img=None, X_txt=None)[source]

Validate input data before fitting.

Parameters:

  • X (array-like of shape (n_samples, n_features), default=None) – Tabular input data.

  • X_ts (array-like of shape (n_samples, ...), default=None) – Time-series input data.

  • X_img (array-like of shape (n_samples, ...), default=None) – Image input data.

  • X_txt (array-like of shape (n_samples, ...), default=None) – Text input data.

  • y (array-like of shape (n_samples,), default=None) – Target values.

Returns:

self – The validated estimator instance.

Return type:

RuleTreeBase

Raises:

ValueError – If no input container is provided, or if the provided containers and y do not have a consistent number of samples.

predict(X=None, X_ts=None, X_img=None, X_txt=None)[source]

Validate input data before prediction.

Parameters:

  • X (array-like of shape (n_samples, n_features), default=None) – Tabular input data.

  • X_ts (array-like of shape (n_samples, ...), default=None) – Time-series input data.

  • X_img (array-like of shape (n_samples, ...), default=None) – Image input data.

  • X_txt (array-like of shape (n_samples, ...), default=None) – Text input data.

Raises:

ValueError – If no input container is provided, or if the provided containers do not have a consistent number of samples.

set_fit_request(*, X_img: bool | None | str = '$UNCHANGED$', X_ts: bool | None | str = '$UNCHANGED$', X_txt: bool | None | str = '$UNCHANGED$') → RuleTreeBase

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:

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

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

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

Returns:

self – The updated object.

Return type:

object

set_predict_request(*, X_img: bool | None | str = '$UNCHANGED$', X_ts: bool | None | str = '$UNCHANGED$', X_txt: bool | None | str = '$UNCHANGED$') → RuleTreeBase

Configure whether metadata should be requested to be passed to the predict 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 predict if provided. The request is ignored if metadata is not provided.

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

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

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

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

Added in version 1.3.

Parameters:

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

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

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

Returns:

self – The updated object.

Return type:

object

RuleTree.base.RuleTreeBaseStump module#

Abstract base class of the stumps: the single splits that make up the nodes of a RuleTree.

class RuleTreeBaseStump[source]

Bases: BaseEstimator, ABC

Abstract base class of the stumps, the splits of the nodes of a RuleTree.

A stump divides the instances of a node into two children: apply returns 1 for the instances that go to the left child and 2 for the ones that go to the right child.

Notes

Stumps receive the whole data set as a dictionary data = {data_type: array} (see RuleTree.utils.define.DATA_INPUT_TYPES) together with idx, the indices of the instances reaching the node. A fitted stump works on a single data type, chosen by the tree among supported_data_types and stored in data_type_. For convenience, data can also be a single array, interpreted as data of the stump’s data type.

The tree passed as context holds a cache that lives until the next fit (or clear_cache()), where stumps can store anything that can be shared among splits, e.g. embeddings computed on the whole data set. The stumps of the same class with the same hyperparameters share a cache, named by cache_namespace(). Everything needed by apply must be stored in the stump itself.

Subclasses that work on a 2D matrix can implement _transform (data of the stump’s data type -> matrix) and _apply_matrix (matrix -> 1/2 labels) and reuse apply() and update_statistics(). The stumps of the library are made of a transformer and a splitter (see RuleTree.stumps.Stump.Stump), which is the simplest way to write a new stump.

Variables:

  • supported_data_types (tuple of str) – Data types the stump can be fitted on.

  • task (str) – Kind of target, MODEL_TYPE_CLF (classification) or MODEL_TYPE_REG (regression).

  • data_type (str) – Data type the stump has been fitted on.

See also

RuleTree.stumps.Stump.Stump

a stump made of a transformer and a splitter, the simplest way to write a new stump (see Extending the library).

supported_data_types = ('tabular',)
abstractmethod 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.

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, used to share cached values among the splits.

  • 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:

RuleTreeBaseStump

Raises:

NoSplitFoundWarning – If the instances cannot be split.

abstractmethod get_rule(columns_names: list = None, scaler: TransformerMixin = None, float_precision: int | None = 3) → dict[source]

Human-readable representation of the split.

Parameters:

  • columns_names (list of str, default=None) – Names of the features, used instead of their indices.

  • scaler (TransformerMixin, default=None) – Scaler used to preprocess the data: the thresholds are shown in the original scale.

  • float_precision (int, default=3) – Number of decimals of the thresholds. If None, they are not rounded.

Returns:

rule – The rule, with at least the keys textual_rule and not_textual_rule (the condition of the left child and its negation), blob_rule, not_blob_rule, graphviz_rule and not_graphviz_rule (attributes of the Graphviz node).

Return type:

dict

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

Attributes of the Graphviz node of the split (see RuleTree.export_graphviz). The default implementation is get_rule(...)["graphviz_rule"]; stumps that draw something in the node, such as the shapelet stumps, override it.

Parameters:

  • columns_names (list of str, default=None) – Names of the tabular features.

  • scaler (TransformerMixin, default=None) – Scaler used to preprocess the data: the thresholds are shown in the original scale.

  • float_precision (int, default=3) – Number of decimals of the threshold.

Returns:

attributes – Attributes of the Graphviz node, e.g. label.

Return type:

dict

abstractmethod node_to_dict() → dict[source]

Dictionary representation of the stump, used to save the tree (see RuleTree.to_dict).

Returns:

node_dict – JSON-friendly dictionary with the key stump_type (module of the stump class) and all that is needed by dict_to_node() to rebuild the stump.

Return type:

dict

abstractmethod classmethod dict_to_node(node_dict: dict) → RuleTreeBaseStump[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:

RuleTreeBaseStump

property task: str

MODEL_TYPE_CLF (classification) or MODEL_TYPE_REG (regression). A tree accepts only stumps of its task (see RuleTree._get_stumps_task).

Type:

Kind of target of the stump

supports(data_type: str) → bool[source]

Whether the stump can be fitted on a data type.

Parameters:

data_type (str) – A data type, e.g. "tabular" (see RuleTree.utils.define.DATA_INPUT_TYPES).

Returns:

supported – True if data_type is in supported_data_types.

Return type:

bool

apply(data, idx=None) → ndarray[source]

Apply the split to the instances idx of data.

Parameters:

  • data (dict or numpy.ndarray) – Data set, as {data_type: array} or a single array of the stump’s data type.

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

Returns:

labels – For each instance in idx, 1 if it goes to the left child, 2 otherwise.

Return type:

numpy.ndarray of int

update_statistics(data, y, idx=None, context=None, sample_weight=None, check_input=True)[source]

Recompute the statistics of the split (e.g. impurity) on the instances idx of data, without changing the split.

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) – Not used, kept for symmetry with fit().

  • sample_weight (numpy.ndarray, default=None) – Sample weights of the whole data set.

  • check_input (bool, default=True) – Not used, kept for symmetry with fit().

cache_namespace() → str[source]

Name of the cache of the stump in the tree (see RuleTree.get_cache): the class name and a hash of the hyperparameters, also of the components (e.g. the transformer of a Stump). Stumps of the same class with different hyperparameters do not share cached values.

The tree gives its random_state to the stumps without one, so the namespace of a stump used by a tree is the one of its copy in candidate_splits_.

Returns:

namespace – E.g. "PivotTreeStumpClassifier-1a2b3c4d".

Return type:

str

Examples

>>> from RuleTree.stumps.classification import DecisionTreeStumpClassifier
>>> a, b = DecisionTreeStumpClassifier(), DecisionTreeStumpClassifier(criterion="entropy")
>>> a.cache_namespace().startswith("DecisionTreeStumpClassifier-")
True
>>> a.cache_namespace() == DecisionTreeStumpClassifier().cache_namespace() != b.cache_namespace()
True
set_fit_request(*, check_input: bool | None | str = '$UNCHANGED$', context: bool | None | str = '$UNCHANGED$', data: bool | None | str = '$UNCHANGED$', data_type: bool | None | str = '$UNCHANGED$', idx: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → RuleTreeBaseStump

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.base.RuleTreeBaseSplitter module#

Abstract base class of the splitters: the component of a stump that finds the best split of a feature matrix (the matrix produced by the stump’s transformer, see RuleTreeBaseTransformer).

class RuleTreeBaseSplitter[source]

Bases: BaseEstimator, ABC

Abstract base class of the splitters, the component of a stump that finds the best split of a feature matrix: a threshold on a numerical feature (x <= threshold goes to the left child) or a value of a categorical feature (x == value goes to the left child).

A new splitter implements fit(), which sets the attributes below; apply(), get_state() and set_state() work for any split of this form. Splitters are scikit-learn estimators: their parameters are the arguments of __init__.

Variables:

  • task (str) – Kind of target: MODEL_TYPE_CLF (classification) or MODEL_TYPE_REG (regression). Class attribute.

  • feature (int) – Column of the matrix used by the split.

  • threshold (float or object) – Threshold (numerical split) or value (categorical split).

  • is_categorical (bool) – Whether the split is categorical.

  • gain (float) – Gain of the split: the stumps with the highest gain are chosen with stump_selection=’best’.

  • impurity (list of float or None) – Impurity of the node and of the two children, if computed.

See also

RuleTreeBaseGainSplitter

a simpler interface, where only the gain of a split is defined.

RuleTree.stumps.Stump.Stump

the stump that combines a transformer and a splitter.

Examples

A splitter that splits the first numerical feature at its median (see Extending the library):

>>> import numpy as np
>>> from RuleTree.base.RuleTreeBaseSplitter import RuleTreeBaseSplitter
>>> from RuleTree.utils.define import MODEL_TYPE_REG
>>> class MedianSplitter(RuleTreeBaseSplitter):
...     task = MODEL_TYPE_REG
...
...     def fit(self, X, y, numerical, categorical, sample_weight=None, check_input=True):
...         self.feature_ = numerical[0]
...         self.threshold_ = float(np.median(X[:, self.feature_]))
...         self.is_categorical_, self.gain_, self.impurity_ = False, 0.0, None
...         return self
>>> X = np.array([[1.0], [2.0], [3.0], [4.0]])
>>> MedianSplitter().fit(X, None, numerical=[0], categorical=[]).apply(X)
array([1, 1, 2, 2])
task = None
abstractmethod fit(X: ndarray, y: ndarray, numerical: list, categorical: list, sample_weight=None, check_input=True)[source]

Find the best split of X.

Parameters:

  • X (numpy.ndarray of shape (n_samples, n_features)) – Feature matrix of the instances in the node.

  • y (numpy.ndarray of shape (n_samples,)) – Target of the instances in the node.

  • numerical (list of int) – Indices of the numerical columns of X.

  • categorical (list of int) – Indices of the categorical columns of X.

  • sample_weight (numpy.ndarray of shape (n_samples,), default=None) – Sample weights of the instances in the node.

  • check_input (bool, default=True) – Whether to check the input data.

Returns:

self – The fitted splitter.

Return type:

RuleTreeBaseSplitter

Raises:

NoSplitFoundWarning – If no split is found.

apply(X: ndarray) → ndarray[source]

Apply the split to a feature matrix.

Parameters:

X (numpy.ndarray of shape (n_samples, n_features)) – Feature matrix.

Returns:

labels – For each row, 1 if it goes to the left child, 2 otherwise.

Return type:

numpy.ndarray of int

update_statistics(X: ndarray, y: ndarray, sample_weight=None)[source]

Recompute the statistics of the split (e.g. impurity) on new data, without changing the split. The default implementation does nothing.

Parameters:

  • X (numpy.ndarray of shape (n_samples, n_features)) – Feature matrix of the instances in the node.

  • y (numpy.ndarray of shape (n_samples,)) – Target of the instances in the node.

  • sample_weight (numpy.ndarray of shape (n_samples,), default=None) – Sample weights of the instances in the node.

get_state() → dict[source]

Fitted state of the splitter: the attributes listed in _state.

Returns:

state – JSON-friendly dictionary, restored by set_state().

Return type:

dict

set_state(state: dict)[source]

Restore the fitted state saved by get_state().

Parameters:

state (dict) – Dictionary created by get_state().

Returns:

self

Return type:

RuleTreeBaseSplitter

set_fit_request(*, categorical: bool | None | str = '$UNCHANGED$', check_input: bool | None | str = '$UNCHANGED$', numerical: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → RuleTreeBaseSplitter

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:

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

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

  • numerical (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for numerical 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.base.RuleTreeBaseGainSplitter module#

Base class of the splitters defined by a gain function: the simplest way to write a new splitter.

class RuleTreeBaseGainSplitter[source]

Bases: RuleTreeBaseSplitter, ABC

Base class of the splitters that test every candidate split and keep the one with the highest gain: a new splitter only defines the task (task) and the gain of a split (gain()).

The candidate splits are the thresholds halfway between consecutive distinct values of each numerical feature (x <= threshold goes left) and the values of each categorical feature (x == value goes left). Splits with fewer than min_samples_leaf instances on a side are skipped. The search is exhaustive and not optimized: gain is called once per candidate.

Variables:

min_samples_leaf (int) – Minimum number of instances on each side of a split. 1 unless the subclass sets it (e.g. as a parameter of __init__).

See also

RuleTreeBaseSplitter

the attributes set by fit.

Examples

>>> import numpy as np
>>> from RuleTree.base.RuleTreeBaseGainSplitter import RuleTreeBaseGainSplitter
>>> from RuleTree.utils.define import MODEL_TYPE_CLF
>>> class MisclassificationSplitter(RuleTreeBaseGainSplitter):
...     task = MODEL_TYPE_CLF
...
...     def gain(self, y, left, sample_weight=None):
...         # decrease of the number of errors when each side predicts its majority class
...         errors = lambda labels: len(labels) - np.unique(labels, return_counts=True)[1].max()
...         return errors(y) - errors(y[left]) - errors(y[~left])
>>> X = np.array([[1.0], [2.0], [3.0], [4.0]])
>>> splitter = MisclassificationSplitter().fit(X, np.array([0, 0, 1, 1]), numerical=[0], categorical=[])
>>> splitter.feature_, splitter.threshold_
(0, 2.5)
min_samples_leaf = 1
abstractmethod gain(y: ndarray, left: ndarray, sample_weight=None) → float[source]

Gain of a candidate split: the higher, the better.

Parameters:

  • y (numpy.ndarray of shape (n_samples,)) – Target of the instances in the node.

  • left (numpy.ndarray of bool of shape (n_samples,)) – Instances that go to the left child.

  • sample_weight (numpy.ndarray of shape (n_samples,), default=None) – Sample weights of the instances in the node.

Returns:

gain

Return type:

float

candidate_thresholds(x: ndarray) → ndarray[source]

Thresholds tested on a numerical feature: halfway between its consecutive distinct values.

Parameters:

x (numpy.ndarray of shape (n_samples,)) – Values of the feature.

Returns:

thresholds

Return type:

numpy.ndarray

fit(X, y, numerical, categorical, sample_weight=None, check_input=True)[source]

Test every candidate split and keep the one with the highest gain.

Parameters:

  • X (numpy.ndarray of shape (n_samples, n_features)) – Feature matrix of the instances in the node.

  • y (numpy.ndarray of shape (n_samples,)) – Target of the instances in the node.

  • numerical (list of int) – Indices of the numerical columns of X.

  • categorical (list of int) – Indices of the categorical columns of X.

  • sample_weight (numpy.ndarray of shape (n_samples,), default=None) – Sample weights of the instances in the node, passed to gain.

  • check_input (bool, default=True) – Not used.

Returns:

self – The fitted splitter.

Return type:

RuleTreeBaseGainSplitter

Raises:

NoSplitFoundWarning – If no candidate split has at least min_samples_leaf instances on each side.

set_fit_request(*, categorical: bool | None | str = '$UNCHANGED$', check_input: bool | None | str = '$UNCHANGED$', numerical: bool | None | str = '$UNCHANGED$', sample_weight: bool | None | str = '$UNCHANGED$') → RuleTreeBaseGainSplitter

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:

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

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

  • numerical (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for numerical 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.base.RuleTreeBaseTransformer module#

Abstract base class of the transformers: the component of a stump that turns the data of one type (tabular data, time series, images, …) into the feature matrix split by the stump’s splitter (see RuleTreeBaseSplitter).

class RuleTreeBaseTransformer[source]

Bases: BaseEstimator, ABC

Abstract base class of the transformers, the component of a stump that turns the data of one type into a feature matrix.

A new transformer implements transform() and, if it learns something from the data, fit() (and get_state()/set_state() to be saved with the tree).

A transformer is fitted on the whole data set of its type (X, all the instances) and on idx, the instances reaching the node, so that values computed on the whole data set can be shared among the splits through cache (a dictionary that lives as long as the tree’s cache).

After the splitter has chosen a feature, select() lets the transformer keep only what is needed to compute that feature (e.g. a single pivot); if the feature matrix changes, refit_after_select is True and the stump fits the splitter again on the new matrix.

Transformers are scikit-learn estimators: their parameters are the arguments of __init__.

Variables:

  • supported_data_types (tuple of str) – Data types the transformer can be fitted on. Class attribute.

  • refit_after_select (bool) – Whether select() changes the feature matrix. Class attribute.

  • numerical (list of int) – Indices of the numerical columns of the feature matrix. Set by fit().

  • categorical (list of int) – Indices of the categorical columns of the feature matrix. Set by fit().

See also

RuleTree.stumps.Stump.Stump

the stump that combines a transformer and a splitter.

RuleTreeBaseSplitter

the other component of a stump.

Examples

A transformer without fitted state defines only transform (see Extending the library):

>>> import numpy as np
>>> from RuleTree import RuleTreeClassifier
>>> from RuleTree.base.RuleTreeBaseTransformer import RuleTreeBaseTransformer
>>> from RuleTree.stumps.Stump import Stump
>>> from RuleTree.stumps.splitters import ClassificationSplitter
>>> from RuleTree.utils.define import DATA_TYPE_TS
>>> class MeanTransformer(RuleTreeBaseTransformer):
...     supported_data_types = (DATA_TYPE_TS,)
...
...     def transform(self, X):
...         return X.mean(axis=2)  # mean of each signal
...
...     def feature_id(self, feature):
...         return f"mean_{feature}"
>>> rng = np.random.default_rng(0)
>>> y = rng.integers(0, 2, size=50)
>>> X_ts = rng.normal(size=(50, 1, 20)) + 2 * y[:, None, None]
>>> stump = Stump(MeanTransformer(), ClassificationSplitter())
>>> model = RuleTreeClassifier(max_depth=1, base_stumps=stump).fit(X_ts=X_ts, y=y)
>>> model.get_rules()["textual_rule"].split()[0]
'mean_0'
supported_data_types = ('tabular',)
refit_after_select = False
fit(X: ndarray, y: ndarray, idx: ndarray = None, data_type: str = None, cache: dict = None, sample_weight=None)[source]

Fit the transformer and set numerical_ and categorical_.

The default implementation, for transformers without fitted state, only sets the types of the columns of transform(X): such a transformer implements just transform().

Parameters:

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

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

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

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

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

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

Returns:

self – The fitted transformer.

Return type:

RuleTreeBaseTransformer

Raises:

NoSplitFoundWarning – If the data of the node cannot be transformed into features (e.g. no numerical feature).

abstractmethod transform(X: ndarray) → ndarray[source]

Feature matrix of the instances in X.

Parameters:

X (numpy.ndarray) – Data of the transformer’s type.

Returns:

X_transformed – Feature matrix.

Return type:

numpy.ndarray of shape (n_samples, n_features)

select(feature: int) → int[source]

Keep only what is needed to compute feature, the column chosen by the splitter. The default implementation keeps everything.

Parameters:

feature (int) – Column of the feature matrix chosen by the splitter.

Returns:

feature – Index of the feature in the matrix returned by transform() from now on.

Return type:

int

feature_id(feature: int)[source]

Identifier of a feature of the matrix in the rules, e.g. a column of the data or a pivot. The default implementation is the index of the column.

Parameters:

feature (int) – Column of the feature matrix.

Returns:

feature_id – Identifier shown in the rules (e.g. X_3) and stored in feature_original.

Return type:

int or str

get_state() → dict[source]

Fitted state needed by transform(). The default implementation is an empty state.

Returns:

state – JSON-friendly dictionary, restored by set_state().

Return type:

dict

set_state(state: dict)[source]

Restore the fitted state saved by get_state().

Parameters:

state (dict) – Dictionary created by get_state().

Returns:

self

Return type:

RuleTreeBaseTransformer

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

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

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

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

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

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

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

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

Added in version 1.3.

Parameters:

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

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

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

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

Returns:

self – The updated object.

Return type:

object

get_feature_types(X: ndarray, cache: dict = None, data_type: str = None) → tuple[list, list][source]

Indices of the numerical and of the categorical columns of a 2D matrix.

Parameters:

  • X (numpy.ndarray of shape (n_samples, n_features)) – Feature matrix.

  • cache (dict, default=None) – If given, the result is stored under ("feature_types", data_type), so that it is computed once per data type.

  • data_type (str, default=None) – Type of the data X comes from.

Returns:

  • numerical (list of int) – Indices of the numerical columns.

  • categorical (list of int) – Indices of the categorical columns.

Module contents#