utelearn

utelearn is a custom machine learning library built from scratch for educational purposes at UTE.

Installation

You can install the package directly from PyPI:

pip install utelearn

Features

• KMeans Clustering: Custom implementation of the KMeans clustering algorithm using NumPy.
• Built-in support for data visualization with Matplotlib.

Quick Start

Here are quick examples of how to use the machine learning libs from utelearn:

K-Means

Kmeans Clustering Example

import numpy as np
import matplotlib.pyplot as plt
from utelearn.kmeans import KMeans

# 1. Tạo dữ liệu mẫu ngẫu nhiên (2 cụm rõ rệt)
np.random.seed(42)
X = np.vstack([
    np.random.randn(50, 2) + np.array([2, 2]),
    np.random.randn(50, 2) + np.array([-2, -2])
])

# 2. Khởi tạo và huấn luyện mô hình K-Means với k=2
kmeans = KMeans(k=2, max_iters=100)
kmeans.fit(X)

# 3. In kết quả trung tâm cụm (centroids)
print("Tọa độ các tâm cụm (Centroids):")
print(kmeans.centroids)

# 4. Dự đoán nhãn cho các điểm dữ liệu (nếu lớp KMeans có hàm predict)
# Hoặc gán nhãn dựa vào khoảng cách gần nhất tới các centroids
labels = np.argmin([np.linalg.norm(X - c, axis=1) for c in kmeans.centroids], axis=0)

# 5. Vẽ biểu đồ trực quan
plt.figure(figsize=(8, 6))
plt.scatter(X[:, 0], X[:, 1], c=labels, cmap='viridis', marker='o', alpha=0.7, edgecolors='k', label='Dữ liệu mẫu')
plt.scatter(kmeans.centroids[:, 0], kmeans.centroids[:, 1], c='red', marker='X', s=250, edgecolors='k', label='Tâm cụm (Centroids)')

plt.title("Trực quan hóa thuật toán K-Means - Utelearn", fontsize=14)
plt.xlabel("Trục X", fontsize=12)
plt.ylabel("Trục Y", fontsize=12)
plt.legend()
plt.grid(True, linestyle='--', alpha=0.5)
plt.show()

K-Nearest Neighbors (KNN)

1. KNN Regression & Classification Example

import numpy as np
from utelearn import knn

# Generate synthetic training data
X_train = np.random.rand(100, 1)
y_train = 4 * X_train**2 + 3 * X_train + 2 + np.random.randn(100, 1) * 0.1

# Generate test points
X_test = np.linspace(0, 1, 10).reshape(-1, 1)

# Perform KNN regression with k=5
predictions = knn.knn_regression(X_train, y_train, X_test, k=5)
print("Regression Predictions:", predictions)

# Generate synthetic training and test features/labels
X_train = np.random.rand(100, 2)
y_train = np.random.randint(0, 3, size=100) # 3 classes
X_test = np.random.rand(10, 2)

# Perform KNN classification with k=5
predictions = knn.knn_classify(X_train, y_train, X_test, k=5, n_classes=3)
print("Classification Predictions:", predictions)

K-Nearest Neighbors (KNN)

1. KNN Regression & Classification Example using Points Lib

import numpy as np
import matplotlib.pyplot as plt
import matplotlib.colors as mcolors
from utelearn import knn
from utelearn import points as point

# 1. Configuration parameters
n_training_points = 100
n_test_points = 500
n_classes = 3
dimension = 2
k_neighbors = 5

# 2. Generate Training and Test Data using utelearn's points module (Spiral Distribution)
training_data = point.Spiral(n_training_points, n_classes, dimension)
test_data = point.Spiral(n_test_points, n_classes, dimension)

# 3. Perform KNN Classification using utelearn's knn module
print("Running KNN classification on test data using utelearn...")
predicted_labels = knn.knn_classify(
    X_train=training_data.P, 
    y_train=training_data.L, 
    X_test=test_data.P, 
    k=k_neighbors, 
    n_classes=n_classes
)

# 4. Plotting the Results
plt.figure(figsize=(15, 5))

