MachineLearningHelper Module

Offers helper functions for machine learning workflows, including training and evaluation.

HMB.MachineLearningHelper.GetScalerObject(scalerName)[source]

Retrieve a scikit-learn scaler object based on the specified scaler name.

This function returns an instance of a scaler from scikit-learn’s preprocessing module according to the provided scaler name. Supported scalers include StandardScaler, MinMaxScaler, RobustScaler, MaxAbsScaler, QuantileTransformer, and Normalizer.

Supported scalers include:

  • “Standard”: Standard Scaler (Standardization)

  • “MinMax”: Min-Max Scaler (Normalization)

  • “Robust”: Robust Scaler (Robust to outliers)

  • “MaxAbs”: Max Absolute Scaler (Scales each feature by its maximum absolute value)

  • “QT”: Quantile Transformer (Transforms features to follow a uniform or normal distribution)

  • “Normalizer”: Max normalizer (Scales samples individually to unit norm)

  • “L1”: L1 Normalizer (Scales samples to have L1 norm equal to 1)

  • “L2”: L2 Normalizer (Scales samples to have L2 norm equal to 1)

Parameters:

scalerName (str) – Name of the scaler to retrieve. Supported values: “Standard”, “MinMax”, “Robust”, “MaxAbs”, “QT”, “Normalizer”, “L1”, “L2”.

Returns:

An instance of the requested scaler class from scikit-learn.

Return type:

object

Raises:

ValueError – If an invalid scaler name is provided.

Examples

import numpy as np
import HMB.MachineLearningHelper as mlh
from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score

# Load the Iris dataset.
data = load_iris()
X = data.data
y = data.target

# Split the dataset into training and testing sets.
xTrain, xTest, yTrain, yTest = train_test_split(
  X, y,
  test_size=0.2,
  random_state=np.random.randint(0, 10000),
)
# Get a scaler object (e.g., Standard Scaler).
scaler = mlh.GetScalerObject("Standard")
# Fit the scaler on the training data and transform both training and testing data.
xTrainScaled = scaler.fit_transform(xTrain)
xTestScaled = scaler.transform(xTest)
# Initialize and train a Logistic Regression model.
model = mlh.GetMLClassificationModelObject("LR")
model.fit(xTrainScaled, yTrain)
# Make predictions on the testing data.
yPred = model.predict(xTestScaled)
# Calculate and print the accuracy of the model.
accuracy = accuracy_score(yTest, yPred)
print(f"Accuracy: {accuracy:.2f}")
HMB.MachineLearningHelper.ListScikitMachineLearningClassifiers()[source]

List all available machine learning classifiers in scikit-learn.

This function retrieves all classifier estimators from scikit-learn’s all_estimators function and returns them as a dictionary containing the classifier name, class object, module name, class name, and import statement for each classifier.

Returns:

Dictionary where keys are classifier names and values are dictionaries with class object, module name, class name, and import statement.

Return type:

dict

Examples

import HMB.MachineLearningHelper as mlh
classifiers = mlh.ListScikitMachineLearningClassifiers()
for name, info in classifiers.items():
  print(f"Classifier Name: {name}")
  print(f"Class Object: {info['class']}")
  print(f"Module: {info['module']}")
  print(f"Class Name: {info['name']}")
  print(f"Import Statement: {info['import']}")
  print("-" * 40)
HMB.MachineLearningHelper.ListScikitMachineLearningRegressors()[source]

List all available machine learning regressors in scikit-learn.

This function retrieves all regressor estimators from scikit-learn’s all_estimators function and returns them as a dictionary containing the regressor name, class object, module name, class name, and import statement for each regressor.

Returns:

Dictionary where keys are regressor names and values are dictionaries with class object, module name, class name, and import statement.

Return type:

dict

Examples

import HMB.MachineLearningHelper as mlh

regressors = mlh.ListScikitMachineLearningRegressors()

for name, info in regressors.items():
  print(f"Regressor Name: {name}")
  print(f"Class Object: {info['class']}")
  print(f"Module: {info['module']}")
  print(f"Class Name: {info['name']}")
  print(f"Import Statement: {info['import']}")
  print("-" * 40)
HMB.MachineLearningHelper.GetFilteredClassifiers(clsList=[])[source]

Retrieve a filtered list of scikit-learn classifier classes.

This function returns a list of classifier classes from scikit-learn, excluding those that require special arguments (such as “base_estimator” or “estimators”) or are known to fail with certain inputs. If a specific list of classifier names is provided, only those classifiers are returned.

Parameters:

clsList (list, optional) – List of classifier names to include. If empty or None, all available classifiers are considered.

Returns:

List of tuples containing classifier names and their corresponding class objects.

Return type:

list

Examples

import HMB.MachineLearningHelper as mlh
# Get all filtered classifiers.
classifiers = mlh.GetFilteredClassifiers()
for name, cls in classifiers:
  print(f"Classifier Name: {name}, Class: {cls}")
# Get only specific classifiers.
classifiers = mlh.GetFilteredClassifiers(["RandomForestClassifier", "LogisticRegression"])
for name, cls in classifiers:
  print(f"Classifier Name: {name}, Class: {cls}")
HMB.MachineLearningHelper.GetFilteredRegressors(regList=[])[source]

