README draft.

Author: schmidt73

README.md

@@ -0,0 +1,91 @@
+# fastBE: A regression based approach to phylogenetic reconstruction from bulk DNA sequencing of tumors
+
+*fastBE* is a method for inferring the evolutionary history
+of tumors from multi-sample bulk DNA sequencing data.
+Our method uses ideas from distance based phylogenetics and 
+a handcrafted solver of the variant allele frequency 
+$\ell_1$-regression problem.
+
+![overview](docs/overview.png)
+
+If you find this tool useful in your research, please cite us at:
+```
+```
+
+## Installation
+
+`fastBE` is implemented in C++ and is packaged with the dependencies
+needed to execute the program. In particular, the only dependencies are
+a recent version of CMAKE and a modern C++17 compliant compiler.
+
+To build `fastBE` from source, first clone the repository and its submodules:
+```
+$ git clone --recurse-submodules https://github.com/schmidt73/fastbe.git
+```
+
+Then from the root of the project directory, execute the following sequence o
+commands:
+```
+$ mkdir build; cd build
+$ cmake ..
+$ make
+```
+The output binary will be located at `build/src/fastbe`.
+
+## Usage
+
+To run *fastbe*, simply execute the binary. 
+```
+Usage: fastbe [--help] [--version] {regress,search}
+
+Optional arguments:
+  -h, --help     shows help message and exits 
+  -v, --version  prints version information and exits 
+
+Subcommands:
+  regress       Regresses a clone tree onto a frequency matrix.
+  search        Searches for a clone tree that best fits a frequency matrix.
+```
+
+### Input format
+
+The input format for *fastbe* consists of a frequency matrix $F$
+in TXT format. Rows are separated by newlines
+and columns are separated by spaces. Rows correspond
+to distinct samples and columns correspond to distinct mutation clusters.
+More formally, $F_{ij}$ is the frequency of the $j^{\text{th}}$ mutation
+cluster in the $i^{\text{th}}$ sample. As an example, a frequency matrix $F$ 
+describing 20 samples and 10 clones is:
+```
+1.0000 0.9801 0.0000 0.8265 0.0156 0.3683 0.2450 0.1218 0.1260 0.0000
+1.0000 1.0000 0.0000 0.1257 0.0000 0.0000 0.0000 0.0000 0.0000 0.1436
+1.0000 0.5202 0.0000 0.4053 0.5045 0.0000 0.0000 0.1945 0.0000 0.0000
+1.0000 0.3497 0.6616 0.1302 0.0000 0.0000 0.0000 0.1558 0.0000 0.0000
+1.0000 0.7233 0.1356 0.5780 0.1640 0.0574 0.0785 0.2873 0.0728 0.1083
+1.0000 0.8394 0.0646 0.8530 0.0000 0.0000 0.0000 0.0000 0.0000 0.8353
+1.0000 0.1309 0.6547 0.0000 0.0174 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.4203 0.1889 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.2731 0.1406 0.2768 0.4452 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.5346 0.4651 0.5437 0.0000 0.0000 0.0000 0.1311 0.1069 0.0000
+1.0000 0.1043 0.0000 0.1258 0.7614 0.0000 0.0000 0.0566 0.0685 0.0562
+1.0000 0.8784 0.0000 0.3935 0.0122 0.0000 0.0124 0.2469 0.2382 0.1668
+1.0000 1.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.9163 0.0412 0.8878 0.0348 0.1197 0.1299 0.6229 0.4443 0.0010
+1.0000 0.9130 0.0418 0.6500 0.0458 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.8923 0.0000 0.9118 0.0000 0.0000 0.0000 0.9092 0.0000 0.0000
+1.0000 0.9318 0.0000 0.9369 0.0704 0.0000 0.0000 0.8478 0.8136 0.0000
+1.0000 0.4489 0.3422 0.4024 0.1828 0.0270 0.0000 0.3257 0.3120 0.0350
+1.0000 0.9753 0.0000 0.8931 0.0000 0.5100 0.0506 0.0682 0.0000 0.1435
+1.0000 1.0000 0.0000 1.0000 0.0000 0.0000 1.0000 0.0000 0.0000 0.0000
+```
+
+The above frequency matrix is provided as an input file at `examples/sim_obs_frequency_matrix.txt`.
+The above frequency matrix was generated using the command,
+`python scripts/simulation.py --clones 20 --samples 10 --coverage 100 --seed 0 --mutations 100 --output examples/sim`
+which simulates the evolution of a tumor with 7 mutation clusters (equivalently, clones) and 20 samples at a 
+read depth of 100$\times$ and 100 mutations distribution across the 10 mutation clusters.
+Several other files such as the mutation to clone mapping, the ground truth usage matrix $U$, clonal
+matrix $B$, and read count matrices are also provided in the `examples/` directory.
+
+## Usage Example
+