# Subplot 1: Reference Training Data
plt.subplot(1, 3, 1)
plt.scatter(
    training_data.P[:, 0], 
    training_data.P[:, 1], 
    c=training_data.L, 
    s=20, 
    cmap=mcolors.ListedColormap(["red", "purple", "green"])
)
plt.title(f"Reference Data ({n_training_points * n_classes} points)")
plt.grid(True, alpha=0.3)

# Subplot 2: Unclassified Test Data
plt.subplot(1, 3, 2)
plt.scatter(
    test_data.P[:, 0], 
    test_data.P[:, 1], 
    color="blue", 
    s=15
)
plt.title("Unclassified Test Data")
plt.grid(True, alpha=0.3)

# Subplot 3: Classified Test Data via utelearn KNN
plt.subplot(1, 3, 3)
plt.scatter(
    test_data.P[:, 0], 
    test_data.P[:, 1], 
    c=predicted_labels, 
    s=15, 
    cmap=mcolors.ListedColormap(["red", "purple", "green"])
)
plt.title(f"Test Data After KNN (k={k_neighbors})")
plt.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

Naives Bayes Classifier (using Gaussian probability density function)

Classification Example using Points Lib

import numpy as np 
import matplotlib.pyplot as plt 
from utelearn import points as point  
from utelearn import naives_bayes as nb

# Configuration parameters
n_generated_points = 1000  
n_classes = 3 
dimension = 2  
N_total = n_generated_points * n_classes  

###############################################################
################### Generate Training Data ####################
###############################################################
Generated_Data = point.Circle(n_generated_points, n_classes, dimension)  
X = np.column_stack((Generated_Data.P[:, 0], Generated_Data.P[:, 1]))
y = Generated_Data.L 

# Train the Naive Bayes classifier using the custom library
means, vars, priors = nb.train_naive_bayes(X, y) 

############################################################## 
################### Generate Test Data ####################### 
############################################################## 
Generated_Data1 = point.Circle(n_generated_points, n_classes, dimension)  
X_test = np.column_stack((Generated_Data1.P[:, 0], Generated_Data1.P[:, 1]))
y_test = Generated_Data1.L 

# Predict on the test data 
y_pred = nb.predict_naive_bayes(X_test, means, vars, priors) 

# Print predictions and actual labels 
print("Predictions:", y_pred) 
print("Actual labels:", y_test) 

# Calculate and print accuracy 
accuracy = np.mean(y_pred == y_test) 
print(f'Accuracy: {accuracy * 100:.2f}%') 

########################################################################## 
####################  Visualization Section  #############################
##########################################################################
x_min, x_max = X[:, 0].min() - 1, X[:, 0].max() + 1 
y_min, y_max = X[:, 1].min() - 1, X[:, 1].max() + 1 
xx, yy = np.meshgrid(np.arange(x_min, x_max, 0.1), np.arange(y_min, y_max, 0.1)) 

# Predict labels for all points in the meshgrid 
grid_points = np.c_[xx.ravel(), yy.ravel()] 
Z = nb.predict_naive_bayes(grid_points, means, vars, priors) 
Z = Z.reshape(xx.shape) 

# Plotting side-by-side comparison
plt.figure(figsize=(12, 5))

# Subplot 1: Original Test Data
plt.subplot(1, 2, 1)
plt.scatter(X_test[:, 0], X_test[:, 1], c=y_test, cmap='coolwarm', edgecolors='k', marker='o', label='Test Data Points') 
plt.xlabel('Feature X_test[0]') 
plt.ylabel('Feature X_test[1]') 
plt.title(f'Test Data ({n_classes} Classes)') 

# Subplot 2: Decision Boundary
plt.subplot(1, 2, 2)
plt.contourf(xx, yy, Z, alpha=0.3, cmap='coolwarm') 
plt.scatter(X_test[:, 0], X_test[:, 1], c=y_pred, cmap='coolwarm', edgecolors='k', marker='o', label='Predictions') 
plt.xlabel('Feature X_test[0]') 
plt.ylabel('Feature X_test[1]') 
plt.title(f'Naive Bayes Decision Boundary ({n_classes} Classes)') 
plt.legend(loc='best') 

plt.tight_layout()
plt.show()

Author

• Dung Cai (dung.cai@hcmute.edu.vn)

Co-Authors

• Dang Khoa Bui
• Minh Tri Huynh