Functions, classes, and modules

Functions: Reusable Logic Blocks

Definition Function

A function is a named block of code that takes inputs (parameters), performs operations, and optionally returns output. It encapsulates logic for reuse and clarity.

Syntax:

def function_name(param1, param2, param3=default_value):
   """Docstring explaining what this does"""
   # function body
   return result

Why Functions Matter in ML/AI

In AI/ML workflows, you'll repeatedly:

Preprocess data (normalize, tokenize, augment)
Compute metrics (accuracy, F1, loss)
Train models with different hyperparameters

Without functions: Copy-paste code everywhere, bugs multiply, changes require editing50 places.

With functions: Write once, call many times, fix bugs in one place.

Formula Function Anatomy Derivation

Let's derive why functions need their components from first principles:

Problem: You need to compute mean squared error (MSE) multiple times in your training loop.

Naive approach (no function):

mse_epoch1 = sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)
mse_epoch2 = sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)
# ... repeat100 times

Problems: Repetition, typo-prone, hard to modify formula.

Step 1 - Extract to named block:

def compute_mse():
   return sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)

Why this step? Give the logic a name so you can call it by name instead of repeating.

Step 2 - Parameterize inputs:

def compute_mse(y_true, y_pred):
   return sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)

Why this step? The function needs to work on different datasets, not just global variables.

Step 3 - Add documentation:

def compute_mse(y_true, y_pred):
   """Calculate mean squared error between true and predicted values.
   
   Args:
       y_true: List/array of ground truth values
       y_pred: List/array of predicted values
   Returns:
       Float MSE value
   """
   return sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)

Why this step? Future you (or teammates) need to understand what inputs are expected.

Step 4 - Add default parameters (optional):

def compute_mse(y_true, y_pred, squared=True):
   """MSE or RMSE based on squared parameter."""
   mse = sum((y_true[i] - y_pred[i])**2 for i in range(len(y_true))) / len(y_true)
   return mse if squared else mse ** 0.5

Why this step? Common variations (MSE vs RMSE) can share code with sensible defaults.

Worked example Example 1: Data Preprocessing Function

Task: Normalize features to [0, 1] range for a neural network.

def normalize_features(X, feature_min=None, feature_max=None):
   """Min-max normalize features to [0, 1].
   
   Args:
       X: 2D array (samples × features)
       feature_min: Optional precomputed minimums (for test set)
       feature_max: Optional precomputed maximums (for test set)
   Returns:
       Normalized array, feature_min, feature_max (to reuse for test)
   """
   if feature_min is None:
       feature_min = X.min(axis=0)  # Min per column
   if feature_max is None:
       feature_max = X.max(axis=0)
   
   # Avoid division by zero for constant features
   range_vals = feature_max - feature_min
   range_vals[range_vals == 0] = 1
   
   X_norm = (X - feature_min) / range_vals
   return X_norm, feature_min, feature_max
# Usage
X_train_norm, mins, maxs = normalize_features(X_train)
X_test_norm, _, _ = normalize_features(X_test, mins, maxs)  # Use train stats

Why each step?

Why compute min/max per column? Each feature has different scales (age: 0-100, income: 0-1M).
Why return min/max? Test set must use training set statistics to avoid data leakage.
Why handle zero range? Constant features (all same value) would cause division by zero.

Figure — Functions, classes, and modules

Classes: Data + Behavior Bundles

Definition Class

A class is a blueprint for creating objects that bundle data (attributes) and functions (methods) that operate on that data. An object (or instance) is a specific realization of the class.

Syntax:

class ClassName:
   def __init__(self, param1, param2):  # Constructor
       self.attribute1 = param1         # Instance attributes
       self.attribute2 = param2
   
   def method_name(self):               # Instance method
       return self.attribute1 + self.attribute2

Deriving Classes from First Principles

Formula Why Classes? Derivation from State Management

Problem: You're building a simple neural network layer. It needs:

Data: weights $W$ , biases $b$ , input size, output size
Behavior: forward pass, backward pass, parameter updates

Attempt 1 - Multiple variables:

layer1_weights = initialize_weights(100, 50)
layer1_biases = initialize_biases(50)
layer1_inputsize = 100
layer1_output_size = 50
def layer1_forward(x):
   return x @ layer1_weights + layer1_biases

Problem: For multiple layers, you'd need layer1_, layer2_, ... variables everywhere. Passing to functions becomes a mess.

