Operators

Nextflow操作符是一些方法，允许您将信道相互连接，或转换应用用户提供的某些规则的信道发出的值。

操作符可分为七组:

• Filtering operators
• Transforming operators
• Splitting operators
• Combining operators
• Forking operators
• Maths operators
• Other operators

Note
操作符set和subscribe是最终操作符，因此，如果使用它们，它们必须是组合操作符链中的最后一个操作符。

---

Combining operators

合并操作符有:

• join
• mix
• cross
• collectFile
• combine
• concat

join

连接操作符创建一个信道，该信道将存在匹配键的两个信道发出的项连接在一起。默认情况下，键被定义为发出的每个项中的第一个元素。

例如:

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

由此产生的信道发出:

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

可以使用by参数指定不同匹配元素的索引。

通过指定可选参数remainder, join操作符可以发出所有不完整的对，即缺少匹配元素的项，如下所示:

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

以下参数可以与连接操作符一起使用:

Name	Description
by	要用作分组键的元素的索引(基于零)。一个由多个元素组成的键可以定义为一个索引列表，例如:[0,2]
remainder	当错误的不完整元组(即小于大小的分组项)被丢弃时(默认)。当为真时，不完整元组作为结束触发
failOnDuplicate	当发现同一个键不止一次时，将报告错误
failOnMismatch	当信道发出的值在连接信道中没有对应的元素时，将报告错误。此选项不能与余数一起使用

cross

交叉操作符允许您组合两个信道的项，以便源信道的项与具有匹配键的目标信道发出的项一起发出。

默认情况下，键被定义为数组、列表或映射对象的第一个条目，或任何其他数据类型的值本身。例如:

source = Channel.from( [1, 'alpha'], [2, 'beta'] )
target = Channel.from( [1, 'x'], [1, 'y'], [1, 'z'], [2,'p'], [2,'q'], [2,'t'] )

source.cross(target).view()

[ [1, alpha], [1, x] ]
[ [1, alpha], [1, y] ]
[ [1, alpha], [1, z] ]
[ [2, beta],  [2, p] ]
[ [2, beta],  [2, q] ]
[ [2, beta],  [2, t] ]

上面的示例显示了源信道发出的项如何与目标信道(右侧)发出的项相关联，这些项具有相同的键。

在使用交叉操作符时，有两个重要的注意事项:

• 该运算符不是自反的，即a.cross(b)的结果不同于b.cross(a)
• 源信道应该发出没有键重复的项，即发出的项有唯一的键标识符。

collectFile

collectFile操作符允许您收集信道发出的项，并将它们保存到一个或多个文件中。该操作符返回一个发送收集的文件的新信道。

在最简单的情况下，只需指定必须存储条目的文件名称。例如:

Channel
    .from('alpha', 'beta', 'gamma')
    .collectFile(name: 'sample.txt', newLine: true)
    .subscribe {
        println "Entries are saved to file: $it"
        println "File content is: ${it.text}"
    }

collectFile操作符的第二个版本允许您收集由信道发出的项，并将它们分组到可由动态条件定义名称的文件中。分组条件由闭包指定，该闭包必须返回一对，其中第一个元素定义组的文件名，第二个元素定义要追加到该文件的实际值。例如:

Channel
   .from('Hola', 'Ciao', 'Hello', 'Bonjour', 'Halo')
   .collectFile() { item ->
       [ "${item[0]}.txt", item + '\n' ]
   }
   .subscribe {
       println "File ${it.name} contains:"
       println it.text
   }

File 'B.txt' contains:
Bonjour

File 'C.txt' contains:
Ciao

File 'H.txt' contains:
Halo
Hola
Hello

Tip
当源信道发出的项目是文件时，可以省略分组条件。 在这种情况下，项目内容将被分组到与源项目同名的文件中。

下面的参数可以与collectFile操作符一起使用:

