natbook 0.1.0__tar.gz

natbook-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: natbook
+Version: 0.1.0
+Summary: ML exam prep — 12 algorithms ready to run
+Requires-Python: >=3.8
+Requires-Dist: numpy
+Requires-Dist: scikit-learn
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Provides-Extra: xgboost
+Requires-Dist: xgboost; extra == "xgboost"

natbook-0.1.0/README.md

@@ -0,0 +1,50 @@
+# lekhexamprep
+
+ML exam prep package — 12 algorithms, one `run()` call each.
+
+## Install
+
+```bash
+pip install lekhexamprep        # from PyPI (after publishing)
+# or locally:
+pip install .
+```
+
+## Usage
+
+```python
+import lekhexamprep as lep
+
+lep.linear_regression()
+lep.polynomial_regression(degree=3)
+lep.classification_regression()
+lep.decision_tree(max_depth=3)
+lep.linear_svm()
+lep.nonlinear_svm(kernel="rbf")
+lep.random_forest(n_estimators=100)
+lep.xgboost()
+lep.kmeans(k=3)
+lep.svd()
+lep.pca(n_components=2)
+lep.lda(n_components=2)
+
+# Pass plot=True to any function for a matplotlib visualisation
+lep.pca(plot=True)
+```
+
+## Algorithms
+
+| # | Module | Algorithm |
+|---|--------|-----------|
+| 1 | `linear_regression` | Simple Linear Regression |
+| 2 | `polynomial_regression` | Polynomial Regression (Pipeline) |
+| 3 | `classification_regression` | Logistic Regression (Classification) |
+| 4 | `decision_tree` | Decision Tree Classifier |
+| 5 | `linear_svm` | Linear SVM |
+| 6 | `nonlinear_svm` | Non-Linear SVM (RBF kernel) |
+| 7 | `random_forest` | Random Forest |
+| 8 | `xgboost` | XGBoost |
+| 9 | `kmeans` | K-Means Clustering |
+| 10 | `svd` | Singular Value Decomposition |
+| 11 | `pca` | Principal Component Analysis |
+| 12 | `lda` | Linear Discriminant Analysis |

natbook-0.1.0/lekhexamprep/__init__.py

@@ -0,0 +1,28 @@
+from .linear_regression       import run as linear_regression
+from .polynomial_regression   import run as polynomial_regression
+from .classification_regression import run as classification_regression
+from .decision_tree           import run as decision_tree
+from .linear_svm              import run as linear_svm
+from .nonlinear_svm           import run as nonlinear_svm
+from .random_forest           import run as random_forest
+from .xgboost_model           import run as xgboost
+from .kmeans                  import run as kmeans
+from .svd                     import run as svd
+from .pca                     import run as pca
+from .lda                     import run as lda
+
+__version__ = "0.1.0"
+__all__ = [
+    "linear_regression",
+    "polynomial_regression",
+    "classification_regression",
+    "decision_tree",
+    "linear_svm",
+    "nonlinear_svm",
+    "random_forest",
+    "xgboost",
+    "kmeans",
+    "svd",
+    "pca",
+    "lda",
+]

natbook-0.1.0/lekhexamprep/adaboost.py

