Your First Machine Learning Project – Complete Step-by-Step (2026)

# Step 1: Create a virtual environment (mandatory, not optional)
python3.12 -m venv ml_first_project
source ml_first_project/bin/activate  # macOS/Linux
# ml_first_project\Scripts\activate    # Windows PowerShell

# Step 2: Upgrade pip before installing anything
pip install --upgrade pip setuptools wheel

# Step 3: Install all required packages with pinned versions
pip install scikit-learn==1.5.0 pandas==2.2.2 numpy==1.26.4 matplotlib==3.9.0

# Step 4: Verify every import works
python -c "
import sklearn
import pandas
import numpy
import matplotlib
print(f'scikit-learn: {sklearn.__version__}')
print(f'pandas:       {pandas.__version__}')
print(f'numpy:        {numpy.__version__}')
print(f'matplotlib:   {matplotlib.__version__}')
print('All packages installed successfully')
"

# Step 5: Freeze versions for reproducibility
pip freeze > requirements.txt
echo "requirements.txt created with $(wc -l < requirements.txt) packages"

# TheCodeForge — Step 2: Load and Explore the Iris Dataset
import pandas as pd
import numpy as np
from sklearn.datasets import load_iris

# Load the dataset — built into scikit-learn, no download needed
iris = load_iris()

# Convert to DataFrame for easier exploration and display
df = pd.DataFrame(
    data=iris.data,
    columns=iris.feature_names
)
df['species'] = pd.Categorical.from_codes(iris.target, iris.target_names)

# 1. Dataset shape — how much data do we have?
print('=== Dataset Shape ===')
print(f'Samples: {df.shape[0]}, Features: {df.shape[1] - 1}')
print(f'Feature names: {iris.feature_names}')
print(f'Class names: {list(iris.target_names)}')

# 2. First 5 rows — what does the data look like?
print('\n=== First 5 Rows ===')
print(df.head().to_string())

# 3. Statistical summary — what are the value ranges?
print('\n=== Feature Statistics ===')
print(df.describe().round(2).to_string())

# 4. Class distribution — is the dataset balanced?
print('\n=== Class Distribution ===')
print(df['species'].value_counts().to_string())
balance_ratio = df['species'].value_counts().min() / df['species'].value_counts().max()
print(f'Balance ratio: {balance_ratio:.2f} (1.00 = perfectly balanced)')

# 5. Missing values — will any algorithms crash?
print('\n=== Missing Values ===')
missing = df.isnull().sum()
print(missing.to_string())
print(f'Total missing: {missing.sum()}')

# 6. Feature correlations — which features carry similar information?
print('\n=== Feature Correlations with Target ===')
df_numeric = df.copy()
df_numeric['target'] = iris.target
for col in iris.feature_names:
    corr = df_numeric[col].corr(df_numeric['target'])
    print(f'  {col}: {corr:.3f}')

print('\nPetal features have higher correlation with species — they will be more useful for classification.')

# TheCodeForge — Step 3: Visualize the Iris Dataset
import matplotlib.pyplot as plt
import pandas as pd
import numpy as np
from sklearn.datasets import load_iris

iris = load_iris()
df = pd.DataFrame(iris.data, columns=iris.feature_names)
df['species'] = pd.Categorical.from_codes(iris.target, iris.target_names)

colors = {'setosa': '#e74c3c', 'versicolor': '#3498db', 'virginica': '#2ecc71'}

# Plot 1: Feature distributions by species (2x2 histograms)
fig, axes = plt.subplots(2, 2, figsize=(10, 8))
fig.suptitle('Iris Dataset — Feature Distributions by Species', fontsize=14)

