You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _episodes/13-expressions.md
+14-14Lines changed: 14 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -90,36 +90,36 @@ syntax is used to describe the additional command line arguments.
90
90
> Just like [parameter references]({{ page.root }}{% link _episodes/06-params.md %}), you can use JavaScript Expressions
91
91
> only in certain fields. These are:
92
92
>
93
-
> - From [`CommandLineTool`](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool)
93
+
> - From [`CommandLineTool`](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool)
94
94
> -`arguments`
95
95
> -`valueFrom`
96
96
> -`stdin`
97
97
> -`stdout`
98
98
> -`stderr`
99
-
> - From [CommandInputParameter](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandInputParameter)
99
+
> - From [CommandInputParameter](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandInputParameter)
100
100
> -`format`
101
101
> -`secondaryFiles`
102
-
> - From [`inputBinding`](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineBinding)
102
+
> - From [`inputBinding`](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineBinding)
103
103
> -`valueFrom`
104
-
> - From [CommandOutputParamater](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputParameter)
104
+
> - From [CommandOutputParamater](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputParameter)
105
105
> -`format`
106
106
> -`secondaryFiles`
107
-
> - From [CommandOutputBinding](http://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputBinding)
107
+
> - From [CommandOutputBinding](https://www.commonwl.org/v1.0/CommandLineTool.html#CommandOutputBinding)
108
108
> -`glob`
109
109
> -`outputEval`
110
110
> - From `Workflow`
111
-
> - From [InputParameter](http://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [WorkflowOutputParameter](http://www.commonwl.org/v1.0/Workflow.html#WorkflowOutputParameter)
111
+
> - From [InputParameter](https://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [WorkflowOutputParameter](https://www.commonwl.org/v1.0/Workflow.html#WorkflowOutputParameter)
112
112
> -`format`
113
113
> -`secondaryFiles`
114
114
> - From `steps`
115
-
> - From [WorkflowStepInput](http://www.commonwl.org/v1.0/Workflow.html#WorkflowStepInput)
115
+
> - From [WorkflowStepInput](https://www.commonwl.org/v1.0/Workflow.html#WorkflowStepInput)
116
116
> -`valueFrom`
117
117
> - From [ExpressionTool](https://www.commonwl.org/v1.0/Workflow.html#ExpressionTool)
118
118
> -`expression`
119
-
> - From [InputParameter](http://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [ExpressionToolOutputParameter](http://www.commonwl.org/v1.0/Workflow.html#ExpressionToolOutputParameter)
119
+
> - From [InputParameter](https://www.commonwl.org/v1.0/Workflow.html#InputParameter) and [ExpressionToolOutputParameter](https://www.commonwl.org/v1.0/Workflow.html#ExpressionToolOutputParameter)
120
120
> -`format`
121
121
> -`secondaryFiles`
122
-
> - From [`ResourceRequirement`](http://www.commonwl.org/v1.0/CommandLineTool.html#ResourceRequirement)
122
+
> - From [`ResourceRequirement`](https://www.commonwl.org/v1.0/CommandLineTool.html#ResourceRequirement)
123
123
> -`coresMin`
124
124
> -`coresMax`
125
125
> -`ramMin`
@@ -128,17 +128,17 @@ syntax is used to describe the additional command line arguments.
128
128
> -`tmpdirMax`
129
129
> -`outdirMin`
130
130
> -`outdirMax`
131
-
> - From [`InitialWorkDirRequirement`](http://www.commonwl.org/v1.0/CommandLineTool.html#InitialWorkDirRequirement)
131
+
> - From [`InitialWorkDirRequirement`](https://www.commonwl.org/v1.0/CommandLineTool.html#InitialWorkDirRequirement)
132
132
> -`listing`
133
-
> - in [Dirent](http://www.commonwl.org/v1.0/CommandLineTool.html#Dirent)
133
+
> - in [Dirent](https://www.commonwl.org/v1.0/CommandLineTool.html#Dirent)
134
134
> -`entry`
135
135
> -`entryname`
136
136
> - From `EnvVarRequirement`
137
-
> - From [EnvironmentDef](http://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef)
137
+
> - From [EnvironmentDef](https://www.commonwl.org/v1.0/CommandLineTool.html#EnvironmentDef)
Copy file name to clipboardExpand all lines: _extras/recommended-practices.md
+63-25Lines changed: 63 additions & 25 deletions
Original file line number
Diff line number
Diff line change
@@ -4,52 +4,91 @@ title: "Recommended Practices"
4
4
permalink: /rec-practices/
5
5
---
6
6
7
-
Below are a set of recommended good practices to keep in mind when writing a Common Workflow Language description for a tool or workflow. These guidelines are presented for consideration on a scale of usefulness: more is better, not all are required.
8
-
9
-
☐ No `type: string` parameters for names of input or reference files/directories; use `type: File` or `type: Directory` as appropriate.
10
-
11
-
☐ Include a license that allows for re-use by anyone, e.g. [Apache 2.0][apache-license]. If possible, the license should be specified with its corresponding [SPDX identifier][spdx]. Construct the metadata field for the licence by providing a URL of the form `https://spdx.org/licenses/[SPDX-ID]` where `SPDX-ID` is the taken from the list of identifiers linked above. See the example snippet below for guidance. For non-standard licenses without an SPDX identifier, provide a URL to the license.
7
+
Below are a set of recommended good practices to keep in mind when writing a
8
+
Common Workflow Language description for a tool or workflow. These guidelines
9
+
are presented for consideration on a scale of usefulness: more is better, not
10
+
all are required.
11
+
12
+
☐ No `type: string` parameters for names of input or reference
13
+
files/directories; use `type: File` or `type: Directory` as appropriate.
14
+
15
+
☐ Include a license that allows for re-use by anyone, e.g.
16
+
[Apache 2.0][apache-license]. If possible, the license should be specified with
17
+
its corresponding [SPDX identifier][spdx]. Construct the metadata field for the
18
+
licence by providing a URL of the form `https://spdx.org/licenses/[SPDX-ID]`
19
+
where `SPDX-ID` is the taken from the list of identifiers linked above. See the
20
+
example snippet below for guidance. For non-standard licenses without an SPDX
21
+
identifier, provide a URL to the license.
12
22
13
23
_Example of metadata field for license with SPDX identifier:_
14
24
~~~
15
25
$namespaces:
16
-
s: http://schema.org/
26
+
s: https://schema.org/
17
27
s:license: https://spdx.org/licenses/Apache-2.0
18
28
# other s: declarations
19
29
~~~
20
30
{: .source}
21
31
22
-
For more examples of providing metadata within CWL descriptions, see the [Metadata and Authorship section][metadata-lesson] of this User Guide.
32
+
For more examples of providing metadata within CWL descriptions, see the
33
+
[Metadata and Authorship section]({{ page.root }}{% link _episodes/17-metadata.md %})
34
+
of this User Guide.
23
35
24
-
☐ Include [attribution information][license-example] for the author(s) of the CWL tool or workflow description. Use unambiguous identifiers like [ORCID][orcid].
36
+
☐ Include [attribution information][license-example] for the author(s) of
37
+
the CWL tool or workflow description. Use unambiguous identifiers like
38
+
[ORCID][orcid].
25
39
26
-
☐ In tool descriptions, list dependencies using short name(s) under `SoftwareRequirement`.
40
+
☐ In tool descriptions, list dependencies using short name(s) under
41
+
`SoftwareRequirement`.
27
42
28
-
☐ Include [SciCrunch][scicrunch-issue] identifiers for dependencies in `https://identifiers.org/rrid/RRID:SCR_NNNNNN` format.
43
+
☐ Include [SciCrunch][scicrunch-issue] identifiers for dependencies in
☐ All `input` and `output` identifiers should reflect their conceptual identity. Use informative names like `unaligned_sequences`, `reference_genome`, `phylogeny`, or `aligned_sequences` instead of `foo_input`, `foo_file`, `result`, `input`, `output`, and so forth.
46
+
☐ All `input` and `output` identifiers should reflect their conceptual
47
+
identity. Use informative names like `unaligned_sequences`, `reference_genome`,
48
+
`phylogeny`, or `aligned_sequences` instead of `foo_input`, `foo_file`,
49
+
`result`, `input`, `output`, and so forth.
31
50
32
-
☐ In tool descriptions, include a list of version(s) of the tool that are known to work with this description under `SoftwareRequirement`.
51
+
☐ In tool descriptions, include a list of version(s) of the tool that are
52
+
known to work with this description under `SoftwareRequirement`.
33
53
34
-
☐`format` should be specified for all input and output `File`s. Bioinformatics tools should use format identifiers from [EDAM][edam-example]. See also `iana:text/plain`, `iana:text/tab-separated-values` with `$namespaces: { iana: "https://www.iana.org/assignments/media-types/" }`. [Full IANA media type list][iana-types] (also known as MIME types). For non-bioinformatics tools use or build an appropriate ontology/controlled vocabulary in the same way. Please edit this page to let us know about it.
54
+
☐`format` should be specified for all input and output `File`s.
55
+
Bioinformatics tools should use format identifiers from [EDAM][edam-example].
56
+
See also `iana:text/plain`, `iana:text/tab-separated-values` with
[Full IANA media type list][iana-types] (also known as MIME types). For
59
+
non-bioinformatics tools use or build an appropriate ontology/controlled
60
+
vocabulary in the same way. Please edit this page to let us know about it.
35
61
36
-
☐ Mark all input and output `File`s that are read from or written to in a streaming compatible way (only once, no random-access), as `streamable: true`.
62
+
☐ Mark all input and output `File`s that are read from or written to in a
63
+
streaming compatible way (only once, no random-access), as `streamable: true`.
37
64
38
-
☐ Each `CommandLineTool` description should focus on a single operation only, even if the (sub)command is capable of more. Don't overcomplicate your tool descriptions with options that you don't need/use.
65
+
☐ Each `CommandLineTool` description should focus on a single operation
66
+
only, even if the (sub)command is capable of more. Don't overcomplicate your
67
+
tool descriptions with options that you don't need/use.
39
68
40
-
☐ Custom types should be defined with one external YAML per type definition for re-use.
69
+
☐ Custom types should be defined with one external YAML per type
70
+
definition for re-use.
41
71
42
72
☐ Include a top level short `label` summarising the tool/workflow.
43
73
44
-
☐ If useful, include a top level `doc` as well. This should provide a longer, more detailed description than was provided in the top level `label` (see above).
74
+
☐ If useful, include a top level `doc` as well. This should provide a
75
+
longer, more detailed description than was provided in the top level `label`
76
+
(see above).
45
77
46
-
☐ Use `type: enum` instead of `type: string` for elements with a fixed list of valid values.
78
+
☐ Use `type: enum` instead of `type: string` for elements with a fixed
79
+
list of valid values.
47
80
48
-
☐ Evaluate all use of JavaScript for possible elimination or replacement. One common example: manipulating `File` names and paths? Consider whether one of the [built in `File` properties][file-prop] like `basename`, `nameroot`, `nameext`, etc, could be used instead.
81
+
☐ Evaluate all use of JavaScript for possible elimination or replacement.
82
+
One common example: manipulating `File` names and paths? Consider whether one
83
+
of the [built in `File` properties][file-prop] like `basename`, `nameroot`,
84
+
`nameext`, etc, could be used instead.
49
85
50
-
☐ Give the tool description to a colleague (preferably at a different institution) to test and provide feedback.
86
+
☐ Give the tool description to a colleague (preferably at a different
87
+
institution) to test and provide feedback.
51
88
52
-
☐ Complex workflows with individual components which can be abstracted should utilise the [`SubworkflowFeatureRequirement`][subworkflow] to make their workflow modular and allow sections of them to be easily reused.
89
+
☐ Complex workflows with individual components which can be abstracted
90
+
should utilise the [`SubworkflowFeatureRequirement`][subworkflow] to make their
91
+
workflow modular and allow sections of them to be easily reused.
53
92
54
93
☐ Software containers should be made to be conformant to the ["Recommendations for the packaging and containerizing of bioinformatics software"][containers] (also useful to other disciplines).
55
94
@@ -58,9 +97,8 @@ For more examples of providing metadata within CWL descriptions, see the [Metada
0 commit comments