RuleTree.utils package

RuleTree.utils package#

Subpackages#

Submodules#

RuleTree.utils.bic_estimator module#

Bayesian Information Criterion of a partition of the data into Gaussian clusters, used by RuleTreeCluster to decide whether a split improves the clustering.

estimate_gaussian_covariances(X, nk, means, resp, reg_covar=1e-06)[source]#

Estimate the full covariance matrices.

Parameters:

resp (array-like of shape (n_samples, n_components))
X (array-like of shape (n_samples, n_features))
nk (array-like of shape (n_components,))
means (array-like of shape (n_components, n_features))
reg_covar (float)

Returns:

covariances – The covariance matrix of the current components.

Return type:

array, shape (n_components, n_features, n_features)

estimate_parameters(X, resp)[source]#

Weights, means and covariances of the Gaussian components from the responsibilities.

Parameters:

X (numpy.ndarray of shape (n_samples, n_features)) – Data.
resp (numpy.ndarray of shape (n_samples, n_components)) – Responsibility of each component for each instance.

Returns:

nk (numpy.ndarray of shape (n_components,)) – Weight of each component.
means (numpy.ndarray of shape (n_components, n_features))
covariances (numpy.ndarray of shape (n_components, n_features, n_features))

compute_precision_cholesky(covariances)[source]#

Compute the Cholesky decomposition of the precisions.

Parameters:: covariances (array-like) – The covariance matrix of the current components. The shape depends of the covariance_type.
Returns:: precisions_cholesky – The cholesky decomposition of sample precisions of the current components. The shape depends of the covariance_type.
Return type:: array-like

estimate_weighted_log_prob(X, means, precisions_chol, weights)[source]#

Estimate the weighted log-probabilities, log P(X | Z) + log weights.

Parameters:: X (array-like of shape (n_samples, n_features))
Returns:: weighted_log_prob
Return type:: array, shape (n_samples, n_component)

estimate_log_prob(X, means, precisions_chol)[source]#

Estimate the log Gaussian probability.

Parameters:

X (array-like of shape (n_samples, n_features))
means (array-like of shape (n_components, n_features))
precisions_chol (array-like)

Returns:

log_prob

Return type:

array, shape (n_samples, n_components)

compute_log_det_cholesky(matrix_chol, n_features)[source]#

Compute the log-det of the cholesky decomposition of matrices.

Parameters:

matrix_chol (array-like) – Cholesky decompositions of the matrices.
n_features (int) – Number of features.

Returns:

log_det_precision_chol – The determinant of the precision matrix for each component.

Return type:

array-like of shape (n_components,)

estimate_log_weights(weights)[source]#

Logarithm of the weights of the components.

Parameters:: weights (numpy.ndarray of shape (n_components,))
Returns:: log_weights
Return type:: numpy.ndarray of shape (n_components,)

score_samples(X, means, precisions_chol, weights)[source]#

Compute the log-likelihood of each sample.

Parameters:: X (array-like of shape (n_samples, n_features)) – List of n_features-dimensional data points. Each row corresponds to a single data point.
Returns:: log_prob – Log-likelihood of each sample in X under the current model.
Return type:: array, shape (n_samples,)

score(X, n_components, labels)[source]#

Compute the per-sample average log-likelihood of the given data X.

Parameters:: X (array-like of shape (n_samples, n_dimensions)) – List of n_features-dimensional data points. Each row corresponds to a single data point.
Returns:: log_likelihood – Log-likelihood of X under the Gaussian mixture model.
Return type:: float

get_n_parameters(X, n_components)[source]#

Number of free parameters of a Gaussian mixture with full covariance matrices.

Parameters:

X (numpy.ndarray of shape (n_samples, n_features)) – Data.
n_components (int) – Number of components (clusters).

Returns:

n_parameters – Parameters of the covariances, of the means and of the weights.

Return type:

int

bic(X, labels)[source]#

Bayesian information criterion for the current model on the input X. You can refer to this mathematical section for more details regarding the formulation of the BIC used.

Parameters:: X (array of shape (n_samples, n_dimensions)) – The input samples.
Returns:: bic – The lower the better.
Return type:: float

RuleTree.utils.data_utils module#

Utility functions for data preprocessing, transformation, and metrics calculation for the RuleTree library. This module contains helper functions for handling categorical and numerical features, calculating information gain metrics, and performing data encoding/decoding operations.

