LucXor (LuciPHOr2) Algorithm Documentation

June 26, 2026 · View on GitHub

Overview

LucXor is a Python implementation of the LuciPHOr2 algorithm for accurate post-translational modification (PTM) localization with probabilistic scoring and false localization rate (FLR) estimation. It provides a comprehensive two-stage workflow for confident PTM site assignment with statistical validation.

Algorithm Description

Core Principles

  1. Two-Stage Processing: Implements the complete LuciPHOr2 workflow with FLR estimation
  2. Probabilistic Scoring: Uses statistical models for site localization confidence
  3. FLR Calculation: Provides accurate false localization rate estimation
  4. Multi-threading: Parallel processing for improved performance

Mathematical Foundation

LucXor implements a sophisticated two-stage approach:

Stage 1: FLR Estimation (RN=0)

  • Process all PSMs with both real and decoy permutations
  • Calculate delta scores for all permutations
  • Estimate false localization rates based on decoy distributions

Stage 2: FLR Assignment (RN=1)

  • Re-process PSMs using only real permutations
  • Assign FLR values based on the estimated distributions
  • Generate final localization confidence scores

Key Features

  • Two-stage processing: Complete LuciPHOr2 workflow implementation
  • Multiple fragmentation methods: Support for CID and HCD fragmentation
  • FLR calculation: Accurate false localization rate estimation
  • Multi-threading: Parallel processing for improved performance
  • PyOpenMS integration: Seamless integration with OpenMS ecosystem

Implementation Details

Parameters

ParameterDefaultDescription
fragment_method"CID"Fragmentation method (CID or HCD)
fragment_mass_tolerance0.5Fragment mass tolerance
fragment_mass_unit"Da"Tolerance units (Da or ppm)
min_mz150.0Minimum m/z value to consider
target_modifications["Phospho (S)", "Phospho (T)", "Phospho (Y)"]Target modifications
neutral_losses["sty -H3PO4 -97.97690"]Neutral loss definitions
decoy_mass79.966331Mass for decoy generation
max_charge_state5Maximum charge state
max_peptide_length40Maximum peptide length
max_num_perm16384Maximum permutations
modeling_score_threshold0.95Minimum score for modeling
min_num_psms_model50Minimum PSMs for modeling
threads4Number of threads
rt_tolerance0.01Retention time tolerance

Workflow

Stage 1: FLR Estimation

  1. PSM Processing: Process all PSMs with real and decoy permutations
  2. Delta Score Calculation: Calculate delta scores for all permutations
  3. FLR Estimation: Estimate false localization rates from decoy distributions
  4. Model Building: Build statistical models for FLR calculation

Stage 2: FLR Assignment

  1. PSM Re-processing: Re-process PSMs with only real permutations
  2. FLR Assignment: Assign FLR values based on estimated distributions
  3. Score Calculation: Calculate final localization scores
  4. Result Generation: Generate final results with confidence metrics

Advanced Features

FLR Calculator

class FLRCalculator:
    """
    Calculates false localization rates using decoy distributions.
    """
    def __init__(self, min_delta_score=0.1, min_psms_per_charge=50):
        self.min_delta_score = min_delta_score
        self.min_psms_per_charge = min_psms_per_charge
    
    def calculate_flr_estimates(self, psms):
        """Calculate FLR estimates from decoy distributions."""
        # Implementation details...
    
    def assign_flr_to_psms(self, psms):
        """Assign FLR values to PSMs based on estimates."""
        # Implementation details...

Core Processor

class CoreProcessor:
    """
    Main processor for scoring PSMs and calculating FLR.
    """
    def process_all_psms(self):
        """Process all PSMs using two-stage workflow."""
        # Stage 1: Calculate FLR estimates
        self._process_psms_stage1()
        
        # Stage 2: Assign FLR values
        self._process_psms_stage2()

PSM Handling

class PSM:
    """
    Peptide Spectrum Match with localization scoring.
    """
    def process(self, config_dict):
        """Process PSM with real and decoy permutations."""
        # Implementation details...
    
    def process_stage2(self, config_dict):
        """Process PSM with only real permutations."""
        # Implementation details...

Usage Examples

Command Line Interface

# Basic usage
onsite lucxor -in spectra.mzML -id identifications.idparquet -out results.idparquet

# With custom parameters
onsite lucxor -in spectra.mzML -id identifications.idparquet -out results.idparquet \
    --fragment-method HCD \
    --fragment-mass-tolerance 0.5 \
    --fragment-mass-unit Da \
    --threads 8 \
    --debug

Python API

from onsite.lucxor.cli import PyLuciPHOr2
from onsite.lucxor.psm import PSM
from onsite.lucxor.peptide import Peptide
from onsite.lucxor.models import CIDModel, HCDModel
from onsite.lucxor.spectrum import Spectrum
from onsite.lucxor.flr import FLRCalculator

# Initialize the main processor
processor = PyLuciPHOr2()

# The processor will parse command line arguments automatically
# For programmatic use, you can also use the core components directly

Advanced Usage

from onsite.lucxor.core import CoreProcessor
from onsite.lucxor.config import LucXorConfig
from onsite.lucxor.psm import PSM
from onsite.lucxor.spectrum import Spectrum

