Update README

Author: schmidt73

README.md

@@ -1,4 +1,4 @@
-# fastBE: A regression based approach to phylogenetic reconstruction from bulk DNA sequencing of tumors
+## 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.
@@ -12,7 +12,7 @@ If you find this tool useful in your research, please cite us at:
 ```
 ```
 
-## Installation
+### Installation
 
 `fastBE` is implemented in C++ and is packaged with the dependencies
 needed to execute the program. In particular, the only dependencies are
@@ -32,7 +32,7 @@ $ make
 ```
 The output binary will be located at `build/src/fastbe`.
 
-## Usage
+### Usage
 
 To run *fastbe*, simply execute the binary. 
 ```
@@ -47,15 +47,33 @@ Subcommands:
   search        Searches for a clone tree that best fits a frequency matrix.
 ```
 
+The two modes of fastbe are `search` and `regress`. The `search` mode
+solves the variant allele frequency $\ell_1$-deconvolution problem, 
+while the `regress` mode solves the variant allele frequency 
+$\ell_1$-regression problem, both of which are defined in 
+our manuscript. 
+
+The `search` mode takes as input an $m \times n$ frequency matrix $F$ and outputs
+an $n$-clonal tree that best fits the frequency matrix. *Important note: the search
+command requires a root vertex specified with the `-f/--assigned-root` flag.*
+By default this root vertex is set to be $0$. When the root vertex is unknown,
+it suffices to append an extra column to the beginning of the frequency matrix 
+and specify the root as $0$.
+
+The `regress` mode
+takes as input an $m \times n$ frequency matrix $F$ and an $n$-clonal
+tree $\mathcal{T}$ and outputs the minimum value of 
+`\lVert F - UB_{\mathcal{T}} \rVert_1` over all usage matrices $U$.
+
 ### Input format
 
-The input format for *fastbe* consists of a frequency matrix $F$
-in TXT format. Rows are separated by newlines
+The input format for the `search` mode of *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:
+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
@@ -79,13 +97,42 @@ describing 20 samples and 10 clones is:
 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,
+The above frequency matrix $F$ is provided as an input file at `examples/sim_obs_frequency_matrix.txt`.
+
+The input format for the `regress` mode of *fastbe* is the aforementioned
+frequency matrix $F$ and an $n$-clonal tree $\mathcal{T}$. The tree is specified
+as an adjacency list in `.txt` format. An example of a clonal tree
+which consists of $10$ clones rooted at the $0$ vertex is:
+```
+0 1 2 4
+1 3
+2
+3 5 6 7 9
+4
+5
+6
+7 8
+8
+9
+```
+
+The above clonal tree $\mathcal{T}$ is provided as an input file at `examples/sim_tree.txt`.
+
+The above frequency matrix and clonal tree were 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.
+which simulates the evolution of a tumor with $10$ 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
 
+As an example, we will infer a phylogenetic tree from the simulated
+data with $20$ samples and $10$ clones. To run `fastbe` on this data,
+execute:
+```
+fastbe search examples/sim_obs_frequency_matrix.txt -o examples/fastbe
+```
+This command will output an adjacency list describing the clonal tree 
+at `examples/fastbe_tree.txt` and a `.json` file containing metadata
+at `examples/fastbe_results.json`.