-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #47 from compbiocore/develop
Fix Grouped Read Depth Heatmap color pallete / Fix genomic range filters / Update README / Clarify Docs
- Loading branch information
Showing
11 changed files
with
93 additions
and
197 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,133 +1,47 @@ | ||
| # Plotting | ||
| # Examples | ||
|
|
||
| ##General notes: visualization options | ||
| To run examples, 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. | ||
|
|
||
| Here we describe VIVA options for plotting. All plots can be generated in a single command. | ||
| Once Julia and VariantVisualization.jl are installed, you can run the following examples and should see the same outputs. | ||
|
|
||
| VIVA orders all variants by chromosomal location for plotting. | ||
| ## Default Options | ||
|
|
||
| VIVA graphics are generated with PlotlyJS.jl. Graphics can be saved in *HTML*, *PDF*, *SVG*, *PNG*, and *EPS* formats. | ||
|
|
||
| To create *interactive visualization* files, save VIVA's graphics in HTML format. These files are sharable and support cursor hoverlabels, zooming, panning, and PNG screen capture. Cursor hoverlabel displays genomic position, sample id, and data value for each data point in heatmap and scatter plot visualizations. We recommend saving graphics to HTML for data exploration. | ||
|
|
||
| To create *publication quality, scalable graphics* for presentations and publications, we recommend saving graphics as PDF. | ||
|
|
||
| ## Genotype and read depth heatmaps | ||
|
|
||
| Plot a categorical heatmap of genotype values and a continuous value heatmap of read depth (coverage) values. | ||
|
|
||
| *flags*: `--heatmap`,`-m` | ||
|
|
||
| *arguments*: `genotype`, `read_depth`, or `genotype,read_depth` | ||
|
|
||
| default: `genotype,read_depth` (plots both) | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf -m genotype | ||
| ``` | ||
|
|
||
| ## Average read depth scatter plots | ||
|
|
||
| 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` | ||
|
|
||
| default: `none` | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf --avg_dp variants | ||
| ``` | ||
|
|
||
| ## Save file format | ||
|
|
||
| Specify file format you wish to save all graphics as (eg. pdf, html, png). [REQUIRED] | ||
|
|
||
| *flags*: `--save_format`, `-s` | ||
|
|
||
| *arguments*: `html`, `pdf`, `svg`, `png`, `eps` | ||
|
|
||
| default: `html` | ||
| Running VIVA with no options produces heatmaps of genotype and read depth values for all samples and variant positions in the VCF file with default options. You can read about VIVA's default settings [here](https://compbiocore.github.io/VariantVisualization.jl/stable/#default-options) | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf --avg_dp variants | ||
| ``` | ||
|
|
||
| ## Output directory | ||
|
|
||
| Specify output directory for saving all graphics. If directory doesn't exist, it creates the directory within the working directory. Defaults to "output." | ||
|
|
||
| Select directory to save output files. If path doesn't exist, creates new directory. | ||
|
|
||
| *flags*: `--output_directory`, `-o` | ||
|
|
||
| *arguments*: filepath | ||
|
|
||
| default: `output` | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf -o my_output_directory | ||
| ``` | ||
|
|
||
| ## Title | ||
|
|
||
| Specify title to display on heatmap and use as filename for saving heatmap files. Use underscores instead of spaces. Underscores will be replaced with spaces in the heatmap title. | ||
|
|
||
| *flags*: `--heatmap_title`, `-t` | ||
|
|
||
| *arguments*: title_text | ||
|
|
||
| default: original vcf filename | ||
|
|
||
| julia VIVA -f test_4X_191.vcf -t Default_Options | ||
| ``` | ||
| julia VIVA -f example.vcf -t your_heatmap_title | ||
| ``` | ||
|
|
||
| ## Y-axis label options | ||
|
|
||
| Choose an option for displaying y-axis ticklabels showing the genomic position of variants on heatmaps and scatter plots. | ||
|  | ||
|
|
||
| *flags*: `--y_axis_labels`, `-y` | ||
|  | ||
|
|
||
| *arguments*: `chromosomes`, `positions`, `hoverlabels_only` | ||
| ## Grouping Samples by Metadata Traits and Generating all Four Plots | ||
|
|
||
| `chromosomes` separates chromosomes by adding chromosome label on the first variant of each new chromosome. | ||
| `positions` labels every variant position (recommended only for visualizing a few variants e.g. <20) | ||
| `hoverlabels_only` no genomic position labels | ||
| 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. | ||
|
|
||
| default: `chromosomes` | ||
| You can find grouping options [here]([options](https://compbiocore.github.io/VariantVisualization.jl/stable/filtering_vcf/#selecting-and-grouping-samples) to group samples by common traits.) | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf `-y` `hoverlabels_only` | ||
| julia VIVA -f test_4X_191.vcf -t Grouped_by_Sequencing_Site -g sample_metadata_matrix.csv seq_site_1,seq_site_2 --avg_dp variant,sample | ||
| ``` | ||
|
|
||
| ## X-axis label options | ||
|  | ||
|
|
||
| Choose an option for displaying x-axis ticklabels showing the sample id of samples included heatmaps and scatter plots. | ||
|  | ||
|
|
||
| *flags*: `--x_axis_labels`.`x` | ||
|  | ||
|
|
||
| *arguments*: if `true`, displays samples names labels on x-axis. if `false`, does not display x-axis sample labels. | ||
|  | ||
|
|
||
| ##Genomic Range and Samples Selection - Genotype and Read Depth Heatmaps with Variant Position Labels | ||
|
|
||
| default: `true` | ||
| 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 example.vcf `-x` | ||
| julia VIVA -f test/test_files/test_4X_191.vcf -t Genomic_Range_Chr4:3076150-3076390 -r chr4:3076150-3076390 -y positions --select_samples select_samples_list.txt | ||
| ``` | ||
|
|
||
| ## Export heatmap data as numerical array | ||
|  | ||
|  | ||
|
|
||
| Save input array to heatmap function with column and row labels. | ||
| Specifically, saves numerical array of genotype or read depth values for selected variants and samples as a .csv table with genomic positions and sample names for row names and column names respectively. | ||
|
|
||
| *flags*: `--num_array`, `-n` | ||
|
|
||
| *arguments*: none, this is a positional argument. | ||
|
|
||
| ``` | ||
| julia VIVA -f example.vcf `-n` | ||
| ``` | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,36 +1,57 @@ | ||
| #Installation | ||
|
|
||
| ##Install Julia v1.1.0 | ||
| ### Install Julia v1.1.0 | ||
| Download [Julia]("https://julialang.org/downloads/") | ||
|
|
||
| ##Install the VariantVisualization.jl | ||
| Add `VariantVisualization.jl` at the package prompt in the Julia v1.1 REPL. | ||
| ### Supported Operating Systems: | ||
|
|
||
| ``` | ||
| julia | ||
| #### macOS | ||
|
|
||
| *press the ']' key to enter the package prompt* | ||
| Sierra, High Sierra, and Mojave. | ||
|
|
||
| (v1.1) pkg> add VariantVisualization | ||
| #### Windows | ||
|
|
||
| ``` | ||
| Windows 10, Windows 7 | ||
|
|
||
| If successful, `VariantVisualization.jl` will be installed in your Julia packages directory (.julia/packages/) and VIVA command line tool should install with this. Adding `VariantVisualization.jl` runs a script to create an alias for the command line tool script in the bash shell. This allows the user to call VIVA from any directory. | ||
| ### Command Line Tool | ||
|
|
||
| 1. Add VariantVisualization.jl using Pkg in the Julia REPL: | ||
| a. run `using Pkg` | ||
| b. run `Pkg.clone("https://github.com/compbiocore/VariantVisualization.jl")` | ||
| c. run `Pkg.instantiate()` | ||
| 2. Download the [VIVA](https://github.com/compbiocore/VariantVisualization.jl/blob/master/viva) tool script and save it to a working directory for your analysis. | ||
| 3. Navigate to your working directory and follow the [VIVA manual](https://compbiocore.github.io/VariantVisualization.jl/latest/) to generate your plots. | ||
|
|
||
| ##Install the Jupyter Notebook | ||
| ### Jupyter Notebook | ||
|
|
||
| If you plan to use the Jupyter Notebook VIVA utility, install Jupyter then download the [VIVA Notebook](). | ||
| 1. [Install Jupyter](https://jupyter.org/install) | ||
| 2. Download the [VIVA Jupyter Notebook](https://github.com/compbiocore/VariantVisualization.jl/blob/master/VIVA.ipynb). | ||
| 3. Follow the in-notebook instructions to generate your plots. | ||
|
|
||
| If you already have Jupyter installed, update following [these instructions](https://jupyter.readthedocs.io/en/latest/projects/upgrade-notebook.html) | ||
| ### Latest Features | ||
|
|
||
| To stay up to date with cutting edge development features install VariantVisualization.jl from the Master branch. | ||
|
|
||
| ##New Features | ||
| To stay up to date with new features before official version release, please check out the master branch. | ||
| Using git from the command line: | ||
|
|
||
| ``` | ||
| julia | ||
| git clone https://github.com/compbiocore/VariantVisualization.jl | ||
| ``` | ||
|
|
||
| or from the Julia REPL (useful if using the PowerShell and don't have git installed): | ||
|
|
||
| ```julia | ||
| using Pkg | ||
| Pkg.clone("https://github.com/compbiocore/VariantVisualization.jl") | ||
| ``` | ||
|
|
||
| ### *For Developers* | ||
|
|
||
| VIVA Jupyter notebook and the VIVA the command line tool are built with functions contained in our VariantVisualization.jl package. | ||
|
|
||
| Developers may contribute to these open source tools by using [functions contained within VariantVisualization.jl](https://github.com/compbiocore/VariantVisualization.jl/tree/master/src/) which are carefully documented with docstrings. | ||
|
|
||
| We have included in-line comments within the code for the [VIVA command line tool](https://github.com/compbiocore/VariantVisualization.jl/tree/master/viva). | ||
|
|
||
| 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. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.