@@ -0,0 +1,166 @@
+# =============================================================================
+# AdaBoost Classifier
+# Dataset: Breast Cancer Wisconsin — Kaggle
+# https://www.kaggle.com/datasets/uciml/breast-cancer-wisconsin-data
+#
+# SETUP:
+#   kaggle datasets download -d uciml/breast-cancer-wisconsin-data --unzip
+#   → this gives you data.csv
+#   OR manually download from Kaggle and place data.csv in the same folder
+# =============================================================================
+
+# Step 1 - Import Libraries
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.ensemble import AdaBoostClassifier
+from sklearn.tree import DecisionTreeClassifier
+from sklearn.model_selection import train_test_split, cross_val_score
+from sklearn.metrics import (accuracy_score, confusion_matrix,
+                             classification_report, ConfusionMatrixDisplay)
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+
+# =============================================================================
+# Step 2 - Load and Explore Dataset
+# =============================================================================
+
+df = pd.read_csv('data.csv')      # CSV must be in the same folder as this file
+
+print("Shape         :", df.shape)
+print("\nColumns       :", list(df.columns))
+print("\nFirst 5 rows:")
+print(df.head())
+print("\nMissing values:")
+print(df.isnull().sum())
+print("\nClass distribution:")
+print(df['diagnosis'].value_counts())   # M = Malignant, B = Benign
+
+# =============================================================================
+# Step 3 - Preprocess the Data
+# =============================================================================
+
+# Drop columns we don't need
+df = df.drop(columns=['id', 'Unnamed: 32'], errors='ignore')
+
+# Encode target: M → 1, B → 0
+le              = LabelEncoder()
+df['diagnosis'] = le.fit_transform(df['diagnosis'])
+
+# Separate features and target
+X             = df.drop(columns=['diagnosis']).values
+y             = df['diagnosis'].values
+feature_names = df.drop(columns=['diagnosis']).columns.tolist()
+
+# Train-test split (80-20)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+# Scale features
+scaler  = StandardScaler()
+X_train = scaler.fit_transform(X_train)
+X_test  = scaler.transform(X_test)     # only transform, never fit on test data
+
+print("\nTraining samples  :", X_train.shape[0])
+print("Testing  samples  :", X_test.shape[0])
+print("Number of features:", X_train.shape[1])
+
+# =============================================================================
+# Step 4 - Train AdaBoost Model
+# =============================================================================
+# AdaBoost = Adaptive Boosting
+# Idea: Train weak learners (stumps) one by one.
+#       Each new learner focuses more on the samples the previous one got WRONG.
+#       Final prediction = weighted vote of all weak learners.
+
+base_estimator = DecisionTreeClassifier(max_depth=1)   # weak learner = stump
+
+ada = AdaBoostClassifier(
+    estimator     = base_estimator,   # weak learner
+    n_estimators  = 100,              # number of weak learners to train
+    learning_rate = 1.0,              # shrinks contribution of each learner
+    algorithm     = 'SAMME',          # use SAMME (SAMME.R is deprecated)
+    random_state  = 42
+)
+
+ada.fit(X_train, y_train)
+print("\nModel trained successfully!")
+print("Number of estimators:", ada.n_estimators)
+
+# =============================================================================
+# Step 5 - Evaluate the Model
+# =============================================================================
+
+y_pred = ada.predict(X_test)
+
+print("\n========== Evaluation ==========")
+print("Accuracy         :", round(accuracy_score(y_test, y_pred), 4))
+
+print("\nClassification Report:")
+print(classification_report(y_test, y_pred, target_names=['Benign', 'Malignant']))
+
+# Cross-validation (5-fold)
+cv_scores = cross_val_score(ada, X, y, cv=5, scoring='accuracy')
+print("5-Fold CV Scores :", cv_scores.round(4))
+print("CV Mean Accuracy :", round(cv_scores.mean(), 4))
+print("CV Std Dev       :", round(cv_scores.std(), 4))
+
+# Confusion Matrix
+cm   = confusion_matrix(y_test, y_pred)
+print("\nConfusion Matrix:\n", cm)
+
+disp = ConfusionMatrixDisplay(confusion_matrix=cm,
+                               display_labels=['Benign', 'Malignant'])
+disp.plot(cmap='Oranges')
+plt.title('AdaBoost - Confusion Matrix')
+plt.tight_layout()
+plt.show()
+
+# =============================================================================
+# Step 6 - Feature Importance
+# =============================================================================
+
+importances = ada.feature_importances_
+indices     = np.argsort(importances)[::-1]
+top_n       = 10
+
+print("\nTop 10 Important Features:")
+for i in range(top_n):
+    print(f"  {i+1}. {feature_names[indices[i]]:35s} {importances[indices[i]]:.4f}")
+
+plt.figure(figsize=(10, 5))
+plt.bar(range(top_n),
+        importances[indices[:top_n]],
+        color='darkorange', edgecolor='black', linewidth=0.6)
+plt.xticks(range(top_n),
+           [feature_names[i] for i in indices[:top_n]],
+           rotation=45, ha='right', fontsize=8)
+plt.title('AdaBoost - Top 10 Feature Importances')
+plt.ylabel('Importance Score')
+plt.tight_layout()
+plt.show()
+
+# =============================================================================
+# Step 7 - Accuracy vs Number of Estimators
+# =============================================================================
+# Shows how AdaBoost improves as it adds more weak learners
+
+train_errors = []
+test_errors  = []
+
+for y_pred_train, y_pred_test in zip(
+    ada.staged_predict(X_train),
+    ada.staged_predict(X_test)
+):
+    train_errors.append(1 - accuracy_score(y_train, y_pred_train))
+    test_errors.append(1 - accuracy_score(y_test,   y_pred_test))
+
+plt.figure(figsize=(9, 5))
+plt.plot(train_errors, label='Train Error', color='blue',  linewidth=2)
+plt.plot(test_errors,  label='Test Error',  color='red',   linewidth=2)
+plt.xlabel('Number of Estimators (Weak Learners)')
+plt.ylabel('Error Rate')
+plt.title('AdaBoost - Error vs Number of Estimators')
+plt.legend()
+plt.tight_layout()
+plt.show()

