TreeClassifier

class sklearn_nominal.TreeClassifier(criterion='entropy', splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, min_error_decrease=1e-16, class_weight=None, attribute_penalization_importance=1, nominal_split='multi', backend='pandas')

A decision tree classifier with support for nominal attributes.

A decision tree classifier that mimics scikit-learn’s sklearn.tree.DecisionTreeClassifier but adds support for nominal attributes.

Args:

criterion (str): The function to measure the quality of a split.

Supported criteria are “gini” for the Gini impurity and “log_loss” and “entropy” both for the Shannon information gain, and “gain_ratio”

for “entropy” regularized by the intrinsic information of the split. Defaults to “entropy”.

class_weight (dict or “balanced”, optional): Weights associated with classes

in the form {class_label: weight}. If None, all classes are assumed to have weight one. Defaults to None.

splitter (str or int, optional): The strategy used to choose the split at

each numeric node. See BaseTree. Defaults to “best”.

max_depth (int, optional): The maximum depth of the tree. See BaseTree.

Defaults to None.

min_samples_split (int or float, optional): The minimum number of samples

required to split an internal node. See BaseTree. Defaults to 2.

min_samples_leaf (int or float, optional): The minimum number of samples

required to be at a leaf node. See BaseTree. Defaults to 1.

min_error_decrease (float, optional): Threshold for early stopping in tree

growth. See BaseTree. Defaults to 1e-16.

nominal_split (str, optional): The strategy used to split nominal attributes.

See BaseTree. Defaults to “multi”.

backend (str, optional): The backend to use for computations. Defaults to “pandas”.

Attributes:

classes_ (ndarray of shape (n_classes,)): The classes labels. n_classes_ (int): The number of classes. n_features_in_ (int): Number of features seen during fit. feature_names_in_ (ndarray of shape (n_features_in_,)): Names of features

seen during fit. Defined only when X has feature names that are all strings.

n_outputs_ (int): The number of outputs when fit is performed. tree_ (Tree): The underlying sklearn_nominal.tree.tree.Tree object.

See Also:

BaseTree: Base class for TreeClassifier and TreeRegressor. TreeRegressor: A decision tree regressor with nominal support. NaiveBayesClassifier: A NaiveBayesClassifier with nominal support.

Notes:

The predict() method operates using the numpy.argmax() function on the outputs of predict_proba(). This means that in case the highest predicted probabilities are tied, the classifier will predict the tied class with the lowest index in classes_.

Examples:

>>> from sklearn.datasets import fetch_openml
>>> df = fetch_openml("credit-g",version=2).frame
>>> x,y = df.iloc[:,0:-1], df.iloc[:,-1]
>>>
>>> from sklearn_nominal import TreeClassifier
>>> model = TreeClassifier(min_samples_leaf=0.01)
>>> model.fit(x,y)
>>>
>>> from sklearn.metrics import accuracy_score
>>> y_pred = model.predict(x)
>>> print(accuracy_score(y,y_pred))
... 0.787

Methods

build_attribute_penalizer()	Determines the penalization strategy for multi-valued attributes.
build_error(criterion, class_weight)	Builds the error function for the given criterion.
build_prune_criteria(d)	Translates tree constraints into internal pruning criteria.
build_splitter(e, p)	Constructs specialized split scorers for different column types.
check_is_fitted()	Checks if the model has been fitted.
complexity()	Returns the complexity of the fitted model.
display([class_names, title])	Displays the tree using the default system viewer or notebook output.
export_dot([class_names, title])	Exports the tree as a Graphviz dot string.
export_dot_file(filepath[, class_names, title])	Exports the tree as a Graphviz dot file.
export_image(filepath[, class_names, title])	Exports the tree as an image file.
fit(x, y)	Fit the decision tree classifier according to the given training data.
get_class_weights(y)	Computes the class weights based on the input target.
get_dtypes(x)	Extracts and maps data types from the input.
get_feature_names()	Returns the names of the features seen during fit.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
get_y(y)	Validates and encodes the target labels.
make_model(d, class_weight)	Creates the Tree trainer for the model.
predict(x)	Perform classification on an array of test vectors X.
predict_proba(x)	Return probability estimates for the test data X.
pretty_print([class_names])	Returns a string representation of the fitted model.
score(X, y[, sample_weight])	Return the mean accuracy on the given test data and labels.
set_dtypes(x)	Sets and persists the data types based on the input.
set_fit_request(*[, x])	Request metadata passed to the fit method.
set_model(model)	Sets the underlying backend model and marks it as fitted.
set_params(**params)	Set the parameters of this estimator.
set_predict_proba_request(*[, x])	Request metadata passed to the predict_proba method.
set_predict_request(*[, x])	Request metadata passed to the predict method.
set_score_request(*[, sample_weight])	Request metadata passed to the score method.
set_sklearn_tags(tags)	Sets scikit-learn tags for the supervised nominal model.
validate_data_fit_classification(x, y)	Validates and transforms data for classification fitting.
validate_data_predict(x)	Validates and prepares input data for prediction.

