VDB-2 - ReferenceIterator

Type:
interface

Header:
align/iterator.h

Revision History:
2012-Feb-07rodarmer

Contents:


Description

The ReferenceIterator is an interface that allows for walking a window of a reference sequence with zero or more associated alignment tables. This is a two-dimensional iterator, where the primary axis (usually thought of as horizontal) is along the reference sequence, while the secondary axis (similarly considered vertical) represents a stack of individual alignments under the reference at the point in question.

The purpose of this iterator is as a high-level means of extracting the vertical alignment information base-by-base. The user moves the horizontal position along a window on the reference and can determine the extent of alignments underneath that position, and detect for each the type of alignment event that occurs.

Since the iteration occurs within the coordinate space of the reference sequence but the events remain in the aligned sequence's coordinate space, the events are restated slightly - semantically mapped to reference space. Matches and mismatches remain as before, but deletions (in the aligned sequence) are expressed as skips in reference space, followed by an out-of-band deletion event that describes the deleted interval. Insertions are similarly described as out-of-band events since by definition they occupy no length of the reference sequence.

Requirements

  1. Must operate within the garbage collection paradigm of the code base
  2. TBD

ReferenceIterator

Make

ask the alignment manager to create an iterator from individual components

ALIGN_EXTERN rc_t CC AlignMgrMakeReferenceIterator ( struct AlignMgr const *self,
    ReferenceIterator **iter, const PlacementRecordExtendFuncs *ext_1, int32_t min_mapq );

iter - OUT
return parameter for the iterator

ext_1
structure containing callback-functions
used to create/destroy the placement-record

min_mapq
mimimal mapping quality an alignment has to have in order to be not filtered out

wonderfulness.

AddRef

duplicate an existing reference

rc_t ReferenceIteratorAddRef ( const ReferenceIterator *self );

The object is defined as being reference counted. In VDB-2, references are direct pointers to objects and the objects maintain a reference counter.

Release

release an existing reference
potentially whacks object

rc_t ReferenceIteratorRelease ( const ReferenceIterator *self );

The object is defined as being reference counted. In VDB-2, references are direct pointers to objects and the objects maintain a reference counter.

NULL pointers are ignored.

AddPlacements

adds a source of placements to the set being examined

ALIGN_EXTERN rc_t CC ReferenceIteratorAddPlacements ( ReferenceIterator *self,
    struct ReferenceObj const *ref_obj, INSDC_coord_zero ref_pos, INSDC_coord_len ref_len,
    struct VCursor const *ref, struct VCursor const *align, align_id_src ids,
    const char * spot_group );

ref_obj
reference the placements align against

ref_pos
start of the requested window on the reference

ref_len
length of the requested window on the reference

ref
cursor to read the REFERENCE-table

align
cursor to read one of the *_ALIGNMENT-tables

ids
selector to define which *_IDS column to read
from the REFERENCE-table

spot-group
string which defines what spot-group the placements
belong to (if any)

NextReference

advance to the next reference

rc_t ReferenceIteratorNextReference ( ReferenceIterator *self,
    INSDC_coord_zero *first_pos, INSDC_coord_len *len, struct ReferenceObj const ** refobj );

first_pos - OUT
start position of the first alignment on the next reference

len - OUT
outer length of the alignments on the next reference

refobj - OUT
next reference

This function has to be called (at least once) to advance to the next reference.

NextWindow

advance to the next window

rc_t ReferenceIteratorNextWindow ( ReferenceIterator *self,
    INSDC_coord_zero *first_pos, INSDC_coord_len *len );

first_pos - OUT
start position of the window

len - OUT
length of the window

This function has to be called (at least once) to advance to the next window on the reference reference.

NextSpotGroup

NextPos

advance the iterator to the next position within reference window
resets vertical iterator
used to advance iterator to the initial valid position

rc_t ReferenceIteratorNextPos ( ReferenceIterator *self, bool skip_empty );

sdf

Position

obtain the current position of the iterator within the reference window

rc_t ReferenceIteratorPosition ( const ReferenceIterator *self,
    INSDC_coord_zero *pos, uint32_t * depth, INSDC_4na_bin * base );

sdf

NextPlacement

retrieve next stacked PlacementRecord under current position

rc_t ReferenceIteratorNextPlacement ( ReferenceIterator *self, const PlacementRecord **rec );

rec - OUT
return parameter for the next stacked placement

sdf

State

retrieve state from current record's AlignmentIterator.

int32_t ReferenceIteratorState ( const ReferenceIterator *self, INSDC_coord_zero *seq_pos );

sdf

BasesInserted

retrieve inserted bases from current record's AlignmentIterator.

uint32_t ReferenceIteratorBasesInserted ( const ReferenceIterator *self, const INSDC_4na_bin **bases );

sdf

BasesDeleted

retrieve position of deleted bases from current record's AlignmentIterator.
may return deleted bases from reference sequence.

uint32_t ReferenceIteratorBasesDeleted ( const ReferenceIterator *self,
    uint64_t *pos, const INSDC_4na_bin **bases );

sdf


NCBI VDB-2 Documentation