epicon 0.3.0__py3-none-any.whl

epicon/__init__.py

@@ -0,0 +1,78 @@
+"""
+============================================================
+Epicon
+============================================================
+
+A lightweight, from-scratch machine learning library built on
+NumPy with optional Numba acceleration. Provides a unified API
+for neural networks and traditional ML models, designed to be
+a minimal yet capable alternative to PyTorch/TensorFlow for
+everyday ML tasks.
+
+Key Design Principles:
+    - Simple, consistent API (fit/predict) across all models
+    - Minimal dependencies (NumPy required, Numba optional)
+    - Educational transparency — readable, documented source
+    - Fast execution via vectorized NumPy and optional Numba JIT
+
+Quick Start:
+    >>> import epicon
+    >>> from epicon.datasets import load_iris
+    >>> X, y = load_iris(return_X_y=True)
+    >>> model = epicon.LogisticRegression()
+    >>> model.fit(X, y)
+    >>> model.predict(X[:5])
+"""
+
+# ---------------------------------------------------------------------------
+# Neural Network Components
+# ---------------------------------------------------------------------------
+from epicon.activations import Activation, LeakyReLU, ReLU, Sigmoid, Softmax, Tanh
+
+# ---------------------------------------------------------------------------
+# Datasets
+# ---------------------------------------------------------------------------
+from epicon.datasets import load_iris, load_mnist, make_classification, make_regression
+from epicon.ensemble import RandomForestClassifier, RandomForestRegressor
+from epicon.layers import Conv1D, Dense, Dropout, Layer
+
+# ---------------------------------------------------------------------------
+# Traditional ML Models
+# ---------------------------------------------------------------------------
+from epicon.linear_model import Lasso, LinearRegression, LogisticRegression, Ridge
+from epicon.losses import MSE, BinaryCrossEntropy, CategoricalCrossEntropy, Loss
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+from epicon.metrics import (
+    accuracy_score,
+    confusion_matrix,
+    f1_score,
+    mean_absolute_error,
+    mean_squared_error,
+    precision_score,
+    r2_score,
+    recall_score,
+)
+from epicon.models import Model, Sequential
+from epicon.naive_bayes import GaussianNB
+from epicon.neighbors import KNeighborsClassifier, KNeighborsRegressor
+from epicon.optimizers import Adam, GradientDescent, Momentum, Optimizer
+
+# ---------------------------------------------------------------------------
+# Preprocessing & Utilities
+# ---------------------------------------------------------------------------
+from epicon.preprocessing import (
+    LabelEncoder,
+    MinMaxScaler,
+    OneHotEncoder,
+    StandardScaler,
+    train_test_split,
+)
+from epicon.tree import DecisionTreeClassifier, DecisionTreeRegressor
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+__version__ = "0.3.0"

epicon/_jit.py

