为QIIME 2开发新插件

Developing a QIIME 2 plugin

https://docs.qiime2.org/2020.11/plugins/developing/

注意：本文档还处于正在完善中，仅并作为创建QIIME 2插件的基本说明。您也可以在https://dev.qiime2.org 上找到一些非常初步的开发人员文档。

创建QIIME 2插件可让您向QIIME 2用户提供微生物组分析功能。插件可以是一个独立的软件项目，也可以在现有软件项目中添加少量内容以使其成为QIIME 2插件。创建单个QIIME 2插件可以让用户通过任何QIIME 2界面（包括QIIME 2 Studio，q2cli和Artifact API）访问您的功能。

概述Overview

创建QIIME 2插件有几个高级步骤：

• 一个QIIME 2插件必须定义一个或多个可以通过QIIME访问的Python 3函数。该插件必须是可通过setuptools进行安装的Python 3软件包。

• 插件必须实例化一个qiime2.plugin.Plugin对象并定义一些信息，包括插件名称及其URL。在插件包的setup.py文件中，此实例将被定义为接口。

• 然后，该插件必须将其功能注册为QIIME 2 Actions，用户可以通过任何QIIME 2界面访问它。

• 该插件应通过Anaconda分发，以便简化QIIME 2用户的安装过程。不过本步骤只是可选项。

这些步骤将在下面详细介绍。

编写简单的QIIME 2插件是一个简单的过程。例如，将Emperor连接到QIIME 2 的q2-emperor插件仅用大约100行代码编写。它是一个独立的插件，定义了如何通过QIIME 2访问Emperor中的功能以及应使用哪些功能。插件的复杂度会有所不同。例如，定义很多新功能的插件可能会更大一些。q2-diversity就是一个很好的例子。与q2-emperor不同，在此项目中定义了一些特定的功能（以及相关的单元测试），它依赖于其他几个Python 3兼容的包。

在开始编写插件之前，您应该安装QIIME 2和一些插件以熟悉系统并提供测试插件的方法。

插件组件Plugin components

以下讨论将以q2-diversity插件为例。当您定义自己的QIIME 2插件时，该插件可以作为参考。

注意：QIIME 2对插件包的结构没有限制。然而，q2-diversity插件很好地代表了许多初始QIIME 2插件中的约定。这个包结构只是开发自己的插件的建议和起点，你可以随时根据需要或期望进行个性化设计包。

定义功能Define functionality

QIIME 2用户将以QIIME 2的身份访问您的功能动作(Actions)。这些Actions可以是Methods或Visualizers。一个Method是一个操作，它将Artifacts和Parameters结合作为输入，并产生一个或多个对象(Artifacts)作为输出。这些输出Artifacts随后可以用作其他QIIME 2 Methods或Visualizers的输入。一个Visualizer是也是一个操作，它结合Artifacts和Parameters作为输入，并精确地产生一个Visualization作为输出。Visualizations根据定义，输出不能用作其他QIIME 2 Methods或Visualizers的输入。因此Methods可以在QIIME分析中产生中间或最终输出，而Visualizers只能创建最终输出。

本节将描述如何定义Python 3函数（功能），它可以转换为QIIME 2的 Methods或Visualizers。这些函数可以在项目的任何位置定义。QIIME对插件包的结构没有限制。

创建一个函数并注册为方法 Create a function to register as a Method

可以被注册为Method的函数将具有Python 3 API，并且该函数的输入和输出将使用mypy语义类型进行注释。尽管这个语义类型对Python 3来说是新功能，mypy注释不会影响其功能，因此可以将其添加到Python 3软件项目中的现有功能中。一个示例是q2_diversity.beta_phylogenetic，它以biom.Table，skbio.TreeNode和str作为输入，并产生一个skbio.DistanceMatrixas作为输出。该函数的签名是：

def beta_phylogenetic(table: biom.Table, phylogeny: skbio.TreeNode,                      metric: str)-> skbio.DistanceMatrix:

就QIIME而言，只要它遵守关于输入和输出类型签名所定义的约定，此函数内部发生什么无关紧要。例如，q2_diversity.beta_phylogenetic正在对skbio和biom API 进行一些调用，但是它可能会做任何事情，包括进行系统调用（如果您的插件包装了命令行应用程序），执行R包等。

创建一个可视化函数 Create a function to register as a Visualizer

定义一个可以注册为Visualizer的函数过程与定义并注册Method非常相似，但前者还有一些其他要求。

首先，此函数的第一个参数必须为output_dir。此参数应使用str注释。

接下来，该至少有一个index.*文件被写入output_dir。这个索引文件将为你的用户提供探索Visualization的起点，这个Visualization是由Visualizer产生的。不同扩展名的索引文件可以通过函数来创建（例如index.html，index.tsv，index.png），但至少有一个必须创建。您可以编写任何想要的文件到output_dir中，包括表，图形和结果的文本描述。你的用户可以通过索引找到这些文件。如果您的函数确实创建了许多不同的文件，则包含指向这些文件链的接index.html可能会有所帮助。

