added file formats episode

Author: Toby Hodges

_episodes/16-file-formats.md

@@ -0,0 +1,68 @@
+---
+title: "File Formats"
+teaching: 10
+exercises: 0
+questions:
+- "How can I allow type-checking of input and output files?"
+objectives:
+- "Learn how to unambiguously specify the format of `File` objects."
+keypoints:
+- "You can document the expected format of input and output `File`s."
+- "Once your tool is mature, we recommend specifying formats by referencing
+existing ontologies e.g. EDAM."
+---
+Tools and workflows can take `File` types as input and produce them as output.
+We also recommend indicating the format for `File` types. This helps document
+for others how to use your tool while allowing you to do some simple
+type-checking when creating parameter files.
+
+For file formats, we recommend referencing existing ontologies (like EDAM in
+our example), reference a local ontology for your institution, or do not add
+a file format initially for quick development before sharing your tool with
+others.
+
+Note that for added value `cwltool` can do some basic reasoning based on file
+formats and warn you if there seem to be some obvious mismatches.
+
+*metadata_example.cwl*
+
+```
+{% include cwl/metadata_example.cwl %}
+```
+
+#### Sample Parameter Files
+
+Below is an example of a parameter file for the example above. We encourage
+checking in working examples of parameter files for your tool. This allows
+others to quickly work with your tool, starting from a "known good"
+parameterization.
+
+*sample.json*
+
+```
+{% include cwl/sample.json %}
+```
+
+Now invoke `cwl-runner` with the tool wrapper and the input object on the
+command line:
+
+```
+$ cwltool metadata_example.cwl sample.json
+/usr/local/bin/cwltool 1.0.20161114152756
+Resolved 'metadata_example.cwl' to 'file:///media/large_volume/testing/cwl_tutorial2/metadata_example.cwl'
+[job metadata_example.cwl] /tmp/tmpNWyAd6$ /bin/sh \
+    -c \
+    'wc' '-l' '/tmp/tmpBf6m9u/stge293ac74-3d42-45c9-b506-dd35ea3e6eea/rna.SRR948778.bam' > /tmp/tmpNWyAd6/output.txt
+Final process status is success
+{
+  "report": {
+    "format": "http://edamontology.org/format_1964",
+    "checksum": "sha1$49dc5004959ba9f1d07b8c00da9c46dd802cbe79",
+    "basename": "output.txt",
+    "location": "file:///media/large_volume/testing/cwl_tutorial2/output.txt",
+    "path": "/media/large_volume/testing/cwl_tutorial2/output.txt",
+    "class": "File",
+    "size": 80
+  }
+}
+```

_episodes/16-metadata.md renamed to _episodes/17-metadata.md

@@ -0,0 +1,35 @@
+#!/usr/bin/env cwl-runner
+
+class: CommandLineTool
+id: Example tool
+label: Example tool
+cwlVersion: v1.0
+doc: |
+    An example tool demonstrating metadata.
+
+requirements:
+  - class: ShellCommandRequirement
+
+inputs:
+  bam_input:
+    type: File
+    doc: The BAM file used as input
+    format: http://edamontology.org/format_2572
+    inputBinding:
+      position: 1
+
+stdout: output.txt
+
+outputs:
+  report:
+    type: File
+    format: http://edamontology.org/format_1964
+    outputBinding:
+      glob: "*.txt"
+    doc: A text file that contains a line count
+
+baseCommand: ["wc", "-l"]
+
+$schemas:
+- http://dublincore.org/2012/06/14/dcterms.rdf
+- http://xmlns.com/foaf/spec/20140114.rdf

_includes/cwl/metadata_example.cwl

@@ -0,0 +1,11 @@
+{
+  "bam_input": {
+        "class": "File",
+	"format": "http://edamontology.org/format_2572",
+        "path": "rna.SRR948778.bam"
+    },
+    "bamstats_report": {
+        "class": "File",
+        "path": "/tmp/bamstats_report.zip"
+    }
+}