biofiles 0.0.11__tar.gz → 0.0.13__tar.gz

{biofiles-0.0.11 → biofiles-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: biofiles
-Version: 0.0.11
+Version: 0.0.13
 Summary: Pure-Python, zero-dependency collection of bioinformatics-related file readers and writers
 Author-email: Tigran Saluev <tigran@saluev.com>
 Maintainer-email: Tigran Saluev <tigran@saluev.com>
@@ -36,6 +36,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # biofiles
 

biofiles-0.0.13/biofiles/dialects/havana_ensembl.py

@@ -0,0 +1,101 @@
+"""Feature dialect for HAVANA+Ensembl .gtf files (e.g. T2T annotation)."""
+
+from enum import StrEnum
+
+from biofiles.types.feature_v2 import Feature, id_field, field, relation
+
+
+class GeneType(StrEnum):
+    LNC_RNA = "lncRNA"
+    PROTEIN_CODING = "protein_coding"
+
+
+class TranscriptType(StrEnum):
+    LNC_RNA = "lncRNA"
+    PROTEIN_CODING = "protein_coding"
+
+
+transcript_gene, gene_transcripts = relation(source="gene_id")
+exon_transcript, transcript_exons = relation(source="transcript_id")
+exon_gene, _ = relation(source="gene_id")
+cds_exon, exon_cds = relation(source="exon_id", one_to_one=True)
+utr_transcript, transcript_utrs = relation(source="transcript_id")
+utr_gene, _ = relation(source="gene_id")
+five_prime_utr_transcript, transcript_five_prime_utr = relation(
+    source="transcript_id", one_to_one=True
+)
+five_prime_utr_gene, _ = relation(source="gene_id")
+three_prime_utr_transcript, transcript_three_prime_utr = relation(
+    source="transcript_id", one_to_one=True
+)
+three_prime_utr_gene, _ = relation(source="gene_id")
+start_codon_transcript, transcript_start_codon = relation(
+    source="transcript_id", one_to_one=True
+)
+start_codon_exon, _ = relation(source="exon_id", one_to_one=True)
+stop_codon_transcript, transcript_stop_codon = relation(
+    source="transcript_id", one_to_one=True
+)
+stop_codon_exon, _ = relation(source="exon_id", one_to_one=True)
+
+
+class Gene(Feature, type="gene"):
+    id: str = id_field(source="gene_id")
+    type: GeneType = field(source="gene_type")
+    name: str = field(source="gene_name")
+    transcripts: list["Transcript"] = gene_transcripts
+
+
+class Transcript(Feature, type="transcript"):
+    id: str = id_field(source="transcript_id")
+    type: TranscriptType = field(source="transcript_type")
+    name: str = field(source="transcript_name")
+    gene: Gene = transcript_gene
+    exons: list["Exon"] = transcript_exons
+    five_prime_utr: "FivePrimeUTR | None" = transcript_five_prime_utr
+    three_prime_utr: "ThreePrimeUTR | None" = transcript_three_prime_utr
+    start_codon: "StartCodon | None" = transcript_start_codon
+    stop_codon: "StopCodon | None" = transcript_stop_codon
+
+
+class Exon(Feature, type="exon"):
+    id: str = id_field(source="exon_id")
+    number: int = field(source="exon_number")
+    transcript: Transcript = exon_transcript
+    gene: Gene = exon_gene
+    cds: "CDS | None" = exon_cds
+
+
+class CDS(Feature, type="cds"):
+    id: str = id_field(source="exon_id")
+    exon: Exon = cds_exon
+
+
+class UTR(Feature, type="utr"):
+    id: str = id_field(source="transcript_id")
+    transcript: Transcript = utr_transcript
+    gene: Gene = utr_gene
+
+
+class FivePrimeUTR(UTR, starts=five_prime_utr_transcript):
+    id: str = id_field(source="transcript_id")
+    transcript: Transcript = five_prime_utr_transcript
+    gene: Gene = five_prime_utr_gene
+
+
+class ThreePrimeUTR(UTR, ends=three_prime_utr_transcript):
+    id: str = id_field(source="transcript_id")
+    transcript: Transcript = three_prime_utr_transcript
+    gene: Gene = three_prime_utr_gene
+
+
+class StartCodon(Feature, type="start_codon"):
+    id: str = id_field(source="transcript_id")
+    transcript: Transcript = start_codon_transcript
+    exon: Exon = start_codon_exon
+
+
+class StopCodon(Feature, type="stop_codon"):
+    id: str = id_field(source="transcript_id")
+    transcript: Transcript = stop_codon_transcript
+    exon: Exon = stop_codon_exon

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles/gtf.py

@@ -5,7 +5,7 @@ from typing import Iterator
 
 from biofiles.common import Writer
 from biofiles.gff import GFFReader
-from biofiles.types.feature import Gene, Exon, Feature, UTR
+from biofiles.types.feature import Gene, Exon, Feature, UTR, CDS
 
 
 class GTFReader(GFFReader):
@@ -46,22 +46,27 @@ if __name__ == "__main__":
             total_features = 0
             annotated_genes = 0
             annotated_exons = 0
+            annotated_cds = 0
             annotated_utrs = 0
             parsed_genes = 0
             parsed_exons = 0
+            parsed_cds = 0
             parsed_utrs = 0
             for feature in r:
                 total_features += 1
                 annotated_genes += "gene" in feature.type_.lower()
                 annotated_exons += feature.type_ == "exon"
+                annotated_cds += feature.type_.lower() == "cds"
                 annotated_utrs += "utr" in feature.type_.lower()
                 parsed_genes += isinstance(feature, Gene)
                 parsed_exons += isinstance(feature, Exon)
+                parsed_cds += isinstance(feature, CDS)
                 parsed_utrs += isinstance(feature, UTR)
         print(
             f"{path}: {total_features} features, "
             f"{parsed_genes} genes parsed out of {annotated_genes}, "
             f"{parsed_exons} exons parsed out of {annotated_exons}, "
+            f"{parsed_cds} CDS parsed out of {annotated_cds}, "
             f"{parsed_utrs} UTRs parsed out of {annotated_utrs}",
             file=sys.stderr,
         )

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles/types/alignment.py

@@ -1,7 +1,15 @@
 from dataclasses import dataclass
 
 
-__all__ = ["ReferenceSequence", "Alignment", "BAMTag"]
+__all__ = [
+    "Alignment",
+    "BAMFlag",
+    "BAMTag",
+    "CIGAR",
+    "CIGAROpKind",
+    "CIGAROperation",
+    "ReferenceSequence",
+]
 
 from enum import IntFlag
 

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles/types/feature.py

@@ -50,6 +50,7 @@ class Transcript(Feature):
 class Exon(Feature):
     gene: Gene
     transcript: Transcript
+    cds: "CDS | None"
 
 
 @dataclass(frozen=True)
@@ -61,3 +62,10 @@ class UTR(Feature):
 @dataclass(frozen=True)
 class ThreePrimeUTR(UTR):
     pass
+
+
+@dataclass(frozen=True)
+class CDS(Feature):
+    gene: Gene
+    transcript: Transcript
+    exon: Exon

biofiles-0.0.13/biofiles/types/feature_v2.py

@@ -0,0 +1,105 @@
+from dataclasses import dataclass, Field, field as dataclass_field
+from typing import dataclass_transform
+
+from biofiles.common import Strand
+
+
+@dataclass
+class Relation:
+    id_field_name: str
+    inverse: "InverseRelation | None" = None
+    class_: type | None = None
+
+
+@dataclass
+class InverseRelation:
+    inverse: Relation
+    one_to_one: bool
+    class_: type | None = None
+
+
+@dataclass_transform()
+class FeatureMetaclass(type):
+    __id_field_name__: str
+    __filter_type__: str
+    __filter_starts__: Relation | None
+    __filter_ends__: Relation | None
+
+    def __new__(
+        cls,
+        name,
+        bases,
+        namespace,
+        type: str | None = None,
+        starts: Field | None = None,
+        ends: Field | None = None,
+    ):
+        result = super().__new__(cls, name, bases, namespace)
+        result.__id_field_name__ = ""
+        for key, value in namespace.items():
+            match value:
+                case Field(metadata={"id_field_name": id_field_name}):
+                    if result.__id_field_name__:
+                        raise TypeError(
+                            f"should specify exactly one id_field() in class {result.__name__}"
+                        )
+                    result.__id_field_name__ = id_field_name
+                case Field(metadata={"relation": Relation() as r}):
+                    r.class_ = result
+                    if key in result.__annotations__:
+                        # TODO handle optionality and forward refs
+                        r.inverse.class_ = result.__annotations__[key]
+                case Field(metadata={"relation": InverseRelation() as r}):
+                    r.class_ = result
+                    # TODO calculating r.inverse.class_ based on type annotation
+
+        if type is not None:
+            result.__filter_type__ = type
+        result.__filter_starts__ = None
+        if starts is not None:
+            result.__filter_starts__ = starts.metadata["relation"]
+        result.__filter_ends__ = None
+        if ends is not None:
+            result.__filter_ends__ = ends.metadata["relation"]
+
+        # TODO generate dataclass-like __init__ method,
+        #      keep all relations optional
+
+        return result
+
+
+class Feature(metaclass=FeatureMetaclass):
+    sequence_id: str
+    source: str
+    type_: str
+
+    start_original: int
+    end_original: int
+    # Original values as they were present in the file (1-based inclusive for .gff and .gtf).
+
+    start_c: int
+    end_c: int
+    # Standardized ("C-style") 0-based values, start inclusive, end exclusive.
+
+    score: float | None
+    strand: Strand | None
+    phase: int | None
+    attributes: dict[str, str]
+
+
+def id_field(source: str) -> Field:
+    return dataclass_field(metadata={"id_field_name": source})
+
+
+def field(source: str) -> Field:
+    return dataclass_field(metadata={"field_name": source})
+
+
+def relation(source: str, *, one_to_one: bool = False) -> tuple[Field, Field]:
+    forward = Relation(id_field_name=source)
+    inverse = InverseRelation(inverse=forward, one_to_one=one_to_one)
+    forward.inverse = inverse
+
+    return dataclass_field(metadata={"relation": forward}), dataclass_field(
+        metadata={"relation": inverse}
+    )

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles/utility/feature.py

@@ -11,6 +11,7 @@ from biofiles.types.feature import (
     Exon,
     UTR,
     Transcript,
+    CDS,
 )
 
 
@@ -126,6 +127,8 @@ class FeatureReader(Reader):
                 feature = self._finalize_transcript(draft, result, Transcript)
             case "exon":
                 feature = self._finalize_exon(draft, result)
+            case "cds":
+                feature = self._finalize_cds(draft, result)
             case "three_prime_utr":
                 feature = self._finalize_utr(draft, result, ThreePrimeUTR)
             case "utr":
@@ -161,10 +164,25 @@ class FeatureReader(Reader):
         feature = self._finalize_other(draft, result)
         if not (transcript := self._find_ancestor_of_type(feature, Transcript)):
             return feature
-        exon = Exon(**feature.__dict__, gene=transcript.gene, transcript=transcript)
+        exon = Exon(
+            **feature.__dict__, gene=transcript.gene, transcript=transcript, cds=None
+        )
         object.__setattr__(transcript, "exons", transcript.exons + (exon,))
         return exon
 
+    def _finalize_cds(self, draft: FeatureDraft, result: Features) -> Feature:
+        feature = self._finalize_other(draft, result)
+        if not (exon := self._find_ancestor_of_type(feature, Exon)):
+            return feature
+        cds = CDS(
+            **feature.__dict__,
+            exon=exon,
+            transcript=exon.transcript,
+            gene=exon.transcript.gene,
+        )
+        object.__setattr__(exon, "cds", cds)
+        return cds
+
     def _finalize_utr(
         self, draft: FeatureDraft, result: Features, type_: Type[UTRT]
     ) -> Feature:
@@ -183,7 +201,7 @@ class FeatureReader(Reader):
 
     def _finalize_other(self, draft: FeatureDraft, result: Features) -> Feature:
         parent_id = self._extract_parent_id(draft)
-        parent = result.by_id[parent_id] if parent_id is not None else None
+        parent = result.by_id.get(parent_id) if parent_id is not None else None
 
         return Feature(
             sequence_id=draft.sequence_id,
@@ -211,6 +229,8 @@ class FeatureReader(Reader):
             id_ := draft.attributes.get("transcript_id")
         ):
             return id_
+        if draft.type_ == "exon" and (id_ := draft.attributes.get("exon_id")):
+            return id_
         return None
 
     def _extract_parent_id(self, draft: FeatureDraft) -> str | None:
@@ -222,4 +242,6 @@ class FeatureReader(Reader):
             id_ := draft.attributes.get("transcript_id")
         ):
             return id_
