CalibrationWorkflow.h

Go to the documentation of this file.

// Copyright (c) 2002-present, OpenMS Inc. -- EKU Tuebingen, ETH Zurich, and FU Berlin
// SPDX-License-Identifier: BSD-3-Clause
//
// --------------------------------------------------------------------------
// $Maintainer: Justin Sing $
// $Authors: Justin Sing $
// --------------------------------------------------------------------------
 
#pragma once
 
#include <OpenMS/DATASTRUCTURES/DefaultParamHandler.h>
#include <OpenMS/CONCEPT/ProgressLogger.h>
#include <OpenMS/DATASTRUCTURES/Param.h>
#include <OpenMS/DATASTRUCTURES/String.h>
#include <OpenMS/ANALYSIS/OPENSWATH/OpenSwathWorkflow.h>
#include <OpenMS/ANALYSIS/OPENSWATH/OpenSwathHelper.h>
#include <OpenMS/OPENSWATHALGO/DATAACCESS/TransitionExperiment.h>
#include <OpenMS/OPENSWATHALGO/DATAACCESS/SwathMap.h>
#include <OpenMS/ANALYSIS/MAPMATCHING/TransformationDescription.h>
#include <OpenMS/APPLICATIONS/OpenSwathBase.h>
 
namespace OpenMS
{
  enum class IrtStrategy 
  {
    NULL_TRANSFORMATION,
    STATIC_FILES,     
    SAMPLE_ONCE,        
    SAMPLE_PER_RUN,   
    RUN_SPECIFIC      
  };
 
