README.md

big

Linux/MacOS Windows

big implements high performance classes for reading and writing BigWIG, BigBED and TDF. You can use big in any programming language running on the JVM, but the public API is in part Kotlin-specific.

Installation

The latest version of big is available on jCenter jcenter. If you're using Gradle just add the following to your build.gradle:

repositories {
    jcenter()
}

dependencies {
    compile 'org.jetbrains.bio:big:0.8.3'
}

Examples

The following examples assume that all required symbols are imported into the current scope. They also rely on the helper function for reading TSV formated [chromosome sizes] chrom-sizes from UCSC annotations.

/** Fetches chromosome sizes from a UCSC provided TSV file. */
internal fun Path.chromosomes(): List<Pair<String, Int>> {
    return Files.newBufferedReader(this).lineSequence().map { line ->
        val chunks = line.split('\t', limit = 3)
        chunks[0] to chunks[1].toInt()
    }.toList()
}

wigToBigWig

fun wigToBigWig(inputPath: Path, outputPath: Path, chromSizesPath: Path) {
    BigWigFile.write(WigFile(inputPath), chromSizesPath.chromosomes(), outputPath)
}

bigWigSummary

fun bigWigSummary(inputPath: Path, numBins: Int) {
    BigWigFile.read(inputPath).use { bwf ->
        println("Total: ${bwf.totalSummary}")

        for (chromosome in bwf.chromosomes.valueCollection()) {
            for ((i, summary) in bwf.summarize(chromosome, numBins = numBins).withIndex()) {
                println("bin #${i + 1}: $summary")
            }
        }
    }
}

bedToBigBed

fun bedToBigBed(inputPath: Path, outputPath: Path, chromSizesPath: Path) {
    BigBedFile.write(BedFile(inputPath), chromSizesPath.chromosomes(), outputPath)
}

bigBedToBed

fun bigBedToBed(inputPath: Path) {
    BigBedFile.read(inputPath).use { bbf ->
        for (chromosome in bbf.chromosomes.valueCollection()) {
            for ((chrom, start, end) in bbf.query(chromosome)) {
                // See 'BedEntry' for a complete list of available
                // attributes.
                println("$chrom\t$start\t$end")
            }
        }
    }
}

Building from source

The build process is as simple as

$ ./gradlew assemble

Testing

No extra configuration is required for running the tests from Gradle

$ ./gradlew test

Publishing

You can publish a new release with a one-liner

./gradlew clean assemble test generatePomFileForMavenJavaPublication bintrayUpload

Make sure to set Bintray credentials (see API key section here) in $HOME/.gradle/gradle.properties.

$ cat $HOME/.gradle/gradle.properties
bintrayUser=CHANGEME
bintrayKey=CHANGEME

Useful links

• Kent et al. paper paper in Bioinformatics
• UCSC documentation on WIG wig, BED bed, BigWIG bigwig and BigBED bigbed
• Reference C implementation of both big formats by UCSC
• Sketch of [TDF spec.] tdf in IGV repository and another version [on Gist] tdf-gist