move ignore to Fingerprint constructor

Author: cbouy

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added `ignore` parameter in `Fingerprint` to ignore specific pairs of residues.
+  Defaults to ignoring interactions of a residue with itself.
 - Support for `ImplicitHBAcceptor` and `ImplicitHBDonor` interactions to calculate  
   hydrogen bond interactions with merely heavy atoms. This helps users to estimate 
   the hydrogen bond interactions for structures from PDB database or AI-driven

docs/notebooks/advanced.ipynb

@@ -584,7 +584,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can define your own predicate function to decide which residue pairs should be ignored. This can be done through the `ignore` parameter which takes two {class}`~prolif.residue.Residue` objects as input and returns a boolean:"
+    "You can define your own predicate function to decide which residue pairs should be ignored. This can be done through the `ignore` parameter of the `Fingerprint` constructor, which takes two {class}`~prolif.residue.Residue` objects as input and returns a boolean:"
    ]
   },
   {
@@ -604,7 +604,8 @@
     "    )\n",
     "\n",
     "\n",
-    "fp.run_from_iterable([protein_mol], protein_mol, ignore=ignore_sequence_neighbours)\n",
+    "fp = plf.Fingerprint([\"HBAcceptor\", \"HBDonor\"], ignore=ignore_sequence_neighbours)\n",
+    "fp.run_from_iterable([protein_mol], protein_mol)\n",
     "fp.to_dataframe()"
    ]
   },

prolif/fingerprint.py

@@ -140,6 +140,10 @@ class Fingerprint:
     implicit_hydrogens : bool
         Whether to use interactions compatible with implicit hydrogens instead of the
         default explicit hydrogen-based ones.
+    ignore : Callable[[Residue, Residue], bool]
+        Predicate function that returns ``True`` if the two residues should be
+        skipped when calculating interactions. Default is to ignore interactions
+        between the same residue (see :func:`~prolif.residue.ignore_self_interactions`).
 
     Attributes
     ----------
@@ -254,7 +258,7 @@ class for more information.
 
     .. versionchanged:: 2.2.0
         Added ``implicit_hydrogens`` for easily switching to implicit-hydrogen
-        interactions.
+        interactions. Added ``ignore`` parameter.
     """
 
     def __init__(
@@ -265,6 +269,7 @@ def __init__(
         vicinity_cutoff: float = 6.0,
         use_segid: bool | None = None,
         implicit_hydrogens: bool = False,
+        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> None:
         if interactions is None:
             interactions = DEFAULT_INTERACTIONS
@@ -295,6 +300,7 @@ def __init__(
             interactions = temp_interactions
 
         self.count = count
+        self.ignore = ignore
         self._set_interactions(interactions, parameters)
         self.vicinity_cutoff = vicinity_cutoff
         self.parameters = parameters
@@ -471,7 +477,6 @@ def generate(
         prot: Molecule,
         residues: "ResidueSelection" = None,
         metadata: Literal[False] = False,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> dict[tuple["ResidueId", "ResidueId"], "NDArray"]: ...
     @overload
     def generate(
@@ -480,15 +485,13 @@ def generate(
         prot: Molecule,
         residues: "ResidueSelection" = None,
         metadata: Literal[True] = True,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> IFP: ...
     def generate(
         self,
         lig: Molecule,
         prot: Molecule,
         residues: "ResidueSelection" = None,
         metadata: bool = False,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> IFP | dict[tuple["ResidueId", "ResidueId"], "NDArray"]:
         """Generates the interaction fingerprint between 2 molecules
 
