Sample Programs

These examples provide an introduction to the Zuffy package and show some ideas of how it can be used to explore a dataset.

Example 1 - Minimal

This is a very basic implementation using the sci-kit learn Iris dataset. The program runs a number of experiments (iterations) where it generates a Fuzzy Pattern Tree on a training subset of the Iris data and it selects the best performing model from those experiments.

It graphs the tree showing the three classes of Iris with a Winner-Take-All root. This simplest of FPTs shows that if the plant has a low length of petal it is likely to be of the Setosa species. If the petal width is medium sized and the length is also medium sized then the species is Versicolor and if the petal width is high (i.e. long) then the species is Virginica.

'''
Zuffy Example 1 - Minimal
'''

# pylint: disable=no-member
import pandas as pd

from sklearn.datasets import load_iris

from zuffy import ZuffyClassifier, visuals
from zuffy.zuffy_fit_iterator import ZuffyFitIterator

iris = load_iris()
dataset = pd.DataFrame(data=iris.data, columns=iris.feature_names)
dataset['target'] = iris.target
X = dataset.iloc[:,0:-1]
y = dataset.iloc[:,-1]

zuffy = ZuffyClassifier(generations=15)
fit_iterator = ZuffyFitIterator(zuffy, n_iter=3, show_fuzzy_range=False)
trained_iterator_results = fit_iterator.fit(X, y)

visuals.graphviz_tree(
    trained_iterator_results.best_estimator_,
    target_class_names=list(iris.target_names),
    target_feature_name = 'Species',
    feature_names=trained_iterator_results.fuzzy_feature_names_,
    tree_name=f"Iris Dataset (Accuracy: {trained_iterator_results.best_score_:.3f})",
    output_filename=f'example1_fpt_{trained_iterator_results.best_score_*1000:.0f}')

Example 2 - Categoricals

This example uses a dataset with both numeric and categorical features.

'''
Zuffy Example 2 - Categoricals
'''

# pylint: disable=no-member disable=C0103 # uppercase naming style
import pandas as pd

from zuffy import ZuffyClassifier, visuals
from zuffy.zuffy_fit_iterator import ZuffyFitIterator
from zuffy.fuzzy_transformer import convert_to_numeric

# Use University of California, Irvine (UCI) Adult dataset (https://archive.ics.uci.edu/dataset/2/adult)
my_data = pd.read_csv('adult.data', sep=',', header=None, skiprows=0)
my_data.columns = ['age', 'workclass', 'fnlwgt', 'education', 'education-num', 'marital-status',
                   'occupation', 'relationship', 'race', 'sex', 'capital-gain', 'capital-loss',
                   'hours-per-week', 'native-country', 'income']

target_name = 'income'
target_class_names, my_data = convert_to_numeric(my_data, target_name)

non_fuzzy =  ['workclass', 'education', 'marital-status', 'occupation',
              'relationship', 'race', 'sex', 'native-country']

y = my_data[target_name]
X = my_data.drop(target_name, axis=1)

zuffy = ZuffyClassifier(generations=25, parsimony_coefficient=0.00002, verbose=1)
fit_iterator = ZuffyFitIterator(zuffy,n_iter=5)
trained_iterator_results = fit_iterator.fit(X, y, non_fuzzy=non_fuzzy)

visuals.plot_evolution(
    trained_iterator_results.best_estimator_,
    target_class_names=target_class_names,
    output_filename='example2_evolution')

visuals.graphviz_tree(
    trained_iterator_results.best_estimator_,
    target_class_names=target_class_names,
    target_feature_name = target_name,
    feature_names=trained_iterator_results.fuzzy_feature_names_,
    tree_name=f"UCI Adult Dataset (Experiment Accuracy: {trained_iterator_results.best_score_:.3f})",
    source_filename=f'example2_fpt_{trained_iterator_results.best_score_*1000:.0f}.dot',
    output_filename=f'example2_fpt_{trained_iterator_results.best_score_*1000:.0f}')

