structures module

class DataExtensionBase(wrap_obj: wrap_T)

Bases: ABC, Generic[wrap_T]

Wrapper adding metadata handling to the object and forwarding other methods to the wrapped object.

pysam objects which we expect to operate on are C extensions. This means no monkey patching. One could store associated metadata in a separate object, but the ergonomics of doing so clash with the intention of this library. Hence, this approach - a wrapper that uses method forwarding to the wrapped object and adds non-clashing methods of its own to store per-object level data. Note that the wrapper is intentionally non-transparent, i.e. it will not pass an isinstance check against the type of the wrapped object.

Note: the instance methods are all private as the opinion of the package is that one should define free functions specific to any extended subclass one creates, encouraging greater flexibility with regard to the properties of the wrapped object

property unwrapped

record_operation(ext_obj: DataExtensionBase[Any], op: str)

mark_ext_obj(ext_obj: DataExtensionBase[Any], mark: str) → None

ext_obj_has_mark(ext_obj: DataExtensionBase[Any], mark: str)

final class ExtendedRead(wrap_obj: wrap_T)

Bases: DataExtensionBase[AlignedSegment], object

make_extended_read(read: AlignedSegment | ExtendedRead) → ExtendedRead

Free func and functional style to minimise pain points:

• ease of converting from AlignedSegment to ExtendedRead, no-op if already extended

mark_read(read: ExtendedRead, mark: str) → None

Free func and functional style so as to minimise pain points:

• since ExtendedRead uses method forwarding, a type checker is unhelpful when using .method() style

• can add behaviour on receiving unwrapped AlignedSegment rather than extended read

read_has_mark(read: ExtendedRead, mark: str) → bool

final class ExtendedVariant(wrap_obj: wrap_T)

Bases: DataExtensionBase[VariantRecord], object

class ReadView(data: Mapping[Any, Sequence[Read_T]])

Bases: Mapping[Any, tuple[Read_T, …]]

keys() → a set-like object providing a view on D's keys

values() → an object providing a view on D's values

items() → a set-like object providing a view on D's items

property all

static validate_read_map(read_map: Mapping[str, Sequence[AlignedSegment]])

static convert_pysam_to_extread(read_map: Mapping[Any, Sequence[AlignedSegment]], validate: bool)

class TestOutcomes(*values)

Bases: StrEnum

VARIANT_PASS = 'PASS'

VARIANT_FAIL = 'FAIL'

NA = 'NA'

class FlagResult(variant_flagged: TestOutcomes, info_flag: Flag | None, reads_seen: int)

Bases: ABC

Parent ABC/pydantic BaseModel defining the implementation that must be followed by result subclasses - subclasses to hold results of running the test() method of a specific subclass of FilterTester on a variant (e.g. for FooFilter.test(), the return value should include an instance of FooResult).

All filters should use subclasses that inherit from this class to hold their results, as enforced by the FilterTester ABC. Defines and guarantees basic properties that must be shared by all filter results:

• a ‘getinfo’ method for returning a string to report to the INFO field of the VCF record - a basic default is provided, but subclasses probably want to override this.

• A basic set of instance variables, which may be extended in a subclass as necessary:

  • name, a string id for the filter to be used in the VCF FILTER field.

  • a flag, a boolean indicating if the filter is True/False, or None if untested.

  • a code, an integer code from a set of possibilities, indicating the basis on which the test has returned True/False, or None if untested.

Note: FlagResult is the part of the abstractflaggers model about which I am most sceptical since it uses init_subclass over a decorator, making it different and because it requires the user to override an abstract method.

FlagName: ClassVar[str]

InfoFlags: ClassVar[type[Flag] | None]

InfoFlagsAllSet: ClassVar[Flag | None]

variant_flagged: TestOutcomes

info_flag: Flag | None

reads_seen: int

abstractmethod getinfo(alt: str) → str

Return basic filter info in a string formatted for use in the VCF INFO field - “<flag>|<code>”.

Each filter must return INFO as it should be formatted for the VCF INFO field, or None if not applicable. Subclasses must override this method to return more specific info.

class ResultPackProtocol(*args, **kwargs)

Bases: Protocol, Generic

Info: type[T]

outcome: TestOutcomes

reason: T

class VariantTestProtocol(*args, **kwargs)

Bases: Protocol, Generic

ResultPack: type[T]

classmethod test_variant_reads(*args: Any, **kwargs: Any) → T