Merge branch 'master' into develop

Author: gtollefson

docs/src/filtering_vcf.md

@@ -1,14 +1,14 @@
-#Variant Record and Sample Selection
+# Filtering your VCF file: Variant Record and Sample Selection
 
-##General Note:s: Extracting and Reshaping VCF Data
+## General Notes: Extracting and Reshaping VCF Data
 
 VIVA supports flexible filters for selecting variant records for visualization.
 
 Additionally, the tool supports selecting and grouping samples by common traits for visualization.
 
 Grouping samples is particularly useful for exploring phenotypic and genotypic associations, displaying differential distribution of variants between groups of samples, and identifying batch effect on coverage between groups of samples in variant analysis experiments.
 
-##Choose a VCF file to Visualize *REQUIRED*
+## Choose a VCF file to Visualize *REQUIRED*
 
 Specify filename of VCF file.
 
@@ -19,16 +19,16 @@ Specify filename of VCF file.
 *Note*: This is the *only required argument* for VIVA. If you run with none of the other options, default options will be used. These default options are described in detail below.
 
 ```
-julia viva -f example.vcf [OPTIONS]
+viva -f example.vcf [OPTIONS]
 ```
 
-##Selecting Variant Records
+## Selecting Variant Records
 
 VIVA offers three filters for selecting variant records to visualize from VCF files.
 
 It is recommended to use one or a combination of these filters to reduce the number of variant records extracted from the VCF for plotting. This is recommended for reasons related to technical limitations and practical visual interpretation. The number of variant records able to be plotted is limited by both the user's available computing resources as well as the number of pixels in their display for displaying data points. While it is possible to visualize many thousands of variant records at one time with VIVA, **we recommend visualizing fewer than 2000 variants** so that all data points can be displayed that your computing resources are not overburdened. However, VIVA is capable of extracting and plotting hundreds of thousands of data points from VCF files.
 
-###Genomic range
+### Genomic range
 
 Select rows within a given genomic range.
 
@@ -39,10 +39,10 @@ Select rows within a given genomic range.
 *Note*: To visualize genomic ranges within multiple chromosomes, you may create a batch script to run VIVA multiple times using different genomic ranges.
 
 ```
-julia viva -f example.vcf -r chr1:20000-30000000
+viva -f example.vcf -r chr1:20000-30000000
 ```
 
-###Variant list
+### Variant list
 
 Select variants matching list of chromosomal positions.
 
