2.8. Custom Types

Sometimes you may want to write your own custom types for use and reuse in CWL descriptions. Use of such custom types can reduce redundancy between multiple descriptions that all use the same type, and also allow for additional customisation/configuration of a tool/analysis without the need to fiddle with the CWL description directly.

The example below is a CWL description of the biom convert format tool for converting a standard biom table file to hdf5 format.

custom-types.cwl

#!/usr/bin/env cwl-runner
cwlVersion: v1.2
class: CommandLineTool

requirements:
  InlineJavascriptRequirement: {}
  ResourceRequirement:
    coresMax: 1
    ramMin: 100  # just a default, could be lowered
  SchemaDefRequirement:
    types:
      - $import: biom-convert-table.yaml

hints:
  DockerRequirement:
    dockerPull: 'quay.io/biocontainers/biom-format:2.1.15'
  SoftwareRequirement:
    packages:
      biom-format:
        specs: [ "https://doi.org/10.1186/2047-217X-1-7" ]
        version: [ "2.1.15" ]

inputs:
  biom:
    type: File
    format: edam:format_3746  # BIOM
    inputBinding:
      prefix: --input-fp
  table_type:
    type: biom-convert-table.yaml#table_type
    inputBinding:
      prefix: --table-type

  header_key:
    type: string?
    doc: |
      The observation metadata to include from the input BIOM table file when
      creating a tsv table file. By default no observation metadata will be
      included.
    inputBinding:
      prefix: --header-key

baseCommand: [ biom, convert ]

arguments:
  - valueFrom: $(inputs.biom.nameroot).hdf5
    prefix: --output-fp
  - --to-hdf5

outputs:
  result:
    type: File
    outputBinding: { glob: "$(inputs.biom.nameroot)*" }

$namespaces:
  edam: http://edamontology.org/
  s: https://schema.org/

$schemas:
  - http://edamontology.org/EDAM_1.16.owl
  - https://schema.org/version/latest/schemaorg-current-http.rdf

s:license: https://spdx.org/licenses/Apache-2.0
s:copyrightHolder: "EMBL - European Bioinformatics Institute"

custom-types.yml

biom:
    class: File
    format: http://edamontology.org/format_3746
    path: rich_sparse_otu_table.biom
table_type: OTU table

Note: To follow the example below, you need to download the example input file, rich_sparse_otu_table.biom e.g. via wget:

$ wget https://github.com/common-workflow-language/user_guide/raw/main/src/_includes/cwl/custom-types/rich_sparse_otu_table.biom

On line 29, in inputs:table_type, a list of allowable table options to be used in the table conversion are imported as a custom object:

inputs:
  biom:
    type: File
    format: edam:format_3746  # BIOM
    inputBinding:
      prefix: --input-fp
  table_type:
    type: biom-convert-table.yaml#table_type
    inputBinding:
      prefix: --table-type

The reference to a custom type is a combination of the name of the file in which the object is defined (biom-convert-table.yaml) and the name of the object within that file (table_type) that defines the custom type. In this case the symbols array from the imported biom-convert-table.yaml file define the allowable table options. For example, in custom-types.yml, we pass OTU table as an input that tells the tool to create an OTU table in hdf5 format.

The contents of the YAML file describing the custom type are given below:

biom-convert-table.yaml

type: enum
name: table_type
label: The type of the table to produce
symbols:
  - OTU table
  - Pathway table
  - Function table
  - Ortholog table
  - Gene table
  - Metabolite table
  - Taxon table
  - Table

In order for the custom type to be used in the CWL description, it must be imported. Imports are described in requirements:SchemaDefRequirement, as below in the example custom-types.cwl description:

requirements:
  InlineJavascriptRequirement: {}
  ResourceRequirement:
    coresMax: 1
    ramMin: 100
  SchemaDefRequirement:
    types:
      - $import: biom-convert-table.yaml

Note also that the author of this CWL description has also included ResourceRequirements, specifying the minimum amount of RAM and number of cores required for the tool to run successfully, as well as details of the version of the software that the description was written for and other useful metadata. These features are discussed further in other chapters of this user guide.