# bam

Dark Mode

Search:
Group by:

# Imports

hts_concat, hts_concat, utils, hts_concat, simpleoption

# Types

    FormatOption {...}{.size: 4.} = enum
      CRAM_OPT_DECODE_MD, CRAM_OPT_PREFIX, CRAM_OPT_VERBOSITY, CRAM_OPT_SEQS_PER_SLICE,
      CRAM_OPT_SLICES_PER_CONTAINER, CRAM_OPT_RANGE, CRAM_OPT_VERSION,
      CRAM_OPT_EMBED_REF, CRAM_OPT_IGNORE_MD5, CRAM_OPT_REFERENCE,
      CRAM_OPT_MULTI_SEQ_PER_SLICE, CRAM_OPT_NO_REF, CRAM_OPT_USE_BZIP2,
      CRAM_OPT_SHARED_REF, CRAM_OPT_NTHREADS, CRAM_OPT_THREAD_POOL, CRAM_OPT_USE_LZMA,
      CRAM_OPT_USE_RANS, CRAM_OPT_REQUIRED_FIELDS, CRAM_OPT_LOSSY_NAMES,
      CRAM_OPT_BASES_PER_SLICE, HTS_OPT_COMPRESSION_LEVEL = 100, HTS_OPT_NTHREADS,
      HTS_OPT_THREAD_POOL, HTS_OPT_CACHE_SIZE, HTS_OPT_BLOCK_SIZE

  CRAM specific

    SamField {...}{.size: 4.} = enum
      SAM_QNAME = 1, SAM_FLAG = 2, SAM_RNAME = 4, SAM_POS = 8, SAM_MAPQ = 16, SAM_CIGAR = 32,
      SAM_RNEXT = 64, SAM_PNEXT = 128, SAM_TLEN = 256, SAM_SEQ = 512, SAM_QUAL = 1024,
      SAM_AUX = 2048, SAM_RGAUX = 4096

    Flag = distinct uint16

    CPtr[T] = ptr CArray[T]

    Cigar = object
      cig: CPtr[uint32]
      n: uint32

  `Cigar` represents ths SAM Cigar type. It consists of one or more `CigarElement` s.

    CigarElement = distinct uint32

  `CigarElement` encodes the operation (length and type) of each element of a `Cigar`.

    Consume = distinct uint32

    CigarOp {...}{.pure.} = enum
      match = 0, insert, deletion, ref_skip, soft_clip, hard_clip, pad, equal, diff, back

    Range = tuple[start: int, stop: int]

    Header = ref object of RootObj
      hdr*: ptr bam_hdr_t

  Header wraps the bam header info.

    Record = ref object of RootObj
      b*: ptr bam1_t
      hdr: Header

  Record is a single alignment object.

    Bam = ref object of RootObj
      hts*: ptr htsFile
      hdr*: Header
      rec: Record
      idx*: ptr hts_idx_t
      path: cstring                ## path the the alignment file.

  Bam wraps a BAM/CRAM/SAM reader object from htslib.

    Target = object
      name*: string
      length*: uint32
      tid*: int

  Target is a chromosome or contig from the bam header.

    IndexStats = tuple[mapped: uint64, unmapped: uint64]

    BamError = ref object of ValueError

# Vars

    errno: cint

