Blog

Submitting Reproducible Code for Peer Review in Gigantum

Posted by The Gigantum Team on May 18, 2020 4:18:42 PM

This post is a high-level overview for using Gigantum to submit reproducible code in support of a manuscript under peer review.

What is Gigantum?

Gigantum makes it easy for researchers and data scientists to share reproducible work. It supports work in Jupyter, JupyterLab and RStudio, and it can easily be run on laptops and remote machines. You can learn more about it in our docs.

The platform has two components, the Gigantum Client and Gigantum Hub. The open source Gigantum Client is a work environment that automates the management, versioning and containerization of workflows. It is self-service and can be run on laptops or remote instances, but it can also be used directly in Gigantum Hub, which is a cloud service that provides storage and publishing of versioned code and data. The Hub provides easy backup and collaboration, as well as a an open portal for publicly published Projects.

Submitting Code for Peer Review

Using Gigantum to submit code for peer review has three basic steps:

  1. Create an account and import your work into a Gigantum Project
  2. Make sure the code runs and that your work satisfies Quality Assurance (QA) requirements
  3. Submit to the Editor.

Step 1 is the same regardless of the trial but step 2 varies depending on the QA requirements of the particular journal. Step 3 requires that you store the Project on Gigantum Hub, but the final submission process will vary according to the journal. 

Importing Your Code Into Gigantum

Gigantum supports both Jupyter and RStudio, but for simplicity this post only deals with Jupyter notebooks. The steps for working in RStudio are similar. Gigantum also supports R in Jupyter.

Create an account and log in

Creating an account can be done exactly as shown in the following instructions, whether you are using Gigantum Hub, a Client installed locally, or a Client installed on a remote instance:

  1. Go to the login page.
  2. Click the “Sign Up” tab on the “Log in” widget.
  3. Enter an email, choose a username and password, and click the “>” button.

Create a Project and configure the environment

Once you’ve created an account and logged in, the application will open on the Overview page. To begin importing your work, you first need to create a new Project.

From the Overview page, create a Project as follows.

  1. Click “Create New” on the Add Project card
  2. Name the Project and click "Continue"
  3. Scroll down to select a base

Once the selected base has built, you can further specify the software environment in a variety of ways:

  1. Use the the package manager to install packages via pip, conda or apt.
  2. Click the tab to add a Requirements file, and then drag and drop a requirements.txt file
  3. Click the Advanced configuration settings drop-down to use Docker commands to build the environment.

For more information on setting up environments, including using Docker commands, see our docs.

Import and configure code and data

For better organization and transparency, you should put code into the Code tab and input data files into the Input Data tab. 

To upload files and start an execution environment, do the following:

  • Select Add Files in the appropriate tab (Code or Input Data).
  • Use the file browser to upload files.
  • Then click “Launch: jupyterlab”, and a new tab will open to a functioning Jupyter instance. If that doesn't work, then you may have a popup blocker onHere is how to fix that.

Once Jupyter is running, you can configure the code and data to work within the Project, making sure  the file paths reflect the Project directory structure. The main directory is /mnt/labbook, and it contains three sub-directories, code, input, and output. These directories correspond to the “Code” and “Input Data” and “Output Data” tabs in the UI.

Relative paths are the easiest way to make sure file paths are correct. For example, to load data from the /mnt/labbok/input directory for code running in the /mnt/labbook/code directory, you can use the relative path ../input/<input-file-name> for access. Relative paths also make it easy to write files to the output directory from the code directory using the relative path ../output/<output-file-name>.

Once file paths are configured, you can run your notebooks as you normally do, and if it runs for you then it will run the same for your reviewer!

You may want to ask a colleague to run through your project to make sure you haven't made any assumptions or missed any details that are unclear before engaging in the journal's formal QA process.

The QA Process

If you can run your code with no errors, then you should be close to passing whatever QA process the journal requires, but to verify that you’ve satisfied QA please consult the journal's guidelines.

You can add a Readme to the Project Overview tab to give reviewers and eventual readers more instructions about what is in the Project, how it relates to your manuscript, and how to explore the code. You can enter markdown directly there.

Submitting Your Code

Once your work passes QA, then you are ready to submit your code. The exact submissions steps depend on the journal and the Editor's preference, so please follow their guidelines for the process. However, regardless of the exact submission process, you will need to store your work on Gigantum Hub and get a Project URL to give provide the Editor and Reviewers access to your work. You can see more about how to store your work in Gigantum Hub in our docs

Once your Project is on Gigantum Hub, you can get a URL from the Actions menu. You should include the URL to your Project on Gigantum Hub when you submit your code for review.

Questions?

This was a brief overview of the process necessary to submit code for review in Gigantum. If you want to see a video that goes through the basic steps outlined above using RStudio, go here.

You can also check out other user-friendly features not featured in this post:

Learn more about Gigantum in our docs or on Medium. You can also email us at hello@gigantum.com and follow us on Twitter at @gigantumscience.

Topics: Science, Reproducibility, Open Science