Example 1: Basic Classification

The simplest way to get started with EasyHPO:

python
from MAT_HPO_LIB import EasyHPO
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split

#  Create sample dataset
X, y = make_classification(
    n_samples=1000,
    n_features=20,
    n_classes=3,
    n_informative=15,
    random_state=42
)

#  Split data
X_train, X_val, y_train, y_val = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

#  One-liner optimization
optimizer = EasyHPO(
    task_type="classification",
    max_trials=30,
    verbose=True
)

print(" Starting basic classification optimization...")
results = optimizer.optimize(X_train, y_train, X_val, y_val)

#  Display results
print(f"\\n Best Performance:")
print(f"   F1 Score: {results['best_performance']['f1']:.4f}")
print(f"   Accuracy: {results['best_performance'].get('accuracy', 'N/A')}")

print(f"\\n⚙️ Best Hyperparameters:")
for param, value in results['best_hyperparameters'].items():
    print(f"   {param}: {value}")

Example 2: LLM-Enhanced Time Series Classification

Using LLM enhancement for intelligent hyperparameter suggestions:

python
from MAT_HPO_LIB import EasyHPO
import numpy as np
from sklearn.model_selection import train_test_split

#  Create time series data
def create_time_series_data(n_samples=1000, sequence_length=100, n_classes=3):
    """Generate synthetic time series classification data"""
    X = np.random.randn(n_samples, sequence_length, 1)

    # Add class-specific patterns
    for i in range(n_samples):
        class_label = i % n_classes
        if class_label == 0:
            X[i] += np.sin(np.linspace(0, 4*np.pi, sequence_length)).reshape(-1, 1)
        elif class_label == 1:
            X[i] += np.cos(np.linspace(0, 2*np.pi, sequence_length)).reshape(-1, 1)

    y = np.array([i % n_classes for i in range(n_samples)])
    return X, y

#  Generate data
X, y = create_time_series_data(n_samples=1500, sequence_length=50)
X_train, X_val, y_train, y_val = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

#  LLM-enhanced optimization with adaptive strategy
optimizer = EasyHPO(
    task_type="time_series_classification",
    llm_enabled=True,              #  Enable LLM enhancement
    llm_strategy="adaptive",        # Smart adaptive strategy
    llm_config={
        'performance_threshold': 0.01,
        'min_episodes': 5,
        'model': 'llama3.2:3b'
    },
    max_trials=40,
    verbose=True
)

print(" Starting LLM-enhanced time series optimization...")
results = optimizer.optimize(X_train, y_train, X_val, y_val)

#  Analyze results
print(f"\\n LLM-Enhanced Results:")
print(f"   F1 Score: {results['best_performance']['f1']:.4f}")
print(f"   AUC: {results['best_performance']['auc']:.4f}")
print(f"   G-mean: {results['best_performance']['gmean']:.4f}")

print(f"\\n LLM Usage Statistics:")
stats = results.get('optimization_stats', {})
print(f"   Total trials: {stats.get('trials_completed', 'N/A')}")
print(f"   LLM interventions: {stats.get('llm_interventions', 'N/A')}")
print(f"   Optimization time: {stats.get('optimization_time', 'N/A'):.2f}s")

❤️ Example 3: ECG Classification (Complete Pipeline)

A complete example for ECG heartbeat classification using specialized configuration:

python
from MAT_HPO_LIB import EasyHPO
from MAT_HPO_LIB.easy_hpo import quick_ecg_optimize
import numpy as np
from sklearn.model_selection import train_test_split

#  Simulate realistic ECG data
def create_ecg_data(n_samples=2000, signal_length=500):
    """Generate synthetic ECG data for 9 cardiac conditions"""
    X = np.random.randn(n_samples, signal_length, 1)
    y = np.random.randint(0, 9, n_samples)  # 9 cardiac conditions

    # Add realistic ECG patterns for each class
    for i in range(n_samples):
        class_id = y[i]

        # Normal sinus rhythm
        if class_id == 0:
            # Regular QRS complexes
            for j in range(0, signal_length, 100):
                if j + 20 < signal_length:
                    X[i, j:j+20, 0] += 2 * np.exp(-np.linspace(0, 5, 20))

        # Atrial fibrillation - irregular rhythm
        elif class_id == 1:
            # Irregular QRS complexes
            positions = np.random.randint(50, 150, 5)
            for pos in positions:
                if pos + 15 < signal_length:
                    X[i, pos:pos+15, 0] += 1.5 * np.sin(np.linspace(0, np.pi, 15))

        # Add noise and variations for other classes
        else:
            X[i] += 0.5 * class_id * np.sin(np.linspace(0, 2*np.pi, signal_length)).reshape(-1, 1)

    return X, y

#  Generate ECG dataset
print(" Generating synthetic ECG data...")
X, y = create_ecg_data(n_samples=3000, signal_length=500)

#  Stratified split to maintain class distribution
X_train, X_val, y_train, y_val = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

print(f" Dataset shape: {X_train.shape}, Classes: {len(np.unique(y))}")

#  Method 1: Use convenience function
print("\\n Method 1: Using convenience function...")
quick_results = quick_ecg_optimize(X_train, y_train, X_val, y_val)
print(f"Quick optimization result: {quick_results}")

#  Method 2: Full EasyHPO with LLM enhancement
print("\\n Method 2: Full LLM-enhanced optimization...")
optimizer = EasyHPO(
    task_type="ecg_classification",
    llm_enabled=True,              #  Use LLM for intelligent suggestions
    llm_strategy="fixed_alpha",     # Stable strategy for ECG
    llm_config={
        'alpha': 0.3,                  # 30% LLM + 70% RL
        'model': 'llama3.2:3b',
        'cooldown': 3
    },
    max_trials=50,                 # More trials for better ECG results
    timeout_minutes=30,             # Reasonable timeout
    auto_save=True,                  # Save results automatically
    verbose=True
)

