@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')
// open local files
const indexedFile = new IndexedCramFile({
cramPath: require.resolve(`./data/ce#5.tmp.cram`),
index: new CraiIndex({
path: require.resolve(`./data/ce#5.tmp.cram.crai`),
}),
seqFetch: async (seqId, start, end) => {
// seqFetch should return a promise for a string.
// this one just returns a fake sequence of all A's of the proper length
let fakeSeq = ''
for (let i = start; i <= end; i += 1) {
fakeSeq += 'A'
}
return fakeSeq
},
checkSequenceMD5: false,
})
// example of fetching records from an indexed CRAM file.
// NOTE: only numeric IDs for the reference sequence are accepted
const records = await indexedFile.getRecordsForRange(0, 10000, 20000)
records.forEach(record => {
console.log(`got a record named ${record.readName}`)
record.readFeatures.forEach(({ code, pos, refPos, ref, sub }) => {
if (code === 'X')
console.log(
`${
record.readName
} shows a base substitution of ${ref}->${sub} at ${refPos}`,
)
})
})
// can also pass `cramUrl`, and `url` params to open remote URLs
These are the record objects returned by this API. Much of the data
is stored in them as simple object entries, but there are some accessor
methods used for conveniently getting the values of each of the flags in
the flags and cramFlags fields.
number): the SAM bit-flags field, see the SAM spec for interpretation. Some of the is* methods below interpret this field.number): the CRAM-specific bit-flags field, see the CRAM spec for interpretation. Some of the is* methods below interpret this field.number): the ID number of the record's reference sequencenumber): length of the read in basesnumber): start coordinate of the alignment on the reference in 1-based closed coordinatesnumber): ID number of the read group, or -1 if nonenumber): name of the read (string)number): for paired sequencing, the total size of the templatearray[ReadFeature]): array of read features showing insertions, deletions, mismatches, etc. See ReadFeatures for their format.number): span of the alignment along the reference sequencenumber): SAM mapping qualityarray[number]): array of numeric quality scoresnumber): unique ID number of the record within the fileobject)
number): CRAM mapping flags for the mate. See CRAM spec for interpretation. Some of the is* methods below interpret this field.number): reference sequence ID for the mate mappingnumber): start coordinate of the mate mapping. 1-based coordinates.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
annotates this feature with the given reference region. right now, this only uses the reference sequence to decode which bases are being substituted in base substitution features.
Parameters
refRegion object
compressionScheme CramContainerCompressionSchemeReturns 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)The pairing of an index and a CramFile. Supports efficient fetching of records for sections of reference sequences.
Parameters
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.Parameters
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.Parameters
seqId numberReturns Promise true if the CRAM file contains data for the given reference sequence numerical ID
Parameters
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.Returns number the number of containers in the file
Represents a .crai index.
Parameters
Parameters
seqId numberReturns Promise true if the index contains entries for the given reference sequence ID, false otherwise
fetch index entries for the given range
Parameters
Returns Promise promise for
an array of objects of the form
{start, span, containerStart, sliceStart, sliceBytes }
@gmod/cram/errors contains some special error classes thrown by cram-js. A list of the error classes is below.
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.
Extends CramError
An error caused by data being too big, exceeding a size limit.
Extends CramError
An invalid argument was supplied to a cram-js method or object.
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.
MIT © Robert Buels
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.