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: docs/docs/process-typed.mdx
+128-5Lines changed: 128 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,7 +54,7 @@ process fastqc {
54
54
55
55
script:
56
56
"""
57
-
echo 'meta: ${meta}`
57
+
echo 'meta: ${meta}'
58
58
echo 'fastq: ${fastq}'
59
59
echo 'extra_args: ${extra_args}'
60
60
"""
@@ -67,6 +67,8 @@ All [standard types][stdlib-types] except for the dataflow types (`Channel` and
67
67
68
68
Nextflow automatically stages `Path` inputs and `Path` collections (such as `Set<Path>`) into the task directory.
69
69
70
+
### Nullable inputs
71
+
70
72
By default, tasks fail if any input receives a `null` value. To allow `null` values, add `?` to the type annotation:
71
73
72
74
```nextflow
@@ -75,7 +77,7 @@ process cat_opt {
75
77
input: Path?
76
78
77
79
stage:
78
-
stageAs 'input.txt', input
80
+
stageAs input, 'input.txt'
79
81
80
82
output:
81
83
stdout()
@@ -87,10 +89,83 @@ process cat_opt {
87
89
}
88
90
```
89
91
90
-
### Stage directives
92
+
### Record inputs
93
+
94
+
Inputs with type `Record` can declare the name and type of each record field:
95
+
96
+
```nextflow
97
+
process fastqc {
98
+
input:
99
+
sample: Record {
100
+
id: String
101
+
fastq: Path
102
+
}
103
+
104
+
script:
105
+
"""
106
+
echo 'id: ${sample.id}'
107
+
echo 'fastq: ${sample.fastq}'
108
+
"""
109
+
}
110
+
```
111
+
112
+
In this example, the record is staged into the task as `sample`, and `sample.fastq` is staged as an input file since the `fastq` field is declared with type `Path`.
113
+
114
+
When the process is invoked, the incoming record should contain the specified fields, or else the run will fail. If the record has additional fields not declared by the process input, they are ignored.
115
+
116
+
:::tip
117
+
Record inputs are a useful way to select a subset of fields from a larger record. This way, the process only stages what it needs, allowing you to keep related data together in your workflow logic.
118
+
:::
119
+
120
+
You can achieve the same behavior using an external record type:
121
+
122
+
```nextflow
123
+
process fastqc {
124
+
input:
125
+
sample: Sample
126
+
127
+
script:
128
+
"""
129
+
echo 'id: ${sample.id}'
130
+
echo 'fastq: ${sample.fastq}'
131
+
"""
132
+
}
133
+
134
+
record Sample {
135
+
id: String
136
+
fastq: Path
137
+
}
138
+
```
139
+
140
+
This approach is useful when the record type can be re-used elsewhere in the pipeline.
141
+
142
+
### Tuple inputs
143
+
144
+
Inputs with type `Tuple` can declare the name of each tuple component:
145
+
146
+
```nextflow
147
+
process fastqc {
148
+
input:
149
+
(id, fastq): Tuple<String,Path>
150
+
151
+
script:
152
+
"""
153
+
echo 'id: ${id}'
154
+
echo 'fastq: ${fastq}'
155
+
"""
156
+
}
157
+
```
158
+
159
+
This pattern is called *tuple destructuring*. Each tuple component is staged into the task the same way as an individual input.
160
+
161
+
The generic types inside the `Tuple<...>` annotation specify the type of each tuple component and should match the component names. In the above example, `id` has type `String` and `fastq` has type `Path`.
162
+
163
+
## Stage directives
91
164
92
165
The `stage:` section defines custom staging behavior using *stage directives*. It should be specified after the `input:` section. These directives serve the same purpose as input qualifiers such as `env` and `stdin` in the legacy syntax.
93
166
167
+
### Environment variables
168
+
94
169
The `env` directive declares an environment variable in terms of task inputs:
95
170
96
171
```nextflow
@@ -108,6 +183,8 @@ process echo_env {
108
183
}
109
184
```
110
185
186
+
### Standard input (stdin)
187
+
111
188
The `stdin` directive defines the standard input of the task script:
112
189
113
190
```nextflow
@@ -125,6 +202,12 @@ process cat {
125
202
}
126
203
```
127
204
205
+
### Custom file staging
206
+
207
+
<ChangedInVersionversion="26.04.0" />
208
+
The method signature for `stageAs` was changed from `(filePattern, value)` to `(value, filePattern)`.
209
+
</ChangedInVersion>
210
+
128
211
The `stageAs` directive stages an input file (or files) under a custom file pattern:
129
212
130
213
```nextflow
@@ -133,7 +216,7 @@ process blast {
133
216
fasta: Path
134
217
135
218
stage:
136
-
stageAs 'query.fa', fasta
219
+
stageAs fasta, 'query.fa'
137
220
138
221
script:
139
222
"""
@@ -151,7 +234,7 @@ process grep {
151
234
fasta: Path
152
235
153
236
stage:
154
-
stageAs "${id}.fa", fasta
237
+
stageAs fasta, "${id}.fa"
155
238
156
239
script:
157
240
"""
@@ -224,6 +307,46 @@ process foo {
224
307
}
225
308
```
226
309
310
+
### Structured outputs
311
+
312
+
Whereas legacy process outputs could only be structured using specific qualifiers like `val` and `tuple`, typed process outputs are regular values.
313
+
314
+
The `record()` standard library function can be used to create a record:
315
+
316
+
```nextflow
317
+
process fastqc {
318
+
input:
319
+
sample: Record {
320
+
id: String
321
+
fastq: Path
322
+
}
323
+
324
+
output:
325
+
record(
326
+
id: sample.id,
327
+
fastqc: file('fastqc_logs')
328
+
)
329
+
330
+
script:
331
+
// ...
332
+
}
333
+
```
334
+
335
+
The `tuple()` standard library function can be used to create a tuple:
336
+
337
+
```nextflow
338
+
process fastqc {
339
+
input:
340
+
(id, fastq): Tuple<String,Path>
341
+
342
+
output:
343
+
tuple(id, file('fastqc_logs'))
344
+
345
+
script:
346
+
// ...
347
+
}
348
+
```
349
+
227
350
## Topics
228
351
229
352
The `topic:` section emits values to [topic channels][channel-topic]. A topic emission consists of an output value and a topic name:
The following operations are supported for records:
939
+
940
+
##### `+ : (Record, Record) -> Record`
941
+
942
+
Given two records, returns a new record containing the fields and values of both records. When a field is present in both records, the value of the right-hand record takes precedence.
0 commit comments