Retrieve a filtered list of scikit-learn regressor classes.

This function returns a list of regressor classes from scikit-learn, excluding those that require special arguments (such as “base_estimator” or “estimators”) or are known to fail with certain inputs. If a specific list of regressor names is provided, only those regressors are returned.

Parameters:

regList (list, optional) – List of regressor names to include. If empty or None, all available regressors are considered.

Returns:

List of tuples containing regressor names and their corresponding class objects.

Return type:

list

Examples

import HMB.MachineLearningHelper as mlh

# Get all filtered regressors.
regressors = mlh.GetFilteredRegressors()
for name, reg in regressors:
  print(f"Regressor Name: {name}, Class: {reg}")
# Get only specific regressors.
regressors = mlh.GetFilteredRegressors(["RandomForestRegressor", "LinearRegression"])
for name, reg in regressors:
  print(f"Regressor Name: {name}, Class: {reg}")
HMB.MachineLearningHelper.GetClassifierClassByName(clsName)[source]

Retrieve a scikit-learn classifier class by its name.

This function returns the classifier class object corresponding to the specified name from scikit-learn. If the classifier is not found, None is returned.

Parameters:

clsName (str) – Name of the classifier to retrieve.

Returns:

Classifier class object corresponding to the specified name, or None if not found.

Return type:

class

Examples

import HMB.MachineLearningHelper as mlh
# Get the RandomForestClassifier class.
rfCls = mlh.GetClassifierClassByName("RandomForestClassifier")
print(rfCls)
# Get a non-existent classifier.
noneCls = mlh.GetClassifierClassByName("NonExistentClassifier")
print(noneCls)  # None.
HMB.MachineLearningHelper.GetRegressorClassByName(regName)[source]

Retrieve a scikit-learn regressor class by its name.

This function returns the regressor class object corresponding to the specified name from scikit-learn. If the regressor is not found, None is returned.

Parameters:

regName (str) – Name of the regressor to retrieve.

Returns:

Regressor class object corresponding to the specified name, or None if not found.

Return type:

class

Examples

import HMB.MachineLearningHelper as mlh
# Get the RandomForestRegressor class.
rfReg = mlh.GetRegressorClassByName("RandomForestRegressor")
print(rfReg)
# Get a non-existent regressor.
noneReg = mlh.GetRegressorClassByName("NonExistentRegressor")
print(noneReg)  # None.
HMB.MachineLearningHelper.GetMLClassificationModelObject(modelName, hyperparameters={})[source]

Get a machine learning classification model object based on the given name and hyperparameters.

This function returns an instance of a classification model from scikit-learn or other libraries according to the provided model name and optional hyperparameters.

Supported models include:

  • “MLP”: Multi-layer Perceptron Classifier

  • “RF”: Random Forest Classifier

  • “AB”: AdaBoost Classifier

  • “KNN”: K-Nearest Neighbors Classifier

  • “DT”: Decision Tree Classifier

  • “SVC”: Support Vector Classifier

  • “GNB”: Gaussian Naive Bayes

  • “LR”: Logistic Regression

  • “SGD”: Stochastic Gradient Descent Classifier

  • “GB”: Gradient Boosting Classifier

  • “Bagging”: Bagging Classifier

  • “ETs”: Extra Trees Classifier

  • “XGB”: eXtreme Gradient Boosting Classifier

  • “LGBM”: Light Gradient Boosting Machine Classifier

  • “Voting”: Voting Classifier

  • “Stacking”: Stacking Classifier

  • “CatBoost”: CatBoost Classifier

  • “HGB”: HistGradientBoosting Classifier

Parameters:

  • modelName (str) – Name of the classification model to retrieve. Supported values include: “MLP”, “RF”, “AB”, “KNN”, “DT”, “SVC”, “GNB”, “LR”, “SGD”, “GB”, “Bagging”, “ETs”, “XGB”, “LGBM”, “Voting”, “Stacking”, “CatBoost”, “HGB”.

  • hyperparameters (dict, optional) – Dictionary of hyperparameters to pass to the model constructor.

Returns:

An instance of the requested classification model.

Return type:

object

Raises:

ValueError – If an invalid model name is provided.

Examples

import numpy as np
import HMB.MachineLearningHelper as mlh
from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score

# Load the Iris dataset.
data = load_iris()
X = data.data
y = data.target

# Split the dataset into training and testing sets.
xTrain, xTest, yTrain, yTest = train_test_split(
  X, y,
  test_size=0.2,
  random_state=np.random.randint(0, 10000),
)
# Get a scaler object (e.g., Standard Scaler).
scaler = mlh.GetScalerObject("Standard")
# Fit the scaler on the training data and transform both training and testing data.
xTrain = scaler.fit_transform(xTrain)
xTest = scaler.transform(xTest)
# Get a classification model object (e.g., Random Forest).
model = mlh.GetMLClassificationModelObject("RF", hyperparameters={"n_estimators": 100})
# Train the model on the training data.
model.fit(xTrain, yTrain)
# Make predictions on the testing data.
yPred = model.predict(xTest)
# Calculate and print the accuracy of the model.
accuracy = accuracy_score(yTest, yPred)
print(f"Accuracy: {accuracy:.2f}")
HMB.MachineLearningHelper.GetClassifierModelSpace(classifierName, noOfFeatures=None, noOfSamples=None)[source]

