|
1 | | -# Plotting |
| 1 | +# Examples |
2 | 2 |
|
3 | | -##General notes: visualization options |
| 3 | +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. |
4 | 4 |
|
5 | | -Here we describe VIVA options for plotting. All plots can be generated in a single command. |
| 5 | +Once Julia and VariantVisualization.jl are installed, you can run the following examples and should see the same outputs. |
6 | 6 |
|
7 | | -VIVA orders all variants by chromosomal location for plotting. |
| 7 | +## Default Options |
8 | 8 |
|
9 | | -VIVA graphics are generated with PlotlyJS.jl. Graphics can be saved in *HTML*, *PDF*, *SVG*, *PNG*, and *EPS* formats. |
10 | | - |
11 | | -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. |
12 | | - |
13 | | -To create *publication quality, scalable graphics* for presentations and publications, we recommend saving graphics as PDF. |
14 | | - |
15 | | -## Genotype and read depth heatmaps |
16 | | - |
17 | | -Plot a categorical heatmap of genotype values and a continuous value heatmap of read depth (coverage) values. |
18 | | - |
19 | | -*flags*: `--heatmap`,`-m` |
20 | | - |
21 | | -*arguments*: `genotype`, `read_depth`, or `genotype,read_depth` |
22 | | - |
23 | | -default: `genotype,read_depth` (plots both) |
24 | | - |
25 | | -``` |
26 | | -julia VIVA -f example.vcf -m genotype |
27 | | -``` |
28 | | - |
29 | | -## Average read depth scatter plots |
30 | | - |
31 | | -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. |
32 | | - |
33 | | - |
34 | | -*flags*: `--avg_dp` |
35 | | - |
36 | | -*arguments*: `samples`, `variants`, or `samples,variants` |
37 | | - |
38 | | -default: `none` |
39 | | - |
40 | | -``` |
41 | | -julia VIVA -f example.vcf --avg_dp variants |
42 | | -``` |
43 | | - |
44 | | -## Save file format |
45 | | - |
46 | | -Specify file format you wish to save all graphics as (eg. pdf, html, png). [REQUIRED] |
47 | | - |
48 | | -*flags*: `--save_format`, `-s` |
49 | | - |
50 | | -*arguments*: `html`, `pdf`, `svg`, `png`, `eps` |
51 | | - |
52 | | -default: `html` |
| 9 | +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) |
53 | 10 |
|
54 | 11 | ``` |
55 | | -julia VIVA -f example.vcf --avg_dp variants |
56 | | -``` |
57 | | - |
58 | | -## Output directory |
59 | | - |
60 | | -Specify output directory for saving all graphics. If directory doesn't exist, it creates the directory within the working directory. Defaults to "output." |
61 | | - |
62 | | -Select directory to save output files. If path doesn't exist, creates new directory. |
63 | | - |
64 | | -*flags*: `--output_directory`, `-o` |
65 | | - |
66 | | -*arguments*: filepath |
67 | | - |
68 | | -default: `output` |
69 | | - |
70 | | -``` |
71 | | -julia VIVA -f example.vcf -o my_output_directory |
72 | | -``` |
73 | | - |
74 | | -## Title |
75 | | - |
76 | | -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. |
77 | | - |
78 | | -*flags*: `--heatmap_title`, `-t` |
79 | | - |
80 | | -*arguments*: title_text |
81 | | - |
82 | | -default: original vcf filename |
83 | | - |
| 12 | +julia VIVA -f test_4X_191.vcf -t Default_Options |
84 | 13 | ``` |
85 | | -julia VIVA -f example.vcf -t your_heatmap_title |
86 | | -``` |
87 | | - |
88 | | -## Y-axis label options |
89 | 14 |
|
90 | | -Choose an option for displaying y-axis ticklabels showing the genomic position of variants on heatmaps and scatter plots. |
| 15 | + |
91 | 16 |
|
92 | | -*flags*: `--y_axis_labels`, `-y` |
| 17 | + |
93 | 18 |
|
94 | | -*arguments*: `chromosomes`, `positions`, `hoverlabels_only` |
| 19 | +## Grouping Samples by Metadata Traits and Generating all Four Plots |
95 | 20 |
|
96 | | -`chromosomes` separates chromosomes by adding chromosome label on the first variant of each new chromosome. |
97 | | -`positions` labels every variant position (recommended only for visualizing a few variants e.g. <20) |
98 | | -`hoverlabels_only` no genomic position labels |
| 21 | +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. |
99 | 22 |
|
100 | | -default: `chromosomes` |
| 23 | +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.) |
101 | 24 |
|
102 | 25 | ``` |
103 | | -julia VIVA -f example.vcf `-y` `hoverlabels_only` |
| 26 | +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 |
104 | 27 | ``` |
105 | 28 |
|
106 | | -## X-axis label options |
| 29 | + |
107 | 30 |
|
108 | | -Choose an option for displaying x-axis ticklabels showing the sample id of samples included heatmaps and scatter plots. |
| 31 | + |
109 | 32 |
|
110 | | -*flags*: `--x_axis_labels`.`x` |
| 33 | + |
111 | 34 |
|
112 | | -*arguments*: if `true`, displays samples names labels on x-axis. if `false`, does not display x-axis sample labels. |
| 35 | + |
| 36 | + |
| 37 | +##Genomic Range and Samples Selection - Genotype and Read Depth Heatmaps with Variant Position Labels |
113 | 38 |
|
114 | | -default: `true` |
| 39 | +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. |
115 | 40 |
|
116 | 41 | ``` |
117 | | -julia VIVA -f example.vcf `-x` |
| 42 | +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 |
118 | 43 | ``` |
119 | 44 |
|
120 | | -## Export heatmap data as numerical array |
| 45 | + |
| 46 | + |
121 | 47 |
|
122 | | -Save input array to heatmap function with column and row labels. |
123 | | -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. |
124 | | - |
125 | | -*flags*: `--num_array`, `-n` |
126 | | - |
127 | | -*arguments*: none, this is a positional argument. |
128 | | - |
129 | | -``` |
130 | | -julia VIVA -f example.vcf `-n` |
131 | | -``` |
132 | | - |
133 | | - |
0 commit comments