sourmash_plugin_betterplot

sourmash 是一个用于生物序列分析和比较的工具。

betterplot 是一个sourmash插件，它为基于sourmash的sketch比较提供了改进的绘图/可视化和聚类检查。它包括更好的相似性矩阵绘图、MDS图和聚类图，以及基于类别的样本着色支持。它还包括对由sourmash的branchwater插件中的快速多线程manysearch和pairwise函数生成的稀疏比较输出格式的支持。

为什么存在这个插件？

sourmash compare 和 sourmash plot 生成基本距离矩阵图，这些图对于比较和可视化数十到数百个基因组之间的关系非常有用。这也是sourmash最流行的用例之一！

然而，可视化可以远远超越sourmash plot产生的简单可视化。有很多比较、聚类和可视化许多基因组的高级用例！

这个插件就是为了探索这些用例之一而存在的！

总体目标

• 提供各种可以与sourmash工具一起使用的绘图和探索命令；
• 提供命令行功能以及可以在Jupyter笔记本中导入和使用的函数；
• （可能）探索除matplotlib以外的其他后端；

还有什么呢？

这个插件提供了什么？

截至v0.4，betterplot插件提供了

• 改进的相似性矩阵可视化，以及聚类提取；
• 多维尺度（MDS）图；
• t-Stochastic Neighbor Embedding（tSNE）图；
• 非正方形矩阵的可视化，用于manysearch的输出；
• 一个upset图来可视化sketch之间的交集；
• 一个将 pairwise 输出转换为相似度矩阵的实用函数；
• 一个将 cluster 输出转换为颜色类别的实用函数；

安装

pip install sourmash_plugin_betterplot

用法

请参阅下面的示例命令行和输出，并使用命令行帮助 (-h/--help) 查看可用选项。

图表上的标签：labels-to CSV 文件。

大多数（所有？）比较矩阵绘图函数（例如 plot2、plot3、mds）使用的 labels-to CSV 文件与 sourmash compare ... --labels-to <file> 生成的格式相同，并由 sourmash plot --labels-from <file> 加载。格式可能很直观，但有几点需要说明——

• sort_order 列指定了距离矩阵中样本的列顺序。这是为了支持任意重新排列和处理 CSV 文件。
• label 列是将在图表上显示的名称，也是默认的 "categories" CSV 匹配（见下文）。您可以手动（电子表格、文本编辑器）或通过程序编辑它。
• 顺便说一下，sourmash compare 生成的 labels.txt 文件完全被忽略；）。

图表上的类别： "categories" CSV 文件

更好的plot函数的一个优点是能够提供使图表着色的类别。这对于某些图表至关重要——例如，没有颜色的 mds 和 mds2 图表几乎没有任何意义——而且对于其他图表（如 plot3 和 clustermap1）也很不错，您可以按类别着色列/行。

要使用此功能，您需要提供 "categories" CSV 文件（通常 -C/--categories-csv）。该文件在格式上相当灵活；它必须包含至少两列，其中一列名为 category，但可以包含更多，只要提供 category。

最简单的categories CSV格式在 10sketches-categories.csv 中显示，它包含两列，label 和 category。当加载此文件时，label 与每个点/行/列的名称匹配，然后该点被分配该类别。

通过列匹配提供额外的灵活性。

当前实现的一些限制/观察

• 如果提供了categories CSV，则每个点都必须有一个相关的类别。应该可以有更多的点和类别——检查me，@CTB！
• 目前无法指定特定颜色为类别；它们会被随机分配。
• 完全可以编辑标签文件（见上文）并添加一个 category 列。代码不会自动检测此更改——您需要通过 -C 指定相同的文件——但它可以正常工作！

示例

以下命令行在安装插件后可在存储库的 examples/ 子目录中执行。

plot2 - 基本的三幅草图示例

使用 sourmash compare 比较三幅草图并进行聚类。

此命令

sourmash compare sketches/{2,47,63}.sig.zip -o 3sketches.cmp \
    --labels-to 3sketches.cmp.labels_to.csv

sourmash scripts plot2 3sketches.cmp 3sketches.cmp.labels_to.csv \
    -o plot2.3sketches.cmp.png

生成此图表

plot2 - 带截断线的三幅草图示例：plot2 --cut-point 1.2

使用 sourmash compare、聚类和显示截断点比较三幅草图。

此命令

sourmash compare sketches/{2,47,63}.sig.zip -o 3sketches.cmp \
    --labels-to 3sketches.cmp.labels_to.csv

sourmash scripts plot2 3sketches.cmp 3sketches.cmp.labels_to.csv \
    -o plot2.cut.3sketches.cmp.png \
    --cut-point=1.2

生成此图表

plot2 - 带截断线加聚类提取的 10 幅草图树状图

使用 sourmash compare、聚类并使用截断点提取多个聚类。使用 --dendrogram-only 仅绘制树状图。

此命令

sourmash compare sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.cmp \
    --labels-to 10sketches.cmp.labels_to.csv

sourmash scripts plot2 10sketches.cmp 10sketches.cmp.labels_to.csv \
    -o plot2.cut.dendro.10sketches.cmp.png \
    --cut-point=1.35 --cluster-out --dendrogram-only

生成此图表

以及一组 6 个聚类到 10sketches.cmp.*.csv。

mds- 从 sourmash compare 输出中的多维缩放（MDS）

使用 MDS 显示由 sourmash compare 生成的比较。

这些命令：

sourmash compare sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.cmp \
    --labels-to 10sketches.cmp.labels_to.csv

sourmash scripts mds 10sketches.cmp 10sketches.cmp.labels_to.csv \
    -o mds.10sketches.cmp.png \
    -C sketches/10sketches-categories.csv

生成了以下图像：