Get the hyperparameter search space for a given classifier.

This function returns a dictionary representing the hyperparameter search space for a specified classifier. The search space is defined based on common hyperparameters for each classifier type, and can be adjusted based on the number of features and samples in the dataset.

Parameters:

  • classifierName (str) – The name of the classifier for which to retrieve the hyperparameter search space. Supported values include “DT”, “SVM”, “LR”, “RF”, “KNN”, “LGBM”, “XGB”, “HGB”, “GB”, “AdaBoost”, “CatBoost”, and “MLP”.

  • noOfFeatures (int, optional) – The number of features in the dataset. This can be used to adjust the search space for certain hyperparameters (e.g., max_depth). If not provided, default values will be used.

  • noOfSamples (int, optional) – The number of samples in the dataset. This can be used to adjust the search space for certain hyperparameters (e.g., n_neighbors for KNN). If not provided, default values will be used.

Returns:

A dictionary representing the hyperparameter search space for the specified classifier.

Return type:

dict

HMB.MachineLearningHelper.GetMLRegressorModelObject(modelName, hyperparameters={})[source]

Get a machine learning regressor model object based on the given name and hyperparameters.

This function returns an instance of a regression model from scikit-learn or other libraries according to the provided model name and optional hyperparameters.

Supported models include:

  • “MLP”: Multi-layer Perceptron Regressor

  • “RF”: Random Forest Regressor

  • “AB”: AdaBoost Regressor

  • “KNN”: K-Nearest Neighbors Regressor

  • “DT”: Decision Tree Regressor

  • “SVR”: Support Vector Regressor

  • “LR”: Linear Regression

  • “SGD”: Stochastic Gradient Descent Regressor

  • “GB”: Gradient Boosting Regressor

  • “Bagging”: Bagging Regressor

  • “ETs”: Extra Trees Regressor

  • “XGB”: eXtreme Gradient Boosting Regressor

  • “LGBM”: Light Gradient Boosting Machine Regressor

  • “Voting”: Voting Regressor

  • “Stacking”: Stacking Regressor

  • “CatBoost”: CatBoost Regressor

  • “HGB”: HistGradientBoosting Regressor

Parameters:

  • modelName (str) – Name of the regression model to retrieve.

  • hyperparameters (dict, optional) – Dictionary of hyperparameters to pass to the model constructor.

Returns:

An instance of the requested regression model.

Return type:

object

Raises:

ValueError – If an invalid model name is provided.

HMB.MachineLearningHelper.PerformFeatureSelection(tech, fsRatio, xTrain, yTrain, xTest, yTest, returnFeatures=False)[source]

Perform feature selection on training and testing data using the specified technique and ratio.

This function applies feature selection or dimensionality reduction to the input data using techniques such as PCA, LDA, Random Forest importance, RFE, Chi2, Mutual Information, or ANOVA.

Supported techniques include:

  • “PCA”: Principal Component Analysis

  • “RF”: Random Forest Feature Importance

  • “RFE”: Recursive Feature Elimination

  • “Chi2”: Chi-Squared Feature Selection

  • “MI”: Mutual Information

  • “ANOVA”: ANOVA F-value

  • “LDA”: Linear Discriminant Analysis

Parameters:
Returns:

Transformed training and testing data, selector object, and selected features (if requested).

  • (xTrainFS, xTestFS): Transformed training and testing data after feature selection.

  • selector: The feature selection or dimensionality reduction object used.

  • features: List of selected feature names (if returnFeatures is True).

Return type:

tuple

Raises:

ValueError – If the number of features is invalid or the technique is not supported.

Examples

import numpy as np
import HMB.MachineLearningHelper as mlh
from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score

# Load the Iris dataset.
data = load_iris()
X = data.data
y = data.target

# Split the dataset into training and testing sets.
xTrain, xTest, yTrain, yTest = train_test_split(
  X, y,
  test_size=0.2,
  random_state=np.random.randint(0, 10000),
)
# Perform feature selection using PCA to select 50% of features.
xTrainFS, xTestFS, selector, features = mlh.PerformFeatureSelection(
  "PCA", 50, xTrain, yTrain, xTest, yTest, returnFeatures=True
)
# Print the selected features.
print(f"Selected Features: {features}")
# Print the shape of the transformed training and testing data.
print(f"xTrainFS shape: {xTrainFS.shape}, xTestFS shape: {xTestFS.shape}")
# Get a scaler object (e.g., Standard Scaler).
scaler = mlh.GetScalerObject("Standard")
# Fit the scaler on the balanced training data and transform both training and testing data.
xTrainFS = scaler.fit_transform(xTrainFS)
xTestFS = scaler.transform(xTestFS)
# Initialize and train a Logistic Regression model.
model = mlh.GetMLClassificationModelObject("LR")
model.fit(xTrainFS, yTrain)
# Make predictions on the testing data.
yPred = model.predict(xTestFS)
# Calculate and print the accuracy of the model.
accuracy = accuracy_score(yTest, yPred)
print(f"Accuracy: {accuracy:.2f}")
HMB.MachineLearningHelper.PerformFeatureRanking(trainDF, testDF, columns, rankTechStr, noOfFeatures)[source]