for idx, feature in enumerate(iris.feature_names):
    ax = axes[idx // 2, idx % 2]
    for species in iris.target_names:
        subset = df[df['species'] == species]
        ax.hist(subset[feature], alpha=0.6, label=species,
                color=colors[species], bins=15, edgecolor='white')
    ax.set_xlabel(feature)
    ax.set_ylabel('Count')
    ax.legend(fontsize=8)

plt.tight_layout()
plt.savefig('iris_distributions.png', dpi=150)
print('Saved: iris_distributions.png')

# Plot 2: Scatter plot — the most revealing single visualization
fig, ax = plt.subplots(figsize=(8, 6))
for species in iris.target_names:
    subset = df[df['species'] == species]
    ax.scatter(
        subset['petal length (cm)'],
        subset['petal width (cm)'],
        label=species,
        color=colors[species],
        alpha=0.7,
        s=60,
        edgecolors='white',
        linewidth=0.5
    )
ax.set_xlabel('Petal Length (cm)', fontsize=12)
ax.set_ylabel('Petal Width (cm)', fontsize=12)
ax.set_title('Petal Length vs Width — Clear Species Separation', fontsize=13)
ax.legend(fontsize=10)
plt.tight_layout()
plt.savefig('iris_scatter.png', dpi=150)
print('Saved: iris_scatter.png')

# Plot 3: Correlation heatmap — which features are related?
fig, ax = plt.subplots(figsize=(7, 5))
corr_matrix = df[iris.feature_names].corr()
im = ax.imshow(corr_matrix, cmap='coolwarm', vmin=-1, vmax=1)
ax.set_xticks(range(4))
ax.set_yticks(range(4))
ax.set_xticklabels([f.replace(' (cm)', '') for f in iris.feature_names], rotation=45, ha='right')
ax.set_yticklabels([f.replace(' (cm)', '') for f in iris.feature_names])
for i in range(4):
    for j in range(4):
        ax.text(j, i, f'{corr_matrix.iloc[i, j]:.2f}', ha='center', va='center', fontsize=10)
plt.colorbar(im, label='Correlation')
ax.set_title('Feature Correlation Matrix')
plt.tight_layout()
plt.savefig('iris_correlation.png', dpi=150)
print('Saved: iris_correlation.png')

print('\nKey insight: setosa is clearly separated. Versicolor and virginica overlap slightly.')
print('This tells us classification is feasible but perfect accuracy may not be possible.')

# TheCodeForge — Step 4: Split Data into Training and Test Sets
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
import numpy as np

# Load data
X, y = load_iris(return_X_y=True)
iris = load_iris()

# Split: 80% train, 20% test
# stratify=y: maintain class proportions in both sets
# random_state=42: same split every time for reproducibility
X_train, X_test, y_train, y_test = train_test_split(
    X, y,
    test_size=0.2,
    random_state=42,
    stratify=y
)

print('=== Train-Test Split ===')
print(f'Full dataset:  {X.shape[0]} samples')
print(f'Training set:  {X_train.shape[0]} samples ({X_train.shape[0]/X.shape[0]*100:.0f}%)')
print(f'Test set:      {X_test.shape[0]} samples ({X_test.shape[0]/X.shape[0]*100:.0f}%)')

print('\n=== Class Distribution in Training Set ===')
for cls_idx, cls_name in enumerate(iris.target_names):
    count = np.sum(y_train == cls_idx)
    print(f'  {cls_name}: {count} samples')

print('\n=== Class Distribution in Test Set ===')
for cls_idx, cls_name in enumerate(iris.target_names):
    count = np.sum(y_test == cls_idx)
    print(f'  {cls_name}: {count} samples')

print('\n=== Verification ===')
print(f'Classes in train: {sorted(set(y_train))}')
print(f'Classes in test:  {sorted(set(y_test))}')
print(f'Train and test overlap: {len(set(range(len(y_train))) & set(range(len(y_test))))} (should be 0)')
print('\nstratify=y ensures balanced classes. random_state=42 ensures reproducibility.')

# TheCodeForge — Step 5: Train Your First ML Model
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.tree import DecisionTreeClassifier
import numpy as np

# Load and split data (same as Step 4)
iris = load_iris()
X, y = iris.data, iris.target
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

# Train a Decision Tree Classifier — three lines
model = DecisionTreeClassifier(random_state=42)
model.fit(X_train, y_train)

print('=== Model Trained ===')
print(f'Algorithm: {model.__class__.__name__}')
print(f'Training samples used: {X_train.shape[0]}')
print(f'Features per sample: {X_train.shape[1]}')
print(f'Classes learned: {list(iris.target_names[model.classes_])}')
print(f'Tree depth: {model.get_depth()}')
print(f'Number of leaves (decision endpoints): {model.get_n_leaves()}')

# Feature importance — which features did the tree use most?
print('\n=== Feature Importance ===')
for name, importance in sorted(
    zip(iris.feature_names, model.feature_importances_),
    key=lambda x: -x[1]
):
    bar = '█' * int(importance * 40)
    print(f'  {name:>20}: {importance:.3f} {bar}')

# Quick accuracy check on test data (detailed evaluation in Step 6)
train_acc = model.score(X_train, y_train)
test_acc = model.score(X_test, y_test)
print(f'\n=== Quick Accuracy Check ===')
print(f'Training accuracy: {train_acc:.2%}')
print(f'Test accuracy:     {test_acc:.2%}')
print(f'Gap:               {train_acc - test_acc:.2%}')
if train_acc - test_acc > 0.10:
    print('WARNING: Large train-test gap may indicate overfitting')
else:
    print('Gap is small — model generalizes well')

# Predict a single new sample
new_flower = np.array([[5.1, 3.5, 1.4, 0.2]])  # measurements in cm
prediction = model.predict(new_flower)
print(f'\nNew flower {new_flower[0]} -> {iris.target_names[prediction[0]]}')

# TheCodeForge — Step 6: Evaluate Model Performance
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split, cross_val_score, StratifiedKFold
from sklearn.tree import DecisionTreeClassifier
from sklearn.metrics import (
    accuracy_score,
    confusion_matrix,
    classification_report,
    ConfusionMatrixDisplay
)
import numpy as np
import matplotlib.pyplot as plt

# Load, split, train
iris = load_iris()
X, y = iris.data, iris.target
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)
model = DecisionTreeClassifier(random_state=42)
model.fit(X_train, y_train)
predictions = model.predict(X_test)

