Merge pull request #65 from compbiocore/develop

VIVA.ipynb

Author: fernandogelin

Project.toml

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

README.md

@@ -54,7 +54,7 @@ Expected Time for Installation: Installation time depends on your network bandwi
 
 ### Running VIVA with Docker or Docker Compose
 
-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.
+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.
 
 To run VIVA from a Docker image, first [install Docker](https://docs.docker.com/install/).
 
@@ -78,6 +78,8 @@ cd project_x
 
 Make sure to add your project VCF files to that folder. That directory will be mapped to `/notebook/data` inside of the container.
 
+When entering the filename of the VCF file and files to support filtering options, you should include `/data/...` in the path to your files.
+
 ##### 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.

VIVA.ipynb

@@ -80,6 +80,98 @@ Use the following steps to use the VIVA Jupyter Notebook utility:
 
 6. Follow the step-by-step instructions within the notebook to generate your figures.
 
+### Running VIVA with Docker or Docker Compose
+
+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.
+
+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
+
+*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.
+
+We provide two images, one with a Jupyter Notebook and one with a command line script for VIVA. You can run VIVA in a single command using these images. The command consists of calls to run the Docker image followed by the usual VIVA options.
+
+To run the images, follow these steps:
+
+Create a project folder and navigate to it:
+```shell
+mkdir project_x
+cd project_x
+```
+
+Make sure to add your project VCF files to that folder. That directory will be mapped to `/notebook/data` inside of the container.
+
+When entering the filename of the VCF file and files to support filtering options, you should include `/data/...` in the path to your files.
+
+##### 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:
+```shell
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli:v0.3.8 --save_remotely arg1 arg2 arg3
+```
+
+- Example run:
+```shell
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli:v0.3.8 --save_remotely -f file.vcf -p
+```
+
+- On Windows:
+```shell
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli:v0.3.8 --save_remotely arg1 arg2 arg3
+```
+
+- Example run:
+```shell
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli:v0.3.8 --save_remotely -f file.vcf -p
+```
+
+##### Run the VIVA Jupyter Notebook from a Docker image:
+
+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":/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}":/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.
+
+#### Using Docker Compose
+
+To run the images with Docker Compose, install Docker following the steps above and then install [Docker Compose[(https://docs.docker.com/compose/). Then copy the [docker-compose.yml](https://github.com/compbiocore/viva-docker/blob/master/docker-compose.yml) file to a local directory. From that same directory, run the command as it appears below.
+
+*Note*: Your current directory will mount to `/notebook/data` in the notebook image and to `/data` in the CLI image.
+
+- Notebook
+```shell
+docker-compose up viva-notebook
+```
+
+- Command Line Tool
+```shell
+docker-compose run viva -f file.vcf --save_remotely arg3 arg4 ...
+```
+
 ## Continue reading for:
 
 * [Variant and Sample Selection](https://compbiocore.github.io/VariantVisualization.jl/stable/filtering_vcf/)

docs/src/index.md

@@ -37,15 +37,15 @@ To install Julia on Windows, you can follow the [platform specific instructions]
 
 ### Running VIVA with Docker or Docker Compose
 
-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.
+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.
 
 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
 
-*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.
 
@@ -61,28 +61,30 @@ cd project_x
 
 Make sure to add your project VCF files to that folder. That directory will be mapped to `/notebook/data` inside of the container.
 
+When entering the filename of the VCF file and files to support filtering options, you should include `/data/...` in the path to your files.
+
 ##### 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
-docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely arg1 arg2 arg3
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli:v0.3.8 --save_remotely arg1 arg2 arg3
 ```
 
 - Example run:
 ```shell
-docker run -it --rm -v "$PWD":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
+docker run -it --rm -v "$PWD":/data compbiocore/viva-cli:v0.3.8 --save_remotely -f file.vcf -p
 ```
 
 - On Windows:
 ```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely arg1 arg2 arg3
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli:v0.3.8 --save_remotely arg1 arg2 arg3
 ```
 
 - Example run:
 ```shell
-docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli --save_remotely -f file.vcf -p
+docker run -it --rm -v "${pwd}":/data compbiocore/viva-cli:v0.3.8 --save_remotely -f file.vcf -p
 ```
 
 ##### Run the VIVA Jupyter Notebook from a Docker image:

docs/src/installation.md

@@ -30,14 +30,13 @@ function jupyter_main(vcf_filename,saving_options,variant_filters,sample_selecti
     sample_names = get_sample_names(reader)
 
     #store save format and create output directory if it doesn't exist yet
-#=
-    save_ext = save_format
+
+    #save_ext = save_format
     VariantVisualization.checkfor_outputdirectory(output_directory)
     output_directory=output_directory
-=#
 
     save_ext = save_format
-    output_directory=output_directory
+    #output_directory=output_directory
 
     #store plot label options
     if occursin("true",x_axis_labels)
@@ -107,7 +106,7 @@ function jupyter_main(vcf_filename,saving_options,variant_filters,sample_selecti
 
     #genomic_range
     if occursin("chr",genomic_range) && !occursin("true",pass_filter) && !occursin(".csv",positions_list)
-        sub = VariantVisualization.io_chromosome_range_vcf_filter(genomic_range,vcf_filename)
+        sub = VariantVisualization.io_genomic_range_vcf_filter(genomic_range,vcf_filename)
         number_rows = size(sub,1)
         println("Selected $number_rows variants within chromosome range: $genomic_range")
         heatmap_input = "range_filtered"