natbook-0.1.0/lekhexamprep/classification_regression.py

@@ -0,0 +1,178 @@
+# =============================================================================
+# Logistic Regression Classifier
+# Dataset: Breast Cancer Wisconsin — Kaggle
+# https://www.kaggle.com/datasets/uciml/breast-cancer-wisconsin-data
+#
+# SETUP:
+#   kaggle datasets download -d uciml/breast-cancer-wisconsin-data --unzip
+#   → this gives you data.csv
+#   OR manually download from Kaggle and place data.csv in the same folder
+# =============================================================================
+
+# Step 1 - Import Libraries
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import train_test_split, cross_val_score
+from sklearn.metrics import (accuracy_score, confusion_matrix,
+                             classification_report, ConfusionMatrixDisplay,
+                             roc_curve, auc)
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+
+# =============================================================================
+# Step 2 - Load and Explore Dataset
+# =============================================================================
+
+df = pd.read_csv('data.csv')      # CSV must be in the same folder as this file
+
+print("Shape         :", df.shape)
+print("\nColumns       :", list(df.columns))
+print("\nFirst 5 rows:")
+print(df.head())
+print("\nMissing values:")
+print(df.isnull().sum())
+print("\nClass distribution:")
+print(df['diagnosis'].value_counts())   # M = Malignant, B = Benign
+
+# =============================================================================
+# Step 3 - Preprocess the Data
+# =============================================================================
+
+# Drop columns we don't need
+df = df.drop(columns=['id', 'Unnamed: 32'], errors='ignore')
+
+# Encode target: M → 1, B → 0
+le              = LabelEncoder()
+df['diagnosis'] = le.fit_transform(df['diagnosis'])
+
+# Separate features and target
+X             = df.drop(columns=['diagnosis']).values
+y             = df['diagnosis'].values
+feature_names = df.drop(columns=['diagnosis']).columns.tolist()
+
+# Train-test split (80-20)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+# Scale features — VERY important for Logistic Regression
+# LR uses gradient descent; unscaled features make it converge slowly/poorly
+scaler  = StandardScaler()
+X_train = scaler.fit_transform(X_train)
+X_test  = scaler.transform(X_test)     # only transform, never fit on test data
+
+print("\nTraining samples  :", X_train.shape[0])
+print("Testing  samples  :", X_test.shape[0])
+print("Number of features:", X_train.shape[1])
+
+# =============================================================================
+# Step 4 - Train Logistic Regression Model
+# =============================================================================
+# Logistic Regression estimates the probability that a sample belongs to a class
+# using the sigmoid function:
+#
+#   P(y=1 | x) = 1 / (1 + e^(-z))   where z = w.x + b
+#
+# If P > 0.5  → predict class 1 (Malignant)
+# If P <= 0.5 → predict class 0 (Benign)
+
+lr = LogisticRegression(
+    C           = 1.0,          # regularisation strength (smaller C = stronger regularisation)
+    penalty     = 'l2',         # L2 regularisation (Ridge) — prevents overfitting
+    solver      = 'lbfgs',      # optimisation algorithm (works well for small datasets)
+    max_iter    = 1000,         # max iterations for solver to converge
+    random_state= 42
+)
+
+lr.fit(X_train, y_train)
+print("\nModel trained successfully!")
+print("Solver used    :", lr.solver)
+print("Regularisation :", lr.penalty)
+
+# =============================================================================
+# Step 5 - Evaluate the Model
+# =============================================================================
+
+y_pred      = lr.predict(X_test)
+y_pred_prob = lr.predict_proba(X_test)[:, 1]   # probability of being Malignant
+
+print("\n========== Evaluation ==========")
+print("Accuracy         :", round(accuracy_score(y_test, y_pred), 4))
+
+print("\nClassification Report:")
+print(classification_report(y_test, y_pred, target_names=['Benign', 'Malignant']))
+
+# Cross-validation (5-fold)
+cv_scores = cross_val_score(lr, X, y, cv=5, scoring='accuracy')
+print("5-Fold CV Scores :", cv_scores.round(4))
+print("CV Mean Accuracy :", round(cv_scores.mean(), 4))
+print("CV Std Dev       :", round(cv_scores.std(), 4))
+
+# Confusion Matrix
+cm   = confusion_matrix(y_test, y_pred)
+print("\nConfusion Matrix:\n", cm)
+
+disp = ConfusionMatrixDisplay(confusion_matrix=cm,
+                               display_labels=['Benign', 'Malignant'])
+disp.plot(cmap='Blues')
+plt.title('Logistic Regression - Confusion Matrix')
+plt.tight_layout()
+plt.show()
+
+# =============================================================================
+# Step 6 - ROC Curve (unique to probabilistic classifiers like LR)
+# =============================================================================
+# ROC curve shows the tradeoff between True Positive Rate and False Positive Rate
+# AUC (Area Under Curve) closer to 1.0 = better model
+
+fpr, tpr, thresholds = roc_curve(y_test, y_pred_prob)
+roc_auc              = auc(fpr, tpr)
+
+plt.figure(figsize=(7, 5))
+plt.plot(fpr, tpr, color='blue', linewidth=2,
+         label=f'ROC Curve (AUC = {roc_auc:.4f})')
+plt.plot([0, 1], [0, 1], color='grey', linestyle='--', linewidth=1,
+         label='Random Classifier (AUC = 0.5)')
+plt.xlabel('False Positive Rate')
+plt.ylabel('True Positive Rate')
+plt.title('Logistic Regression - ROC Curve')
+plt.legend()
+plt.tight_layout()
+plt.show()
+
+print(f"\nAUC Score: {roc_auc:.4f}  (1.0 = perfect, 0.5 = random)")
+
+# =============================================================================
+# Step 7 - Feature Coefficients (what LR actually learned)
+# =============================================================================
+# In Logistic Regression, coefficients tell you:
+#   Positive coefficient → feature pushes toward class 1 (Malignant)
+#   Negative coefficient → feature pushes toward class 0 (Benign)
+
+coefficients = lr.coef_[0]
+coef_df      = pd.DataFrame({
+    'Feature'    : feature_names,
+    'Coefficient': coefficients
+}).sort_values('Coefficient', ascending=False)
+
+print("\nTop 5 features pushing toward Malignant (positive coeff):")
+print(coef_df.head(5).to_string(index=False))
+
+print("\nTop 5 features pushing toward Benign (negative coeff):")
+print(coef_df.tail(5).to_string(index=False))
+
+# Plot top 10 + bottom 10 coefficients
+top10    = coef_df.head(10)
+bottom10 = coef_df.tail(10)
+plot_df  = pd.concat([top10, bottom10])
+
+plt.figure(figsize=(10, 6))
+colors = ['red' if c > 0 else 'blue' for c in plot_df['Coefficient']]
+plt.barh(plot_df['Feature'], plot_df['Coefficient'],
+         color=colors, edgecolor='black', linewidth=0.5)
+plt.axvline(0, color='black', linewidth=0.8)
+plt.xlabel('Coefficient Value')
+plt.title('Logistic Regression - Feature Coefficients\n(Red = Malignant, Blue = Benign)')
+plt.tight_layout()
+plt.show()

