CWL metadata notes

.cwl/cwl-metadata-checklist.md

+
+# Checklist for good CWL documents
+
+based on recommendations from:
+
+- https://www.commonwl.org/user_guide/topics/best-practices.html
+- https://www.commonwl.org/user_guide/topics/metadata-and-authorship.html 
+
+- [Design](#design)
+  - [Single-step first](#single-step-first)
+- [Dependencies](#dependencies)
+  - [Soft requirements = `hints`](#soft-requirements--hints)
+  - [Hard requirements = `requirements`](#hard-requirements--requirements)
+- [Metadata](#metadata)
+  - [Namespaces and schemas](#namespaces-and-schemas)
+
+## Design
+
+### Keep it Simple: Single-step
+
+- follow the [KISS principle](https://en.wikipedia.org/wiki/KISS_principle)
+- a `CommandLineTool` document should only execute one process
+- use `Workflow` documents to design more complex, multi-step pipelines
+- use `scatter` to execute the process on multiple inputs
+- do not hard code input, output paths
+
+## Dependencies
+
+### Soft requirements = `hints`
+
+Specify software and resource requirements under `hints`
+
+- add `SoftwareRequirement` to specify software version and reference
+  - `package: ` name of the software or package
+  - `specs: ` reference url from https://identifiers.org/biotools/ or SciCrunch https://identifiers.org/rrid/
+  - `version: [ "0.11.9" ]`
+- add `DockerRequirement`
+  - reference a local `Dockerfile` or a published Docker image
+- add `ResourceRequirement` to specify the required compute resources
+
+### Hard requirements = `requirements`
+
+Use the `requirements` primarily to specify hard requirements needed to run the current `CommandLineTool` or `Workflow` document
+
+## Metadata
+
+### Namespaces and schemas
+
+Adding namespaces and schemas allows to reuse them elsewhere in a CWL document
+
+```yaml
+$namespaces:
+  s: https://schema.org/
+  edam: http://edamontology.org/
+
+$schemas:
+  - https://schema.org/version/latest/schemaorg-current-https.rdf
+  - http://edamontology.org/EDAM_1.18.owl
+```
+
+### Attribute authors and contributors
+
+```yaml
+s:author:
+  - class: s:Person
+    s:identifier: <author ORCID>
+    s:email: mailto:<author email>
+    s:name: <author name>
+
+s:contributor:
+  - class: s:Person
+    s:identifier: <contributor ORCID>
+    s:email: mailto:<contributor email>
+    s:name: <contributor name>
+
+s:citation: <DOI to software paper>
+s:codeRepository: <URL to software repo (e.g. github)>
+s:dateCreated: "2016-12-13"
+s:license: <URL to license, e.g. from https://spdx.org/licenses/> 
+```

workflows/fastqc/fastqc.cwl

@@ -19,10 +19,10 @@ hints:
     dockerPull: quay.io/biocontainers/fastqc:0.11.9--hdfd78af_1
   SoftwareRequirement:
     packages:
-      fastqc:
+      - package: fastqc
         specs: 
           - https://identifiers.org/biotools/fastqc
-          - - https://identifiers.org/rrid/RRID:SCR_014583
+          - https://identifiers.org/rrid/RRID:SCR_014583
         version: [ "0.11.9" ]
 
 baseCommand: "fastqc"
@@ -58,5 +58,3 @@ $schemas:
   - https://edamontology.org/EDAM_1.25.owl
 
 s:license: https://spdx.org/licenses/GPL-3.0-or-later
-
-

workflows/kallisto/kallisto-index.cwl

@@ -33,7 +33,7 @@ hints:
     dockerPull: quay.io/biocontainers/kallisto:0.51.1--ha4fb952_1
   SoftwareRequirement:
     packages:
-      kallisto:
+      - package: kallisto
         version: [ "0.51.1" ]
         specs:
           - https://identifiers.org/rrid/RRID:SCR_016582

workflows/kallisto/kallisto-quant.cwl

@@ -45,7 +45,7 @@ hints:
     dockerPull: quay.io/biocontainers/kallisto:0.51.1--ha4fb952_1
   SoftwareRequirement:
     packages:
-      kallisto:
+      - package: kallisto
         version: [ "0.51.1" ]
         specs: [ https://identifiers.org/biotools/kallisto ]