Lesson 3 of 5 · reading 15–25 minutes; practice and project time is on the module page

Data as arrays: X, y and one row per prediction

🎯You'll be able to

Turn a table into a feature matrix X and a target vector y, check their shapes and look at the target's balance.

🏠The everyday picture

A teacher's mark sheet has one row per student and one column per test; the final result is in the last column. A model needs data in the same shape: one row per example, one column per input, and the answer kept separately.

📘What it really is

NumPy stores numbers in arrays, which are fast to compute with. pandas wraps them in tables with column names.
X is a table with one row per example and one column per feature. Its shape is (rows, features).
y is a single column with the target for each row, in the same order as X.
Types matter. Models need numbers. Categories such as dest_zone are text, so they are turned into numbers before training (ML2 Lesson 3). The kit's build_frame produces the 12 feature columns; a pipeline does the turning into numbers.
The balance of the target is the share of each answer. DakDost's is 8.43% late, which is called imbalanced: one answer is much rarer than the other. This changes which measures make sense (ML4).
Look before you train: count rows, missing values, the range of each number and the share of each category.

📝A worked example

Input:

from dakdost.features import build_frame
X = build_frame(df)
y = df['late']
print(X.shape, y.shape)
print(y.value_counts())
print(X.head(3))

Expected output: (13410, 12) (13410,), then 0: 12280 and 1: 1130, then three rows. The first is a parcel from Jaipur (JAI) to a regional address, 287.1 km, 1.79 kg, standard service, a morning pickup, an address score of 0.95, a hub load of 27, booked at 7 a.m. on a Thursday (booked_weekday 3, counting Monday as 0). Measured on 2 November 2026 with pandas 3.1.0.

🌍Where it's used

Image models: X is a stack of images, each an array of pixel values; y is the label for each image.
Text models: X is text turned into numbers; y is the category.
Forecasting: X holds past values and calendar features; y is the value to forecast.

📝Case scenario

A team's model trained without errors but its predictions made no sense. They had sorted X by date and y by shipment id, so each row's answer belonged to a different parcel. A check that X and y came from the same table, in one step, would have caught it.

🖱️Try it

Run the worked example, then find the share of late parcels for each destination zone with df.groupby('dest_zone')['late'].mean(). Success: local is about 5% and remote about 23%.

⚠️Common mistakes

Building X and y separately. Sign: rows no longer match. Fix: take both from the same table in one step.
Ignoring the balance. Sign: "90% accurate" sounds good when 90% of parcels are on time anyway. Fix: always report the target's share.
Training before looking. Sign: a strange result nobody can explain. Fix: count, describe and plot first.

🛠️For your project

Project 1 uses the same build_frame in training and in the API, so the model sees the same 12 columns in both places.

✅Quick check

What is the shape of X for 13,410 parcels and 12 features?

Show the answer

(13410, 12).

What does "imbalanced" mean here?

Show the answer

One answer (late) is much rarer than the other (on time).