QIIME 2教程. 24为QIIME 2开发新插件DevelopingPlugin(2024.2)

为QIIME 2开发新插件

Developing a QIIME 2 plugin

https://docs.qiime2.org/2024.2/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中，包