ml-linear-lite 0.1.1

Machine learning libary built with NumPy

ml-lite

ml-lite ist eine bewusst schlank gehaltene Python-Bibliothek für lineare Regressionsmodelle. Die Algorithmen sind mit NumPy implementiert und eignen sich vor allem dazu, Gradientenabstieg, Regularisierung und Regressionsmetriken nachvollziehbar zu lernen.

Hinweis: Das Projekt ist ein Lernprojekt und kein Ersatz für produktive Bibliotheken wie scikit-learn.

Inhalt

• Funktionen
• Voraussetzungen und Installation
• Schnellstart
• API-Übersicht
• Metriken
• Tests und Demo
• Projektstruktur
• Einschränkungen

Funktionen

Komponente	Beschreibung
LinearRegression	Lineare Regression ohne Regularisierung
RidgeRegression	Lineare Regression mit L2-Regularisierung
LassoRegression	Lineare Regression mit L1-Regularisierung
GradientDescent	Optimierer für die iterative Aktualisierung von Gewichten und Bias
mse	Mean Squared Error (mittlerer quadratischer Fehler)
r2	Bestimmtheitsmaß R²

Alle Modelle werden per Gradientenabstieg trainiert. Während des Trainings speichert model.loss den mittleren quadratischen Fehler jeweils alle 100 Iterationen.

Voraussetzungen und Installation

Benötigt werden Python 3.10 oder neuer sowie NumPy. Für die Tests wird zusätzlich pytest verwendet.

git clone <repository-url>
cd ml-lite
python -m venv .venv
source .venv/bin/activate       # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

Ohne Test-Abhängigkeiten genügt:

python -m pip install -e .

Schnellstart

import numpy as np

from ml_lite import GradientDescent, RidgeRegression, mse, r2

# Jede Zeile ist eine Beobachtung, jede Spalte ein Merkmal.
X = np.array([[1, 2], [3, 4], [5, 6]])
y = np.array([7, 8, 9])

optimizer = GradientDescent(lr=0.01, n_iter=5_000)
model = RidgeRegression(lambda_=0.5, optimizer=optimizer)

model.fit(X, y)
predictions = model.predict(X)

print("Vorhersagen:", predictions)
print("Gewichte:", model.w)
print("Bias:", model.b)
print("MSE:", mse(y, predictions))
print("R²:", r2(y, predictions))

fit(X, y) initialisiert die Modellparameter zufällig und optimiert sie für die konfigurierte Anzahl an Iterationen. Daher können die Ergebnisse zwischen Ausführungen leicht variieren. X muss zweidimensional sein (n_beobachtungen × n_merkmale); y enthält einen Zielwert pro Beobachtung.

API-Übersicht

Modelle

from ml_lite import LinearRegression, RidgeRegression, LassoRegression

Klasse	Konstruktor	Zweck
LinearRegression	LinearRegression(optimizer=None)	Minimiert den quadratischen Vorhersagefehler.
RidgeRegression	RidgeRegression(lambda_=0.1, optimizer=None)	Ergänzt die Optimierung um eine L2-Strafe für große Gewichte.
LassoRegression	LassoRegression(lambda_=0.1, optimizer=None)	Ergänzt die Optimierung um eine L1-Strafe und kann Gewichte in Richtung null drücken.

Gemeinsame Methoden und Attribute:

Element	Beschreibung
fit(X, y)	Trainiert das Modell.
predict(X)	Gibt Vorhersagen zurück; vor dem Training wird ein ValueError ausgelöst.
w	Gewichtsvektor nach dem Training.
b	Bias (Achsenabschnitt) nach dem Training.
loss	Liste der während des Trainings aufgezeichneten MSE-Werte.

Optimierer

from ml_lite import GradientDescent

optimizer = GradientDescent(lr=0.01, n_iter=1_000)

• lr: Lernrate. Zu große Werte können dazu führen, dass das Training nicht konvergiert.
• n_iter: Anzahl der Aktualisierungsschritte.

Wird kein Optimierer übergeben, verwenden die Modelle GradientDescent() mit lr=0.01 und n_iter=1000.

Metriken

from ml_lite import mse, r2

error = mse(y_true, y_pred)
score = r2(y_true, y_pred)

• mse(y, y_pred) berechnet den mittleren quadratischen Fehler. Kleinere Werte sind besser; bei perfekten Vorhersagen ist der Wert 0.
• r2(y, y_pred) berechnet R². Bei perfekten Vorhersagen ist der Wert 1; negative Werte sind bei sehr schlechten Modellen möglich.

Tests und Demo

Die Beispielanwendung trainiert alle drei Modelle und gibt Vorhersagen, Koeffizienten sowie Metriken aus:

python test.py

Die automatisierten Tests lassen sich nach Installation der Entwicklungsabhängigkeiten ausführen:

python -m pytest -q

Projektstruktur

ml-lite/
├── ml_lite/
│   ├── __init__.py       # Öffentliche Paket-Schnittstelle
│   ├── linear.py         # Regressionsmodelle
│   ├── metrics.py        # MSE und R²
│   └── optimizer.py      # Gradientenabstieg
├── test/
│   └── test_linear.py    # Unit-Tests
├── pyproject.toml        # Paket- und Abhängigkeitsdefinition
├── test.py               # Ausführbare Demo
└── README.md

Einschränkungen

• Es gibt keine Datenvalidierung, Skalierung oder automatischen Train/Test-Split.
• Die Loss-Historie enthält nur den Fehler ohne Regularisierungsterm.
• Die Modelle sind auf Verständlichkeit und kleine Beispiele ausgelegt; für reale Projekte empfiehlt sich beispielsweise scikit-learn.
• Durch die zufällige Parameterinitialisierung und die fehlende Seed-Steuerung sind Ergebnisse nicht vollständig reproduzierbar.