Reproducible Runs

In order to perform a Reproducible Run from the Capsule IDE, the environment must be built and the run file must specify which script the Capsule should run.

Run File

The run file, often referred to as the driver script, is a bash script that generates all desired results in an automated manner without requiring human intervention. By eliminating manual input, the run file ensures consistent and reproducible results. During a Reproducible Run, the run file is executed from start to finish.

Setting up Run File

To designate a file as the run file in a Capsule:

1. Hover over the first script to run in the Capsule.

2. Click the drop-down menu that appears on the file.

3. Select Set as File to Run.

This action creates a run script that serves as your main shell script. You can modify this file as needed to orchestrate your analyses.

Properties of a good Run File

A well-designed run file should meet the following criteria:

1. Run Headlessly: The script should execute without requiring user input or displaying pop-ups during runtime.

2. Perform Minimal Actions: The run script should perform a very small number of actions, such as pointing to another script in the Capsule.

Executing a Reproducible Run

The Reproducible Run button is located at the top of the Reproducibility Panel, above the Timeline.

Once you click on it, the system will prepare the machine to run your computation. The files will be temporarily locked and show the computation progress information on the Reproducibility Panel.

You can stop the run by clicking on the Stop Run button. For more information, see Stop Computation after Run Step. When the run is complete you are returned to the Timeline where the results of the run are displayed, whether it was successful or not.

To view more information about a specific run, select Run Details from the drop-down menu in the Reproducibility pane.

Closing the browser tab during a run

Reproducible Runs are designed to persist even if the browser tab is closed. To check ongoing computations:

1. Navigate to the My Capsules dashboard.

2. Look for Capsules with a "running" status.

3. Click on the Capsule to view the ongoing process.

Availability of Files during Reproducible Run

Folder	Available in Reproducible Run	Path in Computation	Alternative Path in Computation
Metadata	❌	/root/capsule/metadata	-
Environment	❌	/root/capsule/environment	-
Code	✅	/root/capsule/code	/code
Data	✅	/root/capsule/data	/data
Results	✅	/root/capsule/results	/results
Scratch (CW)	❌	/root/capsule/scratch	/scratch
Scratch (RR)	✅	/root/capsule/scratch	/scratch
CW Root FS	❌	/	-

Referring to Files During a Run

• Use Relative Paths:

  • Simplify portability by using relative paths (e.g., ../data or ../results) wherever possible. This ensures ease of use for those running the code locally.

• Working Directory:

  • The initial working directory is /code when your code is executed. Avoid referencing /code explicitly by relying on relative paths instead.

• Subfolders:

  • When referencing files in subfolders, use relative paths such as:

    load('../../data/my_data.csv')

  • This example navigates up two parent directories to locate ./data/my_data.csv.

Concurrent Runs

You can use the Back to Timeline button at the top of the Reproducibility Panel to return to the Capsule Timeline and execute another run concurrently.

In the image below, there are two computations running at the same time. While computations are running, progress information is displayed in the Reproducibility Panel, and you can switch between runs by selecting View Run Details for any ongoing run in the Capsule Timeline.

Concurrent runs can be on either Flex or Dedicated machines.

The output displayed after a run will be for the second of the two concurrent runs. The run output can be switched between concurrent runs in the console by clicking View Output.

Stop Computation after Run Step

A computation can be stopped during a post-run step, such as results collection during a Reproducible Run or syncing back to the Capsule after a Cloud Workstation session. This functionality is particularly useful for saving time by skipping steps that may not be necessary, such as collecting results that are no longer required.

Warnings

Before stopping a computation, a warning is displayed to highlight the consequences of stopping the run:

• Reproducible Runs:

  • Stopping a run will result in the loss of all generated results.

• Cloud Workstation Sessions:

  • Any unsaved changes to the Capsule or its environment will be discarded.