# Custom configuration
config = LucXorConfig()
config.fragment_method = "HCD"
config.fragment_mass_tolerance = 0.5
config.fragment_mass_unit = "Da"
config.threads = 4

# Initialize processor
processor = CoreProcessor(config)

# Process PSMs
psm_list = [PSM(...)]  # Your PSM objects
spectrum_map = {...}   # Your spectrum mapping
results = processor.process_all_psms(psm_list, spectrum_map)

Performance Characteristics

Computational Complexity

  • Time Complexity: O(n²) where n is the number of permutations
  • Space Complexity: O(n) for storing permutations and spectra
  • Parallelization: Supports multi-threading for improved performance

Performance Metrics

  • Processing Speed: ~100-1000 PSMs/second (depending on data complexity)
  • Memory Usage: ~1-2 GB for typical datasets
  • Accuracy: High accuracy with FLR-based confidence estimation

Optimization Features

  1. Multi-threading: Automatic thread optimization based on PSM count
  2. Memory Efficiency: Streaming processing for large datasets
  3. Scalability: Handles datasets with thousands of PSMs
  4. Caching: Efficient caching of probability calculations

Output Format

LucXor Output

The tool generates an idparquet file containing:

  • Luciphor_delta_score: Main localization score
  • Luciphor_pep_score: Peptide identification score
  • Luciphor_global_flr: Global false localization rate
  • Luciphor_local_flr: Local false localization rate

CSV Output

SpectrumID,Peptide,ModifiedPeptide,Score,DeltaScore,GlobalFLR,LocalFLR,IsDecoy
1,PEPTIDE,PEPTIDE(Phospho),0.95,0.85,0.05,0.02,0
2,PEPTIDE,PEPTIDE(Phospho),0.90,0.80,0.10,0.05,0

Limitations

  1. Memory Requirements: Can be memory-intensive for large datasets
  2. Computational Cost: Two-stage processing can be time-consuming
  3. FLR Dependencies: Requires sufficient PSMs for accurate FLR estimation
  4. Fragment Quality: Requires high-quality MS/MS spectra

Troubleshooting

Common Issues

  1. Memory Errors: Reduce max_peptide_length or use fewer threads
  2. Slow Processing: Increase number of threads or reduce fragment tolerance
  3. Poor Results: Check fragment tolerance settings and data quality
  4. FLR Issues: Ensure sufficient PSMs for modeling (minimum 50 recommended)

Optimization Tips

  1. Thread Count: Adjust based on available CPU cores
  2. Fragment Tolerance: Use appropriate tolerance for your instrument
  3. Peptide Length: Filter very long peptides if not needed
  4. Modeling Threshold: Adjust based on data quality

References

Original Publications

LuciPHOr (2013)

Fermin, D., Walmsley, S. J., Gingras, A. C., Choi, H., & Nesvizhskii, A. I. (2013). LuciPHOr: algorithm for phosphorylation site localization with false localization rate estimation using modified target-decoy approach. Molecular & Cellular Proteomics, 12(11), 3409-3419.

DOI: 10.1074/mcp.M113.028928

LuciPHOr2 (2015)

Fermin, D., Avtonomov, D., Choi, H., & Nesvizhskii, A. I. (2015). LuciPHOr2: site localization of generic post-translational modifications from tandem mass spectrometry data. Bioinformatics, 31(7), 1141-1143.

DOI: 10.1093/bioinformatics/btu788

Key Features of Original Implementation

  1. FLR Estimation: Accurate false localization rate calculation
  2. Two-Stage Processing: Complete workflow with validation
  3. Generic PTM Support: Works with various post-translational modifications
  4. Statistical Validation: Robust statistical framework
  • AScore: Alternative probability-based approach
  • PhosphoRS: Compomics-style scoring method
  • Mascot Delta Score: Similar concept in database search engines

Implementation Notes

Differences from Original

  1. Python Implementation: Native Python port of LuciPHOr2
  2. PyOpenMS Integration: Seamless integration with OpenMS ecosystem
  3. Enhanced Multi-threading: Improved parallel processing
  4. Memory Optimization: Efficient memory usage for large datasets

Future Improvements

  1. Machine Learning: Integration of ML-based scoring
  2. Real-time Processing: Streaming analysis capabilities
  3. Cross-linking: Extension to cross-linked peptides
  4. Quantification: Integration with quantification methods

Algorithm Comparison

FeatureAScorePhosphoRSLucXor
Statistical FrameworkBinomialBinomialFLR-based
Site-Determining IonsYesYesYes
FLR EstimationNoNoYes
Two-Stage ProcessingNoNoYes
Decoy SupportOptionalOptionalRequired
Multi-threadingYesLimitedYes
Memory UsageLowMediumHigh
AccuracyHighHighVery High

Best Practices

  1. Data Quality: Ensure high-quality MS/MS spectra
  2. Fragment Tolerance: Use appropriate tolerance for your instrument
  3. Thread Count: Optimize based on available resources
  4. FLR Thresholds: Set appropriate thresholds for your application
  5. Validation: Use decoy sites for validation in research settings