Skip to content

kaptive.core.collections

Protocol contracts for Structure-of-Arrays (SoA) and batched containers.

This module defines formal protocols (BatchedContainer and RaggedArrayContainer) that govern high-performance, vectorized containers across Kaptive.

Classes:

  • BatchedContainer –

    A formal contract for Structure-of-Arrays (SoA) and batched containers in Kaptive.

  • RaggedArrayContainer –

    A formal contract for ragged Structure-of-Arrays (SoA) containers.

BatchedContainer 


              flowchart TD
              kaptive.core.collections.BatchedContainer[BatchedContainer]

              

              click kaptive.core.collections.BatchedContainer href "" "kaptive.core.collections.BatchedContainer"

A formal contract for Structure-of-Arrays (SoA) and batched containers in Kaptive.

This protocol ensures that all high-performance vectorized collections provide a standard interface for instantiation, concatenation, and indexing without relying on slow dynamic mixins or runtime type introspection.

Class Type Parameters:

  • T

    –

    The scalar record type returned when accessing a single index.

  • S

    –

    The batched container type returned when indexing with slices or array masks.

Methods:

  • __getitem__ –

    Access records by index, slice, or boolean/integer array mask.

  • __len__ –

    Return the number of records in the batch.

  • concat –

    Concatenate multiple collections into a single, larger collection.

  • empty –

    Create an empty, 0-length collection with correctly typed arrays.

__getitem__ 

__getitem__(item: int | slice | NDArray[Any] | list[Any]) -> T | S

Access records by index, slice, or boolean/integer array mask.

Parameters:

  • item

    (int | slice | NDArray | list) –

    An integer index, slice, or mask/indices array.

Returns:

  • T | S –

    T | S: A single scalar record (T) if an integer index is provided, or a new batched collection (S) if a slice or mask is provided.

Raises:

  • IndexError –

    If an integer index is out of bounds.

Source code in src/kaptive/core/collections.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def __getitem__(self, item: int | slice | npt.NDArray[Any] | list[Any]) -> T | S:
    r"""Access records by index, slice, or boolean/integer array mask.

    Args:
        item (int | slice | npt.NDArray | list): An integer index, slice, or mask/indices array.

    Returns:
        T | S: A single scalar record (`T`) if an integer index is provided, or a new
            batched collection (`S`) if a slice or mask is provided.

    Raises:
        IndexError: If an integer index is out of bounds.
    """
    ...

__len__ 

__len__() -> int

Return the number of records in the batch.

Returns:

  • int ( int ) –

    The total count of items in the container.

Source code in src/kaptive/core/collections.py 
32
33
34
35
36
37
38
def __len__(self) -> int:
    r"""Return the number of records in the batch.

    Returns:
        int: The total count of items in the container.
    """
    ...

concat classmethod 

concat(batches: Iterable[Self]) -> Self

Concatenate multiple collections into a single, larger collection.

Parameters:

  • batches

    (Iterable[S]) –

    An iterable of collections of the same type.

Returns:

  • S ( Self ) –

    A new, combined collection.

Raises:

  • ValueError –

    If the input iterable is empty or contains incompatible batches.

Source code in src/kaptive/core/collections.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def concat(cls, batches: Iterable[Self]) -> Self:
    r"""Concatenate multiple collections into a single, larger collection.

    Args:
        batches (Iterable[S]): An iterable of collections of the same type.

    Returns:
        S: A new, combined collection.

    Raises:
        ValueError: If the input iterable is empty or contains incompatible batches.
    """
    ...

empty classmethod 

empty() -> Self

Create an empty, 0-length collection with correctly typed arrays.

Returns:

  • S ( Self ) –

    An empty instance of the container.

Source code in src/kaptive/core/collections.py 
55
56
57
58
59
60
61
62
@classmethod
def empty(cls) -> Self:
    r"""Create an empty, 0-length collection with correctly typed arrays.

    Returns:
        S: An empty instance of the container.
    """
    ...