Attempt 2 - Dictionary:

layer1 = {
   'weights': initialize_weights(100, 50),
   'biases': initialize_biases(50),
   'input_size': 100,
   'output_size': 50
}
 
def forward(layer, x):
   return x @ layer['weights'] + layer['biases']

Problem: No guarantee dictionaries have right keys, no bundled behavior, typo-prone.

Solution - Class:

class DenseLayer:
   def __init__(self, input_size, output_size):
       self.input_size = input_size
       self.output_size = output_size
       self.weights = self._initialize_weights()
       self.biases = self._initialize_biases()
   
   def _initialize_weights(self):
       # Xavier initialization
       limit = (6 / (self.input_size + self.output_size)) ** 0.5
       return np.random.uniform(-limit, limit, 
                                 (self.input_size, self.output_size))
   def _initialize_biases(self):
       return np.zeros(self.output_size)
   
   def forward(self, x):
       """Forward pass: y = xW + b"""
       return x @ self.weights + self.biases
# Usage
layer1 = DenseLayer(100, 50)
layer2 = DenseLayer(50, 10)
 
output = layer1.forward(input_data)
final = layer2.forward(output)

Why this works:

Data encapsulation: Each layer instance owns its weights/biases
Method binding: layer1.forward() automatically operates on layer1's weights
Type safety: DenseLayer objects guaranteed to have expected attributes
Initialization logic: __init__ ensures proper setup

Worked example Example 2: K-Nearest Neighbors Classifier Class

Task: Build a KNN classifier from scratch.

import numpy as np
from collections import Counter
 
class KNNClassifier:
   """K-Nearest Neighbors classifier with Euclidean distance."""
   def __init__(self, k=3):
       """
       Args:
           k: Number of nearest neighbors to consider
       """
       self.k = k
       self.X_train = None
       self.y_train = None
   
   def fit(self, X, y):
       """Store training data (lazy learning).
       
       Args:
           X: Training features (n_samples, n_features)
           y: Training labels (n_samples,)
       """
       self.X_train = X
       self.y_train = y
       return self  # Enable method chaining
   
   def _euclidean_distance(self, x1, x2):
       """Compute Euclidean distance between two vectors."""
       return np.sqrt(np.sum((x1 - x2) ** 2))
   
   def _predict_single(self, x):
       """Predict label for a single sample.
       
       Why this is a separate method? Decompose predict() for clarity.
       """
       # Compute distances to all training samples
       distances = [self._euclidean_distance(x, x_train) 
                    for x_train in self.X_train]
       
       # Get indices of k nearest samples
       k_indices = np.argsort(distances)[:self.k]
       # Get labels of k nearest neighbors
       k_nearest_labels = [self.y_train[i] for i in k_indices]
       
       # Return most common label (majority vote)
       most_common = Counter(k_nearest_labels).most_common(1)
       return most_common[0][0]
   def predict(self, X):
       """Predict labels for multiple samples."""
       return np.array([self._predict_single(x) for x in X])
   def score(self, X, y):
       """Compute accuracy on test set."""
       predictions = self.predict(X)
       return np.mean(predictions == y)
# Usage
knn = KNNClassifier(k=5)
knn.fit(X_train, y_train)
predictions = knn.predict(X_test)
accuracy = knn.score(X_test, y_test)

Why each design choice?

Why store training data in fit()? KNN is lazy – no training computation, just memorize data.
Why separate _predict_single()? Predict multiple samples by applying single prediction logic.
Why return self in fit()? Enables chaining: KNNClassifier(k=3).fit(X, y).predict(X_test).
Why underscore prefix _euclidean_distance()? Convention for "private" helper methods (internal use).

Modules: Organizing Code Across Files

Definition Module

A module is a Python file containing functions, classes, and variables. Modules organize related code and enable reuse across projects via import statements.

Basic structure:

my_ml_project/
├── data_preprocessing.py    # Module for data ops
├── models.py                # Module for model classes
├── metrics.py               # Module for evaluation
└── main.py                  # Script using the modules

Why Modules? Derivation from Scale

Formula From Single File to Module System

Stage 1 - Small script (100 lines):

# train.py - Everything in one file
def load_data(): ...
def preprocess(): ...
class Model: ...
def train(): ...
# Run
train()

Works fine for protypes.

