Документация
Описание предстваляет собой адаптированный перевод англоязычной документации. Рекомендуем в первую очередь обращаться к англоязычной версии.
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
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 выведет справочное сообщение для указанной команды.
Подробную документацию по каждой команде можно найти по ссылке.
Входные данные
Метаданные
Большинство команд VDJtools принимают несколько файлов в качестве аргументов командной строки для пакетной обработки. Это всегда должно быть предпочтительнее нескольких вызовов VDJTools из-за времени инициализации VDJTools.
Альтернативный способ указать входные файлы — передать файл метаданных с опцией -m. Файл должен содержать пути к файлам образцов и имена образцов. Его также можно дополнить дополнительными столбцами метаданных, которые будут добавлены к результатам анализа и могут использоваться для построения графиков.
Альтернативный способ указать входные файлы — передать файл метаданных с опцией -m. Файл должен содержать пути к файлам образцов и имена образцов. Его также можно дополнить дополнительными столбцами метаданных, которые будут добавлены к результатам анализа и могут использоваться для построения графиков.
Кроме того, для каждого шага, который включает в себя модификацию образцов (например, преобразование или фильтрацию нефункциональных перестановок), в папке, содержащей обработанную партию образцов, создается новый файл метаданных.
Метадата – табличный файл, содержащий обязательные колонки file_name и sample_id с путями к файлам и уникальными названиями соответственно. Значения должны быть разделены табуляцией.
Клонотип
Спецификация клонотипа VDJtools включает следующие поля:
- Имя Vсегмента (V)
- Название D сегмента (D) для некоторых цепей рецепторов (TRB, TRD и IGH)
- Имя J сегмента (J)
- Нуклеотидная последовательность CDR3 (CDR3nt)
- Аминокислотная последовательность CDR3 (CDR3aa)
Данные о численности клонотипов представлены полями количества (count) и частоты (frequency):
Count: количество ридов или молекул кДНК/ДНК в случае использования UMI.
Frequency: доля клонотипа в выборке.
Следующие поля не являются обязательными, но используются для расчета различной статистики и визуализации:
Vend, Dstart, Dend и Jstart - маркировка границ сегментов V, D и J в пределах нуклеотидной последовательности CDR3.
Формат входных табличных данных для VDJtools указан ниже. Все наборы данных должны быть преобразованы в этот формат с помощью команды ‘Convert’ перед анализом. Подробное описание команды ‘Convert’ смотри ниже. Столбцы 8–10 являются необязательными.
| col1 | col2 | col3 | col4 | col5 | col6 | col7 | col8 | col9 | col10 | col11 |
|---|---|---|---|---|---|---|---|---|---|---|
| count | frequency | CDR3nt | CDR3aa | V | D | J | Vend | Dstart | Dend | Jstart |
| 1176 | 9.90E‑02 | TGTGCCAGC…AAGCTTTCTTT | CAST…EAFF | TRBV12‑4 | TRBD1 | TRBJ1‑1 | 11 | 14 | 16 | 23 |
Команда ‘Convert’
Преобразует наборы данных из произвольного поддерживаемого формата в формат VDJtools. Вы также можете повторно нормализовать свои данные — свернуть клонотипы по нуклеотидным последовательностям V, D, J и CDR3 и повторно вычислить частоты клонотипов — с помощью опции -S VDJtoolsRenorm. Это полезно, если вы хотите обработать данные, конвертированные вручную, или если по какой-то причине ваши частоты клонотипов не равны 1.
Использование
java -Xmx16G -jar vdjtools.jar Convert [options] [sample1.txt sample2.txt ... если -m не указан] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -S | --software | Название поддерживаемого формата данных (mitcrб, migec, migmap, immunoseq,imgthighvquest, rtcr, mixcr, imseq) | Конвертация в формат VDJtools из поддерживаемого формата данных |
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -c | --compress | Сжать выходные данные |
Команда CalcBasicStats
Эта команда вычисляет набор основных статистических данных, таких как количество прочтений, количество клонотипов и т. д.
Использование
java -Xmx16G -jar vdjtools.jar CalcBasicStats [options] [sample1.txt sample2.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -u | -unweighted | Если данный параметр не выставлен, все статистики будут взвешенными по частоте клонотипов | |
| -h | –help | Вывести справку на экран |
Команда CalcSegmentUsage
Эта процедура вычисляет использования сегментов V и J, то есть частоту связанных считываний для каждого из сегментов V/J, присутствующих в выборке(ах). Если построение графиков включено, также будет выполняться кластеризация для использования V/J и образцов, аналогичных анализу экспрессии генов.
Использование
java -Xmx16G -jar vdjtools.jar СalcSegmentUsage [options] [sample1.txt sample2.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -u | -unweighted | Если данный параметр не выставлен, все статистики будут взвешенными по частоте клонотипов | |
| -p | --plot | Включает графический вывод | |
| -f | --factor | Имя колонки в метаданных, которую стоит интерпретировать как фактор при построении графиков | |
| -n | --numeric | Указывает является ли фактор числовым значением | |
| -l | --label | Указывает подписи для графического вывода | |
| -h | –help | Вывести справку на экран |
Команда CalcSpectratype
Вычисляет спектротип, то есть гистограмму количества чтений по длине нуклеотида CDR3. Спектральный тип полезен для обнаружения патологического и высококлонального репертуара, поскольку спектральный тип не экспансированных Т- и В-клеток имеет симметричное распределение, подобное гауссу.
Использование
java -Xmx16G -jar vdjtools.jar CalcSpectratype [options] [sample1.txt sample2.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -u | -unweighted | Если данный параметр не выставлен, все статистики будут взвешенными по частоте клонотипов | |
| -a | --amino-acid | Для расчета будем использовать аминокислотные последовательности CDR3 вместо нуклеотидных. | |
| -h | –help | Вывести справку на экран |
Команда PlotFancySpectratype
Показывает спектротип, который также отображает длины CDR3 для N топовых клонотипов в данном образце. Этот график позволяет обнаружить сильно экспансированные клонотипы.
Использование
java -Xmx16G -jar vdjtools.jar PlotFancySpectratype [options] sample.txt output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -u | -unweighted | Если данный параметр не выставлен, все статистики будут взвешенными по частоте клонотипов | |
| -h | –help | Вывести справку на экран |
Команда PlotSpectratypeV
Показывает подробный спектротип, содержащий дополнительную информацию, отображает распределение длин CDR3 для клонотипов из N топовых семейств вариабельных сегментов. Этот график полезен для выявления ошибок 1 и 2 типов, в репертуарах, которые могут возникнуть при патологических состояниях.
Использование
java -Xmx16G -jar vdjtools.jar PlotSpectratypeV [options] sample.txt output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -t | –top | Количество клонотипов, которые необходимо визуализировать | |
| -u | -unweighted | Если данный параметр не выставлен, все статистики будут взвешенными по частоте клонотипов | |
| -h | –help | Вывести справку на экран |
Команда PlotQuantileStats
Строит трехслойную кольцевую диаграмму для визуализации клональности репертуара.
-
Первый слой («набор») включает в себя частоту клонотипов синглтона («1», встретились один раз), даблтона («2», встретились дважды) и высокого порядка («3+», встретились три и более раз). Частота синглтона и даблтона является важным фактором при оценке общего разнообразия репертуара, например. Средство оценки разнообразия Chao1. Мы также показали, что в образцах цельной крови одиночные клетки имеют очень хорошую корреляцию с количеством наивных Т-клеток, которые являются основой разнообразия иммунного репертуара.
-
Второй слой («квантиль») отображает численность верхних 20% («Q1»), следующих 20% («Q2»), … (до «Q5») клонотипов для клонотипов из набора «3+». По нашему опыту, этот квантильный график — простой и эффективный способ продемонстрировать клональность репертуара.
-
Последний слой («верхний») отображает индивидуальное содержание верхних N клонотипов.
Использование
java -Xmx16G -jar vdjtools.jar PlotQuantileStats [options] sample.txt output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -t | –top | Количество клонотипов, которые необходимо визуализировать | |
| -h | –help | Вывести справку на экран |
Команда RarefactionPlot
Строит зависимости между разнообразием выборки и размером выборки. Эти кривые интерполируются от 0 до текущего размера выборки, а затем экстраполируются до размера самой большой выборки, что позволяет сравнивать оценки разнообразия. Интерполяция и экстраполяция основаны на полиномиальных моделях.
Использование
java -Xmx16G -jar vdjtools.jar RarefactionPlot [options] [sample1.txt sample2.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -i | --intersect-type | strict,nt,ntV,ntVJ,aa,aaV,aaVJ and aa!nt | Тип пересечения, используемый для объединения клонотипов перед вычислением разнообразия. По умолчанию — strict (не объединяются). |
| -s | --steps | Oбщее количество точек на кривой, по умолчанию — 101. | |
| -f | --factor | Имя колонки в метаданных, которую стоит интерпретировать как фактор при построении графиков | |
| -n | --numeric | Указывает является ли фактор числовым значением | |
| -l | --label | Указывает подписи для графического вывода | |
| --wide-plot | Установить широкую область графического вывода | ||
| -label-exact | Если установлено значение true, метки образцов будут располагаться точно в соответствии с наблюдаемым размером выборки, в противном случае будет использоваться экстраполированный размер выборки. | ||
| -h | –help | Вывести справку на экран |
Команда CalcDiversityStats
Вычисляет набор статистик о разнообразии, включая
-
Наблюдаемое разнообразие, общее количество клонотипов в образце.
-
Нижняя граница оценок общего разнообразия (LBTD).
-
Оценка Чао (обозначается chao1)
-
Оценка Эфрона-Тистеда
-
-
Индексы разнообразия
-
Индекс Шеннона-Винера. Возвращается показатель степени энтропии распределения частот клонотипов.
-
Нормализованный индекс Шеннона-Винера. Нормализованная (деленная на log[количество клонотипов]) энтропия распределения частот клонотипов. Обратите внимание, что возвращается простая энтропия, а не ее показатель.
-
Обратный индекс Симпсона
-
-
Экстраполированная оценка разнообразия Чао, обозначенная здесь как chaoE.
-
Индекс d50, недавно разработанная оценка иммунного разнообразия.
Оценки разнообразия вычисляются в двух режимах: с использованием исходных данных и с помощью нескольких этапов повторной выборки (обычно с понижением выборки до размера наименьшего набора данных).
-
Оценки, рассчитанные на основе исходных данных, могут быть искажены из-за неравномерной глубины выборки (размера выборки), из которых только chaoE правильно нормализован для сравнения между выборками. Хотя оценки LBTD, предоставленные для исходных данных, не подходят для сравнения между выборками, они наиболее полезны для изучения фундаментальных свойств изучаемых репертуаров, то есть для ответа на вопрос, насколько большим может быть разнообразие репертуара всего организма.
-
Оценки, рассчитанные с использованием повторной выборки, полезны для сравнения между выборками, например. мы успешно использовали повторно отобранное (нормализованное) наблюдаемое разнообразие для измерения тенденций старения репертуара..
Использование
java -Xmx16G -jar vdjtools.jar CalcDiversityStats [options] [sample1.txt sample2.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -m | --metadata | путь к метаданным | Использовать метаданные для чтения файлов |
| -i | --intersect-type | strict,nt,ntV,ntVJ,aa,aaV,aaVJ and aa!nt | Тип пересечения, используемый для объединения клонотипов перед вычислением разнообразия. По умолчанию — strict (не объединяются). |
| -х | --downsample-to | Установите размер выборки, чтобы интерполировать оценки разнообразия посредством повторной выборки. По умолчанию = размер наименьшей выборки. Применяется к оценкам разнообразия, хранящимся в таблице .resampled.txt. | |
| --resample-trials | Количество повторных выборок для соответствующей оценки. По умолчанию = 3 | ||
| -h | –help | Вывести справку на экран |
Команда OverlapPair
Выполняет комплексный анализ пересечения клонотипов для пары образцов.
Использование
java -Xmx16G -jar vdjtools.jar OverlapPair [options] sample1.txt sample2.txt output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -i | --intersect-type | strict,nt,ntV,ntVJ,aa,aaV,aaVJ and aa!nt | Тип пересечения, используемый для объединения клонотипов перед вычислением разнообразия. По умолчанию — strict (не объединяются). |
| -t | –top | Количество клонотипов, которые необходимо визуализировать | |
| -p | --plot | Включает графический вывод | |
| --plot-area-v2 | Альтернативный режим построения: последовательности CDR3 клонотипа показаны по бокам графика и соединены с соответствующими областями линиями. | ||
| -h | –help | Вывести справку на экран |
Команда CalcPairwiseDistances
Выполняет попарное пересечение «всех против всех» для списка образцов и вычисляет набор мер сходства репертуара. Необходимо предоставить не менее 3 образцов. Обратите внимание, что это одна из наиболее требовательных к памяти процедур, поскольку она загружает все сэмплы в память одновременно (если не используется с опцией --low-mem).
Меры сходства репертуара включают.
-
Корреляция Пирсона частот клонотипов, ограниченная только перекрывающимися клонотипами
-
Относительное разнообразие перекрытия
-
Среднее геометрическое относительных частот перекрытия
-
Сумма средних геометрических частот по клонотипам
-
Расхождение Дженсена-Шеннона между профилями использования сегментов переменных
-
Индекс Жаккара
-
Индекс Морисита-Хорма
Использование
java -Xmx16G -jar vdjtools.jar CalcPairwiseDistances [options] [sample1.txt sample2.txt sample3.txt ... if -m is not specified] output_prefix
Параметры
| Короткое имя | Длинное имя | Аргумент | Описание |
|---|---|---|---|
| -i | --intersect-type | strict,nt,ntV,ntVJ,aa,aaV,aaVJ and aa!nt | Тип пересечения, используемый для объединения клонотипов перед вычислением разнообразия. По умолчанию — strict (не объединяются). |
| --low-mem | Режим с малым объемом памяти: во время выполнения в памяти будет храниться только пара сэмплов, но он будет работать намного медленнее. | ||
| -p | --plot | Включает графический вывод | |
| -h | –help | Вывести справку на экран |