docs/overview.png

@@ -0,0 +1,10 @@
+1 0 0 0 0 0 0 0 0 0
+1 1 0 0 0 0 0 0 0 0
+1 0 1 0 0 0 0 0 0 0
+1 1 0 1 0 0 0 0 0 0
+1 0 0 0 1 0 0 0 0 0
+1 1 0 1 0 1 0 0 0 0
+1 1 0 1 0 0 1 0 0 0
+1 1 0 1 0 0 0 1 0 0
+1 1 0 1 0 0 0 1 1 0
+1 1 0 1 0 0 0 0 0 1

examples/sim_clonal_matrix.txt

@@ -0,0 +1,20 @@
+1313 904 797 1366 1343 945 498 1026 722 1006
+1318 900 830 1368 1422 955 506 1005 674 996
+1280 915 770 1362 1429 1009 461 1023 684 997
+1308 935 789 1383 1439 972 508 1027 657 1030
+1321 889 804 1448 1378 940 535 978 701 988
+1325 928 790 1361 1387 1010 493 1008 691 1038
+1271 863 811 1439 1381 1032 480 923 733 1015
+1297 897 826 1436 1346 998 493 976 747 999
+1303 897 811 1351 1413 1000 543 1015 708 1031
+1324 911 789 1429 1438 962 487 999 739 980
+1265 882 797 1415 1421 988 477 990 657 1032
+1253 855 805 1395 1395 1013 484 1049 697 971
+1301 895 721 1392 1435 1055 532 947 686 986
+1395 896 898 1444 1378 994 508 1082 673 987
+1302 931 814 1360 1376 973 496 948 668 1031
+1297 873 817 1360 1410 989 500 1002 641 1028
+1364 938 786 1394 1421 997 497 999 676 1027
+1363 920 786 1394 1417 999 479 921 718 1029
+1247 931 793 1347 1346 998 514 997 739 1031
+1303 896 749 1379 1399 1038 512 963 734 1046

examples/sim_collapsed_total_matrix.txt

@@ -0,0 +1,20 @@
+1313 886 0 1129 21 348 122 125 91 0
+1318 900 0 172 0 0 0 0 0 143
+1280 476 0 552 721 0 0 199 0 0
+1308 327 522 180 0 0 0 160 0 0
+1321 643 109 837 226 54 42 281 51 107
+1325 779 51 1161 0 0 0 0 0 867
+1271 113 531 0 24 0 0 0 0 0
+1297 377 156 0 0 0 0 0 0 0
+1303 245 114 374 629 0 0 0 0 0
+1324 487 367 777 0 0 0 131 79 0
+1265 92 0 178 1082 0 0 56 45 58
+1253 751 0 549 17 0 6 259 166 162
+1301 895 0 0 0 0 0 0 0 0
+1395 821 37 1282 48 119 66 674 299 1
+1302 850 34 884 63 0 0 0 0 0
+1297 779 0 1240 0 0 0 911 0 0
+1364 874 0 1306 100 0 0 847 550 0
+1363 413 269 561 259 27 0 300 224 36
+1247 908 0 1203 0 509 26 68 0 148
+1303 896 0 1379 0 0 512 0 0 0

examples/sim_collapsed_variant_matrix.txt