+        if draft.type_.lower() == "cds" and (id_ := draft.attributes.get("exon_id")):
+            return id_
         return None

biofiles-0.0.13/biofiles/utility/feature_v2.py

@@ -0,0 +1,148 @@
+from collections import deque, defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, TextIO
+
+from biofiles.common import Strand, Reader
+from biofiles.types.feature_v2 import Feature, FeatureMetaclass, Relation
+
+
+@dataclass
+class FeatureDraft:
+    idx: int
+    sequence_id: str
+    source: str
+    type_: str
+    start_original: int
+    end_original: int
+    score: float | None
+    strand: Strand | None
+    phase: int | None
+    attributes: dict[str, str]
+
+    class_: type | None = None
+    id: Any = None
+    finalized: Feature | None = None
+
+
+class FeatureTypes:
+    def __init__(self, feature_types: list[FeatureMetaclass]) -> None:
+        for ft in feature_types:
+            if not ft.__id_field_name__:
+                raise ValueError(
+                    f"{ft.__name__} is not proper feature type - has no id_field()"
+                )
+
+        self.ambiguous_type_mapping: dict[str, list[FeatureMetaclass]] = defaultdict(
+            list
+        )
+        self.unique_type_mapping: dict[str, FeatureMetaclass] = {}
+
+        for ft in feature_types:
+            self.ambiguous_type_mapping[ft.__filter_type__].append(ft)
+
+        for key, fts in [*self.ambiguous_type_mapping.items()]:
+            if len(fts) == 1:
+                self.unique_type_mapping[key] = fts[0]
+                del self.ambiguous_type_mapping[key]
+                continue
+            self.ambiguous_type_mapping[key] = _sort_by_filter_specificity(fts)
+
+
+def _sort_by_filter_specificity(fts: list[FeatureMetaclass]) -> list[FeatureMetaclass]:
+    """Sort feature classes by their filter specificity, most specific -> least specific."""
+    key = lambda ft: bool(ft.__filter_starts__) + bool(ft.__filter_ends__)
+    return sorted(fts, key=key, reverse=True)
+
+
+@dataclass
+class FeatureDrafts:
+    feature_types: FeatureTypes
+    drafts: list[FeatureDraft] = field(default_factory=deque)
+    by_class_and_id: dict[tuple[type, Any], FeatureDraft] = field(default_factory=dict)
+
+    def add(self, draft: FeatureDraft) -> None:
+        self.drafts.append(draft)
+        if class_ := self.feature_types.unique_type_mapping.get(draft.type_):
+            draft.class_ = class_
+            draft.id = draft.attributes[class_.__id_field_name__]
+            self.register(draft)
+
+    def register(self, draft: FeatureDraft) -> None:
+        if (key := (draft.class_, draft.id)) in self.by_class_and_id:
+            raise ValueError(
+                f"duplicate feature ID {draft.id} for class {class_.__name__}"
+            )
+        self.by_class_and_id[key] = draft
+
+
+class FeatureReader(Reader):
+
+    def __init__(
+        self, input_: TextIO | Path | str, feature_types: list[FeatureMetaclass]
+    ) -> None:
+        super().__init__(input_)
+        self._feature_types = FeatureTypes(feature_types)
+
+    def __iter__(self) -> Iterator[Feature]:
+        raise NotImplementedError
+
+    def _finalize_drafts(self, fds: FeatureDrafts) -> Iterator[Feature]:
+        self._choose_classes(fds)
+        pass
+
+    def _choose_classes(self, fds: FeatureDrafts) -> Iterator[Feature]:
+        for fd in fds.drafts:
+            if fd.class_:
+                continue
+
+            fts = self._feature_types.ambiguous_type_mapping[fd.type_]
+            matching_fts = [ft for ft in fts if self._check_filters(fd, ft)]
+            if not matching_fts:
+                raise ValueError(
+                    f"no matching classes (out of {len(fts)}) for "
+                    f"feature with type {fd.type_!r}, attributes {fd.attributes!r}"
+                )
+            if len(matching_fts) > 1:
+                raise ValueError(
+                    f"too many matching classes ({len(matching_fts)}) for "
+                    f"feature with type {fd.type_!r}, attributes {fd.attributes!r}"
+                )
+            ft = matching_fts[0]
+            fd.class_ = ft
+            fd.id = fd.attributes[ft.__id_field_name__]
+            fds.register(fd)
+
+    def _check_filters(
+        self, fds: FeatureDrafts, fd: FeatureDraft, ft: FeatureMetaclass
+    ) -> bool:
+        if r := ft.__filter_starts__:
+            related_fd = self._get_related_feature_draft(fds, fd, r)
+            if fd.strand != related_fd.strand:
+                return False
+            if fd.strand == "+" and fd.start_original != related_fd.start_original:
+                return False
+            if fd.strand == "-" and fd.end_original != related_fd.end_original:
+                return False
+        if r := ft.__filter_ends__:
+            related_fd = self._get_related_feature_draft(fds, fd, r)
+            if fd.strand != related_fd.strand:
+                return False
+            if fd.strand == "+" and fd.end_original != related_fd.end_original:
+                return False
+            if fd.strand == "-" and fd.start_original != related_fd.start_original:
+                return False
+        return True
+
+    def _get_related_feature_draft(
+        self, fds: FeatureDrafts, fd: FeatureDraft, r: Relation
+    ) -> FeatureDraft:
+        related_class = r.inverse.class_
+        related_id = fd.attributes[r.id_field_name]
+        try:
+            return fds.by_class_and_id[related_class, related_id]
+        except KeyError as exc:
+            raise ValueError(
+                f"can't find related {related_class.__name__} for "
+                f"{fd.class_.__name__} with attributes {fd.attributes!r}"
+            ) from exc

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: biofiles
-Version: 0.0.11
+Version: 0.0.13
 Summary: Pure-Python, zero-dependency collection of bioinformatics-related file readers and writers
 Author-email: Tigran Saluev <tigran@saluev.com>
 Maintainer-email: Tigran Saluev <tigran@saluev.com>
@@ -36,6 +36,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Dynamic: license-file
 
 # biofiles
 

{biofiles-0.0.11 → biofiles-0.0.13}/biofiles.egg-info/SOURCES.txt

@@ -13,11 +13,15 @@ biofiles.egg-info/PKG-INFO
 biofiles.egg-info/SOURCES.txt
 biofiles.egg-info/dependency_links.txt
 biofiles.egg-info/top_level.txt
+biofiles/dialects/__init__.py
+biofiles/dialects/havana_ensembl.py
 biofiles/types/__init__.py
 biofiles/types/alignment.py
 biofiles/types/feature.py
+biofiles/types/feature_v2.py
 biofiles/types/repeat.py
 biofiles/types/sequence.py
 biofiles/utility/__init__.py
 biofiles/utility/cli.py
-biofiles/utility/feature.py
+biofiles/utility/feature.py
+biofiles/utility/feature_v2.py

{biofiles-0.0.11 → biofiles-0.0.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "biofiles"
-version = "0.0.11"
+version = "0.0.13"
 authors = [
   { name="Tigran Saluev", email="tigran@saluev.com" },
 ]