🧪 PFAS Group Analyzer

🔬 Step-by-Step Algorithm Flow

The PFASGroupsJS algorithm detects PFAS functional groups by matching SMARTS patterns and analyzing fluorinated carbon components in molecular structures. The algorithm follows a multi-step process to identify which PFAS groups are present in a given molecule.

Formula Constraint Types

🔬 PFAS Groups Taxonomy

Interactive visualization of OECD and Generic PFAS group classifications. Click on any group to see SMARTS patterns, constraints, and parent-child relationships.

Fluorinated Chain Pathways

For some PFAS groups, the analyzer looks for fluorinated chains connecting two functional groups. The pathway patterns defined in fpaths.json specify which atoms are considered part of a valid fluorinated path.

Figure 3: Fluorinated Chain Pathway Patterns (from fpaths.json)

Pathway Types

Path Finding Algorithm

1. Identify all atoms matching smarts1 (e.g., carboxylic acid group)
2. Identify all atoms matching smarts2 (e.g., another functional group or chain end)
3. Find shortest path between each pair of matched atoms
4. Check if all atoms in the path match the pathway SMARTS pattern
5. Record valid paths as fluorinated chains

Example: PFOA (Perfluorooctanoic acid)

Structure: CF₃-CF₂-CF₂-CF₂-CF₂-CF₂-CF₂-COOH

Functional group (smarts1): -COOH (carboxylic acid)
Chain end (smarts2): -CF₃ (trifluoromethyl)
Path: All carbon atoms between -COOH and -CF₃
Pattern match: All carbons are fully fluorinated
Result: Matches "Perfluoroalkyl" pathway → Classified as PFCA
                    

⭐ Molecule Prioritization

The prioritization tool ranks analyzed molecules by similarity to reference compounds or by intrinsic fluorination characteristics. This is useful for screening large datasets, regulatory watchlist generation, and environmental monitoring applications.

Prioritization Modes

Parameter Guidelines

Workflow

1. Analyze molecules: Run normal PFAS group analysis first
2. Enable prioritization: Check "Enable prioritization" in the prioritization section
3. Choose mode:
   • For similarity: Check "Use reference list" and enter reference SMILES
   • For intrinsic: Uncheck reference mode and adjust a, b, p parameters
4. Apply: Click "Apply Prioritization" to rank results
5. Export: Priority scores are included in CSV/Excel exports

Example Applications

Interpreting Scores

• Reference mode (KL divergence): Lower scores indicate greater similarity. Score of 0 = identical composition.
• Intrinsic mode: Higher scores indicate higher priority based on your chosen weighting.
• Equal scores: Molecules with identical fluorination profiles receive the same priority.

Python Integration

The full Python package provides additional prioritization capabilities:

• Statistical analysis of priority distributions
• Batch processing of large databases
• Integration with SQL databases
• Advanced filtering and clustering

See the Python documentation for details.

Usage Guide

Single Molecule Analysis

1. Select input format (SMILES or InChI)
2. Enter molecular structure in the text area
3. Click "Analyze" or press Ctrl+Enter
4. View results with structure visualization and detected groups

Batch Processing

1. Prepare a CSV or Excel file with a column containing SMILES or InChI strings
2. Click "📁 Click to import CSV or Excel file"
3. Select your file (column auto-detection happens automatically)
4. Click "Analyze" to process all molecules
5. Export results to CSV or Excel with optional structure images

Export Options

• Include all columns: Creates separate Yes/No columns for each PFAS group type

Example Input Formats

SMILES Examples:

# PFOA (Perfluorooctanoic acid)
C(=O)(C(C(C(C(C(C(C(F)(F)F)(F)F)(F)F)(F)F)(F)F)(F)F)(F)F)O

# PFOS (Perfluorooctanesulfonic acid)  
C(C(C(C(C(C(C(C(F)(F)S(=O)(=O)O)(F)F)(F)F)(F)F)(F)F)(F)F)(F)F)(F)(F)F

# 6:2 FTOH
C(C(C(C(C(C(F)(F)F)(F)F)(F)F)(F)F)(F)F)(F)(F)CCO
                    

CSV File Structure:

