PFASGroups 3.4.3__tar.gz → 3.4.4__tar.gz

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/PFASGroups/PFASDefinitionModel.py

@@ -64,21 +64,21 @@ class PFASDefinition:
     def __str__(self):
         return self.name
     
-    def applies_to_molecule(self, 
-                  mol_or_smiles: Union[Chem.Mol, str], 
+    def applies_to_molecule(self,
+                  mol_or_smiles: Union[Chem.Mol, str],
                   formula: Optional[Dict[str, int]] = None,
                   **kwargs) -> bool:
         """Check if this PFAS definition applies to a given molecule.
-        
+
         This method evaluates whether a molecule meets the structural and/or compositional
         criteria defined by this PFASDefinition. The evaluation logic depends on the
         requireBoth flag:
-        
+
         - If requireBoth=False (default): Returns True if EITHER SMARTS matches OR
           fluorine ratio is met (logical OR)
         - If requireBoth=True: Returns True only if BOTH SMARTS matches AND fluorine
           ratio are met (logical AND)
-        
+
         Parameters
         ----------
         mol_or_smiles : Union[Chem.Mol, str]
@@ -88,16 +88,16 @@ class PFASDefinition:
             If None, will be computed from the molecule.
         **kwargs : dict
             Additional parameters:
-            
+
             - include_hydrogen (bool): Whether to include H in fluorine ratio calculation.
               Defaults to self.includeHydrogen
             - require_both (bool): Override the instance's requireBoth setting
-        
+
         Returns
         -------
         bool
             True if the molecule meets the definition criteria, False otherwise
-        
+
         Examples
         --------
         >>> pfas_def = PFASDefinition(
@@ -108,45 +108,101 @@ class PFASDefinition:
         True
         >>> pfas_def.applies_to_molecule("CCCCCC")  # No fluorine
         False
-        
+
         Notes
         -----
         - SMARTS patterns are checked using substructure matching (HasSubstructMatch)
-        - Fluorine ratio is calculated as: F_count / total_atom_count
+        - Fluorine ratio is mass-weighted: F mass / total mass (see `match_details`
+          for the breakdown of which criterion -- SMARTS, ratio, or both -- was met,
+          and the actual computed ratio value)
         - Invalid SMILES strings return False
         """
+        return self.match_details(mol_or_smiles, formula=formula, **kwargs)['applies']
+
+    def match_details(self,
+                  mol_or_smiles: Union[Chem.Mol, str],
+                  formula: Optional[Dict[str, int]] = None,
+                  **kwargs) -> Dict:
+        """Evaluate a molecule against this definition and report each criterion separately.
+
+        Unlike `applies_to_molecule`, which collapses everything to a single bool,
+        this returns the SMARTS-match result, the fluorine-ratio result, and the
+        actual computed ratio value individually -- useful for explaining *why* a
+        molecule matched (e.g. distinguishing a genuine structural PFAS from one
+        that only clears a fluorine-content threshold).
+
+        Parameters
+        ----------
+        mol_or_smiles : Union[Chem.Mol, str]
+            Input molecule as RDKit Mol object or SMILES string
+        formula : Optional[Dict[str, int]], default=None
+            Pre-computed molecular formula as {element: count} dictionary.
+            If None, will be computed from the molecule.
+        **kwargs : dict
+            Same as `applies_to_molecule` (`include_hydrogen`, `require_both`).
+
+        Returns
+        -------
+        dict
+            - 'valid' (bool): False if the input SMILES could not be parsed
+            - 'smarts_match' (bool): whether any SMARTS pattern matched
+            - 'fluorine_ratio' (float or None): the computed ratio, or None if this
+              definition has no fluorineRatio threshold
+            - 'fluorine_ratio_threshold' (float or None): this definition's threshold
+            - 'ratio_match' (bool): whether the ratio met the threshold (True if no
+              threshold is defined, matching `applies_to_molecule`'s OR semantics)
+            - 'applies' (bool): the same overall result `applies_to_molecule` returns
+        """
         # Convert SMILES to Mol if needed
         if isinstance(mol_or_smiles, str):
             mol = Chem.MolFromSmiles(mol_or_smiles)
             if mol is None:
-                return False
+                return {
+                    'valid': False,
+                    'smarts_match': False,
+                    'fluorine_ratio': None,
+                    'fluorine_ratio_threshold': self.fluorineRatio,
+                    'ratio_match': False,
+                    'applies': False,
+                }
         else:
             mol = mol_or_smiles
-        
+
         # Check SMARTS matches
         smarts_match = False
         for pattern in self.smarts_patterns:
             if mol.HasSubstructMatch(pattern):
                 smarts_match = True
                 break
-        
+
         # Check fluorine ratio if defined
         ratio_match = True  # Default to True if no ratio requirement
+        fluorine_ratio_value = None
         if self.fluorineRatio is not None:
             if formula is None:
                 formula = self._compute_formula(mol, kwargs.get("include_hydrogen", self.includeHydrogen))
-            
-            ratio_match = self._check_fluorine_ratio(formula, kwargs.get("include_hydrogen", self.includeHydrogen))
-        
+
+            fluorine_ratio_value = self._compute_fluorine_ratio(formula, kwargs.get("include_hydrogen", self.includeHydrogen))
+            ratio_match = fluorine_ratio_value >= self.fluorineRatio
+
         # Apply logic based on require_both
         if kwargs.get("require_both", self.requireBoth):
-            return smarts_match and ratio_match
-        else:
+            applies = smarts_match and ratio_match
+        elif self.fluorineRatio is None:
             # If no fluorine ratio is defined, only check SMARTS
-            if self.fluorineRatio is None:
-                return smarts_match
+            applies = smarts_match
+        else:
             # Otherwise, SMARTS OR ratio
-            return smarts_match or ratio_match
+            applies = smarts_match or ratio_match
+
+        return {
+            'valid': True,
+            'smarts_match': smarts_match,
+            'fluorine_ratio': round(fluorine_ratio_value, 4) if fluorine_ratio_value is not None else None,
+            'fluorine_ratio_threshold': self.fluorineRatio,
+            'ratio_match': ratio_match,
+            'applies': applies,
+        }
     
     def _compute_formula(self, mol: Chem.Mol, include_hydrogen: bool) -> Dict[str, int]:
         """Compute molecular formula as element count dictionary.
@@ -175,16 +231,11 @@ class PFASDefinition:
         
         return formula
     
-    def _check_fluorine_ratio(self, formula: Dict[str, int], include_hydrogen: bool) -> bool:
-        """Check if the fluorine ratio in a molecular formula meets the threshold.
+    def _compute_fluorine_ratio(self, formula: Dict[str, int], include_hydrogen: bool) -> float:
+        """Compute the mass-weighted fluorine ratio of a molecular formula.
 
-        Mass-weighted (F mass / total mass), matching the zeropmdb production
-        database's `fluorine_ratio` field (see `Update_CFHNOPS.sql`):
-        `fluorine_ratio = F_mass / (molecular_weight - H_mass)`. This is NOT an
-        atom-count ratio -- a molecule with heavy non-F/non-H atoms (e.g. Cl, Br)
-        will have a lower ratio per atom than per unit mass would suggest, and
-        vice versa for light atoms (C, N, O), so the two formulas can disagree
-        on which side of a threshold like 0.3 a given molecule falls.
+        Mass-weighted (F mass / total mass):
+        `fluorine_ratio = F_mass / (molecular_weight - H_mass)`.
 
         Parameters
         ----------
@@ -197,13 +248,8 @@ class PFASDefinition:
 
         Returns
         -------
-        bool
-            True if (F_mass / total_mass) >= self.fluorineRatio, False otherwise
-
-        Notes
-        -----
-        - Returns False if total_mass is 0
-        - Formula with no fluorine (F_count=0) will fail unless fluorineRatio=0
+        float
+            F_mass / total_mass, or 0.0 if total_mass is 0
         """
         from rdkit.Chem import GetPeriodicTable
         pt = GetPeriodicTable()
@@ -217,9 +263,22 @@ class PFASDefinition:
             total_mass = sum(count * pt.GetAtomicWeight(sym) for sym, count in formula.items() if sym != 'H')
 
         if total_mass == 0:
-            return False
+            return 0.0
+
+        return f_mass / total_mass
 
-        ratio = f_mass / total_mass
+    def _check_fluorine_ratio(self, formula: Dict[str, int], include_hydrogen: bool) -> bool:
+        """Check if the fluorine ratio in a molecular formula meets the threshold.
+
+        Thin boolean wrapper around `_compute_fluorine_ratio`, kept for backward
+        compatibility with any external callers of this (nominally private) method.
+
+        Returns
+        -------
+        bool
+            True if (F_mass / total_mass) >= self.fluorineRatio, False otherwise
+        """
+        ratio = self._compute_fluorine_ratio(formula, include_hydrogen)
         return ratio >= self.fluorineRatio
     
     def test(self, test_data=None):

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/PFASGroups/data/PFAS_definitions_smarts.json

@@ -134,7 +134,7 @@
         ],
         "fluorineRatio": 0.3,
         "includeHydrogen": false,