Stage 2 - Growing project (1000 lines):

# train.py - Getting unwieldy
def load_csv(): ...
def load_json(): ...
def normalize(): ...
def tokenize(): ...
class LinearRegression: ...
class LogisticRegression: ...
class NeuralNet: ...
def mse(): ...
def accuracy(): ...
# ... 900 more lines

Problems: Hard to navigate, slow to load, unclear organization.

Stage 3 - Module organization:

# data_utils.py
def load_csv(): ...
def load_json(): ...
def normalize(): ...
# models.py
class LinearRegression: ...
class LogisticRegression: ...
# metrics.py
def mse(y_true, y_pred): ...
def accuracy(y_true, y_pred): ...
# train.py
from data_utils import load_csv, normalize
from models import LinearRegression
from metrics import mse
data = load_csv('train.csv')
data = normalize(data)
model = LinearRegression()

Why this works:

Separation of concerns: Each module has a single responsibility
Namespace management: models.LinearRegression vs sklearn.linear_model.LinearRegression
Selective imports: Only load what you need
Reusability: Other scripts can import data_utils without dragging in model code

Worked example Example 3: Building a Module for Text Preprocessing

Task: Create a reusable text preprocessing module for NLP tasks.

File: text_preprocessing.py

"""
Text preprocessing utilities for NLP tasks.
 
This module provides functions for common text cleaning operations:
- Lowercasing, punctuation removal
- Tokenization
- Stopword removal
"""
 
import re
from collections import Counter
 
# Module-level constant
COMMON_STOPWORDS = {'the', 'a', 'an', 'in', 'on', 'at', 'to', 'for'}
 
def remove_punctuation(text):
   """Remove punctuation from text, keeping only letters, numbers, spaces."""
   return re.sub(r'[^a-zA-Z0-9\s]', '', text)
def tokenize(text):
   """Split text into lowercase tokens."""
   return text.lower().split()
def remove_stopwords(tokens, stopwords=None):
   """Remove stopwords from token list.
   
   Args:
       tokens: List of string tokens
       stopwords: Set of stopwords (uses module default if None)
   """
   if stopwords is None:
       stopwords = COMMON_STOPWORDS
   return [token for token in tokens if token not in stopwords]
def get_vocabulary(documents, min_count=2):
   """Build vocabulary from documents, filtering rare words.
   
   Args:
       documents: List of token lists
       min_count: Minimum frequency to include word
   Returns:
       Dictionary mapping word -> unique_id
   """
   # Count all tokens
   counter = Counter()
   for doc in documents:
       counter.update(doc)
   # Filter by min_count
   vocab = {word: idx for idx, (word, count) in enumerate(counter.items())
            if count >= min_count}
   return vocab
 
def preprocess_pipeline(text, remove_stops=True):
   """Full preprocessing pipeline for a single text.
   
   Why a pipeline function? Combine common operations.
   """
   text = remove_punctuation(text)
   tokens = tokenize(text)
   if remove_stops:
       tokens = remove_stopwords(tokens)
   return tokens
# Only execute if run directly (not imported)
if __name__ == '__main__':
   # Test code
   sample = "The quick brown fox jumps over the lazy dog!"
   print(preprocess_pipeline(sample))
   # Output: ['quick', 'brown', 'fox', 'jumps', 'over', 'lazy', 'dog']

File: main.py (using the module)

from text_preprocessing import preprocess_pipeline, get_vocabulary
 
documents = [
   "Machine learning is fascinating",
   "Deep learning uses neural networks",
   "Machine learning transforms data"
]
 
# Preprocess each document
processed_docs = [preprocess_pipeline(doc) for doc in documents]
 
# Build vocabulary
vocab = get_vocabulary(processed_docs, min_count=1)
print(f"Vocabulary size: {len(vocab)}")

Why each choice?

Why module docstring? Explains purpose when someone does import text_preprocessing; help(text_preprocessing).
Why COMMON_STOPWORDS at module level? Shared constant, loaded once when module imported.
Why if __name__ == '__main__':? Test code runs when you execute python text_preprocessing.py but not when imported.

Advanced Concepts: `*args`, `**kwargs`, Decorators

Variable-Length Arguments

Formula Deriving *args and **kwargs

Problem: You want a create_model() function that accepts different numbers of layer sizes.

Rigid approach:

def create_model(layer1, layer2, layer3):  # Only works for 3 layers
   ...