最后，该函数无法返回任何内容，其返回类型应注释为None。

举个例子，q2_diversity.alpha_group_significance就是可以被注册为Visualizer的范例。除了output_dir以外，在pandas.Series含有α多样性结果，在qiime2.Metadata中含有样本Metadata，而且还产生几个不同的文件（图和表），这些文件链接于和/或呈现在index.html文件中。该函数的签名是：

def alpha_group_significance(output_dir: str, alpha_diversity: pd.Series,
                             metadata: qiime2.Metadata) -> None:

开发插件的实例Instantiating a plugin

下一步用实例来说明QIIME 2插件的开发过程。这个步骤看起来像下面这个样子：

from qiime2.plugin import Plugin
import q2_diversity

plugin = Plugin(
    name='diversity',
    version=q2_diversity.__version__,
    website='https://qiime2.org',
    user_support_text='https://forum.qiime2.org',
    package='q2_diversity'
)

这将为QIIME提供有关您插件的基本信息。

该name参数是用户将用于从不同QIIME 2界面访问您插件的名称。它应该是“命令行友好”的名称，因此不应包含空格或标点符号。避免在插件中使用大写字符，并使用破折号（-）代替下划线（_），但这些不是必需的，即不是强制规定。

version是您软件包的版本号，且与setup.py中使用的版本号相同。

website是您希望最终用户参考以便获取有关您软件包的更多信息的页面。由于q2-diversity没有自己的网站，因此我们在此处包括QIIME 2网站。

package是您插件的Python包名称。

尽管在前面的示例中未显示，但是插件开发人员可以给qiime2.plugin.Plugin选择性地提供以下参数：

• citation_text：描述用户应如何引用插件和/或其包装的潜在工具。如果未提供，则告知用户引用某网页。

• user_support_text：描述用户应如何获得有关插件的帮助文档，例如问题跟踪器，StackOverflow标签，邮件列表等。如果未提供，用户可在相应网页获得帮助。在QIIME 2论坛上可获得q2-diversity的帮助，因此我们在此处提供了网址。我们鼓励插件开发人员在QIIME 2论坛上支持他们的插件，因此您可以将网址包含在user_support_text中。如果这样做，您应该养成定期浏览QIIME 2论坛，以便及时提供问题解答服务。

该插件对象可以存在于项目中的任何位置，但按照惯例，它将存在于名为plugin_setup.py的文件中。有关示例请参见q2_diversity/plugin_setup.py。

注册一个动作 Registering an Action

你一旦有了要注册为Actions（即Methods或Visualizers）的函数，并实例化了Plugin对象，就可以注册这些函数了。这很可能在Plugin实例化对象的文件中完成，因为它将使用该实例（在以下示例中将称之为plugin）。

注册一个方法 Registering a Method

首先，我们通过plugin.methods.register_function来注册一个Method，具体如下：

from q2_types import (FeatureTable, Frequency, Phylogeny,
                      Rooted, DistanceMatrix)
from qiime2.plugin import Str, Choices, Properties, Metadata

import q2_diversity
import q2_diversity._beta as beta

plugin.methods.register_function(
    function=q2_diversity.beta_phylogenetic,
    inputs={'table': FeatureTable[Frequency],
            'phylogeny': Phylogeny[Rooted]},
    parameters={'metric': Str % Choices(beta.phylogenetic_metrics())},
    outputs=[('distance_matrix', DistanceMatrix % Properties('phylogenetic'))],
    input_descriptions={
        'table': ('The feature table containing the samples over which beta '
                  'diversity should be computed.'),
        'phylogeny': ('Phylogenetic tree containing tip identifiers that '
                      'correspond to the feature identifiers in the table. '
                      'This tree can contain tip ids that are not present in '
                      'the table, but all feature ids in the table must be '
                      'present in this tree.')
    },
    parameter_descriptions={
        'metric': 'The beta diversity metric to be computed.'
    },
    output_descriptions={'distance_matrix': 'The resulting distance matrix.'},
    name='Beta diversity (phylogenetic)',
    description=("Computes a user-specified phylogenetic beta diversity metric"
                 " for all pairs of samples in a feature table.")
)

提供的值(values)是：

function：要被注册为Method的函数。

inputs：说明每个Articact参数名及语义类型的字典，指示每个输入的参数名称及其语义类型对象。这些语义类型与您在输入的mypy注释中提供的数据类型不同，因为语义类型描述了数据，其中数据类型表明了数据结构。这个链接详细介绍了当前可用的语义类型，并说明了为何要定义语义类型。在上面的示例中，我们注明table参数必须为频率特征表（FeatureTable of Frequency），即特征表中的数值是原始计数，并且phylogeny参数必须为有根发育树。请注意，inputs中的键值直接映射到q2_diversity.beta_phylogenetic中的参数名称。