build_attribute_penalizer()

Determines the penalization strategy for multi-valued attributes.

This is used to implement “gain_ratio”, which penalizes nominal attributes with many levels to prevent overfitting.

Returns:

sklearn_nominal.shared.ColumnPenalization

The penalization strategy (e.g., GainRatioPenalization or NoPenalization).

build_error(criterion, class_weight)

Builds the error function for the given criterion.

Parameters:

criterionstr

The error criterion to use (e.g., “entropy”, “gini”, “gain_ratio”).

class_weightnp.ndarray

The class weights to be used by the error function.

Returns:

TargetError

An instance of the requested error function from sklearn_nominal.shared.

Raises:

ValueError

If the criterion is not recognized.

Return type:

TargetError

build_prune_criteria(d)

Translates tree constraints into internal pruning criteria.

This method converts user-facing parameters (which can be counts or fractions) into the absolute integer values required by the tree builders.

Parameters:

dDataset

The dataset used to calculate relative sample counts.

Returns:

PruneCriteria

The consolidated criteria used for pruning.

Return type:

PruneCriteria

build_splitter(e, p)

Constructs specialized split scorers for different column types.

This method maps the general splitter and criterion parameters into concrete ColumnError implementations for both Numeric and Nominal features.

Parameters:

esklearn_nominal.shared.TargetError

The target error function (e.g., Gini, Entropy, or MSE).

psklearn_nominal.shared.ColumnPenalization

The column-level penalization strategy.

Returns:

dict

A dictionary mapping ColumnType to its corresponding ColumnError scorer.

Raises:

ValueError

If the splitter value is neither “best” nor an integer, or if nominal_split is invalid.

check_is_fitted()

Checks if the model has been fitted.

Raises:

NotFittedError

If the is_fitted_ attribute is not set or is False.

complexity()

Returns the complexity of the fitted model.

The definition of complexity is backend and model dependent. For trees, it typically represents the number of nodes.

Returns:

int or float

The complexity metric of the model.

Raises:

NotFittedError

If the model has not been fitted yet.

display(class_names=None, title='')

Displays the tree using the default system viewer or notebook output.

Parameters:

class_nameslist of str, optional

The names of the classes for display.

titlestr, default=””

The title for the graph.

Returns:

Any

The image object for display in interactive environments.

export_dot(class_names=None, title='')

Exports the tree as a Graphviz dot string.

Parameters:

class_nameslist of str, optional

The names of the classes for display.

titlestr, default=””

The title for the graph.

Returns:

str

The tree in Graphviz dot format.

export_dot_file(filepath, class_names=None, title='')

Exports the tree as a Graphviz dot file.

Parameters:

filepathstr

The path to the file to save.

class_nameslist of str, optional

The names of the classes for display.

titlestr, default=””

The title for the graph.

export_image(filepath, class_names=None, title='')

Exports the tree as an image file.

This requires Graphviz to be installed on the system.

Parameters:

filepathstr

The path to the image file (e.g., “tree.png”).

class_nameslist of str, optional

The names of the classes for display.

titlestr, default=””

The title for the graph.

fit(x, y)

Fit the decision tree classifier according to the given training data.

This algorithm builds a classification tree using recursive partitioning. At each node, it selects the feature and the split (numeric or nominal) that maximizes the chosen criterion (e.g., Shannon information gain). For nominal attributes, it creates a multi- way split corresponding to the attribute’s categories.

Args:

x (pd.DataFrame or np.ndarray): The training input samples. y (np.ndarray): The target values (class labels) as integers or strings.

Returns:

self: Returns the instance itself.

get_class_weights(y)

Computes the class weights based on the input target.

Parameters:

yarray-like of shape (n_samples,)

The target labels.

Returns:

np.ndarray

The computed weights for each class, aligned with self.classes_.

get_dtypes(x)

Extracts and maps data types from the input.

This method identifies the data types of the input features to ensure they are correctly handled by the backend.

Parameters:

x{array-like, sparse matrix} of shape (n_samples, n_features)

The input data.

Returns:

dict or None

A dictionary mapping column names to data types if x is a DataFrame, otherwise None.

get_feature_names()

Returns the names of the features seen during fit.

Returns:

ndarray of str or None

The feature names, or None if they were not available during fit (e.g., if input was a numpy array).

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

