Skip to content
GMODPublic

About

Read CRAM v3 and v2 in node or in the browser

Topics

Resources

Contributing

Stars

18 stars

Watchers

10 watching

Forks

Latest commit

 

History

985 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@gmod/cram

NPM version Build Status

Read CRAM files in node or the browser.

  • Handles CRAM 2.x and 3.x, .crai indexes, and every v3 and v3.1 codec, including fqzcomp and tok3.
  • The codecs are the htscodecs C library that samtools uses, compiled to WebAssembly and inlined in the bundle, so there is no .wasm file to serve.
  • Golomb and Golomb-Rice, which only v2 files use, are not implemented.
npm install @gmod/cram

Quick start

import { IndexedCramFile, CraiIndex } from '@gmod/cram'
import { IndexedFasta } from '@gmod/indexedfasta'
import { RemoteFile } from 'generic-filehandle2'

const fasta = new IndexedFasta({
  fasta: new RemoteFile('https://example.com/reference.fa'),
  fai: new RemoteFile('https://example.com/reference.fa.fai'),
})

const indexedFile = new IndexedCramFile({
  cramUrl: 'https://example.com/file.cram',
  index: new CraiIndex({ url: 'https://example.com/file.cram.crai' }),
  fetchReferenceSequence: (seqId, start, end, refName, opts) =>
    fasta.getSequence(refName, start, end, opts),
})

const records = await indexedFile.getRecordsForRange('chr1', 10000, 20000)

for (const record of records) {
  for (const { code, refPos, bases } of record.getMismatches()) {
    console.log(record.readName, String.fromCharCode(code), refPos, bases)
  }
}

For local files, pass cramPath, CraiIndex({ path }) and IndexedFasta({ path }).

  • Coordinates are 0-based half-open, as in @gmod/bam; add 1 for a 1-based format such as SAM's POS.
  • Query a reference by its name in the file's header, such as chr1, 1 or CHROMOSOME_I. A name the file lacks returns [].

Mismatches

record.getMismatches() lists substitutions, insertions, deletions, reference skips and clips, and forEachMismatch passes them to a callback instead. code is a CIGAR char code (88 for X).

import { RF_SUBST } from '@gmod/cram'

record.forEachMismatch(
  (code, refPos, length, bases, qual, refBaseCode, clipLength) => {
    if (code === RF_SUBST) {
      console.log(refPos, bases)
    }
  },
  { start: 10000, end: 20000 }, // optional window
)

Substitutions need the quick start's fetchReferenceSequence, and read N without it. See Mismatch for the fields and window, and Reference sequence for the callback.

Records

record.getReadBases() // 'ACGT…', the read sequence
record.getCigarString() // '50M2I48M'
record.getTag('NM') // one auxiliary tag
record.qualityScoreAt(0) // one base quality
record.isReverseComplemented() // the usual SAM flags

docs/api.md lists every property and method.

Header, reference names and cancellation

await indexedFile.cram.getReferenceInfo() // [{ name, length, md5 }, ...]
await indexedFile.cram.getSamHeader() // parsed SAM header
await indexedFile.hasDataForReferenceSequence('chrY') // false if the file has no chrY

const controller = new AbortController()
await indexedFile.getRecordsForRange('chr1', 0, 1_000_000, {
  signal: controller.signal,
})

Performance

@gmod/range-cache-filehandle merges the many small HTTP requests a query makes into fewer, and reuses bytes across queries:

import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'

const indexedFile = new IndexedCramFile({
  cramFilehandle: new RemoteFileWithRangeCache(url),
  index: new CraiIndex({
    filehandle: new RemoteFileWithRangeCache(`${url}.crai`),
  }),
})

In a browser, slices decode on a worker pool by default. Pass useSliceWorkerPool: false to turn it off, or numSliceWorkers to set its size (workers.md).

Script tag

A standalone browser build puts the same exports on window.gmodCRAM, loading its codec worker from the same directory and decoding in-process without it. The example directory has a working page.

<script src="https://unpkg.com/@gmod/cram/dist/cram-bundle.js"></script>

Docs

  • docs/api.md: every option, property and method, including walking a record's raw read features
  • MIGRATION.md: breaking changes, newest first
  • docs/dataflow.md: a query from index to records, with links to the design docs and ADRs

Academic use

Written with NHGRI funding as part of JBrowse. If you use this in a publication, please cite the most recent JBrowse paper at jbrowse.org.

License

MIT

About

Read CRAM v3 and v2 in node or in the browser

Topics

Resources

Contributing

Stars

18 stars

Watchers

10 watching

Forks

Releases

Packages

Used by

Contributors

Languages