4 title: "Processing Whole Genome Sequences"
7 Copyright (C) The Arvados Authors. All rights reserved.
9 SPDX-License-Identifier: CC-BY-SA-3.0
12 <div style="max-width: 600px; margin-left: 30px">
14 h2. 1. A Brief Introduction to Arvados
16 Arvados is an open source platform for managing, processing, and sharing genomic and other large scientific and biomedical data. Arvados helps bioinformaticians run and scale compute-intensive workflows. By running their workflows in Arvados, they can scale their calculations dynamically in the cloud, track methods and datasets, and easily re-run workflow steps or whole workflows when necessary. This tutorial walkthrough shows examples of running a “real-world” workflow and how to navigate and use the Arvados working environment.
18 When you log into your account on the Arvados playground ("https://playground.arvados.org":https://playground.arvados.org), you see the Arvados Workbench which is the web application that allows users to interactively access Arvados functionality. For this tutorial, we will largely focus on using the Arvados Workbench since that is an easy way to get started using Arvados. You can also access Arvados via your command line and/or using the available REST API and SDKs. If you are interested, this tutorial walkthrough will have an optional component that will cover using the command line.
20 By using the Arvados Workbench or using the command line, you can submit your workflows to run on your Arvados cluster. An Arvados cluster can be hosted in the cloud as well as on premise and on hybrid clusters. The Arvados playground cluster is currently hosted in the cloud.
22 You can also use the workbench or command line to access data in the Arvados storage system called Keep which is designed for managing and storing large collections of files on your Arvados cluster. The running of workflows is managed by Crunch. Crunch is designed to maintain data provenance and workflow reproducibility. Crunch automatically tracks data inputs and outputs through Keep and executes workflow processes in Docker containers. In a cloud environment, Crunch optimizes costs by scaling compute on demand.
24 _Ways to Learn More About Arvados_
25 * To learn more in general about Arvados, please visit the Arvados website here: "https://arvados.org/":https://arvados.org/
26 * For a deeper dive into Arvados, the Arvados documentation can be found here: "https://doc.arvados.org/":https://doc.arvados.org/
27 * For help on Arvados, visit the Gitter channel here: "https://gitter.im/arvados/community":https://gitter.im/arvados/community
30 h2. 2. A Brief Introduction to the Whole Genome Sequencing (WGS) Processing Tutorial
32 The workflow used in this tutorial walkthrough serves as a “real-world” workflow example that takes in WGS data (paired FASTQs) and returns GVCFs and accompanying variant reports. In this walkthrough, we will be processing approximately 10 public genomes made available by the Personal Genome Project. This set of data is from the PGP-UK ("https://www.personalgenomes.org.uk/":https://www.personalgenomes.org.uk/).
34 The overall steps in the workflow include:
35 * Check of FASTQ quality using FastQC ("https://www.bioinformatics.babraham.ac.uk/projects/fastqc/":https://www.bioinformatics.babraham.ac.uk/projects/fastqc/)
36 * Local alignment using BWA-MEM ("http://bio-bwa.sourceforge.net/bwa.shtml":http://bio-bwa.sourceforge.net/bwa.shtml)
37 * Variant calling in parallel using GATK Haplotype Caller ("https://gatk.broadinstitute.org/hc/en-us":https://gatk.broadinstitute.org/hc/en-us)
38 * Generation of an HTML report comparing variants against ClinVar archive ("https://www.ncbi.nlm.nih.gov/clinvar/":https://www.ncbi.nlm.nih.gov/clinvar/)
40 The workflow is written in "Common Workflow Language":https://commonwl.org (CWL), the primary way to develop and run workflows for Arvados.
42 Below are diagrams of the main workflow which runs the processing across multiple sets of fastq and the main subworkflow (run multiple times in parallel by the main workflow) which processes a single set of FASTQs. This main subworkflow also calls other additional subworkflows including subworkflows that perform variant calling using GATK in parallel by regions and generate the ClinVar HTML variant report. These CWL diagrams (generated using "CWL viewer":https://view.commonwl.org) will give you a basic idea of the flow, input/outputs and workflow steps involved in the tutorial example. However, if you aren’t used to looking at CWL workflow diagrams and/or aren’t particularly interested in this level of detail, do not worry. You will not need to know these particulars to run the workflow.
44 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image2.png!
45 <figcaption> _*Figure 1*: Main CWL Workflow for WGS Processing Tutorial. This runs the same WGS subworkflow over multiple pairs FASTQs files._ </figcaption> </figure>
47 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image3.png!
48 <figcaption> _*Figure 2*: Main subworkflow for the WGS Processing Tutorial. This subworkflow does alignment, deduplication, variant calling and reporting._ </figcaption> </figure>
50 _Ways to Learn More About CWL_
52 * The CWL website has lots of good content including the CWL User Guide: "https://www.commonwl.org/":https://www.commonwl.org/
53 * Commonly Asked Questions and Answers can be found in the Discourse Group, here: "https://cwl.discourse.group/":https://cwl.discourse.group/
54 * For help on CWL, visit the Gitter channel here: "https://gitter.im/common-workflow-language/common-workflow-language":https://gitter.im/common-workflow-language/common-workflow-language
55 * Repository of CWL CommandLineTool descriptions for commons tools in bioinformatics:
56 "https://github.com/common-workflow-library/bio-cwl-tools/":https://github.com/common-workflow-library/bio-cwl-tools/
59 h2. 3. Setting Up to Run the WGS Processing Workflow
61 Let’s get a little familiar with the Arvados Workbench while also setting up to run the WGS processing tutorial workflow. Logging into the workbench will present you with the front page. This gives a summary of your projects in your Arvados instance (i.e. the Arvados Playground) as well as a left hand side navigation bar, top search bar, and help, profile settings, and notifications on the top right. The front page will only give you information about projects and activities that you have permissions to view and/or access. Other users' private or restricted projects and activities will not be visible by design.
63 h3. 3a. Setting up a New Project
65 Projects in Arvados help you organize and track your work - and can contain data, workflow code, details about workflow runs, and results. Let’s begin by setting up a new project for the work you will be doing in this walkthrough.
67 To create a new project, go to the Projects dropdown menu and select the "+NEW" button, then select “New project”.
69 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image4.png!
70 <figcaption> _*Figure 3*: Adding a new project using Arvados Workbench, select the "+NEW" button in the upper left-hand corner and click "New project"._ </figcaption> </figure>
72 Let’s name your project “WGS Processing Tutorial”. You can also add a description of your project by typing in the **Description - optional** field. The universally unique identifier (UUID) of the project can be found in the URL, or by clicking the info button on the upper right-hand corner.
74 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image6.png!
75 <figcaption> _*Figure 4*: Renaming new project using Arvados Workbench, enter the name in the "Project Name" box._ </figcaption> </figure>
77 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image7.png!
78 <figcaption> _*Figure 5*: The UUID of the project can be found by selecting the "i" in the upper right-hand corner, under "UUID" and copied using the copy to clipboard option, highlighted in yellow in this image for emphasis._ </figcaption> </figure>
80 If you choose to use another name for your project, just keep in mind when the project name is referenced in the walkthrough later on.
82 h3. 3b. Working with Collections
84 Collections in Arvados help organize and manage your data. You can upload your existing data into a collection or reuse data from one or more existing collections. Collections allow us to reorganize our files without duplicating or physically moving the data, making them very efficient to use even when working with terabytes of data. Each collection has a universally unique identifier (collection UUID). This is a constant for this collection, even if we add or remove files -- or rename the collection. You use this if we want to to identify the most recent version of our collection to use in our workflows.
86 Arvados uses a content-addressable filesystem (i.e. Keep) where the addresses of files are derived from their contents. A major benefit of this is that Arvados can then verify that when a dataset is retrieved it is the dataset you requested and can track the exact datasets that were used for each of our previous calculations. This is what allows you to be certain that we are always working with the data that you think you are using. You use the portable data hash of a collection when you want to guarantee that you use the same version as input to your workflow.
88 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image1.png!
89 <figcaption> _*Figure 6*: A collection in Arvados as viewed via the Arvados Workbench. You will find a panel that contains: the name of the collection (this is editable, if you hit the three dots in the upper right-hand corner and click "Edit collection"), a description of the collection (also editable through the same way), the collection UUID, the portable data hash, content size, and some other information like version number._ </figcaption> </figure>
91 Let’s start working with collections by copying the existing collection that stores the FASTQ data being processed into our new “WGS Processing Tutorial” project.
93 First, you must find the collection you are interested in copying over to your project. There are several ways to search for a collection: by collection name, by UUID or by portable data hash. In this case, let’s search for our collection by name.
95 In this case it is called “PGP UK FASTQs (ten genomes)” and by searching for it in the “Search” box. It will come up and you can navigate to it. You would do similarly if you would want to search by UUID or portable data hash.
97 Now that you have found the collection of FASTQs you want to copy to your project, you can simply click the three dots in the right corner and click "Make a copy" and select your new project to copy the collection there. You can rename your collection whatever you wish, or use the default name on copy and add whatever description you would like.
101 We want to do the same thing for the other inputs to our WGS workflow. Similar to the “PGP UK FASTQs” collection there is a collection of inputs entitled “WGS Processing reference data” and that collection can be copied over in a similar fashion.
103 Now that we are a bit more familiar with the Arvados Workbench, projects and collections. Let’s move onto running a workflow.
105 h2. 4. Running the WGS Processing Workflow
107 In this section, we will be discussing three ways to run the tutorial workflow using Arvados. We will start using the easiest way and then progress to the more involved ways to run a workflow via the command line which will allow you more control over your inputs, workflow parameters and setup. Feel free to end your walkthrough after the first way or to pick and choose the ways that appeal the most to you, fit your experience and/or preferred way of working.
109 h3. 4a. Interactively Running a Workflow Using Workbench
111 Workflows can be registered in Arvados. Registration allows you to share a workflow with other Arvados users, and let’s them run the workflow by clicking the "+NEW" button and selecting "Run a workflow" on the Workbench Dashboard or on the command line by specifying the workflow UUID. Default values can be specified for workflow inputs.
113 We have already previously registered the WGS workflow and set default input values for this set of the walkthrough.
115 Let’s find the registered WGS Processing Workflow and run it interactively in our newly created project.
117 # To find the registered workflow, in the left-hand navigation bar, select "Public Favorites". That listing will include the "WGS Processing Workflow" project. Open that project, and it will include the workflow "WGS processing workflow scattered over samples". Open that workflow.
118 # Once you have found the registered workflow, you can run it your project by using the "Run Workflow" button and selecting your project ("WGS Processing Tutorial") that you set up in Section 3a, under *Project where the workflow will run*.
119 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image8.png!
120 <figcaption> _*Figure 7*: This is the page that pops up when you hit "Run Workflow", the input that needs selected is highlighted in yellow._ </figcaption> </figure>
121 # Default inputs to the registered workflow will be automatically filled in. These inputs will still work. You can verify this by checking the addresses of the collections you copied over to your new project.
122 # Now, you can submit your workflow by selecting the "Run Workflow" button.
124 Congratulations! You have now submitted your workflow to run. You can move to Section 5 to learn how to check the state of your submitted workflow and Section 6 to learn how to examine the results of and logs from your workflow.
126 Let’s now say instead of running a registered workflow you want to run a workflow using the command line. This is a completely optional step in the walkthrough. To do this, you can specify cwl files to define the workflow you want to run and the yml files to specify the inputs to our workflow. In this walkthrough we will give two options (4b) and (4c) for running the workflow on the commandline. Option 4b uses a virtual machine provided by Arvados made accessible via a browser that requires no additional setup. Option 4c allows you to submit from your personal machine but you must install necessary packages and edit configurations to allow you to submit to the Arvados cluster. Please choose whichever works best for you.
128 h3. 4b. Optional: Setting up to Run a Workflow Using Command Line and an Arvados Virtual Machine
130 Arvados provides a virtual machine which has all the necessary client-side libraries installed to submit to your Arvados cluster using the command line. Webshell gives you access to an Arvados Virtual Machine (VM) from your browser with no additional setup. You can access webshell through the Arvados Workbench. It is the easiest way to try out submitting a workflow to Arvados via the command line.
132 New users are playground are automatically given access to a shell account.
134 _Note_: the shell accounts are created on an interval and it may take up to two minutes from your initial log in before the shell account is created.
136 You can follow the instructions here to access the machine using the browser (also known as using webshell):
137 * "Accessing an Arvados VM with Webshell":{{ site.baseurl }}/user/getting_started/vm-login-with-webshell.html
139 Arvados also allows you to ssh into the shell machine and other hosted VMs instead of using the webshell capabilities. However this tutorial does not cover that option in-depth. If you like to explore it on your own, you can allow the instructions in the documentation here:
140 * "Accessing an Arvados VM with SSH - Unix Environments":{{ site.baseurl }}/user/getting_started/ssh-access-unix.html
141 * "Accessing an Arvados VM with SSH - Windows Environments":{{ site.baseurl }}/user/getting_started/ssh-access-windows.html
143 Once you can use webshell, you can proceed to section *“4d. Running a Workflow Using the Command Line”* .
145 h3. 4c. Optional: Setting up to Run a Workflow Using Command Line and Your Computer
147 Instead of using a virtual machine provided by Arvados, you can install the necessary libraries and configure your computer to be able to submit to your Arvados cluster directly. This is more of an advanced option and is for users who are comfortable installing software and libraries and configuring them on their machines.
149 To be able to submit workflows to the Arvados cluster, you will need to install the Python SDK on your machine. Additional features can be made available by installing additional libraries, but this is the bare minimum you need to install to do this walkthrough tutorial. You can follow the instructions in the Arvados documentment to install the Python SDK and set the appropriate configurations to access the Arvados Playground.
151 * "Installing the Arvados CWL Runner":{{ site.baseurl }}/sdk/python/arvados-cwl-runner.html
152 * "Setting Configurations to Access the Arvados Playground":{{ site.baseurl }}/user/reference/api-tokens.html
154 Once you have your machine set up to submit to the Arvados Playground Cluster, you can proceed to section *“4d. Running a Workflow Using the Command Line”* .
156 h3. 4d. Optional: Running a Workflow Using the Command Line
158 Now that we have access to a machine that can submit to the Arvados Playground, let’s download the relevant files containing the workflow description and inputs.
161 * Clone the tutorial repository from GitHub ("https://github.com/arvados/arvados-tutorial":https://github.com/arvados/arvados-tutorial)
162 * Change directories into the WGS tutorial folder
164 <pre><code>$ git clone https://github.com/arvados/arvados-tutorial.git
165 $ cd arvados-tutorial/WGS-processing
168 Recall that CWL is a way to describe command line tools and connect them together to create workflows. YML files can be used to specify input values into these individual command line tools or overarching workflows.
170 The tutorial directories are as follows:
171 * @cwl@ - contains CWL descriptions of workflows and command line tools for the tutorial
172 * @yml@ - contains YML files for inputs for the main workflow or to test subworkflows command line tools
173 * @src@ - contains any source code necessary for the tutorial
174 * @docker@ - contains dockerfiles necessary to re-create any needed docker images used in the tutorial
176 Before we run the WGS processing workflow, we want to adjust the inputs to match those in your new project. The workflow that we want to submit is described by the file @/cwl/@ and the inputs are given by the file @/yml/@. Note: while all the cwl files are needed to describe the full workflow only the single yml with the workflow inputs is needed to run the workflow. The additional yml files (in the helper folder) are provided for testing purposes or if one might want to test or run an underlying subworkflow or cwl for a command line tool by itself.
178 Several of the inputs in the yml file point to original portable data hashes of collections that you make copies of in our New Project. These still work because even though we made copies of the collections into our new project we haven’t changed the underlying contents. However, by changing this file is in general how you would alter the inputs in the accompanying yml file for a given workflow.
180 The command to submit to the Arvados Playground Cluster is @arvados-cwl-runner@.
181 To submit the WGS processing workflow , you need to run the following command replacing YOUR_PROJECT_UUID with the UUID of the new project you created for this tutorial.
183 <pre><code>$ arvados-cwl-runner --no-wait --project-uuid YOUR_PROJECT_UUID ./cwl/wgs-processing-wf.cwl ./yml/wgs-processing-wf.yml
186 The @--no-wait@ option will submit the workflow to Arvados, print out the UUID of the job that was submitted to standard output, and exit instead of waiting until the job is finished to return the command prompt.
188 The @--project-uuid@ option specifies the project you want the workflow to run in, that means the outputs and log collections as well as the workflow process will be saved in that project
190 If the workflow submitted successfully, you should see the following at the end of the output to the screen
192 <pre><code>INFO Final process status is success
195 Now, you are ready to check the state of your submitted workflow.
197 h2. 5. Checking the State Of a Submitted Workflow
199 Once you have submitted your workflow, you can examine its state interactively using the Arvados Workbench. If you aren’t already viewing your workflow process on the workbench, you can navigate there via your project. You will want to go back to your new project, using the projects pulldown menu (the list of projects on the left) or searching for the project name. Note: You can mark a project as a favorite (if/when you have multiple projects) to make it easier to find on the pulldown menu by right-clicking on the project name on the project pulldown menu and selecting "Add to favorites".
201 The process you will be looking for will be titled “WGS processing workflow scattered over samples” (if you submitted via the command line/Workbench).
203 Once you have found your workflow, you can clearly see the state of the overall workflow and underlying steps below by their label.
205 Common states you will see are as follows:
207 * "Queued" - Workflow or step is waiting to run
208 * "Running" or "Active"- Workflow is currently running
209 * "Complete" - Workflow or step has successfully completed
210 * "Failing"- Workflow is running but has steps that have failed
211 * "Failed"- Workflow or step did not complete successfully
212 * "Cancelled" - Workflow or step was either manually cancelled or was canceled by Arvados due to a system error
214 Since Arvados Crunch reuses steps and workflows if possible, this workflow should run relatively quickly since this workflow has been run before and you have access to those previously run steps. You may notice an initial period where the top level job shows the option of canceling while the other steps are filled in with already finished steps.
216 h2. 6. Examining a Finished Workflow
218 Once your workflow has finished, you can see how long it took the workflow to run, see scaling information, and examine the logs and outputs. Outputs will be only available for steps that have been successfully completed. Outputs will be saved for every step in the workflow and be saved for the workflow itself. Outputs are saved in collections. You can access each collection by clicking on the link corresponding to the output.
220 <figure> !{width: 100%}{{ site.baseurl }}/images/wgs-tutorial/image5.png!
221 <figcaption> _*Figure 8*: A completed workflow process in Arvados as viewed via the Arvados Workbench. You can click on the outputs link (highlighted in yellow) to view the outputs. Outputs of a workflow are stored in a collection._ </figcaption> </figure>
223 If we click on the outputs of the workflow, we will see the output collection. It contains the GVCF, tabix index file, and HTML ClinVar report for each analyzed sample (e.g., set of FASTQs). You can open a report in the browser by selecting it from the listing. You can also download a file to your local machine by right-clicking a file and selecting "Download" from the context menu, or from the action menu available from the far right of each listing.
225 Logs for the main process can be found back on the workflow process page. Selecting the "LOGS" button at the top navigates down to the logs. You can view the logs directly through that panel, or in the upper right-hand corner select the button with hover-over text "Go to Log collection".
227 There are several logs available, so here is a basic summary of what some of the more commonly used logs contain. Let's first define a few terms that will help us understand what the logs are tracking.
229 As you may recall, Arvados Crunch manages the running of workflows. A _container request_ is an order sent to Arvados Crunch to perform some computational work. Crunch fulfils a request by either choosing a worker node to execute a container, or finding an identical/equivalent container that has already run. You can use _container request_ or _container_ to distinguish between a work order that is submitted to be run and a work order that is actually running or has been run. So our container request in this case is just the submitted workflow we sent to the Arvados cluster.
231 A _node_ is a compute resource where Arvardos can schedule work. In our case since the Arvados Playground is running on a cloud, our nodes are virtual machines. @arvados-cwl-runner@ (acr) executes CWL workflows by submitting the individual parts to Arvados as containers and crunch-run is an internal component that runs on nodes and executes containers.
234 ** Captures everything written to standard error by the programs run by the executing container
235 * @node-info.txt@ and @node.json@
236 ** Contains information about the nodes that executed this container. For the Arvados Playground, this gives information about the virtual machine instance that ran the container.
237 node.json gives a high level overview about the instance such as name, price, and RAM while node-info.txt gives more detailed information about the virtual machine (e.g., CPU of each processor)
238 * @crunch-run.txt@ and @crunchstat.txt@
239 ** @crunch-run.txt@ has info about how the container's execution environment was set up (e.g., time spent loading the docker image) and timing/results of copying output data to Keep (if applicable)
240 ** @crunchstat.txt@ has info about resource consumption (RAM, cpu, disk, network) by the container while it was running.
241 * @usage_report.html@ can be viewed directly in the browser by clicking on it. It provides a summary and chart of the resource consumption derived from the raw data in @crunchstat.txt@. (Available starting with @arvados-cwl-runner@ 2.7.2).
243 ** Describes the container (unit of work to be done), contains CWL code, runtime constraints (RAM, vcpus) amongst other details
245 ** Contains information using Arvados Keep on the node executing the container
247 ** Contains about resource consumption (RAM, cpu, disk, network) on the node while it was running
248 This is different from the log crunchstat.txt because it includes resource consumption of Arvados components that run on the node outside the container such as crunch-run and other processes related to the Keep file system.
250 For the highest level logs, the logs are tracking the container that ran the @arvados-cwl-runner@ process which you can think of as the “workflow runner”. It tracks which parts of the CWL workflow need to be run when, which have been run already, what order they need to be run, which can be run simultaneously, and so forth and then creates the necessary container requests. Each step has its own logs related to containers running a CWL step of the workflow including a log of standard error that contains the standard error of the code run in that CWL step. Those logs can be found by expanding the steps and clicking on the link to the log collection.
252 Let’s take a peek at a few of these logs to get you more familiar with them. First, we can look at the @stderr.txt@ of the highest level process. Again recall this should be of the “workflow runner” @arvados-cwl-runner@ process. You can click on the log to download it to your local machine, and when you look at the contents - you should see something like the following...
254 <pre><code>2020-06-22T20:30:04.737703197Z INFO /usr/bin/arvados-cwl-runner 2.0.3, arvados-python-client 2.0.3, cwltool 1.0.20190831161204
255 2020-06-22T20:30:04.743250012Z INFO Resolved '/var/lib/cwl/workflow.json#main' to 'file:///var/lib/cwl/workflow.json#main'
256 2020-06-22T20:30:20.749884298Z INFO Using empty collection d41d8cd98f00b204e9800998ecf8427e+0
257 [removing some log contents here for brevity]
258 2020-06-22T20:30:35.629783939Z INFO Running inside container su92l-dz642-uaqhoebfh91zsfd
259 2020-06-22T20:30:35.741778080Z INFO [workflow WGS processing workflow] start
260 2020-06-22T20:30:35.741778080Z INFO [workflow WGS processing workflow] starting step getfastq
261 2020-06-22T20:30:35.741778080Z INFO [step getfastq] start
262 2020-06-22T20:30:36.085839313Z INFO [step getfastq] completed success
263 2020-06-22T20:30:36.212789670Z INFO [workflow WGS processing workflow] starting step bwamem-gatk-report
264 2020-06-22T20:30:36.213545871Z INFO [step bwamem-gatk-report] start
265 2020-06-22T20:30:36.234224197Z INFO [workflow bwamem-gatk-report] start
266 2020-06-22T20:30:36.234892498Z INFO [workflow bwamem-gatk-report] starting step fastqc
267 2020-06-22T20:30:36.235154798Z INFO [step fastqc] start
268 2020-06-22T20:30:36.237328201Z INFO Using empty collection d41d8cd98f00b204e9800998ecf8427e+0
271 You can see the output of all the work that arvados-cwl-runner does by managing the execution of the CWL workflow and all the underlying steps and subworkflows.
273 Now, let’s explore the logs for a subprocess in the workflow. Start by navigating back to the workflow process page. The logs can be found by selecting the appropriate subprocess under the "Subprocesses" tab, and getting the logs in the way as mentioned above. Let’s look at the log for the subprocess that does the alignment. That subprocess is named bwamem-samtools-view. We can see there are 10 of them because we are aligning 10 genomes. Let’s look at *bwamem-samtools-view_2.*
275 We click on the subprocess to open it and then can go down to the "Logs" section to access the logs. You may notice there are two sets of seemingly identical logs. One listed under a directory named for a container and one up in the main directory. This is done in case your subprocess had to be automatically re-run due to any issues and gives the logs of each re-run. The logs in the main directory are the logs for the successful run. In most cases this does not happen, you will just see one directory and one those logs will match the logs in the main directory. Let’s open the logs labeled node-info.txt and stderr.txt.
277 @node-info.txt@ gives us information about detailed information about the virtual machine this step was run on. The tail end of the log should look like the following:
279 <pre><code>Memory Information
280 MemTotal: 64465820 kB
282 MemAvailable: 62590172 kB
288 Active(anon): 873716 kB
289 Inactive(anon): 8444 kB
290 Active(file): 197152 kB
291 Inactive(file): 1305804 kB
302 SReclaimable: 106580 kB
303 SUnreclaim: 145264 kB
309 CommitLimit: 32232908 kB
310 Committed_AS: 2076668 kB
311 VmallocTotal: 34359738367 kB
315 AnonHugePages: 743424 kB
322 Hugepagesize: 2048 kB
324 DirectMap4k: 155620 kB
325 DirectMap2M: 6703104 kB
326 DirectMap1G: 58720256 kB
329 Filesystem 1M-blocks Used Available Use% Mounted on
330 /dev/nvme1n1p1 7874 1678 5778 23% /
331 /dev/mapper/tmp 381746 1496 380251 1% /tmp
334 Filesystem Inodes IUsed IFree IUse% Mounted on
335 /dev/nvme1n1p1 516096 42253 473843 9% /
336 /dev/mapper/tmp 195549184 44418 195504766 1% /tmp
339 We can see all the details of the virtual machine used for this step, including that it has 16 cores and 64 GIB of RAM.
341 @stderr.txt@ gives us everything written to standard error by the programs run in this step. This step ran successfully so we don’t need to use this to debug our step currently. We are just taking a look for practice.
343 The tail end of our log should be similar to the following:
345 <pre><code>2020-08-04T04:37:19.674225566Z [main] CMD: /bwa-0.7.17/bwa mem -M -t 16 -R @RG\tID:sample\tSM:sample\tLB:sample\tPL:ILLUMINA\tPU:sample1 -c 250 /keep/18657d75efb4afd31a14bb204d073239+13611/GRCh38_no_alt_plus_hs38d1_analysis_set.fna /keep/a146a06222f9a66b7d141e078fc67660+376237/ERR2122554_1.fastq.gz /keep/a146a06222f9a66b7d141e078fc67660+376237/ERR2122554_2.fastq.gz
346 2020-08-04T04:37:19.674225566Z [main] Real time: 35859.344 sec; CPU: 553120.701 sec
349 This is the command we ran to invoke bwa-mem, and the scaling information for running bwa-mem multi-threaded across 16 cores (15.4x).
351 You can also view outputs for the subprocess just like you do for the main workflow process. Back on the subprocess page for *bwamem-samtools-view_2*, the Outputs pane shows the output files of this specific subprocess. In this case, it is a single BAM file. This way, if your workflow succeeds but produces a surprising result, you can download and review the intermediate outputs to investigate further.
353 We hope that now that you have a bit more familiarity with the logs you can continue to use them to debug and optimize your own workflows as you move forward with using Arvados if your own work in the future.
357 Thank you for working through this walkthrough tutorial. Hopefully this tutorial has helped you get a feel for working with Arvados. This tutorial just covered the basic capabilities of Arvados. There are many more capabilities to explore. Please see the links featured at the end of Section 1 for ways to learn more about Arvados or get help while you are working with Arvados.
359 If you would like help setting up your own production instance of Arvados, please contact us at "info@curii.com.":mailto:info@curii.com
projects / arvados.git / blob