@@ -0,0 +1,101 @@
+mutation,clone
+4,0
+21,0
+24,0
+33,0
+37,0
+44,0
+45,0
+65,0
+83,0
+88,0
+90,0
+95,0
+98,0
+5,1
+14,1
+28,1
+34,1
+52,1
+56,1
+57,1
+84,1
+91,1
+1,2
+25,2
+41,2
+43,2
+64,2
+92,2
+94,2
+97,2
+6,3
+20,3
+22,3
+26,3
+29,3
+30,3
+31,3
+40,3
+61,3
+66,3
+74,3
+79,3
+87,3
+96,3
+9,4
+19,4
+38,4
+46,4
+51,4
+53,4
+69,4
+70,4
+72,4
+73,4
+75,4
+76,4
+78,4
+93,4
+0,5
+15,5
+23,5
+47,5
+48,5
+67,5
+81,5
+82,5
+85,5
+89,5
+2,6
+10,6
+49,6
+62,6
+71,6
+8,7
+11,7
+12,7
+32,7
+39,7
+42,7
+58,7
+63,7
+80,7
+99,7
+7,8
+13,8
+17,8
+27,8
+50,8
+55,8
+77,8
+3,9
+16,9
+18,9
+35,9
+36,9
+54,9
+59,9
+60,9
+68,9
+86,9

examples/sim_mutation_to_clone_mapping.txt

@@ -0,0 +1,20 @@
+1.0000 0.9801 0.0000 0.8265 0.0156 0.3683 0.2450 0.1218 0.1260 0.0000
+1.0000 1.0000 0.0000 0.1257 0.0000 0.0000 0.0000 0.0000 0.0000 0.1436
+1.0000 0.5202 0.0000 0.4053 0.5045 0.0000 0.0000 0.1945 0.0000 0.0000
+1.0000 0.3497 0.6616 0.1302 0.0000 0.0000 0.0000 0.1558 0.0000 0.0000
+1.0000 0.7233 0.1356 0.5780 0.1640 0.0574 0.0785 0.2873 0.0728 0.1083
+1.0000 0.8394 0.0646 0.8530 0.0000 0.0000 0.0000 0.0000 0.0000 0.8353
+1.0000 0.1309 0.6547 0.0000 0.0174 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.4203 0.1889 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.2731 0.1406 0.2768 0.4452 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.5346 0.4651 0.5437 0.0000 0.0000 0.0000 0.1311 0.1069 0.0000
+1.0000 0.1043 0.0000 0.1258 0.7614 0.0000 0.0000 0.0566 0.0685 0.0562
+1.0000 0.8784 0.0000 0.3935 0.0122 0.0000 0.0124 0.2469 0.2382 0.1668
+1.0000 1.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.9163 0.0412 0.8878 0.0348 0.1197 0.1299 0.6229 0.4443 0.0010
+1.0000 0.9130 0.0418 0.6500 0.0458 0.0000 0.0000 0.0000 0.0000 0.0000
+1.0000 0.8923 0.0000 0.9118 0.0000 0.0000 0.0000 0.9092 0.0000 0.0000
+1.0000 0.9318 0.0000 0.9369 0.0704 0.0000 0.0000 0.8478 0.8136 0.0000
+1.0000 0.4489 0.3422 0.4024 0.1828 0.0270 0.0000 0.3257 0.3120 0.0350
+1.0000 0.9753 0.0000 0.8931 0.0000 0.5100 0.0506 0.0682 0.0000 0.1435
+1.0000 1.0000 0.0000 1.0000 0.0000 0.0000 1.0000 0.0000 0.0000 0.0000

examples/sim_obs_frequency_matrix.txt

