7. Operators¶

Operators are methods that allow you to connect channels, transform values emitted by a channel, or apply some user-provided rules.

There are seven main groups of operators are described in greater detail within the Nextflow Reference Documentation, linked below:

1. Filtering operators
2. Transforming operators
3. Splitting operators
4. Combining operators
5. Forking operators
6. Maths operators
7. Other operators

7.1 Basic example¶

1
2
3

nums = Channel.of(1, 2, 3, 4) // (1)!
square = nums.map { it -> it * it } // (2)!
square.view() // (3)!

1. Creates a queue channel emitting four values
2. Creates a new channel, transforming each number into its square
3. Prints the channel content

Operators can also be chained to implement custom behaviors, so the previous snippet can also be written as:

1
2
3
4

Channel
    .of(1, 2, 3, 4)
    .map { it -> it * it }
    .view()

7.2 Basic operators¶

Here we explore some of the most commonly used operators.

7.2.1 view()¶

The view operator prints the items emitted by a channel to the console standard output, appending a new line character to each item. For example:

1
2
3

Channel
    .of('foo', 'bar', 'baz')
    .view()

foo
bar
baz

An optional closure parameter can be specified to customize how items are printed. For example:

1
2
3

Channel
    .of('foo', 'bar', 'baz')
    .view { "- $it" }

- foo
- bar
- baz

7.2.2 map()¶

The map operator applies a function of your choosing to every item emitted by a channel and returns the items obtained as a new channel. The function applied is called the mapping function and is expressed with a closure as shown in the example below:

1
2
3
4

Channel
    .of('hello', 'world')
    .map { it -> it.reverse() }
    .view()

A map can associate a generic tuple to each element and can contain any data.

1
2
3
4

Channel
    .of('hello', 'world')
    .map { word -> [word, word.size()] }
    .view { word, len -> "$word contains $len letters" }

1
2
3
4

Channel
    .fromPath('data/ggal/*.fq')
    .map { file -> [file.name, file] }
    .view { name, file -> "> $name : $file" }

7.2.3 mix()¶

The mix operator combines the items emitted by two (or more) channels into a single channel.

1
2
3
4
5
6
7

my_channel_1 = Channel.of(1, 2, 3)
my_channel_2 = Channel.of('a', 'b')
my_channel_3 = Channel.of('z')

my_channel_1
    .mix(my_channel_2, my_channel_3)
    .view()

1
2
a
3
b
z

7.2.4 flatten()¶

The flatten operator transforms a channel in such a way that every tuple is flattened so that each entry is emitted as a sole element by the resulting channel.

1
2
3
4
5
6
7

foo = [1, 2, 3]
bar = [4, 5, 6]

Channel
    .of(foo, bar)
    .flatten()
    .view()

1
2
3
4
5
6

7.2.5 collect()¶

The collect operator collects all of the items emitted by a channel in a list and returns the object as a sole emission.

1
2
3
4

Channel
    .of(1, 2, 3, 4)
    .collect()
    .view()

It prints a single value:

[1, 2, 3, 4]

7.2.6 groupTuple()¶

The groupTuple operator collects tuples (or lists) of values emitted by the source channel, grouping the elements that share the same key. Finally, it emits a new tuple object for each distinct key collected.

Try the following example:

1
2
3
4

Channel
    .of([1, 'A'], [1, 'B'], [2, 'C'], [3, 'B'], [1, 'C'], [2, 'A'], [3, 'D'])
    .groupTuple()
    .view()

[1, [A, B, C]]
[2, [C, A]]
[3, [B, D]]

This operator is useful to process a group together with all the elements that share a common property or grouping key.

1
2
3
4
5

Channel
    .fromPath('data/meta/*')
    .map { file -> tuple(file.baseName, file) }
    .groupTuple()
    .view { baseName, file -> "> $baseName : $file" }

7.2.7 join()¶

The join operator creates a channel that joins together the items emitted by two channels with a matching key. The key is defined, by default, as the first element in each item emitted.

1
2
3

left = Channel.of(['X', 1], ['Y', 2], ['Z', 3], ['P', 7])
right = Channel.of(['Z', 6], ['Y', 5], ['X', 4])
left.join(right).view()

[Z, 3, 6]
[Y, 2, 5]
[X, 1, 4]

7.2.8 branch()¶

The branch operator allows you to forward the items emitted by a source channel to one or more output channels.

The selection criterion is defined by specifying a closure that provides one or more boolean expressions, each of which is identified by a unique label. For the first expression that evaluates to a true value, the item is bound to a named channel as the label identifier. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Channel
    .of(1, 2, 3, 40, 50)
    .branch {
        small: it < 10
        large: it > 10
    }
    .set { result }

result.small.view { "$it is small" }
result.large.view { "$it is large" }

7.3 More resources¶

Check the operators documentation on Nextflow web site.