Skip to content

Commit 054c5c7

Browse files
mr-cmr-c
authored
Merge pull request #12 from tobyhodges/metadata_episode
annotation episodes
2 parents 626bdc7 + ae812fe commit 054c5c7

File tree

9 files changed

+275
-0
lines changed

9 files changed

+275
-0
lines changed

‎_episodes/16-file-formats.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: "File Formats"
3+
teaching: 10
4+
exercises: 0
5+
questions:
6+
- "How can I allow type-checking of input and output files?"
7+
objectives:
8+
- "Learn how to unambiguously specify the format of `File` objects."
9+
keypoints:
10+
- "You can document the expected format of input and output `File`s."
11+
- "Once your tool is mature, we recommend specifying formats by referencing
12+
existing ontologies e.g. EDAM."
13+
---
14+
Tools and workflows can take `File` types as input and produce them as output.
15+
We also recommend indicating the format for `File` types. This helps document
16+
for others how to use your tool while allowing you to do some simple
17+
type-checking when creating parameter files.
18+
19+
For file formats, we recommend referencing existing ontologies (like EDAM in
20+
our example), reference a local ontology for your institution, or do not add
21+
a file format initially for quick development before sharing your tool with
22+
others. You can browse existing file format listings for IANA [here][IANA] and
23+
for EDAM [here][EDAM].
24+
25+
Note that for added value `cwltool` can do some basic reasoning based on file
26+
formats and warn you if there seem to be some obvious mismatches.
27+
28+
*metadata_example.cwl*
29+
30+
```
31+
{% include cwl/metadata_example.cwl %}
32+
```
33+
34+
#### Sample Parameter Files
35+
36+
Below is an example of a parameter file for the example above. We encourage
37+
checking in working examples of parameter files for your tool. This allows
38+
others to quickly work with your tool, starting from a "known good"
39+
parameterization.
40+
41+
*sample.json*
42+
43+
```
44+
{% include cwl/sample.yml %}
45+
```
46+
47+
Now invoke `cwl-runner` with the tool wrapper and the input object on the
48+
command line:
49+
50+
```
51+
$ cwltool metadata_example.cwl sample.yml
52+
/usr/local/bin/cwltool 1.0.20161114152756
53+
Resolved 'metadata_example.cwl' to 'file:///media/large_volume/testing/cwl_tutorial2/metadata_example.cwl'
54+
[job metadata_example.cwl] /tmp/tmpNWyAd6$ /bin/sh \
55+
-c \
56+
'wc' '-l' '/tmp/tmpBf6m9u/stge293ac74-3d42-45c9-b506-dd35ea3e6eea/rna.SRR948778.bam' > /tmp/tmpNWyAd6/output.txt
57+
Final process status is success
58+
{
59+
"report": {
60+
"format": "http://edamontology.org/format_1964",
61+
"checksum": "sha1$49dc5004959ba9f1d07b8c00da9c46dd802cbe79",
62+
"basename": "output.txt",
63+
"location": "file:///media/large_volume/testing/cwl_tutorial2/output.txt",
64+
"path": "/media/large_volume/testing/cwl_tutorial2/output.txt",
65+
"class": "File",
66+
"size": 80
67+
}
68+
}
69+
```
70+
71+
[IANA]: https://www.iana.org/assignments/media-types/media-types.xhtml
72+
[EDAM]: http://www.ebi.ac.uk/ols/ontologies/edam/terms?iri=http%3A%2F%2Fedamontology.org%2Fformat_1915

‎_episodes/17-metadata.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "Metadata and Authorship"
3+
teaching: 10
4+
exercises: 0
5+
questions:
6+
- "How do I provide information for people to cite my tool descriptions?"
7+
objectives:
8+
- "Learn how to add authorship information and other metadata to a CWL
9+
description."
10+
keypoints:
11+
- "Metadata can be provided in CWL descriptions."
12+
- "Developers should provide a minimal amount of authorship information to
13+
encourage correct citation."
14+
---
15+
Implementation extensions not required for correct execution (for example,
16+
fields related to GUI presentation) and metadata about the tool or workflow
17+
itself (for example, authorship for use in citations) may be provided as
18+
additional fields on any object.
19+
Such extensions fields must use a namespace prefix listed in the `$namespaces`
20+
section of the document as described in the
21+
[Schema Salad specification][schema-salad].
22+
23+
For all developers, we recommend the following minimal metadata for your tool
24+
and workflows. This example includes metadata allowing others to cite your tool.
25+
26+
*metadata_example2.cwl*
27+
28+
```
29+
{% include cwl/metadata_example2.cwl %}
30+
```
31+
32+
#### Extended Example
33+
34+
For those that are highly motivated, it is also possible to annotate your tool
35+
with a much larger amount of metadata. This example includes EDAM ontology tags
36+
as keywords (allowing the grouping of related tools), hints at hardware
37+
requirements in order to use the tool, and a few more metadata fields.
38+
39+
*metadata_example3.cwl*
40+
41+
```
42+
{% include cwl/metadata_example3.cwl %}
43+
```
44+
45+
[schema-salad]: http://www.commonwl.org/v1.0/SchemaSalad.html#Explicit_context

‎_episodes/16-1st-workflow.md renamed to ‎_episodes/18-1st-workflow.md

