browser.org 8.2 KB
Newer Older
Mathieu Giraud's avatar
Mathieu Giraud committed
1
#+TITLE: Vidjil -- Browser Manual
Mikaël Salson's avatar
Mikaël Salson committed
2
#+AUTHOR: The Vidjil team (Mathieu, Mikaël and Marc)
3

Mathieu Giraud's avatar
Mathieu Giraud committed
4 5
This is the help of the Vidjil browser : [[http://www.vidjil.org/browser]].
This help will be extended in a few months.
Mikaël Salson's avatar
Mikaël Salson committed
6
Further help can always be asked to [[mailto:contact@vidjil.org][contact@vidjil.org]]. We can also arrange phone or Skype meeting.
7 8 9

The Vidjil team (Mathieu, Mikaël and Marc)

Mathieu Giraud's avatar
Mathieu Giraud committed
10
* Requirements
11

12 13
** Browser

14 15 16 17 18 19 20
The Vidjil browser runs in any modern browser. It has been successfully tested on the following platforms
 - Firefox version >= XX
 - Chrome version >= XX
 - IE version >= XX
 - Opera version >= XX
 - Safari version >= XX

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
** The .data files

The vidjil browser displays .data files that summarizes the V(D)J
rearrangements and the sequences found in a run. Such files can be
obtained:
 - by sending us your .fasta/.fastq files, either through
   http://www.vidjil.org/submit.html or using any other method
   (e.g. your own FTP)
 - from the command-line version of Vidjil (starting from
   .fasta/.fastq files, see doc/README in the command-line version)
 - in a next release (start of 2015), you will be able to upload,
   manage and process your runs (.fasta/.fastq files) directly on the browser (with
   authentication to ensure that you keep the control on your data).
 - or by post-processing of other V(D)J analysis pipelines (contact us
   if you are interested)


Mathieu Giraud's avatar
Mathieu Giraud committed
38
* First aid
39

40
- Go to the “file” menu to access your data.
41
  Your files are protected with your login and password.
42
  There is always a “sample/L2-LIL.data” dataset for demonstration purposes.
43

44
- You can change the number of displayed clones by moving the slider “number of clones” (menu “filter”)
Mathieu Giraud's avatar
Mathieu Giraud committed
45
  The maximal number of clones that can be displayed depends on what has been run before
46 47 48

- Due to sequencing errors, there may be several clones corresponding to a real clone. 
   - You can select several clones (for example those sharing a same V and a same J), 
Mathieu Giraud's avatar
Mathieu Giraud committed
49 50
   - inspect the sequences in the lower panel (possibly using the “align” function),
   - and click on “merge” if you think that the clones should be merged. 
51
     Once several clones are merged, you can still visualize them by clicking on “+” in the list of clones.
52 53 54 55


* The elements of the Vidjil browser

Mikaël Salson's avatar
Mikaël Salson committed
56 57
** The info panel (upper left panel)
   - analysis :: name of the configuration file used for displaying the data
Mathieu Giraud's avatar
Mathieu Giraud committed
58
   - system :: system used for analyzing the data. In case of multi-system
Mikaël Salson's avatar
Mikaël Salson committed
59
               data, you can select what system should be displayed.
Mathieu Giraud's avatar
Mathieu Giraud committed
60 61 62 63 64
   - point :: name of the current point (you can change the selected point by clicking on
              another point in the graph). The name can be edited (“...” button).
   - date :: when the run was performed (manually curated, with “...” button)
   - segmented :: number of reads where Vidjil found a CDR3, for that point.
                  See [[Number of segmented reads]] below.
Mikaël Salson's avatar
Mikaël Salson committed
65
   - total :: total number of reads for that point
66 67 68

** The list of clones (left panel)

Mathieu Giraud's avatar
Mathieu Giraud committed
69
- You can assign other tags (and thus colors) to clones using the “★” button.
70
  The “filter” menu allows to further filter clones by tags.
Mathieu Giraud's avatar
Mathieu Giraud committed
71
- Under the “★” button it is possible to normalize clone concentrations
Mikaël Salson's avatar
Mikaël Salson committed
72
  according to this clone. You must specify the expected concentration in the
Mathieu Giraud's avatar
Mathieu Giraud committed
73
  “expected size” field (e.g. 0.01 for 1%). See [[Control with standard/spike]] below.
74

Mathieu Giraud's avatar
Mathieu Giraud committed
75
- The “i” button displays additional information on each clone.
76

Mikaël Salson's avatar
Mikaël Salson committed
77 78
- The list can be sorted on V genes, J genes or concentrations. At the top of
  the list you need to click respectively on “V sort”, “J sort” or “sort”.
Mathieu Giraud's avatar
Mathieu Giraud committed
79
  The “+” and “-” allow respectively to un-merge or re-merge all clones that have
Mikaël Salson's avatar
Mikaël Salson committed
80
  already been merged.
81 82 83

** The graph

Mathieu Giraud's avatar
Mathieu Giraud committed
84
- The gray areas at the bottom of the graph show, for each point, the resolution (1 read / 5 reads).
Mikaël Salson's avatar
Mikaël Salson committed
85

86
- You can reorder the points by dragging them, and hide some points by dragging them on the “+” mark at the right of the points.
Mikaël Salson's avatar
Mikaël Salson committed
87
  If you want to recover some hidden points, you need to drag them from the “+” mark to the graph.
88

89
- If your dataset contains sampling dates (for example in a MRD setup), you can switch between point keys and dates in “settings > point key”
90

Mikaël Salson's avatar
Mikaël Salson committed
91
- The vertical gray area shows the current point, you can change that by clicking on another point.
92 93


Mikaël Salson's avatar
Mikaël Salson committed
94
** The scatterplot view
95

Mathieu Giraud's avatar
Mathieu Giraud committed
96
- The axes of the plot (by default “V gene” / “J gene”) can be changed.
97

98
- Some presets are available in the “analysis” menu.
99 100
  
  To segregate a set of clones sharing a same V and J, it is often useful
Mathieu Giraud's avatar
Mathieu Giraud committed
101
  to display the clones according to their “N length” (that is N1-D-N2 in the case of VDJ rearrangements)
102

Mikaël Salson's avatar
Mikaël Salson committed
103 104 105 106 107 108 109 110 111
** The aligner (bottom panel)
   - When several clones are selected (you can select clones by clicking on
     them either in the list, the graph or the scatterplot, or by drawing a
     rectangle around clones to be selected in the scatterplot view), you can
     view their sequences in the aligner.
   - Sequences can be aligned together to see how they differ or how similar
     they are (“align” button). After aligning them a shaded background identifies
     substitutions and a dash identifies indels.
   - You can remove sequences from the aligner by clicking on their name (and
Mathieu Giraud's avatar
Mathieu Giraud committed
112
     therefore, you unselect them).
Mikaël Salson's avatar
Mikaël Salson committed
113
   - You can visualize results by IMGT/V-QUEST and IgBlast on the selected sequences, in another window, by clicking on the corresponding buttons.
Mathieu Giraud's avatar
Mathieu Giraud committed
114
   - You can unselect all sequences by clicking on the background of the scatterplot.
115

Mikaël Salson's avatar
Mikaël Salson committed
116
* Assessing the quality of your data and of the analysis
117

Mikaël Salson's avatar
Mikaël Salson committed
118
To make sure that the PCR, the sequencing and the Vidjil analysis went well, several elements can be controlled.
119

Mikaël Salson's avatar
Mikaël Salson committed
120
** Number of segmented reads
Mathieu Giraud's avatar
Mathieu Giraud committed
121
A first control is to check the number of “segmented reads” in the info panel. For each point, this shows the number of reads where Vidjil found a CDR3. 
122 123 124 125
     
Ratios above 90% usually mean very good results. Smaller ratios, especially under 60%, often mean that something went wrong.
There can be several causes leading to bad ratios: 

Mikaël Salson's avatar
Mikaël Salson committed
126 127 128
*** analysis or biological causes

   - a system (for example TRG) was analyzed and the data actually contains other systems.
Mathieu Giraud's avatar
Mathieu Giraud committed
129
      (solution: ask that we relaunch Vidjil with other systems)
Mikaël Salson's avatar
Mikaël Salson committed
130 131 132

   - there are incomplete/exceptional rearrangements 
     (Vidjil can process some of them)
133

Mikaël Salson's avatar
Mikaël Salson committed
134 135
   - there are too many hypersomatic mutations
     (usually Vidjil can process mutations until 10% mutation rate... above that threshold, some sequences are lost)
136

Mikaël Salson's avatar
Mikaël Salson committed
137
*** PCR or sequencing causes
138

Mikaël Salson's avatar
Mikaël Salson committed
139 140
   - the read length is too short, the reads do not span the junction zone 
      (Vidjil detects a “window” including the CDR3. By default this window is 40–60bp long, so the read needs be that long)
141

Mikaël Salson's avatar
Mikaël Salson committed
142 143
   - In particular, for paired-end sequencing, one of the ends can lead to reads not fully containing the CDR3 region
      (solution: ignore this end, or extend the read length)
144

Mikaël Salson's avatar
Mikaël Salson committed
145 146
   - There were too many PCR or sequencing errors
      (this can be asserted by inspecting the related clones, checking if there is a large dispersion around the main clone)
147

Mikaël Salson's avatar
Mikaël Salson committed
148
** Control with standard/spike
149

Mikaël Salson's avatar
Mikaël Salson committed
150
   - If your sample included a standard/spike control, you should first
Mathieu Giraud's avatar
Mathieu Giraud committed
151 152
     identify the main standard sequence (if that is not already done) and
     specify its expected concentration (by clicking on the “★” button).
Mikaël Salson's avatar
Mikaël Salson committed
153 154
     Then the data is normalized according to that sequence.
   - You can (de)activate normalization in the settings menu.
155

Mikaël Salson's avatar
Mikaël Salson committed
156 157 158 159 160 161 162
** Steadiness verification
   - When assessing different PCR primers, PCR enzymes, PCR cycles, one may want to see how regular the concentrations are among the points.
   - When following a patient one may want to identify any clone that is emerging.
   - To do so, you may want to change the color system, in the “color” menu
     select “by abundance at selected timepoint”.  The color ranges from red
     (high concentration) to purple (low concentration) and allows to easily
     spot on the graph any large change in concentration.
Mathieu Giraud's avatar
Mathieu Giraud committed
163

164 165 166 167 168
* Reference

If you use Vidjil for your research, please cite the following reference:

Mathieu Giraud, Mikaël Salson, et al.,
169
“Fast multiclonal clusterization of V(D)J recombinations from high-throughput sequencing”,
170 171 172
BMC Genomics 2014, 15:409 
http://dx.doi.org/10.1186/1471-2164-15-409

Mathieu Giraud's avatar
Mathieu Giraud committed
173