@gmod/cram
Advanced tools
Read CRAM files (indexed or unindexed) with pure JS, works in node or in the browser.
$ npm install --save @gmod/cram
# or
$ yarn add @gmod/cram
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
Class of each CRAM record returned by this API.
Returns boolean true if the read is paired, regardless of whether both segments are mapped
Returns boolean true if the read is paired, and both segments are mapped
Returns boolean true if the read itself is unmapped; conflictive with isProperlyPaired
Returns boolean true if the read itself is unmapped; conflictive with isProperlyPaired
Returns boolean true if the read is mapped to the reverse strand
Returns boolean true if the mate is mapped to the reverse strand
Returns boolean true if this is read number 1 in a pair
Returns boolean true if this is read number 2 in a pair
Returns boolean true if this is a secondary alignment
Returns boolean true if this read has failed QC checks
Returns boolean true if the read is an optical or PCR duplicate
Returns boolean true if this is a supplementary alignment
Returns boolean true if the read is detached
Returns boolean true if the read has a mate in this same CRAM segment
Returns boolean true if the read contains qual scores
Returns boolean true if the read has no sequence bases
Get the original sequence of this read.
Returns String sequence basepairs
Get the pair orientation of a paired read. Adapted from igv.js
Returns String of paired orientatin
Annotates this feature with the given reference sequence basepair information.
This will add a sub and a ref item to base subsitution read features given
the actual substituted and reference base pairs, and will make the
getReadSequence() method work.
refRegion
object
compressionScheme CramContainerCompressionScheme
Returns undefined nothing
The feature objects appearing in the readFeatures member of CramRecord objects
that show insertions, deletions, substitutions, etc.
character): One of "bqBXIDiQNSPH". See page 15 of the CRAM v3 spec
for their meanings.any): the data associated with the feature. The format of this
varies depending on the feature code.number): location relative to the read (1-based)number): location relative to the reference (1-based)args
object
args.cram CramFileargs.index Index-like object that supports
getEntriesForRange(seqId,start,end) -> Promise[Array[index entries]]args.cacheSize
number?
optional maximum number of CRAM records to cache. default 20,000args.fetchSizeLimit
number?
optional maximum number of bytes to fetch in a single getRecordsForRange
call. Default 3 MiB.args.checkSequenceMD5
boolean?
default true. if false, disables verifying the MD5 checksum of the reference
sequence underlying a slice. In some applications, this check can cause an
inconvenient amount (many megabases) of sequences to be fetched.seq
number
numeric ID of the reference sequencestart
number
start of the range of interest. 1-based closed coordinates.end
number
end of the range of interest. 1-based closed coordinates.opts (optional, default {})seqId
numberReturns Promise true if the CRAM file contains data for the given reference sequence numerical ID
args
object
args.filehandle
object?
a filehandle that implements the stat() and read() methods of the Node
filehandle API https://nodejs.org/api/fs.html#fs_class_filehandleargs.path
object?
path to the cram fileargs.url
object?
url for the cram file. also supports file:// urls for local filesargs.seqFetch
function?
a function with signature (seqId, startCoordinate, endCoordinate) that
returns a promise for a string of sequence basesargs.cacheSize
number?
optional maximum number of CRAM records to cache. default 20,000args.checkSequenceMD5
boolean?
default true. if false, disables verifying the MD5 checksum of the reference
sequence underlying a slice. In some applications, this check can cause an
inconvenient amount (many megabases) of sequences to be fetched.seqId
numberReturns Promise true if the index contains entries for the given reference sequence ID, false otherwise
fetch index entries for the given range
Returns
Promise
promise for an array of objects of the form
{start, span, containerStart, sliceStart, sliceBytes }
Extends Error
Error caused by encountering a part of the CRAM spec that has not yet been implemented
Extends CramError
An error caused by malformed data.
Extends CramMalformedError
An error caused by attempting to read beyond the end of the defined data.
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.
MIT © Robert Buels
v2.0.2
FAQs
read CRAM files with pure Javascript
The npm package @gmod/cram receives a total of 448 weekly downloads. As such, @gmod/cram popularity was classified as not popular.
We found that @gmod/cram demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.