parameters：标明每个输入Parameter的参数名称及其语义类型。这些参数是原始值，即非对象。在上面的示例中，我们标明metric应当是来自特定集合的字符串。在这种情况下，是已知的系统发生β多样性指标的集合。

outputs：表示每个输出名称及其语义类型的元组（tuple）列表。

input_descriptions：包含输入Artifact名称及其对应描述。界面使用该信息来指导用户如何使用每个特定的输入Artifact。

parameter_descriptions：包含参数名称及其相应描述的字典。界面使用此信息来指导用户如何使用每个特定的输入参数。这些描述中不应包含任何默认参数值，因为这些默认值通常会由界面自动添加。

output_descriptions：包含输出对象名称及其对应描述的字典。界面使用此信息来告知用户每个特定的输对象将是什么。

name：人类易读的Method名称。这可以在界面中呈现给用户。

description：人类易读的Method描述。这可以在界面中呈现给用户。

注册可视化工具 Registering a Visualizer

注册Visualizers与注册Methods的方法类似，但有两点不同。

首先，您调用plugin.visualizers.register_function来注册Visualizer。

其次，在进行此调用时您不需要提供outputs或output_descriptions。根据Visualizers的定义，它仅返回单个可视化结果（visualization）。由于可视化输出路径是必需的参数，因此您无需在outputs列表中包括该参数。对于所有Visualizer已注册的参数，该参数都是相同的，因此会自动添加。

下面以注册q2_diversity.alpha_group_significance为Visualizer为例介绍具体过程：

plugin.visualizers.register_function(
    function=q2_diversity.alpha_group_significance,
    inputs={'alpha_diversity': SampleData[AlphaDiversity]},
    parameters={'metadata': Metadata},
    input_descriptions={
        'alpha_diversity': 'Vector of alpha diversity values by sample.'
    },
    parameter_descriptions={
        'metadata': 'The sample metadata.'
    },
    name='Alpha diversity comparisons',
    description=("Visually and statistically compare groups of alpha diversity"
                 " values.")
)

将插件对象定义为入口点

Defining your plugin object as an entry point

最后，您需要告诉QIIME在哪里可以找到您的实例化插件对象。这是通过在项目setup.py文件中将其定义为entry_point来完成的。在q2-diversity中，执行以下操作来完成这个过程：

setup(
    ...
    entry_points={
        'qiime2.plugins': ['q2-diversity=q2_diversity.plugin_setup:plugin']
    }
)

entry_points字典中的相关键为qiime2.plugins，键值是单个元素列表，其中包含格式为<distribution-name>=<import-path>:<instance-name>的字符串；<distribution-name>是Python软件包分发版本的名称，它与调用setup时传递给name的值匹配；<import-path>是Plugin您在上面创建的实例的导入路径；而<instance-name>是以上创建Plugin的名称。

在开发过程中使用q2cli测试您的插件

Testing your plugin with q2cli during development

如果在开发过程中使q2cli（即qiime命令）测试插件，则需在命令行中运行qiime dev refresh-cache来查看插件最新的更改。修改插件界面时，您将需要运行此命令。例如，添加/重命名/删除命令（或其输入/参数/输出），以及编辑任何插件/操作/输入/参数/输出说明。

另一种选择是设置环境变量Q2CLIDEV=1以便每次运行命令时刷新高速缓存。这将在开发时降低CLI（命令行界面）的速度，因为刷新缓存很慢。但是，当用户安装QIIME 2和插件的发行版时，CLI的速度要快得多，因此，这种减慢只有在开发插件时才明显。

手动刷新q2cli缓存是必要的，因为在开发过程中它无法检测到何时对插件的代码进行了更改（插件的版本在代码编辑中保持不变）。仅在开发插件时才需要手动刷新缓存。当用户安装QIIME 2和您发布的插件（即不再在开发中）时，缓存将在必要时自动更新。

插件测试 Plugin testing

许多QIIME 2插件（包括q2-emperor和q2-diversity）在其软件存储库中都具有Travis-CI的连续集成（CI）配置。如果在插件的软件存储库上启用了Travis-CI，则只要在GitHub上提交了对插件代码的更改就可以进行自动测试。插件CI测试通常包flake8 linting/style-checking以及用于运行单元测试的noseor或py.test命令。

鼓励插件开发人员为其插件功能添加单元测试，并使用flake8进行样式检验。单元测试是确定软件是否按预期运行的重要部分，这将使您和您的用户对插件充满信心。遵循样式约定，并使用诸如flake8之类的工具检查该样式，这对于希望了解您的代码的其他人（包括希望深入了解功能和潜在开源软件贡献者的用户）非常有帮助。