# 1. Accuracy — the simplest metric
accuracy = accuracy_score(y_test, predictions)
print(f'=== Accuracy ===')
print(f'Test accuracy: {accuracy:.2%} ({int(accuracy * len(y_test))}/{len(y_test)} correct)')

# 2. Confusion Matrix — which classes get confused?
print(f'\n=== Confusion Matrix ===')
cm = confusion_matrix(y_test, predictions)
print(f'{"":>12} {"  ".join(iris.target_names)}  <- Predicted')
for i, row in enumerate(cm):
    print(f'{iris.target_names[i]:>12}: {row}  <- Actual')
print('Diagonal = correct predictions. Off-diagonal = mistakes.')

# Save confusion matrix as image
fig, ax = plt.subplots(figsize=(7, 5))
ConfusionMatrixDisplay.from_predictions(
    y_test, predictions,
    display_labels=iris.target_names,
    cmap='Blues',
    ax=ax
)
ax.set_title('Confusion Matrix — Iris Classification')
plt.tight_layout()
plt.savefig('confusion_matrix.png', dpi=150)
print('Saved: confusion_matrix.png')

# 3. Classification Report — precision, recall, F1 per class
print(f'\n=== Classification Report ===')
print(classification_report(y_test, predictions, target_names=iris.target_names))