@@ -0,0 +1,20 @@
+97 95 97 97 95 94 92 110 108 96 92 99 99 98 98 100 105 112 89 87 118 100 114 97 99 102 88 101 88 87 84 83 113 98 102 108 94 100 102 104 83 120 107 94 98 101 101 103 84 83 111 100 101 102 96 96 94 110 96 110 105 104 112 98 107 97 98 92 106 86 91 114 97 86 87 95 109 94 96 102 101 95 88 106 103 98 96 126 88 91 131 114 93 95 89 95 100 97 105 101
+88 104 99 102 100 98 106 94 107 91 117 98 104 117 110 111 114 95 101 96 86 93 86 94 102 102 92 88 104 116 98 99 98 106 95 103 105 94 104 98 103 103 105 111 98 105 102 86 83 93 89 95 78 114 91 90 103 115 99 100 85 99 92 97 105 116 95 111 93 102 101 105 114 114 96 108 104 101 88 91 95 98 81 97 95 113 102 104 101 90 97 102 103 89 95 111 97 107 98 104
+105 97 81 91 109 107 90 101 83 92 97 98 119 103 119 91 106 103 99 104 105 83 83 103 107 88 80 95 103 88 107 112 83 108 99 105 103 102 106 88 112 87 92 106 99 92 104 96 102 90 93 138 90 96 105 76 100 83 119 94 106 93 90 120 107 108 84 107 102 102 78 103 107 104 107 108 89 113 92 97 109 95 114 98 105 103 86 100 100 93 98 109 82 109 106 106 104 97 70 112
+91 75 102 117 119 102 86 86 101 109 106 92 107 91 119 113 87 92 104 98 117 114 101 95 93 100 95 97 99 118 99 91 101 111 116 104 116 90 87 108 107 97 105 97 92 80 94 86 93 89 99 115 96 106 91 92 82 111 96 106 89 102 92 97 121 100 89 92 106 96 104 119 115 103 71 108 96 100 103 103 107 93 116 92 107 105 110 104 102 88 108 103 94 105 104 109 100 101 98 113
+108 87 104 97 96 99 103 95 91 122 116 93 104 94 117 85 89 88 101 91 115 87 120 95 97 96 106 117 87 92 92 106 101 102 91 108 101 96 91 104 92 109 83 91 101 118 90 83 100 99 110 108 103 107 86 106 114 109 109 107 110 117 98 99 101 105 93 104 94 104 98 118 88 88 127 93 101 91 112 97 106 88 99 116 93 96 95 94 91 82 102 76 122 85 90 114 94 108 96 88
+97 88 89 102 107 94 92 92 97 88 95 97 86 109 100 104 111 90 98 112 108 100 93 109 108 106 109 96 99 100 95 99 108 105 105 112 92 87 96 99 105 100 96 101 109 107 94 110 92 103 105 95 104 93 111 96 98 103 107 107 99 97 109 89 91 103 91 111 103 91 103 97 121 86 99 105 108 103 92 96 117 99 104 112 123 109 103 77 98 75 96 102 105 103 108 86 100 91 107 112
+120 94 97 97 101 96 102 124 92 112 97 95 94 104 74 108 105 98 100 104 99 106 96 104 92 105 106 94 98 97 104 106 102 85 104 114 113 122 104 103 108 102 91 104 91 92 79 89 100 98 100 80 97 112 96 103 106 91 84 100 100 86 83 78 99 106 117 98 103 108 86 105 97 85 86 114 100 110 110 112 93 91 98 95 92 118 87 116 99 106 106 105 108 90 103 90 104 96 86 91
+92 119 103 88 85 103 96 94 98 109 106 109 97 131 111 111 113 118 100 101 105 111 124 88 88 96 96 79 111 93 102 93 101 105 88 86 106 84 109 105 104 99 102 101 107 109 92 92 94 87 88 101 108 91 110 108 83 89 89 101 88 100 101 89 102 103 90 96 102 102 90 96 98 88 105 100 93 129 83 104 82 106 117 106 97 97 105 100 98 105 96 107 99 89 107 104 124 103 101 104
+105 99 123 97 97 90 99 95 111 110 105 109 102 107 102 125 98 102 91 117 86 101 98 117 95 92 88 118 96 104 99 94 110 99 102 112 125 81 106 99 106 117 97 107 122 99 90 82 97 103 93 95 120 90 90 108 106 88 94 97 120 101 113 101 86 107 100 85 108 95 106 99 87 105 87 101 108 85 107 97 99 99 100 93 103 102 93 100 101 88 109 90 116 96 107 114 92 87 85 93
+85 114 93 111 99 108 92 120 108 118 104 96 103 88 107 93 99 110 88 105 107 99 101 68 102 76 99 117 85 121 96 94 120 89 104 107 94 110 87 87 115 101 93 99 110 92 98 88 99 97 95 125 104 100 106 101 97 105 94 96 83 95 94 99 95 102 106 97 98 127 102 99 89 99 106 88 94 108 108 91 113 120 112 114 97 88 98 101 111 112 99 104 96 98 104 114 105 104 83 86
+97 101 99 124 92 96 96 99 105 107 89 78 122 86 102 100 87 95 91 84 95 102 102 107 87 95 110 104 111 112 94 86 92 95 102 119 101 108 112 104 103 96 86 94 113 92 116 92 94 85 101 101 99 114 96 90 95 85 101 111 100 107 104 106 91 100 107 96 109 100 102 100 99 76 115 99 108 82 106 89 99 111 94 87 91 106 94 103 114 91 86 101 105 97 110 86 96 105 103 97
+99 99 98 104 83 103 114 81 123 103 86 92 91 92 89 100 97 94 108 99 89 100 104 105 98 109 94 131 83 103 109 84 109 110 102 100 96 86 87 94 98 115 101 102 113 105 113 104 101 104 84 90 97 108 84 96 99 89 107 83 97 99 107 113 89 79 105 111 102 103 92 89 78 88 98 120 109 119 98 98 100 102 101 92 85 89 100 110 97 101 94 108 101 107 95 98 90 95 98 119
+100 85 108 97 87 101 109 83 92 102 108 94 105 94 97 84 108 97 110 99 92 95 95 114 103 99 108 105 112 96 98 89 102 87 94 73 102 96 107 82 99 97 101 83 101 113 105 106 102 92 102 113 91 92 93 99 116 85 83 101 108 99 99 89 89 106 75 115 111 90 105 125 98 112 112 116 106 106 92 112 95 109 116 93 110 114 83 111 105 95 119 89 96 98 93 102 97 79 94 104
+109 114 105 109 107 105 111 88 96 126 83 107 106 115 93 107 101 104 93 90 101 103 92 108 105 122 98 84 95 106 119 98 93 92 99 97 87 101 102 111 107 108 117 127 119 124 120 80 98 94 91 86 110 108 98 81 101 104 120 104 107 92 108 124 101 89 109 95 108 93 90 118 93 96 106 93 98 110 95 109 106 98 93 118 90 111 83 113 107 95 112 99 120 88 105 116 83 101 102 102
+107 112 104 111 93 85 95 99 97 90 89 93 78 89 107 77 94 100 113 67 90 100 87 115 98 107 93 109 105 96 83 99 104 104 110 97 111 98 101 90 92 101 111 94 97 108 89 99 84 97 98 91 98 98 96 82 88 115 94 102 107 121 113 89 113 109 105 85 96 81 125 93 95 95 102 125 105 91 116 106 90 110 105 101 111 84 104 103 103 107 86 112 101 98 104 108 88 82 97 102
+103 91 102 104 102 96 104 89 99 103 95 96 91 91 90 99 102 100 113 99 110 101 105 98 107 96 79 84 101 103 83 105 102 94 96 108 116 108 110 105 104 112 91 105 92 94 99 109 94 103 93 105 84 86 104 92 103 99 110 89 101 108 101 106 112 90 77 99 105 109 100 99 85 100 93 95 115 92 111 92 98 91 99 115 95 95 86 91 89 102 110 109 106 93 92 101 106 103 94 104
+102 111 111 107 109 93 101 93 96 116 89 78 99 99 104 92 104 79 124 94 106 98 112 95 105 108 97 94 113 101 102 83 98 102 99 92 106 98 88 96 108 100 101 94 120 114 118 131 102 102 98 96 99 99 94 112 115 95 106 103 103 94 95 106 75 98 107 85 103 86 108 100 96 109 98 88 120 101 110 75 111 105 93 102 112 91 91 90 118 101 98 108 91 93 95 104 120 112 98 108
+97 98 76 100 107 104 112 91 85 114 90 90 91 97 85 96 85 108 115 99 104 104 116 92 109 105 92 101 100 109 92 85 103 103 109 120 115 100 85 96 97 106 91 100 113 121 112 97 103 95 99 112 91 103 97 105 107 117 89 112 85 92 106 80 86 108 97 118 94 93 96 112 87 105 99 109 110 117 92 99 88 93 103 94 105 100 106 109 92 100 90 102 109 100 90 112 91 92 110 108
+92 98 111 88 92 97 85 121 107 98 98 107 112 100 101 97 96 91 101 106 83 98 109 92 107 93 95 110 107 103 85 110 87 85 107 106 115 87 100 92 82 98 115 120 86 94 79 98 96 89 112 104 94 99 100 93 100 112 98 103 109 108 109 95 91 102 87 105 100 94 97 107 76 93 97 87 103 112 90 99 95 140 86 114 97 98 113 95 90 94 109 116 94 120 93 93 109 106 90 89
+111 104 96 122 80 88 103 101 100 84 101 97 110 111 85 126 97 100 119 102 108 89 102 95 97 91 92 99 120 89 89 102 79 96 103 100 99 103 76 85 106 97 110 90 96 114 118 95 96 120 114 104 85 99 110 109 103 92 105 112 84 97 105 92 83 112 94 96 99 112 92 90 111 87 96 95 107 100 101 88 88 105 114 112 109 106 104 107 92 94 93 111 100 111 85 116 106 99 103 97

