coreLearn 0.1.0__py3-none-any.whl

coreLearn/linear_regression.py

@@ -0,0 +1,205 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from .base import BaseModel
+
+
+# ---------------------------------------------------------------------------
+# Strategy interface
+# ---------------------------------------------------------------------------
+
+class OptimizationStrategy(ABC):
+    """Abstract base class for optimization strategies."""
+
+    @abstractmethod
+    def fit(self, X: np.ndarray, y: np.ndarray) -> np.ndarray:
+        """Fit weights to the given design matrix X and target vector y."""
+
+
+# ---------------------------------------------------------------------------
+# Concrete strategies
+# ---------------------------------------------------------------------------
+
+class NormalEquationStrategy(OptimizationStrategy):
+    """
+    Closed-form solution: w = argmin ||Xw - y||^2
+
+    Uses np.linalg.lstsq (SVD-based) instead of the textbook (X^T X)^-1 X^T y
+    formula. Direct inversion squares the condition number of X and causes
+    numerical warnings on ill-conditioned data; lstsq avoids this entirely.
+    """
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> np.ndarray:
+        weights, _, _, _ = np.linalg.lstsq(X, y, rcond=None)
+        return weights
+
+
+class GradientDescentStrategy(OptimizationStrategy):
+    """
+    Batch gradient descent: w <- w - lr * (1/n) * X^T (Xw - y)
+
+    Numerical stability:
+    - np.errstate(all='ignore') suppresses NumPy overflow/invalid warnings
+      that would otherwise fire during the matmul before any check runs.
+    - np.isfinite guards catch divergence and stop the loop early.
+
+    Tip: normalize X and y with StandardScaler before training on
+    large or unscaled datasets (see example.py section 2b).
+    """
+
+    def __init__(self, learning_rate: float = 0.01, epochs: int = 1000) -> None:
+        self.learning_rate: float = learning_rate
+        self.epochs: int = epochs
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> np.ndarray:
+        w: np.ndarray = np.zeros(X.shape[1])
+        n: int = len(y)
+
+        with np.errstate(all='ignore'):
+            for _ in range(self.epochs):
+                residual: np.ndarray = X @ w - y
+                if not np.isfinite(residual).all():
+                    break
+                grad: np.ndarray = X.T @ residual / n
+                if not np.isfinite(grad).all():
+                    break
+                w -= self.learning_rate * grad
+
+        return w
+
+
+# ---------------------------------------------------------------------------
+# LinearRegression model
+# ---------------------------------------------------------------------------
+
+class LinearRegression(BaseModel):
+    """
+    Linear Regression model: y = X * w + b
+
+    The optimization algorithm is selected by name and encapsulated in an
+    OptimizationStrategy object — callers never interact with the strategy
+    directly (Strategy Pattern).
+
+    Parameters
+    ----------
+    strategy      : 'normal' (default) or 'gradient_descent'
+    learning_rate : learning rate — gradient_descent only
+    epochs        : number of iterations — gradient_descent only
+    """
+
+    def __init__(
+        self,
+        strategy: str = "normal",
+        learning_rate: float = 0.01,
+        epochs: int = 1000,
+    ) -> None:
+        if strategy == "normal":
+            self._strategy: OptimizationStrategy = NormalEquationStrategy()
+        elif strategy == "gradient_descent":
+            self._strategy = GradientDescentStrategy(
+                learning_rate=learning_rate, epochs=epochs
+            )
+        else:
+            raise ValueError(
+                f"Unknown strategy '{strategy}'. Use 'normal' or 'gradient_descent'."
+            )
+        self._weights: np.ndarray | None = None
+        self._n_features: int = 0
+
+    # ------------------------------------------------------------------
+    # Training
+    # ------------------------------------------------------------------
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> "LinearRegression":
+        """Fit the model to training data X and target vector y."""
+        X = np.array(X, dtype=float)
+        y = np.array(y, dtype=float)
+
+        if X.ndim == 1:
+            X = X.reshape(-1, 1)   # (n,) -> (n, 1) single-feature convenience
+        if X.ndim != 2:
+            raise ValueError(
+                f"X must be 2-D (n_samples, n_features), got shape {X.shape}."
+            )
+        if len(X) == 0:
+            raise ValueError("Training data X must not be empty.")
+        if len(y) == 0:
+            raise ValueError("Target vector y must not be empty.")
+        if len(X) != len(y):
+            raise ValueError(
+                f"X and y must have the same number of samples: {len(X)} != {len(y)}."
+            )
+
+        self._n_features = X.shape[1]
+        X_b: np.ndarray = np.c_[np.ones(len(X)), X]  
+        self._weights = self._strategy.fit(X_b, y)
+        return self
+
+    # ------------------------------------------------------------------
+    # Prediction
+    # ------------------------------------------------------------------
+
+    def predict(self, X: np.ndarray) -> list[float]:
+        """
+        Return predictions as a plain Python list.
+
+        Returns list (not np.ndarray) to stay consistent with
+        BaseModel.predict() — satisfying the Liskov Substitution Principle.
+        Use predict_array() when NumPy output is needed.
+        """
+        if self._weights is None:
+            raise RuntimeError("Call fit() before predict().")
+        X = np.array(X, dtype=float)
+        if X.ndim == 1:
+            X = X.reshape(-1, 1)
+        if X.ndim != 2:
+            raise ValueError(
+                f"X must be 2-D (n_samples, n_features), got shape {X.shape}."
+            )
+        if len(X) == 0:
+            return []
+        if X.shape[1] != self._n_features:
+            raise ValueError(
+                f"Feature count mismatch: model was trained with {self._n_features} "
+                f"features, but X has {X.shape[1]}."
+            )
+        X_b: np.ndarray = np.c_[np.ones(len(X)), X]
+        with np.errstate(all='ignore'): 
+            return (X_b @ self._weights).tolist()
+
+    def predict_array(self, X: np.ndarray) -> np.ndarray:
+        """Return predictions as a NumPy array."""
+        if self._weights is None:
+            raise RuntimeError("Call fit() before predict().")
+        X = np.array(X, dtype=float)
+        if X.ndim == 1:
+            X = X.reshape(-1, 1)
+        if X.ndim != 2:
+            raise ValueError(
+                f"X must be 2-D (n_samples, n_features), got shape {X.shape}."
+            )
+        if len(X) == 0:
+            return np.array([])
+        if X.shape[1] != self._n_features:
+            raise ValueError(
+                f"Feature count mismatch: model was trained with {self._n_features} "
+                f"features, but X has {X.shape[1]}."
+            )
+        X_b: np.ndarray = np.c_[np.ones(len(X)), X]
+        with np.errstate(all='ignore'): 
+            return X_b @ self._weights
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def coef_(self) -> np.ndarray:
+        """Learned feature coefficients (excludes the bias term)."""
+        return self._weights[1:]
+
+    @property
+    def intercept_(self) -> float:
+        """Learned bias (intercept) term."""
+        return float(self._weights[0])