RaggedArrayContainer 


              flowchart TD
              kaptive.core.collections.RaggedArrayContainer[RaggedArrayContainer]
              kaptive.core.collections.BatchedContainer[BatchedContainer]

                              kaptive.core.collections.BatchedContainer --> kaptive.core.collections.RaggedArrayContainer
                


              click kaptive.core.collections.RaggedArrayContainer href "" "kaptive.core.collections.RaggedArrayContainer"
              click kaptive.core.collections.BatchedContainer href "" "kaptive.core.collections.BatchedContainer"

A formal contract for ragged Structure-of-Arrays (SoA) containers.

Ragged containers store variable-length data (such as sequences or CIGAR operations) in a flat, contiguous memory layout, managing sequence boundaries using offsets and lengths arrays.

Attributes:

  • offsets (NDArray[int32]) –

    Starting indices into the flat data array for each record.

  • lengths (NDArray[int32]) –

    Number of elements in the flat array for each record.

Methods:

  • __getitem__ –

    Access records by index, slice, or boolean/integer array mask.

  • __len__ –

    Return the number of records in the batch.

  • concat –

    Concatenate multiple collections into a single, larger collection.

  • empty –

    Create an empty, 0-length collection with correctly typed arrays.

__getitem__ 

__getitem__(item: int | slice | NDArray[Any] | list[Any]) -> T | S

Access records by index, slice, or boolean/integer array mask.

Parameters:

  • item

    (int | slice | NDArray | list) –

    An integer index, slice, or mask/indices array.

Returns:

  • T | S –

    T | S: A single scalar record (T) if an integer index is provided, or a new batched collection (S) if a slice or mask is provided.

Raises:

  • IndexError –

    If an integer index is out of bounds.

Source code in src/kaptive/core/collections.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def __getitem__(self, item: int | slice | npt.NDArray[Any] | list[Any]) -> T | S:
    r"""Access records by index, slice, or boolean/integer array mask.

    Args:
        item (int | slice | npt.NDArray | list): An integer index, slice, or mask/indices array.

    Returns:
        T | S: A single scalar record (`T`) if an integer index is provided, or a new
            batched collection (`S`) if a slice or mask is provided.

    Raises:
        IndexError: If an integer index is out of bounds.
    """
    ...

__len__ 

__len__() -> int

Return the number of records in the batch.

Returns:

  • int ( int ) –

    The total count of items in the container.

Source code in src/kaptive/core/collections.py 
32
33
34
35
36
37
38
def __len__(self) -> int:
    r"""Return the number of records in the batch.

    Returns:
        int: The total count of items in the container.
    """
    ...

concat classmethod 

concat(batches: Iterable[Self]) -> Self

Concatenate multiple collections into a single, larger collection.

Parameters:

  • batches

    (Iterable[S]) –

    An iterable of collections of the same type.

Returns:

  • S ( Self ) –

    A new, combined collection.

Raises:

  • ValueError –

    If the input iterable is empty or contains incompatible batches.

Source code in src/kaptive/core/collections.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def concat(cls, batches: Iterable[Self]) -> Self:
    r"""Concatenate multiple collections into a single, larger collection.

    Args:
        batches (Iterable[S]): An iterable of collections of the same type.

    Returns:
        S: A new, combined collection.

    Raises:
        ValueError: If the input iterable is empty or contains incompatible batches.
    """
    ...

empty classmethod 

empty() -> Self

Create an empty, 0-length collection with correctly typed arrays.

Returns:

  • S ( Self ) –

    An empty instance of the container.

Source code in src/kaptive/core/collections.py 
55
56
57
58
59
60
61
62
@classmethod
def empty(cls) -> Self:
    r"""Create an empty, 0-length collection with correctly typed arrays.

    Returns:
        S: An empty instance of the container.
    """
    ...