natbook-0.1.0/lekhexamprep/decision_tree.py

@@ -0,0 +1,198 @@
+# =============================================================================
+# Decision Tree Classifier
+# Dataset: Breast Cancer Wisconsin — Kaggle
+# https://www.kaggle.com/datasets/uciml/breast-cancer-wisconsin-data
+#
+# SETUP:
+#   kaggle datasets download -d uciml/breast-cancer-wisconsin-data --unzip
+#   → this gives you data.csv
+#   OR manually download from Kaggle and place data.csv in the same folder
+# =============================================================================
+
+# Step 1 - Import Libraries
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.tree import DecisionTreeClassifier, plot_tree, export_text
+from sklearn.model_selection import train_test_split, cross_val_score
+from sklearn.metrics import (accuracy_score, confusion_matrix,
+                             classification_report, ConfusionMatrixDisplay)
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+
+# =============================================================================
+# Step 2 - Load and Explore Dataset
+# =============================================================================
+
+df = pd.read_csv('data.csv')      # CSV must be in the same folder as this file
+
+print("Shape         :", df.shape)
+print("\nColumns       :", list(df.columns))
+print("\nFirst 5 rows:")
+print(df.head())
+print("\nMissing values:")
+print(df.isnull().sum())
+print("\nClass distribution:")
+print(df['diagnosis'].value_counts())   # M = Malignant, B = Benign
+
+# =============================================================================
+# Step 3 - Preprocess the Data
+# =============================================================================
+
+# Drop columns we don't need
+df = df.drop(columns=['id', 'Unnamed: 32'], errors='ignore')
+
+# Encode target: M → 1, B → 0
+le              = LabelEncoder()
+df['diagnosis'] = le.fit_transform(df['diagnosis'])
+
+# Separate features and target
+X             = df.drop(columns=['diagnosis']).values
+y             = df['diagnosis'].values
+feature_names = df.drop(columns=['diagnosis']).columns.tolist()
+
+# Train-test split (80-20)
+X_train, X_test, y_train, y_test = train_test_split(
+    X, y, test_size=0.2, random_state=42, stratify=y
+)
+
+# Note: Decision Trees don't strictly need scaling (they split on thresholds)
+# but we scale anyway for consistency and fair comparison with other models
+scaler  = StandardScaler()
+X_train = scaler.fit_transform(X_train)
+X_test  = scaler.transform(X_test)
+
+print("\nTraining samples  :", X_train.shape[0])
+print("Testing  samples  :", X_test.shape[0])
+print("Number of features:", X_train.shape[1])
+
+# =============================================================================
+# Step 4 - Train Decision Tree Model
+# =============================================================================
+# Decision Tree splits data at each node by asking a question:
+#   "Is feature X > threshold T?"
+# It picks the split that best separates classes using a criterion (Gini / Entropy)
+#
+# Gini Impurity: measures how often a randomly chosen element is misclassified
+#   Gini = 1 - sum(p_i^2)    → 0 means perfectly pure node
+#
+# Entropy (Information Gain): measures disorder
+#   Entropy = -sum(p_i * log2(p_i))   → 0 means perfectly pure node
+
+dt = DecisionTreeClassifier(
+    criterion    = 'gini',    # split criterion: 'gini' or 'entropy'
+    max_depth    = 5,         # limit tree depth to prevent overfitting
+    min_samples_split = 2,    # min samples needed to split a node
+    min_samples_leaf  = 1,    # min samples required at a leaf node
+    random_state = 42
+)
+
+dt.fit(X_train, y_train)
+print("\nModel trained successfully!")
+print("Tree depth   :", dt.get_depth())
+print("Num of leaves:", dt.get_n_leaves())
+
+# =============================================================================
+# Step 5 - Evaluate the Model
+# =============================================================================
+
+y_pred = dt.predict(X_test)
+
+print("\n========== Evaluation ==========")
+print("Accuracy         :", round(accuracy_score(y_test, y_pred), 4))
+
+print("\nClassification Report:")
+print(classification_report(y_test, y_pred, target_names=['Benign', 'Malignant']))
+
+# Cross-validation (5-fold)
+cv_scores = cross_val_score(dt, X, y, cv=5, scoring='accuracy')
+print("5-Fold CV Scores :", cv_scores.round(4))
+print("CV Mean Accuracy :", round(cv_scores.mean(), 4))
+print("CV Std Dev       :", round(cv_scores.std(), 4))
+
+# Confusion Matrix
+cm   = confusion_matrix(y_test, y_pred)
+print("\nConfusion Matrix:\n", cm)
+
+disp = ConfusionMatrixDisplay(confusion_matrix=cm,
+                               display_labels=['Benign', 'Malignant'])
+disp.plot(cmap='Purples')
+plt.title('Decision Tree - Confusion Matrix')
+plt.tight_layout()
+plt.show()
+
+# =============================================================================
+# Step 6 - Visualise the Decision Tree
+# =============================================================================
+# This is the best part of Decision Trees — you can actually SEE the rules
+
+plt.figure(figsize=(20, 8))
+plot_tree(
+    dt,
+    feature_names = feature_names,
+    class_names   = ['Benign', 'Malignant'],
+    filled        = True,          # colour nodes by class
+    rounded       = True,          # rounded boxes
+    fontsize      = 8
+)
+plt.title('Decision Tree Visualisation (max_depth=5)', fontsize=14, fontweight='bold')
+plt.tight_layout()
+plt.show()
+
+# Print tree as text rules (useful for exam/report)
+print("\n=== Decision Tree Rules (Text) ===")
+tree_rules = export_text(dt, feature_names=feature_names, max_depth=3)
+print(tree_rules)
+
+# =============================================================================
+# Step 7 - Feature Importance
+# =============================================================================
+
+importances = dt.feature_importances_
+indices     = np.argsort(importances)[::-1]
+top_n       = 10
+
+print("\nTop 10 Important Features:")
+for i in range(top_n):
+    print(f"  {i+1}. {feature_names[indices[i]]:35s} {importances[indices[i]]:.4f}")
+
+plt.figure(figsize=(10, 5))
+plt.bar(range(top_n),
+        importances[indices[:top_n]],
+        color='mediumpurple', edgecolor='black', linewidth=0.6)
+plt.xticks(range(top_n),
+           [feature_names[i] for i in indices[:top_n]],
+           rotation=45, ha='right', fontsize=8)
+plt.title('Decision Tree - Top 10 Feature Importances')
+plt.ylabel('Importance Score (Gini)')
+plt.tight_layout()
+plt.show()
+
+# =============================================================================
+# Step 8 - Effect of max_depth on Accuracy (Overfitting Demo)
+# =============================================================================
+# A tree with no depth limit memorises training data = overfitting
+# This plot shows the sweet spot for max_depth
+
+train_accs = []
+test_accs  = []
+depths     = range(1, 21)
+
+for d in depths:
+    model = DecisionTreeClassifier(criterion='gini', max_depth=d, random_state=42)
+    model.fit(X_train, y_train)
+    train_accs.append(accuracy_score(y_train, model.predict(X_train)))
+    test_accs.append(accuracy_score(y_test,   model.predict(X_test)))
+
+plt.figure(figsize=(9, 5))
+plt.plot(depths, train_accs, marker='o', label='Train Accuracy',
+         color='blue', linewidth=2)
+plt.plot(depths, test_accs,  marker='s', label='Test Accuracy',
+         color='red',  linewidth=2)
+plt.axvline(5, color='grey', linestyle='--', linewidth=1.2, label='Our max_depth=5')
+plt.xlabel('max_depth')
+plt.ylabel('Accuracy')
+plt.title('Decision Tree - Accuracy vs max_depth\n(shows overfitting as depth increases)')
+plt.legend()
+plt.xticks(depths)
+plt.tight_layout()
+plt.show()