Документация

Описание предстваляет собой адаптированный перевод англоязычной документации. Рекомендуем в первую очередь обращаться к англоязычной версии.

VDJtools

VDJtools — это первая платформа с открытым исходным кодом на основе Java/Groovy, предназначенная для облегчения пост-анализа данных секвенирования иммунного репертуара (RepSeq). VDJtools вычисляет широкий набор статистик для единичных репертуаров, а также может выполнять различные формы анализа пересечений репертуаров. Результаты VDJtools представляет как подробные табличные данные, так и графики, готовые к публикации.

Использование VDJtools позволяет биоинформатикам обеспечить воспроизводимость и согласованность между методами постанализа и результатами. А также VDJtools предоставляет достаточно простой инструмент командной строки, который могут использовать иммунологи и биологи с небольшим опытом компьютерных вычислений.

Исходный код и двоичные файлы VDJtools находятся по ссылке.

Программное обеспечение предоставляется «как есть», и лицензиар не обязан предоставлять обслуживание, поддержку, обновления, улучшения или модификации.

Требования к программному обеспечению

VDJtools можно запускать на любой платформе, на которой установлена среда выполнения для Java, которая распространяется свободна и может быть скачана с сайта Oracle. Программное обеспечение распространяется в виде исполняемого файла JAR.

Для графического вывода требуется установка языка программирования R и соответствующих модулей.

Дополнительные сведения см. в разделе «Установка VDJtools».

Требования к аппаратному обеспечению

VDJtools можно запускать на большинстве стандартных аппаратных средств, и он оптимизирован для использования преимуществ параллельных вычислений. VDJtools был успешно подвергнут стресс-тестированию с использованием около 70 различных образцов, содержащих репертуары около 500 000 Т-клеток человека на сервере UNIX с двумя процессорами Intel Xeon E5-1620 и 64 ГБ оперативной памяти.

Входные данные

В настоящее время для анализа при помощи VDJtools можно импортировать результаты следующих программ: MiTCR, MiGEC, IgBlast, IMGT, ImmunoSEQ, VDJdb, Vidjil, RTCR, MiXCR, ImSEQ.

Установка VDJtools

Установка бинарных файлов

Сначала убедитесь, что у вас установлена среда выполнения Java (JRE) v1.8 или выше, запустив java -version. Любой недавний дистрибутив Linux предоставит его через менеджер пакетов. Если нет или если ваша система работает под управлением MacOSX или Windows, загрузите JRE с сайта Oracle.

Затем загрузите и распакуйте бинарные файлы VDJtools последней версии по ссылке.

Затем программа запускается путем выполнения следующей строки:

java -jar path-to-vdjtools-X.X.X.jar

где XX обозначает версию VDJtools (далее опущена для простоты). Откроется список доступных процедур. Чтобы просмотреть детали (параметры и т. д.) для конкретной процедуры, выполните

java -jar vdjtools.jar RoutineName -h

Windows

Специальный пакет VDJtools для Windows можно загрузить по ссылке. Он отмечен суффиксом .win.zip.

Linux

Специальный пакет VDJtools для Windows можно загрузить по ссылке. Он отмечен суффиксом .jar.

MacOS

Установку можно выполнить с помощью менеджера пакетов Homebrew:

brew tap homebrew/science

brew tap mikessh/repseq

brew install vdjtools

Обратите внимание, что при этом vdjtools становится ярлыком для java -jar vdjtools-X.X.X.jar. Аргументы JVM, такие как -Xmx, по-прежнему могут передаваться в сценарий, например, vdjtools -Xmx20G CalcBasicStats ....

Настройка графического вывода

Все построения графиков в среде VDJtools выполняются посредством запуска сценариев R. Поэтому необходимо установить язык программирования R и несколько его пакетов. Убедись в том, что

Rscript --version

работает успешно. Обратите внимание, что все сценарии R были протестированы в версии R 3.1.0.

Необходимые пакеты для выполнения графического вывода: ape, circlize, FField, ggplot2, gplots, grid, gridExtra, MASS, plotrix, RColorBrewer, reshape, reshape2, scales, VennDiagram.

Если ваш дистрибутив Linux включает предварительно упакованные версии пакета, им следует отдать предпочтение. Следующая команда установит существующие дистрибутивы для Debian и Debian, такие как Ubuntu и Mint:

apt-get install r-cran-ape r-cran-ggplot2 r-cran-gplots r-cran-mass r-cran-plotrix r-cran-rcolorbrewer r-cran-reshape r-cran-reshape2 r-cran-scales

в то время как другие пакеты необходимо будет установить через сам R:

install.packages(c("circlize", "grid", "gridExtra", "VennDiagram"))

Другой способ – установка через команду Rinstall в VDJtools:

java -jar vdjtools.jar Rinstall

В случае невозможности установить необходимые пакеты через Rinstall их можно установить вручную, выполнив в R следующую команду:

java -jar vdjtools.jar Rinstallinstall.packages(c("reshape2", "FField", "reshape", "gplots", "gridExtra", "circlize", "ggplot2", "grid", "VennDiagram", "ape", "MASS", "plotrix", "RColorBrewer", "scales"))

Обратите внимание, что большинство проблем с установкой пакета можно решить, переключившись на правильное зеркало CRAN.

В бинарные файлы для Windows уже включены все пакеты R, и описанное выше следует учитывать только для устранения проблем с выполнением сценариев R.

Компиляция из исходного кода

VDJtools можно скомпилировать из исходного кода с помощью Apache Maven. Компиляцию следует выполнять используя JRE v1.8, выполнив следующие команды:

git clone https://github.com/mikessh/vdjtools.git

cd vdjtools/

mvn clean install

Использование

Общий способ выполнения команд VDJtools следующий:

java -Xmx16G -jar vdjtools.jar RoutineName [arguments] -m metadata.txt output/prefix

Префикс для вывода результатов может быть либо именем выходного каталога (если заканчивается /), либо префиксом выходного файла. Большинство команд VDJtools добавляют к префиксу интуитивно понятный суффикс и расширение.

Аргумент -m метаданные.txt указывает файл метаданных с относительными путями к образцам, именами образцов и любой другой информацией, которую можно предоставить позже при анализе.

В качестве альтернативы аргумент -m можно заменить списком файлов, разделенных пробелами, например:

java -Xmx16G -jar vdjtools.jar RoutineName sample1.txt[.gz] sample2.txt[.gz] ... output/prefix

Аргумент -h выведет справочное сообщение для указанной команды.

Подробную документацию по каждой комманде можно найти по ссылке.