Ballc NPM | npm.io

BAllC

BAllC is a javascript API for reading and querying the BAllC files. The original C++ BAllC project is available here.

Installation

Requires Node

$ npm install ballc

Examples

import { BAllC } from "ballc";

//@para: filePath (object): {path: /path/to/ballc, url: https://path/to/ballc, ...}, path or url is required. 
//@para: chrRange (str): chr{chrName}:{start}-{end}

async function testBAllC(filePath, chrRange) {
    const testBallc = new BAllC(filePath);

    const mc_records = await testBallc.query(chrRange);
    const header = await testBallc.getHeader();
    
    return mc_records;
    // return header;
}

// local test
// const results = await queryBAllC(
//     { path: "/path/to/ballc" },
//     "chr1:0-1000000"
// );

//remote test
const results = await queryBAllC(
    { url: "https://wangftp.wustl.edu/~dli/ballc/ballc/HBA_200622_H1930001_A46_1_P2-1-F3-K1.ballc" },
    "chr1:0-1000000"
);

Main functions

query

    //In Class function, chrRange example: "chr1:0-100000"
    async query(chrRange)

    //Usage, the mc_records is an array of objects [Object, ...], the range format: "chr{chrName}:{start}-{end}"
    const mc_records = await testBallc.query(range);

Here's the doc for the mc_records.

getHeader

    //In Class function
    async getHeader()

    //Usage, the header is an array of objects [Object, ...]
    const header = await testBallc.getHeader();

Here's the doc for the header.

Some utility functions

Here are some functions that you may find them helpful, but they are not in the BAllC class.

VirtualOffset

//This Class initiate the vitual offset of the bgzf file format. 
class VirtualOffset(blockAddress, blockOffset)

For the virtual offset of bgzf file, you can find details here

ChrRange

//This Class initiate the query range. chrRange: "chr{chrName}:{start}-{end}"
class ChrRange(chrRange)

reg_to_bin

//An utility function in bgzf
function reg_to_bin(beg, end)

You can find reg_to_bin function here

queryBGZFIndex and queryBAIIC

//This is the function that reads the bgzf index.
async function queryBGZFIndex(filePath, chrRange, ref_id)
//This is the core function that search the target query range in the index file(.bci)
function queryBAIIC(chrRange, hexString, refID)

queryChunk

//This is the core function that queries the chunks after we convert the virtual offsets to the offsets in the .ballc file.
async function queryChunk(fileHandle, blockAddress ,startOffset, endOffset)