Lab 3 — Building a Reproducible Open Science Project

Introduction¶

This laboratory introduces the principles of reproducible research through the development of an open science project based on the dataset selected and published on Borealis in Lab 2. You will organize a repository following community best practices, manage a reproducible computational environment, and build a documented data analysis workflow using Git and GitHub.

GitHub Environment¶

Repository¶

Create a repository. Refer to the GitHub Quickstart for repositories for an introduction to repository creation and management.

README.md file¶

The README.md file is the entry point to your project. It provides the information needed for others to understand your work, reproduce your results, and reuse your repository.

You may use the following template as a starting point:

Template: World Bank README template

The README.md should be updated throughout the lab as you build your project.

License¶

A license defines how others are allowed to use, modify, and share your project.

Code of Conduct¶

A Code of Conduct establishes clear expectations for respectful and inclusive collaboration within your project.

CONTRIBUTING.md file¶

A CONTRIBUTING.md file explains how others can participate in your project. It defines clear guidelines for submitting changes, reporting issues, and following project conventions.

AI_Prompts file¶

Create an AI_Prompts.md file that documents the AI model used during the assignment and the most useful prompt you used. Sharing an effective prompt can help others learn from your experience and apply similar techniques in their own work.

When writing your prompts, pay particular attention to the Description component of the 4D Framework, as providing clear context is essential for obtaining useful and reproducible results. To learn more about effective prompting, you are encouraged to explore Anthropic’s free AI Fluency Framework Foundations course.

Branch protection rules¶

Branch protection rules help maintain the integrity of your repository by preventing direct or unreviewed changes to critical branches.

Protect main¶

The main branch should always remain stable and represent a working version of the project. Direct pushes to this branch must be prevented so that all changes go through a controlled review process.

Pull requests required with at least one review¶

All changes must be submitted through pull requests and reviewed by at least one other team member. This ensures that no one approves their own changes and promotes collaborative validation of the work.

Branch naming convention¶

A consistent branch naming convention must be followed to keep the project history clear and readable. This helps avoid confusion and makes it easier to understand the purpose of each branch.

Issues¶

You must use GitHub Issues to structure and track the work of your project. Each issue should represent a clear task or objective, and the work should be distributed across the team.

You need:

• At least 3 issues,

• At least one assigned to each member,

• At least one closed via PR.

Collaborative Git workflow¶

Throughout the lab, use the collaborative Git workflow introduced in Lab 1. Organize your work into issues, develop changes on appropriately named branches, write meaningful commit messages, and submit pull requests for review before merging them into main.

Keep your repository documentation up to date as the project evolves, and ensure that your commit history reflects the progression of your work.

Code environment¶

Folder structure¶

A clear folder structure separates raw data, processed data, code, results, and documentation in a consistent way, making the workflow easier to understand and navigate.

For example:

project-root/
│
├── README.md
├── environment.yml
├── .gitignore
├── data/
│   ├── raw/
│   └── processed/
├── scripts/
│   ├── download_data.py
│   └── analyze.py
├── notebooks/
├── figures/
└── results/

Virtual environment¶

Create a virtual environment to isolate project dependencies and ensure a reproducible computational setup. This prevents conflicts with other projects and avoids polluting your global environment.

Choose one of the following options to create your virtual environment:

• Isolating programming environments for Python using Conda to create a virtual environment using Conda, as introduced in Lab 1.

• Virtual Environments and Packages with venv to create a lightweight virtual environment using Python’s built-in venv module.

Download the data¶

Create a script that retrieves the dataset from Borealis. This step ensures that data acquisition is automated and reproducible, rather than performed manually.

Preprocess the data¶

Create a preprocessing script to clean and standardize the raw data before analysis. This may include:

• missing values handling

• renaming / formatting columns filtering rows (basic criteria)

• simple type conversion (string → numeric/date)

• removing obvious outliers if justified

Analyze your data¶

Create a script that performs the data analysis and generates the results. The script should compute summary metrics and produce visualizations that help answer your research question. The use of Pandas, NumPy, and Matplotlib is recommended.

Compute 2–3 metrics¶

Compute at least two or three meaningful metrics from your dataset. Typical examples include:

• Mean

• Correlation

• Grouped statistics

Produce 1–2 visualizations¶

Produce one or two visualizations that communicate your results effectively. Each visualization must:

• Be directly related to the research question or a computed metric.

• Be understandable without reading the source code.

• Include appropriate axis labels, a title, and a short explanation.

Examples include:

• Scatter plot with a correlation analysis.

• Bar plot of grouped means.

• Distribution plot with summary statistics.

Comment your code¶

Write clear, readable code and include comments where they improve understanding. Comments should explain the purpose or reasoning behind the code rather than restating what individual statements do. Refer to the MIT Communication Lab guidelines on coding and comment style for recommendations.

Report¶

Create a report in Markdown (.md) format that presents your project and communicates the results of your analysis. The report should briefly introduce the research question, describe the dataset, summarize the methodology, and discuss the main findings.

Include the figures generated by your analysis and explain what they show. Each figure should be referenced in the text and accompanied by a short interpretation that relates it to your research question.

Virtual environment export¶

Export your virtual environment and its dependencies to a file that can be used to recreate the same computational environment. This file captures the project’s required packages and versions, allowing others to reproduce your analysis in a consistent environment.

Depending on your chosen environment management tool, export your dependencies using the appropriate format:

• For Conda environments, use an environment.yml file.

• For Python venv environments, use a requirements.txt file.

.gitignore file¶

The .gitignore file specifies which files and directories should not be tracked by Git. It is commonly used to exclude temporary files, caches, virtual environments, and large or generated data files that should not be stored in the repository. Keeping these files out of version control helps maintain a clean and reproducible project.

You may use the GitHub .gitignore template as a starting point. As your project evolves, remember to update your .gitignore and other repository files as needed to reflect changes to your project structure and workflow.

Bonus — Continuous Integration (CI)¶

Continuous Integration (CI) is commonly used in open science projects to automatically verify that a project remains reproducible as it evolves.

Using GitHub Actions, implement at least one automated workflow for your repository.

Possible examples include:

• Run a linter on Python scripts (e.g., Ruff, Flake8, Pylint).

• Verify that the Conda environment can be created successfully.

• Execute the preprocessing and analysis scripts.

• Generate the notebook automatically from scripts.

• Check that required repository files are present (README, LICENSE, CONTRIBUTING, etc.).

Requirements¶

• Create at least one GitHub Actions workflow in .github/workflows/.

• Document the workflow in the README.

• The workflow must execute automatically when a Pull Request is opened or updated.

Evaluation¶