Example 3 - GridSearchCV

The sci-kit learn package includes the GridSearchCV feature that allows a developer to specify a range of hyperparameters when building their model. This is supported by Zuffy.

'''
Zuffy Example 3 - GridSearchCV
'''

# pylint: disable=no-member
import pandas as pd
from sklearn.datasets import load_iris
from sklearn.model_selection import GridSearchCV

from zuffy import ZuffyClassifier
from zuffy.zuffy_fit_iterator import ZuffyFitIterator


# 1. Load data
iris = load_iris()
dataset = pd.DataFrame(data=iris.data, columns=iris.feature_names)
dataset['target'] = iris.target
X = dataset.iloc[:,0:-1]
y = dataset.iloc[:,-1]

# 2. Define the base estimator and the parameter grid for GridSearchCV
zuffy_model = ZuffyClassifier()

param_grid = {
    'population_size': [5, 20, 500],
    'generations': [3, 10, 20],
}

# 3. Set up GridSearchCV
# This will search for the best hyperparameters for the ZuffyClassifier
# within each iteration of the ZuffyFitIterator.
grid_search = GridSearchCV(
    estimator=zuffy_model,
    param_grid=param_grid,
    cv=3,  # 3-fold cross-validation
    scoring='accuracy',
    n_jobs=-1, # Use all available CPU cores,
    verbose=1 # Set to 1 to see detailed output
)

# 4. Initialize and run ZuffyFitIterator
# It will run GridSearchCV 3 times (n_iter=3) and find the best overall model.
fit_iterator = ZuffyFitIterator(
    model=grid_search,
    n_iter=5,
    test_size=0.25
)

trained_iterator_results = fit_iterator.fit(X, y, feature_names=None)

# 5. Display the results
print(f"Best iteration index: {fit_iterator.best_iteration_index_}")
print(f"Best score (accuracy): {fit_iterator.best_score_:.4f}")
print(f"Smallest tree size of best model: {fit_iterator.smallest_tree_size_}")

# Display the best parameters found by GridSearchCV in the best iteration
if hasattr(fit_iterator.best_estimator_, 'best_params_'):
    print(f"Best hyperparameters found by GridSearch: {fit_iterator.best_estimator_.best_params_}")

# Show performance of each iteration
print("\n--- Iteration Performance ---")
print("\n   Score     Tree Size  Class Scores")
perf_df = pd.DataFrame(fit_iterator.iteration_performance_)
print(perf_df.to_string())

# Example of using the fitted iterator to make predictions on new data
print("\n--- Making a prediction on a 'new' data sample ---")
# Take the last 5 samples as "new" data
X_new = X[-5:]
fuzzy_X_new = fit_iterator.fuzz_transformer_.transform(X_new)
predictions = fit_iterator.best_estimator_.predict(fuzzy_X_new)
print(f"Predicted classes: {predictions}")
print(f"Actual classes: {list(y[-5:])}")

Example 4 - Pipeline

Because it is scikit-learn compatible, the Zuffy classifier and Fuzzy transformer can be included in pipelines to help manage more complex model generation.

'''
Zuffy Example 4 - Pipeline
'''

# pylint: disable=no-member
import pandas as pd
import numpy as np
from sklearn.compose import ColumnTransformer
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler, OneHotEncoder

from zuffy import ZuffyClassifier
from zuffy.fuzzy_transformer import FuzzyTransformer
from zuffy.visuals import plot_evolution


# 1. Create a synthetic dataset
N_SAMPLES = 100

data = pd.DataFrame({
    'age': np.random.randint(18, 70, size=N_SAMPLES),
    'income': np.random.randint(20000, 100000, size=N_SAMPLES),
    'gender': np.random.choice([0, 1], size=N_SAMPLES),
    'region': np.random.choice([1, 2, 3, 4], size=N_SAMPLES),
    'target': np.random.choice(['A', 'B'], size=N_SAMPLES)
})