威尔逊等2014年的文章中对软件测试和相关主题进行了很好的讨论，这对开始开发和分发软件的科学家非常有帮助。

高级插件开发

Advanced plugin development

定义语义类型，数据布局和视图读取器/写入器

Defining semantic types, data layouts, and view readers/writers

本部分目前尚未完成。同时，如果您对这些高级插件开发主题有疑问，请随时在论坛上与我们联系。有关定义语义类型，数据布局和视图读取器/写入器的插件的示例请参阅q2-types。

示例插件 Example plugins

• q2-emperor：这是一个简单的插件，定义为独立软件包。它提供QIIME 2对Emperor中定义的功能的访问。

• q2-diversity：这是一个更复杂的插件，该插件与其提供访问功能的软件包定义在同一包中。

• q2-types：这是一个更复杂的插件，用于定义现实世界中的QIIME 2类型，以进行生物信息学/微生物组分析。

译者简介

刘永鑫，博士，中科院青促会会员，QIIME 2项目参与人。2008年毕业于东北农业大学微生物学专业，2014年于中国科学院大学获生物信息学博士，2016年遗传学博士后出站留所工作，任工程师。目前主要研究方向为宏基因组数据分析。目前在Science、Nature Biotechnology、Protein & Cell、Current Opinion in Microbiology等杂志发表论文30余篇，被引2千余次。2017年7月创办“宏基因组”公众号，目前分享宏基因组、扩增子原创文章2400余篇，代表作有《扩增子图表解读、分析流程和统计绘图三部曲(21篇)》、 《微生物组实验手册》、《微生物组数据分析》等，关注人数11万+，累计阅读2100万+。

Reference

https://docs.qiime2.org/2020.11

Evan Bolyen, Jai Ram Rideout, Matthew R. Dillon, Nicholas A. Bokulich, Christian C. Abnet, Gabriel A. Al-Ghalith, Harriet Alexander, Eric J. Alm, Manimozhiyan Arumugam, Francesco Asnicar, Yang Bai, Jordan E. Bisanz, Kyle Bittinger, Asker Brejnrod, Colin J. Brislawn, C. Titus Brown, Benjamin J. Callahan, Andrés Mauricio Caraballo-Rodríguez, John Chase, Emily K. Cope, Ricardo Da Silva, Christian Diener, Pieter C. Dorrestein, Gavin M. Douglas, Daniel M. Durall, Claire Duvallet, Christian F. Edwardson, Madeleine Ernst, Mehrbod Estaki, Jennifer Fouquier, Julia M. Gauglitz, Sean M. Gibbons, Deanna L. Gibson, Antonio Gonzalez, Kestrel Gorlick, Jiarong Guo, Benjamin Hillmann, Susan Holmes, Hannes Holste, Curtis Huttenhower, Gavin A. Huttley, Stefan Janssen, Alan K. Jarmusch, Lingjing Jiang, Benjamin D. Kaehler, Kyo Bin Kang, Christopher R. Keefe, Paul Keim, Scott T. Kelley, Dan Knights, Irina Koester, Tomasz Kosciolek, Jorden Kreps, Morgan G. I. Langille, Joslynn Lee, Ruth Ley, Yong-Xin Liu, Erikka Loftfield, Catherine Lozupone, Massoud Maher, Clarisse Marotz, Bryan D. Martin, Daniel McDonald, Lauren J. McIver, Alexey V. Melnik, Jessica L. Metcalf, Sydney C. Morgan, Jamie T. Morton, Ahmad Turan Naimey, Jose A. Navas-Molina, Louis Felix Nothias, Stephanie B. Orchanian, Talima Pearson, Samuel L. Peoples, Daniel Petras, Mary Lai Preuss, Elmar Pruesse, Lasse Buur Rasmussen, Adam Rivers, Michael S. Robeson, Patrick Rosenthal, Nicola Segata, Michael Shaffer, Arron Shiffer, Rashmi Sinha, Se Jin Song, John R. Spear, Austin D. Swafford, Luke R. Thompson, Pedro J. Torres, Pauline Trinh, Anupriya Tripathi, Peter J. Turnbaugh, Sabah Ul-Hasan, Justin J. J. van der Hooft, Fernando Vargas, Yoshiki Vázquez-Baeza, Emily Vogtmann, Max von Hippel, William Walters, Yunhu Wan, Mingxun Wang, Jonathan Warren, Kyle C. Weber, Charles H. D. Williamson, Amy D. Willis, Zhenjiang Zech Xu, Jesse R. Zaneveld, Yilong Zhang, Qiyun Zhu, Rob Knight & J. Gregory Caporaso#. Reproducible, interactive, scalable and extensible microbiome data science using QIIME 2. Nature Biotechnology. 2019, 37: 852-857. doi:10.1038/s41587-019-0209-9