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.
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
/datafolder or adding them to a .gitignore.
Second, after selecting the appropriate base environment, install dependencies required by your package through the appropriate package managers or the postInstall script. (You can make sure dependencies are not downloaded in runtime by checking the Download Data performance metric from the chevron menu on the latest run results.)
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
We recommend that you begin your
runscript with the shebang
#!/usr/bin/env bashand the
set -exflag 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::install(). (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.