# 4. Cross-Validation — more robust than a single split
print(f'=== Cross-Validation (5-fold stratified) ===')
cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
cv_scores = cross_val_score(
    DecisionTreeClassifier(random_state=42),
    X, y, cv=cv, scoring='accuracy'
)
print(f'Fold scores: {cv_scores.round(3)}')
print(f'Mean accuracy: {cv_scores.mean():.2%} (+/- {cv_scores.std():.2%})')
print(f'Worst fold:    {cv_scores.min():.2%}')
print(f'Best fold:     {cv_scores.max():.2%}')

if cv_scores.mean() < accuracy - 0.05:
    print('\nWARNING: Test accuracy is notably higher than CV mean — the test set may be unusually easy.')
else:
    print('\nTest accuracy aligns with CV mean — results are reliable.')

# TheCodeForge — Step 7: Compare Multiple Algorithms
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split, cross_val_score, StratifiedKFold
from sklearn.tree import DecisionTreeClassifier
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.neighbors import KNeighborsClassifier
from sklearn.preprocessing import StandardScaler
from sklearn.pipeline import Pipeline
from sklearn.metrics import accuracy_score
import numpy as np

# Load and split data (same split for fair comparison)
iris = load_iris()
X, y = iris.data, iris.target
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)

# Define algorithms to compare
# Note: Logistic Regression and KNN need feature scaling — use a Pipeline
algorithms = {
    'Decision Tree':      DecisionTreeClassifier(random_state=42),
    'Random Forest':      RandomForestClassifier(n_estimators=100, random_state=42),
    'Logistic Regression': Pipeline([
        ('scaler', StandardScaler()),
        ('clf', LogisticRegression(max_iter=200, random_state=42))
    ]),
    'K-Nearest Neighbors': Pipeline([
        ('scaler', StandardScaler()),
        ('clf', KNeighborsClassifier(n_neighbors=5))
    ]),
}

print('=== Algorithm Comparison ===')
print(f'{"Algorithm":<24} {"Test Acc":>10} {"CV Mean":>10} {"CV Std":>10}')
print('-' * 58)

results = {}
for name, algo in algorithms.items():
    algo.fit(X_train, y_train)
    test_acc = accuracy_score(y_test, algo.predict(X_test))
    cv_scores = cross_val_score(algo, X, y, cv=cv, scoring='accuracy')
    results[name] = {
        'test_acc': test_acc,
        'cv_mean': cv_scores.mean(),
        'cv_std': cv_scores.std()
    }
    print(f'{name:<24} {test_acc:>9.2%} {cv_scores.mean():>9.2%} {cv_scores.std():>9.2%}')

best = max(results, key=lambda k: results[k]['cv_mean'])
print(f'\nBest algorithm by CV mean: {best} ({results[best]["cv_mean"]:.2%})')
print('\nKey insight: on clean, balanced data like Iris, most algorithms perform similarly.')
print('On real-world messy data, gradient boosting typically wins for tabular problems.')

# TheCodeForge — Step 8: Make Predictions and Save the Model
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.tree import DecisionTreeClassifier
import numpy as np
import joblib
import os

# Load, split, train (same as previous steps)
iris = load_iris()
X, y = iris.data, iris.target
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)
model = DecisionTreeClassifier(random_state=42)
model.fit(X_train, y_train)

# Predict new flowers — data the model has never seen
new_flowers = np.array([
    [5.1, 3.5, 1.4, 0.2],  # typical setosa measurements
    [6.2, 2.9, 4.3, 1.3],  # typical versicolor measurements
    [7.7, 3.0, 6.1, 2.3],  # typical virginica measurements
    [5.0, 3.4, 1.5, 0.2],  # another setosa candidate
    [5.9, 3.0, 4.2, 1.5],  # versicolor or virginica?
])

predictions = model.predict(new_flowers)
probabilities = model.predict_proba(new_flowers)

