从结构/混合物数据中对种群结构图进行超快速分析和交互式可视化
项目描述
本文档用作安装和使用 pong 的快速入门指南和参考卡。有关全面信息，请参阅软件手册。
安装乒乓球
pong 已在 macOS (10.8-11)、Linux (Ubuntu 15.04、Linux Mint 17.2) 和 Windows 7 上进行了测试。
pong 托管在PyPI上，因此可以使用pip. 为了运行 pong，您需要 Python 3（3.6 或更高版本）和现代网络浏览器。
要安装 pong，请运行：
pip3 install pong
Python 2 用户注意事项：旧版本的 pong 在 Python 2.7 上运行。与 Python 2 兼容的最新版本 pong 可以安装pip install pong==1.4.9
特定于 Linux 的提示
在某些 Linux 系统上，安装命令可能由于权限错误而失败。在这种情况下，请尝试运行sudo pip install pong。系统将提示您输入计算机登录密码。如果这也不起作用，请尝试以超级用户身份运行命令：
su # you will be prompted to enter an administrator password
pip install pong
exit
特定于 Mac 的提示
请注意，Apple 系统默认 Python 无法运行 pong。Python 3 并且pip可以手动安装，但我们发现如果您使用(mini)conda或Homebrew安装是最简单的。例如：
# If you have Miniconda (or Anaconda)
conda install python
conda install pip
pip install pong
# Or, if you don't want to install pong in your base environment
conda create -n my-pong-env python pip
conda activate my-pong-env
pip install pong
# Or, using Homebrew
brew install python [ brew upgrade python ]
pip install pip [ pip install --upgrade pip ]
pip install pong [ pip install --upgrade pong ]
跑步乒乓球
pong 通过命令行执行。要查看完整的选项列表，请运行：
pong -h
Windows 用户注意事项：在某些 Windows 系统上，pong 可能未安装为可执行文件，因此无法使用此命令运行。相反，替换pong为python3 \path\to\pong.
我们提供了一个示例数据集，您可以在该数据集上运行 pong（可在GitHub或Ramachandran Lab 网站上获得）。使用来自1000 Genomes Project Phase3（2,426 个人）的数据，我们在K = 2 到K = 8的每个K值下执行了 8 次 ADMIXTURE 。要使用 pong 分析示例数据集，请导航到解压缩的示例目录并运行：
pong -m pong_filemap -i ind2pop.txt -n pop_order_expandednames.txt
有关 pong 对输入数据的应用的信息将显示在您的终端窗口中。算法完成后，pong 会在localhost:4000上初始化一个 Web 服务器（您可以使用命令行选项更改 pong 运行的端口--port）。在 Web 浏览器上导航到localhost:4000后，pong 将检测到新的浏览器连接并开始呈现可视化。
示例截图：
提示：单击屏幕顶部的问号可获取有关如何与 pong 的网络应用程序交互的快速教程（包括突出显示多模态和下载绘图）。
在自己的数据上运行 pong
pong 的设置被设计为低麻烦。本节详细介绍了 pong 处理的必需和可选输入文件。
聚类输出
pong 接受来自各种聚类推理程序的聚类输出文件或Q矩阵。命令行选项-c或--ignore_cols告诉 pong在解析各个隶属系数之前要跳过输入Q矩阵文件的每一行的前导列的数量。例如，-c 5用于某些版本的Structure
indiv 输出以忽略协变量元数据。如果不应该跳过前导列（例如对于 ADMIXTURE 输出），则不需要提供-c 0，因为默认值为-c0。
一些相关的注意事项：
- 不用担心尾随列；它们不会被解析（在
-c忽略前导列之后，只使用前K列）。 - pong默认将Q矩阵文件解析为空格分隔。如果由于某种原因，您的输入数据不是这种情况，您可以使用该选项指定任何列分隔符
--col_delim（例如--col_delim ","，用于 CSV 文件，或--col_delim "\t"用于制表符分隔的文件）。 - 虽然 pong 确实处理Q矩阵中的前导/尾随列，但它不处理前导/尾随行。这些行必须在使用 pong 分析之前被剥离（即对于具有n 个样本的数据集，每个Q矩阵文件应该有n行）。
文件映射文件
必须以filemap的形式提供有关输入Q矩阵的一些信息。文件映射是一个三列、制表符分隔的文件。每行包含有关单个Q矩阵的以下信息：
- 唯一 ID（例如
iter5_K=7; 这必须包含至少一个字母，并且不能包含井号/井号或句点。接受整数、空格和其他特殊字符。） - K值_
- Q矩阵文件路径，相对于filemap。因此，如果文件映射与Q矩阵文件位于同一目录中，则这只是Q矩阵文件的名称。
重要的是文件映射的列顺序正确并且文件是制表符分隔的。使用示例数据集提供的文件映射作为参考。使用命令行选项-m，或--filemap，将路径传递给您的文件映射。
人口标签（可选）
ind2pop数据：
Q矩阵通常使用人口元数据进行注释。在许多数据集中，个人被分配了一个人口代码/标签/编号；我们将其称为ind2pop数据。如果提供此信息，pong 的可视化将按人口对个体进行排序，用黑线划分人口，并根据每个人口中的个人在人口主要集群中的成员身份对其进行排序。* 也可以使用其他协变量，例如大陆或所讲的语言作为ind2pop代替人口元数据。
您可以使用命令行选项提供ind2pop-i数据，或--ind2pop. 此选项的参数可以是以下之一：
- 一个整数，表示包含ind2pop数据的Q矩阵列号。例如，用于标准结构输出。
-i 4 - ind2pop文件的路径，其中该文件的第i行包含由Q矩阵文件的第i行表示的个人的ind2pop数据（即人口代码/标签/编号） 。
请注意，作为ind2pop数据提供的人口代码/标签/数字不应包含任何空格。
人口顺序和详细名称：
如果您提供ind2pop数据，您可以提供一个附加文件，指定显示人口的所需顺序（作为命令行选项的参数-n）。该文件每行应有一个人口代码/标签/编号；文件的从上到下的顺序与总体的从左到右的显示顺序相对应。
您可能希望显示更具描述性的人口名称（例如，如果输入的ind2pop数据是数字、神秘的三字母代码等）；在这种情况下，您可以在包含人口名称的人口订单文件中添加第二列（制表符分隔）。这些名称中允许使用空格字符。请参阅示例数据集中的文件pop_order_expandednames.txt以供参考。
可视化的自定义颜色（可选）
pong 提供默认颜色（除非K_max > 26），但可以为 pong 提供包含一组用于可视化的颜色的文件（使用命令行选项-l）。该文件必须至少包含K_max颜色，每行一种颜色。因为 pong 的可视化是基于 Web 的，所以可以以 CSS 接受的任何格式（例如#ff0000、rgb(255,0,0)、red）提供颜色。
其他资源
示例数据集、软件手册和其他相关材料可在Ramachandran 实验室网站上找到。
如需更多信息，请联系Aaron Behr或Sohini Ramachandran。
*我们发现，这种排序操作可以更容易地理解每个群体中集群成员的分布。请注意，pong 对单个Q矩阵（主可视化中最底部的图，它是最高K值的主要模式的代表运行）执行此排序操作，并将该顺序传播到所有其他可视化Q矩阵，这样个体的顺序在所有地块中都是一致的。
