Chapter 2 Get started

cwlProcess is the main constructor function to wrap a command line tool into an R tool as a cwlProcess object (S4 class). Let’s start with a simple example to wrap the echo command and execute echo hello world in R.

First, we need to define the input parameter for the base command echo, here it is a string without a prefix. An id argument is required here.

input1 <- InputParam(id = "sth")

Second, we can construct a cwlProcess object by specifying the baseCommand for the command line tool, and InputParamList for the input parameters.

echo <- cwlProcess(baseCommand = "echo", inputs = InputParamList(input1))

Now we have converted the command line tool echo into an R tool: an R object of class cwlProcess with the name of echo. We can take a look at the this R object and use some utility functions to extract specific information.

echo

## class: cwlProcess 
##  cwlClass: CommandLineTool 
##  cwlVersion: v1.0 
##  baseCommand: echo 
## inputs:
##   sth (string):  
## outputs:
## output:
##   type: stdout

class(echo)

## [1] "cwlProcess"
## attr(,"package")
## [1] "Rcwl"

cwlClass(echo)

## [1] "CommandLineTool"

cwlVersion(echo)

## [1] "v1.0"

baseCommand(echo)

## [1] "echo"

inputs(echo)

## inputs:
##   sth (string):

outputs(echo)

## outputs:
## output:
##   type: stdout

The inputs(echo) will show the value once it is assigned in next step. Since we didn’t define the outputs for this tool, it will stream standard output to a temporary file by default.

The third step is to assign values (here is “Hello World!”) for the input parameters.

echo$sth <- "Hello World!"
inputs(echo)

## inputs:
##   sth (string):  Hello World!

Now this R version of command line tool echo is ready to be executed.

The function runCWL runs the tools in R and returns a list of: 1) actual command line that was executed, 2) filepath to the output, and 3) running logs. The output directory by default takes the working directory, but can be specified in outdir argument.

r1 <- runCWL(echo, outdir = tempdir())

## [1;30mINFO[0m Final process status is success

r1

## List of length 3
## names(3): command output logs

r1$command

## [1] "\033[1;30mINFO\033[0m [job echo.cwl] /private/tmp/docker_tmptw4l9_2r$ echo \\"                
## [2] "    'Hello World!' > /private/tmp/docker_tmptw4l9_2r/36a045913589936efd476118f8e7f986eb86e995"

readLines(r1$output)

## [1] "Hello World!"

r1$logs

##  [1] "\033[1;30mINFO\033[0m /Users/qi31566/Library/Python/3.7/bin/cwltool 3.0.20200324120055"                                                                                                                                   
##  [2] "\033[1;30mINFO\033[0m Resolved '/var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T//RtmptDExzb/file82097749d3b5/echo.cwl' to 'file:///var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T/RtmptDExzb/file82097749d3b5/echo.cwl'"
##  [3] "\033[1;30mINFO\033[0m [job echo.cwl] /private/tmp/docker_tmptw4l9_2r$ echo \\"                                                                                                                                            
##  [4] "    'Hello World!' > /private/tmp/docker_tmptw4l9_2r/36a045913589936efd476118f8e7f986eb86e995"                                                                                                                            
##  [5] "\033[1;30mINFO\033[0m [job echo.cwl] completed success"                                                                                                                                                                   
##  [6] "{"                                                                                                                                                                                                                        
##  [7] "    \"output\": {"                                                                                                                                                                                                        
##  [8] "        \"location\": \"file:///var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T/RtmptDExzb/36a045913589936efd476118f8e7f986eb86e995\","                                                                                   
##  [9] "        \"basename\": \"36a045913589936efd476118f8e7f986eb86e995\","                                                                                                                                                      
## [10] "        \"class\": \"File\","                                                                                                                                                                                             
## [11] "        \"checksum\": \"sha1$a0b65939670bc2c010f4d5d6a0b3e4e4590fb92b\","                                                                                                                                                 
## [12] "        \"size\": 13,"                                                                                                                                                                                                    
## [13] "        \"path\": \"/var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T/RtmptDExzb/36a045913589936efd476118f8e7f986eb86e995\""                                                                                               
## [14] "    }"                                                                                                                                                                                                                    
## [15] "}"                                                                                                                                                                                                                        
## [16] "\033[1;30mINFO\033[0m Final process status is success"

Users can also have the log printed out by specifying showLog = TRUE.

r1 <- runCWL(echo, outdir = tempdir(), showLog = TRUE)

## }

A utility function writeCWL converts the cwlProcess object into 2 files: a .cwl file for the command and .yml file for the inputs, which are the internal cwl files to be executed when runCWL is invoked. The internal execution requires a cwl-runner (e.g., cwltool), which will be installed automatically with runCWL.

writeCWL(echo)

##                                                                                   cwlout 
## "/var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T//RtmptDExzb/file82096fb8655b/echo.cwl" 
##                                                                                   ymlout 
## "/var/folders/7t/9l4kkf_j2sqbpn321y9g5558z96ck_/T//RtmptDExzb/file82096fb8655b/echo.yml"