diff --git a/docs/api/alignment.rst b/docs/api/alignment.rst new file mode 100644 index 0000000..0390266 --- /dev/null +++ b/docs/api/alignment.rst @@ -0,0 +1,47 @@ +Alignment +========= + +The alignment component receives one query domain and an ordered sequence of +matching ortholog-domain strings. Its ``calc_identities`` method returns one +identity ratio per input occurrence, in the same order. Duplicate sequences +must not be collapsed: the pipeline retains the corresponding ortholog and +domain records by their candidate positions. + +``BiopythonGlobalAlignment`` is the default V2 implementation. Its default +affine-gap scoring preserves the existing global alignment configuration: +match 2, mismatch -1, gap open -2, and gap extension -0.5. That configuration +uses Gotoh's affine-gap global algorithm; it is not linear-gap +Needleman-Wunsch. To explicitly select Biopython's Needleman-Wunsch +implementation, set ``gap_model="linear"`` and give equal open and extension +scores, for example both -2. This option does not change the default. + +Identity is exact, case-sensitive residue matches divided by all alignment +columns. Mismatches and gap columns remain in the denominator. The supplied +implementation uses pairwise alignments; the collection-based interface allows +a future multiple-sequence implementation without changing the pipeline +contract. + +Pass a custom implementation as ``alignment_component`` when constructing +``Lverage``. It must inherit from ``AlignmentTemplate`` and return ordered +ratios in the range zero to one: + +.. code-block:: python + + from lverage.alignment import BiopythonGlobalAlignment + from lverage.pipeline import Lverage + + pipeline = Lverage( + motif_database_list, + orf_searcher, + domain_scanner, + ortholog_searcher, + alignment_component=BiopythonGlobalAlignment(), + ) + +.. autoclass:: lverage.alignment.AlignmentTemplate + :members: + :show-inheritance: + +.. autoclass:: lverage.alignment.BiopythonGlobalAlignment + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst index 6c48958..07cfae8 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -9,6 +9,7 @@ classes from the modules shown below. :maxdepth: 1 domain_scanner + alignment blast jaspar motif_database diff --git a/docs/api/pipeline.rst b/docs/api/pipeline.rst index 90b7632..3dedcc8 100644 --- a/docs/api/pipeline.rst +++ b/docs/api/pipeline.rst @@ -2,8 +2,10 @@ Pipeline ======== ``Lverage`` uses direct constructor injection for ORF searching, domain -scanning, ortholog searching, and motif databases. Constructors validate only -local configuration and do not contact remote services. +scanning, ortholog searching, motif databases, and domain alignment. +Constructors validate only local configuration and do not contact remote +services. See :doc:`alignment` for the identity contract, scoring options, +and how to inject a different alignment implementation. Each run deduplicates ORFs, selects the first longest ORF with an accepted domain, compares matching base PFAM accessions, and searches motif databases @@ -11,6 +13,12 @@ for domain pairs meeting the identity threshold. Intermediate evidence remains local to the run; the instance retains its copied configuration and the latest :class:`lverage.pipeline.LverageCode`. +For each query-domain occurrence, the pipeline gathers matching ortholog +domains in ortholog/domain order and calls the alignment component once. It +keeps score-to-domain associations by position, including duplicate domain +sequences, and emits accepted results in the existing ortholog/query-domain/ +ortholog-domain order. + Valid biological no-hit outcomes return an empty list and set a deterministic code. Adapter and service failures remain exceptions. diff --git a/src/lverage/alignment.py b/src/lverage/alignment.py new file mode 100644 index 0000000..c3bc821 --- /dev/null +++ b/src/lverage/alignment.py @@ -0,0 +1,157 @@ +"""Interfaces and Biopython implementations for domain alignment.""" + +from abc import ABC, abstractmethod +from collections.abc import Sequence +import math +from numbers import Real + +from Bio.Align import PairwiseAligner + + +class AlignmentTemplate(ABC): + """Abstract interface for calculating query-to-ortholog domain identities.""" + + @abstractmethod + def calc_identities(self, query_dbd: str, ortholog_dbds: Sequence[str]) -> list[float]: + """Calculate one identity ratio for each ortholog domain, in input order. + + Parameters + ---------- + query_dbd : str + Nonempty query protein-domain sequence. + ortholog_dbds : sequence of str + Ordered, nonempty ortholog protein-domain sequences. Duplicate + sequences represent distinct occurrences and must be retained. + + Returns + ------- + list of float + One ratio in the range zero to one for each input occurrence, in + the same order. + """ + + raise NotImplementedError + + +class BiopythonGlobalAlignment(AlignmentTemplate): + """Calculate exact identity from Biopython global pairwise alignments. + + The default ``gap_model="affine"`` retains the V2 scores: match 2, + mismatch -1, gap open -2, and gap extension -0.5. This selects Gotoh's + affine-gap global algorithm. Set ``gap_model="linear"`` and use equal + ``open_gap_score`` and ``extend_gap_score`` values (for example, both -2) + to select Biopython's Needleman-Wunsch linear-gap algorithm. The latter is + explicit and does not alter the default scoring behavior. + + Identity is the number of exact, case-sensitive residue matches divided + by the number of alignment columns; mismatches and columns containing a + gap remain in the denominator. + + Parameters + ---------- + gap_model : {"affine", "linear"}, optional + Gap scoring model. Defaults to the existing affine-gap model. + match_score : real number, optional + Score for an exact residue match. Defaults to 2. + mismatch_score : real number, optional + Score for a residue mismatch. Defaults to -1. + open_gap_score : real number, optional + Gap-open score; defaults to -2. + extend_gap_score : real number, optional + Gap-extension score; defaults to -0.5. For linear scoring, this must + equal ``open_gap_score``. + + Raises + ------ + TypeError + If the gap model or a score has an unsupported type. + ValueError + If a score is non-finite or linear gap scores are unequal. + """ + + def __init__(self, + gap_model: str = "affine", + match_score: float = 2, + mismatch_score: float = -1, + open_gap_score: float = -2, + extend_gap_score: float = -0.5): + if gap_model not in ("affine", "linear"): + raise ValueError("gap_model must be 'affine' or 'linear'") + + scores = { + "match_score": match_score, + "mismatch_score": mismatch_score, + "open_gap_score": open_gap_score, + "extend_gap_score": extend_gap_score, + } + for name, score in scores.items(): + if isinstance(score, bool) or not isinstance(score, Real): + raise TypeError(f"{name} must be a real number") + if not math.isfinite(score): + raise ValueError(f"{name} must be finite") + if gap_model == "linear" and open_gap_score != extend_gap_score: + raise ValueError("linear gap scoring requires equal open and extend scores") + + self.gap_model = gap_model + self.match_score = match_score + self.mismatch_score = mismatch_score + self.open_gap_score = open_gap_score + self.extend_gap_score = extend_gap_score + + def calc_identities(self, query_dbd: str, ortholog_dbds: Sequence[str]) -> list[float]: + """Return exact identity ratios for the ordered ortholog domains. + + Parameters + ---------- + query_dbd : str + Nonempty query protein-domain sequence. + ortholog_dbds : sequence of str + Ordered, nonempty ortholog domain sequences. + + Returns + ------- + list of float + One exact-identity ratio per input sequence, preserving duplicates. + + Raises + ------ + TypeError + If inputs are not strings and an ordered sequence of strings. + ValueError + If any input sequence is empty. + """ + + if not isinstance(query_dbd, str): + raise TypeError("query_dbd must be a string") + if not query_dbd: + raise ValueError("query_dbd must be nonempty") + if isinstance(ortholog_dbds, (str, bytes)) or not isinstance(ortholog_dbds, Sequence): + raise TypeError("ortholog_dbds must be an ordered sequence of strings") + if any(not isinstance(sequence, str) for sequence in ortholog_dbds): + raise TypeError("ortholog_dbds must contain only strings") + if any(not sequence for sequence in ortholog_dbds): + raise ValueError("ortholog_dbds must contain only nonempty strings") + + aligner = self._make_aligner() + identities = [] + for ortholog_dbd in ortholog_dbds: + alignment = aligner.align(query_dbd, ortholog_dbd)[0] + exact_matches = sum( + query_index != -1 + and ortholog_index != -1 + and query_dbd[query_index] == ortholog_dbd[ortholog_index] + for query_index, ortholog_index in zip(alignment.indices[0], alignment.indices[1]) + ) + identities.append(exact_matches / alignment.length) + return identities + + def _make_aligner(self) -> PairwiseAligner: + """Build the configured Biopython aligner used for each comparison.""" + + aligner = PairwiseAligner() + aligner.mode = "global" + aligner.match_score = self.match_score + aligner.mismatch_score = self.mismatch_score + aligner.open_gap_score = self.open_gap_score + aligner.extend_gap_score = self.extend_gap_score + return aligner \ No newline at end of file diff --git a/src/lverage/pipeline.py b/src/lverage/pipeline.py index a868912..9786d74 100644 --- a/src/lverage/pipeline.py +++ b/src/lverage/pipeline.py @@ -2,9 +2,10 @@ from enum import Enum import logging +import math +from numbers import Real -from Bio.Align import PairwiseAligner - +from .alignment import AlignmentTemplate, BiopythonGlobalAlignment from .domain_scanner import DomainRecord from .domain_scanner import DomainScannerTemplate from .motif_database import MotifDBTemplate, MotifSearchRequest @@ -65,6 +66,8 @@ class Lverage: Accepted PFAM accessions; an empty list accepts every detected domain dbd_identity_thresh : float, optional Minimum domain identity ratio from zero to one + alignment_component : AlignmentTemplate, optional + Component that calculates ordered query-to-ortholog domain identities """ lverage_code_info = { @@ -83,7 +86,8 @@ def __init__(self, domain_scanner, ortholog_searcher, valid_pfam_list=None, - dbd_identity_thresh=0.7): + dbd_identity_thresh=0.7, + alignment_component=None): if valid_pfam_list is None: valid_pfam_list = [] @@ -91,6 +95,11 @@ def __init__(self, self.orf_searcher = orf_searcher self.domain_scanner = domain_scanner self.ortholog_searcher = ortholog_searcher + self.alignment_component = ( + BiopythonGlobalAlignment() + if alignment_component is None + else alignment_component + ) self.valid_pfam_list = valid_pfam_list.copy() if isinstance(valid_pfam_list, list) else valid_pfam_list self.dbd_identity_thresh = dbd_identity_thresh self.lverage_code = LverageCode.NOT_SET @@ -113,6 +122,8 @@ def validate_arguments(self) -> None: raise TypeError("domain_scanner must be a DomainScannerTemplate instance") if not isinstance(self.ortholog_searcher, OrthologSearcherTemplate): raise TypeError("ortholog_searcher must be an OrthologSearcherTemplate instance") + if not isinstance(self.alignment_component, AlignmentTemplate): + raise TypeError("alignment_component must be an AlignmentTemplate instance") if not isinstance(self.valid_pfam_list, list): raise TypeError("valid_pfam_list must be a list") @@ -184,21 +195,7 @@ def _calculate_domain_identity(query_sequence : str, query_slice = Lverage._get_domain_slice(query_sequence, query_domain) ortholog_slice = Lverage._get_domain_slice(ortholog_sequence, ortholog_domain) - - aligner = PairwiseAligner() - aligner.mode = "global" - aligner.match_score = 2 - aligner.mismatch_score = -1 - aligner.open_gap_score = -2 - aligner.extend_gap_score = -0.5 - alignment = aligner.align(query_slice, ortholog_slice)[0] - - exact_matches = 0 - for query_index, ortholog_index in zip(alignment.indices[0], alignment.indices[1]): - if query_index != -1 and ortholog_index != -1: - if query_slice[query_index] == ortholog_slice[ortholog_index]: - exact_matches += 1 - return exact_matches / alignment.length + return BiopythonGlobalAlignment().calc_identities(query_slice, [ortholog_slice])[0] @staticmethod def _get_domain_slice(sequence, domain): @@ -251,20 +248,59 @@ def run(self, tf_sequence : str | list[str]) -> list[LverageRecord]: self.lverage_code = LverageCode.NO_ORTHOLOGS return [] + ortholog_domain_sets = [ + self.domain_scanner.get_domains(ortholog.sequence) + for ortholog in orthologs + ] + identities_by_query_domain = [] + for query_domain in query_domains: + matching_positions = [] + ortholog_dbds = [] + for ortholog_index, (ortholog, ortholog_domains) in enumerate( + zip(orthologs, ortholog_domain_sets) + ): + for domain_index, ortholog_domain in enumerate(ortholog_domains): + if self._base_accession(query_domain.accession) != self._base_accession(ortholog_domain.accession): + continue + matching_positions.append((ortholog_index, domain_index)) + ortholog_dbds.append(self._get_domain_slice(ortholog.sequence, ortholog_domain)) + + identity_matrix = [ + [None] * len(ortholog_domains) + for ortholog_domains in ortholog_domain_sets + ] + if matching_positions: + query_dbd = self._get_domain_slice(query_orf, query_domain) + returned_identities = self.alignment_component.calc_identities( + query_dbd, + ortholog_dbds, + ) + try: + domain_identities = list(returned_identities) + except TypeError as error: + raise TypeError("alignment component must return an ordered sequence of ratios") from error + if len(domain_identities) != len(matching_positions): + raise ValueError("alignment component must return one ratio per ortholog domain") + for (ortholog_index, domain_index), identity in zip( + matching_positions, + domain_identities, + ): + if isinstance(identity, bool) or not isinstance(identity, Real): + raise ValueError("alignment identities must be finite numeric ratios") + if not math.isfinite(identity) or identity < 0 or identity > 1: + raise ValueError("alignment identities must be finite ratios between zero and one") + identity_matrix[ortholog_index][domain_index] = float(identity) + identities_by_query_domain.append(identity_matrix) + records = [] has_valid_domain_pair = False - for ortholog in orthologs: - ortholog_domains = self.domain_scanner.get_domains(ortholog.sequence) - for query_domain in query_domains: - for ortholog_domain in ortholog_domains: + for ortholog_index, ortholog in enumerate(orthologs): + ortholog_domains = ortholog_domain_sets[ortholog_index] + for query_index, query_domain in enumerate(query_domains): + for domain_index, ortholog_domain in enumerate(ortholog_domains): if self._base_accession(query_domain.accession) != self._base_accession(ortholog_domain.accession): continue - domain_identity = self._calculate_domain_identity( - query_orf, - query_domain, - ortholog.sequence, - ortholog_domain, - ) + domain_identity = identities_by_query_domain[query_index][ortholog_index][domain_index] if domain_identity < self.dbd_identity_thresh: continue diff --git a/tests/v2/test_alignment.py b/tests/v2/test_alignment.py new file mode 100644 index 0000000..e04636b --- /dev/null +++ b/tests/v2/test_alignment.py @@ -0,0 +1,68 @@ +import unittest + +from lverage.alignment import BiopythonGlobalAlignment + + +class BiopythonGlobalAlignmentTests(unittest.TestCase): + + def test_exact_identity_counts_mismatches_and_gap_columns(self): + aligner = BiopythonGlobalAlignment() + + self.assertEqual(aligner.calc_identities("AAAA", ["AAAT"]), [0.75]) + self.assertEqual(aligner.calc_identities("AAAA", ["AAA"]), [0.75]) + + def test_internal_and_terminal_gaps_count_in_denominator(self): + aligner = BiopythonGlobalAlignment() + + self.assertEqual(aligner.calc_identities("ACGT", ["ACT"]), [0.75]) + self.assertEqual(aligner.calc_identities("ACGT", ["CGT"]), [0.75]) + + def test_duplicate_sequences_return_distinct_ordered_results(self): + identities = BiopythonGlobalAlignment().calc_identities( + "AAAA", + ["AAAT", "AAAT", "AAAA"], + ) + + self.assertEqual(identities, [0.75, 0.75, 1.0]) + + def test_default_scores_select_affine_global_algorithm(self): + aligner = BiopythonGlobalAlignment() + configured = aligner._make_aligner() + + self.assertEqual(configured.mode, "global") + self.assertEqual(configured.match_score, 2) + self.assertEqual(configured.mismatch_score, -1) + self.assertEqual(configured.open_gap_score, -2) + self.assertEqual(configured.extend_gap_score, -0.5) + self.assertEqual(configured.algorithm, "Gotoh global alignment algorithm") + + def test_linear_gap_configuration_selects_needleman_wunsch(self): + aligner = BiopythonGlobalAlignment( + gap_model="linear", + open_gap_score=-2, + extend_gap_score=-2, + ) + + self.assertEqual(aligner._make_aligner().algorithm, "Needleman-Wunsch") + + def test_linear_gap_configuration_requires_equal_gap_scores(self): + with self.assertRaises(ValueError): + BiopythonGlobalAlignment(gap_model="linear") + + def test_nonfinite_and_non_numeric_scores_are_rejected(self): + with self.assertRaises(ValueError): + BiopythonGlobalAlignment(match_score=float("inf")) + with self.assertRaises(TypeError): + BiopythonGlobalAlignment(match_score=True) + + def test_empty_sequences_are_rejected(self): + aligner = BiopythonGlobalAlignment() + + with self.assertRaises(ValueError): + aligner.calc_identities("", ["AAAA"]) + with self.assertRaises(ValueError): + aligner.calc_identities("AAAA", [""]) + + +if __name__ == "__main__": + unittest.main() \ No newline at end of file diff --git a/tests/v2/test_pipeline.py b/tests/v2/test_pipeline.py index a4b30c1..96262a3 100644 --- a/tests/v2/test_pipeline.py +++ b/tests/v2/test_pipeline.py @@ -1,5 +1,6 @@ import unittest +from lverage.alignment import AlignmentTemplate from lverage.domain_scanner import DomainRecord, DomainScannerTemplate from lverage.motif_database import MotifDBRecordTemplate, MotifDBTemplate from lverage.orf_searcher import OrfSearcherTemplate @@ -69,6 +70,19 @@ def get_orthologs(self, sequence : str): return list(self.orthologs) +class RecordingAlignment(AlignmentTemplate): + + def __init__(self, identities=None): + self.identities = identities + self.calls = [] + + def calc_identities(self, query_dbd, ortholog_dbds): + self.calls.append((query_dbd, list(ortholog_dbds))) + if self.identities is None: + return [1.0] * len(ortholog_dbds) + return list(self.identities[len(self.calls) - 1]) + + def make_ortholog(sequence="AAAA", species_tax_id=9606): return OrthologRecord( "NP_000001.1", @@ -90,7 +104,8 @@ def make_pipeline(self, orthologs=None, databases=None, valid_pfam_list=None, - threshold=0.7): + threshold=0.7, + alignment_component=None): if orfs is None: orfs = ["AAAA"] if domains is None: @@ -108,6 +123,7 @@ def make_pipeline(self, StubOrthologSearcher(orthologs), valid_pfam_list=valid_pfam_list, dbd_identity_thresh=threshold, + alignment_component=alignment_component, ) def test_no_orf_code(self): @@ -152,11 +168,102 @@ def test_success_returns_nested_records(self): self.assertEqual(records[0].motif_database_name, "ExampleDB") self.assertEqual(records[0].domain_identity, 1.0) + def test_default_alignment_components_are_independent_per_pipeline(self): + first_pipeline = self.make_pipeline() + second_pipeline = self.make_pipeline() + + first_pipeline.alignment_component.match_score = 7 + + self.assertIsNot(first_pipeline.alignment_component, second_pipeline.alignment_component) + self.assertEqual(first_pipeline.alignment_component.match_score, 7) + self.assertEqual(second_pipeline.alignment_component.match_score, 2) + def test_identity_threshold_is_inclusive(self): pipeline = self.make_pipeline(threshold=1.0) self.assertEqual(len(pipeline.run("QUERY")), 1) + def test_injected_alignment_preserves_occurrences_and_output_order(self): + query_sequence = "AAAAAAAA" + first_ortholog = make_ortholog("CCCCCCCC") + second_ortholog = make_ortholog("GGGGGGGG", species_tax_id=10090) + query_domains = [ + DomainRecord("Query first", "PF00046.1", 0, 2), + DomainRecord("Query second", "PF00046.2", 2, 4), + ] + repeated_ortholog_domains = [ + DomainRecord("Ortholog first", "PF00046.3", 0, 2), + DomainRecord("Ortholog second", "PF00046.4", 2, 4), + ] + alignment = RecordingAlignment([ + [0.80, 0.81, 0.82, 0.83], + [0.84, 0.85, 0.86, 0.87], + ]) + pipeline = self.make_pipeline( + orfs=[query_sequence], + domains={ + query_sequence: query_domains, + first_ortholog.sequence: repeated_ortholog_domains, + second_ortholog.sequence: repeated_ortholog_domains, + }, + orthologs=[first_ortholog, second_ortholog], + alignment_component=alignment, + ) + + records = pipeline.run("QUERY") + + self.assertEqual( + alignment.calls, + [("AA", ["CC", "CC", "GG", "GG"])] * 2, + ) + self.assertEqual( + [ + (record.ortholog.sequence, record.query_domain.start, record.ortholog_domain.start) + for record in records + ], + [ + (ortholog.sequence, query_start, ortholog_start) + for ortholog in (first_ortholog, second_ortholog) + for query_start in (0, 2) + for ortholog_start in (0, 2) + ], + ) + self.assertEqual( + [record.domain_identity for record in records], + [0.80, 0.81, 0.84, 0.85, 0.82, 0.83, 0.86, 0.87], + ) + + def test_alignment_component_must_return_one_score_per_candidate(self): + alignment = RecordingAlignment([[]]) + pipeline = self.make_pipeline(alignment_component=alignment) + + with self.assertRaises(ValueError): + pipeline.run("QUERY") + + def test_type_error_from_alignment_component_propagates_unchanged(self): + original_error = TypeError("alignment implementation failed") + + class FailingAlignment(AlignmentTemplate): + + def calc_identities(self, query_dbd, ortholog_dbds): + raise original_error + + pipeline = self.make_pipeline(alignment_component=FailingAlignment()) + + with self.assertRaises(TypeError) as raised: + pipeline.run("QUERY") + + self.assertIs(raised.exception, original_error) + + def test_alignment_component_scores_must_be_finite_ratios(self): + for invalid_score in [float("nan"), -0.1, 1.1, "1.0", True]: + with self.subTest(score=invalid_score): + pipeline = self.make_pipeline( + alignment_component=RecordingAlignment([[invalid_score]]) + ) + with self.assertRaises(ValueError): + pipeline.run("QUERY") + def test_longest_distinct_orf_with_an_accepted_domain_is_selected(self): pipeline = self.make_pipeline( orfs={"first": ["AAAA", "AAAAAAAA", "AAAAAAAA"], "second": ["AAAAAA"]},