Balancing and Preprocessing the Dataset

Before a model can classify anything, the data it trains on has to be prepared. This article follows one preparation pipeline from start to finish: download a spam dataset, load it, balance it, convert its labels to numbers, split it three ways, and save the parts to files. The goal is simple, to end with CSV files for training, validation, and testing, but each stage has to happen in a particular order, and each stage can introduce errors that carry forward.

The problem starts with the class distribution. A classification dataset assigns each row to a class. In a spam filter, every message is labeled either spam or ham, where ham means non-spam. If one class has far more rows than the other, the dataset is imbalanced. The larger group is called the majority class and the smaller one is the minority class.

Imbalance matters because the distribution of examples shapes what a model learns. When the majority class dominates the training data, the model sees the majority pattern far more often than the minority pattern, so its behavior can become biased toward the majority class. Dataset balancing is the process of adjusting the class distribution so that this bias is reduced.

The balancing logic is packaged as a single function named create_balanced_dataset. It takes a DataFrame called df whose Label column holds the values 'spam' or 'ham', and it returns a new DataFrame called balanced_df. The function is easiest to understand as four decisions made in sequence. First, count how many spam rows exist. Second, randomly select that many ham rows. Third, combine the selected ham rows with all of the spam rows. Fourth, return the combined result.

Notice what the function does not do. It does not create new spam rows, and it does not generate new ham rows. The balancing operation is called undersampling. You reduce the number of instances in the majority class until it matches the minority class. Undersampling keeps every minority example and keeps only a random subset of the majority examples. It adds no new data.

The diagram shows that the balanced dataset is not produced by one operation. It is assembled from two separate filters on the original DataFrame, joined by a sampling step and a concatenation step. The spam count does double duty. It sets how many ham rows are sampled, and every spam row is also carried into the result. Because all spam rows are kept and the ham rows are sampled to the same size, the final label counts match.

The step most likely to surprise you is the random sample. The count of ham rows is fixed by the spam count, so the sizes always match. But which ham rows are chosen is random. Without a fixed seed, each run could select a different subset of ham rows. The class counts would be identical from run to run, yet the actual rows inside balanced_df would differ. This is the point where a balanced dataset can diverge from what you expected: the proportions are right, but the specific contents may not be the same.

The sampling call in the listing passes random_state=123. Setting random_state makes the random selection repeatable, so the same input produces the same balanced dataset each time the code runs. This matters when you debug or compare results. If the output changes, you can trust that the cause is a change in your code rather than a different random draw.

Balancing needs data in memory, so the listing starts by getting the data. The dataset is the SMS spam collection, stored at a fixed URL on the UCI archive. The learner does not search for the file by hand. The URL is stored in a variable, and that variable is passed into a helper function that handles the download. The helper comes from the chapter 6 module, so only its calls appear here, not its internal code.

The helper takes four arguments: the URL, the path where the zip file will be saved, the folder where its contents are extracted, and the path of the data file inside that folder. The last argument is built from the folder path, so the file location is stated once and reused. The helper must run before pandas reads anything, because pandas can only read a file that already exists on disk.

After the DataFrame is loaded, the listing calls create_balanced_dataset on it, and every later step works from the balanced version. The order is deliberate. Balancing comes first, so that the split receives data that already has the intended class proportions. The source states the balancing and text-label mapping both happen before the split.

Next, the map call replaces each text label with an integer. Ham messages become 0 and spam messages become 1. The label column is the target a classifier learns to predict, so it must be numeric before a model can use it. The map happens after balancing and before splitting, so all three output files inherit the integer labels.

The balanced data is then divided by random_split into three sets: training, validation, and test. The call receives the balanced DataFrame and two fractions, 0.7 and 0.1. The first fraction sets the training share and the second sets the validation share. The test set is whatever remains, which is 0.2, or the remaining 20 percent.

The three returned objects are assigned on one line, in the order train, validation, then test. The assignment order matters because the variable names are the only thing telling a reader which split is which. Later code must use the same order when it refers to the splits.

The last stage writes each split to its own CSV file, using to_csv on the matching DataFrame with a file name. Each call passes index=None, which keeps the DataFrame row index out of the saved file. Each CSV therefore holds only the message and label columns, and the three files store the training, validation, and test data separately.

Every stage feeds the next, so a mistake at one stage propagates to all later stages. The pipeline runs download, unzip, load, count, sample, combine, label mapping, and split. An error that enters early, such as a bad file path, can cause a failure that looks like it comes from a later line. Tracing each stage in order helps you find where the problem actually starts.