@@ -0,0 +1,250 @@
+"""
+---------------------------------------------------------
+NUMBA JIT COMPILED KERNELS FOR PERFORMANCE-CRITICAL LOOPS
+---------------------------------------------------------
+
+Optional Numba acceleration for tree-based models, KNN,
+and other algorithms with non-vectorizable loops.
+If Numba is not installed, pure Python fallbacks are used.
+"""
+
+import numpy as np
+
+try:
+    import numba as nb
+
+    HAS_NUMBA = True
+except ImportError:
+    HAS_NUMBA = False
+    nb = None
+
+
+def _jit_if_available(func=None, *, nopython=True, parallel=False, **kwargs):
+    """
+    Decorator that applies Numba JIT only if Numba is installed.
+    Can be used with or without arguments.
+
+    Usage:
+        @_jit_if_available
+        def my_func(x): ...
+
+        @_jit_if_available(nopython=True, parallel=True)
+        def my_func(x): ...
+    """
+
+    def decorator(f):
+        if HAS_NUMBA:
+            return nb.jit(f, nopython=nopython, parallel=parallel, **kwargs)
+        return f
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Tree split helpers
+# ---------------------------------------------------------------------------
+
+
+@_jit_if_available
+def _gini_impurity(left_counts, right_counts, total_left, total_right, total_samples):
+    """
+    Compute weighted Gini impurity for a binary split.
+
+    Args:
+        left_counts (np.ndarray): Class counts in left child.
+        right_counts (np.ndarray): Class counts in right child.
+        total_left (int): Total samples in left child.
+        total_right (int): Total samples in right child.
+        total_samples (int): Total samples in parent.
+
+    Returns:
+        float: Weighted Gini impurity of the split.
+    """
+    if total_left == 0 or total_right == 0:
+        return 0.0
+
+    left_gini = 1.0 - np.sum((left_counts / total_left) ** 2)
+    right_gini = 1.0 - np.sum((right_counts / total_right) ** 2)
+
+    return (total_left / total_samples) * left_gini + (total_right / total_samples) * right_gini
+
+
+@_jit_if_available
+def _entropy_impurity(left_counts, right_counts, total_left, total_right, total_samples):
+    """
+    Compute weighted entropy for a binary split.
+
+    Args:
+        left_counts (np.ndarray): Class counts in left child.
+        right_counts (np.ndarray): Class counts in right child.
+        total_left (int): Total samples in left child.
+        total_right (int): Total samples in right child.
+        total_samples (int): Total samples in parent.
+
+    Returns:
+        float: Weighted entropy of the split.
+    """
+    if total_left == 0 or total_right == 0:
+        return 0.0
+
+    def _entropy(counts, total):
+        if total == 0:
+            return 0.0
+        probs = counts / total
+        probs = probs[probs > 0]
+        return -np.sum(probs * np.log2(probs))
+
+    left_ent = _entropy(left_counts, total_left)
+    right_ent = _entropy(right_counts, total_right)
+
+    return (total_left / total_samples) * left_ent + (total_right / total_samples) * right_ent
+
+
+@_jit_if_available
+def _mse_split(left_y, right_y):
+    """
+    Compute weighted MSE for a binary split.
+
+    Args:
+        left_y (np.ndarray): Target values in left child.
+        right_y (np.ndarray): Target values in right child.
+
+    Returns:
+        float: Weighted MSE of the split.
+    """
+    total = len(left_y) + len(right_y)
+    if total == 0:
+        return 0.0
+
+    left_mse = np.var(left_y) * len(left_y) if len(left_y) > 0 else 0.0
+    right_mse = np.var(right_y) * len(right_y) if len(right_y) > 0 else 0.0
+
+    return (left_mse + right_mse) / total
+
+
+@_jit_if_available
+def _best_split_numeric(X_column, y, num_classes, criterion, min_samples_split, min_samples_leaf):
+    """
+    Find the best threshold for a numeric feature.
+
+    Args:
+        X_column (np.ndarray): Feature values (sorted).
+        y (np.ndarray): Target values.
+        num_classes (int): Number of classes (1 for regression).
+        criterion (str): 'gini', 'entropy', or 'mse'.
+        min_samples_split (int): Minimum samples to split.
+        min_samples_leaf (int): Minimum samples per leaf.
+
+    Returns:
+        tuple: (best_threshold, best_impurity) or (None, inf).
+    """
+    n = len(X_column)
+    best_threshold = None
+    best_score = np.inf
+
+    if n < min_samples_split:
+        return None, np.inf
+
+    # Unique thresholds at midpoints between sorted values
+    unique_vals = np.unique(X_column)
+    if len(unique_vals) == 1:
+        return None, np.inf
+
+    thresholds = (unique_vals[:-1] + unique_vals[1:]) / 2.0
+
+    for threshold in thresholds:
+        left_mask = X_column <= threshold
+        right_mask = ~left_mask
+
+        left_count = np.sum(left_mask)
+        right_count = np.sum(right_mask)
+
+        if left_count < min_samples_leaf or right_count < min_samples_leaf:
+            continue
+
+        if criterion == "mse":
+            score = _mse_split(y[left_mask], y[right_mask])
+        elif criterion in ("gini", "entropy"):
+            left_y = y[left_mask].astype(np.int64)
+            right_y = y[right_mask].astype(np.int64)
+
+            left_counts = np.zeros(num_classes, dtype=np.float64)
+            right_counts = np.zeros(num_classes, dtype=np.float64)
+
+            for c in range(num_classes):
+                left_counts[c] = np.sum(left_y == c)
+                right_counts[c] = np.sum(right_y == c)
+
+            if criterion == "gini":
+                score = _gini_impurity(left_counts, right_counts, left_count, right_count, n)
+            else:
+                score = _entropy_impurity(left_counts, right_counts, left_count, right_count, n)
+        else:
+            raise ValueError(f"Unknown criterion: {criterion}")
+
+        if score < best_score:
+            best_score = score
+            best_threshold = threshold
+
+    return best_threshold, best_score
+
+
+# ---------------------------------------------------------------------------
+# KNN distance helpers
+# ---------------------------------------------------------------------------
+
+
+@_jit_if_available
+def _euclidean_distance(x1, x2):
+    """
+    Compute Euclidean distance between two vectors.
+    """
+    diff = x1 - x2
+    return np.sqrt(np.dot(diff, diff))
+
+
+@_jit_if_available
+def _manhattan_distance(x1, x2):
+    """
+    Compute Manhattan distance between two vectors.
+    """
+    return np.sum(np.abs(x1 - x2))
+
+
+@_jit_if_available
+def _knn_predict_single(x_test, X_train, y_train, k, metric="euclidean"):
+    """
+    Predict label for a single test point using KNN.
+
+    Args:
+        x_test (np.ndarray): Single test sample.
+        X_train (np.ndarray): Training data.
+        y_train (np.ndarray): Training labels.
+        k (int): Number of neighbors.
+        metric (str): 'euclidean' or 'manhattan'.
+
+    Returns:
+        float: Predicted label (for classification, returns the majority class).
+    """
+    n_train = X_train.shape[0]
+    distances = np.zeros(n_train)
+
+    for i in range(n_train):
+        if metric == "euclidean":
+            distances[i] = _euclidean_distance(x_test, X_train[i])
+        else:
+            distances[i] = _manhattan_distance(x_test, X_train[i])
+
+    # Get indices of k smallest distances
+    indices = np.argsort(distances)[:k]
+    k_nearest = y_train[indices]
+
+    # For regression, return mean; for classification, return mode
+    if np.issubdtype(y_train.dtype, np.floating) or len(np.unique(y_train)) > 20:
+        return np.mean(k_nearest)
+    else:
+        # Return mode (most common)
+        counts = np.bincount(k_nearest.astype(np.int64))
+        return np.argmax(counts)

