params.yaml: A Guide to Configuring Machine Learning Projects

📊 params.yaml in Machine Learning: Complete Educational Guide

📚 Table of Contents

• Introduction
• YAML Example
• Base Configuration
• Data Handling
• Data Splitting
• Model Parameters
• Mathematical Concepts
• Best Practices
• Related Articles

📘 Introduction

In machine learning and data science, managing configurations manually inside code quickly becomes messy and error-prone. This is where YAML (Yet Another Markup Language) becomes powerful.

💡 Key Idea: YAML centralizes all configurations → improves reproducibility, clarity, and scalability.

📄 params.yaml Example

base:
  project: insurance-price-prediction
  random_state: 180
  target_data: expenses

data_source: 
  local_data: data_given/insurance_updated.csv

load_data:
  raw_data_csv: data/raw/insurance_updated.csv

raw_data:
  raw: insurance_data/insurance.csv

split_data:
  train_path: data/processed/train_insurance.csv
  test_path: data/processed/test_insurance.csv
  split_ratio: 0.250

estimators: 
  GradientBoostingRegressor:
    params:
      learning_rate: 0.1001
      n_estimators: 100
      alpha: 0.8
      verbose: 0
      validation_fraction: 0.000001
      tol: 0.0001
      ccp_alpha: 0.1

model_dirs: saved_models

reports:
  scores: reports/scores.json
  params: reports/params.json

webapp_model_dir: prediction_service/model/model.pkl

⚙️ Base Configuration

This section defines the identity and reproducibility of your project.

🎯 Random State Mathematics

Randomness in ML is controlled using seeds:

$$ X_{random} = f(seed) $$

If seed is constant → output remains constant.

$$ TrainSplit = f(Data, seed=180) $$

✔ Same seed = Same dataset split = Reproducible experiment

📂 Data Handling

The YAML file separates data stages clearly:

• Raw source
• Loaded data
• Processed data

📊 Data Pipeline Flow

$$ Raw \rightarrow Processed \rightarrow Model $$

✂️ Data Splitting

The split ratio determines how much data is used for training vs testing.

📉 Mathematical Representation

$$ TestSize = TotalData \times SplitRatio $$

$$ TrainSize = TotalData - TestSize $$

For 1000 samples:

$$ Test = 1000 \times 0.25 = 250 $$

$$ Train = 750 $$

🤖 Model Parameters (Gradient Boosting)

Gradient Boosting builds models sequentially to reduce error.

📈 Boosting Formula

$$ F_m(x) = F_{m-1}(x) + \eta \cdot h_m(x) $$

• \(F_m(x)\): final model
• \(\eta\): learning rate
• \(h_m(x)\): weak learner

🔍 Loss Minimization

$$ Loss = \sum (y - \hat{y})^2 $$

Model minimizes this error step-by-step.

📊 Advanced Mathematical Concepts

📉 Regularization

$$ Loss = Error + \lambda Complexity $$

Where:

• \(\lambda\) → controls overfitting

🌳 Tree Pruning

$$ Cost = Error + \alpha \times Leaves $$

CCP Alpha reduces unnecessary branches.

🚀 Best Practices

• Keep YAML modular
• Use meaningful naming
• Version control configs
• Avoid hardcoding values in scripts

💻 CLI Usage Example

python train.py --config=params.yaml

Loading configuration...
Training model...
Saving results...

🎯 Key Takeaways

✔ YAML improves project organization ✔ Ensures reproducibility ✔ Simplifies scaling ML pipelines ✔ Separates logic from configuration