Course contentsShow
← Data Science
Lesson 2060 of 2,14547. Reproducible ResearchFree lesson

Documenting Random Seeds

Learn best practices for recording seed values in code, notebooks, and documentation for reproducibility.

Documenting Random Seeds

You'll learn how to properly record seed values in your code and documentation so others (and future you) can reproduce your exact results.

Why Document Seeds?

Setting a seed is only half the reproducibility battle. If you don't document where and why you set seeds, your analysis becomes a black box. Imagine finding code that starts with seed=42 but no explanation—why 42? Was it arbitrary? Does changing it matter? Proper documentation turns mysterious numbers into transparent, reproducible choices.

Best Practices for Recording Seeds

In Code Comments

Always add inline comments explaining why you chose a particular seed:

# Seed ensures consistent train/test split across team runs
# Selected 2024 as project start year for easy recall
np.random.seed(2024)
X_train, X_test = train_test_split(X, y, test_size=0.2)

In Notebooks

Create a dedicated configuration cell at the top with all seeds defined as named constants:

# Reproducibility Configuration
SEED_DATA_SPLIT = 2024
SEED_MODEL_INIT = 2025
SEED_CV_FOLDS = 2026

In Documentation and Reports

Include a "Reproducibility" section that lists:

  • All seed values used
  • Where each seed is applied (data splitting, model initialization, cross-validation)
  • The random library/version (NumPy 1.24, scikit-learn 1.3, etc.)

In Version Control

Commit messages should note when seeds change: "Updated CV seed to 2026 for consistency with new experiment protocol"

The Arbitrary Choice Problem

Seeds are inherently arbitrary—42 and 123 are equally valid. Document that you tested sensitivity to seed choice, or explicitly state it's arbitrary but fixed for consistency.

Key Takeaway: Documenting random seeds means recording not just the values, but where they're used, why they were chosen (even if arbitrary), and which libraries they affect—turning reproducible code into truly understandable science.