epicon/activations/__init__.py

@@ -0,0 +1,8 @@
+from epicon.activations.base import Activation
+from epicon.activations.leaky_relu import LeakyReLU
+from epicon.activations.relu import ReLU
+from epicon.activations.sigmoid import Sigmoid
+from epicon.activations.softmax import Softmax
+from epicon.activations.tanh import Tanh
+
+__all__ = ["Activation", "ReLU", "Softmax", "Sigmoid", "LeakyReLU", "Tanh"]

epicon/activations/base.py

@@ -0,0 +1,21 @@
+from epicon.layers.base import Layer
+
+
+class Activation(Layer):
+    """
+    -----------------------------------
+    BASE CLASS FOR ACTIVATION FUNCTIONS
+    -----------------------------------
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    def forward(self, inputs):
+        raise NotImplementedError
+
+    def backward(self, dvalues):
+        raise NotImplementedError
+
+    def get_params(self):
+        return super().get_params()

epicon/activations/leaky_relu.py

@@ -0,0 +1,65 @@
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class LeakyReLU(Activation):
+    """
+    -----------------------------------------------
+              LEAKY RELU ACTIVATION FUNCTION
+    f(x) = x if x > 0, otherwise f(x) = α * x
+    This prevents neurons from "dying" by allowing a small,
+    non-zero gradient when the unit is not active.
+    -----------------------------------------------
+    """
+
+    def __init__(self, alpha=0.01):
+        """
+        Initialize the LeakyReLU with a given alpha.
+
+        Parameters:
+            alpha (float): the small constant multiplier for negative inputs. Default is 0.01.
+        """
+        self.alpha = alpha
+
+    def forward(self, inputs):
+        """
+        The forward pass applies the LeakyReLU function.
+
+        Parameters:
+            inputs (ndarray): input data to the layer
+
+        Returns:
+            output (ndarray): transformed output of the layer
+        """
+        self.inputs = inputs
+        # For each element, if positive keep it; if negative, multiply by alpha
+        self.output = np.where(inputs > 0, inputs, self.alpha * inputs)
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        The backward pass computes the gradient of the loss with respect to the inputs.
+
+        Parameters:
+            dvalues (ndarray): the gradient from the next layer
+
+        Returns:
+            dinputs (ndarray): the gradient with respect to the inputs of this layer
+        """
+        # Initialize gradient as a copy of dvalues
+        self.dinputs = np.copy(dvalues)
+        # For inputs <= 0, multiply the gradient by alpha
+        self.dinputs[self.inputs <= 0] *= self.alpha
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "LeakyReLU", "attrs": {"alpha": self.alpha}}
+
+    @override
+    def set_params(self, params: dict):
+        for key, val in params.items():
+            setattr(self, key, val)