@@ -509,13 +512,6 @@ def generate(
         metadata : bool
             For each residue pair and interaction, return an interaction metadata
             dictionary instead of bits.
-        ignore : Callable[[Residue, Residue], bool]
-            Predicate function that returns ``True`` if the two residues should be
-            skipped when calculating interactions. Default is to ignore interactions
-            between the same residue (see
-            :func:`~prolif.residue.ignore_self_interactions`). Can be used to exclude
-            residue pairs based on :class:`~prolif.residue.ResidueId` attributes, but
-            also by geometric criteria (e.g. residues where any atom clashes).
 
         Returns
         -------
@@ -544,9 +540,6 @@ def generate(
             dictionary of metadata tuples indexed by interaction name instead of a
             tuple of arrays.
 
-        .. versionchanged:: 2.2.0
-            Added ``ignore`` parameter.
-
         """
         ifp: IFP | dict[tuple["ResidueId", "ResidueId"], "NDArray"] = (
             IFP() if metadata else {}
@@ -563,7 +556,7 @@ def generate(
                 )
             for prot_key in prot_residues:  # type:ignore[union-attr]
                 pres = prot[prot_key]
-                if ignore(lres, pres):
+                if self.ignore(lres, pres):
                     continue
                 key = (lresid, pres.resid)
                 interactions = get_interactions(lres, pres)
@@ -582,7 +575,6 @@ def run(
         progress: bool = True,
         n_jobs: int | None = None,
         parallel_strategy: Literal["chunk", "queue"] | None = None,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> "Fingerprint":
         """Generates the fingerprint on a trajectory for a ligand and a protein
 
@@ -625,16 +617,9 @@ def run(
               atoms.
             - ``None``: See :func:`~prolif.parallel.get_mda_parallel_strategy` for
               the default behavior.
-        ignore : Callable[[Residue, Residue], bool]
-            Predicate function that returns ``True`` if the two residues should be
-            skipped when calculating interactions. Default is to ignore interactions
-            between the same residue (see
-            :func:`~prolif.residue.ignore_self_interactions`). Can be used to exclude
-            residue pairs based on :class:`~prolif.residue.ResidueId` attributes, but
-            also by geometric criteria (e.g. residues where any atom clashes).
 
         Raises
-        ------
+------
         ValueError
             If ``n_jobs <= 0``
 
@@ -679,9 +664,6 @@ def run(
             Added ``use_segid``, ``parallel_strategy`` parameter and changed the
             default behavior of ``n_jobs=None``.
 
-        .. versionchanged:: 2.2.0
-            Added ``ignore`` parameter.
-
         """  # noqa: E501
         if converter_kwargs is not None and len(converter_kwargs) != 2:
             raise ValueError("converter_kwargs must be a list of 2 dicts")
@@ -714,7 +696,6 @@ def run(
                     residues=residues,
                     converter_kwargs=converter_kwargs,
                     progress=progress,
-                    ignore=ignore,
                 )
             else:
                 ifp = self._run_parallel(
@@ -726,7 +707,6 @@ def run(
                     progress=progress,
                     n_jobs=n_jobs,
                     parallel_strategy=parallel_strategy,
-                    ignore=ignore,
                 )
             self.ifp = ifp
 
@@ -741,7 +721,6 @@ def run(
                 use_segid=self.use_segid,
                 n_jobs=n_jobs,
                 parallel_strategy=parallel_strategy,
-                ignore=ignore,
             )
         return self
 
@@ -763,7 +742,6 @@ def _run_serial(
         residues: "ResidueSelection",
         converter_kwargs: tuple[dict, dict],
         progress: bool,
-        ignore: Callable[[Residue, Residue], bool],
         **kwargs: Any,
     ) -> "IFPResults":
         """Serial implementation for trajectories."""
@@ -780,7 +758,7 @@ def _run_serial(
                 prot, use_segid=self.use_segid, **converter_kwargs[1]
             )
             ifp[int(ts.frame)] = self.generate(
-                lig_mol, prot_mol, residues=residues, metadata=True, ignore=ignore
+                lig_mol, prot_mol, residues=residues, metadata=True
             )
         return ifp
 
@@ -794,7 +772,6 @@ def _run_parallel(
         progress: bool,
         n_jobs: int | None,
         parallel_strategy: Literal["chunk", "queue"],
-        ignore: Callable[[Residue, Residue], bool],
         **kwargs: Any,
     ) -> "IFPResults":
         """Parallel implementation of :meth:`~Fingerprint.run`"""
@@ -825,7 +802,6 @@ def _run_parallel(
                     residues=residues,
                     converter_kwargs=converter_kwargs,
                     progress=progress,
-                    ignore=ignore,
                 )
             else:
                 frames = []
@@ -843,7 +819,6 @@ def _run_parallel(
                 tqdm_kwargs=tqdm_kwargs,
                 rdkitconverter_kwargs=converter_kwargs,
                 use_segid=self.use_segid or False,
-                ignore=ignore,
             ) as pool:
                 return pool.process(traj, lig, prot)
 
@@ -860,7 +835,6 @@ def _run_parallel(
             tqdm_kwargs=tqdm_kwargs,
             rdkitconverter_kwargs=converter_kwargs,
             use_segid=self.use_segid or False,
-            ignore=ignore,
         ) as pool:
             for ifp_data_chunk in pool.process(args_iterable):
                 ifp.update(ifp_data_chunk)
@@ -875,7 +849,6 @@ def run_from_iterable(
         residues: "ResidueSelection" = None,
         progress: bool = True,
         n_jobs: int | None = None,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
     ) -> "Fingerprint":
         """Generates the fingerprint between a list of ligands and a protein
 
@@ -900,13 +873,6 @@ def run_from_iterable(
             Number of processes to run in parallel. If ``n_jobs=1``, the
             calculation will run in serial. If ``n_jobs=None``, see
             :func:`~prolif.parallel.get_n_jobs` for the default behavior.
-        ignore : Callable[[Residue, Residue], bool]
-            Predicate function that returns ``True`` if the two residues should be
-            skipped when calculating interactions. Default is to ignore interactions
-            between the same residue (see
-            :func:`~prolif.residue.ignore_self_interactions`). Can be used to exclude
-            residue pairs based on :class:`~prolif.residue.ResidueId` attributes, but
-            also by geometric criteria (e.g. residues where any atom clashes).
 
         Raises
         ------
@@ -948,9 +914,6 @@ def run_from_iterable(
         .. versionchanged:: 2.1.0
             Changed the default behavior of ``n_jobs=None``.
 
-        .. versionchanged:: 2.2.0
-            Added ``ignore`` parameter.
-
         """
         if residues == "all":
             residues = list(prot_mol.residues)
@@ -963,7 +926,6 @@ def run_from_iterable(
                     prot_mol=prot_mol,
                     residues=residues,
                     progress=progress,
-                    ignore=ignore,
                 )
             else:
                 ifp = self._run_iter_parallel(
@@ -972,7 +934,6 @@ def run_from_iterable(
                     residues=residues,
                     progress=progress,
                     n_jobs=n_jobs,
-                    ignore=ignore,
                 )
             self.ifp = ifp
 
@@ -983,7 +944,6 @@ def run_from_iterable(
                 residues=residues,
                 progress=progress,
                 n_jobs=n_jobs,
-                ignore=ignore,
             )
 
         return self
@@ -994,14 +954,13 @@ def _run_iter_serial(
         prot_mol: Molecule,
         residues: "ResidueSelection" = None,
         progress: bool = True,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
         **kwargs: Any,
     ) -> "IFPResults":
         iterator = tqdm(lig_iterable, **kwargs) if progress else lig_iterable
         ifp: "IFPResults" = {}
         for i, lig_mol in enumerate(iterator):
             ifp[i] = self.generate(
-                lig_mol, prot_mol, residues=residues, metadata=True, ignore=ignore
+                lig_mol, prot_mol, residues=residues, metadata=True
             )
         return ifp
 
@@ -1012,7 +971,6 @@ def _run_iter_parallel(
         residues: "ResidueSelection" = None,
         progress: bool = True,
         n_jobs: int | None = None,
-        ignore: Callable[[Residue, Residue], bool] = ignore_self_interactions,
         **kwargs: Any,
     ) -> "IFPResults":
         """Parallel implementation of :meth:`~Fingerprint.run_from_iterable`"""
@@ -1028,7 +986,6 @@ def _run_iter_parallel(
             fingerprint=self,
             prot_mol=prot_mol,
             residues=residues,
-            ignore=ignore,
             tqdm_kwargs={"total": total, "disable": not progress, **kwargs},
         ) as pool:
             for i, ifp_data in enumerate(pool.process(lig_iterable)):
@@ -1059,7 +1016,7 @@ def _run_bridged_analysis(
         """  # noqa: E501
         self.ifp = cast("IFPResults", getattr(self, "ifp", {}))
         for interaction in self.bridged_interactions.values():
-            interaction.setup(ifp_store=self.ifp, **kwargs)
+            interaction.setup(ifp_store=self.ifp, ignore=self.ignore, **kwargs)
             interaction.run(traj, lig, prot)
         return self
 
@@ -1078,7 +1035,7 @@ def _run_iter_bridged_analysis(
         """
         self.ifp = getattr(self, "ifp", {})
         for interaction in self.bridged_interactions.values():
-            interaction.setup(ifp_store=self.ifp, **kwargs)
+            interaction.setup(ifp_store=self.ifp, ignore=self.ignore, **kwargs)
             interaction.run_from_iterable(lig_iterable, prot_mol)
         return self
 

prolif/interactions/water_bridge.py

@@ -110,6 +110,7 @@ def setup(self, ifp_store: Optional["IFPResults"] = None, **kwargs: Any) -> None
         self.residues = self.kwargs.pop("residues", None)
         self.converter_kwargs = self.kwargs.pop("converter_kwargs", ({}, {}))
         self.water_fp.use_segid = self.kwargs.pop("use_segid", False)
+        self.water_fp.ignore = self.kwargs.pop("ignore", self.water_fp.ignore)
 
     def run(
         self,