👋 This guide is under active development. Please feel free to contribute using the link at the bottom of the page!
Stemming from a longstanding legacy of print, the primary outputs of today’s research publishing workflows are based around PDF and plain HTML. These formats strip out much of the underlying richness from research findings that increasingly rely on the use of code and data.
Stencila has partnered with eLife, a leading publisher that aims to improve research communication through open science and open technology innovation.
The new, open-source, and web-native Executable Research Article (ERA) publication format allows you to embed code and data natively, in a fully reproducible document that is designed to help transparency, collaboration, training, and reproducibility.
The enrichment process will consist of:
- Using Stencila Hub to fetch the published article XML
- Using Stencila Hub to convert the article XML back to the format you used to author the article for submission.
- Replacing the static figures in the article with Code Chunks
- Uploading the enriched article and supporting assets to a Stencila project
This guide assumes that you are already signed in to Stencila, and have set up a new project for your eLife article. If you haven't signed up yet, see the creating an account and creating a project guides to get started.
There is an interactive version of this guide if you'd rather follow along on the Hub.
This guide uses the following eLife article as an example: Lewis, L. Michelle, et al. "Replication Study: Transcriptional amplification in tumor cells with elevated c-Myc." eLife 2018;7:e30274 DOI: 10.7554/eLife.30274.
Files vs Sources: Pulling in the content of the original article from the eLife website
An important concept to be aware of is that of linked (file) sources. In addition to uploading files to a project, you can link to sources that are hosted elsewhere, such as public websites and GitHub. These sources remain on the external service, but a versioned copy is downloaded and stored with your project to maintain reproducibility. You can go to the sources tab and update the local copies of your source files by pulling them periodically.
For this guide, we will be linking to the published version of the article. This will allow you to save the article in one of several formats so that you can replace the static tables and figures with reproducible code chunks.
Converting article to another format for editing
Now that you have a link to the published version of your article, you can decide which format you will use to transform it into a reproducible article. See the available formats by clicking the Actions menu, represented by the vertical ellipsis "...".
There are two primary pathways for enriching an article:
- Save the article as a Google Doc and use the Stencila plugin for Google Docs to replace static tables and figures with reproducible versions
- Save the article as a Jupyter Notebook or R Markdown document, download it, and edit it locally. (See further notes below).
Click on your desired format to begin the conversion process. The conversion process can take some time. In the background, Stencila Encoda needs to do several things:
- Search the eLife article Github repository to get the most recent version number
- Download the XML of the article from that repository
- Download images for each of the figures in the article
- Convert the XML and images to Google Docs format and upload the file to Google.
Don’t worry if the Save button spins for some time after you press it. When the conversion is complete, you’ll have a new entry in the project’s list of files:
Create an editable manuscript to publish
If you use editable formats such as R Studio or Jupyter Notebooks and you've successsfully converted the article into your chosen format, your next step is to download the file to your computer:
The next step is to find the static figures in the article and replace them with Code Chunks. This will make your manuscript executable.
If you have questions please don't hesitate to reach out to us via the chat widget on our website or emailing us at firstname.lastname@example.org