-        "description": "Custom structural patterns or F ratio >= 0.3, mass-weighted (F mass / heavy-atom mass), matching the zeropmdb production database's fluorine_ratio field. Not an atom-count ratio: molecules with heavier non-F/non-H atoms (Cl, Br, S...) score lower per unit mass than per atom, and vice versa for lighter atoms (C, N, O).",
+        "description": "Custom structural patterns or F ratio >= 0.3, mass-weighted (F mass / heavy-atom mass).",
         "test": {
             "category": "definition",
             "examples": {

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/PFASGroups/parser.py

@@ -179,12 +179,21 @@ def parse_definitions_in_mol(mol, **kwargs):
     pfas_definitions = kwargs.get('pfas_definitions')
     for pdef in pfas_definitions:
         matched = False
+        best_details = None
         for mol in frags:
-            if pdef.applies_to_molecule(mol_or_smiles=mol, **kwargs) is True:
+            details = pdef.match_details(mol_or_smiles=mol, **kwargs)
+            # Keep the most informative details across fragments: prefer the
+            # fragment that actually matched, and among matches prefer the one
+            # with the higher fluorine ratio (most representative of the PFAS
+            # fragment rather than an unrelated counterion/fragment).
+            if details['applies'] is True:
                 matched = True
-                break
+                if best_details is None or (details['fluorine_ratio'] or 0) > (best_details['fluorine_ratio'] or 0):
+                    best_details = details
+            elif best_details is None:
+                best_details = details
         if matched is True:
-            definition_matches.append(pdef)
+            definition_matches.append((pdef, best_details))
     return definition_matches
 
 
@@ -696,9 +705,7 @@ def setup_halogen_groups_database(
 ):
     """Set up halogen groups metadata tables in a database.
 
-    This function creates tables to store halogen group definitions and SMARTS patterns,
-    similar to the load_pfas_groups function in zeropmdb.
-
+    This function creates tables to store halogen group definitions and SMARTS patterns.
     Parameters
     ----------
     conn : str or sqlalchemy.engine.Engine
@@ -873,6 +880,12 @@ def parse_mols(mols, output_format='list', include_PFAS_definitions=True,
         - ``'id'``: integer definition ID
         - ``'definition_name'``: definition name
         - ``'halogen'``: ``'F'`` (definitions only match when F is enabled)
+        - ``'smarts_match'``: bool, whether any of the definition's SMARTS patterns matched
+        - ``'fluorine_ratio'``: float or None, the computed mass-weighted F ratio
+          (None if this definition has no fluorineRatio threshold)
+        - ``'fluorine_ratio_threshold'``: float or None, the definition's configured threshold
+        - ``'ratio_match'``: bool, whether the ratio met the threshold (True if no
+          threshold is defined)
     """
 
     real_halogens, include_h_components, include_wildcards = _normalize_halogen_controls(halogens)
@@ -1130,7 +1143,12 @@ def parse_mols(mols, output_format='list', include_PFAS_definitions=True,
                             'id': definition.id,
                             'definition_name': definition.name,
                             'type':'PFASdefinition',
-                            'halogen': 'F'} for definition in definitions])
+                            'halogen': 'F',
+                            'smarts_match': details['smarts_match'],
+                            'fluorine_ratio': details['fluorine_ratio'],
+                            'fluorine_ratio_threshold': details['fluorine_ratio_threshold'],
+                            'ratio_match': details['ratio_match'],
+                            } for definition, details in definitions])
     # Convert results to list format (one entry per molecule)
     results_list = [r for r in results.values()]
     # Format output based on requested format