@@ -51,10 +51,10 @@ Select variants matching list of chromosomal positions.
 *arguments*: Provide filename of text file formatted with two columns in .csv format as an argument. There should be a header row with "chr" and "start" in row 1 of column 1 and 2 respectively. Column 1 should contain chromosome number in the format "chr1" or "1" and should match the syntax of the VCF file (that is, if the VCF file lists chromosome numbers in the form "chrX", use "chrX" in your positions list, not "X") You can find an example of this file [here]("[here]("https://github.com/compbiocore/VariantVisualization.jl/tree/master/test/test_files/positions_list.csv")")
 
 ```
-julia viva -f example.vcf -l "example_positions_list.txt"
+viva -f example.vcf -l "example_positions_list.txt"
 ```
 
-###Pass filter
+### Pass filter
 
 Select rows that passed filters originally set during variant calling and VCF file generation. Selects records with "PASS" in the FILTER column of the VCF file. This filter alone is often not stringent enough to reduce the number of variants for plotting and visual interpretation. For analyzing large VCF files with many "passed" filter records, use genomic range,
 
@@ -63,12 +63,12 @@ Select rows that passed filters originally set during variant calling and VCF fi
 *arguments*: This flag is a positional argument and does not take options.
 
 ```
-julia viva -f example.vcf -p
+viva -f example.vcf -p
 ```
 
-##Selecting and Grouping Samples
+## Selecting and Grouping Samples
 
-###Group samples by sample metadata traits
+### Group samples by sample metadata traits
 
 Group sample columns using your sample metadata and visualize metadata attributes in a colorbar above heatmap visualizations.
 
@@ -94,10 +94,10 @@ Metadata traits are stored as rownames in the first column of the table and shou
 This matrix should be saved as a comma delimited .csv file. Microsoft Excel is commonly used for this purpose, but sometimes creates extra delimiter characters in the output file that produce an error in VIVA. You can check to make sure the .csv file was saved properly by opening the file with a text editor such as BBEdit to inspect for and delete empty values or extra delimiter characters at the end of each row.
 
 ```
-julia viva -f example.vcf -g sample_metadata_matrix.csv case,control
+viva -f example.vcf -g sample_metadata_matrix.csv case,control
 ```
 
-###Select samples to include in visualization
+### Select samples to include in visualization
 
 Select specific samples to be extracted from the VCF for visualization.
 
@@ -108,5 +108,5 @@ Select specific samples to be extracted from the VCF for visualization.
 *Note*: To use the sample selection feature in combination with the sample grouping feature, the sample metadata matrix must only contain the sample ids to be selected.
 
 ```
-julia viva -f example.vcf --select_samples select_samples_list.txt
+viva -f example.vcf --select_samples select_samples_list.txt
 ```

docs/src/index.md

@@ -1,6 +1,6 @@
 ![VIVA Logo](assets/VIVA_logo.png)
 
-Read the [VIVA Manual](https://compbiocore.github.io/VariantVisualization.jl/latest/installation/) here.
+
 
 # Getting Started
 
@@ -18,6 +18,9 @@ VIVA is available as a Jupyter Notebook utility [here](https://github.com/compbi
 
 Formatting requirements for VIVA's input files are described in the Manual and clearly named examples of all user-generated input files can be found in the `/test/test_files` directory of the `VariantVisualization.jl` repository.
 
+## Installation
+For detailed installation instructions, read the [VIVA Manual](https://compbiocore.github.io/VariantVisualization.jl/latest/installation/) here.
+
 ## General Use
 
 To use VIVA, we recommend creating a new directory for storing your VCF file to analyze where output files will be saved. Alternatively, users may also provide paths to the VCF file and to preferred output file locations as command line arguments.
@@ -26,29 +29,29 @@ To use VIVA, we recommend creating a new directory for storing your VCF file to
 VIVA's general command line argument structure is as follows:
 
 ```
-    julia viva -f file.vcf [OPTIONS]
+    viva -f file.vcf [OPTIONS]
 ```
 
 From the command line or powershell, run the VIVA command line tool script which takes arguments from the command line and parses them with ArgParse.jl.
 
 Example:
 
 ```
-    julia viva -f example.vcf -r chr1:20000-30000000 -s pdf -m genotype,read_depth --avg_dp samples
+    viva -f example.vcf -r chr1:20000-30000000 -s pdf -m genotype,read_depth --avg_dp samples
 ```
 
 To display a complete set of help instructions while using the tool, run VIVA with the help flag (`--help`, `-h`).
 
 ```
-    julia viva -h
+    viva -h
 ```
 
 ### Default Options:
 
 By running VIVA with only a VCF filename:
 
 ```
-    julia viva -f file.vcf
+    viva -f file.vcf
 ```
 
 Default options will be used:

docs/src/installation.md

@@ -35,7 +35,7 @@ To install VariantVisualization.jl:
 
 ```julia
 julia
-]add VarianatVisualization
+]add VariantVisualization
 exit()
 ```
 ### Step 3: Run `viva`
@@ -99,19 +99,16 @@ We have included in-line comments within the code for the [VIVA command line too
 
 The ***VIVA Jupyter notebook*** is powered by a [main function](https://github.com/compbiocore/VariantVisualization.jl/tree/master/src/new_notebook_utils.jl) which takes arguments defined by the user in the notebook. We welcome users to post in issues to request a new feature or bug fix.
 
-## Installation Features Under Development
 
-### Running VIVA with Docker or Docker Compose (Under Active Development)
+### Running VIVA with Docker or Docker Compose
 
-Soon, you will be able to run VIVA using Docker images. This is not yet a supported feature. The instructions below will be helpful once this is supported.
-
-Alternatively, you can run VIVA using the Docker images we've provided if you don't want to install Julia and the VariantVisualization.jl Julia package. You may only save images to HTML format using the Docker, for now, due to technical limitations of dependency packages. We've actively developing a feature to save to all formats using Docker.
+You can run VIVA using the Docker images we've provided if you don't want to install Julia and the VariantVisualization.jl Julia package. 
 
 To run VIVA from a Docker image, first [install Docker](https://docs.docker.com/install/).
 
 Then double-click the Docker.app in the Applications folder to start Docker. You will see a whale icon in the top status bar to indicate that Docker is running and accessible from the terminal. You can quit Docker once you are finished using VIVA by clicking the Docker whale icon in the top status bar and clicking "Quit Docker Desktop."
 
-#### Using Docker
+### Using Docker
 
 *Note*: You must use the flag `--save_remotely` when running VIVA by using Docker.
 
@@ -130,31 +127,22 @@ cd project_x
 Make sure to add your project VCF files to that folder.
 
 
-##### Run the VIVA Command Line Tool from a Docker image:
+#### Run the VIVA Command Line Tool from a Docker image:
 
 *Note*: Remember, you must use the flag `--save_remotely` when running VIVA by using Docker.
 
-- On Mac or Linux:
+- Example run on Mac or Linux:
 ```shell
 docker run -it --rm -v "$PWD":/data compbiocore/viva-cli viva --save_remotely -f file.vcf -s pdf -o output
 ```
 
-- Example run:
+- Example run on Windows:
 ```shell
-docker run -it --rm -v "$PWD":/data compbiocore/viva-cli viva --save_remotely -f file.vcf -s pdf -o output
+docker run -it --rm -v ${pwd}:/data compbiocore/viva-cli viva --save_remotely -f file.vcf -s pdf -o output
 ```
 
-- On Windows:
-```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli viva --save_remotely -f file.vcf -s pdf -o output
-```
-
-- Example run:
-```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli viva --save_remotely -f file.vcf -s pdf -o output
-```
 
-##### Run the VIVA Jupyter Notebook from a Docker image:
+#### Run the VIVA Jupyter Notebook from a Docker image:
 
 Copy and run the following line from the terminal or Windows PowerShell:
 
@@ -169,7 +157,7 @@ Go to `http://127.0.0.1:8888/?token=<enter token here>`
 
 - On Windows:
 ```shell
-docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "${pwd}":/home/jovyan/notebook/data compbiocore/viva-notebook:v0.3.9
+docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v ${pwd}:/home/jovyan/notebook/data compbiocore/viva-notebook:v0.3.9
 ```
 
 Go to the following url in your internet browser. You'll receive a token to enter into the url.