+
+
+
+
+# Welcome to the RIVET Wiki
+
+RIVET is a software pipeline and visual web platform to perform SARS-CoV-2 recombination inference using RIPPLES and organize the relevant information in order to greatly accelerate the process of identifying and tracking SARS-CoV-2 recombinants.
+
+
+
+For detailed information on each column of the results table, please see the [RIVET Results Table](start/table.md) page.
+
+### Results Table Next and Previous Buttons
+Use the `next` and `previous` buttons shown below to skip to the next recombinant result (next row) and SNV visualization in the table.
+
+
+
+!!! tip
+ You can also use the arrow keys instead of the `next` and `previous` buttons. Use the right arrow key :arrow_forward: and left arrow key :arrow_backward: to skip to `next` and `previous` results respectively.
+
+
+### Sort by Column
+The results can be sorted by any column, by **clicking on the column title**, shown below:
+
+
+
+
+### SNV plot
+When a user clicks on a row to select a recombinant of interest the following visualization, shown below, will be rendered.
+
+
+
+The above visualization shows all of the single-nucleotide variant (SNV) sites in the recombinant sequence and its two parents (donor/acceptor), with respect to the reference sequence. The recombinant-informative sites are highlighted in orange where the recombinant matches the donor, and blue where the recombinant matches the acceptor. The gene region annotations are shown below the trio sequences in the bottom track.
+
+
+### Query Descendants
+For a selected recombinant ancestor node of interest, you might want to query which samples are descendants of this inferred recombinant. Simply **click** the `Recombinant` label to the left of the track to view up to 10,000 sample descendants of that particular recombinant, as seen in the screenshots below.
+
+You can also click the `Donor` and `Acceptor` labels to query the samples that are descendants of those particular parental nodes.
+
+
+
+
+
+
+
+
+
+
+!!! warning
+
+ This feature will open a new tab to `UShER` and may take a few minutes to load in the new tab.
+
+Once finished loading, you will see the following page, where you can view the subtree by clicking `view downsampled global tree in Nextstrain`.
+
+
+
+
+
+
+!!! question
+
+ If there is additional information you would like to know for a particular recombinant of interest, please make this suggestion through a [GitHub Issue](https://github.com/TurakhiaLab/rivet/issues) in our repository.
+
+
+
+
+
+
+
+
+Since the SNV plot for RSV includes many sites, only the region up to around position 1000 is shown in the image above.
+**Please click the download button below to view the entire `RSV` SNV plot as an SVG image.**
+
+
+
+
+
+### RIVET Backend Architecture
+A. **RIPPLES Job Orchestrator**
+When running a `RIVET` job on Google Cloud Platform (GCP), `RIVET` calculates the number of long branches in the input mutation-annotated tree and partitions them across `n` GCP instances, which is a parameter specified by the user. This stage of the pipeline is responsible for setting up and launching these parallel jobs, as well as monitoring their progress as they run. This stage of the pipeline also initiates a [Chronumental](https://github.com/theosanderson/chronumental) job, to run concurrently as a subprocess on the local machine, which is explained in the following part B.
+
+
+B. **Infer MAT nodes ancestral dates**
+In order to infer the emergence of detected ancestral recombinant nodes of interest for ranking and epidemiological prioritization, `RIVET` builds a time-tree using the [Chronumental](https://www.biorxiv.org/content/10.1101/2021.10.27.465994v1) method. This method uses the sample dates provided in the sequence metadata file to build a probabilistic
+model for length of time across branches in the tree and is able to infer the dates of all internal nodes in the tree. `RIVET` uses these dates for internal nodes that we label as recombinants.
+
+C. **Mult-node GCP Workflow**
+When running a `RIVET` job on GCP, the `RIPPLES` recombinant search and subsequent filtration pipeline utilizes multi-node parallelism. The degree of speedup depends on how many GCP instances the user decides to allocate towards the job, since the `MAT` long branches to search will be automatically partitioned across the given `n` machines. On each instance, once a putative list of recombinant nodes is obtained, the pipeline on that machine begins quality control and filtration checks to flag false-positive recombinants.
+
+D. **Post-filtration Aggegrator and Ranking**
+This is the last stage of the pipeline and it occurs on your local machine, for both on-premise and GCP `RIVET` workflows. Once the recombination search and filtration steps of the pipeline have concluded on **all** instances and the local `Chronumental` job has finished, the filtered recombinant results for each partition of long branches are aggregated locally and the post-filtration stage of the pipeline can begin. During this last step, the final list of recombinants is ranked according to a [growth metric](start/table.md#recombinant-ranking-score) and also additional information on each recombinant is gathered, such as clade/lineage information, descendant samples, parsimony scores, quality control/filtration information, and more. For a full list of all information reported about each putative recombinant, please see our documentation about the [RIVET Results Table](start/table.md)
+
+
+### RIVET Backend Input
+
+!!! warning
+ All input files should be placed in the current directory where you will launch your `RIVET` workflow.
+
+ **If using GCP:** The following input files with the same naming as you specify in the `config.yaml` file below need to be placed in your GCP Storage Bucket (`bucket_id`) before launching the remote `RIVET` job.
+
+1. `UShER Mutation-Annotated Tree (MAT)`: Updated daily and can be obtained here: [SARS-CoV-2 global MAT](https://hgdownload.soe.ucsc.edu/goldenPath/wuhCor1/UShER_SARS-CoV-2/)
+ - `RIVET` performs recombination search using `RIPPLES` over an UShER mutation-annotated tree (`MAT`). Any samples you wish to search for recombinant ancestry must first be added to the `MAT` using [UShER](https://github.com/yatisht/usher/tree/master).
+ 
+
+### RIVET Architecture
+A. **RIPPLES Job Orchestrator**
+When running a `RIVET` job on Google Cloud Platform (GCP), `RIVET` calculates the number of long branches in the input mutation-annotated tree and partitions them across `n` GCP instances, which is a parameter specified by the user. This stage of the pipeline is responsible for setting up and launching these parallel jobs, as well as monitoring their progress as they run. This stage of the pipeline also initiates a [Chronumental](https://github.com/theosanderson/chronumental) job, to run concurrently as a subprocess on the local machine, which is explained in the following part B.
+
+
+B. **Infer MAT nodes ancestral dates**
+In order to infer the emergence of detected ancestral recombinant nodes of interest for ranking and epidemiological prioritization, `RIVET` builds a time-tree using the [Chronumental](https://www.biorxiv.org/content/10.1101/2021.10.27.465994v1) method. This method uses the sample dates provided in the sequence metadata file to build a probabilistic
+model for length of time across branches in the tree and is able to infer the dates of all internal nodes in the tree. `RIVET` uses these dates for internal nodes that we label as recombinants.
+
+C. **Mult-node GCP Workflow**
+When running a `RIVET` job on GCP, the `RIPPLES` recombinant search and subsequent filtration pipeline utilizes multi-node parallelism. The degree of speedup depends on how many GCP instances the user decides to allocate towards the job, since the `MAT` long branches to search will be automatically partitioned across the given `n` machines. On each instance, once a putative list of recombinant nodes is obtained, the pipeline on that machine begins quality control and filtration checks to flag false-positive recombinants.
+
+D. **Post-filtration Aggegrator and Ranking**
+This is the last stage of the pipeline and it occurs on your local machine, for both on-premise and GCP `RIVET` workflows. Once the recombination search and filtration steps of the pipeline have concluded on **all** instances and the local `Chronumental` job has finished, the filtered recombinant results for each partition of long branches are aggregated locally and the post-filtration stage of the pipeline can begin. During this last step, the final list of recombinants is ranked according to a [growth metric](https://turakhialab.github.io/rivet/start/table.html#recombinant-ranking-score) and also additional information on each recombinant is gathered, such as clade/lineage information, descendant samples, parsimony scores, quality control/filtration information, and more. For a full list of all information reported about each putative recombinant, please see our documentation about the [RIVET Results Table](https://turakhialab.github.io/rivet/start/table.html).
+
+
+## RIVET Backend Input
+
+!!! warning
+ All input files should be placed in the current directory where you will launch your `RIVET` workflow.
+
+ **If using GCP:** The following input files with the same naming as you specify in the `config.yaml` file below need to be placed in your GCP Storage Bucket (`bucket_id`) before launching the remote `RIVET` job.
+
+1. `UShER Mutation-Annotated Tree (MAT)`: Updated daily and can be obtained here: [SARS-CoV-2 global MAT](https://hgdownload.soe.ucsc.edu/goldenPath/wuhCor1/UShER_SARS-CoV-2/)
+ - `RIVET` performs recombination search using `RIPPLES` over an UShER mutation-annotated tree (`MAT`). Any samples you wish to search for recombinant ancestry must first be added to the `MAT` using [UShER](https://github.com/yatisht/usher/tree/master).
+ 
+
+For detailed information on each column of the results table, please see the [RIVET Results Table](https://turakhialab.github.io/rivet/start/table.html) page.
+
+## Results Table Next and Previous Buttons
+Use the `next` and `previous` buttons shown below to skip to the next recombinant result (next row) and SNV visualization in the table.
+
+
+!!! tip
+ You can also use the arrow keys instead of the `next` and `previous` buttons. Use the right arrow key :arrow_forward: and left arrow key :arrow_backward: to skip to `next` and `previous` results respectively.
+
+
+## Sort by Column
+The results can be sorted by any column, by **clicking on the column title**, shown below:
+
+
+
+
+## SNV plot
+When a user clicks on a row to select a recombinant of interest the following visualization, shown below, will be rendered.
+
+
+
+The above visualization shows all of the single-nucleotide variant (SNV) sites in the recombinant sequence and its two parents (donor/acceptor), with respect to the reference sequence. The recombinant-informative sites are highlighted in orange where the recombinant matches the donor, and blue where the recombinant matches the acceptor. The gene region annotations are shown below the trio sequences in the bottom track.
+
+
+## Query Descendants
+For a selected recombinant ancestor node of interest, you might want to query which samples are descendants of this inferred recombinant. Simply **click** the `Recombinant` label to the left of the track to view up to 10,000 sample descendants of that particular recombinant, as seen in the screenshots below.
+
+You can also click the `Donor` and `Acceptor` labels to query the samples that are descendants of those particular parental nodes.
+
+
+
+
+
+
+
+
+
+
+!!! warning
+
+ This feature will open a new tab to `UShER` and may take a few minutes to load in the new tab.
+
+Once finished loading, you will see the following page, where you can view the subtree by clicking `view downsampled global tree in Nextstrain`.
+
+
+
+
+
+
+!!! question
+
+ If there is additional information you would like to know for a particular recombinant of interest, please make this suggestion through a [GitHub Issue](https://github.com/TurakhiaLab/rivet/issues) in our repository.
+
+
+
+
diff --git a/docs/start/filtration.md b/docs/start/filtration.md
new file mode 100644
index 0000000..67c19bb
--- /dev/null
+++ b/docs/start/filtration.md
@@ -0,0 +1,25 @@
+# Quality Control and Filtration Checks
+
+## 3SeqP02
+P-value from 3-seq > 0.2.
+
+## russPval005
+False-discovery rate (FDR) of the parsimony improvement > 0.05. (See [Supplementary Text S3 of RIPPLES](https://www.nature.com/articles/s41586-022-05189-9#MOESM1) for details of the null model.)
+
+## Alt
+"Alternate": Other recombination trios with the same recombination node have more parsimony improvement, fewer possible breakpoint intervals, or better P-values.
+
+## cluster
+All recombination informative mutations occur within a span of 20 nucleotides.
+
+## redundant
+More than two of the recombination node, donor node, and acceptor node appear in that of another trios.
+
+## Informative_sites_clump
+More than 5 recombination-informative mutations in a 20-nucleotide span.
+
+## Suspicious_mutation_clump
+More than 6 mutations (or 3 near indels) in a 20-nucleotide span on any of the donor node, the aceptor node or the recombination node.
+
+## Too_many_mutations_near_INDELs
+Too many mutations on 100-nt spans near indels or a string of Ns.
\ No newline at end of file
diff --git a/docs/start/future.md b/docs/start/future.md
new file mode 100644
index 0000000..d13dcbd
--- /dev/null
+++ b/docs/start/future.md
@@ -0,0 +1,83 @@
+# Using RIVET for Other Pathogens
+
+Below are two examples of using `RIVET's` backend pipeline to infer and visualize recombinants of other pathogens beyond SARS-CoV-2.
+
+!!! warning
+ Currently, `RIVET's` backend QC/filtration pipeline is specific to SARS-CoV-2 and will not run when using the `RIVET` backend for other pathogens.
+
+
+## Human Respiratory Syncytial Virus (HRSV) Subgroup A
+
+Below are the steps followed to infer putative recombinants in an `RSV` mutation-annotated tree (MAT).
+
+
+
+### Using RIVET frontend for Visualization
+
+
+
+
+
+Since the SNV plot for RSV includes many sites, only the region up to around position 1000 is shown in the image above.
+**Please click the download button below to view the entire `RSV` SNV plot as an SVG image.**
+
+
+
+
