Package: draupnir
DRAUPNIR: "Beta library version for performing ASR using a tree-structured Variational Autoencoder"Extra requirements for tree inference:#These are NOT necessary if you have your own tree file or for using the default datasetsIQ-Tree:http://www.iqtree.org/doc/Quickstartconda install -c bioconda iqtreeRapidNJ:https://birc.au.dk/software/rapidnjconda config --add channels bioconda
conda install rapidnjExtra requirements for fast patristic matrix construction#Recommended if you have more than 200 sequences. The patristic matrix is constructed only onceInstall R (R version 4.1.2 (2021-11-01) -- "Bird Hippie"
)sudo apt update & sudo apt upgrade
sudo apt -y install r-basetogether with ape 5.5 and TreeDist 2.3 librariesinstall.packages(c("ape","TreeDist"))Draupnir pip installpip install draupnirExampleSee Draupnir_example.pyWhich guide to use?By experience, use delta_map, since the marginal results (Test folder) are the most stable.
It is recommended to run the model both with the variational and the delta_map guides and compare outputs using the mutual information.
If necessary, run the variational guide longer than the delta_map, since it has more parameters to optimize and takes longer.How long should I run my model?Before training:It is recommended to train for at least 10000 epochs in datasets <800 leaves. See article for inspiration, the runtimes where extended to achieve maximum benchmarking accuracy, but it should not be necessary.While it is training:Check for the Percent_ID.png plot, if the training accuracy has peaked to almost 100%, run for at least ~1000 epochs more to guarantee full learningCheck for stabilization of the error loss: ELBO_error.pngCheck for stabilization of the entropy: Entropy_convergence.pngAfter training:Observe the latent space:t_SNE, UMAP and PCA plots: Is it organized by clades? Although, not every data set will present tight clustering of the tree clades though but there should be some organizationDistances_GP_VAE_z_vs_branch_lengths_Pairwise_distance_INTERNAL_and_LEAVES plot: Is there a positive correlation? If there is not a good correlation but the train percent identity is high, it will still be a valid runObserve the sampled training (leaves) sequences and test (internal) sequences: Navigate to the Train_argmax and Test_argmax folders and look for the .fasta filesCalculate mutual information:First: Run Draupnir with the MAP & Marginal version and Variational version, or just the VariationalSecond: Use the draupnir.calculate_mutual_information() with the paths to the folders with the trained runs.Datasets#They are recommended to use with the pipeline, look into datasets.py for more detailsdict_urls = {
        "aminopeptidase":"https://drive.google.com/drive/folders/1fLsOJbD1hczX15NW0clCgL6Yf4mnx_yl?usp=sharing",
        "benchmark_randall_original_naming":"https://drive.google.com/drive/folders/1oE5-22lqcobZMIguatOU_Ki3N2Fl9b4e?usp=sharing",
        "Coral_all":"https://drive.google.com/drive/folders/1IbfiM2ww5PDcDSpTjrWklRnugP8RdUTu?usp=sharing",
        "Coral_Faviina":"https://drive.google.com/drive/folders/1Ehn5xNNYHRu1iaf7vS66sbAESB-dPJRx?usp=sharing",
        "PDB_files_Draupnir_PF00018_116":"https://drive.google.com/drive/folders/1YJDS_oHHq-5qh2qszwk-CucaYWa9YDOD?usp=sharing",
        "PDB_files_Draupnir_PF00400_185": "https://drive.google.com/drive/folders/1LTOt-dhksW1ZsBjb2uzi2NB_333hLeu2?usp=sharing",
        "PF00096":"https://drive.google.com/drive/folders/103itCfxiH8jIjKYY9Cvy7pRGyDl9cnej?usp=sharing",
        "PF00400":"https://drive.google.com/drive/folders/1Ql10yTItcdX93Xpz3Oh-sl9Md6pyJSZ3?usp=sharing",
        "SH3_pf00018_larger_than_30aa":"https://drive.google.com/drive/folders/1Mww3uvF_WonpMXhESBl9Jjes6vAKPj5f?usp=sharing",
        "simulations_blactamase_1":"https://drive.google.com/drive/folders/1ecHyqnimdnsbeoIh54g2Wi6NdGE8tjP4?usp=sharing",
        "simulations_calcitonin_1":"https://drive.google.com/drive/folders/1jJ5RCfLnJyAq0ApGIPrXROErcJK3COvK?usp=sharing",
        "simulations_insulin_2":"https://drive.google.com/drive/folders/1xB03AF_DYv0EBTwzUD3pj03zBcQDDC67?usp=sharing",
        "simulations_PIGBOS_1":"https://drive.google.com/drive/folders/1KTzfINBVo0MqztlHaiJFoNDt5gGsc0dK?usp=sharing",
        "simulations_sirtuins_1":"https://drive.google.com/drive/folders/1llT_HvcuJQps0e0RhlfsI1OLq251_s5S?usp=sharing",
        "simulations_src_sh3_1":"https://drive.google.com/drive/folders/1tZOn7PrCjprPYmyjqREbW9PFTsPb29YZ?usp=sharing",
        "simulations_src_sh3_2":"https://drive.google.com/drive/folders/1ji4wyUU4aZQTaha-Uha1GBaYruVJWgdh?usp=sharing",
        "simulations_src_sh3_3":"https://drive.google.com/drive/folders/13xLOqW2ldRNm8OeU-bnp9DPEqU1d31Wy?usp=sharing"

    }DatasetNumber of leavesAlignment lenghtNameRandall's Coral fluorescent proteins (CFP)19225benchmark_randall_original_namingCoral fluorescent proteins (CFP) Faviina subclade35361Coral_FaviinaCoral fluorescent proteins (CFP) subclade71272Coral_allSimulation $\beta$-Lactamase32314simulations_blactamase_1Simulation Calcitonin5071simulations_calcitonin_1Simulation SRC-Kinase SH3 domain10063simulations_src_sh3_1Simulation Sirtuin150477simulations_sirtuins_1Simulation SRC-kinase SH3 domain200128simulations_src_sh3_3Simulation PIGBOS30077simulations_PIGBOS_1Simulation Insulin400558simulations_insulin_2Simulation SRC-kinase SH3 domain80099simulations_src_sh3_2What do the results folders mean?If you selecteddelta_mapguide:Train_Plots: Contains information related to the inference of the train sequences (the leaves). They aresamplesobtained by using the marginal probability approach (equation 5 in the paper).Train_argmax_Plots: Single sequence per leaf obtained by the using the most likely amino acids indicated by the marginal logits ("argmax the logits")Test_Plots: Samples for the test sequences (ancestors). In this case they contain the sequences sampled using themarginal probabilityapproach (equation 5 in the paper)Test_argmax_Plots: Contains the most voted sequence from the samples in Test_Plots.Test2_Plots: Samples for the test sequences (ancestors). In this case they contain the sequences sampled using theMAP estimatesof the logits.Test2_argmax_Plots:  Samples for the test sequences (ancestors). In this case they contain the most likely amino acids indicated by the MAP logits ("argmax the logits") (equation 4 in the paper)If you selectedvariationalguide:Train_Plots: Contains information related to the inference of the train sequences (the leaves). They aresamplesobtained from sampling from the variational posterior (equation 6 in the paper).Train_argmax_Plots: Single sequence per leaf obtained by the using the most likely amino acids indicated by the logits ("argmax the logits")Test_Plots: Samples for the test sequences (ancestors). In this case they contain the sequences sampled using the full variational probability approach (equation 6 in the paper)Test_argmax_Plots: Contains the most voted sequence from the samples in Test_Plots.Test2_Plots == Test_PlotsTest2_argmax_Plots == Test_argmax_PlotsWhere are my ancestral sequences?In each of the folders there should be a fasta file _sampled_nodes_seq.fastaEach of the sequences in the file should be identified as //_sample_-Node-name-input-tree: Original name of the node in the given input tree-Tree-level-order: Position of the node in tree-level order in the treeNode_A1//1.0_sample_0If this library is useful for your research please cite:@inproceedings{moreta2021ancestral,
  title={Ancestral protein sequence reconstruction using a tree-structured Ornstein-Uhlenbeck variational autoencoder},
  author={Moreta, Lys Sanz and R{\o}nning, Ola and Al-Sibahi, Ahmad Salim and Hein, Jotun and Theobald, Douglas and Hamelryck, Thomas},
  booktitle={International Conference on Learning Representations},
  year={2021}
}Do not hesitate to give input on how to improve the documentation of this library