Reproducing a colleague's research project

This tutorial walks through how to actually reproduce someone else's work.

What you will achieve. By the end of this tutorial you will have received a colleague's reproducible research package, restored their working environment, run their original analysis to confirm it produces the result they reported, and (optionally) branched off into your own instance to build on top of their work without disturbing the original.

How long it takes. About 30–60 minutes for the reproduction itself, depending on the size of the analysis. Application restoration and (if applicable) Docker image import can take 10–20 minutes in the background.

What you need before you start. You should have completed 'Your first research project' tutorial - that is, you have a Nuvolos account and you can navigate the platform. You also need a handover from your colleague: an invitation email, an exported Docker image, or access to a snapshot in a project they have already shared with you. The colleague's published result (a number, a figure, a value in a paper or report) - you will need this to know whether reproduction succeeded.

1

Step 1 - Identify what kind of handover you have

Three handover formats are common on Nuvolos. The right first move depends on which one you got, so identify yours before doing anything else:

You received…	How you can tell	Skip to step
A Nuvolos invitation email	Subject line names a project; the email contains a Review Invitation button.	Step 2a
An exported Docker image (or a registry reference like docker.io/...)	Your colleague sent you a docker pull command, a Docker Hub URL, or a tar.gz archive.	Step 2b
Access to an existing project that already has a named snapshot	Your colleague says "restore the snapshot called v1.0 in the project I shared with you".	Step 2c

2

Step 2a - Restore the environment from a Nuvolos invitation

If your colleague invited you directly:

1. Open the invitation email and click Review Invitation.

2. Check the role: Instance Editor is the typical reviewer role and is what most authors will give you. It lets you run everything in the instance and modify it locally, without touching anything outside that one instance.

3. Sign in (or sign up) and accept the invitation.

4. From the Dashboard, navigate into the project. You should see one instance you have access to - that is the reviewer copy your colleague prepared.

Skip ahead to Step 3.

3

Step 2b - Restore the environment from a Docker export

If your colleague sent you a Docker image or registry reference, you are reproducing the work outside Nuvolos. The Application Export documentation covers the import procedure end-to-end; the steps below are the practical reproduction workflow.

1. Pull or load the image into your local Docker daemon (docker pull <reference> or docker load -i <archive>).

2. Run the container with the recommended command from your colleague (or the defaults documented in the export). Most exports run a JupyterLab or RStudio server you can open in a local browser.

3. Open the application in your browser at the URL the container prints to its log.

Continue to Step 3.

What's missing from a Docker export

By design, exports do not include: license-gated applications and the matching license environment variables (BYOL model - Nuvolos prevents accidental license leakage), and data stored in Nuvolos Tables. If the original analysis depended on either, your colleague should have either substituted a license-free alternative or exported the relevant Nuvolos Tables data to files (CSV or Parquet) before packaging. If you find one of these missing, that is what to ask them about first.

4

Step 2c - Restore from a named snapshot in a shared project

If your colleague has already given you access to their project:

1. From the Dashboard, navigate to the shared project. You should see at least one instance you can access.

2. Open the instance your colleague pointed you to. By default, you are looking at the Current state - but reproduction needs the historical state your colleague snapshotted.

3. Use the snapshot selector to switch from the Current state to the named snapshot your colleague identified (e.g. "v1.0 - final analysis 2026-05"). For details on snapshot navigation, see how snapshots and states work in Concepts.

You're in a read-only state

When you view a snapshot, you see the exact files and configuration as they were at snapshot time, but you cannot modify them. That is correct for the reproduction step - you want to run the original code unchanged. If you later want to extend the work, Step 5 covers how to branch off into your own writable instance.

5

Step 3 - Run the original analysis without changing anything

This is the moment of truth. Open the application your colleague used (the same JupyterLab, RStudio, Matlab, or whatever shows up in the application list - pre-configured with their package versions). Find their analysis script or notebook. Run it end-to-end without modification.

Resist the urge to refactor

If the code is messy or in a style you would never use yourself, leave it alone. Your only goal in this step is to confirm that running the colleague's exact code produces the colleague's exact result. Cleanup, refactoring, or extension comes after the reproduction is verified, in Step 5.