epicon/activations/relu.py

@@ -0,0 +1,37 @@
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class ReLU(Activation):
+    """
+    -----------------------------------------------
+    RECTIFIED LINEAR UNIT (ReLU) ACTIVATION FUNCTION
+    f(x) = max(0, x)
+    -----------------------------------------------
+    """
+
+    def forward(self, inputs):
+        """
+        The `forward` function takes an input array, applies a ReLU activation function element-wise,
+        and returns the resulting output array.
+        """
+        self.inputs = inputs
+        self.output = np.maximum(0, inputs)
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        The `backward` function calculates the derivative of the inputs with respect to the given values
+        and sets the derivative to zero for inputs less than or equal to zero.
+        """
+
+        self.dinputs = dvalues.copy()
+        self.dinputs[self.inputs <= 0] = 0
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "ReLU", "attrs": {}}

epicon/activations/sigmoid.py

@@ -0,0 +1,37 @@
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class Sigmoid(Activation):
+    """
+    -----------------------------------------------
+            SIGMOID ACTIVATION FUNCTION
+    f(x) = 1 / (1 + e ^ (-x))
+    USED TO MAP ANY INPUT TO A VALUE BETWEEN 0 AND 1
+    -----------------------------------------------
+    """
+
+    def forward(self, inputs):
+        """
+        The forward function takes inputs, applies the sigmoid function, and returns the output.
+        """
+        self.inputs = inputs
+        self.output = 1 / (1 + np.exp(-inputs))
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        The `backward` function calculates the derivative of the inputs based on the output and the
+        given derivative values.
+        """
+
+        # derivative of the sigmoid: f'(x) = f(x) * (1 - f(x))
+        self.dinputs = dvalues * (self.output * (1 - self.output))
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "Sigmoid", "attrs": {}}

epicon/activations/softmax.py