Name,SMILES,CAS,Category
PFOA,C(=O)(C(C(...))O,335-67-1,PFCA
PFOS,C(C(C(...))F,1763-23-1,PFSA
GenX,C(C(C(OC(...))O,13252-13-6,PFECA
                    

Keyboard Shortcuts

• Ctrl+Enter: Analyze molecules (when text area is focused)

Troubleshooting

🔧 Key Functions

matchAllSmarts(mol, smartsDict)

Matches all SMARTS patterns from a group's definition and checks minimum count requirements.

/**
 * Match all SMARTS patterns from a group's smarts dictionary
 * Returns Set of all atoms that match any SMARTS pattern
 */
function matchAllSmarts(mol, smartsDict) {
    if (!smartsDict || typeof smartsDict !== 'object') {
        return null;
    }
    
    const allMatchedAtoms = new Set();
    
    for (const [smartsPattern, minCount] of Object.entries(smartsDict)) {
        let pattern = RDKit.get_qmol(smartsPattern);
        const matchesJson = mol.get_substruct_matches(pattern);
        pattern.delete();
        
        // Check if we have at least minCount matches
        if (matches.length < minCount) {
            return null; // Not enough matches
        }
        
        // Add all matched atoms to set
        for (const match of matches) {
            for (const atomIdx of match.atoms) {
                allMatchedAtoms.add(atomIdx);
            }
        }
    }
    
    return allMatchedAtoms.size > 0 ? allMatchedAtoms : null;
}

connectedComponents(graph, subset)

Finds connected components in a molecular graph using BFS (Breadth-First Search).

/**
 * Find connected components in a molecular graph using BFS
 * Takes a graph and a subset of node indices
 * Returns array of Sets (each Set is a component)
 */
function connectedComponents(graph, subset) {
    const subsetSet = new Set(subset);
    const visited = new Set();
    const components = [];
    
    // BFS to find each connected component
    for (const startNode of subsetSet) {
        if (visited.has(startNode)) continue;
        
        const component = new Set();
        const queue = [startNode];
        
        while (queue.length > 0) {
            const node = queue.shift();
            const neighbors = graph.edges.get(node) || [];
            
            for (const edge of neighbors) {
                const neighborIdx = edge.neighbor; // Fixed: was edge.to
                if (subsetSet.has(neighborIdx) && !visited.has(neighborIdx)) {
                    visited.add(neighborIdx);
                    component.add(neighborIdx);
                    queue.push(neighborIdx);
                }
            }
        }
        
        components.push(component);
    }
    
    return components;
}

isWithinDistance (Distance-2 Connectivity)

Checks if a matched atom is within a specified distance of a fluorinated component using BFS.

/**
 * Check if atom is within distance N of a component using BFS
 * This allows functional groups 2 bonds away from fluorinated chains
 * to be correctly associated with those chains
 */
function isWithinDistance(startAtom, component, graph, maxDistance) {
    if (!graph || !graph.edges) return false;
    
    const visited = new Set([startAtom]);
    let queue = [{ atom: startAtom, distance: 0 }];
    
    while (queue.length > 0) {
        const { atom, distance } = queue.shift();
        
        if (component.has(atom)) {
            return true; // Found connection!
        }
        
        if (distance < maxDistance) {
            const neighbors = graph.edges.get(atom) || [];
            for (const edge of neighbors) {
                if (!visited.has(edge.to)) {
                    visited.add(edge.to);
                    queue.push({ atom: edge.to, distance: distance + 1 });
                }
            }
        }
    }
    
    return false;
}

⚖️ Python vs JavaScript Implementation

Comparison of key differences between the Python reference implementation and this JavaScript port.

🔍 JS vs Python: Behaviour Summary

This tab summarises how closely this JavaScript port follows the Python PFASGroups reference implementation, which changes were made during the porting/parity work, and in which situations the results can still differ.

Changes implemented in this JavaScript port

• Shared PFAS group definitions: JavaScript reads the same PFAS group JSON definitions as Python for IDs 1–73, including SMARTS patterns, formula constraints and component types.
• Groups 18 (Perfluoroalkenes) and 19 (Hydrofluoroolefins): Their SMARTS patterns, distance limits (max_dist_from_CF) and linker settings were aligned exactly with the Python configuration to avoid inconsistent classification of double-bonded systems.
• Universal component merging: All fluorinated atoms from different pathway definitions are merged before computing connected components, matching the Python behaviour on branched or overlapping chains.
• Distance-2 connectivity: Functional groups up to two bonds away from a fluorinated component are associated with that component, reproducing the Python adjacency criterion.
• Graph edge handling: The connected‐component routine was corrected to follow the same neighbour semantics as the Python NetworkX graph, preventing artificial fragmentation.
• Perfluoro vs polyfluoro overlap handling: When perfluoroalkyl and polyfluoroalkyl components describe the same atom set, only the polyfluoro component is kept, mirroring Python’s preference for the more general class.

Where results can still differ from Python

Practical guidance

• Use this JavaScript analyzer for quick screening, exploration and educational purposes, especially when Python/RDKit are not available.
• For regulatory, inventory or production workflows where exact reproducibility is critical, prefer the Python PFASGroups package as the reference implementation.
• When results differ slightly between Python and JavaScript, differences are most likely in a small number of generic functional groups rather than in the presence/absence of a PFAS scaffold.