X = data.drop('target', axis=1)
y = data['target']

# 2. Define preprocessing pipelines for numeric and categorical features
numeric_transformer = Pipeline(steps=[('scaler', StandardScaler())])

# Create a preprocessor with ColumnTransformer
preprocessor = ColumnTransformer(
    transformers=[
        ('num', numeric_transformer, ['age','income'])
    ],
    remainder='passthrough'
)

# 3. Create the full pipeline including preprocessing, fuzzification, and classifier
full_pipeline = Pipeline(steps=[
    ('preprocessor', preprocessor),
    ('fuzzifier', FuzzyTransformer(feature_names=X.columns)),
    ('classifier', ZuffyClassifier(generations=35))
])

# 4. Fit the model
pipeline_results = full_pipeline.fit(X, y)

# 5. Display the results
print(f"Fuzzy Feature Names: {pipeline_results.named_steps['fuzzifier'].feature_names_out_}")

plot_evolution(
    model=pipeline_results.named_steps['classifier'],
    target_class_names=['A', 'B'],
    output_filename='example4_evolution'
    )

print("Run Details:")
print(pipeline_results.named_steps['classifier'].multi_.estimators_[0].run_details_)

Example 5 - Full Visuals

The Zuffy visuals module includes four plots to facilitates visualisation of the induction process and the performance across multiple experiments.

'''
Zuffy Example 5 - Full Visuals
'''

# pylint: disable=no-member
import pandas as pd

from sklearn.datasets import load_iris

from zuffy import ZuffyClassifier
from zuffy.visuals import (
                        show_feature_importance,
                        plot_evolution,
                        graphviz_tree,
                        plot_iteration_performance
                        )
from zuffy.zuffy_fit_iterator import ZuffyFitIterator

iris = load_iris()
dataset = pd.DataFrame(data=iris.data, columns=iris.feature_names)
dataset['target'] = iris.target
X = dataset.iloc[:,0:-1]
y = dataset.iloc[:,-1]

zuffy = ZuffyClassifier(generations=15, parsimony_coefficient=0.0002)
fit_iterator = ZuffyFitIterator(zuffy, n_iter=10, show_fuzzy_range=True)
trained_iterator_results = fit_iterator.fit(X, y)

best_zuffy_model = trained_iterator_results.best_estimator_
best_overall_score = trained_iterator_results.best_score_
fuzzy_feature_names = trained_iterator_results.fuzzy_feature_names_
iter_perf = trained_iterator_results.iteration_performance_

feature_importance_results = show_feature_importance(
    reg=best_zuffy_model,
    X_test=best_zuffy_model.X_,
    y_test=best_zuffy_model.y_,
    features=fuzzy_feature_names, # Use fuzzified feature names for this plot
    n_jobs=1,                     # Number of parallel jobs (-1 for all processors)
    n_repeats=5,                  # Number of permutations
    output_filename='example5_feat_imp'
)

# Plot Evolutionary Metrics (e.g., fitness and length over generations)
plot_evolution(
    model=best_zuffy_model,
    target_class_names=list(iris.target_names),
    output_filename='example5_evolution'
)

graphviz_tree(
    trained_iterator_results.best_estimator_,
    imp_feat=feature_importance_results,
    target_class_names=list(iris.target_names),
    target_feature_name = 'Species',
    feature_names=fuzzy_feature_names,
    tree_name=f"Iris Dataset (Accuracy: {trained_iterator_results.best_score_:.3f})",
    output_filename='example5_fpt')

plot_iteration_performance(
    iter_perf,
    title='Iteration Performance: Example5',
    output_filename='example5_iter_perf'
    )

This plot shows the relative importance of key features in the dataset.

This FPT includes the feature range and a measure of their importance.

This plot shows the evolution metrics for each class in the best FPT.

Each of the experiments can be graphed using the plot_iteration_performance function. The graph shows the result of each experiment with the accuracy on the left axis and the tree size on the right.