@@ -0,0 +1,94 @@
+"""
+---------------------------------------------------------
+                    SOFTMAX ACTIVATION FUNCTION
+---------------------------------------------------------
+The Softmax activation function converts a vector of raw scores (logits)
+into a probability distribution. It is commonly used as the activation
+function in the output layer of a classification model.
+
+Given a vector of raw scores, the softmax function computes the
+probability for each class using the following formula:
+
+    f(x_i) = exp(x_i) / sum(exp(x_j) for j in all classes)
+
+Where:
+    - x_i is the raw score (logit) for class i.
+    - f(x_i) is the probability of class i.
+
+The function ensures that all the probabilities sum up to 1, making it suitable
+for classification tasks where the model needs to output a probability distribution.
+
+Attributes:
+    inputs (ndarray): Raw input data (logits).
+    output (ndarray): Output probabilities after applying softmax.
+    dinputs (ndarray): Gradient of the loss with respect to the inputs.
+
+Methods:
+    forward(inputs):
+        Computes the forward pass of the softmax activation function.
+
+    backward(dvalues):
+        Computes the backward pass, propagating gradients through the softmax function.
+---------------------------------------------------------
+"""
+
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class Softmax(Activation):
+    def __init__(self):
+        super().__init__()
+        self.inputs = None
+        self.output = None
+        self.dinputs = None
+
+    def forward(self, inputs):
+        """
+        Forward pass of Softmax.
+
+        Args:
+            inputs (ndarray): Raw scores (logits).
+
+        Returns:
+            ndarray: Probabilities.
+        """
+        self.inputs = inputs
+
+        # Sanity check to see if inputs are valid to work with
+        if np.isnan(inputs).any() or np.isinf(inputs).any():
+            raise ValueError("NaN values detected in Softmax output.")
+
+        # Subtract the max value for numerical stability
+        # This won't cause any error as Softmax isn't scale dependent
+        exponent_values = np.exp(inputs - np.max(inputs, axis=1, keepdims=True))
+
+        probabilites = exponent_values / np.sum(exponent_values, axis=1, keepdims=True)
+
+        self.output = probabilites
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        Backward pass of Softmax.
+
+        NOTE: Normally used together with cross-entropy loss,
+        and we use the combined derivative for efficiency.
+
+        This method assumes dvalues already contains the proper gradient.
+
+        Args:
+            dvalues (ndarray): Gradient from loss.
+
+        Returns:
+            ndarray: Gradient of the loss with respect to the inputs.
+        """
+        self.dinputs = dvalues  # usually combined with loss
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "Softmax", "attrs": {}}

epicon/activations/tanh.py

@@ -0,0 +1,80 @@
+"""
+---------------------------------------------------------
+                    TANH ACTIVATION FUNCTION
+---------------------------------------------------------
+The Tanh activation function maps input values to the range of
+[-1, 1]. It is commonly used in hidden layers of neural networks.
+
+Given an input, the tanh function is defined as:
+
+    f(x) = (exp(x) - exp(-x)) / (exp(x) + exp(-x))
+
+Where:
+    - x is the input value.
+
+The function outputs values between -1 and 1, and it is symmetric
+around the origin, making it suitable for tasks where both positive
+and negative values are important.
+
+Attributes:
+    inputs (ndarray): Input data passed to the activation function.
+    output (ndarray): Output values after applying the tanh function.
+    dinputs (ndarray): Gradient of the loss with respect to the inputs.
+
+Methods:
+    forward(inputs):
+        Computes the forward pass for the tanh activation function.
+
+    backward(dvalues):
+        Computes the backward pass, propagating gradients through the tanh function.
+---------------------------------------------------------
+"""
+
+from typing import override
+
+import numpy as np
+
+from epicon.activations.base import Activation
+
+
+class Tanh(Activation):
+    def __init__(self):
+        self.inputs = None
+        self.output = None
+        self.dinputs = None
+
+    def forward(self, inputs):
+        """
+        Forward pass of Tanh.
+
+        Args:
+            inputs (ndarray): Input values.
+
+        Returns:
+            ndarray: Output values after applying tanh.
+        """
+        self.inputs = inputs
+
+        output = np.tanh(inputs)
+        if np.isnan(output).any():
+            raise ValueError("NaN values detected in Softmax output.")
+
+        self.output = output
+        return self.output
+
+    def backward(self, dvalues):
+        """
+        Backward pass of Tanh.
+
+        Args:
+            dvalues (ndarray): Gradient from the next layer.
+
+        Returns:
+            ndarray: Gradient with respect to the inputs.
+        """
+        self.dinputs = dvalues * (1 - self.output**2)
+        return self.dinputs
+
+    @override
+    def get_params(self):
+        return {"type": "Tanh", "attrs": {}}

epicon/datasets/__init__.py

@@ -0,0 +1,4 @@
+from epicon.datasets.generator import make_classification, make_regression
+from epicon.datasets.loader import load_iris, load_mnist
+
+__all__ = ["load_iris", "load_mnist", "make_classification", "make_regression"]