get_y(y)

Validates and encodes the target labels.

Parameters:

yarray-like of shape (n_samples,)

The target labels to encode.

Returns:

ndarray

The integer-encoded target labels.

make_model(d, class_weight)

Creates the Tree trainer for the model.

Args:

d (Dataset): The dataset to train on. class_weight (np.ndarray): The weights for each class.

Returns:

BaseTreeTrainer: The tree trainer instance.

predict(x)

Perform classification on an array of test vectors X.

Predictions are made by traversing the decision tree from the root to a leaf node according to the feature values of each input sample. Ties in leaf node probabilities are resolved by choosing the class with the lowest index in classes_.

Args:

x (pd.DataFrame or np.ndarray): The input samples.

Returns:

np.ndarray: Predicted target values for X.

predict_proba(x)

Return probability estimates for the test data X.

Probabilities are estimated as the class distribution observed at the leaf node reached by traversing the tree for each input sample.

Args:

x (pd.DataFrame or np.ndarray): The input samples.

Returns:

np.ndarray: Returns the probability of the sample for each class

in the model.

pretty_print(class_names=None)

Returns a string representation of the fitted model.

Delegates the visualization logic to the underlying backend model.

Parameters:

class_nameslist of str, optional

Names of the classes to use in the output. If None, default identifiers are used.

Returns:

str

A human-readable representation of the model.

Raises:

NotFittedError

If the model has not been fitted yet.

score(X, y, sample_weight=None)

Return the mean accuracy on the given test data and labels.

In multi-label classification, this is the subset accuracy which is a harsh metric since you require for each sample that each label set be correctly predicted.

Parameters:

Xarray-like of shape (n_samples, n_features)

Test samples.

yarray-like of shape (n_samples,) or (n_samples, n_outputs)

True labels for X.

sample_weightarray-like of shape (n_samples,), default=None

Sample weights.

Returns:

scorefloat

Mean accuracy of self.predict(X) w.r.t. y.

set_dtypes(x)

Sets and persists the data types based on the input.

This is called during fit to ensure that subsequent calls to predict can cast the input data to the same types, preserving nominal/numeric distinctions.

Parameters:

x{pd.DataFrame, np.ndarray, sparse matrix}

The input data to extract types from.

Raises:

ValueError

If the input type is not supported or if the input is not 2D.

set_fit_request(*, x: bool | None | str = '$UNCHANGED$') → TreeClassifier

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in fit.

Returns:

selfobject

The updated object.

set_model(model)

Sets the underlying backend model and marks it as fitted.

Parameters:

modelsklearn_nominal.backend.core.Model

The trained model instance from the backend.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.

set_predict_proba_request(*, x: bool | None | str = '$UNCHANGED$') → TreeClassifier

Request metadata passed to the predict_proba method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to predict_proba 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_proba.

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

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in predict_proba.

Returns:

selfobject

The updated object.

set_predict_request(*, x: bool | None | str = '$UNCHANGED$') → TreeClassifier

Request metadata passed to the predict method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

xstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for x parameter in predict.

Returns:

selfobject

The updated object.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → TreeClassifier

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to score 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 score.

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

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_weight parameter in score.

Returns:

selfobject

The updated object.

set_sklearn_tags(tags)

Sets scikit-learn tags for the supervised nominal model.

Parameters:

tagsTags

The scikit-learn tags object to be modified.

validate_data_fit_classification(x, y)

Validates and transforms data for classification fitting.

This method performs the following transformations: 1. Validates x and y using scikit-learn’s validate_data. 2. Determines the unique classes and stores them in classes_. 3. Encodes y using LabelEncoder. 4. Calculates class weights based on the class_weight parameter. 5. Packages features and the encoded target into a backend-specific

Dataset (e.g., PandasDataset).

Parameters:

xarray-like of shape (n_samples, n_features)

The input features.

yarray-like of shape (n_samples,) or (n_samples, n_outputs)

The target labels.

Returns:

tuple

A tuple containing: - Dataset : The backend-specific dataset object. - np.ndarray : The computed class weights for each class in classes_.

Raises:

ValueError

If y contains only one unique class.

Return type:

tuple[Dataset, ndarray]

validate_data_predict(x)

Validates and prepares input data for prediction.

This method ensures the input features match the structure seen during training, handles feature name alignment, and restores data types.

Parameters:

xarray-like of shape (n_samples, n_features)

The input data to validate.

Returns:

pd.DataFrame

The validated data as a pandas DataFrame, with dtypes restored to match those observed during training.

Raises:

NotFittedError

If the model has not been fitted yet.

ValueError

If the input contains no samples or has inconsistent features.