Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/api/alignment.rst
Original file line number Diff line number Diff line change
@@ -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:
1 change: 1 addition & 0 deletions docs/api/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ classes from the modules shown below.
:maxdepth: 1

domain_scanner
alignment
blast
jaspar
motif_database
Expand Down
12 changes: 10 additions & 2 deletions docs/api/pipeline.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,23 @@ 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
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.

Expand Down
157 changes: 157 additions & 0 deletions src/lverage/alignment.py
Original file line number Diff line number Diff line change
@@ -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
92 changes: 64 additions & 28 deletions src/lverage/pipeline.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 = {
Expand All @@ -83,14 +86,20 @@ 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 = []

self.motif_database_list = motif_database_list.copy() if isinstance(motif_database_list, list) else motif_database_list
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
Expand All @@ -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")
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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

Expand Down
Loading
Loading