默认情况下，此命令生成度量MDS图。使用--nmds可以生成非度量（NMDS）图。

mds2 - 从pairwise输出生成多维度缩放（MDS）图

使用MDS显示使用branchwater插件的pairwise命令创建的稀疏比较。与sourmash compare输出不同：pairwise生成只包含阈上匹配的稀疏CSV文件，而sourmash compare生成密集的numpy矩阵。

这些命令：

sourmash sig cat sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.sig.zip
sourmash scripts pairwise 10sketches.sig.zip -o 10sketches.pairwise.csv

sourmash scripts mds2 10sketches.pairwise.csv \
    -o mds2.10sketches.cmp.png \
    -C sketches/10sketches-categories.csv

生成了以下图像：

默认情况下，此命令生成度量MDS图。使用--nmds可以生成非度量（NMDS）图。

cluster_to_categories - 将cluster中的聚类转换为类别

branchwater插件中的sourmash scripts cluster命令会对pairwise输出进行聚类；cluster_to_categories将这些聚类转换为类别CSV文件，可用于着色点和列/行。

这些命令：

# generate pairwise comparison
sourmash scripts pairwise sketches/64sketches.sig.zip -o 64sketches.pairwise.csv \
    --write-all

# generate clusters
sourmash scripts cluster 64sketches.pairwise.csv \
    -o 64sketches.pairwise.clusters.csv \
    --similarity jaccard -t 0 

# convert to categories CSV
sourmash scripts cluster_to_categories 64sketches.pairwise.csv \
    64sketches.pairwise.clusters.csv -o 64sketches.pairwise.clusters.cats.csv

生成64sketches.pairwise.clusters.cats.csv，根据输入样本的聚类成员资格进行分类。

tsne - 从sourmash compare输出生成t-SNE图

t-分布随机邻域嵌入（t-SNE）是另一种将高维数据可视化在二维的方法。tsne命令显示由sourmash compare生成的比较。

这些命令：

sourmash compare sketches/64sketches.sig.zip -o 64sketches.cmp \
    --labels-to 64sketches.cmp.labels_to.csv
    
sourmash scripts tsne 64sketches.cmp 64sketches.cmp.labels_to.csv \
    -C 64sketches.pairwise.clusters.cats.csv -o tsne.64sketches.cmp.png

生成此图

（64sketches.pairwise.clusters.cats.csv由上面的cluster_to_categories命令生成。）

tsne2 - 从pairwise输出生成t-SNE图。

这些命令：

sourmash scripts pairwise sketches/64sketches.sig.zip -o 64sketches.pairwise.csv \
    --write-all
    
sourmash scripts tsne2 64sketches.pairwise.csv \
    -C 64sketches.pairwise.clusters.cats.csv -o tsne2.64sketches.cmp.png

生成此图

（64sketches.pairwise.clusters.cats.csv由上面的cluster_to_categories命令生成。）

pairwise_to_matrix - 将pairwise输出转换为sourmash compare输出并绘图

将使用branchwater插件的pairwise命令创建的稀疏比较CSV转换为sourmash compare风格的相似度矩阵。

这些命令：

# build pairwise
sourmash sig cat sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.sig.zip
sourmash scripts pairwise 10sketches.sig.zip -o 10sketches.pairwise.csv

# convert pairwise
sourmash scripts pairwise_to_matrix 10sketches.pairwise.csv \
    -o 10sketches.pairwise.cmp \
    --labels-to 10sketches.pairwise.cmp.labels_to.csv
    
# plot!
sourmash scripts plot2 10sketches.pairwise.cmp \
    10sketches.pairwise.cmp.labels_to.csv \
    -o plot2.pairwise.10sketches.cmp.png

生成此图

plot3 - 带颜色类别的seaborn聚类图

使用seaborn聚类图绘制sourmash compare相似度矩阵，它提供了一些良好的可视化选项。

这些命令：

sourmash compare sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.cmp \
    --labels-to 10sketches.cmp.labels_to.csv

sourmash scripts plot3 10sketches.cmp 10sketches.cmp.labels_to.csv \
    -o plot3.10sketches.cmp.png -C sketches/10sketches-categories.csv

生成此图

clustermap1 - seaborn聚类图，用于非对称矩阵

使用seaborn的聚类图绘制使用branchwater插件的manysearch命令创建的稀疏比较CSV。支持行和列的单独类别着色。

这些命令：

sourmash sig cat sketches/{2,47,48,49,51,52,53,59,60,63}.sig.zip \
    -o 10sketches.sig.zip

sourmash scripts manysearch 10sketches.sig.zip \
    sketches/shew21.sig.zip -o 10sketches.manysearch.csv

sourmash scripts clustermap1 10sketches.manysearch.csv \
    -o clustermap1.10sketches.png \
    -u containment -R sketches/10sketches-categories.csv

生成

upset - 使用UpSetPlot绘制草图交集

绘制草图交集的UpSetPlot。

此命令

sourmash scripts upset 10sketches.sig.zip -o 10sketches.upset.png

生成

venn - 使用Venn图绘制2个或3个草图交集

绘制两个或三个草图交集的Venn图。

此命令

sourmash scripts venn sketches/{2,47,63}.sig.zip \
    -o 3sketches.venn.png --ident

生成

支持

我们建议在sourmash主问题跟踪器中提交问题，因为那里会得到更多的关注！

开发文档

betterplot是在https://github.com/sourmash-bio/sourmash_plugin_betterplot开发的。

请参阅environment.yml以获取开发betterplot所需的依赖项。

测试

运行

make examples

以运行示例。

目前，示例充当测试；最终我们将添加单元测试。

生成发布版

在pyproject.toml中增加版本号并推送。

在GitHub上创建新的发布版。

然后拉取，并

python -m build

接着执行twine upload dist/...。

CTB 2024年6月