Publishing a Reproducible Computational Book

Conceptual map

1. V-06.01Chapter contracts
2. V-06.02Environment records
3. V-06.03Sources and permissions
4. V-06.04Tests
5. V-06.05Web display and execution

1. A chapter contract separates claims from demonstrations

A reproducible computational chapter tells readers which statements are proved, which are computed for fixed inputs, and which remain empirical or numerical evidence.

The contract lists required data, generated artifacts, commands, environment, expected runtime, memory, random-state policy, and acceptance tests. Each figure and table has one generating target. Hand-edited numbers break the dependency graph unless the manual operation is itself recorded as a source transformation.

2. A manifest certifies byte identity

For every released file, store path, media type, size, cryptographic digest, role, and generating target. The byte string “theta=0.5” followed by a newline has SHA-256 digest 6c2a607e45bdea99821f70a9ea6cff27280c82249e87e1fb380f8b41f008630c. A verifier recomputes the digest after extraction and rejects a mismatch before executing code.

The certificate says nothing about scientific correctness, licensing, completeness, or safe execution. A manifest can faithfully preserve a flawed program. Provenance, tests, and substantive review supply those separate gates.

3. Environments and randomness are inputs

Record interpreter and library versions, operating-system dependencies, locale, time zone, numerical libraries, hardware-sensitive settings, and environment variables actually read. Lockfiles must be resolved and tested; a package name without a version range does not freeze behavior. Containers improve isolation but their base images and build arguments also need immutable identifiers.

A fixed pseudorandom seed reproduces a deterministic generator stream only when algorithm, library, parallel scheduling, and draw order are controlled. Statistical conclusions should remain valid across admissible seeds. Release tests can include a fixed-seed snapshot and a multi-seed stability envelope.

4. Web display and executable release are different artifacts

Relative paths, case sensitivity, file permissions, archive timestamps, line endings, and locale-dependent sorting often separate local success from clean execution. Restricted data require synthetic or derived public inputs and a documented protected-data route. Network downloads need versioned URLs, digests, licenses, and an offline failure mode. Empty datasets, unavailable GPUs, zero-length simulations, interrupted builds, and partial outputs must fail clearly. Accessibility and responsive display are publication tests, while numerical equivalence belongs to the computational gate.

5. Implementation, exercises, and sources

Organize source, data manifests, environment locks, generated artifacts, and tests in separate directories. Provide a single top-level validation command. Run it from a clean temporary directory, verify input and output digests, scan logs for warnings, and compare generated pages with their source fragments. Publish only after the archive, extracted archive, and served copy agree on the release manifest.

Exercises

1. Recompute the digest in Section 2 and test one-byte modification.
2. Design acceptance tests for a stochastic table.
3. List the extra records needed when a chapter downloads a mutable public dataset.

1. Greg Wilson et al. (2014), “Best Practices for Scientific Computing,” PLoS Biology 12, e1001745.Testing, automation, and source management.
2. Mark D. Wilkinson et al. (2016), “The FAIR Guiding Principles for Scientific Data Management and Stewardship,” Scientific Data 3, 160018.Findable and reusable research objects.
3. Adam Rule et al. (2019), “Ten Simple Rules for Writing and Sharing Computational Analyses in Jupyter Notebooks,” PLoS Computational Biology 15, e1007007.Executable narrative and clean reruns.