#  Run optimization
print(" Starting ECG hyperparameter optimization...")
results = optimizer.optimize(X_train, y_train, X_val, y_val)

#  Comprehensive results analysis
print(f"\\n Final ECG Classification Results:")
print("=" * 50)

performance = results['best_performance']
print(f" Performance Metrics:")
print(f"   F1 Score:  {performance['f1']:.4f}")
print(f"   AUC:       {performance['auc']:.4f}")
print(f"   G-mean:    {performance['gmean']:.4f}")

print(f"\\n⚙️ Optimized Hyperparameters:")
best_params = results['best_hyperparameters']
for param, value in best_params.items():
    print(f"   {param:20s}: {value}")

print(f"\\n Optimization Statistics:")
stats = results.get('optimization_stats', {})
print(f"   Total trials:     {stats.get('trials_completed', 'N/A')}")
print(f"   LLM usage:        {stats.get('llm_interventions', 'N/A')} interventions")
print(f"   Total time:       {stats.get('optimization_time', 'N/A'):.2f} seconds")
print(f"   Convergence step: {stats.get('convergence_step', 'N/A')}")

print(f"\\n Results saved to: {optimizer.output_dir if hasattr(optimizer, 'output_dir') else 'current directory'}")

Example 4: Custom Pipeline with Model Factory

Advanced usage with custom model creation and training pipeline:

python
from MAT_HPO_LIB import EasyHPO, HyperparameterSpace
import numpy as np
from sklearn.ensemble import RandomForestClassifier
from sklearn.neural_network import MLPClassifier
from sklearn.metrics import f1_score, roc_auc_score

# ️ Custom model factory
def custom_model_factory(**hyperparams):
    """Create custom model based on hyperparameters"""
    model_type = hyperparams.get('model_type', 'rf')

    if model_type == 'rf':
        return RandomForestClassifier(
            n_estimators=int(hyperparams.get('n_estimators', 100)),
            max_depth=int(hyperparams.get('max_depth', 10)),
            random_state=42
        )
    else:  # mlp
        return MLPClassifier(
            hidden_layer_sizes=(int(hyperparams.get('hidden_size', 100)),),
            learning_rate_init=hyperparams.get('learning_rate', 0.001),
            max_iter=500,
            random_state=42
        )

#  Custom trainer
def custom_trainer(model, X_train, y_train, **hyperparams):
    """Custom training logic"""
    # Add preprocessing if needed
    if hyperparams.get('normalize', False):
        from sklearn.preprocessing import StandardScaler
        scaler = StandardScaler()
        X_train = scaler.fit_transform(X_train)
        model.scaler = scaler  # Store for evaluation

    # Train the model
    model.fit(X_train, y_train)
    return model

#  Custom evaluator
def custom_evaluator(model, X_val, y_val):
    """Custom evaluation logic"""
    # Apply same preprocessing as training
    if hasattr(model, 'scaler'):
        X_val = model.scaler.transform(X_val)

    # Make predictions
    y_pred = model.predict(X_val)

    # Calculate metrics
    try:
        y_pred_proba = model.predict_proba(X_val)
        if len(np.unique(y_val)) == 2:
            auc = roc_auc_score(y_val, y_pred_proba[:, 1])
        else:
            auc = roc_auc_score(y_val, y_pred_proba, multi_class='ovr')
    except:
        auc = 0.5

    f1 = f1_score(y_val, y_pred, average='weighted')

    return {
        'f1': f1,
        'auc': auc,
        'accuracy': np.mean(y_pred == y_val)
    }

#  Create sample data
from sklearn.datasets import make_classification
X, y = make_classification(n_samples=1000, n_features=20, n_classes=3)
X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.2)

#  Define custom hyperparameter space
custom_space = HyperparameterSpace()
custom_space.add_discrete('model_type', ['rf', 'mlp'], agent=0)
custom_space.add_continuous('n_estimators', 50, 200, agent=1)  # For RF
custom_space.add_continuous('max_depth', 5, 20, agent=1)       # For RF
custom_space.add_continuous('hidden_size', 50, 200, agent=1)     # For MLP
custom_space.add_continuous('learning_rate', 0.001, 0.1, agent=2) # For MLP
custom_space.add_boolean('normalize', agent=2)                           # Preprocessing

#  Create optimizer with custom pipeline
optimizer = EasyHPO(
    task_type="classification",
    llm_enabled=True,
    llm_strategy="adaptive",
    max_trials=25,
    verbose=True
)

#  Run optimization with custom pipeline
print(" Starting custom pipeline optimization...")
results = optimizer.optimize_with_pipeline(
    data_loader=lambda: (X_train, y_train, X_val, y_val),
    model_factory=custom_model_factory,
    trainer=custom_trainer,
    evaluator=custom_evaluator,
    custom_space=custom_space
)

#  Display results
print(f"\\n Custom Pipeline Results:")
print(f"   Best F1: {results['best_performance']['f1']:.4f}")
print(f"   Best Model: {results['best_hyperparameters']['model_type']}")

# ️ Create final tuned model
best_config = optimizer.get_best_config()
final_model = custom_model_factory(**best_config)
print(f"️ Final tuned model created: {type(final_model).__name__}")

Next Steps

LLM Strategies Guide

Learn about different LLM enhancement strategies

Full Control Examples

See examples using the complete MAT-HPO API

API Reference

Detailed documentation for all classes and methods