biofiles 0.0.14__tar.gz → 0.1.1__tar.gz

{biofiles-0.0.14 → biofiles-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: biofiles
-Version: 0.0.14
+Version: 0.1.1
 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>
@@ -30,7 +30,6 @@ Project-URL: Homepage, https://github.com/Saluev/biofiles
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
@@ -84,14 +83,20 @@ Reading GFF genome annotations:
 
 ```python
 from biofiles.gff import GFFReader
-from biofiles.types.feature import Gene
+from biofiles.dialects.gencode import GENCODE_DIALECT
+from biofiles.dialects.genomic_base import Gene
 
-with GFFReader("GCF_009914755.1_T2T-CHM13v2.0_genomic.gff") as r:
+with GFFReader("GCF_009914755.1_T2T-CHM13v2.0_genomic.gff", dialect=GENCODE_DIALECT) as r:
     for feature in r:
         if isinstance(feature, Gene):
             print(feature.name, len(feature.exons))
 ```
 
+Currently three dialects are supported:
+* `biofiles.dialects.gencode.GENCODE_DIALECT` for GENCODE genome annotation;
+* `biofiles.dialects.refseq.REFSEQ_DIALECT` for RefSeq genome annotation;
+* `biofiles.dialects.stringtie.STRINGTIE_DIALECT` for StringTie output files.
+
 ## License 
 
 MIT license, see [License](LICENSE).

{biofiles-0.0.14 → biofiles-0.1.1}/README.md

@@ -44,14 +44,20 @@ Reading GFF genome annotations:
 
 ```python
 from biofiles.gff import GFFReader
-from biofiles.types.feature import Gene
+from biofiles.dialects.gencode import GENCODE_DIALECT
+from biofiles.dialects.genomic_base import Gene
 
-with GFFReader("GCF_009914755.1_T2T-CHM13v2.0_genomic.gff") as r:
+with GFFReader("GCF_009914755.1_T2T-CHM13v2.0_genomic.gff", dialect=GENCODE_DIALECT) as r:
     for feature in r:
         if isinstance(feature, Gene):
             print(feature.name, len(feature.exons))
 ```
 
+Currently three dialects are supported:
+* `biofiles.dialects.gencode.GENCODE_DIALECT` for GENCODE genome annotation;
+* `biofiles.dialects.refseq.REFSEQ_DIALECT` for RefSeq genome annotation;
+* `biofiles.dialects.stringtie.STRINGTIE_DIALECT` for StringTie output files.
+
 ## License 
 
 MIT license, see [License](LICENSE).

biofiles-0.1.1/biofiles/dialects/detector.py

@@ -0,0 +1,74 @@
+import sys
+from itertools import islice
+from pathlib import Path
+
+from biofiles.dialects.gencode import GENCODE_DIALECT
+from biofiles.dialects.refseq import REFSEQ_DIALECT
+from biofiles.dialects.stringtie import STRINGTIE_DIALECT
+from biofiles.types.feature import Dialect
+from biofiles.utility.feature import RawFeatureReader
+
+
+class CantDetectDialect(Exception):
+    pass
+
+
+class DialectDetector:
+    def __init__(self, raw_reader: RawFeatureReader, num_samples: int = 1000) -> None:
+        self._raw_reader = raw_reader
+        self._num_samples = num_samples
+
+    def detect(self) -> Dialect:
+        gencode_rows = 0
+        refseq_rows = 0
+        stringtie_rows = 0
+        total_rows = 0
+        for fd in islice(self._raw_reader, self._num_samples):
+            total_rows += 1
+            source = fd.source.lower()
+            if source in ("havana", "ensembl"):
+                gencode_rows += 1
+            elif source in ("bestrefseq", "bestrefseq%2cgnomon", "gnomon", "refseq"):
+                refseq_rows += 1
+            elif source in ("stringtie",):
+                stringtie_rows += 1
+
+        if gencode_rows > 0 and gencode_rows >= 0.9 * total_rows:
+            return GENCODE_DIALECT
+        if refseq_rows > 0 and refseq_rows >= 0.9 * total_rows:
+            return REFSEQ_DIALECT
+        if stringtie_rows > 0 and stringtie_rows >= 0.9 * total_rows:
+            return STRINGTIE_DIALECT
+
+        raise CantDetectDialect(
+            f"of {total_rows} read rows {gencode_rows} look like GENCODE, "
+            f"{refseq_rows} look like RefSeq, {stringtie_rows} look like StringTie"
+        )
+
+
+def detect_dialect(path: Path) -> Dialect:
+    if path.suffix == ".gtf":
+        from biofiles.gtf import RawGTFReader
+
+        raw_reader = RawGTFReader(path)
+    elif path.suffix in (".gff", ".gff3"):
+        from biofiles.gff import RawGFFReader
+
+        raw_reader = RawGFFReader(path)
+    else:
+        raise CantDetectDialect(f"unknown file extension {path.suffix}")
+    detector = DialectDetector(raw_reader=raw_reader)
+    return detector.detect()
+
+
+if __name__ == "__main__":
+    exit_code = 0
+    for path_str in sys.argv[1:]:
+        path = Path(path_str)
+        try:
+            dialect = detect_dialect(path)
+            print(f"{path}\t{dialect.name}")
+        except CantDetectDialect as exc:
+            print(f"Failed to detect dialect for {path}: {exc}", file=sys.stderr)
+            exit_code = 1
+    sys.exit(exit_code)

biofiles-0.1.1/biofiles/dialects/gencode.py

@@ -0,0 +1,235 @@
+"""Feature dialect for GENCODE .gtf/.gff3 files."""
+
+from enum import StrEnum
+from types import NoneType
+
+from biofiles.dialects.genomic_base import (
+    Gene as BaseGene,
+    Transcript as BaseTranscript,
+    Exon as BaseExon,
+    CDS as BaseCDS,
+    UTR as BaseUTR,
+)
+from biofiles.types.feature import (
+    Feature,
+    id_field,
+    field,
+    relation,
+    no_id_field,
+    Dialect,
+)
+
+
+class GeneType(StrEnum):
+    ARTIFACT = "artifact"
+    IG_C_GENE = "IG_C_gene"
+    IG_C_PSEUDOGENE = "IG_C_pseudogene"
+    IG_D_GENE = "IG_D_gene"
+    IG_D_PSEUDOGENE = "IG_D_pseudogene"
+    IG_J_GENE = "IG_J_gene"
+    IG_J_PSEUDOGENE = "IG_J_pseudogene"
+    IG_PSEUDOGENE = "IG_pseudogene"
+    IG_V_GENE = "IG_V_gene"
+    IG_V_PSEUDOGENE = "IG_V_pseudogene"
+    LNCRNA = "lncRNA"
+    MIRNA = "miRNA"
+    MISC_RNA = "misc_RNA"
+    MT_RRNA = "Mt_rRNA"
+    MT_TRNA = "Mt_tRNA"
+    PROCESSED_PSEUDOGENE = "processed_pseudogene"
+    PROTEIN_CODING = "protein_coding"
+    RIBOZYME = "ribozyme"
+    RRNA = "rRNA"
+    RRNA_PSEUDOGENE = "rRNA_pseudogene"
+    SRNA = "sRNA"
+    SCRNA = "scRNA"
+    SCARNA = "scaRNA"
+    SNRNA = "snRNA"
+    SNORNA = "snoRNA"
+    TEC = "TEC"
+    TR_C_GENE = "TR_C_gene"
+    TR_C_PSEUDOGENE = "TR_C_pseudogene"
+    TR_D_GENE = "TR_D_gene"
+    TR_D_PSEUDOGENE = "TR_D_pseudogene"
+    TR_J_GENE = "TR_J_gene"
+    TR_J_PSEUDOGENE = "TR_J_pseudogene"
+    TR_V_GENE = "TR_V_gene"
+    TR_V_PSEUDOGENE = "TR_V_pseudogene"
+    TRANSCRIBED_PROCESSED_PSEUDOGENE = "transcribed_processed_pseudogene"
+    TRANSCRIBED_UNITARY_PSEUDOGENE = "transcribed_unitary_pseudogene"
+    TRANSCRIBED_UNPROCESSED_PSEUDOGENE = "transcribed_unprocessed_pseudogene"
+    TRANSLATED_PROCESSED_PSEUDOGENE = "translated_processed_pseudogene"
+    UNITARY_PSEUDOGENE = "unitary_pseudogene"
+    UNPROCESSED_PSEUDOGENE = "unprocessed_pseudogene"
+    VAULT_RNA = "vault_RNA"
+
+
+class TranscriptType(StrEnum):
+    ARTIFACT = "artifact"
+    IG_C_GENE = "IG_C_gene"
+    IG_C_PSEUDOGENE = "IG_C_pseudogene"
+    IG_D_GENE = "IG_D_gene"
+    IG_D_PSEUDOGENE = "IG_D_pseudogene"
+    IG_J_GENE = "IG_J_gene"
+    IG_J_PSEUDOGENE = "IG_J_pseudogene"
+    IG_PSEUDOGENE = "IG_pseudogene"
+    IG_V_GENE = "IG_V_gene"
+    IG_V_PSEUDOGENE = "IG_V_pseudogene"
+    LNCRNA = "lncRNA"
+    MIRNA = "miRNA"
+    MISC_RNA = "misc_RNA"
+    MT_RRNA = "Mt_rRNA"
+    MT_TRNA = "Mt_tRNA"
+    PROCESSED_PSEUDOGENE = "processed_pseudogene"
+    PROTEIN_CODING = "protein_coding"
+    RIBOZYME = "ribozyme"
+    RRNA = "rRNA"
+    RRNA_PSEUDOGENE = "rRNA_pseudogene"
+    SRNA = "sRNA"
+    SCRNA = "scRNA"
+    SCARNA = "scaRNA"
+    SNRNA = "snRNA"
+    SNORNA = "snoRNA"
+    TEC = "TEC"
+    TR_C_GENE = "TR_C_gene"
+    TR_C_PSEUDOGENE = "TR_C_pseudogene"
+    TR_D_GENE = "TR_D_gene"
+    TR_D_PSEUDOGENE = "TR_D_pseudogene"
+    TR_J_GENE = "TR_J_gene"
+    TR_J_PSEUDOGENE = "TR_J_pseudogene"
+    TR_V_GENE = "TR_V_gene"
+    TR_V_PSEUDOGENE = "TR_V_pseudogene"
+    TRANSCRIBED_PROCESSED_PSEUDOGENE = "transcribed_processed_pseudogene"
+    TRANSCRIBED_UNITARY_PSEUDOGENE = "transcribed_unitary_pseudogene"
+    TRANSCRIBED_UNPROCESSED_PSEUDOGENE = "transcribed_unprocessed_pseudogene"
+    TRANSLATED_PROCESSED_PSEUDOGENE = "translated_processed_pseudogene"
+    UNITARY_PSEUDOGENE = "unitary_pseudogene"
+    UNPROCESSED_PSEUDOGENE = "unprocessed_pseudogene"
+    VAULT_RNA = "vault_RNA"
+
+    # Transcript-specific:
+    NON_STOP_DECAY = "non_stop_decay"
+    NONSENSE_MEDIATED_DECAY = "nonsense_mediated_decay"
+    PROCESSED_TRANSCRIPT = "processed_transcript"
+    PROTEIN_CODING_CDS_NOT_DEFINED = "protein_coding_CDS_not_defined"
+    PROTEIN_CODING_LOF = "protein_coding_LoF"
+    RETAINED_INTRON = "retained_intron"
+
+
+transcript_gene, gene_transcripts = relation(source="gene_id")
+selenocysteine_gene, _ = relation(source="gene_id")
+selenocysteine_transcript, _ = relation(source="transcript_id")
+exon_transcript, transcript_exons = relation(source="transcript_id")
+exon_gene, _ = relation(source="gene_id")
+cds_exon, exon_cds = relation(source=("transcript_id", "exon_number"), 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=("transcript_id", "exon_number"), one_to_one=True)
+stop_codon_transcript, transcript_stop_codon = relation(
+    source="transcript_id", one_to_one=True
+)
+stop_codon_exon, _ = relation(source=("transcript_id", "exon_number"), one_to_one=True)
+
+
+class Gene(BaseGene, 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
+    tags: list[str] = field(source="tag", default_factory=list)
+
+
+class Transcript(BaseTranscript, 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
+    utrs: list["UTR"] = transcript_utrs
+    start_codon: "StartCodon | None" = transcript_start_codon
+    stop_codon: "StopCodon | None" = transcript_stop_codon
+    tags: list[str] = field(source="tag", default_factory=list)
+
+
+class Selenocysteine(
+    Feature, type=("selenocysteine", "stop_codon_redefined_as_selenocysteine")
+):
+    id: str = no_id_field()
+    gene: Gene = selenocysteine_gene
+    transcript: Transcript = selenocysteine_transcript
+
+
+class Exon(BaseExon, type="exon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    number: int = field(source="exon_number")
+    transcript: Transcript = exon_transcript
+    gene: Gene = exon_gene
+    cds: "CDS | None" = exon_cds
+    tags: list[str] = field(source="tag", default_factory=list)
+
+    @property
+    def cdss(self) -> list["CDS"]:
+        # In RefSeq, exon can have multiple CDS.
+        # This property is for compatibility with a more general case.
+        return [self.cds] if self.cds is not None else []
+
+
+class CDS(BaseCDS, type="cds"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    exon: Exon = cds_exon
+
+
+class UTR(BaseUTR, type="utr"):
+    id: NoneType = no_id_field()
+    transcript: Transcript = utr_transcript
+    gene: Gene = utr_gene
+
+
+class FivePrimeUTR(UTR, type="five_prime_utr"):
+    id: NoneType = no_id_field()
+    transcript: Transcript = five_prime_utr_transcript
+    gene: Gene = five_prime_utr_gene
+
+
+class ThreePrimeUTR(UTR, type="three_prime_utr"):
+    id: NoneType = no_id_field()
+    transcript: Transcript = three_prime_utr_transcript
+    gene: Gene = three_prime_utr_gene
+
+
+class StartCodon(Feature, type="start_codon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    transcript: Transcript = start_codon_transcript
+    exon: Exon = start_codon_exon
+
+
+class StopCodon(Feature, type="stop_codon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    transcript: Transcript = stop_codon_transcript
+    exon: Exon = stop_codon_exon
+
+
+GENCODE_FEATURE_TYPES = [
+    Gene,
+    Transcript,
+    Selenocysteine,
+    Exon,
+    CDS,
+    UTR,
+    FivePrimeUTR,
+    ThreePrimeUTR,
+    StartCodon,
+    StopCodon,
+]
+GENCODE_DIALECT = Dialect(name="GENCODE", feature_types=GENCODE_FEATURE_TYPES)

biofiles-0.1.1/biofiles/dialects/genomic_base.py

@@ -0,0 +1,25 @@
+from biofiles.types.feature import Feature
+
+
+class Gene(Feature):
+    type: str
+    transcripts: list["Transcript"]
+
+
+class Transcript(Feature):
+    type: str
+    gene: Gene
+    exons: list["Exon"]
+
+
+class Exon(Feature):
+    transcript: Transcript
+    cdss: list["CDS"]
+
+
+class CDS(Feature):
+    exon: Exon
+
+
+class UTR(Feature):
+    transcript: Transcript

biofiles-0.1.1/biofiles/dialects/refseq.py

@@ -0,0 +1,142 @@
+"""Feature dialect for RefSeq .gtf/.gff3 files."""
+
+from enum import StrEnum
+
+from biofiles.dialects.genomic_base import (
+    Gene as BaseGene,
+    Transcript as BaseTranscript,
+    Exon as BaseExon,
+    CDS as BaseCDS,
+)
+from biofiles.types.feature import (
+    Feature,
+    id_field,
+    field,
+    relation,
+    no_id_field,
+    Dialect,
+)
+
+
+class GeneType(StrEnum):
+    ANTISENSE_RNA = "antisense_RNA"
+    C_REGION = "C_region"
+    C_REGION_PSEUDOGENE = "C_region_pseudogene"
+    D_SEGMENT = "D_segment"
+    D_SEGMENT_PSEUDOGENE = "D_segment_pseudogene"
+    J_SEGMENT = "J_segment"
+    J_SEGMENT_PSEUDOGENE = "J_segment_pseudogene"
+    LNCRNA = "lncRNA"
+    MIRNA = "miRNA"
+    MISC_RNA = "misc_RNA"
+    NCRNA = "ncRNA"
+    NCRNA_PSEUDOGENE = "ncRNA_pseudogene"
+    OTHER = "other"
+    PROTEIN_CODING = "protein_coding"
+    PSEUDOGENE = "pseudogene"
+    RNASE_MRP_RNA = "RNase_MRP_RNA"
+    RNASE_P_RNA = "RNase_P_RNA"
+    RRNA = "rRNA"
+    SCARNA = "scaRNA"
+    SCRNA = "scRNA"
+    SNORNA = "snoRNA"
+    SNRNA = "snRNA"
+    TELOMERASE_RNA = "telomerase_RNA"
+    TRANSCRIBED_PSEUDOGENE = "transcribed_pseudogene"
+    TRNA = "tRNA"
+    VAULT_RNA = "vault_RNA"
+    V_SEGMENT = "V_segment"
+    V_SEGMENT_PSEUDOGENE = "V_segment_pseudogene"
+    Y_RNA = "Y_RNA"
+
+
+class TranscriptType(StrEnum):
+    ANTISENSE_RNA = "antisense_RNA"
+    C_GENE_SEGMENT = "C_gene_segment"
+    D_GENE_SEGMENT = "D_gene_segment"
+    J_GENE_SEGMENT = "J_gene_segment"
+    LNC_RNA = "lnc_RNA"
+    MIRNA = "miRNA"
+    MRNA = "mRNA"
+    PRIMARY_TRANSCRIPT = "primary_transcript"
+    RNASE_MRP_RNA = "RNase_MRP_RNA"
+    RNASE_P_RNA = "RNase_P_RNA"
+    RRNA = "rRNA"
+    SCARNA = "scaRNA"
+    SCRNA = "scRNA"
+    SNORNA = "snoRNA"
+    SNRNA = "snRNA"
+    TELOMERASE_RNA = "telomerase_RNA"
+    TRANSCRIPT = "transcript"
+    TRNA = "tRNA"
+    VAULT_RNA = "vault_RNA"
+    V_GENE_SEGMENT = "V_gene_segment"
+    Y_RNA = "Y_RNA"
+
+
+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=("transcript_id", "exon_number"))
+start_codon_transcript, transcript_start_codon = relation(
+    source="transcript_id", one_to_one=True
+)
+start_codon_exon, _ = relation(source=("transcript_id", "exon_number"), one_to_one=True)
+stop_codon_transcript, transcript_stop_codon = relation(
+    source="transcript_id", one_to_one=True
+)
+stop_codon_exon, _ = relation(source=("transcript_id", "exon_number"), one_to_one=True)
+
+
+class Gene(BaseGene, type="gene"):
+    id: str = id_field(source="gene_id")
+    type: GeneType = field(source="gene_biotype")
+    name: str = field(source="gene")
+    synonyms: list[str] = field(source="gene_synonym", default_factory=list)
+    transcripts: list["Transcript"] = gene_transcripts
+
+
+class Transcript(BaseTranscript, type="transcript"):
+    id: str = id_field(source="transcript_id")
+    type: TranscriptType = field(source="transcript_biotype")
+    product: str | None = field(source="product", default=None)
+    gene: Gene = transcript_gene
+    exons: list["Exon"] = transcript_exons
+    start_codon: "StartCodon | None" = transcript_start_codon
+    stop_codon: "StopCodon | None" = transcript_stop_codon
+
+
+class Exon(BaseExon, type="exon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    number: int = field(source="exon_number")
+    transcript: Transcript = exon_transcript
+    gene: Gene = exon_gene
+    cdss: list["CDS"] = exon_cds
+
+
+class CDS(BaseCDS, type="cds"):
+    id: tuple[str, int] = no_id_field()
+    exon: Exon = cds_exon
+
+
+class StartCodon(Feature, type="start_codon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    transcript: Transcript = start_codon_transcript
+    exon: Exon = start_codon_exon
+
+
+class StopCodon(Feature, type="stop_codon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    transcript: Transcript = stop_codon_transcript
+    exon: Exon = stop_codon_exon
+
+
+REFSEQ_FEATURE_TYPES = [
+    Gene,
+    Transcript,
+    Exon,
+    CDS,
+    StartCodon,
+    StopCodon,
+]
+REFSEQ_DIALECT = Dialect(name="RefSeq", feature_types=REFSEQ_FEATURE_TYPES)

biofiles-0.1.1/biofiles/dialects/stringtie.py

@@ -0,0 +1,24 @@
+"""Feature dialect for StringTie .gtf/.gff output."""
+
+from biofiles.types.feature import Feature, relation, id_field, field, Dialect
+
+exon_transcript, transcript_exons = relation(source="transcript_id")
+
+
+class Transcript(Feature, type="transcript"):
+    id: str = id_field(source="transcript_id")
+    gene_id: str = field(source="gene_id")
+    exons: list["Exon"] = transcript_exons
+    coverage: float = field(source="cov")
+    fpkm: float = field(source="FPKM")
+    tpm: float = field(source="TPM")
+
+
+class Exon(Feature, type="exon"):
+    id: tuple[str, int] = id_field(source=("transcript_id", "exon_number"))
+    transcript: Transcript = exon_transcript
+    coverage: float = field(source="cov")
+
+
+STRINGTIE_FEATURE_TYPES = [Transcript, Exon]
+STRINGTIE_DIALECT = Dialect(name="StringTie", feature_types=STRINGTIE_FEATURE_TYPES)