ML data engineering
Training Dataset Construction and Release
Construct cohorts, intermediate products, snapshots, diffs, and release evidence for model training.
By the end you can
- Build a dataset from an explicit example spine and cohort contract
- Choose between materialized examples, views, and reproducible recipes
- Publish snapshots with manifests, diffs, checks, and ownership
- Distinguish deterministic code from reproducible data evidence
Build from the example spine, not from the easiest table
A training dataset should begin with a spine: one row for every example the learning protocol intends to include. The spine carries the example key, the subject, the prediction time, and often the outcome window. Features are then joined onto that spine under explicit temporal and cardinality rules. Labels are assigned separately, so that feature availability and outcome logic both stay inspectable. Starting from a large feature table can reverse this discipline. The available rows begin defining the population. Examples with missing joins disappear without a deliberate exclusion rule.
A published training dataset is therefore a release artifact. It combines a population definition, source snapshots, transformation code, feature availability, labels, splits, diagnostics and documentation. The rest of this lesson takes those parts one at a time. For each it asks the same two questions: what does a published dataset that actually does this look like, and what does the record show when it is skipped?
The example spine defines who could be learned from; joins should enrich that population rather than redefine it accidentally.
Visual
A reproducible build has named intermediate products
Separating stages makes population changes and target logic easier to inspect.
Stage 3 is the one most often treated as a lookup rather than as a product with its own error rate. The test sets of 10 widely used vision, language and audio benchmarks are the sets whose numbers the field reports as ground truth. Northcutt and colleagues tested them for label errors, and opened their abstract with the result: “Errors in test sets are numerous and widespread: we estimate an average of at least 3.3% errors across the 10 datasets, where for example label errors comprise at least 6% of the ImageNet validation set.” The algorithmically flagged candidates were not taken on trust either. Crowdworkers confirmed 51% of them as erroneous.
The figure has since been repeated from outside the group. Anzaku and colleagues, re-annotating ImageNetV2, write that “Label errors have been identified within the test sets of numerous commonly used datasets, including a 6% error rate in the ImageNet-1k validation set [11].”
The most scrutinised label sets in the field carry that much error. So a label column assembled in-house, out of an operational review process, is not a fact to be joined in silently at stage 3. It is a stage that owes the reader a count.
1. Example spine
Generate unique subjects and prediction times under the inclusion policy.
2. Feature assembly
Attach only observations available before each prediction cutoff.
3. Label assignment
Evaluate outcomes over the declared horizon and mark censoring or uncertainty.
4. Split assignment
Apply grouped, temporal, or other protocol-specific boundaries deterministically.
5. Snapshot publication
Freeze data references, code, schema, diagnostics, and documentation together.
Each stage should expose row counts and reasons for inclusion, exclusion, or unresolved status — labels included, since even benchmark test sets run at least 3.3% wrong.
Comparison
Materialize examples, views, or recipes?
The right choice depends on data scale, reproducibility needs, and how often source history changes.
Materialized dataset
Store the complete rows used by the experiment.
- Strongest protection from source mutation
- Simple to inspect and share within governance limits
- Consumes storage for repeated variants
- Best for release candidates and regulated evidence
Immutable source snapshot plus recipe
Store exact source versions and deterministic build logic.
- Reduces duplicated final storage
- Supports rebuilding feature variants
- Depends on durable source snapshots and environments
- Best when transforms are deterministic and sources persist
Live view or query
Recompute from current source tables when read.
- Convenient for exploration
- Can change without a new dataset identifier
- Weak evidence for experiment reproduction
- Unsuitable as the sole record of a published result
Key idea
Deterministic code does not guarantee reproducible data
A deterministic query against mutable sources can return different rows next month. External APIs, current-state dimensions, nondeterministic deduplication ties and changing user-defined functions can alter results too. Rebuilding the same rows requires stable inputs, stable logic, stable parameters, and one agreed reading of how the job runs. Even then, distributed ordering can affect operations that choose an arbitrary first row. Use explicit tie-breakers, immutable snapshots, content hashes and versioned dependencies. Test a rebuild by comparing keys and values, not only row counts.
Reproducibility is the product of deterministic logic and immutable dependencies together.
Case
1,159,166 notebooks, and the 4.03% that reproduced
The previous section's claim has been put to a measurement. For a 2019 study, Pimentel and colleagues assembled “a corpus consisting of 1,159,166 unique notebooks collected from 264,023 GitHub repositories” — roughly 4.4 notebooks per repository — and then tried to run them. Their introduction states the outcome: “out of 863,878 attempted executions of valid notebooks … only 24.11% executed without errors and only 4.03% produced the same results”.
Read the two rates against each other. Only 74.5% of the collected corpus was even attempted, so the 4.03% is a share of the notebooks that got that far, not of the million. Running and reproducing are separated by a factor of 6.0: for every six notebooks that finished without raising an error, one returned what its author had recorded. The code was deterministic in the ordinary sense. What had moved were the dependencies underneath it. That is the gap this lesson's snapshots, hashes and pinned environments exist to close.
Figure
Steps
Release a training dataset like a versioned product
Publishing a version should make its differences from the last one reviewable. It should also make the terms of use, the known defects and the exit route explicit.
A standard form for this was proposed in 2018. The datasheet, from Gebru and colleagues, asks every dataset to document “its motivation, composition, collection process, recommended uses, and so on”. The analogy is the electronics datasheet that ships with each component. The proposal reached Communications of the ACM in December 2021.
Since 1 August 2024, when it entered into force, that documentation has had a statutory floor. Regulation (EU) 2024/1689, the AI Act, states at Article 10(3): “Training, validation and testing data sets shall be relevant, sufficiently representative, and to the best extent possible, free of errors and complete in view of the intended purpose.” Article 10(2)(f)–(g) add the examination for possible biases and the measures to detect, prevent and mitigate the biases so identified. The European Commission's own regulatory framework page puts the high-risk requirement as “high-quality of the datasets feeding the system to minimise risks of discriminatory outcomes”. For a high-risk system in the EU, step 5's intended use, restrictions and known gaps are not house style. They are obligations under a named regulation, with an article number.
Step 5's deprecation policy is not hypothetical either. On 23 December 2023 David Thiel of the Stanford Internet Observatory published an evaluation of LAION entries above a safety cutoff, 32,138,129 items examined. His report says what came back: “Through this process, we identified 3,226 dataset entries of suspected CSAM, much of which was confirmed as CSAM by third parties.” LAION withdrew the corpus. On 30 August 2024 it republished as Re-LAION-5B, and the release note gives a removal count rather than a reassurance: 2,236 links removed after matching against hash lists from the Internet Watch Foundation (18), the Canadian Centre for Child Protection (1,129) and Stanford (1,714). That set subsumes the 1,008 links named in the December 2023 report. A named version, a withdrawal, a successor with a new identifier, and an itemised list of what left: that is step 5 being exercised rather than promised.
1. Freeze dependencies
Record source snapshots, schemas, contracts, code commit, parameters, and environment.
2. Produce diagnostics
Save row counts, exclusions, duplicates, missingness, labels, slices, and temporal coverage.
3. Assign deterministic splits
Persist split membership rather than regenerating it from a changing population.
4. Compare the previous version
Measure population, feature, label, and coverage changes before approval.
5. Publish documentation
State intended use, restrictions, known gaps, owner, retention, and deprecation policy.
Re-LAION-5B was reissued with a count of 2,236 removed links, itemised by the list each match came from — a version is reviewable only when its changes arrive as numbers.
Analogy
Specimens that travel with their protocol
Laboratory studies store labeled specimens, collection dates, preparation methods, instrument settings and group assignments. The result can be reexamined years later because the evidence and the protocol travel together. The example spine is the participant roster. Feature assembly is specimen preparation. Split assignment defines the study groups. The dataset manifest is the chain-of-custody record. Retention policy rarely gets the latitude a freezer does. When the raw records have to go, immutable source references, hashes, summaries and transformation provenance may need to substitute for full materialization.
A reproducible dataset preserves both the evidence and the protocol that made the evidence interpretable.
Dataset diffs should explain why the model changed
Compare dataset versions at several levels. Start with example keys: added, removed, and retained rows. Then compare labels, features, missingness and important slices among the retained examples. Separate expected changes from unexplained ones. A new source may add coverage intentionally, while a sudden category collapse may signal a producer bug. Model metrics alone are too downstream for this task. A model can hide a data defect temporarily, and fixing a real data defect can lower an overoptimistic score.
MIMIC-IV publishes this comparison in public. It is distributed through PhysioNet by the MIT Laboratory for Computational Physiology, and it has appeared as eight dated versions: 0.3 and 0.4 on 13 August 2020, 1.0 on 16 March 2021, 2.0 on 12 June 2022, 2.1 on 16 November 2022, 2.2 on 6 January 2023, 3.0 on 23 July 2024 and 3.1 on 11 October 2024. The v3.0 release notes state the population delta in figures rather than in adjectives: patients 299,712 → 364,627, admissions 431,231 → 546,028, ICU stays 73,181 → 94,458. The reason is one sentence: “Stays occurring between 2020 and 2022, inclusive, were added to the database.”
The pre-v3.0 side of that diff is independently checkable. Johnson and colleagues, in Scientific Data, describe 431,231 hospital admissions and 73,181 ICU admissions collected between 2008 and 2019. A team whose metrics moved after upgrading can therefore ask a specific question — did the added years change the case mix? — instead of a vague one.
Store the diff report with the release. It becomes the first document investigators consult when training behavior changes after a data update.
MIMIC-IV v3.0 names its delta — 431,231 admissions to 546,028 — and the reason for it; a diff that cannot be stated that way is not yet a diff.
Example
Build steps that silently redefine the population
Each step needs an explicit policy and a diagnostic count. The cost of leaving them implicit has been counted across the sciences. Kapoor and Narayanan surveyed reviews of ML-based science and summarised the result this way: “Through a survey of literature in fields that have adopted ML methods, we find 17 fields where leakage has been found, collectively affecting 294 papers and, in some cases, leading to wildly overoptimistic conclusions.” Their paper appeared in Patterns on 4 August 2023, and it sorts the failures into a taxonomy of eight distinct leakage types. The earlier preprint, from 14 July 2022, had put the count at 329 papers across the same 17 fields.
The finding has been restated from outside that group. Simon Roth, surveying 2,047 benchmark datasets, writes: “Kapoor and Narayanan audited the machine learning literature across 17 scientific fields and found 294 published papers whose results were invalidated by data leakage after publication; their living survey now catalogues 648 papers (as of mid-2024) across 30 fields.”
None of those 294 papers set out to define a population by accident. The five steps below are how it happens.
- Inner join: customers without a profile row disappear, even though the serving system must still score them.
- Complete-case filter: examples with any missing feature are removed, concentrating the dataset on well-measured users.
- Latest-record selection: a correction submitted after prediction time replaces the value that was actually available then.
- Label availability filter: only investigated fraud cases remain, turning an operational review policy into the target population.
- Minimum-history rule: new entities are excluded offline even though cold-start entities appear frequently in production.
Key takeaways
- A training-dataset build should start from an explicit example spine rather than the most convenient source table, and end as a governed release: Article 10(3) of Regulation (EU) 2024/1689 requires high-risk training, validation and testing sets to be relevant, sufficiently representative and, to the best extent possible, free of errors.
- Feature assembly, label assignment, split assignment and snapshot publication are separate reviewable stages — labels most of all, since Northcutt and colleagues found at least 3.3% label error across 10 benchmark test sets, and at least 6% in the ImageNet validation set.
- Inner joins, complete-case filters and label-availability rules can silently redefine the training population; Kapoor and Narayanan found leakage of exactly this kind in 17 fields, affecting 294 published papers, under a taxonomy of eight types.
- Reproducibility requires immutable dependencies and deterministic logic, not deterministic code alone: of 863,878 attempted notebook executions, 24.11% ran without errors and only 4.03% produced the same results.
- Persisted split membership protects evaluation comparisons when the dataset population evolves.
- Dataset version diffs should explain changes in keys, labels, features, missingness, slices and time coverage before model training begins — MIMIC-IV v3.0 published its additions (admissions 431,231 → 546,028) and Re-LAION-5B its removals (2,236 links), which is what a reviewable version change looks like in each direction.