Zuffy Fit Iterator

This module contains the ZuffyFitIterator, a scikit-learn compatible meta-estimator that repeatedly fits a classifier and builds Fuzzy Pattern Trees to find an optimal model.

class zuffy.zuffy_fit_iterator.ZuffyFitIterator(model: Any, tags: List[str] = ['lo', 'med', 'hi'], show_fuzzy_range: bool = True, n_iter: int = 5, test_size: float = 0.2, random_state: int | RandomState | None = None)

Bases: BaseEstimator

Iteratively trains a Zuffy classifier on fuzzified data and tracks performance metrics.

This class runs multiple randomised train/test splits, fuzzifies the data within each split, and then trains a Zuffy classifier (or a GridSearchCV wrapper) to find the best-performing model across iterations. It considers both accuracy and model complexity (tree size) for model selection.

Parameters

modelestimator object

A Zuffy classifier that follows scikit-learn’s API. This can also be a GridSearchCV object wrapping a Zuffy classifier.

tagslist of str, default=[‘lo’, ‘med’, ‘hi’]

A list of string tags to use for fuzzification, representing the names of the fuzzy sets (e.g., low, medium, high). These are passed directly to the FuzzyTransformer.

show_fuzzy_rangebool, default=True

If True, the names of the output fuzzy features will include the numerical range (e.g., ‘low feature_name (0.00 to 5.00)’). If False, only the tag and feature name will be used (e.g., ‘low feature_name’). This parameter is passed directly to the FuzzyTransformer.

n_iterint, default=5

The number of random splits and evaluations to perform. A higher value increases the robustness of the results but also increases computation time.

test_sizefloat, default=0.2

The proportion of the dataset to include in the test split for each iteration. Must be between 0.0 and 1.0.

random_stateint or None, default=None

Controls the randomness of the train/test splits. - Pass an int for reproducible output across multiple function calls. - Pass None (default) for a different random state each time.

Attributes

best_estimator_object

The best trained model (estimator) found across all iterations. This will be a Zuffy classifier or the best_estimator_ from GridSearchCV if used.

best_score_float

The overall score achieved by the best_estimator_ on its respective test set (accuracy).

iteration_performance_list of tuples

A list containing the performance metrics for each iteration. Each tuple contains:

• score (float): The overall accuracy of the model on the test set.

• tree_size (int): The total number of nodes in the Zuffy tree(s).

• class_scores_dict (dict): A dictionary mapping class labels to their individual accuracy scores for that iteration.

best_iteration_index_int

The index of the iteration (0-based) that yielded the best_estimator_.

smallest_tree_size_int

The size (total number of nodes) of the tree in the best_estimator_. If best_estimator_ is a GridSearchCV, this refers to the size of the best model found within GridSearchCV.

fuzzy_feature_names_list of str

The names of the features after fuzzification, derived from the FuzzyTransformer associated with the best_estimator_. This attribute is set during the fit method.

feature_names_in_ndarray of str

Names of features seen during fit. Defined only when X has feature names that are all strings (e.g., a Pandas DataFrame).

n_features_in_int

The number of features seen during fit.

_parameter_constraints: dict = {'n_iter': [<sklearn.utils._param_validation.Interval object>], 'random_state': ['random_state'], 'show_fuzzy_range': [<class 'bool'>], 'tags': [<class 'list'>], 'test_size': [<sklearn.utils._param_validation.Interval object>]}

_perform_single_fit_job(model: Any, X: ndarray | DataFrame, y: ndarray, test_size: float = 0.2, random_state: int | None = None) → Tuple[float, Any, Dict[Any, float], FuzzyTransformer]

Performs a single iteration of data splitting, fuzzification, model training, and evaluation.

This private method handles one randomised train/test split, fuzzifies the resulting data, trains the provided model, and calculates performance metrics.

Parameters

modelestimator object

A Zuffy classifier or GridSearchCV object to be trained.

Xarray-like of shape (n_samples, n_features)

The input features for this single job.

yarray-like of shape (n_samples,)

The target labels for this single job.

test_sizefloat, default=0.2

The proportion of the dataset to include in the test split.

random_stateint or None, default=None

The random seed for the train_test_split.

Returns

scorefloat

The overall accuracy score of the fitted model on the test set.

fitted_modelobject

The trained model (either the base Zuffy classifier or the best_estimator_ from GridSearchCV).

class_scoresdict

A dictionary where keys are class labels and values are their corresponding accuracy scores on the test set for this iteration.

fuzz_transformerFuzzyTransformer

The fitted FuzzyTransformer used in this specific iteration.

_verbose_out(*msg: str) → None

Prints messages if the model’s ‘verbose’ attribute is True.

This method checks the ‘verbose’ attribute on the contained model (e.g., ZuffyClassifier or GridSearchCV) to control output.

fit(X: ndarray | DataFrame, y: ndarray, feature_names: List[str] | None = None, non_fuzzy: List[str] | None = None) → ZuffyFitIterator

Fits the ZuffyFitIterator by running multiple training iterations.

This method orchestrates the iterative training process: 1. Validates input data X and y. 2. Performs n_iter randomised train/test splits. 3. For each split, fuzzifies the data using FuzzyTransformer. 4. Trains the model (or GridSearchCV) on the fuzzified training data. 5. Evaluates the trained model on the fuzzified test data. 6. Tracks performance metrics (score, tree size, per-class accuracies). 7. Selects the best_estimator_ based on overall score, then smallest tree size.

Parameters

Xarray-like of shape (n_samples, n_features) or pd.DataFrame

The input features (unfuzzified) to be used for training and testing.

yarray-like of shape (n_samples,)

The target labels corresponding to X.

feature_nameslist of str, optional

A list of strings representing the names of the features in X. If X is a Pandas DataFrame and feature_names is None, X.columns will be used. If X is a NumPy array and feature_names is None, generic names (e.g., ‘X0’, ‘X1’) will be generated.

non_fuzzylist of str, optional

A list of feature names that should NOT be fuzzified. These columns will be passed through directly to the model after one-hot encoding by the FuzzyTransformer.

Returns

selfZuffyFitIterator

The fitted instance of the ZuffyFitIterator.

get_best_class_accuracy() → str | int | None

Returns the class label with the highest accuracy in the best iteration.

Returns

best_classstr or int or None

Class label with the highest accuracy in the best iteration. Returns None if no class scores are available.

set_fit_request(*, feature_names: bool | None | str = '$UNCHANGED$', non_fuzzy: bool | None | str = '$UNCHANGED$') → ZuffyFitIterator

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.

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

Metadata routing for feature_names parameter in fit.

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

Metadata routing for non_fuzzy parameter in fit.

selfobject

The updated object.