# umiVisualiser User Guide

## Table of contents
1. [Data import](#import)
2. [Data filtering](#selection)
3. [Plots and Tables](#plots)


## Import data <a name="import"></a>

### Importing your umierrorcorrect output
The input section is in the upper left corner of dashboard and contains two tabs,
one for data upload and another for data selection. You have two option for importing
your data files generated with umierrorcorrect:

- Choose directory: You specify a top-level directory containing the umierrorcorrect output folders you want to analyse
- Choose zip file: Upload a zip file containing you umierrorcorrect output folders

The directory you choose or the zip file you create should have a folder structure like
this:

- Experiment folder
    + Sample_X
        * sample_1.cons
        * sample_1_summary_statistics.txt
        * sample_1_consensus_reads.bam
    + Sample_2
        * ...
    + Sample_3

Note that the app infers sample names from the the names of the folder. That is,
the first sample will be refered to as "Sample_X", regardless of the filenames
within the folder.

Umierrorcorrect may output other files, but these are not currently used by the app.
The .bam files are optional, as they will only be used for generating histograms
upon user request (see below). You may choose to delete larger files such as
.fastq and the full alignment file and only keep the 3 files mentioned above.

If you do not have any data but would like to test the app, press the "Load test data"
button and sample data will load automatically. 

### Importing additional data

#### Meta data
If you have a file containing metadata, such as time points, replicate information or
other types of sample information for sample grouping and statistics, you can
upload a metadata file in the "Choose a file containing sample info" box. Your 
metadata may look like this:

|   Sample    |   Replicate   |   Time |  Other variable  |
|-------------|---------------|------|---|
| s1 |  1         |   0    | ...  |   
| s2 |  1         |   0    |  ... |   
| s3 |  1         |   0    | ...  |   
| s4 |  2         |   10   | ...  |   
| s5 |  2         |   10   | ...  |   
| s6 |  2         |   10   | ...  |   

The app assumes that the first column in the metadata table contains the same
names as the sample names from the umierrorcorrect output.

#### Alignment files
The bam files generated by umierrorcorrect are not automatically imported, but
you can choose to so by pressing the "import .bam files" button. This will automatically
generate the barcode family histogram as well.

## Data selection and filtering  <a name="selection"></a>
### Selecting samples and amplicons

The app uses the names of the folders you upload and named assay regions to suggest
samples and amplicons in the data selection tab. You can select one or more samples
or amplicons and the output will change dynamically reflecting your choices.

### Choosing the right consensus depth

In the data selection tab you also choose a consus depth to use. This is the 
minimum number of reads a barcode family needs to have in order to be included
in the analysis. The default value is 3, which means only barcodes found in
at least three reads will considered. The greater this value, the more powerful
the error correction will be. However, depending on your actual raw sequencing depth,
the number of available reads may become drastically smaller with increasing
consensus cut offs. Generally a consensus depth of 3 already offers good error
correction but maintains sufficiently many reads. You should try different values
depending on your data and find the optimal value.

### Filtering indivdual positions

You can filter you data further in the "Parameters" tab in the top right corner
of the dashboard. You can change the following:

- Minimum variant allele frequency: Only keep positions with at least this allele frequency
- Minimum variant allele count: Only keep positions with at least this many variant reads
- Min and Max family size: This changes the x axis on the barcode family histogram

You can additionally decide if plots should show variant allele frequency (default) or
absolute counts, where applicable.

## Looking at your data <a name="plots"></a>
### The Data Viewer tab

### The Plots tab


## Advanced usage








