description
astral是基于java开发的根据一组无根的genetrees建立speciestree。
tutorial steps
installation
运行astral不需要安装，但是需要在java环境下运行。
命令行运行astral
astral没有图形界面，需要在命令行下运行。
java -jar astral.5.5.1.jar
运行后可以看到astral的options。如果运行没有错误，说明安装成功了。
用astral运行一个简单的数据
java -jar astral.5.5.1.jar -i test_data/song_mmammals.424.gene.tre
-o 输出
java -jar astral.5.5.1.jar -i test_data/song_mmammals.424.gene.tre -o test_data/song_mammals.tre
输入文件是含有所有genetrees的Newick格式的文件。输入的genetree被当做unrooted tree,不管他们是否有根。astral的输出也是被当做unrooted tree。输入的genetree支持多分支。
astral 结果查看
输出的结果是Newick格式，可以用很多软件查看。
branch length and support
astral测量branch length 是用coalscent units。不是我们通常认为的boostrap value
1.astral 只测量internal branches 不测量terminal branches
2.branch lengthes 是直接测量genetree的不一致性，有可能因为统计噪音被低估。
3.support value 测量quadriparition的support而不是通常的bipartion（二分位）。（astral 认为自己的support value 比boostrap value 可信度更高。）
scoring a species tree
-q参数
得到的是quartet score 和branch length 和 branch support values。0.9表示genetree产生的quartet tree的90%存在于species tree中。为树打分的命令如下：
java -jar astral.5.6.3.jar -q test_data/simulated_14taxon.default.tre -i test_data/simulated_14taxon.gene.tre -o test_data/simulated_scored.tre 2> test_data/simulated_scored.log
与simulated_14taxon.gene.tre进行比较后，会为物种树simulated_14taxon.default.tre打分。
表示来自genetree的4803个quartet trees存在于species trees中。4803个quartet trees占所有的quartet trees的47.98%。这个数据集的ILS水平很高。导致这个结果，也就是genetree和species tree的不一致性很高。
extensive branch annotations
当你得到一个species tree或者用-q参数为树打分，你将会得到每一个分支的branch length 和local posterior support 。除了这些默认的参数，还可以输出其他branch 信息。无根树的每一个branch都有四组。分别是first child (L), the second child (R), the sister group (S), and everything else (O)。两两配对，可以得到三种拓扑结构。其中一种就是当前树的拓扑结构。剩下的就是可选的两种拓扑结构。astral可以不仅仅得到当前树的local posterior probability，也能计算剩下的两种拓扑结构的。-t 参数
-t 0 :关掉当前的posterior probability。
-t 1：local posterior probability 如果你想知道genetree中的quartet占branch的多少。就可以使用这个参数。用这个测定quartet support。quartet score 是测量基因树与分支冲突的好办法。
-t 4:输出3个local posterior probability，就是前文说的三种拓扑结构。
-t 2：当你使用这个参数，许多分支都会得到很多测量。
q1,q2,q3:分别展示了main topology，和另外两种拓扑结构的quartet support。
f1,f2,f3:分别展示main topology 和另外两种拓扑结构的quartet trees的总数。
pp1,pp2,pp3分别展示了main topology 和另外两种拓扑结构的local posterior probability
QC：展示了每一个分支下的quartets 的总数。
EN：branch的有效的genes。如果不存在missing data的时候，这个就是出现在branch中的数目。如果有missing data的时候，有些genetree对branch没有任何贡献。因此，这里的genetree的number可能小于总共genes的number。
-t 8：输出q1,q2,q3
-t 10:测试，查看无效假设是否会被拒绝。
-t 16:产生.csv文件，带有quartet 频率的freqQuad.csv。
命令如下
java -jar astral.5.6.3.jar -q test_data/1kp.tre -i test_data/1KP-genetrees.tre -t 2 -o test_data/1kp-scored-t2.tre
java -jar astral.5.6.3.jar -q test_data/1kp.tre -i test_data/1KP-genetrees.tre -t 4 -o test_data/1kp-scored-t4.tre
java -jar astral.5.6.3.jar -q test_data/1kp.tre -i test_data/1KP-genetrees.tre -t 8 -o test_data/1kp-scored-t8.tre
java -jar astral.5.6.3.jar -q test_data/1kp.tre -i test_data/1KP-genetrees.tre -t 10 -o test_data/1kp-scored-t10.tre
阅读几个分支给出的所有值，并理解他们。
Prior hyper-parameter（这里一节都不懂是什么意思）
用Yule prior model 计算speciestree 的branch length的local posterior probabilities 和branch lengths。Yule process的物种形成速率（in coalscent units）默认值设置为0.5，导致quartet 频率在[1/3,1]之间是平稳的。（并不理解）用-c的选项可以调节hyper-parameter。
multi-locus bootstrapping
astral 可以不通过bootstrapping输出branch support value.这种support比bootstrapping更加可靠（在作者的数据下）。尽管，你可能还是想得到bootstrapping。astral可以进行multi-locus bootstrapping。为了开展multi-locus bootstrapping，astral需要访问每一个gene的boostrap replicate trees。
例如：
你需要提供所有gene tree bootstrap replicates的位置。在测试数据中进行bootstrapping。
1.进入test_data目录
2.解压called song_mammals.424genes.bs-trees.zip.
3.然后运行
java -jar ../astral.5.6.3.jar -i song_mammals.424.gene.tre -b bs-files -o song_mammals.bootstrapped.astral.tre
然后会run100次bootstrapping。
input
1.-i 包括所有的MLgenetrees（就像不计算bootstrap也要输入的）
2.-b 告诉astral 需要计算bootstrap value。-b 后面的文件 bs-files 包含了genetree bootstrap files的文件路径，一行一个gene。例如：
424genes/100/raxmlboot.gtrgamma/RAxML_bootstrap.allbs
outputfile 包括
1.100 bootstrapped replicate trees，每一个都是对一组bootstrap gene trees进行running astral 的结果。
2.A greedy consensus of the 100 bootstrapped replicate trees; this tree has support values drawn on branches based on the bootstrap replicate trees. Support values show the percentage of bootstrap replicates that contain a branch.
3.The “main” ASTRAL tree; this is the results of running ASTRAL on the best_ml input gene trees. This main tree also includes support values, which are again drawn based on the 100 bootstrap replicate trees.（不懂）
注意：support value以百分数的形式展示。而local posterior probabilities是0-1之间的数。当astral 计算bootstrapping时，它会持续输出每一个重复的bootstrapped astral tree.因此，如果replicate 被输入成100，它将会输出100个数，然后，输出100 bootstrapped trees 的greedy consensus。（不懂）最后，它会开展主要的分析 （-i参数的文件）然后计算主要树的branch support。这个示例中就是102trees。
number of replicates
默认值是100，-r 参数可以设置任何数量的重复。但是要保证你的genetree的bootstrap file 的bootstrap replicates 要多于你的-r参数后面的设置。
gene+site resampling
astral 开展site-only的resampling，可以用-g参数。
java -jar ../astral.5.6.3.jar -i song_mammals.424.gene.tre -b bs-files -g -r 100 -o song_mammals.bootstrapped.gs.astral.tre
这时候我们需要更多的genetree replicates。如果是-g -r 100，对于某些gene那可能需要150 replicates。因为在genes resampled的时候，一些gene抽到的概率会比其他的gene更多。
gene-only resampling
astral展开gene-only bootstrapping 用--gene-only的option。这个只要one inputfile。用-i 参数就可以了，对于这个就不要使用-b参数。
java -jar ../astral.5.6.3.jar -i song_mammals.424.gene.tre --gene-only -o song_mammals.bootstrapped.go.astral.tre
由于引导涉及一个随机的过程，我们可以提供一个seed number给astral 保证重复性。seed number 可以有-s进行设置。默认的参数是692.
the search space of astral
exact version
astral 有exact 和heuristic 的version。当taxa的数目较少的时候，exact version 会节约时间。但是分类不能超过37个。
java -jar astral.5.6.3.jar -i test_data/song_primates.424.gene.tre -o test_data/song_primates.424.exact.tre -x
-x参数就是开启exact version。大约30秒。同样的，我们可以使用默认的heuristic启发式搜索法
java -jar astral.5.6.3.jar -i test_data/song_primates.424.gene.tre -o test_data/song_primates.424.default.tre
这就只有1秒，那么他们的运行结果有何不同呢？其实是一致的
example what exact helps
The default primate dataset we used in the previous step had 424 genes and 14 taxa. Since we have a relatively large number of gene trees, we could reasonably expect the exact and heuristic versions to generate identical output. The key point here is that as the number of genes increases, the probability that each bipartition of the species tree appears in at least one input gene tree increases. Thus, with 424 genes all bipartitions from the species tree are in at least one input gene tree, and therefore, the exact and the heuristic versions are identical.
We tried hard to find a subset of genes in the biological primates dataset where the exact and the heuristic versions did not match. We couldn't! So we had to resort to simulations. We simulated a 14-taxon dataset with extreme levels of ILS (average 87% RF between gene trees and the species tree). Now, with this simulated dataset, if you take only 10 genes, something interesting happens.
运行：
java -jar astral.5.6.3.jar -i test_data/simulated_14taxon.gene.tre -o test_data/simulated_14taxon.default.tre
astral.5.6.3.jar -i test_data/simulated_14taxon.gene.tre -o test_data/simulated_14taxon.exact.tre -x
这时得分会有一点不同，topology也会不同。因此，在极端的情况下（ILS水平较高，genetree错误较多或者较分类来说可用的genetrees较少比如14类群只有10个gene，较之前的424gene就是较少）。那么就可以观察到两种算法的差异。
providing astral with extra trees
为了expand search space ，运行：
java -jar astral.5.6.3.jar -i test_data/simulated_primates_5X.10.gene.tre -o test_data/simulated_primates_5X.10.species.tre -e test_data/simulated_primates_5X.10.bootstrap.gene.tre
这里的-e参数用于输入一组extra trees 用于扩展astral的搜索空间。这个文件为10个simulated genes提供了200 bootstrap replicates 。-f 用于当input tree 有species labels代替gene label 的时候。
memory
大数据集（>500taxa）增加memory available to java。
run
java -Xmx3000M -jar astral.5.6.3.jar -i in.tree
其他参数
-m: 移除含有少于指定叶子数量的gene。对于需要一定分类级别的taxon occupancy 是有用的。后面设置数量。
-k completed : To build the set X (and not to score the species tree), ASTRAL internally completes the gene trees. To see these completed gene trees, run this option. This option is usable only when you also have -o（不懂）
-k bootstrapped 和-k bootstraps_norun:these options output the bootstrap replicate inputs to ASTRAL. These are useful if you want to run ASTRAL separately on each bootstrap replicate on a cluster.
-k searchspace_norun:输出search space然后退出。
----polylimit：
--samplingrounds：For multi-individual datasets, this option controls how many rounds of individual sampling is used in building the constraint set. Adjust to reduce/increase the search space for multi-individual datasets
文章参考：[https://github.com/smirarab/ASTRAL/blob/master/astral-tutorial.md#running-on-a-multi-individual-datasets]