preprocessing(X, feature_names_r, is_cat_feat, data_encoder=None, numerical_scaler=None)[source]#

Preprocess data by applying encoding and scaling transformations.

Parameters:

X (numpy.ndarray) – Input data matrix to be preprocessed
feature_names_r (list) – Names of features in the original feature space
is_cat_feat (numpy.ndarray) – Boolean array indicating which features are categorical
data_encoder (category_encoders object, optional) – Encoder for transforming categorical features
numerical_scaler (sklearn.preprocessing scaler, optional) – Scaler for normalizing numerical features

Returns:

Preprocessed data

Return type:

numpy.ndarray

inverse_preprocessing(X, is_cat_feat, data_encoder=None, numerical_scaler=None)[source]#

Inverse the preprocessing operation to restore original data format.

Parameters:

X (numpy.ndarray) – Input data matrix in preprocessed form
is_cat_feat (numpy.ndarray) – Boolean array indicating which features are categorical
data_encoder (category_encoders object, optional) – Encoder used in the preprocessing step
numerical_scaler (sklearn.preprocessing scaler, optional) – Scaler used in the preprocessing step

Returns:

Data in original feature space

Return type:

numpy.ndarray

prepare_data(X_original, max_nbr_values, max_nbr_values_cat, feature_names_original, one_hot_encode_cat, categorical_indices, numerical_indices, numerical_scaler)[source]#

Prepare data for RuleTree by handling categorical features and applying preprocessing.

This function identifies categorical features, optionally one-hot encodes them, scales numerical features, and creates mapping dictionaries for feature transformation.

Parameters:

X_original (numpy.ndarray) – Original input data matrix
max_nbr_values (int) – Maximum number of values for binning continuous features
max_nbr_values_cat (int) – Maximum number of unique values for a feature to be considered categorical
feature_names_original (list) – Original feature names
one_hot_encode_cat (bool) – Whether to one-hot encode categorical features
categorical_indices (list, optional) – Indices of features known to be categorical
numerical_indices (list, optional) – Indices of features known to be numerical
numerical_scaler (sklearn.preprocessing scaler, optional) – Scaler to apply to numerical features

Returns:

(X, features, maps) - X: preprocessed data matrix - features: tuple containing feature information - maps: dictionary with mappings between original and one-hot encoded features

Return type:

tuple

Raises:

Exception – If provided categorical and numerical indices don’t match the dataset dimensions

calculate_mode(x: ndarray) → int | float | str[source]#

Calculate the mode (most frequent value) of an array.

Parameters:: x (numpy.ndarray) – Input array
Returns:: Most frequent value in the input array
Return type:: object

log_odds(class_counts: ndarray, n_samples: int) → ndarray[source]#

Compute the log-odds log(n_c / (n - n_c)) of each class.

Pure cases are handled explicitly instead of dividing by zero: a class with no samples gets -inf, a class with all the samples gets +inf, and an empty node gets nan.

Parameters:

class_counts (numpy.ndarray) – Number of samples of each class
n_samples (int) – Total number of samples

Returns:

Log-odds of each class

Return type:

numpy.ndarray

get_info_gain(clf: DecisionTreeClassifier | DecisionTreeRegressor)[source]#

Calculate information gain from a decision tree split.

Parameters:: clf (DecisionTreeClassifier or DecisionTreeRegressor) – Fitted decision tree classifier or regressor
Returns:: Information gain achieved by the split
Return type:: float

get_gain_ratio(clf: DecisionTreeClassifier | DecisionTreeRegressor)[source]#

Calculate the gain ratio from a decision tree split.

Gain ratio is information gain divided by the split information, which normalizes the information gain to account for the number of splits.

Parameters:: clf (DecisionTreeClassifier or DecisionTreeRegressor) – Fitted decision tree classifier or regressor
Returns:: Gain ratio achieved by the split
Return type:: float

gini(x, sample_weight: ndarray = None, class_weight: dict = None)[source]#

Calculate the Gini impurity of an array.

Gini impurity measures the probability of incorrectly classifying a randomly chosen element if it were randomly labeled according to the distribution of classes.

Parameters:

x (numpy.ndarray) – Input array
sample_weight (numpy.ndarray, optional) – Sample weights to apply
class_weight (dict, optional) – Class weights to apply

