VDJviz: a versatile immune repertoire browser
VDJviz is a web-based graphical user interface application that allows browsing and analyzing immune repertoire sequencing (RepSeq) data. It can be used to visualize results of MITCR, MIGEC, MIXCR and MIGMAP RepSeq processing software as well as popular IMGT/HighV-QUEST and ImmunoSEQ Analyzer services. VDJviz can be installed and used as a local server, alternatively you can use an online demo version available at https://vdjviz.cdr3.net/ which currently has an upload limit of 25 datasets each having size at most 10,000 clonotypes. The list of VDJviz features at a glance:
- Clonotype table browsing with V/D/J markup.
- CDR3 pattern matching for a single sample and across multiple samples with flexible filters.
- Spectratype, V-Spectratype, V-J usage and clonality analysis. Those can be compared side-by-side using the Compare panel.
- Summary statistics and rarefaction for multiple samples.
- Clonotype sharing across samples (many-to-many intersection) with flexible clonotype matching criteria.
- Uploaded data sharing.
VDJviz uses VDJtools API as a back-end. The software utilizes Play framework for running the server instance and state-of-art web graphics libraries such as D3js for visualization.
The most straightforward way to install VDJviz as a local server is to download the latest release package.
After downloading unzip the package wherever you want, but please avoid long paths and spaces (Windows version is especially sensitive to it).
You can find the server executable in
bin/ directory. To set up the server:
bash vdjviz -Dconfig.file=application.confin your console (Linux/Mac OS)
Wait until the server is started, and go to
localhost:9000 URL in your browser to open VDJviz.
The user generator is enabled in the config by default, so you can login with
firstname.lastname@example.org as an email and
vdjviz1 as password,
To stop application just press
Ctrl-C at any time in console.
Troubleshooting. Note that an exception will be thrown in case the
9000port is busy:
org.jboss.netty.channel.ChannelException: Failed to bind to: /0.0.0.0:9000. In order to fix it, either close the application that is using this port (in UNIX the
lsof -i:9000will give the processes that are using the port) or pass the
XXXXis new port id) argument to
vdjvizshell script (UNIX) /
VDJviz server configuration can be performed by manually editing
application.conf file in the
bin/ directory. The configuration file has the following fields:
application.secretThe secret key used in cryptographic hash functions.
uploadPathSpecifies the path that will be used by VDJviz to store user's uploaded files. You can use '~' symbol as a shortcut for user home directory. Default:
maxFileSizeFile size limit in kB Default:
maxFilesCountLimit on the number of uploaded files per user. Default:
maxClonotypesCountLimit on the number of clonotypes for each uploaded file. Default:
allowSharingDisable or enable sharing feature Default:
maxSharedGroupsMaximum number of shared analyses per user. Default:
deleteAfterTime period after which uploaded files are deleted from the server, in hours. Default:
applyNewLimitsToOldUsersIf set to
truethe server will automatically update limtis of all existing user accounts according to the ones specified in config. If set to
false, the limits will only be applied to newly created users. Default:
createDefaultUsersSpecifies whether the server will generate some default user accounts with predefined emails and passwords, setting their emails to
email@example.com) and passwords to
vdjviz1). Set this option to
falseif you don't need this feature and prefer to use registration via SMTP. Default:
nDefaultUsersNumber of default users to be created. Default:
nameDefaultUserDefault user name prefix. Default:
userManagementSystemEnable user management (admin) panel for users with admin rights Default:
userManagementSystemAccountsSpecifies the list of user accounts with predefined emails and passwords that will be granted admin rights. The
application.confshould be used to specify their credentials.
db.default.urlPoints to the path that will be used to store H2 database file. Default value:
~/vdjviz/h2.dbStandalone version uses H2 Database for handling metadata by default, if you want to change H2 to another DBMS please see the corresponding Play documentation section You can also use this database to manually modify user limits.
allowRegistrationShow the Register button in login screen. Default:
allowChangePasswordsShow the Change Password button in login screen. Default:
smtp.*SMTP server configuration. If you don't want to use registration features, you can leave
smtp.*fields empty and generate default users.