  class OPENMS_DLLAPI CalibrationWorkflow : 
    public DefaultParamHandler,
    public ProgressLogger
  {
  public:
    struct CalibrationResult 
    {
      // Transformation
      TransformationDescription rt_trafo;
      TransformationDescription im_trafo;
      
      // Estimated Extraction Windows
      double ms2_mz_window_ppm{-1.0};
      double ms2_im_window{-1.0};
      double ms1_mz_window_ppm{-1.0};
      double ms1_im_window{-1.0};
      double estimated_rt_window{-1.0};
    };
    
    struct IrtExperiments
    {
      OpenSwath::LightTargetedExperiment linear_irt;
      OpenSwath::LightTargetedExperiment nonlinear_irt;
      IrtStrategy strategy{IrtStrategy::STATIC_FILES};
      bool is_prepared{false};
    };
 
    CalibrationWorkflow();
    
    ~CalibrationWorkflow() override;
    
    IrtStrategy determineIrtStrategy(
      const OpenSwath::LightTargetedExperiment& full_transition_exp,
      size_t num_runs = 1
    ) const;
    
    IrtExperiments prepareIrtExperiments(
      IrtStrategy strategy,
      const OpenSwath::LightTargetedExperiment& full_transition_exp,
      const std::vector<String>& priority_peptides,
      size_t run_index = 0,
      const IrtExperiments* cached_irts = nullptr
    );
 
    CalibrationResult performCalibration(
      std::vector<OpenSwath::SwathMap>& swath_maps,
      OpenSwath::LightTargetedExperiment& transition_exp,
      ChromExtractParams& cp,
      ChromExtractParams& cp_ms1,
      const IrtExperiments& irt_experiments,
      const Param& feature_finder_param,
      const ChromExtractParams& cp_irt,
      const Param& irt_detection_param,
      const Param& calibration_param,
      const Param& mrm_mapping_param,
      bool pasef = false,
      bool load_into_memory = false,
      const String& irt_trafo_out = "",
      const String& irt_mzml_out = "",
      Size debug_level = 0
    );
 
    OpenSwath::LightTargetedExperiment loadIrtExperimentFromFile_(
      const String& irt_file_path,
      const String& label) const;
 
    TransformationDescription performRTNormalization(
      const OpenSwath::LightTargetedExperiment& irt_transitions,
      std::vector< OpenSwath::SwathMap > & swath_maps,
      TransformationDescription& im_trafo,
      double min_rsq,
      double min_coverage,
      const Param& feature_finder_param,
      const ChromExtractParams& cp_irt,
      const Param& irt_detection_param,
      const Param& calibration_param,
      const Param& mrm_mapping_param,
      const String& irt_mzml_out,
      Size debug_level,
      bool pasef = false,
      bool load_into_memory = false);
 
    TransformationDescription doDataNormalization_(
      const OpenSwath::LightTargetedExperiment& targeted_exp,
      const std::vector< OpenMS::MSChromatogram >& chromatograms,
      TransformationDescription& im_trafo,
      std::vector< OpenSwath::SwathMap > & swath_maps,
      double min_rsq,
      double min_coverage,
      const Param& default_ffparam,
      const Param& irt_detection_param,
      const Param& calibration_param,
      const bool pasef);
 
    double getEstimatedMzWindow() const { return estimated_mz_window_; }
 
    double getEstimatedImWindow() const { return estimated_im_window_; }
 
    double getEstimatedMs1MzWindow() const { return estimated_ms1_mz_window_; }
 
    double getEstimatedMs1ImWindow() const { return estimated_ms1_im_window_; }
 
  private:
 
 
    void updateMembers_() override;
 
    // Estimated windows stored during calibration (internal caching)
    double estimated_mz_window_{-1.0};
    double estimated_im_window_{-1.0};
    double estimated_ms1_mz_window_{-1.0};
    double estimated_ms1_im_window_{-1.0};
    
 
    
    // iRT File Parameters
    String linear_irt_file_;
    String nonlinear_irt_file_;
    // Run-specific iRT file lists (positional mapping: nth entry -> nth run)
    std::vector<String> linear_irt_files_list_;
    std::vector<String> nonlinear_irt_files_list_;
    
    // Auto-iRT Sampling Parameters
    bool auto_irt_enabled_;
    int auto_irt_irt_bins_;
    int auto_irt_irt_peptides_per_bin_;
    int auto_irt_irt_seed_;
    int auto_irt_irt_bins_nonlinear_;
    int auto_irt_irt_peptides_per_bin_nonlinear_;
    double auto_irt_linear_top_fraction_;
    double auto_irt_nonlinear_top_fraction_;
    
    // Linear Calibration Parameters
    String linear_outlier_detection_;
      
    // Nonlinear Calibration Parameters
    String nonlinear_outlier_detection_;
    
    // Window Estimation Parameters
    bool windows_estimate_rt_;
    bool windows_estimate_mz_;
    bool windows_estimate_im_;
    double windows_rt_percentile_;
    double rt_estimation_padding_factor_;
    
    // Quality Control Parameters
    double min_rsq_;
    double min_coverage_;
    
    
 
    
    CalibrationResult performLinearCalibration_(
      std::vector<OpenSwath::SwathMap>& swath_maps,
      const IrtExperiments& irt_experiments,
      const Param& feature_finder_param,
      const ChromExtractParams& cp_irt,
      const Param& irt_detection_param,
      const Param& calibration_param,
      const Param& mrm_mapping_param,
      bool pasef,
      bool load_into_memory,
      const String& irt_trafo_out,
      const String& irt_mzml_out,
      Size debug_level);
    
    CalibrationResult performLinearThenNonlinearCalibration_(
      std::vector<OpenSwath::SwathMap>& swath_maps,
      const IrtExperiments& irt_experiments,
      const Param& feature_finder_param,
      const ChromExtractParams& cp_irt,
      const Param& irt_detection_param,
      const Param& calibration_param,
      const Param& mrm_mapping_param,
      bool pasef,
      bool load_into_memory,
      const String& irt_trafo_out,
      const String& irt_mzml_out,
      Size debug_level);
      
    void applyEstimatedWindows_(
      const CalibrationResult& result,
      ChromExtractParams& cp,
      ChromExtractParams& cp_ms1, 
      bool pasef,
      bool use_ms1_im) const;
      
    void applyWindow_(
      const char* label,
      double estimate,
      double& dst_param,
      double user_value,
      bool applicable = true,
      bool commit = true) const;
      
    inline bool isValidWindow_(double v, double min_positive = 1e-9) const noexcept;
  };
 
} // namespace OpenMS