Background: 

Many published capsules on Code Ocean present the results of a published or forthcoming journal article. Some capsules, however, present a suite of functions and/or datasets intended for general use (and some accompany journal articles that are primarily about a package). This tutorial walks through readying a software library for sharing or publication on Code Ocean.

First, start a new capsule, either from a blank slate or, if your package is hosted on GitHub or equivalent, from an existing repo

  • We generally recommend that you upload the source code for the package itself to the capsule rather than installing it via a package manager.
  • If your package features many datasets, we recommend moving them to the /data folder or adding them to a .gitignore

Second, after selecting the appropriate base environment, install all dependencies through the appropriate package managers or the postInstall script

Third, begin a new run  script. You can do so by either following the instructions here or by creating a new file in the /code directory called run

  •  We recommend that you begin your run  script with the shebang #!/usr/bin/env bash  and the set -ex  flag on lines 1 and 2. This will happen automatically if you hover over a file and select 'Set as File to Run'.

Fourth, if needed, write the needed commands to install the package locally. 

  • In Python, this will look something like pip install -v . ;
  • in R, something like Rscript -e "devtools::intstall() . (The specific flags you set, as well as any path-related details, will be unique to your capsule). 
  • Note: we recommend strongly (and require for publication) that your capsule not access any internet resources during runtime. All dependencies should already be installed through the environment, and any datasets should be uploaded to the capsule itself.

Fifth, if you have any sample scripts -- such as an .Rmd vignette or a representative Jupyter notebook  -- that walk users through how to use the included functions, you can add a line to the run script to execute it. 

  • For instance, if your R package includes a vignette, You can add Rscript -e "rmarkdown::render(input = 'awesome-vignette.Rmd', output_dir = '../results', clean = TRUE)"

Sixth, if you are intending to submit for publication, or for peer review, please review the criteria in Code Ocean's verification process for computational reproducibility and proceed when you are ready.

Published example:

See Topaz: positive-unlabeled convolutional neural networks for particle picking in
cryo-electron micrographs
.

Did this answer your question?