Sharing workspaces as part of the publication process is a useful aspect of working in Terra. Publications and pre-prints can refer reviewers and/or peers to Terra-based resources, helping researchers to explore each other's methodologies in detail. This article describes the format for citing individual workflows and workspaces, as well as the versions of the Cromwell execution engine and the Workflow Description Language (WDL) used in your analysis on Terra.
Who can see your Terra workspace? You can share your workflow and workspace with any reviewer who has a Terra account. Once you are ready to publish your work, you can change the workspace permission to include individuals or groups with Terra access, or reach out to our support team to help make the workspace publicly readable. You can also think about featuring your workspace to make it easy for others to reproduce your analysis.
Dashboards of Featured workspaces are accessible to anyone, even if they do not have an account on Terra.
Citing workflows and workspaces
Citing a workspace or workflow makes it easier for reviewers to examine your data. You can cite an individual workflow or an entire workspace (workflows, Jupyter Notebooks, test data, dashboard info, etc.) as demonstrated below.
Citation format: Last Name, First Initial. (Year, Month Day that your workspace/method was last modified) name of your workspace/method [workspace or method] Retrieved Date from URL to workspace/method/method results
Citation example (workspaces)
Kovalsky, A. (2020, January 1) Somatic-CNVs-GATK4 copy_akovalsk 10_31_2019 [workspace] Retrieved October 31, 2019, https://app.terra.bio/#workspaces/help-gatk/Somatic-CNVs-GATK4%20copy_akovalsk%2010_31_2019
Citation example (workflows)
Shifaw, B. (2021, April 21) gatk/2-CNV_Somatic_Pair (Version 184.108.40.206) [Workflow] Retrieved April 22, 2021 from https://app.terra.bio/#workspaces/help-gatk/Somatic-CNVs-GATK4/workflows/help-gatk/2-CNV_Somatic_Pair
Where to find citation information
The citation information can be found in the workspace dashboard. In some instances, the original authors may have a section in the dashboard Markdown detailing all the people involved in the creation of the workspace. If that doesn't exist, use the owner's email listed on the right-hand panel of the Dashboard tab to contact the owners about the authors of the workspace. The right-hand panel also lists the date the workspace was last modified which can be used directly in your citation.
Dockstore supports researchers who want to publish citable workflows in different ways, such as creating snapshots and requesting DOIs. Researchers can become verified users and link their ORCID profiles to their Dockstore account, as described in this blog post.
If you wish to cite the Cromwell execution engine or the WDL themselves, as is the case when you are publishing analyses using one of the Broad Institute's workflows, please use the example below:
Voss K, Gentry J and Van der Auwera G.
Full-stack genomics pipelining with GATK4 + WDL + Cromwell [version 1; not peer reviewed].
F1000Research 2017, 6(ISCB Comm J):1379 (poster)
Citing the Terra platform
If you are simply looking for a way to cite the Terra platform as a whole, please cite the landing page as you would any website. We plan to write a manuscript about Terra; once that is published or posted as a pre-print, we will update this article with full citation information.