If the analysis writes results to files, the database, or a return value, capture each one. You will compare them against the published numbers in the next step.

6

Step 4 - Verify the result matches

Compare what you produced in Step 3 against your colleague's published result - the number in their paper, the figure they reported, the table in their methods section. There are three possible outcomes:

• Exact match: Numerical identity, byte-for-byte file equivalence. This is the strongest result and what well-prepared reproducibility packages aim for. Move to Step 5 (or stop here, if you only needed to confirm the result).

• Match within tolerance: Floating-point arithmetic, GPU non-determinism, or unseeded randomness can produce slightly different numbers between runs. If the difference is within reasonable tolerance for the analysis (often documented by the author), this still counts as successful reproduction.

• Mismatch: Numbers don't agree, or the script fails outright. Don't panic, the failure mode is usually informative. Common causes are listed below.

Common failure modes when reproduction fails

• Missing license: Errors like "License server not reachable" or "Feature not licensed" indicate a license-gated application that wasn't carried across. Most common with Matlab toolboxes, Stata, SAS, or commercial R packages. Ask your colleague which license configuration the original used.

• Missing tabular data: Errors mentioning database tables, NORTH_AMERICA_5_FACTORS-style names, or "table does not exist" indicate the analysis depended on Nuvolos Tables data that wasn't bundled with a Docker export. Snapshot- and invitation-based handovers preserve this; exports do not.

• Unseeded randomness: If the analysis involves random sampling, bootstrapping, or stochastic optimisation and the author didn't set a random seed, you will get different numbers every run. The result should still be statistically equivalent - check whether the author reported confidence intervals or ran multiple seeds.

• Package version drift: If the original was run with sklearn 1.2 and you're now running 1.5, behavior may have changed. Snapshot- and invitation-based handovers preserve exact versions. With an export, check the image's package versions match what the author reported.

• Path or filename mismatch: Hard-coded paths in the original code may not exist in your environment. Check the script for absolute paths and adjust if needed - but document any change you make.

Checkpoint

If you reached an exact match or a match within tolerance: the reproduction is verified. The colleague's claim holds, and you now have a working environment in which to extend the work. If reproduction failed for a reason on the list above, the next step is usually to go back to the author with a specific question ("which Matlab license?" / "do you have the random seed?") rather than to try fixing it yourself.

7

Step 5 - Branch off into your own instance to extend the work (optional)

Once reproduction is verified, you usually want to do something with the colleague's environment, like extend their model, try alternative parameters, run the analysis on your own data, build a follow-up paper. Doing this in their instance would mean modifying their work; doing it in your own personal Nuvolos project means losing their environment. The right answer is to branch.

If you have Space Administrator permission on the shared project, you can create your own writable copy of a colleague’s environment without modifying the original instance.

1. Open the shared project/space.

2. Click the Cogwheel icon to open project settings.

3. Navigate to Project Users / Instances.

4. Select + ADD NEW INSTANCE.

5. When prompted, choose the snapshot that you previously reproduced from. Complete the creation process.

A new instance will be created based on the selected snapshot. This gives you a fully writable copy of the environment while leaving the original instance unchanged.

For the complete workflow and additional details, see Create alternate instances.

If you only have Instance Editor access (the typical reviewer role), you can't create new instances. Two options: (a) ask your colleague to create one for you, or (b) take a snapshot of the current state in your own first Nuvolos research project, then distribute the files and applications across.

You're done

You have received a reproducible research package, restored the working environment, run the original analysis, verified the result, and (optionally) created a writable copy to build on top of.

Where to go next

• If you intend to publish work that builds on this reproduction, see the From notebook to reproducible result tutorial to learn how to produce your own reproducibility package.

• To compare alternative methods or parameters in parallel without disturbing your reproduced baseline, see How-to › Create alternate instances.

• If reproduction failed and you need to compare specific package versions or environment details, see How-to › Run analyses and applications for application configuration and How-to › GPU computation for GPU-specific considerations.