Apply feature ranking to training and test DataFrames and return reduced DataFrames.

This function ranks features using a specified ranking technique and selects the top percentage or absolute number of features specified by noOfFeatures. Supported ranking techniques include: “UDFS”, “MCFS”, “MRMR”, “CMIM”, “JMI”, “MIM”, “MIFS”, “CIFE”, “ICAP”, “DISR”.

Parameters:

  • trainDF (pandas.DataFrame) – The training data as a DataFrame.

  • testDF (pandas.DataFrame) – The test data as a DataFrame.

  • columns (list) – List of feature column names to be used for ranking.

  • rankTechStr (str) – The ranking technique to be used.

  • noOfFeatures (int or float) – The number of features to select. If <= 100, interpreted as a percentage.

Returns:

A tuple containing the reduced training DataFrame, reduced test DataFrame, and the list of selected columns.

Return type:

tuple

HMB.MachineLearningHelper.PerformDataBalancing(xTrain, yTrain, techniqueStr='SMOTE')[source]

Perform data balancing on training data using the specified oversampling or undersampling technique.

This function applies data balancing techniques such as SMOTE, ADASYN, BorderlineSMOTE, SVMSMOTE, KSMOTE, RandomOverSampler, RandomUnderSampler, NearMiss, NearMiss-1, NearMiss-2, NearMiss-3, TomekLinks, or ClusterCentroids to the input training data.

Supported techniques include:

  • “SMOTE”: Synthetic Minority Over-sampling Technique

  • “ADASYN”: Adaptive Synthetic Sampling Approach

  • “BSMOTE”: Borderline SMOTE

  • “SVMSMOTE”: Support Vector Machine SMOTE

  • “KSMOTE”: KMeans SMOTE

  • “ROS”: Random Over-Sampling

  • “RUS”: Random Under-Sampling

  • “NearMiss”: Near Miss Sampling. This is the same as “NearMiss-1”.

  • “NearMiss-1”: Near Miss version 1

  • “NearMiss-2”: Near Miss version 2

  • “NearMiss-3”: Near Miss version 3

  • “TomekLinks”: Tomek Links

  • “CCx”: Cluster Centroids

Parameters:

  • xTrain (array-like) – Training data features.

  • yTrain (array-like) – Training data labels.

  • techniqueStr (str, optional) – Name of the balancing technique to use. Supported values include: “SMOTE”, “ADASYN”, “BSMOTE”, “SVMSMOTE”, “KSMOTE”, “ROS”, “RUS”, “NearMiss”, “NearMiss-1”, “NearMiss-2”, “NearMiss-3”, “TL”, “CCx”. Default is “SMOTE”.

Returns:

Resampled training data features, labels, and balancing object.

  • xTrain: Resampled training data features.

  • yTrain: Resampled training data labels.

  • obj: Data balancing object used for resampling.

Return type:

tuple

Raises:

ValueError – If an invalid balancing technique is specified.

Examples

import numpy as np
import HMB.MachineLearningHelper as mlh
from sklearn.model_selection import train_test_split
from sklearn.datasets import make_classification
from sklearn.metrics import accuracy_score

# Create an imbalanced dataset.
X, y = make_classification(
  n_classes=2, class_sep=2, weights=[0.9, 0.1],
  n_informative=3, n_redundant=1, flip_y=0,
  n_features=20, n_clusters_per_class=1,
  n_samples=1000, random_state=np.random.randint(0, 10000),
)
# Split the dataset into training and testing sets.
xTrain, xTest, yTrain, yTest = train_test_split(
  X, y,
  test_size=0.2,
  random_state=np.random.randint(0, 10000),
)
# Perform data balancing using SMOTE.
xTrainBalanced, yTrainBalanced, obj = mlh.PerformDataBalancing(xTrain, yTrain, techniqueStr="SMOTE")
# Print the class distribution before and after balancing.
print(f"Original class distribution: {np.bincount(yTrain)}")
print(f"Balanced class distribution: {np.bincount(yTrainBalanced)}")
# Get a scaler object (e.g., Standard Scaler).
scaler = mlh.GetScalerObject("Standard")
# Fit the scaler on the balanced training data and transform both training and testing data.
xTrainBalanced = scaler.fit_transform(xTrainBalanced)
xTest = scaler.transform(xTest)
# Initialize and train a Logistic Regression model.
model = mlh.GetMLClassificationModelObject("LR")
model.fit(xTrainBalanced, yTrainBalanced)
# Make predictions on the testing data.
yPred = model.predict(xTest)
# Calculate and print the accuracy of the model.
accuracy = accuracy_score(yTest, yPred)
print(f"Accuracy: {accuracy:.2f}")
HMB.MachineLearningHelper.PerformOutlierDetection(xTrain, techniqueStr='IQR', contamination=0.05, returnMask=False)[source]

Detect and optionally remove outliers from training data using the specified technique.

This function applies outlier detection techniques such as IQR (Interquartile Range), Z-Score, Isolation Forest, Local Outlier Factor, Elliptic Envelope, One-Class SVM, DBSCAN, or Mahalanobis Distance to the input training data. It returns the filtered data and optionally a mask indicating which samples are considered inliers.