coreLearn/tests/test_distances.py

@@ -0,0 +1,187 @@
+"""Unit tests for DistanceMetric subclasses and DistanceMetricFactory."""
+
+import math
+
+import pytest
+from coreLearn import DistanceMetric, DistanceMetricFactory
+
+
+# ---------------------------------------------------------------------------
+# EuclideanDistance
+# ---------------------------------------------------------------------------
+
+def test_euclidean_basic():
+    """3-4-5 üçgeni: sqrt(3²+4²) = 5."""
+    metric = DistanceMetricFactory.create("euclidean")
+    assert metric.compute([0, 0], [3, 4]) == pytest.approx(5.0)
+
+
+def test_euclidean_same_point():
+    """Aynı noktalar arası mesafe sıfır olmalı."""
+    metric = DistanceMetricFactory.create("euclidean")
+    assert metric.compute([1, 2, 3], [1, 2, 3]) == pytest.approx(0.0)
+
+
+def test_euclidean_1d():
+    """Tek boyutlu: |7 - 3| = 4."""
+    metric = DistanceMetricFactory.create("euclidean")
+    assert metric.compute([3], [7]) == pytest.approx(4.0)
+
+
+def test_euclidean_symmetry():
+    """Mesafe simetriktir: d(a,b) == d(b,a)."""
+    metric = DistanceMetricFactory.create("euclidean")
+    assert metric.compute([1, 2], [5, 6]) == pytest.approx(metric.compute([5, 6], [1, 2]))
+
+
+def test_euclidean_callable():
+    """DistanceMetric nesnesi fonksiyon gibi çağrılabilmeli (__call__)."""
+    metric = DistanceMetricFactory.create("euclidean")
+    assert metric([0, 0], [3, 4]) == pytest.approx(5.0)
+
+
+# ---------------------------------------------------------------------------
+# ManhattanDistance
+# ---------------------------------------------------------------------------
+
+def test_manhattan_basic():
+    """|3-0| + |4-0| = 7."""
+    metric = DistanceMetricFactory.create("manhattan")
+    assert metric.compute([0, 0], [3, 4]) == pytest.approx(7.0)
+
+
+def test_manhattan_same_point():
+    """Aynı noktalar arası mesafe sıfır olmalı."""
+    metric = DistanceMetricFactory.create("manhattan")
+    assert metric.compute([2, 5], [2, 5]) == pytest.approx(0.0)
+
+
+def test_manhattan_1d():
+    """Tek boyutlu: |1 - 9| = 8."""
+    metric = DistanceMetricFactory.create("manhattan")
+    assert metric.compute([1], [9]) == pytest.approx(8.0)
+
+
+def test_manhattan_symmetry():
+    """Mesafe simetriktir: d(a,b) == d(b,a)."""
+    metric = DistanceMetricFactory.create("manhattan")
+    assert metric.compute([0, 1], [4, 6]) == pytest.approx(metric.compute([4, 6], [0, 1]))
+
+
+def test_manhattan_callable():
+    """DistanceMetric nesnesi fonksiyon gibi çağrılabilmeli (__call__)."""
+    metric = DistanceMetricFactory.create("manhattan")
+    assert metric([0, 0], [3, 4]) == pytest.approx(7.0)
+
+
+# ---------------------------------------------------------------------------
+# Euclidean vs Manhattan farkı
+# ---------------------------------------------------------------------------
+
+def test_euclidean_less_or_equal_manhattan():
+    """L2 ≤ L1 her zaman doğrudur (norm ilişkisi)."""
+    eu = DistanceMetricFactory.create("euclidean")
+    ma = DistanceMetricFactory.create("manhattan")
+    a, b = [1, 3, 5], [4, 7, 2]
+    assert eu.compute(a, b) <= ma.compute(a, b) + 1e-9
+
+
+# ---------------------------------------------------------------------------
+# DistanceMetricFactory — create()
+# ---------------------------------------------------------------------------
+
+def test_factory_create_euclidean_type():
+    """Factory 'euclidean' için doğru tip döndürmeli."""
+    from coreLearn.distances import EuclideanDistance
+    metric = DistanceMetricFactory.create("euclidean")
+    assert isinstance(metric, EuclideanDistance)
+
+
+def test_factory_create_manhattan_type():
+    """Factory 'manhattan' için doğru tip döndürmeli."""
+    from coreLearn.distances import ManhattanDistance
+    metric = DistanceMetricFactory.create("manhattan")
+    assert isinstance(metric, ManhattanDistance)
+
+
+def test_factory_create_unknown_raises():
+    """Bilinmeyen metrik adı ValueError fırlatmalı."""
+    with pytest.raises(ValueError, match="Unknown"):
+        DistanceMetricFactory.create("chebyshev")
+
+
+def test_factory_create_returns_new_instance():
+    """Her create() çağrısı bağımsız bir nesne döndürmeli."""
+    m1 = DistanceMetricFactory.create("euclidean")
+    m2 = DistanceMetricFactory.create("euclidean")
+    assert m1 is not m2
+
+
+# ---------------------------------------------------------------------------
+# DistanceMetricFactory — available()
+# ---------------------------------------------------------------------------
+
+def test_factory_available_contains_defaults():
+    """Varsayılan metrikler listelenebilmeli."""
+    names = DistanceMetricFactory.available()
+    assert "euclidean" in names
+    assert "manhattan" in names
+
+
+def test_factory_available_returns_list():
+    """available() bir liste döndürmeli."""
+    assert isinstance(DistanceMetricFactory.available(), list)
+
+
+# ---------------------------------------------------------------------------
+# DistanceMetricFactory — register()
+# ---------------------------------------------------------------------------
+
+def test_factory_register_and_use():
+    """Yeni metrik kaydedilip kullanılabilmeli."""
+
+    class ChebyshevDistance(DistanceMetric):
+        def compute(self, a, b):
+            return float(max(abs(x - y) for x, y in zip(a, b)))
+
+    DistanceMetricFactory.register("chebyshev_tmp", ChebyshevDistance)
+    metric = DistanceMetricFactory.create("chebyshev_tmp")
+    # [1,2,3] ile [4,6,5] → max(3,4,2) = 4
+    assert metric.compute([1, 2, 3], [4, 6, 5]) == pytest.approx(4.0)
+
+
+def test_factory_register_appears_in_available():
+    """Kaydedilen metrik available() listesinde görünmeli."""
+
+    class DummyDistance(DistanceMetric):
+        def compute(self, a, b):
+            return 0.0
+
+    DistanceMetricFactory.register("dummy_tmp", DummyDistance)
+    assert "dummy_tmp" in DistanceMetricFactory.available()
+
+
+def test_factory_register_invalid_class_raises():
+    """DistanceMetric'ten türemeyen sınıf kaydı TypeError fırlatmalı."""
+
+    class NotAMetric:
+        pass
+
+    with pytest.raises(TypeError):
+        DistanceMetricFactory.register("bad", NotAMetric)
+
+
+def test_factory_register_non_class_raises():
+    """Sınıf olmayan bir nesne kaydı TypeError fırlatmalı."""
+    with pytest.raises(TypeError):
+        DistanceMetricFactory.register("bad_fn", lambda a, b: 0.0)
+
+
+# ---------------------------------------------------------------------------
+# DistanceMetric — soyut sınıf doğrudan örneklenemez
+# ---------------------------------------------------------------------------
+
+def test_distance_metric_is_abstract():
+    """DistanceMetric doğrudan örneklenemez (abstract)."""
+    with pytest.raises(TypeError):
+        DistanceMetric()  # type: ignore[abstract]

