Web platform, user manual

Vidjil is an open-source platform for the analysis of high-throughput sequencing data from lymphocytes. V(D)J recombinations in lymphocytes are essential for immunological diversity. They are also useful markers of pathologies, and in leukemia, are used to quantify the minimal residual disease during patient follow-up. With adapted library preparation and sequencing, high-throughput sequencing (NGS/HTS) now enables the deep sequencing of a lymphoid population with dedicated sequencing methods and software, called either Rep-Seq or AIRR-Seq.

This is the help of the Vidjil web application. Further help can always be asked to support@vidjil.org. We can also arrange phone or video meeting.

The Vidjil team (Mathieu, Mikaël, Aurélien, Florian, Marc, Ryan and Tatiana)

Requirements

Supported browsers

The Vidjil web application runs in any modern browser. We recommend to either regularly update one's web browsers, or to use long-term releases, such as Firefox ESR. As of September 2020, we recommend using Firefox or Chrome/Chromium :

These platforms will be supported to at least June 2023. Chrome 79, and possibly other recent versions, are tested through our continuous integration pipelines.

Legacy browsers

We also provide an extended support on

Some of these legacy platforms are also tested through our continuous integration pipelines. However, old platforms have security flaws and are not recommended for routine usage involving clinical data. They may not get the new features, and this extended support may be dropped in September 2021.

Other browsers

Vidjil is also reported to work with recent Edge, IE (version >= 10.0), Opera or Safari browsers, but these browsers are not officialy supported. Note that Vidjil will not run on IE 9.0 or below.

Getting .vidjil files

The vidjil web application displays .vidjil files that summarize the V(D)J recombinations and the sequences found in one or several samples.

The easiest way to get these files is to request an account on the public Vidjil test server. You will then be able to upload, manage, process your samples (.fasta, .fastq, .gz, .bam, or .clntab files) directly on the web application (see The sample database and the server), and the server behind the sample database computes these .vidjil files with vidjil-algo. Otherwise, such .vidjil files can be obtained either:

Contact us if you want help on converting such data.

First aid

You are advised to go through to the tutorial available from http://www.vidjil.org/doc to learn the essential features of Vidjil.

The elements of the Vidjil web application

The info panel (upper left panel)

The list of clones (left panel)

When they were processed by vidjil-algo, clones are described with identifiers such as TRGV3*01 2/ATC/6 J1*02 that describes the V(D)J recombination. Here the sequence was analyzed as the V gene TRGV3*01, with 2 nucleotides deleted at its end (3'), followed by a N region with the three nucleotides ATC, then followed by the J gene TRGJ1*02, with 6 nucleotides deleted at its start (5').

Detailed information on each clone

The “🛈” button opens a window showing detailed information (V(D)J designation, e-value, number of reads) about each clone.

In addition, depending on what the user launched on this clone, we may also find detailed informations retrieved from IMGT or from CloneDB.

Detailed information from CloneDB

(experimental feature) If you are connected to a sample database where CloneDB is enabled, and if CloneDB was launched on the selected clone, you can see here occurrences of this clone in CloneDB as well as links to the relevant patients/runs/sets. Note that the percentage shown can be above 100% as the percentage is calculated over all the samples in the sample set.

The sample graph

The sample graph is displayed as soon as there are at least two samples. It shows the most frequent clones of each sample, tracked into every sample.

The plot view and the plot presets

The grid view shows the clones scattered according to some axes. When there is only one sample, two such views are shown.

The sequence panel (bottom panel)

The sequence panel displays nucleotide sequences from selected clones.

Further sequence analysis with external software

The sequence panel displays buttons to further analyze the selected sequences with other software useful for RepSeq studies. These buttons open another window/tab.

The sample database and the server