Supported techniques include:

  • “IQR”: Interquartile Range method

  • “ZScore”: Z-Score method

  • “IForest”: Isolation Forest

  • “LOF”: Local Outlier Factor

  • “EllipticEnvelope”: Elliptic Envelope (Gaussian)

  • “OCSVM”: One-Class SVM

  • “DBSCAN”: DBSCAN clustering (outliers as noise)

  • “Mahalanobis”: Mahalanobis Distance

Parameters:

  • xTrain (array-like) – Training data features (numpy array or pandas DataFrame).

  • techniqueStr (str, optional) – Name of the outlier detection technique to use. Supported values: “IQR”, “ZScore”, “IForest”, “LOF”, “EllipticEnvelope”, “OCSVM”, “DBSCAN”, “Mahalanobis”. Default is “IQR”.

  • contamination (float, optional) – Proportion of outliers in the data (used for IForest/LOF/EllipticEnvelope/OCSVM/DBSCAN). Default is 0.05.

  • returnMask (bool, optional) – If True, also return a boolean mask of inliers. Default is False.

Returns:

Training data with outliers removed. mask (optional): Boolean mask indicating inliers (if returnMask=True).

Return type:

xFiltered

Raises:

ValueError – If an invalid technique is specified.

Examples

import HMB.MachineLearningHelper as mlh
import numpy as np

X = np.random.randn(100, 5)
xFiltered = mlh.PerformOutlierDetection(X, techniqueStr="ZScore")
HMB.MachineLearningHelper.MachineLearningClassification(datasetFilePath, scalerName, modelName, fsTechName, fsTechRatio=0.2, dataBalanceTech=None, outlierTech=None, contamination=0.05, testRatio=0.2, testFilePath=None, targetColumn='Class', dropFirstColumn=True, dropNAColumns=True, encodeCategorical=True, eps=1e-08)[source]

Perform machine learning classification on a dataset with optional scaling, feature selection, and data balancing.

This function loads a dataset from a CSV file, applies preprocessing steps (scaling, feature selection, data balancing), trains a classification model, and evaluates its performance. Optionally, a separate test file can be provided for evaluation.

Data flow:

Load Data -> Drop First Column (if specified) -> Drop NA Columns -> Encode Target Labels -> Encoder Categorial Features (if any and if needed) -> Split Features and Target -> Split Train/Test (if no test file) -> Outlier Detection (if specified) -> Scale Features -> Feature Selection -> Data Balancing (if specified) -> Train Model -> Evaluate Performance -> Plot Performance Metrics

Parameters:

  • datasetFilePath (str) – Path to the dataset CSV file.

  • scalerName (str) – Name of the scaler to use (e.g., “Standard”, “MinMax”, “Robust”).

  • modelName (str) – Name of the machine learning classification model (e.g., “LR” for Logistic Regression).

  • fsTechName (str) – Feature selection technique name.

  • fsTechRatio (float) – Ratio of features to select (default: 0.2).

  • dataBalanceTech (str, optional) – Data balancing technique to apply (e.g., “SMOTE”).

  • outlierTech (str, optional) – Outlier detection technique to apply (e.g., “IQR”).

  • contamination (float, optional) – Proportion of outliers in the data (used for outlier detection techniques).

  • testRatio (float) – Ratio of the test data (default: 0.2).

  • testFilePath (str, optional) – Optional path to a test CSV file for evaluation.

  • targetColumn (str) – Name of the target column in the dataset (default: “Class”).

  • dropFirstColumn (bool) – Whether to drop the first column (usually an index or ID, default: True).

  • dropNAColumns (bool) – Whether to drop columns with any null values (default: True).

  • encodeCategorical (bool) – Whether to encode categorical features (if any, default: True).

  • eps (float) – Small value to avoid division by zero (if needed, default: 1e-8).

Returns:

A tuple containing:

  • dict: Dictionary of performance metrics.

  • matplotlib.figure.Figure: Matplotlib figure object with performance plots.

  • dict: Dictionary containing various objects used in the process (e.g., model, scaler, feature selector). Keys include:

    • ”Model”: Trained machine learning model.

    • ”CurrentColumns”: List of current feature columns.

    • ”Scaler”: Scaler object used for scaling.

    • ”FeatureSelector”: Feature selection object used.

    • ”FeatureSelectionTechnique”: Name of the feature selection technique used.

    • ”FeatureSelectionRatio”: Ratio of features selected.

    • ”SelectedFeatures”: List of selected feature names.

    • ”DataBalancingTechnique”: Name of the data balancing technique used.

    • ”DataBalancingObject”: Data balancing object used.

    • ”OutlierDetectionTechnique”: Name of the outlier detection technique used.

    • ”OutlierDetectionContamination”: Contamination ratio used for outlier detection.

    • ”OutlierDetectionMask”: Outlier detection object used.

    • ”LabelEncoder”: Label encoder object used for encoding target labels.

Return type:

tuple

Examples

import numpy as np
import HMB.MachineLearningHelper as mlh
from sklearn.model_selection import train_test_split
from sklearn.datasets import load_iris
from sklearn.metrics import accuracy_score

# Load the Iris dataset.
data = load_iris()
X = data.data
y = data.target

