Publishing in KBase with Static Narratives

KBase allows you to perform powerful research on-system and share your work with the scientific community. One of the newest KBase features to help your research go further are Static Narratives. Static Narratives are snapshots of KBase’s reproducible analysis notebooks, called Narratives, that are visible to anyone on the internet, even without a KBase account. When you create a Static Narrative, KBase processes the steps in the workflow to all the cells in your Narrative and create a webpage that displays on markdown text, data analysis information, and data visualizations. The result is a sleek, fast loading webpage that allows everyone to view your analysis. And, as they are able to receive a digital object identifier (DOI) from KBase, Static Narratives are perfect as supplementary information to ensure reproducibility in a publication.

Furthermore, Static Narratives document a persistent record of your current workflow without limiting future analysis. As a copy of the original Narrative, a particular Static Narrative version will not be changed by changes to the underlying Narrative. Users can publish data and analysis, and then later expand the original Narrative. If the additional analysis proves publishable, then a new static Narrative version can be created to capture the changes. Afterwards, either the old version, the new version, or both can be shared freely.

Creating Static Narratives

To create a static Narrative, the underlying Narrative must first be made public. Then, a static Narrative can be created by clicking “Manage Static Narratives” and then “Create Static Narrative,” if one has not been created already, or “Create new static Narrative” if a static version already exists. 

Once the static Narrative is created, KBase can register it with the U.S. Department of Energy’s Office of Scientific and Technical Information (OSTI) to generate a “dataset” DOI for the Narrative. To request a DOI for your Narrative, contact us at engage@kbase.us and be sure to include a link to the public Narrative and/or Static Narrative.

When you have created a static Narrative and registered a DOI, the Narrative itself will be publicly visible by appearing as a DataCite record and indexed by Google. If you are submitting a publication, the Static Narrative is visible to reviewers and readers without the need for a KBase account, making your data more open and available. Because it is indexed by Google, it will also appear in search engines, making your data more easily findable and accessible. Finally, the DOI makes your data citable, allowing others to build upon your data and cite you in the process. 

Improving Static Narratives

Before creating a static Narrative, it’s important to recognize that the static Narrative will be essentially identical to the interactive Narrative. This allows users to add a wealth of information in the form of Markdown cells. There are three key concepts that should be considered when annotating Narratives: readability, explanation of the analysis, and additional context.

Readability

KBase’s markdown cells make it very easy to create an attractive and well-documented Narrative that is easy to read and follow. Markdown cells allow you to create rich content by combining different media formats using Markdown syntax, HTML, or LaTeX equations. One simple, yet powerful syntactic element is the <a> tag, which can be combined with lists or raw text to create an interactive table of contents, which allows readers to browse the Narrative quickly, as well as allowing the author to draw attention to specific parts of the Narrative. 

Sections of Narratives can be hyperlinked to a table of contents, as in this example from Dale Pelletier’s public Narrative (DOI: 10.25982/54100.27/1635639)

There are many reference guides available online for Markdown, HTML, or LaTeX syntax. You can also copy this Markdown cell “cheat sheet” Narrative to get templates of common formatting styles.

Explanation

When writing an explanation for a Narrative, it’s always beneficial to add plenty of information about the analysis to inform reviewers and readers about your analysis rationale, aiding in reproducibility. For example, explaining which analysis tools were used and why, the parameters chosen for an analysis, or more information explaining how the data were generated before importing into KBase.  

Explanation of the Narrative and background, from a Narrative by Andrew St. James (DOI:10.25982/51077.6/1637903)

Context

Likewise, it’s helpful to provide readers additional context for the Narrative. This could be a summary of the paper associated with the Narrative, figures or images that show how the data from the Narrative were used to support your conclusions, and more. In general, adding as much information as possible is a low-effort, high-reward way to enhance Narratives using text and images that can be taken directly from the paper or a publicly available image on the web.

Publicly accessible figures can be embedded, as with this figure (same Narrative as above) 

Implementing Static Narratives in KBase

KBase Developer Spotlight: Bill Riehl

The Lead Developer for implementing static Narratives is Bill Riehl. Bill has worked on the KBase project since 2012. As a developer, he has been working on managing data uploads and Narrative publishing. Bill’s favorite cookie is the classic chocolate chip.
What did Bill find exciting or challenging about this project?
(BR) It’s exciting to take a few steps toward having Narratives become static, freely visible documents. One day he would like to see an interactive repository of KBase Narratives that highlight reproducible biological analyses.

Future for publishing Narratives

Narrative publishing is still new in KBase. As such, there are many more features planned for future development. One key feature will be the ability to link ORCiD accounts to Narratives and automatically push the Narrative record to your ORCiD profile. If there are features you’d like to see as a reader or creator of static Narratives, please let us know. You can create a new feature request ticket at the Help Desk. If you want a Static Narrative DOI, contact us at engage@kbase.us.

Narratives referenced:

• Pelletier, Dale: Draft Genome Sequence of Larkinella sp. Strain BK230, Isolated from Populus deltoides Roots (DOI: 10.25982/54100.27/1635639)
• St. James, Andrew: Ecogenomics reveals community interactions in a long-term methanogenic bioreactor and a rapid switch to sulfate-reducing conditions (DOI: 10.25982/51077.6/1637903)