Returns:

Gini impurity value

Return type:

float

entropy(x, sample_weight: ndarray = None, class_weight: dict = None)[source]#

Calculate the entropy of an array.

Entropy measures the average level of “information” or “uncertainty” inherent in the possible outcomes of a random variable.

Parameters:

x (numpy.ndarray) – Input array
sample_weight (numpy.ndarray, optional) – Sample weights to apply
class_weight (dict, optional) – Class weights to apply

Returns:

Entropy value

Return type:

float

select_stumps(node, p=0.2, selected_stumps=None)[source]#

Select decision stumps from a tree based on balance score threshold.

This function recursively traverses the tree and collects stumps that have a balance score above the specified threshold.

Parameters:

node (Node) – Current node in the tree
p (float, default=0.2) – Balance score threshold
selected_stumps (list, optional) – Accumulator for selected stumps during recursion

Returns:

Selected stumps that meet the balance score threshold

Return type:

list

class json_numpy_encoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]#

Bases: JSONEncoder

JSON encoder that handles NumPy data types.

This class extends the standard JSON encoder to properly serialize NumPy integers, floats, and arrays to their Python equivalents.

Examples

>>> import json
>>> import numpy as np
>>> from RuleTree.utils.data_utils import json_numpy_encoder
>>> json.dumps({"a": np.arange(3), "b": np.float32(0.5)}, cls=json_numpy_encoder)
'{"a": [0, 1, 2], "b": 0.5}'

default(obj)[source]#

Convert NumPy types to standard Python types for JSON serialization.

Parameters:: obj (object) – Object to be serialized
Returns:: Python equivalent of NumPy type
Return type:: object
Raises:: TypeError – If object is not a NumPy type and cannot be serialized by the parent class

RuleTree.utils.define module#

Constants of RuleTree.

MODEL_TYPE_CLF, MODEL_TYPE_REG, MODEL_TYPE_CLU: Tasks: classification, regression and clustering.
DATA_TYPE_TABULAR, DATA_TYPE_TS, DATA_TYPE_IMAGE, DATA_TYPE_TEXT: Data types: tabular data, time series, images and texts.
DATA_INPUT_TYPES: Data type of each input argument of fit and predict (X, X_ts, X_img, X_txt).
GRAPHVIZ_DEFAULT_NODE_SPLIT, GRAPHVIZ_DEFAULT_NODE_LEAF: Default Graphviz attributes of the internal nodes and of the leaves.

RuleTree.utils.fairness_metrics module#

Fairness and privacy metrics of a partition of the data, used by FairSplitter.

balance_metric(labels: ndarray, prot_attr: ndarray)[source]#

Computes the balance fairness metric between protected attributes and class labels.

The balance metric measures how evenly the protected attributes are distributed across different class labels. A value closer to 1 indicates better balance.

Parameters:

labels (np.ndarray) – Array of class labels for each instance
prot_attr (np.ndarray) – Array of protected attribute values for each instance

Returns:

Minimum balance ratio across all protected attribute and class label combinations. Values range from 0 to 1, with 1 indicating perfect balance.

Return type:

float

max_fairness_cost(labels: ndarray, prot_attr: ndarray, ideal_dist: dict)[source]#

Calculates the maximum fairness cost based on deviation from an ideal distribution.

This metric measures how far the actual distribution of protected attributes within each class is from an ideal (fair) distribution.

Parameters:

labels (np.ndarray) – Array of class labels for each instance
prot_attr (np.ndarray) – Array of protected attribute values for each instance
ideal_dist (dict) – Dictionary mapping protected attribute values to their ideal proportions

Returns:

Maximum fairness cost across all class labels. Lower values indicate distributions closer to the ideal fair distribution.

Return type:

float

privacy_metric(X, X_bool, sensible_attribute, k_anonymity, l_diversity, t_closeness, strict, categorical, use_t)[source]#

Evaluates privacy preservation based on k-anonymity, l-diversity, and t-closeness.

This function checks whether a split of the data satisfies specified privacy constraints.

Parameters:

X (array-like) – The dataset features
X_bool (array-like) – Boolean array indicating the split (True/False for each instance)
sensible_attribute (int or list) – Index or indices of the sensitive attribute(s) in X
k_anonymity (int or float) – Minimum required k-anonymity level. If float, interpreted as a proportion
l_diversity (int) – Minimum required l-diversity level
t_closeness (float) – Maximum allowed t-closeness value
strict (bool) – If True, enforces all privacy constraints strictly
categorical (bool) – Whether the sensitive attribute is categorical
use_t (bool) – Whether to compute and use t-closeness in the evaluation

Returns:

(is_valid, k, l, t) where: - is_valid: boolean indicating if privacy constraints are satisfied - k: achieved k-anonymity value - l: achieved l-diversity value - t: achieved t-closeness value or np.nan if not computed

Return type:

tuple

privacy_metric_all(k, k_thr, l, l_thr, t, t_thr)[source]#

Computes normalized privacy violations for k-anonymity, l-diversity, and t-closeness.

Parameters:

k (float) – Achieved k-anonymity value
k_thr (float) – Threshold for k-anonymity
l (float) – Achieved l-diversity value
l_thr (float) – Threshold for l-diversity
t (float) – Achieved t-closeness value
t_thr (float) – Threshold for t-closeness

Returns:

List of normalized violation scores for [k-anonymity, l-diversity, t-closeness]. Each score is 0 if the constraint is satisfied, otherwise it’s a positive value representing the degree of violation.

Return type:

list

RuleTree.utils.optional module#

Import of the optional dependencies, with an error that tells how to install them.

import_optional(module: str, feature: str)[source]#

Import an optional dependency.

Parameters:

module (str) – Module to import, a key of OPTIONAL_DEPENDENCIES or one of its submodules (e.g. "matplotlib.pyplot").
feature (str) – What needs the module, used in the error message (e.g. "ShapeletTransformer").

Returns:

module – The imported module.

Return type:

module

Raises:

MissingOptionalDependencyError – If the module is not installed.

Examples

>>> from RuleTree.utils.optional import import_optional
>>> import_optional("numba", "ShapeletTransformer").__name__
'numba'

RuleTree.utils.privacy_utils module#

k-anonymity, l-diversity and t-closeness of a partition of the data, used by the fairness metrics.

compute_k_anonimity(X, X_bool, sensible_attribute)[source]#

Compute k-anonymity values for left and right partitions of data.

K-anonymity ensures that each group contains at least k individuals with the same sensitive attribute value, making it difficult to identify a specific individual.

Parameters:

X (np.ndarray) – Feature matrix
X_bool (np.ndarray) – Boolean array indicating the split (True for left partition, False for right)
sensible_attribute (int) – Index of the sensitive attribute column

Returns:

(k_left, k_right) representing the k-anonymity values for both partitions

Return type:

tuple

compute_l_diversity(X, X_bool, sensible_attribute)[source]#

Compute l-diversity values for left and right partitions of data.

L-diversity ensures that sensitive attribute values are well-represented in each group, making it difficult to infer an individual’s sensitive attribute.

Parameters:

X (np.ndarray) – Feature matrix
X_bool (np.ndarray) – Boolean array indicating the split (True for left partition, False for right)
sensible_attribute (int) – Index of the sensitive attribute column

Returns:

(l_left, l_right) representing the l-diversity values for both partitions

Return type:

tuple

compute_t_closeness(X, X_bool, sensible_attribute, categorical)[source]#

Compute t-closeness values for left and right partitions of data.

Parameters:

X (np.ndarray) – Feature matrix
X_bool (np.ndarray) – Boolean array indicating the split (True for left partition, False for right)
sensible_attribute (int) – Index of the sensitive attribute column
categorical (list or set) – Indices of categorical features

Returns:

(t_left, t_right) representing the t-closeness values for both partitions

Return type:

tuple

Module contents#

bic(X, labels)[source]

Bayesian information criterion for the current model on the input X. You can refer to this mathematical section for more details regarding the formulation of the BIC used.

Parameters:: X (array of shape (n_samples, n_dimensions)) – The input samples.
Returns:: bic – The lower the better.
Return type:: float

RuleTree.utils package

Contents

RuleTree.utils package#

Subpackages#

Submodules#

RuleTree.utils.bic_estimator module#

RuleTree.utils.data_utils module#

RuleTree.utils.define module#

RuleTree.utils.fairness_metrics module#

RuleTree.utils.optional module#

RuleTree.utils.privacy_utils module#

Module contents#