# Split the dataset into training and testing sets.
xTrain, xTest, yTrain, yTest = train_test_split(
  X, y,
  test_size=0.2,
  random_state=np.random.randint(0, 10000),
)
# Get a scaler object (e.g., Standard Scaler).
scaler = mlh.GetScalerObject("Standard")
# Fit the scaler on the training data and transform both training and testing data.
xTrain = scaler.fit_transform(xTrain)
xTest = scaler.transform(xTest)
# Get a classification model object (e.g., Random Forest).
model = mlh.GetMLClassificationModelObject("RF", hyperparameters={"n_estimators": 100})
# Train the model on the training data.
model.fit(xTrain, yTrain)
# Make predictions on the testing data.
yPred = model.predict(xTest)
# Calculate and print the accuracy of the model.
accuracy = accuracy_score(yTest, yPred)
print(f"Accuracy: {accuracy:.2f}")
HMB.MachineLearningHelper.MachineLearningRegression(datasetFilePath, scalerName, modelName, fsTechName, fsTechRatio=0.2, testRatio=0.2, testFilePath=None, targetColumn='Target', dropFirstColumn=True, dropNAColumns=True, encodeCategorical=True)[source]

Perform machine learning regression on a dataset with optional scaling and feature selection.

This function loads a dataset from a CSV file, applies preprocessing steps (scaling, feature selection), trains a regression model, and evaluates its performance. Optionally, a separate test file can be provided for evaluation.

Parameters:

  • datasetFilePath (str) – Path to the CSV dataset.

  • scalerName (str) – Name of the scaler to use.

  • modelName (str) – Name of the regression model.

  • fsTechName (str) – Feature selection technique.

  • fsTechRatio (float) – Ratio of features to select.

  • testRatio (float) – Test set ratio.

  • testFilePath (str, optional) – Path to test CSV file.

  • targetColumn (str) – Name of the target column.

  • dropFirstColumn (bool) – Drop first column if True.

  • dropNAColumns (bool) – Drop columns with NA if True.

  • encodeCategorical (bool) – Encode categorical features if True.

Returns:

A tuple containing:

  • dict: Dictionary of regression performance metrics (MSE, MAE, R2).

  • matplotlib.figure.Figure: Matplotlib figure object with regression results plot.

  • dict: Dictionary containing various objects used in the process (e.g., model, scaler, feature selector). Keys include:

    • ”model”: Trained regression model.

    • ”scaler”: Scaler object used for scaling (if any).

    • ”feature_selector”: Feature selection object used (if any).

    • ”features”: List of feature names used.

    • ”metrics”: Dictionary of performance metrics.

Return type:

tuple

Examples

import HMB.MachineLearningHelper as mlh

# Define the dataset file path and parameters.
datasetFilePath = "path/to/your/dataset.csv"
scalerName = "Standard"
modelName = "LR"
fsTechName = "PCA"
fsTechRatio = 0.5  # Select 50% of features.
testRatio = 0.2
targetColumn = "Target"

# Perform machine learning regression.
metrics, pltObject, objects = mlh.MachineLearningRegression(
  datasetFilePath,
  scalerName,
  modelName,
  fsTechName,
  fsTechRatio,
  testRatio,
  targetColumn,
  dropFirstColumn=True,
)
class HMB.MachineLearningHelper.OptunaTuningClassification(baseDir, scalers, models, fsTechs, fsRatios, dataBalanceTechniques, outliersTechniques, datasetFilename, storageFolderPath, testFilename, testRatio=0.2, contamination=0.05, numTrials=100, prefix='Optuna', samplerTech='TPE', targetColumn='Class', dropFirstColumn=True, dropNAColumns=True, encodeCategorical=True, saveFigures=True, eps=1e-08, loadStudy=True, verbose=False)[source]

Bases: object

Hyperparameter tuning for machine learning classification using Optuna.

This class automates the process of hyperparameter optimization for machine learning pipelines using Optuna. It supports tuning over scalers, models, feature selection techniques and ratios, data balancing techniques, and outlier detection techniques. The class manages study creation, objective evaluation, result storage, and retrieval of the best parameters and study objects.

Parameters:

  • baseDir (str) – Base directory where the dataset is stored.

  • scalers (list) – List of scalers to be used in the tuning process.

  • models (list) – List of machine learning models to be used in the tuning process.

  • fsTechs (list) – List of feature selection techniques to be used in the tuning process.

  • fsRatios (list) – List of feature selection ratios to be used in the tuning process.

  • dataBalanceTechniques (list) – List of data balancing techniques to be used in the tuning process.

  • outliersTechniques (list) – List of outlier detection techniques to be used in the tuning process.

  • datasetFilename (str) – Name of the dataset file to be used for training.

  • storageFolderPath (str) – Path to the folder where results will be stored.

  • testFilename (str) – Name of the test dataset file to be used for evaluation.

  • testRatio (float, optional) – Ratio of the test data to be used in the classification. Default is 0.2.

  • contamination (float, optional) – Proportion of outliers in the data (for outlier detection techniques). Default is 0.05.

  • numTrials (int, optional) – Number of trials for hyperparameter tuning. Default is 100.

  • prefix (str, optional) – Prefix for the study name and storage files. Default is “Optuna”.

  • samplerTech (str, optional) – Sampler technique to be used for hyperparameter tuning. Options are “TPE”, “Random”, “NSGAIISampler”, or “CmaEs”. Default is “TPE”.

  • targetColumn (str, optional) – Name of the target column in the dataset. Default is “Class”.

  • dropFirstColumn (bool, optional) – Whether to drop the first column (usually an index or ID). Default is True.

  • dropNAColumns (bool, optional) – Whether to drop columns with any null values. Default is True.

  • encodeCategorical (bool, optional) – Whether to encode categorical features (if any). Default is True.

  • saveFigures (bool, optional) – Whether to save the performance plots. Default is True.

  • eps (float, optional) – Small value to avoid division by zero (if needed). Default is 1e-8.

  • loadStudy (bool, optional) – Whether to load an existing study if available. Default is True.

  • verbose (bool, optional) – Whether to print verbose output. Default is False.