If a server with a sample database is configured with your installation of Vidjil (as on the public test server http://app.vidjil.org/ or on the healthcare server http://health.vidjil.org/), the 'samples' menu gives you access to the server.

With authentication, you can add 'patients', 'runs', or 'sets', they are just three different ways to group 'samples'. Samples are .fasta, .fastq, .gz or .clntab files, possibly pre-processed. Once you uploaded samples (either in 'patients', 'runs', or 'sets'), you can process your data and save the results of your analysis.

Patients

⚠️ The public http://app.vidjil.org/ server is for Research Use Only and is not compliant for clinical use. Clinical data have to be uploaded on a certified healthcare server.

Once you are authenticated, this page shows the patient list. Here you can see your patients and patients whose permission has been given to you.

New patients can be added (+ new patients), edited (✏️) or deleted (⌫). By default, you are the only one who can see and update this new patient. If you have an admin access, you can grant access to other users (p).

Runs and sets

Runs and sets can be manipulated the same way as patients. They can be added (+ new runs, + new sets), edited (✏️) or deleted (⌫). They are just different ways to group samples. Sets can for example gather a set of samples of a same experiment. Runs can be used to gather samples that have been sequenced in the same run.

Batch creation of patients/runs/sets

Patients, runs and sets can be added one by one (add patient, add run, add set). They can also be created by pasting data from a properly formatted table created by any spreadsheet editor such as LibreCalc/LibreOffice or Excel.

Data has to be presented with the following columns, but some cells may be empty. Do not copy any header row, but only the data rows.

Patient : 5 columns (patient id, first name, last name, birth date, info)
42 John Doe #ALL
George Sand 1804-02-01

Run : 4 columns (run id, name, date, info)
2020r84 Lib84 2020-09-15
2020r85 Lib85 2020-09-15 new IGH-DJ primers

Set : 2 columns (set name, info)
CohortCLL Retrospective 2015-2019
Mouse1604

Permanent address (URL) to a set of samples

Addresses such as http://app.vidjil.org/3241-25 directly target a set of samples (here the public dataset L3), possibly with your saved analysis. Moreover, the address may also encode other parameters, for instance https://app.vidjil.org/3241-25?plot=clone%20average%20read%20length,J/3%27%20gene,bar&clone=30 (selected axes and selected clones).

To discuss on some results or to raise any issue, you can share such addresses with other users (with whom you share access grants, see below), to your local IT staff or to the Vidjil team.

Samples and pre-processes

Clicking on a patient, a run or a set give acccess to the "samples" page. Each sample is a .fasta, .fastq, .gz or .clntab file that will be processed by one or several pipelines with one or several process configurations that set software options.

Depending on your granted access, you can add a new sample to the list (+ add samples), download sample files when they are available (⬇) or delete sequence files (⌫). Note that sample files may be deleted (in particular to save server disk space), which is not the case for the results (unless the user wants so).

You can see which samples have been processed with the selected process, and access to the results (See results, bottom right).

Adding a sample

To add a sample (+ add samples), you must add at least one sample file. Each sample file must be linked to a patient, a run or a set. One of those fields will be automatically completed depending on whether you accessed the sample page. These fields provide autocompletion to help you enter the correct patient, run or sets. It is advised to fill in both fields (when it makes sense). However please note that the correspondig patients, runs and sets must have been created beforehand.

Pre-processing

The sample files may be preprocessed, by selecting a pre-process scenario when adding a sample. At the moment the only preprocess avalaible on the public server (http://app.vidjil.org) are the paired-end read merging.

  1. Read merging

    People using Illumina sequencers may sequence paired-end R1/R2 fragments. It is highly recommended to merge those reads in order to have a read that consists of the whole DNA fragment instead of split fragments. To merge R1/R2 fragments, select an adapted pre-process scenario and provide both R1/R2 files at once when adding a sample. On the public test server, the default scenarios use the Flash2 read merger with the option -M 300.

    There are two scenarios to merge reads. Indeed in case the merging is not possible for some paired-end reads we must keep only one of the fragments (either R1 or R2). We cannot keep both because it would bias the quantification (as there would be two unmerged reads instead of one). Depending on the sequencing strategy it could be better to keep R1 or R2 in such a case. Therefore it really depends on users and their sequencing protocols. You must choose to keep the fragment that most probably contains both a part of the V and the J genes.

Processing samples and process configurations

Depending on your granted accesses, you can schedule a processing for a sequence file (select a config and run). The processing can take a few seconds to a few hours, depending on the software lauched, the options set in the process configuration, the size of the sample and the server load.

The base human configurations with vidjil-algo are « TRG », « IGH », « multi » (-g germline), « multi+inc » (-g germline -i), « multi+inc+xxx » (-g germline -i -2, default advised configuration). See Libraries and recombinations for information on these processes. There are also processes for other species and for other RepSeq algorithms, such as « MiXCR ». The server mainteners can add new process configurations tailored to specific needs, contact us if you have other needs.

The « reload » button (bottom left) updates the view. It is useful to see if the status of the task changed. It should do QUEUED → ASSIGNED → RUNNING → COMPLETED. It is possible to launch several processes at the same time (some will wait in the QUEUED / ASSIGNED states), and also to launch processes while you are uploading data. Finally, you can safely close the window with the sample database (and even your web browser) when some process are queued/launched. The only thing you should not do is to close completely your web browser (or the webpage) while sequences are uploading.

Once a task is completed, a click on the See results link (bottom right) will open the main window to browse the clones. A click on the out link at the right of every sample give access to the raw output file of the RepSeq software.

Groups

Each patient, run or set is assigned to at least one group. Users are assigned to different groups and therefore gain access to any patients, runs or sets that said group has access to.

Groups may be nested. For example, a group may represents an organization, such as a hospital or a network of hospitals. Subgroups may be created for individual labs and/or for different roles in the labs. This allows users to have different sets of permissions while accessing to some of the files uploaded to the organization's group.

Users may be a part of several groups. By default Users are assigned their personal group to which they can upload files and be the sole possessor of an access to this file. Different groups imply different sets of permissions. A user may not have the same permissions on a file accessed from an organization's group as (s)he does on files from her/his personal group, or even from a group associated to another organization.

The different permissions that can be attributed are:

Usage and processes pages

These pages allow to follow your activity and the activity of your groups.

Usage page

The usage page detail, for each of your groups, data usage and last processes. For each group, you will find:

Processes page

This page lists the last processes you ran, with information such as its configuration and its status. Each sample is provided with links to the related patient/runs/sets.

How do you define clones, their sequences, their V(D)J designation and their productivity?

The Vidjil web application allows to run several RepSeq algorithms. Each RepSeq algorithm (selected by « process configuration », see above) has its own definition of what a clone is (or, more precisely a clonotype), how to output its sequence and how to assign a V(D)J designation. Knowing how clones are defined is important to be aware of the potential biases that could affect your analysis.

How do you define a clone? How are gathered clones?

Some RepSeq studies want to broadly cluster clones to have a global view on the immune repertoire. One may want to focus on CDR3 on the amino-acid level, or on the nucleotide level. One also generally wants to correct technological artifacts (PCR, sequencing). On the contrary, when studying hypermutations in IGH recombinations, people want to know as precisely as possible differences between sequences, even when they occur for a single nucleotide in the V gene or elsewhere.

In vidjil-algo (Giraud, Salson, BMC Genomics 2014), sequences are gathered into a same clone as long as they share the same 50bp DNA sequence around the CDR3 sequence. In a first step, the algorithm has a quick heuristic which detects approximatively where the CDR3 lies and extracts a 50bp nucleotide sequence centered on that region. This region is called a window in vijdil-algo. When two sequences share the same window, they belong to the same clone. Therefore in vidjil-algo clones are only defined based on the (conservative) exact match of a long DNA sequence. This explains why some little clones can be seen around larger clones: They may be due to artifacts that lead to different windows. However those small differences can also be due to a real biological process inside the cells. Therefore we let the user choose whether the clones should be manually clustered or not -- and the choice may depend on the purpose of her study.

In MiXCR, clones are defined based on the amino-acid CDR3 sequence, on the V gene used and on the hypermutations. Other software may have other definitions, see also What is a clone ?.

What is the sequence displayed for each clone ?

The sequences displayed for each clone are not individual reads. The clones may gather thousands of reads, and all these reads can have some differences. Depending on the sequencing technology, the reads inside a clone can have different lengths or can be shifted, especially in the case of overlapping paired-end sequencing. There can be also some sequencing errors. The .vidjil file has to give one consensus sequence per clone, and RepSeq algorithms have to deal with great care to these difference in order not to gather reads from different clones.

For vidjil-algo, it is required that the window centered on the CDR3 is exactly shared by all the reads. The other positions in the consensus sequence are guaranteed to be present in at least half of the reads. The consensus sequence can thus be shorter than some reads.

How are computed the V(D)J designations?

In vijdil-algo, V(D)J designations are computed after the clone clustering by dynamic programming, finding the most similar V (or 5') and J (or 3') gene, then trying to match a D gene. Note that the algorithm also detects some VDDJ or VDDDJ recombinations that may happen in the TRD locus. Some incomplete or unusual rearrangements (Dh/Jh, Dd2/Dd3, KDE-Intron, mixed TRA-TRD recombinations) are also detected.

Once clones are selected, you can send their sequence to IMGT/V-QUEST and IgBlast by clicking on the links just above the sequence panel (bottom left). This opens another window/tab.

How is productivity computed? Why do I have some discrepancies with other software?

Vidjil-algo computes the productivity by checking that the CDR3 comes from an in-frame recombination and that there is no stop codon in the full sequence.

The productivitiy as computed by Vidjil-algo may differ from what computes other software. For instance, as of September 2019, IMGT/V-QUEST removes by default insertions and deletions from the sequences to compute the productivity, as it considers them as sequencing errors.

How can there be discrepancies in annotations of a same clone in different samples?

Sometimes, the "same" clone shows different properties between different samples -- as for exemple different V(D)J designations or productivity prediction. Warnings W81 and W82 are now raised for such situations.

Such differences may come from the way sequences are clustered. When different sequences are clustered in a "same" clone, some of them may actually have different mutations or lengths even if they share the same window. This can also be due to clustering results of different analysis programs, for example with different releases of vidjil-algo.

Can I see all the clones and all the reads ?

The interest of NGS/RepSeq studies is to provide a deep view of any V(D)J repertoire. The underlying analysis softwares (such as vidjil-algo) try to analyze as much reads as possible (see Number of analyzed reads below). One often wants to "see all clones and reads", but a complete list is difficult to see in itself. In a typical dataset with about 106 reads, even in the presence of a dominant clone, there can be 104 or 105 different clones detected. A dominant clone can have thousands or even more reads.

Whereas many applications require to focus on some clones with their consensus sequences, repertoire studies usually consider all clones, for example to assess their diversity or to compare repertoires between samples. Vidjil allows both:

The "top" slider in the "filter" menu

The "top 50" clones are the clones that are in the first 50 ones in at least one sample. As soon as one clone is in this "top 50" list, it is displayed for every sample, even if its concentration is very low in other samples. This is the case for clones tracked in follow-up samples (for example checking minimal residual disease, MRD) after a diagnosis sample.

Most of the time, a "top 50" is enough. The hidden clones are thus the one that never reach the 50 first clones. With a default installation, the slider can be set to display clones until the "top 100" on the grid (and, on the graph, until "top 20").

However, in some cames, one may want to track some known clones that are never in the "top 100", as for example:

In these situations, a solution is to create a .fasta file with this sequences to be tracked and upload it as another sample in the same patient/run/set. It should then show up in any sample.

(Upcoming feature). If clone is "tagged" in the .vidjil or in the .analysis file, it will always be shown even if it does not meet the "top" filter.

Studying the distribution of all clones, including "smaller clones"

Vidjil detects all clones, even if, by default, only the top 50 or 100 clones are displayed with a full analysis. The other clones, that are hidden (because of the "top" or because of hiding some tags) are gathered into virtual clones, shown with light gray.

This enables to study full repertoires, including assessing the polyclonal background and the diversity of the repertoires. Note that selecting color by clone emphasizes the difference between the top clones, colored, and these virtual clones. Depending on the process configuration, these "smaller clones" are shown, in the clone list:

In both cases, the sum of ratios in the list of clones is always 100%: thus these "smaller clones" changes when one uses the "filter" menu.

Note that the ratios include the "smaller clones": if a clone is reported to have 10.54%, this 10.54% ratio relates to the number of analyzed reads, including the hidden clones.

Studying diversity and overlap indices

Several indices are computed on the full list of clones to assess the diversity and overlap of sample(s):

Some of these indices are currently shown on the sample information panel (“🛈” next to the sample name in the info panel). Contact us if you have other needs.

Exporting the full list of clones

The Export all clones (AIRR) process exports all clones in the AIRR format. Such a .tsv file that can be further processed or opened in any spreadsheet editor. The exported fields are described in the documentation of vidjil-algo. Once the process has run, click on See the output files (at the right of COMPLETED) to download this file. Note that results can then not be visualized on the main Vidjil window.

For more specific analyses, we advise to work with bioinformaticians. The full list of clones can be retrieved by launching the command-line vidjil-algo (see documentation), Parsing the .vidjil files gives then all information computed on each clone (see documentation).

Going back to the analyzed reads

The web application displays one consensus sequence per clone (see Representative above). In some situations, one may want to go back to the reads.

For vidjil-algo, analyzing a dataset with the default + extract reads process generates a .detected.vdj.fa file with the reads with detected V(D)J recombinations. This file can be downloaded through the See the output files link near each sample. It enables to use vidjil-algo as a filtering tool, shrinking a large read set into a manageable number of (pre-)clones that will be deeply analyzed and possibly further clustered by other software.

Other custom processes are possible, in particular to retrieve reads for a particular clone. Contact us if you are interested.

How can I assess the quality of the data and the analysis ?

To make sure that the PCR, the sequencing and the RepSeq analysis went well, several elements can be controlled.

Number of analyzed reads

A first control is to check the number of “analyzed reads” in the info panel (top left box). This shows the number of reads where the underlying RepSeq algorithm found some V(D)J recombination in the selected sample.

With DNA-Seq sequencing with specific V(D)J primers, ratios above 90% usually mean very good results. Smaller ratios, especially under 60%, often mean that something went wrong. On the other side, capture with many probes or RNA-Seq strategies usually lead to datasets with less than 0.1% V(D)J recombinations.

The “info“ button further detail the causes of non-analysis (for vijdil-algo, UNSEG, see detail on vidjil-algo documentation. There can be several causes leading to low ratios:

Analysis or biological causes

PCR or sequencing causes

Control with standard/spike

Steadiness verification

Clone coverage

In vidjil-algo, the clone coverage is the ratio of the length of the clone consensus sequence to the median read length in the clone. A consensus sequence is displayed for each clone (see What is the sequence displayed for each clone?). Its length should be representative of the read lengths among that clone. A clone can be constituted of thousands of reads of various lengths. We expect the consensus sequence to be close to the median read length of the clone. The clone coverage is such a measure: having a clone coverage between .85 and 1 is quite frequent. On the contrary, if it is .5 it means that the consensus sequence length is half shorter than the median read length in the clone.

There is a bad clone coverage (\< 0.5) when reads do share the same window (it is how Vidjil defines a clone) and when they have frequent discrepancies outside of the window. Such cases have been observed with chimeric reads which share the same V(D)J recombinations in their first half and have totally different and unknown sequences in their second half.

In the web application, the clones with a low clone coverage (\< 0.5) are displayed in the list with an orange I on the right. You can also visualize the clones according to their clone coverage by selecting for example “clone coverage/GC content” in the preset menu of the “plot” box.

E-value

Vidjil-algo computes an e-value of the found recombination. An e-value is the number of times such a recombination is expected to be found by chance. The lower the e-value the more robust the detection is.

Whenever the e-value is too large, a warning sign will be shown next to the clone, instead of the info icon.

How can I have further support or help on a specific sample or on some sequences?

When you have questions on specific data, we advise to use the help > get support link inside the web application. This opens a mail template with reference to the sample, and possibly with references to the selected clones.

Indeed, the address http://app.vidjil.org/3241-25?clone=3 reflects the sample you are studying with a given process configuration. When you select one or several clones, the address is updated.

Note that, even knowing this address, only the logged-in users with proper authorization can access to these data. This includes the uploader of the data, possibly users of the same groups if such groups were defined, and the server maintainers.

Settings

The settings menu allows to set:

These settings are kept in your web browser ``localStorage'' between several sessions.

Keyboard shortcuts

Note that some shortcuts may not work on some systems or on on some web browsers.
← and → navigate between samples
Shift-← and Shift-→ decrease or increase the number of displayed clones
numeric keypad, 0-9 switch between available plot presets
# switch between grid and bar modes
z zoom/focus on selected clones
Shift-z hide the selected clones
z or Shift-z with no clone selected reset the zoom/focus
+ cluster selected clones
Backspace revert to previous clusters
a: TRA
b: TRB
g: TRG
d: TRD, TRD+ change the selected germline/locus
h: IGH, IGH+
l: IGL
k: IGK, IGK+
x: xxx

Note: You can select just one locus by holding the Shift key while pressing the letter corresponding to the locus of interest.
Ctrl-s save the analysis (when connected to a database)
Shift-p open the database panel (when connected to a database)

References

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

Marc Duez et al., “Vidjil: A web platform for analysis of high-throughput repertoire sequencing”, PLOS ONE 2016, 11(11):e0166126 http://dx.doi.org/10.1371/journal.pone.0166126

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