—— 从一无所知到前期工作准备妥当的整个学习路径，涉及到多篇文档，算是一篇流水账
(在gatk4网站的文档海洋中漫游真的会被呛死...)
前言：最开始当然是想越快跑起来越好，跳进坑里才发现这坑好深，就算看了gatk4为你准备的get start，你仍旧无法get start，你需要从一篇文档跳至另一篇文档，再跳至另一篇文档才能将它的best practice 跑通
首先上来直奔主题，想跑pipeline当然是从data preprocessing入手：
https://github.com/gatk-workflows/gatk4-data-processing
数据预处理的best practice
WDL pipeline的要求:
- Pair-end sequencing data in unmapped BAM (uBAM) format
uBAM双端测序文件 可以 - One or more read groups, one per uBAM file, all belonging to a single sample (SM) 1个SM多个RG' 可以
- Input uBAM files must additionally comply with the following requirements: 要求：
a. filenames all have the same suffix (we use ".unmapped.bam") 相同的后缀 可以
b. files must pass validation by ValidateSamFile 样本通过ValidateSamFile程序 没明白
c. reads are provided in query-sorted order uBAM的排序方式要求 可以
d. all reads must have an RG tag 必须都有RG tag 可以
e. Reference index files must be in the same directory as source (e.g. reference.fasta.fai in the same directory as reference.fasta) 保证参考序列的index和参考序列在同一目录下 可以
output为clean bam，可直接用于variant calling（理想很丰满）
软件要求（环境）：
GATK4 如何安装 安装好了
BWA 可以
Picard 可以
Samtools 可以
Python2.7 可以
Cromwell v24 ~ v49 如何安装 安装好了
给了个Resource Bundle，结果打开发现404...
User Guide 发现就是a bundle of troubleshooting documentations，我直接迷失
接着看这篇文档：（启航~）
https://gatk.broadinstitute.org/hc/en-us/articles/360036194592-Getting-started-with-GATK4
GATK4 前提
Linux系统 可以
安装Java 8 / JDK 1.8 可以
下载GATK package 可以
使用语法 gatk [--java-options "-Xmx4G"] ToolName [GATK args] 可以
(可选) Docker container system 不选，使用conda
GATK best practice想用就得学习它的pipeline scripts 使用WDL语法书写，使用Cromwell engine
接着看这篇文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035889771
说GATK把他们的pipeline都放在了https://github.com/gatk-workflows/ 上
还是在说WDL+Cromwell的事情
接着看这篇文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035530952--How-to-Execute-Workflows-from-the-gatk-workflows-Git-Organization
说他们在GitHub上提供了pipeline，每个pipeline跟着一个json文件，还说他们的workflow是针对云端计算设计的，在本地运行需要用户自行调整（感觉心又累了起来）
但还是提供了本地化运行的教程
需要docker和git
首先创建一个工作目录
mkdir gatk-workflows
cd gatk-workflows
再创建一个目录存放输入
mkdir inputs
下载Cromwell，一个java文件
wget https://github.com/broadinstitute/cromwell/releases/download/33.1/cromwell-33.1.jar
选择一个你喜欢的repository并git clone它，执行完下面的代码后工作目录下会多出一个seq-format-validation (当然你可以选择喜欢的repository去git clone，这里只是举个例子)，里面有很多文件，我们要关心的是json文件和wdl文件，即我们要使用配套的json文件去跑validate-bam.wdl这个pipeline
git clone https://github.com/gatk-workflows/seq-format-validation.git
改变我们的工作目录
cd seq-format-validation
修改json文件，主要是修改参数
vim validate-bam.inputs.json
回到原来的工作目录
cd ..
然后就可以使用Cromwell运行GATK best practice pipeline了
java -jar cromwell-33.1.jar run ./seq-format-validation/validate-bam.wdl --inputs ./seq-format-validation/validate-bam.inputs.json
看具体的best practice文档之前，看看这篇介绍GATK best practice的文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035894711-About-the-GATK-Best-Practices
什么是GATK best practice，简单说来就是一个reads-to-variants的workflow
分析的阶段分为:
- data preprocess
- variant discovery阶段
- 后续可能还有filtering和annotation (可能包括resources of known variation, truthsets, metadata)
接着看这篇文档：
万事第一步，data preprocess。
https://gatk.broadinstitute.org/hc/en-us/articles/360035535912-Data-pre-processing-for-variant-discovery
主要做了三件事：
- BWA, MergeBamAlignments
- MarkDuplicatesSpark / MarkDuplicates + SortSam (替代方案)
- aseRecalibrator, Apply Recalibration, AnalyzeCovariates
git clone https://github.com/gatk-workflows/gatk4-data-processing.git
看了一下json的设置，貌似只支持b37和hg38，真的吗？
为了解决这个疑惑，接着看这篇文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035891071
举的例子很有意思，说参考基因组就像：The quick brown fox jumped over the lazy doge.
你并不知道真正的原句是"jumped"还是"jumps"，你也有把握认为"doge"不应该这么拼写，这就是参考基因组，一个common standard
另外目前所有的参考基因组都是单倍体！
“the biggest problem is that once you've started working with a particular reference build, it's difficult to switch to another or incorporate an external resource that was derived from a different build.”
这是目前在使用不同基因组时最大的问题，你无法使用源自另一基因组的resource，如SNPdb
contigs是连续的序列，不包含physical gaps(NNNNNNNN不算)
Alternate contigs(ALT contigs), alternate scaffolds或alternate loci 这些序列过于复杂，无法用单倍体的方式表示
primary assembly 包括了组装的染色体 unlocalized序列即知道在哪条染色体上但不知道方向，unplaced序列即不知道在哪条染色体上，构成了非冗余的单倍体基因组
PAR 假常染色体区，辅助哺乳动物的XY染色体recombination
不同的assembly组装如hg38和b37
patches在不改变某个组装的染色体坐标的情况下，增加一些信息
上篇文档还讲到了alt contigs不对应的问题，这个问题也曾令我困扰，着看这篇文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035891131
错误发生在混用hg38和hg19时，最常见的还是发生在些许不同的版本如b37和hg19，建议是：选择匹配的参考基因组。。。说人话就是重新比对
(虽然约等于啥都没说，但不可否认这是最好的解决办法)
接着看这篇文档，讲了不同组装之间的差异：
https://gatk.broadinstitute.org/hc/en-us/articles/360035890951-Human-genome-reference-builds-GRCh38-or-hg38-b37-hg19
理想的参考基因组可以概括所有个体，但这很难，因为人与人之间染色体的某些区域的差异实在过大，hg38旨在提供不同人种的alternate haplotype
“GRCh38/hg38 is the assembly of the human genome released December of 2013, that uses alternate or ALT contigs to represent common complex variation, including HLA loci.”
先前组装并没有hg38这么多的alt contigs，这些改进离不开其他项目，例如1000 Genomes Project，并且修正了hg19中在人群中不存在的一些SNPs和InDels
目前hg19也仍在使用，b37是与之相近的一个版本，在染色体的命名和decoy序列上有一些出入，这里有个坏消息，如果你在分析的过程中用到了基于其他基因组build的资源，那么建议您：重 头 比 对
这篇文章中专门列出了一些External resources，读一读还是有收获的(例如目前使用hg38遇到的一些难题，有一篇Genome Biology专门讲这个)，但我实在是不想细看了
接着看这篇文档：
resource bundle的资源都在这里
https://gatk.broadinstitute.org/hc/en-us/articles/360035890811
目前提供了hg38和b37的资源，hg38的部分待补充
b37 resource包括：
1. standard 1000 Genomes Reference sequence (fasta + fai + dict)
2. dbSNP (vcf) 包括dbSNP build 138 + subset before build 129
3. HapMap genotypes and sites VCFs 这是什么
4. OMNI 2.5 genotypes for 1000 Genomes samples, as well as sites, VCF 这是什么
5. 用于局部重比对的两个文件：
1000G_phase1.indels.b37.vcf (currently from the 1000 Genomes Phase I indel calls)
Mills_and_1000G_gold_standard.indels.b37.sites.vcf
6. The latest set from 1000G phase 3 (v4) for genotype refinement: 1000G_phase3_v4_20130502.sites.vcf 这是什么
7. 示例数据：bam文件和interval list(仅供参考，不可用于实际分析)
下载分为Google bucket和FTP两种方式，目前FTP已经挂了，Google bucket暂时还没找到下载b37 resource的方法
提供的都是所谓"bucket path", 应当是使用google bucket作为云储存工具?
bucket path例如: gs://gcp-public-data--broad-references
看来我是需要通过bucket path获取resource了，问题是要怎么做
接着看这篇文档：
讲如何获取公开数据
https://cloud.google.com/storage/docs/access-public-data#gsutil
可能需要使用gsutil这一命令行工具下载
接着看这篇文档：
讲如何安装gsutil
https://cloud.google.com/storage/docs/gsutil_install#install
下载了tar包后，执行下列命令将gsutil安装至主目录
tar xfz gsutil.tar.gz -C $HOME
配置.bashrc
export PATH=${PATH}:$HOME/gsutil
装好了，运行：
gsutil ls gs://gatk-legacy-bundles/b37/
至此相当于可以访问Google Cloud bucket公开数据了，但并没有hg19的相关数据，只有与之相似的b37
事实上ftp上储存的hg19数据也是b37 lift over得到的
接着看这篇文档：
讲gsutil如何入门(简单了解下ls和cp命令)
https://cloud.google.com/storage/docs/quickstart-gsutil
至此知识，自己测序数据，公共数据都准备妥当了，可以开始执行best practice pipeline了~
现在再回到这个链接，会有不一样的感受
https://github.com/gatk-workflows/gatk4-data-processing
再看这个文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035535912-Data-pre-processing-for-variant-discovery
分为以下几步：
- 先是uBAM或fastq文件
- 比对至参考基因组，得到raw BAM
- MarkDuplicateSpark
- RBQS(碱基质量重校正)
- 得到可用于分析的BAM
接着看这个文档：
https://github.com/gatk-workflows/gatk4-data-processing
执行该WDL pipeline的要求:
1. Pair-end sequencing data in unmapped BAM (uBAM) format 输入为uBAM双端测序文件 可以
2. One or more read groups, one per uBAM file, all belonging to a single sample (SM) 1个SM多个RG' 可以，可能要用到Picard AddOrReplaceReadGroups工具
3. Input uBAM files must additionally comply with the following requirements: 要求：
filenames all have the same suffix (例如".unmapped.bam") 相同的后缀 可以
files must pass validation by ValidateSamFile 样本通过ValidateSamFile程序 是Picard ValidateSamFile工具
reads are provided in query-sorted order uBAM的排序方式要求为query-sorted order 可以
all reads must have an RG tag 必须都有RG tag 可以，可能要用到Picard AddOrReplaceReadGroups工具
4. Reference index files must be in the same directory as source (e.g. reference.fasta.fai in the same directory as reference.fasta) 保证参考序列的index和参考序列在同一目录下 可以
接着看这篇文档：
https://gatkforums.broadinstitute.org/gatk/discussion/6484/how-to-generate-an-unmapped-bam-from-fastq-or-aligned-bam
将fastq文件转换为uBAM文件
使用gatk4也可以调用picard，具体方法为：
gatk --java-options "-Xmx8G" picard_tool_name
例：
gatk FastqToSam \
-F1 ./R1_L001_paired.fastq.gz \
-F2 ./R2_L001_paired.fastq.gz \
-O unmapped.bam \
-RG lane1 \
-SM B1 \
-LB kk8504 \
-PL illumina
配置环境：
GATK4
BWA 可以
Picard 随GATK4一同安装
Samtools 可以
Python2.7 可以
Cromwell v24 ~ v49
(其实除Cromwell外的全部软件均在docker内运行，因此pull相应的docker image即可)
vim配置json，发现运行pipeline必须的相应文件
使用gsutil ls gs://gatk-legacy-bundles/b37/human_g1k_v37_decoy*查看参考基因组索引文件和bwa-mem索引文件并下载
使用gsutil ls gs://gatk-legacy-bundles/b37/human_g1k_v37_decoy* | gsutil -m cp -I ./批量下载这部分文件，即用管道的方式将标准输出传递给gsutil即可
尝试开始跑wdl pipeline
cromwell run ./gatk4-data-processing-master/processing-for-variant-discovery-gatk4.wdl --inputs ./gatk4-data-processing-master/processing-for-variant-discovery-gatk4.b37.wgs.inputs.json
发现仍无法运行，猜测可能是docker没配置好，接着看这篇文档：
https://gatk.broadinstitute.org/hc/en-us/articles/360035889991--How-to-Run-GATK-in-a-Docker-container
首先是在linux上安装docker，看这篇文档：
https://docs.docker.com/engine/install/
安装好了
service docker start
安装gatk:4.1.8.0版本
docker pull broadinstitute/gatk:4.1.8.0
启动docker(进入容器，后面发现这一步无关紧要，其实并不需要我们手动进入docker))
docker run -it broadinstitute/gatk:4.1.8.0
停止容器并退出(暗指有不停止容器但可以退出的方法，即detach)：
exit
挂载进容器外的目录
docker run -v /root/WZW/20200512_wes_p3/:/root/20200512_wes_p3 -it broadinstitute/gatk:4.1.8.0
容器自带conda，配置源(后面发现这一步无关紧要，其实并不需要我们手动进入docker)
conda config --add channels bioconda
conda config --add channels conda-forge
conda install bwa picard samtools
docker貌似是基于ubuntu的，属于debian系Linux，因此要使用apt-get
更新软件源(后面发现这一步无关紧要，其实并不需要我们手动进入docker)
apt-get update
安装vim
apt-get install vim
配置 ~/.bashrc(后面发现这一步无关紧要，其实并不需要我们手动进入docker)
vi ~/.bashrc
# cromwell config
alias cromwell='java -jar /root/20200512_wes_p3/bin/cromwell-33.1.jar'
source ~/.bashrc
进入相同的docker
docker exec -it 1ab29d9b1496 bash
又或许有不使用docker即可运行wdl pipeline的方法（这里其实是想岔了，以为是要进入docker运行Cromwell，其实是在docker外运行Cromwell，Cromwell在执行wdl pipline时会自动进入相应的docker执行命令，不同的命令需要不同的docker）
看这个问题：
https://gatkforums.broadinstitute.org/wdl/discussion/11442/modifying-the-processing-for-variant-discovery-inputs-json
看了这篇博客：（解决问题并最终跑通pipeline最关键的博文，gatk4的说明文档在这里缺少提示，或是没有放在很显眼的位置，我知道看了这篇文章才知道自己错在哪里）
http://www.zxzyl.com/archives/869
要点：压根不应该进入docker运行，而是让Cromwell自动调用docker(所以说gatk4的说明文档还是令人一言难尽，稍微提一句不用进入docker image能少走不少弯路)
根据wdl文件安装其他docker
docker pull broadinstitute/genomes-in-the-cloud:2.3.1-1512499786
docker pull python:2.7
在docker外，也就是我们平常的环境中运行：
cromwell run ./gatk4-data-processing-master/processing-for-variant-discovery-gatk4.wdl --inputs ./gatk4-data-processing-master/processing-for-variant-discovery-gatk4.b37.wgs.inputs.json
终于成功了，跑通了一个pipeline，后面自然一通百通