Variables:

  • study (optuna.study.Study) – The Optuna study object.

  • bestParams (dict) – The best hyperparameters found by the study.

  • bestValue (float) – The best value found by the study.

  • history (list) – List of trial results and metrics.

Example

import HMB.MachineLearningHelper as mlh

tuner = mlh.OptunaTuningClassification(
  baseDir="./data",
  scalers=["Standard", "MinMax"],
  models=["RF", "LR"],
  fsTechs=["PCA", "RF"],
  fsRatios=[50, 100],
  dataBalanceTechniques=["SMOTE", None],
  outliersTechniques=["IQR", None],
  datasetFilename="train.csv",
  storageFolderPath="./results",
  testFilename="test.csv",
  testRatio=0.2,
  contamination=0.05,
  numTrials=50,
  prefix="Optuna",
  samplerTech="TPE",
  targetColumn="Class",
  dropFirstColumn=True,
  dropNAColumns=True,
  encodeCategorical=True,
  saveFigures=True,
  eps=1e-8,
  loadStudy=False,
  verbose=True,
)
tuner.Tune()
print(tuner.GetBestParams())
print(tuner.GetBestValue())

Initializes the OptunaTuningClassification class with the provided hyperparameters.

Parameters:

  • scalers (list) – List of scalers to be used in the tuning process.

  • models (list) – List of machine learning models to be used in the tuning process.

  • fsTechs (list) – List of feature selection techniques to be used in the tuning process.

  • fsRatios (list) – List of feature selection ratios to be used in the tuning process.

  • dataBalanceTechniques (list) – List of data balancing techniques to be used in the tuning process.

  • outliersTechniques (list) – List of outlier detection techniques to be used in the tuning process.

  • baseDir (str) – Base directory where the dataset is stored.

  • datasetFilename (str) – Name of the dataset file to be used for training.

  • storageFolderPath (str) – Path to the folder where results will be stored.

  • testFilename (str) – Name of the test dataset file to be used for evaluation.

  • testRatio (float) – Ratio of the test data to be used in the classification.

  • contamination (float) – Proportion of outliers in the data (for outlier detection techniques).

  • numTrials (int) – Number of trials for hyperparameter tuning.

  • prefix (str) – Prefix for the study name and storage files.

  • samplerTech (str) – Sampler technique to be used for hyperparameter tuning. Options are “TPE”, “Random”, “NSGAIISampler”, or “CmaEs”.

  • targetColumn (str) – Name of the target column in the dataset.

  • dropFirstColumn (bool) – Whether to drop the first column (usually an index or ID).

  • dropNAColumns (bool) – Whether to drop columns with any null values.

  • encodeCategorical (bool) – Whether to encode categorical features (if any).

  • saveFigures (bool) – Whether to save the performance plots.

  • eps (float) – Small value to avoid division by zero (if needed).

  • loadStudy (bool) – Whether to load an existing study if available.

  • verbose (bool) – Whether to print verbose output.

__init__(baseDir, scalers, models, fsTechs, fsRatios, dataBalanceTechniques, outliersTechniques, datasetFilename, storageFolderPath, testFilename, testRatio=0.2, contamination=0.05, numTrials=100, prefix='Optuna', samplerTech='TPE', targetColumn='Class', dropFirstColumn=True, dropNAColumns=True, encodeCategorical=True, saveFigures=True, eps=1e-08, loadStudy=True, verbose=False)[source]

Initializes the OptunaTuningClassification class with the provided hyperparameters.

Parameters:

  • scalers (list) – List of scalers to be used in the tuning process.

  • models (list) – List of machine learning models to be used in the tuning process.

  • fsTechs (list) – List of feature selection techniques to be used in the tuning process.

  • fsRatios (list) – List of feature selection ratios to be used in the tuning process.

  • dataBalanceTechniques (list) – List of data balancing techniques to be used in the tuning process.

  • outliersTechniques (list) – List of outlier detection techniques to be used in the tuning process.

  • baseDir (str) – Base directory where the dataset is stored.

  • datasetFilename (str) – Name of the dataset file to be used for training.

  • storageFolderPath (str) – Path to the folder where results will be stored.

  • testFilename (str) – Name of the test dataset file to be used for evaluation.

  • testRatio (float) – Ratio of the test data to be used in the classification.

  • contamination (float) – Proportion of outliers in the data (for outlier detection techniques).

  • numTrials (int) – Number of trials for hyperparameter tuning.

  • prefix (str) – Prefix for the study name and storage files.

  • samplerTech (str) – Sampler technique to be used for hyperparameter tuning. Options are “TPE”, “Random”, “NSGAIISampler”, or “CmaEs”.

  • targetColumn (str) – Name of the target column in the dataset.

  • dropFirstColumn (bool) – Whether to drop the first column (usually an index or ID).

  • dropNAColumns (bool) – Whether to drop columns with any null values.

  • encodeCategorical (bool) – Whether to encode categorical features (if any).

  • saveFigures (bool) – Whether to save the performance plots.

  • eps (float) – Small value to avoid division by zero (if needed).

  • loadStudy (bool) – Whether to load an existing study if available.

  • verbose (bool) – Whether to print verbose output.