examples/sim_total_matrix.txt

@@ -0,0 +1,13 @@
+#scripts/simulation.py --clones 10 --samples 20 --coverage 100 --seed 0 --mutations 100 --output examples/sim
+# GMT Tue Oct 31 16:07:18 2023
+# 
+0 1 2 4
+1 3
+2
+3 5 6 7 9
+4
+5
+6
+7 8
+8
+9

examples/sim_tree.txt

@@ -0,0 +1,20 @@
+0.0000 0.1617 0.0000 0.0932 0.0200 0.3565 0.2528 0.0000 0.1157 0.0000
+0.0000 0.8569 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.1431
+0.0000 0.1205 0.0000 0.1786 0.4997 0.0000 0.0000 0.2011 0.0000 0.0000
+0.0000 0.1989 0.6621 0.0000 0.0000 0.0000 0.0000 0.1390 0.0000 0.0000
+0.0000 0.1085 0.1302 0.0448 0.1648 0.0580 0.0858 0.2151 0.0826 0.1101
+0.0942 0.0000 0.0609 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.8450
+0.1985 0.1227 0.6629 0.0000 0.0159 0.0000 0.0000 0.0000 0.0000 0.0000
+0.3881 0.4157 0.1962 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+0.1274 0.0000 0.1344 0.2813 0.4569 0.0000 0.0000 0.0000 0.0000 0.0000
+0.0000 0.0000 0.4617 0.4092 0.0000 0.0000 0.0000 0.0000 0.1291 0.0000
+0.1323 0.0000 0.0000 0.0000 0.7527 0.0000 0.0000 0.0000 0.0614 0.0537
+0.1240 0.4655 0.0000 0.0000 0.0143 0.0000 0.0051 0.0000 0.2333 0.1577
+0.0000 1.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000
+0.0000 0.0421 0.0345 0.0000 0.0349 0.1050 0.1673 0.1888 0.4235 0.0037
+0.0000 0.2437 0.0418 0.6671 0.0474 0.0000 0.0000 0.0000 0.0000 0.0000
+0.0943 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.9057 0.0000 0.0000
+0.0000 0.0000 0.0000 0.0888 0.0708 0.0000 0.0000 0.0000 0.8403 0.0000
+0.0000 0.0063 0.3596 0.0630 0.1982 0.0250 0.0000 0.0000 0.3089 0.0391
+0.0202 0.0821 0.0017 0.1213 0.0000 0.5055 0.0538 0.0868 0.0000 0.1287
+0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 1.0000 0.0000 0.0000 0.0000