@gmod/cram

Read CRAM files (indexed or unindexed) with pure JS, works in node or in the browser.

• Reads CRAM 3.x and 2.x (3.1 added in v1.6.0)
• Does not read CRAM 1.x
• Can use .crai indexes out of the box, for efficient sequence fetching, but also has an index API that would allow use with other index types
• Does implement bzip2 but not lzma codecs (yet); if this is important to your use case, please file an issue

Install

$ npm install --save @gmod/cram
# or
$ yarn add @gmod/cram

Usage

const { IndexedCramFile, CramFile, CraiIndex } = require('@gmod/cram')

// Use indexedfasta library for seqFetch, if using local file (see below)
const { IndexedFasta, BgzipIndexedFasta } = require('@gmod/indexedfasta')

// this uses local file paths for node.js for IndexedFasta, for usages using
// remote URLs see indexedfasta docs for filehandles and
// https://github.com/gmod/generic-filehandle
const t = new IndexedFasta({
  path: '/filesystem/yourfile.fa',
  faiPath: '/filesystem/yourfile.fa.fai',
})

// example of fetching records from an indexed CRAM file.
// NOTE: only numeric IDs for the reference sequence are accepted.
// For indexedfasta the numeric ID is the order in which the sequence names
// appear in the header

// Wrap in an async and then run
run = async () => {
  const idToName = []
  const nameToId = {}

  // example opening local files on node.js
  // can also pass `cramUrl` (for the IndexedCramFile class), and `url` (for
  // the CraiIndex) params to open remote URLs
  //
  // alternatively `cramFilehandle` (for the IndexedCramFile class) and
  // `filehandle` (for the CraiIndex) can be used,  see for examples
  // https://github.com/gmod/generic-filehandle

  const indexedFile = new IndexedCramFile({
    cramPath: '/filesystem/yourfile.cram',
    //or
    //cramUrl: 'url/to/file.cram'
    //cramFilehandle: a generic-filehandle or similar filehandle
    index: new CraiIndex({
      path: '/filesystem/yourfile.cram.crai',
      // or
      // url: 'url/to/file.cram.crai'
      // filehandle: a generic-filehandle or similar filehandle
    }),
    seqFetch: async (seqId, start, end) => {
      // note:
      // * seqFetch should return a promise for a string, in this instance retrieved from IndexedFasta
      // * we use start-1 because cram-js uses 1-based but IndexedFasta uses 0-based coordinates
      // * the seqId is a numeric identifier, so we convert it back to a name with idToName
      // * you can return an empty string from this function for testing if you want, but you may not get proper interpretation of record.readFeatures
      return t.getSequence(idToName[seqId], start - 1, end)
    },
    checkSequenceMD5: false,
  })
  const samHeader = await indexedFile.cram.getSamHeader()

  // use the @SQ lines in the header to figure out the
  // mapping between ref ref ID numbers and names

  const sqLines = samHeader.filter(l => l.tag === 'SQ')
  sqLines.forEach((sqLine, refId) => {
    sqLine.data.forEach(item => {
      if (item.tag === 'SN') {
        // this is the ref name
        const refName = item.value
        nameToId[refName] = refId
        idToName[refId] = refName
      }
    })
  })

  const records = await indexedFile.getRecordsForRange(
    nameToId['chr1'],
    10000,
    20000,
  )
  records.forEach(record => {
    console.log(`got a record named ${record.readName}`)
    if (record.readFeatures != undefined) {
      record.readFeatures.forEach(({ code, pos, refPos, ref, sub }) => {
        // process the read features. this can be used similar to
        // CIGAR/MD strings in SAM. see CRAM specs for more details.
        if (code === 'X') {
          console.log(
            `${record.readName} shows a base substitution of ${ref}->${sub} at ${refPos}`,
          )
        }
      })
    }
  })
}

run()

// can also pass `cramUrl` (for the IndexedCramFile class), and `url` (for the CraiIndex) params to open remote URLs
// alternatively `cramFilehandle` (for the IndexedCramFile class) and `filehandle` (for the CraiIndex) can be used,  see for examples https://github.com/gmod/generic-filehandle

You can use cram-js without NPM also with the cram-bundle.js. See the example directory for usage with script tag

API (auto-generated)

• CramRecord - format of CRAM records returned by this API
  • ReadFeatures - format of read features on records
• IndexedCramFile - indexed access into a CRAM file
• CramFile - .cram API
• CraiIndex - .crai index API
• Error Classes - special error classes thrown by this API

CramRecord

Table of Contents

ReadFeatures

The feature objects appearing in the readFeatures member of CramRecord objects that show insertions, deletions, substitutions, etc.

Static fields

• code (character): One of "bqBXIDiQNSPH". See page 15 of the CRAM v3 spec for their meanings.
• data (any): the data associated with the feature. The format of this varies depending on the feature code.
• pos (number): location relative to the read (1-based)
• refPos (number): location relative to the reference (1-based)

IndexedCramFile

Table of Contents

CramFile

Table of Contents

CraiIndex

Table of Contents

CramUnimplementedError

Extends Error

Error caused by encountering a part of the CRAM spec that has not yet been implemented

CramMalformedError

Extends CramError

An error caused by malformed data.

CramBufferOverrunError

Extends CramMalformedError

An error caused by attempting to read beyond the end of the defined data.

Academic Use

This package was written with funding from the NHGRI as part of the JBrowse project. If you use it in an academic project that you publish, please cite the most recent JBrowse paper, which will be linked from jbrowse.org.

License

MIT © Robert Buels