print('=== Predictions on New Data ===')
for i, (flower, pred, prob) in enumerate(zip(new_flowers, predictions, probabilities)):
    species = iris.target_names[pred]
    confidence = prob[pred]
    all_probs = ', '.join([f'{iris.target_names[j]}={p:.1%}' for j, p in enumerate(prob) if p > 0.01])
    print(f'Flower {i+1}: {flower} -> {species} (confidence: {confidence:.1%})')
    print(f'          Probabilities: {all_probs}')

# Save the model for deployment or later use
model_path = 'iris_model_v1.pkl'
joblib.dump(model, model_path)
model_size = os.path.getsize(model_path)
print(f'\nModel saved to {model_path} ({model_size:,} bytes)')

# Load and verify the saved model produces identical predictions
loaded_model = joblib.load(model_path)
loaded_predictions = loaded_model.predict(new_flowers)
assert np.array_equal(predictions, loaded_predictions), 'Loaded model produces different predictions!'
print(f'Loaded model verification: predictions match original ✓')

# Save the feature names for documentation
print(f'\nExpected input format: {iris.feature_names}')
print('Each prediction requires exactly 4 numeric values in this order.')

# TheCodeForge — Complete First ML Project Pipeline
import pandas as pd
import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split, cross_val_score, StratifiedKFold
from sklearn.tree import DecisionTreeClassifier
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score, classification_report
import joblib
import os


def run_iris_pipeline():
    """Complete ML pipeline for the Iris dataset — from data to saved model."""

    # Step 1: Load data
    iris = load_iris()
    X, y = iris.data, iris.target
    print(f'[1/8] Data loaded: {X.shape[0]} samples, {X.shape[1]} features, '
          f'{len(iris.target_names)} classes')

    # Step 2: Explore
    df = pd.DataFrame(X, columns=iris.feature_names)
    df['target'] = y
    class_dist = dict(zip(*np.unique(y, return_counts=True)))
    missing = df.isnull().sum().sum()
    print(f'[2/8] Class distribution: {class_dist} | Missing values: {missing}')

    # Step 3: Split
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42, stratify=y
    )
    print(f'[3/8] Split: {X_train.shape[0]} train, {X_test.shape[0]} test')

    # Step 4: Train primary model
    model = DecisionTreeClassifier(random_state=42)
    model.fit(X_train, y_train)
    print(f'[4/8] Trained: {model.__class__.__name__} '
          f'(depth={model.get_depth()}, leaves={model.get_n_leaves()})')

    # Step 5: Evaluate
    predictions = model.predict(X_test)
    test_acc = accuracy_score(y_test, predictions)
    print(f'[5/8] Test accuracy: {test_acc:.2%}')
    print(classification_report(y_test, predictions,
                                target_names=iris.target_names, zero_division=0))

    # Step 6: Cross-validate
    cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
    cv_scores = cross_val_score(model, X, y, cv=cv)
    print(f'[6/8] Cross-validation: {cv_scores.mean():.2%} (+/- {cv_scores.std():.2%})')

    # Step 7: Compare with Random Forest
    rf = RandomForestClassifier(n_estimators=100, random_state=42)
    rf.fit(X_train, y_train)
    rf_acc = accuracy_score(y_test, rf.predict(X_test))
    rf_cv = cross_val_score(rf, X, y, cv=cv).mean()
    print(f'[7/8] Comparison — Decision Tree: {test_acc:.2%} | '
          f'Random Forest: {rf_acc:.2%} (CV: {rf_cv:.2%})')

    # Step 8: Save model
    model_path = 'iris_model_v1.pkl'
    joblib.dump(model, model_path)
    size = os.path.getsize(model_path)
    print(f'[8/8] Model saved: {model_path} ({size:,} bytes)')

    return model, test_acc


if __name__ == '__main__':
    model, accuracy = run_iris_pipeline()
    print(f'\n{"=" * 50}')
    print(f'Pipeline complete. Final test accuracy: {accuracy:.2%}')
    print(f'Model ready for deployment: iris_model_v1.pkl')
    print(f'{"=" * 50}')