Solution - *args (positional arguments):

def create_model(*layer_sizes):
   """Create model with arbitrary number of layers.
   
   Args:
       *layer_sizes: Variable number of integers (layer sizes)
   """
   print(f"Creating model with layers: {layer_sizes}")
   # layer_sizes is a tuple: (100, 50, 10)
   layers = []
   for in range(len(layer_sizes) - 1):
       layers.append(DenseLayer(layer_sizes[i], layer_sizes[i+1]))
   return layers
 
# Usage
model1 = create_model(784, 128, 10)        # 2 layers
model2 = create_model(784, 256, 128, 10)   # 3 layers

Problem: You want to pass configuration options as named arguments.

Solution - **kwargs (keyword arguments):

def train_model(model, X, y, **training_config):
   """Train model with flexible configuration.
   
   Args:
       **training_config: Variable keyword args (epochs=10, lr=0.01, etc.)
   """
   # training_config is a dictionary
   epochs = training_config.get('epochs', 100)  # Default 100
   learning_rate = training_config.get('learning_rate', 0.01)
   batch_size = training_config.get('batch_size', 32)
   
   print(f"Training for {epochs} epochs, lr={learning_rate}")
   # ... training loop
# Usage
train_model(model, X_train, y_train, epochs=50, learning_rate=0.001)
train_model(model, X_train, y_train, epochs=10)  # Uses default lr

Combining both:

def flexible_function(*args, **kwargs):
   print(f"Positional args: {args}")    # Tuple
   print(f"Keyword args: {kwargs}")      # Dictionary
flexible_function(1, 2, 3, name='test', value=42)
# Positional args: (1, 2, 3)
# Keyword args: {'name': 'test', 'value': 42}

Common mistake Common Mistake: Mutable Default Arguments

Wrong:

def add_sample(sample, dataset=[]):  # BUG: Mutable default
   dataset.append(sample)
   return dataset
result1 = add_sample(1)  # [1]
result2 = add_sample(2)  # [1, 2] - WHY?!

Why it feels right: "Default empty list makes sense."

Why it's wrong: Default arguments are created once at function definition time, not each call. The same list object persists across calls.

Fix:

def add_sample(sample, dataset=None):
   if dataset is None:
       dataset = []  # Create new list each call
   dataset.append(sample)
   return dataset

Steel-man the mistake: Using mutable defaults can actually be intentional for caching/memoization patterns, but it's almost never what beginers want.

Common mistake Common Mistake: Forgetting

self in Class Methods Wrong:

class Model:
   def __init__(self, weights):
       self.weights = weights
   def predict(x):  # BUG: Missing self
       return x @ self.weights  # NameError: self not defined

Why it feels right: "It's inside the class, shouldn't it automatically know about self.weights?"

Why it's wrong: Python doesn't have implicit this like some languages. Methods need explicit self parameter to access instance attributes.

Fix:

def predict(self, x):  # First parameter is always the instance
   return x @ self.weights

The deeper pattern: When you call model.predict(x), Python internally does Model.predict(model, x) – the instance is passed as first argument.

Recall Explain to a 12-year-old

Imagine you're organizing your school backpack: Functions are like labeled pouches. You have a "pencil pouch" (function) that holds all your pencils. Instead of dumping pencils loose everywhere, you put them in the pouch. When you need a pencil, you know exactly where to look. If you need to replace broken pencils, you only fix the pouch, not search whole backpack.

Classes are like your calculator. It's not just buttons (functions) – it also remembers numbers you typed (data/state). A "Calculator" class has memory slots (attributes) and buttons (methods). Each student has their own calculator with their own stored numbers, but all calculators work the same way.

Modules are like different textbooks. You don't carry all your books everywhere – you take your math textbook to math class, science textbook to science. Each book (module) contains related stuff. Your homework script "imports" from these books: from math_textbook import quadratic_formula.

When building AI, you might have a data_cleaning.py module (textbook) with a remove_duplicates() function (pouch) and a NeuralNetwork class (fancy calculator that remembers weights and can compute predictions).

Connections to Other Topics

Python basics - syntax, data types, control flow - Functions use control flow internally
NumPy arrays and vectorization - Classes often wrap NumPy arrays as attributes
Object-oriented programming in ML - Deep dive into inheritance, polymorphism with ML examples
scikit-learn API patterns - sklearn's fit/predict pattern is class-based design
Building neural networks from scratch - Classes essential for layer abstractions
Data pipelines and preprocessing - Modules organize pipeline stages
Software engineering for ML - Testing, documentation, version control of modules

