Merge pull request #64 from compbiocore/develop

Update docs for Docker

Author: fernandogelin

Project.toml

@@ -1,7 +1,7 @@
 name = "VariantVisualization"
 uuid = "7f8bf45c-0ad5-53b5-97e6-33c1305e0aa4"
 authors = ["George Tollefson <[email protected]>"]
-version = "0.3.8"
+version = "0.3.9"
 
 [deps]
 ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"

README.md

@@ -1,4 +1,4 @@
-# VariantVisualization.jl
+# VIVA: A VCF File Visualization Tool and VariantVisualization.jl
 ## Visualization of Variants
 
 
@@ -11,7 +11,7 @@
 
 VariantVisualization.jl is a package we built specifically to power the genetics visualization tool, *VIVA*.
 
-*VIVA* is a user-friendly command line tool for creating publication quality graphics from Variant Call Format (VCF) files. It has been designed for clinicians and bioinformaticians to explore their VCF files visually. In a single command, users can extract genotype or read depth information and plot trends in interactive categorical heatmaps and scatter plots of average read depth values. VIVA offers a robust set of filters to select variants and samples of interest for analysis. VIVA is especially useful in early data exploration for identifying batch effect and sources of poor read depth, as well as identifying distribution of disease causing variants in a set of clinical samples.
+*VIVA* is a user-friendly command line tool for creating publication quality graphics from Variant Call Format (VCF) files. It has been designed for clinicians and bioinformaticians to explore their VCF files visually. In a single command, users can extract genotype or read depth information and plot trends in interactive categorical heatmaps and scatter plots of average read depth values. VIVA offers a robust set of filters to select variants and samples of interest for analysis. VIVA is especially useful in early data exploration for identifying batch effect and sources of poor read depth in sequencing experiments, as well as identifying distribution of disease causing variants in a set of clinical samples.
 
 
 ## Getting Started:
@@ -20,6 +20,8 @@ Note: Once you have set up VIVA, you can quickly run the command line tool [EXAM
 
 ## Installation
 
+Read the [installation documentation](https://compbiocore.github.io/VariantVisualization.jl/latest/installation/) for complete installation details.
+
 ### Supported Operating Systems:
 
 macOS ( Sierra, High Sierra, and Mojave ), Windows, and Linux.
@@ -60,7 +62,7 @@ Then double-click the Docker.app in the Applications folder to start Docker. You
 
 #### Using Docker
 
-*Note* You must use the flag `--save_remotely` when running VIVA by using Docker.
+*Note*: You must use the flag `--save_remotely` when running VIVA by using Docker.
 
 Once Docker is running, you can run VIVA by running the Docker commands below in the Mac/Linux terminal or Windows PowerShell.
 
@@ -78,7 +80,7 @@ Make sure to add your project VCF files to that folder. That directory will be m
 
 ##### 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.
+*Note*: Remember, you must use the flag `--save_remotely` when running VIVA by using Docker.
 
 - On Mac or Linux:
 ```shell
@@ -87,7 +89,7 @@ docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely arg1 ar
 
 - Example run:
 ```shell
-docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely -f file.vcf -p -s pdf
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
 ```
 
 - On Windows:
@@ -97,7 +99,7 @@ docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely arg1
 
 - Example run:
 ```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely -f file.vcf -p -s pdf
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
 ```
 
 ##### Run the VIVA Jupyter Notebook from a Docker image:
@@ -106,14 +108,20 @@ Copy and run the following line from the terminal or Windows PowerShell:
 
 - On Mac or Linux:
 ```shell
-docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/notebook/data compbiocore/viva-notebook
+docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/home/jovyan/notebook/data compbiocore/viva-notebook
 ```
+
+Go to the following url in your internet browser. You'll receive a token to enter into the url.
+
 Go to `http://0.0.0.0:8888/?token=<enter token here>`
 
 - On Windows:
 ```shell
-docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "${pwd}":/notebook/data compbiocore/viva-notebook
+docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "${pwd}":/home/jovyan/notebook/data compbiocore/viva-notebook
 ```
+
+Go to the following url in your internet browser. You'll receive a token to enter into the url.
+
 Go to `http://0.0.0.0:8888/?token=<enter token here>`
 
 [Click here](https://jupyter-docker-stacks.readthedocs.io/en/latest/index.html) for more information about Jupyter Docker Images.
@@ -131,7 +139,7 @@ docker-compose up viva-notebook
 
 - Command Line Tool
 ```shell
-docker-compose run viva -f --save_remotely /data/file.vcf arg2 arg3 ...
+docker-compose run viva -f file.vcf --save_remotely arg3 arg4 ...
 ```
 
 ### Latest Features

docs/src/examples.md

@@ -3,9 +3,9 @@
 To run examples:
 
 1. Install Julia and the VariantVisualization.jl package
-2. Download the five test files found [here](https://github.com/compbiocore/VariantVisualization.jl/tree/master/test/test_files) and put them into a working directory with the viva script. 
-3. Open the command line (Terminal or Powershell), copy the provided commands into the command line prompt, and press enter. 
-4. Your first viva run will take longer than usual (several minutes) because of the way Julia compiles packages. All subsequent runs will be much faster. Each example should take 30-50 seconds to run and you should see the same outputs as those below each demo. 
+2. Download the five test files found [here](https://github.com/compbiocore/VariantVisualization.jl/tree/master/test/test_files) and put them into a working directory with the viva script.
+3. Open the command line (Terminal or Powershell), copy the provided commands into the command line prompt, and press enter.
+4. Your first viva run will take longer than usual (several minutes) because of the way Julia compiles packages. All subsequent runs will be much faster. Each example should take 30-50 seconds to run and you should see the same outputs as those below each demo.
 
 We encourage you to also run these examples without the flag `-s png` to save and view interactive HTML graphics with cursor hovertext, zooming, panning, and screen capture features. View HTML graphics in your browser by opening the HTML file.
 
@@ -22,7 +22,7 @@ julia viva -f test_4X_191.vcf -t Default_Options -s png
 
 ## Grouping Samples by Metadata Traits and Generating all Four Plots
 
-Group samples by sequencing facility and generate heatmaps of genotype and read depth values as well as scatter plots of average read depth for both all selected samples and all selected variant positions. 
+Group samples by sequencing facility and generate heatmaps of genotype and read depth values as well as scatter plots of average read depth for both all selected samples and all selected variant positions.
 
 You can find grouping options [here](https://compbiocore.github.io/VariantVisualization.jl/stable/filtering_vcf/#selecting-and-grouping-samples).
 
@@ -37,14 +37,3 @@ julia viva -f test_4X_191.vcf -t Grouped_by_Sequencing_Site -g sample_metadata_m
 ![Grouped Variant Average Read Depth Scatter Plot](assets/Average_Variant_Read_Depthtest_4X_191.vcf.png)
 
 ![Grouped Sample Average Read Depth Scatter Plot](assets/Average_Sample_Read_Depth_test_4X_191.vcf.png)
- 
-## Genomic Range and Samples Selection - Genotype and Read Depth Heatmaps with Variant Position Labels
-
-Generate heatmaps of genotype and read depth values of variants selected within a genomic range, in this case, chromosome 4, nucleotides 200000-500000, with y-axis variant position labels.
-
-```
-julia viva -f test_4X_191.vcf -t Genomic_Range -r chr4:3076150-3076390 -y positions --select_samples select_samples_list.txt -s png
-```
-![Genomic Range Genotype Heatmap](assets/Genotype_Genomic_Range.png)
-![Genomic Range Read Depth Heatmap](assets/Read_Depth_Genomic_Range.png)
-

docs/src/installation.md

@@ -13,6 +13,8 @@ Sierra, High Sierra, and Mojave.
 
 Windows 10, Windows 7.
 
+To install Julia on Windows, you can follow the [platform specific instructions](https://julialang.org/downloads/platform.html).
+
 #### Linux
 
 *Note*: To run on remote compute clusters, you may need to load opengl module along with julia/1.1.0.
@@ -70,7 +72,7 @@ docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely arg1 ar
 
 - Example run:
 ```shell
-docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely -f file.vcf -p -s pdf
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
 ```
 
 - On Windows:
@@ -80,7 +82,7 @@ docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely arg1
 
 - Example run:
 ```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely -f file.vcf -p -s pdf
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
 ```
 
 ##### Run the VIVA Jupyter Notebook from a Docker image:
@@ -89,14 +91,20 @@ Copy and run the following line from the terminal or Windows PowerShell:
 
 - On Mac or Linux:
 ```shell
-docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/notebook/data compbiocore/viva-notebook
+docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/home/jovyan/notebook/data compbiocore/viva-notebook
 ```
+
+Go to the following url in your internet browser. You'll receive a token to enter into the url.
+
 Go to `http://0.0.0.0:8888/?token=<enter token here>`
 
 - On Windows:
 ```shell
-docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "${pwd}":/notebook/data compbiocore/viva-notebook
+docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "${pwd}":/home/jovyan/notebook/data compbiocore/viva-notebook
 ```
+
+Go to the following url in your internet browser. You'll receive a token to enter into the url.
+
 Go to `http://0.0.0.0:8888/?token=<enter token here>`
 
 [Click here](https://jupyter-docker-stacks.readthedocs.io/en/latest/index.html) for more information about Jupyter Docker Images.
@@ -114,7 +122,7 @@ docker-compose up viva-notebook
 
 - Command Line Tool
 ```shell
-docker-compose run viva -f --save_remotely /data/file.vcf arg2 arg3 ...
+docker-compose run viva -f file.vcf --save_remotely arg3 arg4 ...
 ```
 
 -----

docs/src/plotting.md

@@ -30,7 +30,6 @@ julia viva -f example.vcf -m genotype
 
 Generate scatter plots of average read depths across either samples or variants. Caps outlier read depth values at 100 to optimize resolution of visualization of values under 50.
 
-
 *flags*: `--avg_dp`
 
 *arguments*: `samples`, `variants`, or `samples,variants`
@@ -99,7 +98,7 @@ Choose an option for displaying y-axis ticklabels showing the genomic position o
 
 default: `chromosomes`
 
-*Note*: We don't recommend using the `positions` option when visualizing samples grouped with a metadata matrix. This will show labels that are meant to be hidden that exist as an artifact of constructing the metadata trait colorbars which are sized dynamically to make up 1/20th of the plot height. If you must use the `positions` option in this scenario, we recommend editing the final plot in a program like Powerpoint to "cover up" the multitude of tick labels that will appear beside metadata trait rows. 
+*Note*: We don't recommend using the `positions` option when visualizing samples grouped with a metadata matrix. This will show labels that are meant to be hidden that exist as an artifact of constructing the metadata trait colorbars which are sized dynamically to make up 1/20th of the plot height. If you must use the `positions` option in this scenario, we recommend editing the final plot in a program like Powerpoint to "cover up" the multitude of tick labels that will appear beside metadata trait rows.
 
 ```
 julia viva -f example.vcf `-y` `hoverlabels_only`