A Java API for high-throughput sequencing data (HTS) formats.
HTSJDK is an implementation of a unified Java library for accessing common file formats, such as SAM and VCF, used for high-throughput sequencing data. There are also an number of useful utilities for manipulating HTS data.
NOTE: HTSJDK has only partial support for the latest Variant Call Format Specification. VCFv4.3 can be read but not written and there is no support for BCFv2.2
API documentation for all versions of HTSJDK since
1.128are available through javadoc.io.
If you believe you have found a bug or have an issue with the library please a) search the open and recently closed issues to ensure it has not already been reported, then b) log an issue.
The project has a gitter chat room if you would like to chat with the developers and others involved in the project.
To receive announcements of releases and other significant project news please subscribe to the htsjdk-announce google group.
HTSJDK is now built using gradle.
A wrapper script (
gradlew) is included which will download the appropriate version of gradle on the first invocation.
Example gradle usage from the htsjdk root directory: - compile and build a jar
./gradlewor
./gradlew jarThe jar will be in build/libs/htsjdk-<version>.jar where version is based on the current git commit.
./gradlew test --tests AlleleUnitTest
./gradlew test --tests AlleleUnitTest --debug-jvm ```
run tests and collect coverage information (report will be in
build/reports/jacoco/test/html/index.html)
./gradlew jacocoTestReport
./gradlew clean
./gradlew shadowJar
./gradlew install
./gradlew tasks
To create a project in IntelliJ IDE for htsjdk do the following:
File -> New -> Project from Existing Sources
Import from existing model, select
Gradleand
Next
default gradle wrapperand
Finish.
From time to time if dependencies change in htsjdk you may need to refresh the project from the
View -> Gradlemenu.
Style guides files are included for Intellij and Eclipse. These are a variation of the Google Java Style with 4 space indentation. This style is suggested for new code but not rigidly checked. We allow for contributors to deviate from the style when it improves clarity or to match surrounding code. Existing code does not necessarily conform to this and does not need to be modified to do so, but users are encouraged to correct the formatting of code that they modify.
Not all sub-packages of htsjdk are subject to the same license, so a license notice is included in each source file or sub-package as appropriate. Please check the relevant license notice whenever you start working with a part of htsjdk that you have not previously worked with to avoid any surprises. Broadly speaking the majority of the code is covered under the MIT license with the following notable exceptions:
tribblecode (underlying VCF reading/writing amongst other things) is under LGPL
Htsjdk currently targets Java 8 and is tested on both 8 and 11. We do not currently plan to support versions of Java which are not long-term-support releases (ex: 9, 10, or 12).
We will notify the community at least 6 months before we plan to stop support for Java 8.
Java SE Major Release |
End of Java SE Oracle Public Updates / OpenJDK support | Proposed End of Support in HTSJDK | Actual End of Support in HTSJDK |
---|---|---|---|
6 | Feb 2013 | Aug 2013 | Oct 2015 |
7 | Apr 2015 | Oct 2015 | Oct 2015 |
8 | Jan 2019 | TBD | TBD |
11 | Sep 2022 | TBD | TBD |
We encourage downstream projects to use the most recent htsjdk release in order to have access to the most up to date features and bug fixes. It is therefore important therefore to make upgrading to newer versions as easy as possible. We make a best effort to adhere to the following principles in order to minimize disruption to projects that depend on htsjdk: * Avoid making breaking changes whenever possible. A breaking change is one which requires downstream projects to recompile against the new version of htsjdk or make changes to their source code. These include both binary incompatiblities and source incompatibilites. * Deprecate and provide new alternatives instead of removing exising APIs. * Document breaking changes in the release notes. * Provide clear instructions for upgrading to new API's when breaking changes/ deprecations occur. * Provide explanations for the rare cases when functionality is deprecated or removed without replacement.
We treat any accessible class/method/field as part of our API and attempt to minimize changes to it with the following exceptions: * The
htsjdk.samtools.crampackage and subpackages are considered unstable and are undergoing major changes. * Code which has not yet been released in a numbered version is considered unstable and subject to change without warning. * We consider changes to public code more disruptive than changes to protected code in classes that we believe are not generally subclassed by the downstream community.
Our current version number has 3 parts. ex: 2.19.0