1.1 Open Reproducible Science

🖥️ Lecture slides — Session 01 (Wed Sep 30)

Open, reproducible science is the working standard for this course. Every homework and the final project are graded partly on whether someone else could rerun your analysis and get your result. This page explains what that means in practice: open science, the FAIR principles, licenses, data citation, preprints, and why reproducibility matters more now that AI writes a lot of the code.

Two complements to this lesson (not substitutes for it):

What is open science?¶

Open science is the practice of making the products of research — data, code, methods, and papers — available for others to inspect, reuse, and build on. In the geosciences this is not an abstract ideal. Most of the data we use in this book (seismic waveforms, GNSS positions, satellite imagery, climate reanalyses) exists because agencies and researchers published it openly. When you publish your own work the same way, you close the loop.

Open science has several components:

Open data: observations and derived data sets deposited in archives, with documentation.
Open source: analysis code published under a license that permits reuse.
Open methods: workflows described well enough (or scripted well enough) to be repeated.
Open access: papers readable without a paywall, often via preprints.

Reproducibility is the thread through all four. A result is reproducible if someone with your code and data can regenerate your figures and numbers. It is replicable if someone with new data and their own code reaches the same conclusion. This course grades the first and aims for the second.

FAIR principles¶

The FAIR principles (Wilkinson et al., 2016) describe what makes data useful to others:

Findable: the data has a persistent identifier (a DOI) and rich metadata, and is indexed somewhere searchable.
Accessible: the data can be retrieved by a standard protocol (HTTPS, not “email the author”).
Interoperable: the data uses open, documented formats (CSV, NetCDF, HDF5, GeoTIFF) and standard vocabularies, so it can be read across languages and tools.
Reusable: the data carries a clear license and enough provenance information that someone else can judge whether it fits their purpose.

When you assemble an AI-ready data set in Chapter 2, you will apply these to your own products: archive the data, document the provenance, attach a license, get a DOI.

Geoscience data is often data about place, and data about place can carry obligations that a license file does not capture — local regulations, community agreements, or national data policies. Before assuming open publication is appropriate, check the terms under which the data were collected.

Licenses¶

Without a license, others legally cannot reuse or modify your work, even if it sits in a public repository. “Public” does not mean “licensed.” So every repository you create in this course carries a license file.

Software licenses. The common open source choices:

MIT and BSD: permissive. Anyone can reuse the code, including commercially, as long as they keep the copyright notice. Most scientific Python packages (numpy, pandas, scikit-learn) use these.
GPL: copyleft. Reuse is allowed, but derivative works must carry the same license.

choosealicense.com walks you through the choice. For coursework, MIT is a sensible default. The Turing Way licensing chapter has a longer discussion.

Data and text licenses. Software licenses are written for code and fit data poorly. For data sets, documentation, and figures, use Creative Commons:

CC-BY: reuse with attribution. The common choice for data sets and papers.
CC0: public domain dedication, no conditions. Common for data where attribution tracking is impractical.

A repository that contains both code and data can carry two licenses — say, MIT for the code and CC-BY for the data — with the split stated in the README.

What a reusable repository contains¶

Beyond the license, a repository that others (including future you) can use has:

README.md: the center piece of the documentation. What the project is, how to install it, basic usage, how to cite it, how to get help. See awesome-readme for good examples. A citation block in BibTeX belongs here:
```
@software{MLGeo,
authors = {The GeoSMART team},
year = 2023,
doi = {10.5281/zenodo.7838345}
}
```
LICENSE: as above. You may need separate language for software and data.
CONTRIBUTING.md: what contributions are welcome and how to make them. Awesome contributing guides has examples.
An environment specification: pixi.toml and pixi.lock, or environment.yml, or requirements.txt, so the software environment can be rebuilt (see 1.3).

The Software Carpentries Intermediate Research Software Development lessons cover this in depth Nenadic et al., 2022.

Data citation and DOIs¶

A DOI (Digital Object Identifier) is a persistent identifier that resolves to a data set, paper, or software release forever, even if the hosting URL changes. Data with a DOI can be cited like a paper, which is how data producers get credit — and why archives require you to cite the data you use. When this book downloads GNSS data from the Nevada Geodetic Laboratory in 1.7, we cite Blewitt et al. (2018). Do the same for every data set in your project.

Zenodo, operated by CERN, mints DOIs for free and integrates with GitHub: link your repository once, and every GitHub release is archived on Zenodo with its own DOI automatically. This is how you make your final project citable. GitHub documents the workflow here. Domain-specific archives (PANGAEA, EarthScope, national data centers) serve the same role for observational data.

Preprints¶

A preprint is the manuscript posted publicly before (or during) peer review. In the Earth sciences, the main servers are EarthArXiv and ESS Open Archive (ESSOAr). Preprints make results available months to years earlier than journals, carry DOIs, and are citable. Most geoscience journals permit preprinting; check the journal’s policy. Reading preprints is also part of the weekly literature work in this course, with the standard caution: a preprint has not yet been peer reviewed, so read it with the same critical eye you will learn to apply to AI output.

Reproducibility in the AI era¶

You might expect AI assistants to make reproducibility concerns obsolete: if the code can be regenerated on demand, why archive it? The opposite is true.

AI-generated code is not deterministic. Ask the same assistant the same question twice and you get different code. The only record of what you actually ran is the code you committed, in the environment you locked.
Volume goes up, scrutiny per line goes down. An assistant can produce a working-looking analysis in minutes. Whether it computed what you think it computed is a separate question, and the answer lives in the committed code, not in your memory of the prompt.
Provenance now includes the AI. Disclosing which tools were used, for what, is part of the methods, exactly like naming the software packages and versions. The course policy is in 1.8.
Verification is the new bottleneck. When code is cheap, the reproducible artifact — locked environment, pinned data, scripted workflow, committed outputs — is what lets a human (you, a teammate, a reviewer) check the work efficiently.

Chapter 5 develops this into a full workflow: environments as lockfiles, data versioning, and experiment tracking. For now, the rule is simple: everything that produced a figure or a number in your project is committed, licensed, and rerunnable.