@@ -1154,7 +1172,11 @@ def parse_mols(mols, output_format='list', include_PFAS_definitions=True,
                         'smiles': entry['smiles'],
                         'match_id': match['match_id'],
                         'match_name': match['definition_name'],
-                        'match_type': match['type']
+                        'match_type': match['type'],
+                        'smarts_match': match.get('smarts_match'),
+                        'fluorine_ratio': match.get('fluorine_ratio'),
+                        'fluorine_ratio_threshold': match.get('fluorine_ratio_threshold'),
+                        'ratio_match': match.get('ratio_match'),
                     })
         df = pd.DataFrame(rows)
         return df.to_csv(index=False) if output_format == 'csv' else df

{pfasgroups-3.4.3 → pfasgroups-3.4.4/PFASGroups.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PFASGroups
-Version: 3.4.3
+Version: 3.4.4
 Summary: A comprehensive cheminformatics package for automated detection, classification, and analysis of halogenated substances, with a focus on per- and polyfluoroalkyl substances (PFAS). Combines SMARTS pattern matching, molecular formula constraints, and graph-based pathfinding to identify 119 groups. Supports creations of embeddings with graph metrics for Machine Learning workflows.
 Author: Luc T. Miaz
 Author-email: "Luc T. Miaz" <luc@miaz.ch>
@@ -846,6 +846,8 @@ See [USER_GUIDE.md](USER_GUIDE.md) for comprehensive examples including:
 - Integration with pandas and scikit-learn
 
 ## Summary of changes by version
+- **Version 3.4.4**: Add fluorine ratio and structural match to returned results (for debugging or diplay).
+
 - **Version 3.4.3**: Fixed ratio error, specific to PFASSTRUCTv5
 
 - **Version 3.4.2**: Fixed ambiguity with OPPT 2023.

{pfasgroups-3.4.3/PFASGroups.egg-info → pfasgroups-3.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PFASGroups
-Version: 3.4.3
+Version: 3.4.4
 Summary: A comprehensive cheminformatics package for automated detection, classification, and analysis of halogenated substances, with a focus on per- and polyfluoroalkyl substances (PFAS). Combines SMARTS pattern matching, molecular formula constraints, and graph-based pathfinding to identify 119 groups. Supports creations of embeddings with graph metrics for Machine Learning workflows.
 Author: Luc T. Miaz
 Author-email: "Luc T. Miaz" <luc@miaz.ch>
@@ -846,6 +846,8 @@ See [USER_GUIDE.md](USER_GUIDE.md) for comprehensive examples including:
 - Integration with pandas and scikit-learn
 
 ## Summary of changes by version
+- **Version 3.4.4**: Add fluorine ratio and structural match to returned results (for debugging or diplay).
+
 - **Version 3.4.3**: Fixed ratio error, specific to PFASSTRUCTv5
 
 - **Version 3.4.2**: Fixed ambiguity with OPPT 2023.

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/README.md

@@ -798,6 +798,8 @@ See [USER_GUIDE.md](USER_GUIDE.md) for comprehensive examples including:
 - Integration with pandas and scikit-learn
 
 ## Summary of changes by version
+- **Version 3.4.4**: Add fluorine ratio and structural match to returned results (for debugging or diplay).
+
 - **Version 3.4.3**: Fixed ratio error, specific to PFASSTRUCTv5
 
 - **Version 3.4.2**: Fixed ambiguity with OPPT 2023.

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/gui/workers.py

@@ -146,15 +146,20 @@ class DefinitionTestWorker(Worker):
             self.progress.emit(50)
 
             matched = parse_definitions_in_mol(mol)
-            matched_ids = {d.id for d in matched}
+            matched_details = {pdef.id: details for pdef, details in matched}
 
             results = []
             for d in definitions:
+                details = matched_details.get(d.id)
                 results.append({
                     "id": d.id,
                     "name": d.name,
                     "description": d.description,
-                    "passed": d.id in matched_ids,
+                    "passed": d.id in matched_details,
+                    "smarts_match": details["smarts_match"] if details else False,
+                    "fluorine_ratio": details["fluorine_ratio"] if details else None,
+                    "fluorine_ratio_threshold": d.fluorineRatio,
+                    "ratio_match": details["ratio_match"] if details else False,
                 })
 
             self.progress.emit(100)

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PFASGroups"
-version = "3.4.3"
+version = "3.4.4"
 description = "A comprehensive cheminformatics package for automated detection, classification, and analysis of halogenated substances, with a focus on per- and polyfluoroalkyl substances (PFAS). Combines SMARTS pattern matching, molecular formula constraints, and graph-based pathfinding to identify 119 groups. Supports creations of embeddings with graph metrics for Machine Learning workflows."
 authors = [
     { name = "Luc T. Miaz", email = "luc@miaz.ch" }

{pfasgroups-3.4.3 → pfasgroups-3.4.4}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = PFASGroups
-version = 3.4.3
+version = 3.4.4
 description = A comprehensive cheminformatics package for automated detection, classification, and analysis of halogenated substances, with a focus on per- and polyfluoroalkyl substances (PFAS). Supports multi-halogen fingerprinting (F, Cl, Br, I) with per/poly saturation filtering and stackable fingerprint vectors.
 long_description = file: README.md
 long_description_content_type = text/markdown