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/StringUtils.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>
 
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<std::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 std::string& irt_trafo_out = "",
      const std::string& irt_mzml_out = "",
      Size debug_level = 0
    );
 
    OpenSwath::LightTargetedExperiment loadIrtExperimentFromFile_(
      const std::string& irt_file_path,
      const std::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 std::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
    std::string linear_irt_file_;
    std::string nonlinear_irt_file_;
    // Run-specific iRT file lists (positional mapping: nth entry -> nth run)
    std::vector<std::string> linear_irt_files_list_;
    std::vector<std::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
    std::string linear_outlier_detection_;
 
    // Nonlinear Calibration Parameters
    std::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_;
    double min_rt_window_;
    double max_rt_window_;
 
    // 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 std::string& irt_trafo_out,
      const std::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 std::string& irt_trafo_out,
      const std::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