API Reference

SAM.Header()

Create an empty header.

MetaInfo(tag::AbstractString, value)

Create a SAM metainfo with tag and value.

tag is a two-byte ASCII string. If tag is "CO", value must be a string; otherwise, value is an iterable object with key and value pairs.

Examples

julia> SAM.MetaInfo("CO", "some comment")
BioAlignments.SAM.MetaInfo:
    tag: CO
  value: some comment

julia> string(ans)
"@CO	some comment"

julia> SAM.MetaInfo("SQ", ["SN" => "chr1", "LN" => 12345])
BioAlignments.SAM.MetaInfo:
    tag: SQ
  value: SN=chr1 LN=12345

julia> string(ans)
"@SQ	SN:chr1	LN:12345"

MetaInfo(str::AbstractString)

Create a SAM metainfo from str.

Examples

julia> SAM.MetaInfo("@CO	some comment")
BioAlignments.SAM.MetaInfo:
    tag: CO
  value: some comment

julia> SAM.MetaInfo("@SQ	SN:chr1	LN:12345")
BioAlignments.SAM.MetaInfo:
    tag: SQ
  value: SN=chr1 LN=12345

SAM.Reader(input::IO)

Create a data reader of the SAM file format.

Arguments

• input: data source

SAM.Record(str::AbstractString)

Create a SAM record from str. This function verifies the format and indexes fields for accessors.

SAM.Record(data::Vector{UInt8})

Create a SAM record from data. This function verifies the format and indexes fields for accessors. Note that the ownership of data is transferred to a new record object.

SAM.Record()

Create an unfilled SAM record.

Writer(output::IO, header::Header=Header())

Create a data writer of the SAM file format.

Arguments

• output: data sink
• header=Header(): SAM header object

findall(header::Header, key::AbstractString)::Vector{MetaInfo}

Find metainfo objects satisfying SAM.tag(metainfo) == key.

read!(rdr::Reader, rec::Record)

Read a Record into rec; overwriting or adding to existing field values. It is assumed that rec is already initialized or empty.

header(reader::Reader)::Header

Get the header of reader.

alignlength(record::Record)::Int

Get the alignment length of record.

alignment(record::Record)::BioAlignments.Alignment

Get the alignment of record.

auxdata(record::Record)::Dict{String,Any}

Get the auxiliary data (optional fields) of record.

cigar(record::Record)::String

Get the CIGAR string of record.

iscomment(metainfo::MetaInfo)::Bool

Test if metainfo is a comment (i.e. its tag is "CO").

keyvalues(metainfo::MetaInfo)::Vector{Pair{String,String}}

Get the values of metainfo as string pairs.

mappingquality(record::Record)::UInt8

Get the mapping quality of record.

nextposition(record::Record)::Int

Get the position of the mate/next read of record.

nextrefname(record::Record)::String

Get the reference name of the mate/next read of record.

position(record::Record)::Int

Get the 1-based leftmost mapping position of record.

quality(::Type{String}, record::Record)::String

Get the ASCII-encoded base quality of record.

quality(record::Record)::Vector{UInt8}

Get the Phred-scaled base quality of record.

refname(record::Record)::String

Get the reference sequence name of record.

rightposition(record::Record)::Int

Get the 1-based rightmost mapping position of record.

seqlength(record::Record)::Int

Get the sequence length of record.

sequence(::Type{String}, record::Record)::String

Get the segment sequence of record as String.

sequence(record::Record)::BioSequences.LongDNA{4}

Get the segment sequence of record.

tag(metainfo::MetaInfo)::String

Get the tag of metainfo.

templength(record::Record)::Int

Get the template length of record.

tempname(record::Record)::String

Get the query template name of record.

value(metainfo::MetaInfo)::String

Get the value of metainfo as a string.

BAI(filename::AbstractString)

Load a BAI index from filename.

BAI(input::IO)

Load a BAI index from input.

BAM.Reader(input::IO; index=nothing)

Create a data reader of the BAM file format.

Arguments

• input: data source
• index=nothing: filepath to a random access index (currently bai is supported) or BAI object

BAM.Record()

Create an unfilled BAM record.

BAM.Writer(output::BGZFStream, header::SAM.Header)

Create a data writer of the BAM file format.

Arguments

• output: data sink
• header: SAM header object

header(reader::Reader; fillSQ::Bool=false)::SAM.Header

Get the header of reader.

If fillSQ is true, this function fills missing "SQ" metainfo in the header.

alignlength(record::Record)::Int

Get the alignment length of record.

alignment(record::Record)::BioAlignments.Alignment

Get the alignment of record.

auxdata(record::Record)::BAM.AuxData

Get the auxiliary data of record.

cigar(record::Record)::String

Get the CIGAR string of record.

Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.

Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.

If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.

See also BAM.cigar_rle.

cigar_rle(record::Record, checkCG::Bool = true)::Tuple{Vector{BioAlignments.Operation},Vector{Int}}

Get a run-length encoded tuple (ops, lens) of the CIGAR string in record.

Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.

Calling this method with checkCG set to true (default) this method will always yield the true cigar string, because this is probably what you want the vast majority of the time.

If you have a record that stores the true cigar in a CG:B,I tag, but you still want to access the pseudo-cigar that is stored in the cigar field of the BAM record, then you can set checkCG to false.

See also BAM.cigar.

mappingquality(record::Record)::UInt8

Get the mapping quality of record.

n_cigar_op(record::Record, checkCG::Bool = true)

Return the number of operations in the CIGAR string of record.

Note that in the BAM specification, the field called cigar typically stores the cigar string of the record. However, this is not always true, sometimes the true cigar is very long, and due to some constraints of the BAM format, the actual cigar string is stored in an extra tag: CG:B,I, and the cigar field stores a pseudo-cigar string.

Calling this method with checkCG set to true (default) this method will always yield the number of operations in the true cigar string, because this is probably what you want, the vast majority of the time.

If you have a record that stores the true cigar in a CG:B,I tag, but you still want to get the number of operations in the cigar field of the BAM record, then set checkCG to false.

nextposition(record::Record)::Int

Get the 1-based leftmost mapping position of the next/mate read of record.

nextrefid(record::Record)::Int

Get the next/mate reference sequence ID of record.

nextrefname(record::Record)::String

Get the reference name of the mate/next read of record.

position(record::Record)::Int

Get the 1-based leftmost mapping position of record.

quality(record::Record)

Get the base quality of record.

refid(record::Record)::Int

Get the reference sequence ID of record.

The ID is 1-based (i.e. the first sequence is 1) and is 0 for a record without a mapping position.

See also: BAM.rname

reflen(record::Record)::Int

Get the length of the reference sequence this record applies to.

refname(record::Record)::String

Get the reference sequence name of record.

See also: BAM.refid

rightposition(record::Record)::Int

Get the 1-based rightmost mapping position of record.

seqlength(record::Record)::Int

Get the sequence length of record.

sequence(record::Record)::BioSequences.LongDNA{4}

Get the segment sequence of record.

templength(record::Record)::Int

Get the template length of record.

tempname(record::Record)::String

Get the query template name of record.