File renamed without changes.

‎_episodes/17-nested-workflows.md renamed to ‎_episodes/19-nested-workflows.md

File renamed without changes.

‎_includes/cwl/file-formats.bam

44.5 MB
Binary file not shown.

‎_includes/cwl/metadata_example.cwl

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
#!/usr/bin/env cwl-runner
2+
3+
class: CommandLineTool
4+
id: Example tool
5+
label: Example tool
6+
cwlVersion: v1.0
7+
doc: |
8+
An example tool demonstrating metadata.
9+
10+
requirements:
11+
- class: ShellCommandRequirement
12+
13+
inputs:
14+
bam_input:
15+
type: File
16+
doc: The BAM file used as input
17+
format: edam:format_2572
18+
inputBinding:
19+
position: 1
20+
21+
stdout: output.txt
22+
23+
outputs:
24+
report:
25+
type: File
26+
format: edam:format_1964
27+
outputBinding:
28+
glob: "*.txt"
29+
doc: A text file that contains a line count
30+
31+
baseCommand: ["wc", "-l"]
32+
33+
$namespaces:
34+
edam: http://edamontology.org/

‎_includes/cwl/metadata_example2.cwl

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#!/usr/bin/env cwl-runner
2+
3+
class: CommandLineTool
4+
id: Example tool
5+
label: Example tool
6+
cwlVersion: v1.0
7+
doc: |
8+
An example tool demonstrating metadata. Note that this is an example and the metadata is not necessarily consistent.
9+
10+
requirements:
11+
- class: ShellCommandRequirement
12+
13+
inputs:
14+
bam_input:
15+
type: File
16+
doc: The BAM file used as input
17+
format: edam:format_2572
18+
inputBinding:
19+
position: 1
20+
21+
stdout: output.txt
22+
23+
outputs:
24+
report:
25+
type: File
26+
format: edam:format_1964
27+
outputBinding:
28+
glob: "*.txt"
29+
doc: A text file that contains a line count
30+
31+
baseCommand: ["wc", "-l"]
32+
33+
$namespaces:
34+
s: https://schema.org/
35+
edam: http://edamontology.org/
36+
37+
$schemas:
38+
- https://schema.org/docs/schema_org_rdfa.html
39+
40+
s:author:
41+
- class: s:Person
42+
s:id: https://orcid.org/0000-0002-6130-1021
43+
s:email: mailto:[email protected]
44+
s:name: Denis Yuen
45+
46+
s:contributor:
47+
- class: s:Person
48+
s:id: http://orcid.org/0000-0002-7681-6415
49+
s:email: mailto:[email protected]
50+
s:name: Brian O'Connor
51+
52+
s:citation: https://dx.doi.org/10.6084/m9.figshare.3115156.v2
53+
s:codeRepository: https://github.com/common-workflow-language/common-workflow-language
54+
s:dateCreated: "2016-12-13"
55+
s:license: https://www.apache.org/licenses/LICENSE-2.0

‎_includes/cwl/metadata_example3.cwl

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/usr/bin/env cwl-runner
2+
3+
class: CommandLineTool
4+
id: Example tool
5+
label: Example tool
6+
cwlVersion: v1.0
7+
doc: |
8+
An example tool demonstrating metadata. Note that this is an example and the metadata is not necessarily consistent.
9+
10+
requirements:
11+
- class: ShellCommandRequirement
12+
13+
hints:
14+
- class: ResourceRequirement
15+
coresMin: 4
16+
17+
inputs:
18+
bam_input:
19+
type: File
20+
doc: The BAM file used as input
21+
format: edam:format_2572
22+
inputBinding:
23+
position: 1
24+
25+
stdout: output.txt
26+
27+
outputs:
28+
report:
29+
type: File
30+
format: edam:format_1964
31+
outputBinding:
32+
glob: "*.txt"
33+
doc: A text file that contains a line count
34+
35+
baseCommand: ["wc", "-l"]
36+
37+
$namespaces:
38+
- s: https://schema.org/
39+
- edam: https://edamontology.org/
40+
41+
$schemas:
42+
- https://schema.org/docs/schema_org_rdfa.html
43+
44+
s:author:
45+
- class: s:Person
46+
s:id: https://orcid.org/0000-0002-6130-1021
47+
s:email: mailto:[email protected]
48+
s:name: Denis Yuen
49+
50+
s:contributor:
51+
- class: s:Person
52+
s:id: http://orcid.org/0000-0002-7681-6415
53+
s:email: mailto:[email protected]
54+
s:name: Brian O'Connor
55+
56+
s:citation: https://dx.doi.org/10.6084/m9.figshare.3115156.v2
57+
s:codeRepository: https://github.com/common-workflow-language/common-workflow-language
58+
s:dateCreated: "2016-12-13"
59+
s:license: https://www.apache.org/licenses/LICENSE-2.0
60+
61+
s:keywords: edam:topic_0091 , edam:topic_0622
62+
s:programmingLanguage: C

‎_includes/cwl/sample.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
bam_input:
2+
class: File
3+
format: http://edamontology.org/format_2572
4+
path: file-formats.bam
5+
bamstats_report:
6+
class: File
7+
path: /tmp/bamstats_report.zip

0 commit comments

Comments
 (0)