coreLearn/tests/test_evaluator.py

@@ -0,0 +1,104 @@
+"""Unit tests for evaluator metric functions and Evaluator class."""
+
+import pytest
+from coreLearn import (
+    Evaluator,
+    accuracy, mae, mse, rmse,
+    precision, recall, f1_score,
+)
+
+
+# ---------------------------------------------------------------------------
+# Regression metrics
+# ---------------------------------------------------------------------------
+
+def test_mae():
+    assert mae([1.0, 2.0, 3.0], [1.5, 2.5, 3.5]) == pytest.approx(0.5)
+
+
+def test_mse():
+    assert mse([1.0, 2.0, 3.0], [2.0, 3.0, 4.0]) == pytest.approx(1.0)
+
+
+def test_rmse():
+    assert rmse([1.0, 2.0, 3.0], [2.0, 3.0, 4.0]) == pytest.approx(1.0)
+
+
+def test_mae_perfect():
+    assert mae([1.0, 2.0, 3.0], [1.0, 2.0, 3.0]) == pytest.approx(0.0)
+
+
+# ---------------------------------------------------------------------------
+# Classification metrics
+# ---------------------------------------------------------------------------
+
+def test_accuracy():
+    assert accuracy([0, 1, 1, 0, 1], [0, 1, 0, 0, 1]) == pytest.approx(0.8)
+
+
+def test_accuracy_perfect():
+    assert accuracy([1, 0, 1], [1, 0, 1]) == pytest.approx(1.0)
+
+
+def test_precision_perfect():
+    assert precision([0, 0, 1, 1], [0, 0, 1, 1]) == pytest.approx(1.0)
+
+
+def test_recall_binary():
+    assert recall([1, 1, 0], [1, 0, 0]) == pytest.approx(0.75)
+
+
+def test_f1_perfect():
+    assert f1_score([0, 1, 0, 1], [0, 1, 0, 1]) == pytest.approx(1.0)
+
+
+# ---------------------------------------------------------------------------
+# Input validation
+# ---------------------------------------------------------------------------
+
+def test_empty_raises():
+    with pytest.raises(ValueError):
+        accuracy([], [])
+
+
+def test_length_mismatch_raises():
+    with pytest.raises(ValueError):
+        mae([1.0, 2.0], [1.0])
+
+
+# ---------------------------------------------------------------------------
+# Evaluator class
+# ---------------------------------------------------------------------------
+
+def test_evaluate_regression_keys():
+    result = Evaluator.evaluate_regression([1.0, 2.0], [1.0, 2.0])
+    assert set(result.keys()) == {"mae", "mse", "rmse"}
+
+
+def test_evaluate_regression_perfect():
+    result = Evaluator.evaluate_regression([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
+    assert result["mae"] == pytest.approx(0.0)
+    assert result["mse"] == pytest.approx(0.0)
+    assert result["rmse"] == pytest.approx(0.0)
+
+
+def test_evaluate_classification_keys():
+    result = Evaluator.evaluate_classification([0, 1, 0, 1], [0, 1, 0, 1])
+    assert set(result.keys()) == {"accuracy", "precision", "recall", "f1"}
+
+
+def test_evaluate_classification_perfect():
+    result = Evaluator.evaluate_classification([0, 1, 0, 1], [0, 1, 0, 1])
+    assert result["accuracy"] == pytest.approx(1.0)
+    assert result["f1"] == pytest.approx(1.0)
+
+
+def test_register_regression():
+    Evaluator.register("max_err", lambda t, p: max(abs(a - b) for a, b in zip(t, p)), kind="regression")
+    result = Evaluator.evaluate_regression([1.0, 2.0, 3.0], [1.5, 2.0, 3.5])
+    assert result["max_err"] == pytest.approx(0.5)
+
+
+def test_register_unknown_kind_raises():
+    with pytest.raises(ValueError):
+        Evaluator.register("bad", lambda t, p: 0.0, kind="unknown")

coreLearn/tests/test_knn.py

@@ -0,0 +1,101 @@
+"""Unit tests for KNNClassifier."""
+
+import pytest
+from coreLearn import KNNClassifier
+
+
+def test_basic_classification():
+    X_train = [[1, 1], [2, 2], [3, 3], [7, 7], [8, 8], [9, 9]]
+    y_train = [0, 0, 0, 1, 1, 1]
+    model = KNNClassifier(k=3)
+    model.fit(X_train, y_train)
+    assert model.predict([[2, 2]]) == [0]
+    assert model.predict([[8, 8]]) == [1]
+
+
+def test_manhattan_distance():
+    X_train = [[0, 0], [1, 0], [0, 1], [5, 5], [6, 5], [5, 6]]
+    y_train = ["A", "A", "A", "B", "B", "B"]
+    model = KNNClassifier(k=3, distance="manhattan")
+    model.fit(X_train, y_train)
+    preds = model.predict([[0.5, 0.5], [5.5, 5.5]])
+    assert preds == ["A", "B"]
+
+
+def test_parallel_predict():
+    X_train = [[i] for i in range(20)]
+    y_train = [0 if i < 10 else 1 for i in range(20)]
+    model = KNNClassifier(k=3, n_jobs=2)
+    model.fit(X_train, y_train)
+    preds = model.predict([[4], [15]])
+    assert preds == [0, 1]
+
+
+def test_predict_before_fit_raises():
+    with pytest.raises(RuntimeError):
+        KNNClassifier().predict([[1, 2]])
+
+
+def test_unknown_distance_raises():
+    with pytest.raises(ValueError):
+        KNNClassifier(distance="cosine")
+
+
+def test_fit_predict_template_method():
+    model = KNNClassifier(k=1)
+    preds = model.fit_predict([[0], [10]], [0, 1], [[1], [9]])
+    assert preds == [0, 1]
+
+
+# ---------------------------------------------------------------------------
+# Parametre doğrulama — fit()
+# ---------------------------------------------------------------------------
+
+def test_k_greater_than_n_samples_raises():
+    """k, eğitim örnek sayısından büyük olamaz."""
+    model = KNNClassifier(k=10)
+    with pytest.raises(ValueError, match="k"):
+        model.fit([[1], [2], [3]], [0, 1, 0])
+
+
+def test_k_zero_raises():
+    """k sıfır veya negatif olamaz."""
+    with pytest.raises(ValueError):
+        KNNClassifier(k=0)
+
+
+def test_k_negative_raises():
+    """k negatif olamaz."""
+    with pytest.raises(ValueError):
+        KNNClassifier(k=-1)
+
+
+def test_n_jobs_zero_raises():
+    """n_jobs sıfır olamaz."""
+    with pytest.raises(ValueError):
+        KNNClassifier(n_jobs=0)
+
+
+def test_n_jobs_negative_raises():
+    """n_jobs negatif olamaz."""
+    with pytest.raises(ValueError):
+        KNNClassifier(n_jobs=-2)
+
+
+# ---------------------------------------------------------------------------
+# Parametre doğrulama — predict()
+# ---------------------------------------------------------------------------
+
+def test_feature_mismatch_raises():
+    """Tahmin sırasında özellik sayısı eğitimle uyuşmalı."""
+    model = KNNClassifier(k=1)
+    model.fit([[1, 2], [3, 4]], [0, 1])
+    with pytest.raises(ValueError, match="[Ff]eature"):
+        model.predict([[1]])          # 1 özellik; model 2 ile eğitildi
+
+
+def test_predict_empty_returns_empty():
+    """Boş X verildiğinde predict boş liste döndürür."""
+    model = KNNClassifier(k=1)
+    model.fit([[1], [2]], [0, 1])
+    assert model.predict([]) == []