User Guide¶
This user guide assumes you have at least some basic knowledge about CWL.
Note
Here is a CWL user guide for an introduction to tool and workflows wrappers.
The aim is to help you through the different steps to build your CWL tool with python-cwlgen.
Note
If you find a bug, have any questions or suggestions, please submit an issue on Github.
Basic example¶
Through this little tutorial, we will go step by step through the example you can find on Github. It aims to wrap the grep command.
Initialize your tool¶
You need to initialize a CommandLineTool object
import cwlgen
cwl_tool = cwlgen.CommandLineTool(tool_id='grep',
label='print lines matching a pattern',
base_command='grep')
Now that you have your object, you can attach the different elements of a tool description.
Add Inputs¶
Now we need to add inputs to our tool. We are going to only wrap a simple version of the grep command with a input file and a pattern.
First the input file:
file_binding = cwlgen.CommandLineBinding(position=2)
input_file = cwlgen.CommandInputParameter('input_file',
param_type='File',
input_binding=file_binding,
doc='input file from which you want to look for the pattern')
cwl_tool.inputs.append(input_file)
And finally the pattern:
pattern_binding = cwlgen.CommandLineBinding(position=1)
pattern = cwlgen.CommandInputParameter('pattern',
param_type='string',
input_binding=pattern_binding,
doc='pattern to find in the input file')
cwl_tool.inputs.append(pattern)
Note
You can specify more information concerning your inputs: Input documentation
This is it for the inputs, now let’s add some outputs and the description will be ready to be tested.
Add an Output¶
The only output which is retrieved in our example is a File with the line containing the pattern. Here is how to add this output:
output = cwlgen.CommandOutputParameter('output',
param_type='stdout',
doc='lines found with the pattern')
cwl_tool.outputs.append(output)
# Now specify a name for your output file
cwl_tool.stdout = "grep.txt"
Add Documentation and Metadata¶
You can ask bunch of information and metadata concerning your tool. For instance you can add some documentation:
cwl_tool.doc = "grep searches for a pattern in a file."
For the metadata:
metadata = {'name': 'grep',
'about' : 'grep searches for a pattern in a file.'}
cwl_tool.metadata = cwlgen.Metadata(**metadata)
Write your tool¶
Finally, you can export your tool description with the export() method.
cwl_tool.export() # On STDOUT
cwl_tool.export(outfile="grep.cwl") # As a file (grep.cwl)
You can then try your tool description (using cwltool for instance):
cwltool grep.cwl --input_file underdog_lyrics.txt --pattern lost