Name	Description
cache	在使用resume特性时控制collectFile操作符的缓存能力。它遵循与cache指令相同的语义(默认值:true)
keepHeader	将在第一个收集的文件中获取的头文件添加到结果文件的前面。标题大小(例如。Lines)可以通过使用skip参数指定(默认值:false)，以确定从所有收集的文件中删除多少行，除了第一个(其中不删除任何行)
name	存储所有接收值的文件的名称
newLine	在每个条目之后自动附加一个换行符(默认:false)
seed	用于初始化文件内容的值或值的映射
skip	跳过前n行，跳过1行为skip:1
sort	定义结果文件中内容的排序标准。查看下面的排序选项
storeDir	存储生成文件的文件夹
tempDir	存放收集过程中使用的临时文件的文件夹

Note
文件内容以这样一种方式排序，它不依赖于添加的条目的顺序，这保证了它是一致的(即不改变)在不同的执行相同的数据。

文件内容的排序可以通过使用sort参数来定义。可指定以下条件:

Sort	Description
false	禁用内容排序。条目在生成时被追加。
true	按照条目的自然顺序排列内容，例如，用数字表示数字，用字典表示字符串，等等。参见http://docs.oracle.com/javase/tutorial/collections/interfaces/order.html
'index'	在收集时按分配给每个条目的增量索引号对内容进行排序
'hash'	按照与每个条目关联的哈希号对内容进行排序(默认)
'deep'	与前面的类似，但哈希值是在实际的条目内容上创建的，例如，当条目是一个文件时，哈希值是在实际的文件内容上创建的
cusotm	自定义排序标准可以通过使用Closure或Comparator对象来指定

例如，下面的代码片段显示了如何按字母顺序对结果文件的内容进行排序:

Channel
   .from('Z'..'A')
   .collectFile(name:'result', sort: true, newLine: true)
   .view { it.text }

A
B
C
:
Z

下面的例子展示了如何使用闭包来收集和排序FASTA文件中的所有序列，从最短到最长:

Channel
     .fromPath('/data/sequences.fa')
     .splitFasta( record: [id: true, sequence: true] )
     .collectFile( name:'result.fa', sort: { it.size() } )  {
        it.sequence
      }
     .view { it.text }

Warning
collectFile操作符需要将文件存储在临时文件夹中，该文件夹将在作业完成时自动删除。出于性能原因，此文件夹位于计算机的本地存储中，
它需要和你收集的数据一样多的空闲空间。也可以使用tempDir参数指定一个替代的临时数据文件夹。

combine

combine操作符将两个信道或一个信道和Collection对象(作为右操作数)发出的项(笛卡尔积)组合起来。例如:

numbers = Channel.from(1,2,3)
words = Channel.from('hello', 'ciao')
numbers
    .combine(words)
    .view()

# outputs
[1, hello]
[2, hello]
[3, hello]
[1, ciao]
[2, ciao]
[3, ciao]

组合操作符的第二个版本允许您在它们之间组合那些共享公共匹配键的项。通过使用by参数指定关键元素的索引(索引是从零开始的，可以用list一个整数指定多个索引)。例如:

left = Channel.from(['A',1], ['B',2], ['A',3])
right = Channel.from(['B','x'], ['B','y'], ['A','z'], ['A', 'w'])

left
    .combine(right, by: 0)
    .view()

# outputs
[A, 1, z]
[A, 3, z]
[A, 1, w]
[A, 3, w]
[B, 2, x]
[B, 2, y]

See also join, cross, spread and phase.

concat

concat操作符允许您将两个或多个信道发出的项连接到一个新信道，其方式是结果信道发出的项按照作为操作符参数指定时的顺序排列。

换句话说，它保证给定任意n个信道，连接信道只有在发出所有来自信道 i 的项之后才发出来自信道i+1的项。

a = Channel.from('a','b','c')
b = Channel.from(1,2,3)
c = Channel.from('p','q')

c.concat( b, a ).view()

p
q
1
2
3
a
b
c

---