Trees argument

By default, from every starting tree, POY will only store one resulting tree. That is, if you do:
```
build (1)            
```
```
swap ()
```
You are guaranteed to end with one tree in memory. What about other trees of the same cost that could be found during the search? In order to increase the number of trees held in memory, after swap, you can use the trees argument:
```
use ("initial")            
```
```
select (best:1)            
```
```
report (treestats)            
```
```
swap (trees:10)
```
Did you get more than one tree at the end?
We can also keep suboptimal trees in memory by using the threshold argument. This allow us to find trees that are at most some number of steps longer than the current optimum. For example, try the following:
```
use ("initial")            
```
```
select (best:1)            
```
```
swap (threshold:20, trees:10)            
```
```
report (treestats)
```
How many trees did you get? What are the minimum and maximum lengths?
Now we will use the argument timeout. We are preparing a talk that starts in 5 minutes, and only have 3 minutes to run the analysis, and then only 2 to prepare the slides! So we decide to build 3 trees, and then swap for 60 seconds each, here is how we would do it:
```
use ("initial")            
```
```
select (best:3)            
```
```
swap (timeout:60)            
```
```
report (treestats)            
```
```
select ()            
```
```
report ("graphic_trees.ps", graphtrees)
```
The argument timeout will stop the search on each tree after 60 seconds, and the result will be the best tree found in that short amount of search. Finally we have the best tree in a file to prepare the slide.

Let's continue with the same scenario. This time you decide to let it run for as long as it can, and stop it manually. For this case, the recover argument is useful:

use ("initial")

select (best:3)

report (treestats)

swap (recover)

(* Now let it swap for a little bit so that POY finds some better trees. Then interrupt it with <C-c>. *)

recover ()

report (treestats)

select ()

Same scenario again. This time, you find that your initial trees are not that bad, and you would like to swap only on those trees that resolve the strict consensus produced by the best three trees. To do this we use the constraint argument:
```
use ("initial")            
```
```
select (best:3)            
```
```
swap (constraint)
```
You can also provide a constraint file from an input file. Let's try that setup. First create the consensus file:
```
use ("initial")            
```
```
select (best:3)            
```
```
report ("constraint.txt", consensus)
```
Now open the constraint.txt file and delete the title at the beginning. We are ready to proceed with the swap:
```
swap (constraint:("constraint.txt"), timeout:10)
```
Notice that this time we have also added a timeout of 10 minutes. The main difference between using the constraint file in this way with the automated constraint in the previous item is that the reported consensus tree collapse zero length branches.
Same scenario, but this time ... ehm ... POY is crashing. You don't know what could be the problem, and Andrés has not been able to fix it soon enough. There is a nice argument called trajectory which allows swap to print every better tree found during the search. You can now give it a try:
```
use ("initial")            
```
```
swap (trajectory)
```

OK, printing on the screen is useful, but the program is crashing! So I still loose the results! No problem, just output the trees in a file:

use ("initial")

swap (trajectory:"trees_of_swap.txt")

(* Let it run for few minutes and then cancel with <C-c> *)

read ("trees_of_swap.txt")

report (treestats)

(* We have all the trees of the trajectory plus the initial trees before the swap *)

select ()

Trajectory only reports a tree if its better than the current best. How about all the trees that have been evaluated? This is a useful command for Bremer support calculations (which we will learn later). Let's give that argument a try. We will ask POY to print the trees in the visited_trees.txt file:
```
use ("initial")
```
```
swap (visited)
```
```
(* Wow! many trees on screen! Cancel it with <C-c> *)            
```
```
swap (visited:"visited_trees.txt")            
```
```
(* Let it run for few _seconds_ and then cancel it with <C-c> *)            
```
```
read ("visited_trees.txt")            
```
```
report (treestats)
```
Observe that we have lots of trees in memory now. visited collect every tested tree during the search. This is a lot! If you let it run long enough, visited will produce file of several Gigabytes. So beware, don't try to read one of those files directly into POY, either it will take a long time to finish, or it will just run out of memory and it is not really the program's fault.
To finalize this tutorial, complete the TBR swap on your initial 20 trees and store the resulting trees in the file tbr_trees.tree.