Admixtools 2 shiny app

[kolompar]

Admixtools 2 is the R implementation of Admixtools, the number one software package used for ancient DNA population genomics analyses. It is faster, simple to use, and has some features not available in the original Admixtools. It also includes an ambitious simple point-and-click grapchical user interface, the "shiny app".
Unfortunately the app has a few bugs here and there, and its development seems to have been abandoned, but we can collect instructions, tips and tricks, and constructive criticism of it here in case someone needs it.

[kolompar]

To start, call run_shiny_admixtools()
It should open the app in your default web browser. My version has Admixtools 2 written in the top left in Comic Sans - a good omen.

First you are on the data tab. Here you can load a folder where you have pre-extracted f2-stats. (You need to create them with extract_f2. A problem here is if you have a large number of populations with missing data there will be very few SNPs that are shared between all of them, and if you use different SNPs for each pair the results could be biased. I don't think there's a concrete solution to this, choose high coverage populations and maxmiss between 0 and 1. Read more here https://uqrmaie1.github.io/admixtools/ar...tml#biases)
After successfully loading your folder, your populations will appear in squeezed boxes on the page. I have no idea what that is for.
There used to be an option to load a geno file, but that was only useful with small files like if you have extracted your populations. For a big file like the AADR it loaded forever and couldn't be used. I think "Extract settings" is intended for that.

Then you can use the other tabs, which are rather self-evident. Warning, the f-stats look like they will calculate all possible combinations once you click on them, so if you have a large number of populations be careful. Some of them give errors.
Sometimes clicking on a tab will give you a pop-up error after which sometimes the app can't be used anymore. The usual way the app crashes is the screen goes gray, you can then see on the R console there was an error. In this case you have to stop the function in R (press ESC or click STOP button) and start over. This happens a lot.
Do not attempt to compare with a file in qpAdm, this crashes the app. Be careful where you click, as anything will immediately start the calculation (or crash the app).

The main appeal of the app would be qpGraph and its graph editor. By default you get a random graph with all populations, but it isn't showing until you click Evaluate graph. Don't click that unless you have very few populations. It will take forever and the graph is useless anyway.
The best way to use it is to load a small premade graph. The only format it seems to accept is edge list. It should be able to read ADMIXTOOLS format but they crash the app, it definitely can't read DOT. If you have a graph saved in that format you might try to edit it to the other format but that probably just makes the whole experience even more frustrating.
A small graph would be something like this, saved in a text file:

Code:

from to lower upper
Root Mbuti.DG NA NA
Root X NA NA
X Czechia_ZlatyKun_IUP.AG.SG NA NA
X IUP NA NA
IUP Bulgaria_BachoKiro_IUP.AG.BY.AA NA NA

Once you load it, and you didn't get an error on the right side under f2, you can click Evaluate graph and the graph should appear. Before you do anything else, it's best to uncheck Evaluate graph. Be careful with clicking Similar on the right, it might immediately calculate hundreds of graphs. Watch out for not leaving the tab selected. I don't know what Compare or Resample is for. Best to leave it on Fit.

From here you can start building your graph. Go to Modify on the left.

• To add a population, choose it from the drop-down list, click on the EDGE you want to place it on your graph and click Add. The Selected field should show one edge, anything else and the app crashes. You can clear the selection with the Clear button. Watch out, don't click randomize.
  
• To add an edge, click on the edge on your graph from where you want it, then click on the edge to where you want it, then Add. Once again, select edges only, not nodes.
  
• To delete a population click the pop name itself on the graph and then Delete. Don't click the edge leading to it, that will cause a crash. You might be able to select and Delete multiple populations at the same time, or it migth cause a crash. Looks like the app also crashes if there's <=2 populations left on the graph.
  
• To delete an admixture edge, click the edge itself. Only try admixture edges, anything else crashes the app, you need to click the middle of the edge. If the graph has a lot going on you can zoom into it to do that.
  
• Sometimes if the graph is large (or there's a circle in it?) trying to delete or add anything causes a crash with an "infinite recursion" error.
  
• Once you added everything, you can try to Optimize. It's one place where you HAVE to check Evaluate graph before Run, or it won't save the graph it finds even if it has a better score. Choose the options as you want. "min seconds" seems to be actually max seconds, after which optimize stops. Don't know about # generations, I just set each to 1000. Watch out if you worked with a graph don't select start randomly. If I'm sure in my outgroup I uncheck change root, if my graph looks good I usually only select mutate n which has a better chance to knock out the graph from a local optimum.
  
• Constrain might be useful. Compare once again crashes it. Plot options Highlight unidentifiable and Fit return_fstats (to return fitted f4) are also helpful.
  
• There's a History tab on the right, you can update and revert a graph at Fit. Usually either the app crashes or I've had enough before I use these. If you want to save just do it in Edge list format.
  
  

A real experience:

1. Download graph from forum.
   
2. Spend hour editing pop names in graph or ind file.
   
3. Extract pops.
   
4. Stop extract, edit maxmiss to have more SNPs.
   
5. Run shiny admixtools, load folder.
   
6. Try to load graph crash.
   
7. Check if correct format. Delete most of it to see it loads.
   
8. Try deleting only parts of it to see what's the problem. Get an error if I left an internal node as a leaf that there's no such population. Sometimes with a popup after which the app evaluates a random graph.
   
9. Shut down app, try again several times.
   
10. Eventually find a space at the end of a line that seems to be it. Check every line.
    
11. No, there's also something else.
    
12. It was Kostenki, for unknown reason. Maybe too long name? Bacho Kiro is the same length.
    
13. Fix it, load graph.
    
14. Try to add another pop, crash.
    
15. Try to delete something, crash.
    
16. Is the graph too big? Editing the file, do 8 again for another hour.
    
17. Strip down the graph to the bare minimum, still unusable.
    
18. Check with return fstats, thousands of significant f4-stats so just leave it.
    
19. Try to build own graph. Crash...