Skip to main content
`Ctrl`+`K`

# skbio.alignment.AlignPath

class skbio.alignment.AlignPath(lengths, states, starts)

  Create an alignment path from segment lengths and states.

  The underliying data structure of the `AlignPath` class efficiently represents a sequence alignment as two equal-length vectors: lengths and gap status. The lengths vector contains the lengths of individual segments of the alignment with consistent gap status. The gap status vector contains the encoded bits of the gap (1) and character (0) status for each position in the alignment.

  This data structure is detached from the original sequences and is highly memory efficient. It permits fully vectorized operations and enables efficient conversion between various formats such as CIGAR, tabular, indices (Biotite), and coordinates (Biopython).

  Parameters:
    lengths array_like of int of shape (n_segments,)

      Length of each segment in the alignment.

    states array_like of uint8 of shape (n_segments,) or (n_packs, n_segments)

      Packed bits representing character (0) or gap (1) status per sequence per segment in the alignment.

    starts array_like of int of shape (n_sequences,)

      Start position (0-based) of each sequence in the alignment.

  See also

  `skbio.sequence.Sequence`
  `skbio.alignment.TabularMSA`

  Notes

  The underlying logic of the `AlignPath` data structure is rooted in two concepts: run length encoding and bit arrays.

  The lengths array is calculated by performing run length encoding on the alignment, considering each segment with consistent gap status to be an individual unit in the encoding. In the above example, the first three positions of the alignment contain no gaps, so the first value in the lengths array is 3, and so on.

  The states array is calculated by turning the alignment segments into a bit array where gaps become 1’s, and characters become zeros. Then, the 0’s and 1’s are converted into bytes. In the above example, the fourth segment, which has length 1, would become [0, 1, 1], which then becomes 6.

  Examples

  Create an `AlignPath` object from a `TabularMSA` object with three DNA sequences and 20 positions.

      >>> from skbio import DNA, TabularMSA
      >>> from skbio.alignment import AlignPath
      >>> seqs = [
      ...    DNA('CGGTCGTAACGCGTA---CA'),
      ...    DNA('CAG--GTAAG-CATACCTCA'),
      ...    DNA('CGGTCGTCAC-TGTACACTA')
      ... ]
      >>> msa = TabularMSA(seqs)
      >>> msa
      TabularMSA[DNA]
      ----------------------
      Stats:
          sequence count: 3
          position count: 20
      ----------------------
      CGGTCGTAACGCGTA---CA
      CAG--GTAAG-CATACCTCA
      CGGTCGTCAC-TGTACACTA
      >>> path = AlignPath.from_tabular(msa)
      >>> path
      AlignPath
      Shape(sequence=3, position=20)
      lengths: [3 2 5 1 4 3 2]
      states: [0 2 0 6 0 1 0]

  Attributes

  `lengths` | Array of lengths of segments in alignment path.
  `shape` | Number of sequences (rows) and positions (columns).
  `starts` | Array of start positions of sequences in the alignment.
  `states` | Array of gap status of segments in alignment path.

  Built-ins

  `__eq__`(value, /) | Return self==value.
  `__ge__`(value, /) | Return self>=value.
  `__getstate__`(/) | Helper for pickle.
  `__gt__`(value, /) | Return self>value.
  `__hash__`(/) | Return hash(self).
  `__le__`(value, /) | Return self<=value.
  `__lt__`(value, /) | Return self<value.
  `__ne__`(value, /) | Return self!=value.
  `__str__`() | String representation of this AlignPath.

  Methods

  `from_bits`(bits[, starts]) | Create an alignment path from a bit array (0 - character, 1 - gap).
  `from_coordinates`(coords) | Generate an alignment path from an array of segment coordinates.
  `from_indices`(indices[, gap]) | Create an alignment path from character indices in the original sequences.
  `from_tabular`(msa) | Create an alignment path from a TabularMSA object.
  `to_bits`() | Unpack states into an array of bits.
  `to_coordinates`() | Generate an array of segment coordinates in the original sequences.
  `to_indices`([gap]) | Generate an array of indices of characters in the original sequences.