#flashcards/ai-ml

What are the three fundamental code organization units in Python? :: Functions (reusable logic), classes (data + behavior), and modules (files organizing related code).

What is the purpose of the __init__ method in a Python class?

Constructor method that initializes instance attributes when creating an object. Called automatically when you write obj = ClassName(args).

Why should you avoid mutable default arguments in function definitions? :: Mutable defaults (like [] or {}) are created once at function definition time and persist across calls, causing unexpected shared state. Use None and create new object inside function.

What does *args allow in a function signature?

Accepts variable number of positional arguments as a tuple. Enables flexible functions like create_model(100, 50, 10) with any number of layers.

What is the difference between from module import function vs import module?

First imports specific names into current namespace (function()), second imports module itself requiring prefix (module.function()). First is convenient, second avoids name conflicts.

Why do class methods need self as the first parameter?

self refers to the instance calling the method. When you call obj.method(x), Python internally does Class.method(obj, x), passing the instance explicitly.

What does if __name__ == '__main__': do in a module?

Code inside runs only when file is executed directly (python module.py), not when imported. Used for testing and demos without affecting imports.

In a KNN classifier class, why does fit() just store the data?

KNN is a lazy learner – no training computation happens. It memorizes training data and does all work during prediction (computing distances to stored samples).

What is the Scikit-learn API pattern that classes follow?

Estimators have fit(X, y) for training and predict(X) for inference. Convention enables consistent interface across different models.

Why return self from a fit() method?

Enables method chaining like Model().fit(X, y).predict(X_test), a convenience pattern from sklearn API design.

Concept Map

Hinglish (regional understanding)

Intuition Hinglish mein samjho

Hinglish (regional understanding)

Intuition Hinglish mein samjho

Dekho, jab tum machine learning ka koi project banate ho, toh code bahut jaldi bada aur messy ho jata hai. Agar sab kuch ek hi lambe script mein likhoge toh debugging karna nightmare ban jayega, aur same logic baar-baar copy-paste karoge. Isliye Python humein teen tools deta hai code organize karne ke liye – functions, classes, aur modules. Simple analogy samjho: functions ek recipe hai (ek kaam ko step-by-step karti hai), classes ek appliance hai jismein data aur uspe chalne wale controls dono saath rehte hain, aur modules cabinets hain jo related cheezon ko ek file mein group kar dete hain.

Ab function ka core idea yeh hai ki agar tumhe koi logic – jaise MSE (mean squared error) calculate karna – baar-baar chahiye, toh usse ek naam de do aur inputs ko parameters bana do. Phir jitni baar chahiye utni baar bulaao. Note mein jo step-by-step derivation di hai, wahi asli intuition hai: pehle naive tarika (har baar poora formula likhna) galtiyon se bhara hota hai, phir tum usse ek named block banate ho, phir usmein inputs pass karte ho taaki alag-alag data pe kaam kare, phir docstring add karte ho taaki aage koi (ya khud tum) samajh sake, aur last mein default parameters se ek hi function multiple variations (jaise MSE ya RMSE) handle kar leta hai.

Yeh cheez matter kyun karti hai? Kyunki real ML kaam mein tum data preprocess karte ho, metrics compute karte ho, aur models train karte ho – yeh sab repeatedly hota hai. Functions ka asli faayda yeh hai ki tum ek baar likho, hazaar baar use karo, aur agar koi bug mile toh sirf ek jagah fix karo, na ki 50 jagah. Isse tumhara code clean, reusable, aur team ke saath share karne layak ban jaata hai – jo kisi bhi serious AI-ML developer ki pehli zaroorat hai.

Functions: Reusable Logic Blocks

Why Functions Matter in ML/AI

Classes: Data + Behavior Bundles

Deriving Classes from First Principles

Modules: Organizing Code Across Files

Why Modules? Derivation from Scale

Advanced Concepts: `*args`, `**kwargs`, Decorators

Variable-Length Arguments

Connections to Other Topics

Concept Map

Hinglish (regional understanding)

Hinglish (regional understanding)

Go deeper — visual, from zero

Test yourself — Python & Scientific Computing

Connections