Слияние кода завершено, страница обновится автоматически
GATK 4
В этом репозитории представлено новое поколение Genome Analysis Toolkit (GATK). Содержимое этого репозитория на 100% является открытым исходным кодом и выпущено под лицензией Apache 2.0 (см. LICENSE.TXT).
GATK4 стремится объединить хорошо зарекомендовавшие себя инструменты из кодовых баз GATK и Picard в рамках оптимизированной структуры, а также обеспечить возможность запуска выбранных инструментов массово параллельным способом на локальных кластерах или в облаке с использованием Apache Spark. Он также содержит множество новых инструментов, которых не было в более ранних выпусках набора инструментов.
brew tap homebrew/cask-versions, а затем brew install --cask temurin17, чтобы установить OpenJDK 17 от Eclipse Foundation.gatk)После загрузки выполните команду git lfs install, а затем в корне вашего git-клона — git lfs pull для загрузки всех больших файлов, включая файлы, необходимые для запуска набора тестов. Общий объём загрузки составляет примерно 5 гигабайт.
В качестве альтернативы, если вы просто собираете GATK и не запускаете набор тестов, этот шаг можно пропустить, так как сама сборка будет использовать git-lfs для загрузки минимального набора больших файлов ресурсов LFS, необходимого для завершения сборки. Тестовые ресурсы загружаться не будут, но это значительно уменьшает размер загрузки.
./gradlew, который автоматически загрузит и использует соответствующую версию gradle (см. примеры ниже).Предварительно упакованные образы Docker со всеми установленными зависимостями можно найти в нашем репозитории dockerhub по ссылке: https://hub.docker.com/r/broadinstitute/gatk/. Для этого требуется последняя версия клиента docker, которую можно найти на веб-сайте docker по адресу: https://www.docker.com/get-docker.
Зависимости Python:
GATK4 использует диспетчер пакетов Conda для создания и управления средой Python и зависимостями, необходимыми инструментам GATK с зависимостью от Python. Эта среда также включает зависимости R, используемые для построения графиков в некоторых инструментах. Среда gatk требует оборудования с поддержкой AVX для инструментов, зависящих от TensorFlow (например, CNNScoreVariant). Образ Docker GATK поставляется с предварительно настроенной средой gatk.
На данный момент поддерживаются только 64-битные дистрибутивы Linux. Требуемая среда Conda в настоящее время не поддерживается в OS X/macOS.
Чтобы создать среду, когда образ Docker не используется, сначала необходимо «создать», а затем «активировать» среду conda:
conda env create -f gatkcondaenv.yml, чтобы создать среду gatk../gradlew localDevCondaEnv. Это генерирует архив пакета Python и файл(ы) зависимостей yml в каталоге сборки, а также создаёт (или обновляет) локальную среду conda gatk.source activate gatk, чтобы активировать среду gatk../gradlew bundle (создаёт gatk-VERSION.zip в build/)../gatk --help../gatk --list../gatk PrintReads -I src/test/resources/NA12878.chr17_69k_70k.dictFix.bam -O output.bam../gatk PrintReads --help.Вы можете загрузить и запустить готовые версии GATK4 со следующих сайтов:
Архив zip со всем необходимым для запуска GATK4 можно скачать для каждого выпуска со страницы релизов github по ссылке: https://github.com/broadinstitute/gatk/releases. Также мы размещаем нестабильные архивы, создаваемые ежедневно в Google bucket gs://gatk-nightly-builds.
Вы можете загрузить образ Docker GATK4 из нашего репозитория dockerhub по ссылке: https://hub.docker.com/r/broadinstitute/gatk/. Хост нестабильных ночных сборок разработки в этом репозитории Docker Hub (https://hub.docker.com/r/broadinstitute/gatk-nightly/).
В образе Docker запускайте команды gatk как обычно из каталога запуска по умолчанию (/gatk).
Наш образ Docker содержит следующие инструменты биоинформатики, которые можно запустить, вызвав имя инструмента из командной строки:
Также мы включаем установку Python 3 (3.6.10) со следующими популярными пакетами:
Мы также включаем установку R (3.6.2) со следующими популярными пакетами:
Для получения более подробной информации о системных пакетах см. базовый файл Dockerfile GATK (scripts/docker/gatkbase/Dockerfile), а для получения дополнительной информации о пакетах Python 3/R см. файл настройки среды Conda (scripts/gatkcondaenv.yml.template). Версии пакетов Python 3/R можно найти там.
Чтобы выполнить полную сборку GATK4, сначала клонируйте репозиторий GATK с помощью «git clone», затем запустите:
./gradlew bundle
Эквивалентно, вы можете просто ввести:
./gradlew
build/ с именем вроде gatk-VERSION.zip, содержащий полный автономный дистрибутив GATK, включая наш лаунчер gatk, как локальные, так и spark jar-файлы, и этот README.Другие способы сборки:
./gradlew installDist
./gradlew installAll
./gradlew localJar
build/libs с именем типа gatk-package-VERSION-local.jar и может использоваться вне вашего git-клона../gradlew sparkJar
build/libs с именем типа gatк-package-VERSION-spark.jar и может использоваться вне вашего git-клона.Чтобы удалить предыдущие сборки, запустите:
./gradlew clean
Для ускорения операций gradle добавьте org.gradle.daemon=true в ваш файл ~/.gradle/gradle.properties.
Это позволит сохранить gradle-демон работающим в фоновом режиме и избежать ~6-секундного времени запуска gradle при каждой команде.
Gradle хранит кэш зависимостей, используемых для сборки GATK. По умолчанию он находится в ~/.gradle. Если в вашем домашнем каталоге недостаточно свободного места, вы можете изменить расположение кэша, установив переменную среды GRADLE_USER_HOME.
Номер версии автоматически определяется из истории git с использованием git describe, вы можете переопределить его, установив свойство versionOverride.
( ./gradlew -DversionOverride=my_weird_version printVersion )
gatk, расположенный в корневом каталоге клона этого репозитория.
./gradlew bundle, в каталог и запуска gatk оттуда;gatk в тот же каталог, что и полностью упакованные JAR-файлы GATK, созданные с помощью команд ./gradlew localJar и/или ./gradlew sparkJar;GATK_LOCAL_JAR и GATK_SPARK_JAR, установив их равными путям к JAR-файлам GATK, созданным с помощью команд ./gradlew localJar и/или ./gradlew sparkJar.GATK может запускать инструменты как на основе Spark, так и без него, а также инструменты Spark локально, в кластере Spark или в Google Cloud Dataproc.
Примечание: запуск с использованием java -jar напрямую и в обход gatk приводит к тому, что некоторые важные системные свойства не устанавливаются, включая уровень сжатия htsjdk!
Для получения справки по использованию самого GATK, выполните команду ./gatk --help.
Чтобы вывести список доступных инструментов, выполните команду ./gatk --list. Инструменты на основе Spark будут иметь имя, оканчивающееся на Spark (например, BaseRecalibratorSpark). Большинство других инструментов не основаны на Spark.
Чтобы получить справку по конкретному инструменту, выполните команду ./gatk ToolName --help.
Чтобы запустить инструмент без Spark или запустить инструмент Spark локально, синтаксис следующий: ./gatk ToolName toolArguments.
Аргументы инструмента, допускающие несколько значений, такие как -I, можно предоставить в командной строке с помощью файла с расширением «.args». Каждая строка файла должна содержать одно значение аргумента.
Примеры:
./gatk PrintReads -I input.bam -O output.bam
./gatk PrintReadsSpark -I input.bam -O output.bam
Чтобы передать аргументы JVM в GATK, запустите gatk с аргументом --java-options:
./gatk --java-options "-Xmx4G" <остальная часть команды>
./gatk --java-options "-Xmx4G -XX:+PrintGCDetails" <остальная часть команды>
Чтобы передать конфигурационный файл в GATK, запустите gatk с аргументом --gatk-config-file:
./gatk --gatk-config-file GATKProperties.config <остальная часть команды>
Пример конфигурационного файла GATK поставляется с каждым выпуском как GATKConfig.EXAMPLE.properties. Этот пример файла содержит все текущие параметры, используемые GATK, и их значения по умолчанию.
Многие инструменты GATK4 могут читать входные данные BAM или VCF из корзины Google Cloud Storage. Просто используйте префикс «gs://»:
./gatk PrintReads -I gs://mybucket/path/to/my.bam -L 1:10000-20000 -O output.bam
Важно: для этого необходимо сначала настроить учётные данные! Есть три варианта:
gcloud auth application-default login
gcloud auth activate-service-account --key-file "$PATH_TO_THE_KEY_FILE"
GOOGLE_APPLICATION_CREDENTIALS, чтобы она указывала на файлexport GOOGLE_APPLICATION_CREDENTIALS="$PATH_TO_THE_KEY_FILE"
Инструменты GATK4 Spark можно запускать в локальном режиме (без кластера). В этом режиме Spark будет запускать инструмент
в нескольких параллельных потоках выполнения, используя ядра вашего процессора. Вы можете контролировать, сколько потоков
Spark будет использовать с помощью аргумента --spark-master.
Примеры:
Запустите PrintReadsSpark с 4 потоками на локальном компьютере:
./gatk PrintReadsSpark -I src/test/resources/large/CEUTrio.HiSeq.WGS.b37.NA12878.20.21.bam -O output.bam \
-- \
--spark-runner LOCAL --spark-master 'local[4]'
Запустите PrintReadsSpark, используя столько рабочих потоков, сколько логических ядер на вашем локальном компьютере:
./gatk PrintReadsSpark -I src/text/resources/large/CEUTrio.HiSeq.WGS.b37.NA12878.20.21.bam -O output.bam \
-- \
--spark-runner LOCAL --spark-master 'local[*]'
Обратите внимание, что аргументы, специфичные для Spark, отделены от аргументов, специфичных для инструмента, символом --.
./gatk ToolName toolArguments -- --spark-runner SPARK --spark-master <master_url> additionalSparkArguments
Примеры:
./gatk PrintReadsSpark -I hdfs://path/to/input.bam -O hdfs://path/to/output.bam \
-- \
--spark-runner SPARK --spark-master <master_url>
./gatk PrintReadsSpark -I hdfs://path/to/input.bam -O hdfs://path/to/output.bam \
-- \
--spark-runner SPARK --spark-master <master_url> \
--num-executors 5 --executor-cores 2 --executor-memory 4g \
--conf spark.executor.memoryOverhead=600
Вы также можете опустить аргумент --num-executors, чтобы включить динамическое распределение, если вы правильно настроите кластер (см. веб-сайт Spark для получения инструкций).
Обратите внимание, что аргументы, специфичные для Spark, отделены от аргументов, специфичных для инструмента, символом --.
Для запуска инструмента Spark в кластере необходимо установить Spark с сайта http://spark.apache.org/, поскольку
gatk за кулисами вызывает инструмент spark-submit.
Обратите внимание, что в приведённых выше примерах используется YARN, но мы успешно запустили GATK4 и на Mesos.
gatk вызывает инструмент gcloud за кулисами. В процессе установки обязательно
следуйте инструкциям по настройке gcloud здесь. Поскольку эта библиотека часто обновляется Google, мы рекомендуем регулярно обновлять вашу копию, чтобы избежать трудностей, связанных с версиями.gs://my-gcs-bucket/path/to/my-file
После настройки вы можете запустить инструмент Spark в своём кластере Dataproc, используя команду вида:
./gatk ToolName toolArguments -- --spark-runner GCS --cluster myGCSCluster additionalSparkArguments
Примеры:
./gatk PrintReadsSpark \
-I gs://my-gcs-bucket/path/to/input.bam \
-O gs://my-gcs-bucket/path/to/output.bam \
-- \
--spark-runner GCS --cluster myGCSCluster
./gatk PrintReadsSpark \
-I gs://my-gcs-bucket/path/to/input.bam \
-O gs://my-gcs-bucket/path/to/output.bam \
-- \
--spark-runner GCS --cluster myGCSCluster \
--num-executors 5 --executor-cores 2 --executor-memory 4g \
--conf spark.yarn.executor.memoryOverhead=600 **Не используйте `toString()` ни для чего, кроме потребления человеком (т. е. не основывайте логику своего кода на результатах `toString()`).**
Не переопределяйте clone(), если вы действительно не знаете, что делаете. Если вы всё же переопределите его, тщательно задокументируйте это. В противном случае предпочитайте другие способы создания копий объектов.
Для логирования используйте org.apache.logging.log4j.Logger.
Мы в основном следуем руководству по стилю Google Java Style guide (https://google.github.io/styleguide/javaguide.html).
Git: Не отправляйте напрямую в мастер — вместо этого создайте запрос на вытягивание.
Git: При слиянии перебазируйте и объедините коммиты.
Если вы отправляете изменения в мастер или портите историю коммитов, вы должны нам 1 гроулер или вкусные закуски во время «счастливого часа». Если вы нарушаете сборку мастера, вы должны 3 гроулера (или много вкусных закусок). Пиво можно заменить вином (по цвету и году выпуска по выбору покупателя) в пропорции 1 гроулер = 1 бутылка.
Перед запуском тестового набора убедитесь, что вы установили git lfs и скачали большие тестовые данные, следуя инструкциям по настройке git lfs (#lfs).
Чтобы запустить тестовый набор, выполните команду ./gradlew test.
* Отчёт о тестировании находится в build/reports/tests/test/index.html.
* Что произойдёт, зависит от значения переменной среды TEST_TYPE:
* не задано или любое другое значение: запускаются не облачные модульные и интеграционные тесты, это значение по умолчанию;
* cloud, unit, integration, conda, spark: запускаются только облачные, модульные, интеграционные, conda (python + R) или Spark тесты;
* all: запускается весь тестовый набор.
* Облачные тесты требуют входа в систему gcloud и аутентификации с проектом, который имеет доступ к облачным тестовым данным. Они также требуют установки нескольких определённых переменных среды.
* HELLBENDER_JSON_SERVICE_ACCOUNT_KEY: путь к локальному файлу JSON с учётными данными службы (https://cloud.google.com/storage/docs/authentication#service_accounts);
* HELLBENDER_TEST_PROJECT: ваш проект Google Cloud;
* HELLBENDER_TEST_STAGING: путь gs:// к доступному для записи местоположению;
* HELLBENDER_TEST_INPUTS: путь к облачным тестовым данным, например: gs://hellbender/test/resources/.
* Установка переменной среды TEST_VERBOSITY=minimal приведёт к меньшему объёму вывода из тестового набора.
Чтобы выполнить подмножество тестов, используйте фильтрацию тестов Gradle (см. документацию Gradle (https://docs.gradle.org/current/userguide/java_plugin.html)):
* Вы можете использовать --tests с подстановочным знаком для запуска определённого тестового класса, метода или для выбора нескольких тестовых классов:
* ./gradlew test --tests *SomeSpecificTestClass;
* ./gradlew test --tests *SomeTest.someSpecificTestMethod;
* ./gradlew test --tests all.in.specific.package*.
Чтобы запустить тесты и создать отчёты о покрытии, выполните команду ./gradlew jacocoTestReport. Отчёт будет находиться в build/reports/jacoco/test/html/index.html. (IntelliJ имеет хороший инструмент покрытия, который предпочтительнее для разработки).
В качестве поставщика непрерывной интеграции мы используем Github Actions (https://github.com/broadinstitute/gatk/actions/workflows/gatk-tests.yml).
* Прежде чем объединять какую-либо ветку, убедитесь, что все необходимые тесты пройдены на Github.
* Каждая сборка действий будет загружать результаты тестирования в наше хранилище Google Cloud Storage и zip-архив загрузки артефактов. Ссылка на загруженный отчёт появится в самом низу журнала действий github. Ищите строку, которая говорит: «Смотрите отчёт об испытаниях». Отчёты о тестах действий Github не будут отображаться на веб-странице до завершения всего теста. Если сам TestNG выйдет из строя, отчёт не будет создан.
Для наших длительных тестов и тестов производительности мы используем Broad Jenkins (https://gatk-jenkins.broadinstitute.org/view/Performance/).
* Чтобы добавить тест производительности (требуется Broad-ID), вам нужно создать «новый элемент» в Jenkins и сделать его «копией», а не пустым проектом. Вам нужно основать его либо на «-spark-». **Использование Git LFS для загрузки и отслеживания больших тестовых данных**
Мы используем git-lfs для управления версиями и распространения тестовых данных, которые слишком велики, чтобы их можно было проверить в нашем репозитории напрямую. Вы должны установить и настроить его, чтобы иметь возможность запускать наш набор тестов.
После установки git-lfs, запустите git lfs install.
Чтобы вручную получить большие тестовые данные, запустите git lfs pull из корня вашего клона GATK git.
Чтобы добавить новый большой файл для отслеживания с помощью git-lfs, просто:
src/test/resources/large (или подкаталог).git add файлы, затем git commit -a.git lfs track для файлов вручную: все файлы в src/test/resources/large автоматически отслеживаются git-lfs.Создание проекта GATK в среде IntelliJ IDE (последний раз тестировалось с версией 2016.2.4):
Убедитесь, что у вас установлены gradle и JDK Java 17.
Возможно, вам потребуется установить плагины TestNG и Gradle (в настройках).
Клонируйте репозиторий GATK с помощью git.
В IntelliJ нажмите «Импортировать проект» на главном экране или перейдите в «Файл» -> «Новый...» -> «Проект из существующих источников...».
Выберите корневой каталог вашего клона GATK, затем нажмите «ОК».
Выберите «Импортировать проект из внешней модели», затем «Gradle», затем нажмите «Далее».
Убедитесь, что «Gradle project» указывает на файл build.gradle в корне вашего клона GATK.
Выберите «Использовать автоимпорт» и «Использовать оболочку gradle по умолчанию».
Убедитесь, что Gradle JVM указывает на Java 17. Возможно, вам придётся установить это вручную после создания проекта, для этого найдите настройки gradle, нажав значок гаечного ключа на вкладке gradle на правой панели, оттуда отредактируйте аргумент «Gradle JVM», чтобы он указывал на Java 17.
Нажмите «Готово».
После загрузки зависимостей проекта IntelliJ должен открыть новое окно с вашим проектом GATK.
Убедитесь, что версия Java установлена правильно, перейдя в «Файл» -> «Структура проекта» -> «Проект». Проверьте, что «Project SDK» установлен на ваш JDK Java 17, а «Уровень языка проекта» — на 17 (возможно, вам потребуется добавить свой JDK Java 17 в разделе «Настройки платформы» -> SDK, если его там ещё нет). Затем нажмите «Применить» / «Ок».
Настройка отладки в IntelliJ
Следуйте инструкциям выше для создания проекта IntelliJ для GATK.
Перейдите в «Выполнить» -> «Редактировать конфигурации», затем нажмите «+» и добавьте новую конфигурацию «Приложение».
Установите имя новой конфигурации на что-то вроде «Отладка GATK».
Для «Главного класса» введите org.broadinstitute.hellbender.Main.
Убедитесь, что «Использовать путь к классам модуля:» настроен на использование пути к классам модуля «gatk».
Введите аргументы команды, которую вы хотите отладить, в «Аргументы программы».
Нажмите «Применить» / «Ок».
Устанавливайте точки останова и т. д., как требуется, затем выберите «Выполнить» -> «Отладка» -> «Отладка GATK», чтобы начать сеанс отладки.
В будущих сеансах отладки вы можете просто настроить «Аргументы программы» в конфигурации «Отладка GATK» по мере необходимости.
Обновление проекта Intellij при изменении зависимостей
Если в build.gradle есть изменения зависимостей, необходимо обновить проект gradle. Это легко сделать с помощью следующих шагов.
Настройка профилирования с использованием JProfiler
./gradlew localJar.Также можно работать в облаке, используя Google Dataproc.
В кластерном сценарии ваши входные и выходные файлы находятся на HDFS, а Spark будет работать распределённым образом в кластере.
Документация Spark содержит хороший обзор архитектуры.
Обратите внимание, что если у вас нет выделенного кластера, вы можете запустить Spark в автономном режиме на одном компьютере, который использует распределённые пути кода, хотя и на одном узле.
Во время выполнения задания Spark пользовательский интерфейс Spark UI — отличное место для отслеживания прогресса. Кроме того, если вы запускаете тесты, то добавив -Dgatk.spark.debug=true, вы можете выполнить один тест Spark и посмотреть на пользовательский интерфейс Spark (на http://localhost:4040/), пока он выполняется.
Вы можете найти дополнительную информацию о настройке Spark и выборе хороших значений для важных параметров, таких как количество исполнителей и настройки памяти, по следующим ссылкам:
Мы приветствуем все вклады в проект GATK. Вклад может быть отчётом об ошибке или запросом на вытягивание. Если вы не коммиттер, вам нужно сделать форк репозитория gatk и отправить запрос на вытягивание из вашего форка.
Чтобы узнать, над чем поработать, проверьте проблемы с меткой «Требуется помощь (Сообщество)». Оставьте комментарий к проблеме, чтобы показать свою заинтересованность в написании кода и поделиться своими вопросами и идеями.
Для внесения исправления:
./gradlew test в корневом каталоге.Мы внимательно читаем запросы на вытягивание, и вы можете получить много комментариев. Некоторые вещи, которые следует учитывать:
IllegalArgumentException, если они недействительны.if, for и т. д.final, если нет веской причины не делать этого.a+b, а a + b и не foo(int a,int b), а foo(int a, int b).Спасибо за участие!
Список авторов находится в файле AUTHORS. Также см. список Contributors на GitHub.
Лицензия Apache 2.0. См. файл LICENSE.txt.
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Комментарии ( 0 )