# Procs

    proc `and`(f: Flag; o: uint16): uint16 {...}{.borrow, inline.}

    proc `and`(f: Flag; o: Flag): uint16 {...}{.borrow, inline.}

    proc `or`(f: Flag; o: uint16): uint16 {...}{.borrow.}

    proc `or`(o: uint16; f: Flag): uint16 {...}{.borrow.}

    proc `==`(f: Flag; o: Flag): bool {...}{.borrow, inline.}

    proc `==`(f: Flag; o: uint16): bool {...}{.borrow, inline.}

    proc `==`(o: uint16; f: Flag): bool {...}{.borrow, inline.}

    proc has_flag(f: Flag; o: uint16): bool {...}{.inline, raises: [], tags: [].}

    proc pair(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc proper_pair(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc unmapped(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc mate_unmapped(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc reverse(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc mate_reverse(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc read1(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc read2(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc secondary(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc qcfail(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc dup(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc supplementary(f: Flag): bool {...}{.inline, raises: [], tags: [].}

    proc `$`(f: Flag): string {...}{.raises: [], tags: [].}

    proc `$`(o: CigarOp): char {...}{.inline, raises: [], tags: [].}

    proc len(c: Cigar): int {...}{.inline, raises: [], tags: [].}

  returns the number of operations in the cigar.

    proc `[]`(c: Cigar; i: int): CigarElement {...}{.inline, raises: [], tags: [].}

    proc op(o: CigarElement): CigarOp {...}{.inline, raises: [], tags: [].}

  `op` gives the operation of the cigar.

    proc len(o: CigarElement): int {...}{.inline, raises: [], tags: [].}

  `len` gives the length of the cigar op.

    proc `$`(o: CigarElement): string {...}{.raises: [], tags: [].}

  shows the string representation of the cigar element.

    proc `$`(c: Cigar): string {...}{.raises: [], tags: [].}

    proc ref_coverage(c: Cigar; ipos: int = 0): seq[Range] {...}{.deprecated, raises: [], tags: [].}

  Deprecated

    proc `$`(h: Header): string {...}{.raises: [], tags: [].}

    proc stats(idx: ptr hts_idx_t; tid: int): IndexStats {...}{.raises: [], tags: [].}

  get the stats from the index.

    proc copy(h: Header): Header {...}{.raises: [], tags: [].}

  make a copy of the bam Header and underlying pointer.

    proc xam_index(fn: string; fnidx: string = ""; min_shift: int = 14; nthreads: int = 1) {...}{.
        raises: [ValueError, OSError], tags: [].}

  index the file

    proc from_string(h: Header; header_string: string) {...}{.raises: [ValueError], tags: [].}

  create a new header from a string

    proc from_string(r: Record; record_string: string) {...}{.raises: [ValueError], tags: [].}

  update the record with the given SAM record. note that this does not make a copy of `record_string` and will modify the string in-place.

    proc sequence(r: Record; s: var string): string {...}{.discardable, raises: [], tags: [].}

  fill the given string with the read sequence

    proc base_at(r: Record; i: int): char {...}{.inline, raises: [], tags: [].}

  return just the base at the requsted index 'i' into the query sequence.

    proc base_qualities(r: Record; q: var seq[uint8]): seq[uint8] {...}{.raises: [], tags: [].}

  fill the given seq with the base-qualities.

    proc base_quality_at(r: Record; i: int): uint8 {...}{.inline, raises: [], tags: [].}

    proc targets(h: Header): seq[Target] {...}{.raises: [], tags: [].}

  The targets (chromosomes) from the header.

    proc `$`(t: Target): string {...}{.raises: [ValueError], tags: [].}

    proc chrom(r: Record): string {...}{.inline, raises: [], tags: [].}

  `chrom` returns the chromosome or '' if not mapped.

    proc mate_chrom(r: Record): string {...}{.inline, raises: [], tags: [].}

  `mate_chrom` returns the chromosome of the mate or '' if not mapped.

    proc mate_tid(r: Record): int {...}{.inline, raises: [], tags: [].}

  `mate_tid` returns the tid of the mate or -1 if not mapped.

    proc tid(r: Record): int {...}{.inline, raises: [], tags: [].}

  `tid` returns the tid of the alignment or -1 if not mapped.

    proc start(r: Record): int64 {...}{.inline, raises: [], tags: [].}

  `start` returns 0-based start position.

    proc stop(r: Record): int {...}{.inline, raises: [], tags: [].}

  `stop` returns end position of the read.

    proc qname(r: Record): string {...}{.inline, raises: [], tags: [].}

  `qname` returns the query name.

    proc set_qname(r: Record; qname: string) {...}{.raises: [], tags: [].}

  set a new qname for the record

    proc flag(r: Record): Flag {...}{.inline, raises: [], tags: [].}

  `flag` returns a `Flag` object.

    proc cigar(r: Record): Cigar {...}{.inline, raises: [], tags: [].}

  `cigar` returns a `Cigar` object.

    proc `$`(r: Record): string {...}{.raises: [ValueError], tags: [].}

    proc mapping_quality(r: Record): uint8 {...}{.inline, raises: [], tags: [].}

  mapping quality

    proc isize(r: Record): int64 {...}{.inline, raises: [], tags: [].}

  insert size

    proc mate_pos(r: Record): int64 {...}{.inline, raises: [], tags: [].}

  mate position

    proc tostring(r: Record): string {...}{.raises: [ValueError], tags: [].}

    proc copy(r: Record): Record {...}{.noInit, raises: [], tags: [].}

  `copy` makes a copy of the record.

    proc write_header(bam: var Bam; header: Header) {...}{.raises: [ValueError], tags: [].}

  write the bam the the bam stream. useful when a bam is opened in write mode. this also sets the header.

    proc write(bam: var Bam; rec: Record) {...}{.inline, raises: [ValueError], tags: [].}

  write the record to the bam which must be writeable.

    proc close(bam: Bam) {...}{.raises: [], tags: [].}

    proc NewRecord(h: Header): Record {...}{.raises: [], tags: [].}

  create a new bam record and associate it with the header

    proc open(bam: var Bam; path: cstring; threads: int = 0; mode: string = "r";
             fai: cstring = nil; index: bool = false): bool {...}{.discardable,
        raises: [IOError, ValueError], tags: [WriteIOEffect].}

  `open_hts` returns a bam object for the given path. If CRAM, then fai must be given. if index is true, then it will attempt to open an index file for regional queries. for writing, mode can be, e.g. 'wb7' to indicate bam format with compression level 7 or 'wc' for cram format with default compression level.

    proc load_index(b: Bam; path: string) {...}{.raises: [IOError, ValueError], tags: [].}

  load the bam/cram index at the given path. This can be remote or local.

    proc hts_set_opt(fp: ptr htsFile; opt: FormatOption): cint {...}{.varargs, cdecl,
        importc: "hts_set_opt", dynlib: libname.}

    proc set_fields(b: Bam; fields: varargs[SamField]): int {...}{.raises: [IOError],
        tags: [WriteIOEffect].}

    proc set_option(b: Bam; f: FormatOption; val: int): int {...}{.raises: [IOError],
        tags: [WriteIOEffect].}

    proc delete_tag(r: Record; itag: string): bool {...}{.inline, raises: [], tags: [].}

  remove the tag from the record return a bool indicating success.

    proc set_tag[T: int | float | string | char](r: Record; itag: string; value: T)

  set the aux tag to `value`.

    proc tag[T: int | float | float32 | float64 | string | char | cstring](r: Record; itag: string): Option[
        T]

  Get the aux tag from the record. Due to `nim` language limitations, this must be used as, e.g.: `tag[int](rec, "NM")`. This returns an Option type that is either `Some` result or `none` if the tag does not exist or if it is not of the requested type.

# Iterators

    iterator items(c: Cigar): CigarElement {...}{.raises: [], tags: [].}

  iterates over the ops in the cigar.

    iterator query(bam: Bam; chrom: string; start: int = 0; stop: int = 0): Record {...}{.
        raises: [ValueError, IOError], tags: [WriteIOEffect].}

  query iterates over the given region. A single element is used and overwritten on each iteration so use `Record.copy` to retain.

    iterator query(bam: Bam; tid: int; start: int = 0; stop: int = (-1)): Record {...}{.
        raises: [IOError, ValueError], tags: [WriteIOEffect].}

  query iterates over the given region. A single element is used and overwritten on each iteration so use `Record.copy` to retain.

    iterator items(bam: Bam): Record {...}{.raises: [ValueError], tags: [].}

  items iterates over a bam. A single element is used and overwritten on each iteration so use `Record.copy` to retain.

# Templates

    template bam_get_cigar(b: untyped): untyped

    template consumes(o: CigarElement): Consume

    template query(c: Consume): bool

  returns true if the op consumes bases in the query.

    template reference(c: Consume): bool

  returns true if the op consumes bases in the reference.

    template bam_get_qual(b: untyped): untyped

# Exports

$, Option, get, none, get, ==, isSome, isNone, some, simpleoption