ObjectiveFunction(trial)[source]

Objective function for Optuna to optimize hyperparameters for machine learning classification. This function performs machine learning classification using the specified hyperparameters, saves the results, and returns the weighted average of the metrics.

Parameters:

optuna.Trial – The Optuna trial object containing the hyperparameters to be optimized.

Returns:

The weighted average of the metrics obtained from the machine learning classification.

Return type:

float

Tune()[source]

Tunes the hyperparameters using Optuna for machine learning classification. This function creates an Optuna study, optimizes the objective function, and saves the results including the best hyperparameters, trials history, and performance metrics. It also saves the study object for future reference.

GetStudy()[source]

Returns the Optuna study object.

Returns:

The Optuna study object.

Return type:

optuna.study.Study

GetBestParams()[source]

Returns the best hyperparameters found by the Optuna study.

Returns:

A dictionary containing the best hyperparameters.

Return type:

dict

GetBestValue()[source]

Returns the best value found by the Optuna study.

Returns:

The best value found by the Optuna study.

Return type:

float

LoadStudy(studyFilePath)[source]

Loads the Optuna study from a file.

Parameters:

studyFilePath (str) – The path to the study file.

Returns:

The loaded Optuna study object.

Return type:

optuna.study.Study

HMB.MachineLearningHelper.OptunaTuningClassificationTesting(datasetFilePath, experimentPath, storageDir, dpi=720, T=500, plotCounterfactualOutcomes=False, numberOfTopExperiments=1, sortByMetric='Weighted Average')[source]

Run inference using a saved preprocessing + model objects bundle.

Parameters:

  • datasetFilePath (str) – Path to the dataset file for inference.

  • experimentPath (str) – Path to the experiment folder containing the saved model and preprocessing objects.

  • storageDir (str) – Directory where the performance plots and results will be saved.

  • dpi (int, optional) – DPI for saving the performance plots. Default is 720.

  • T (int, optional) – Number of Monte Carlo samples for uncertainty estimation (if applicable). Default is 500.

  • plotCounterfactualOutcomes (bool, optional) – Whether to plot counterfactual outcomes (if applicable). Default is False.

  • numberOfTopExperiments (int, optional) – Number of top experiments to test based on the best parameters. Default is 1.

  • sortByMetric (str, optional) – The metric by which to sort the experiments when selecting the top experiments. Default is “Weighted Average”.

HMB.MachineLearningHelper.OptunaTuningClassificationTrials(datasetFilePath, experimentPath, storageDir, noOfTrials=10, dpi=720, T=500, plotCounterfactualOutcomes=False, numberOfTopExperiments=1, sortByMetric='Weighted Average')[source]

Run multiple trials of inference using a saved preprocessing + model objects bundle with the best parameters from a previous tuning run.

Parameters:

  • datasetFilePath (str) – Path to the dataset file for inference.

  • experimentPath (str) – Path to the experiment folder containing the saved model and preprocessing objects.

  • storageDir (str) – Directory where the performance plots and results will be saved.

  • noOfTrials (int, optional) – Number of trials to run. Default is 10.

  • dpi (int, optional) – DPI for saving the performance plots. Default is 720.

  • T (int, optional) – Number of Monte Carlo samples for uncertainty estimation (if applicable). Default is 500.

  • plotCounterfactualOutcomes (bool, optional) – Whether to plot counterfactual outcomes (if applicable). Default is False.

  • numberOfTopExperiments (int, optional) – Number of top experiments to test based on the best parameters. Default is 1.

  • sortByMetric (str, optional) – The metric to sort the experiments by when selecting the top experiments. Default is “Weighted Average”.

HMB.MachineLearningHelper.OptunaTuningClassificationTrialsStatistics(trialResultsPath, statisticsStoragePath, dpi=720, plotMetricsIndividual=False, plotMetricsOverall=False, includeAverageInPlots=False)[source]

Analyze the results from multiple trials of inference using a saved preprocessing + model objects bundle with the best parameters from a previous tuning run.

Parameters:

  • trialResultsPath (str) – Path to the directory containing the results of multiple trials.

  • statisticsStoragePath (str) – Directory where the aggregated performance plots and statistics will be saved.

  • dpi (int, optional) – DPI for saving the performance plots. Default is 720.

  • plotMetricsIndividual (bool, optional) – Whether to plot performance metrics for individual trials. Default is False.

  • plotMetricsOverall (bool, optional) – Whether to plot aggregated performance metrics across all trials. Default is False.

  • includeAverageInPlots (bool, optional) – Whether to include the average performance across trials in the plots. Default is False.

Returns:

A dictionary containing the aggregated performance metrics and results from all trials.

Return type:

dict