Attention une mise à jour du service Gitlab va être effectuée le mardi 30 novembre entre 17h30 et 18h00. Cette mise à jour va générer une interruption du service dont nous ne maîtrisons pas complètement la durée mais qui ne devrait pas excéder quelques minutes. Cette mise à jour intermédiaire en version 14.0.12 nous permettra de rapidement pouvoir mettre à votre disposition une version plus récente.

browser.org 9.79 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
** The .data files

Mathieu Giraud's avatar
Mathieu Giraud committed
23
The vidjil browser displays .data files that summarize the V(D)J
24 25 26 27 28 29
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
Mathieu Giraud's avatar
Mathieu Giraud committed
30 31
   .fasta/.fastq files, see doc/alog.org in the command-line version).
   To gather several .data files, you have to use the [[../server/fuse.py][fuse.py]] script
32 33 34 35 36 37 38
 - 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
39
* First aid
40

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

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

- 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
50 51
   - 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. 
52
     Once several clones are merged, you can still visualize them by clicking on “+” in the list of clones.
53 54 55 56


* The elements of the Vidjil browser

Mikaël Salson's avatar
Mikaël Salson committed
57 58
** The info panel (upper left panel)
   - analysis :: name of the configuration file used for displaying the data
Mathieu Giraud's avatar
Mathieu Giraud committed
59
   - system :: system used for analyzing the data. In case of multi-system
Mikaël Salson's avatar
Mikaël Salson committed
60
               data, you can select what system should be displayed.
Mathieu Giraud's avatar
Mathieu Giraud committed
61 62 63 64 65
   - 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
66
   - total :: total number of reads for that point
67 68 69

** The list of clones (left panel)

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

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

Mikaël Salson's avatar
Mikaël Salson committed
78 79
- 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
80
  The “+” and “-” allow respectively to un-merge or re-merge all clones that have
Mikaël Salson's avatar
Mikaël Salson committed
81
  already been merged.
82 83 84

** The graph

Mathieu Giraud's avatar
Mathieu Giraud committed
85
- 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
86

87
- 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
88
  If you want to recover some hidden points, you need to drag them from the “+” mark to the graph.
89

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

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


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

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

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

Mikaël Salson's avatar
Mikaël Salson committed
104 105 106 107 108 109 110 111 112
** 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
113
     therefore, you unselect them).
Mikaël Salson's avatar
Mikaël Salson committed
114
   - 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
115
   - You can unselect all sequences by clicking on the background of the scatterplot.
116

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

** The database / server connection (experimental)

A *server* is currently developed to link the browser and the
algorithmic part. The goal is that the clinicians will be able to
upload, manage and process their runs directly on the browser (with
authentication).


*** Patients
      
Once you are authentified, this page show the patient list. Here you
can see your patients and patients whose permission has been given to you.

New patients can be added ('add patient'), edited ('e') or deleted ('X').
By default, you are the only one who can see/access this new patient.
You can grant access to other people or group ('P'),
people will be able to see your patient and make some action depending of the access granted.


*** Samples

Clicking on a patient give acccess the "samples" page. Each sample is
a .fasta/.fastq file that will be processed by one or several
pipelines.
You can see which samples have been processed with the selected
config, and download the sequence files if they are available ("dl").

Depending on your granted accesses, you can 
add a new sample to the list ("add file"), 
schedule a processing for a sequence file (select a config and "run"),
or delete a sample ("X").

The processing can take a few seconds to a few hours, depending on the
software lauched, its options and the size of the sample.
Once the processing is finished, click on the button "see result" and
the browser will load the data of the processed files. The first click
on this button can take a few seconds.

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

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

Mikaël Salson's avatar
Mikaël Salson committed
160
** Number of segmented reads
Mathieu Giraud's avatar
Mathieu Giraud committed
161
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. 
162 163 164 165
     
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
166 167 168
*** 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
169
      (solution: ask that we relaunch Vidjil with other systems)
Mikaël Salson's avatar
Mikaël Salson committed
170 171 172

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

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

Mikaël Salson's avatar
Mikaël Salson committed
177
*** PCR or sequencing causes
178

Mikaël Salson's avatar
Mikaël Salson committed
179 180
   - 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)
181

Mikaël Salson's avatar
Mikaël Salson committed
182 183
   - 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)
184

Mikaël Salson's avatar
Mikaël Salson committed
185 186
   - 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)
187

Mikaël Salson's avatar
Mikaël Salson committed
188
** Control with standard/spike
189

Mikaël Salson's avatar
Mikaël Salson committed
190
   - If your sample included a standard/spike control, you should first
Mathieu Giraud's avatar
Mathieu Giraud committed
191 192
     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
193 194
     Then the data is normalized according to that sequence.
   - You can (de)activate normalization in the settings menu.
195

Mikaël Salson's avatar
Mikaël Salson committed
196 197 198 199 200 201 202
** 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
203

204 205 206 207 208
* Reference

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

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

Mathieu Giraud's avatar
Mathieu Giraud committed
213