Lab 1 — Reproducibility and Replicability

Introduction¶

This first laboratory introduces the fundamental concepts of reproducibility and replicability in open and computational science. Students will work through the complete setup of a collaborative scientific workflow, including account creation, local environment preparation, and organizational setup.

The laboratory culminates in two complementary activities:

1. reproducing an existing computational result using the original environment and methodology;

2. replicating the experiment under modified conditions or environments.

Laboratory procedure¶

Account creation¶

GitHub¶

Create a GitHub account and add both your username and your teammate’s username in this Google Sheet.

This account is required in order to grant your team access to a dedicated repository, which will be used throughout the laboratory activities and for the organizational setup phase.

If you already have a GitHub account, you may use it instead of creating a new one.

Local setup¶

Visual Studio Code¶

Install Visual Studio Code, which will be used as the primary code editor throughout the laboratory.

Git¶

As discussed in class, Git will be used for version control of both code and data. Install Git on your system.

Miniforge¶

Install Miniforge.

Miniforge is a lightweight Conda distribution used to create and manage reproducible Python environments. It is configured by default to use the community-maintained conda-forge package repository, which is widely adopted in scientific and research environments.

Organizational setup¶

Accept the invitation to the GitHub organization that will be sent to the email address associated with your GitHub account. This is the link to the organization.

Onboarding with GitHub¶

Fork the repository¶

Fork this repository. A fork creates your own copy of the repository under your GitHub account while preserving its connection to the original repository. You will complete the laboratory using your fork.

Modify a file from the GitHub interface¶

Modify the README.md file directly from the GitHub web interface.

Add your group number.

Select the option Create a new branch and start a pull request.

Compare your changes with your own repository¶

Open the pull request¶

Merge the pull request¶

Delete the unused branch¶

This promotes cleaner merges.

For more guidelines about branches, refer to Comparing Git workflows: What you should know.

Reproducibility¶

Clone the repository¶

From your terminal, clone your tp1 repository to a location where you will keep your course files. For example, you may create a dedicated directory for your ING8100 laboratories.

git clone <repository-url>
# Go inside your repository
cd <repo-name>

Create a new branch¶

git switch -c <branch-name>

Create the virtual environment¶

Follow the instructions provided in the README.md file.

Data analysis¶

Follow the instructions provided in the README.md file.

Add modified files to the staging area¶

Add the generated figure using:

git add <file-name>

or:

git add .

to stage all modified, added, or deleted files.

Create a commit¶

git commit -m "<commit-message>"

Push the changes¶

git push

The first push of a new branch must set the upstream branch:

git push --set-upstream origin <branch-name>

Create a pull request¶

Use the GitHub online interface to create the pull request (PR).

Add the teamate who is not creating the PR as the reviewer.

Merge the pull request¶

The reviewer must approve and merge the PR.

Delete the branch¶

Once the PR is merged, delete the source branch (not main).

Replicability¶

Return to the main branch¶

git switch main

Pull the latest changes¶

git pull origin main

Create a new branch¶

git switch -c <branch-name>

Modify the analysis parameters¶

Open the src/analysis.py file and change the values of:

START_YEAR = ...
END_YEAR = ...

This modification represents a new experimental configuration, which is part of the concept of replicability.

Run the analysis again¶

Execute the analysis using the instructions provided in the README.md file.

Create a commit¶

Use the VS Code Source Control interface to create your commit.

Push the branch¶

Use the VS Code Source Control interface to synchronize the changes.

Create a pull request¶

Use the GitHub interface to create a pull request for the new branch.

Review the pull request¶

A pull request review differs from a simple comment.
When starting a review, GitHub groups comments together and allows the reviewer to formally approve the changes or request modifications.

The other teammate must:

• start a review on GitHub

• leave a comment requesting a modification to the selected year range

Apply the requested changes¶

Modify the START_YEAR and/or END_YEAR values again according to the review comments.

Resolve the review¶

After applying the requested changes:

git add .
git commit -m "<commit-message>"
git push

Then resolve the review conversation on GitHub.

Merge the pull request¶

Once the review is approved, merge the pull request into main.

Delete the branch¶

After the merge is completed, delete the source branch (not main).

Evaluation¶

The evaluation is based on the following criteria: