corems.mass_spectra.factory.lc_class

   1from pathlib import Path
   2
   3import numpy as np
   4import pandas as pd
   5import warnings
   6import matplotlib.pyplot as plt
   7
   8from corems.encapsulation.factory.parameters import LCMSParameters
   9from corems.mass_spectra.calc.lc_calc import LCCalculations, PHCalculations
  10from corems.molecular_id.search.lcms_spectral_search import LCMSSpectralSearch
  11from corems.mass_spectrum.input.numpyArray import ms_from_array_profile, ms_from_array_centroid
  12from corems.mass_spectra.calc.lc_calc import find_closest
  13
  14
  15class MassSpectraBase:
  16    """Base class for mass spectra objects.
  17
  18    Parameters
  19    -----------
  20    file_location : str or Path
  21        The location of the file containing the mass spectra data.
  22    analyzer : str, optional
  23        The type of analyzer used to generate the mass spectra data. Defaults to 'Unknown'.
  24    instrument_label : str, optional
  25        The type of instrument used to generate the mass spectra data. Defaults to 'Unknown'.
  26    sample_name : str, optional
  27        The name of the sample; defaults to the file name if not provided to the parser. Defaults to None.
  28    spectra_parser : object, optional
  29        The spectra parser object used to create the mass spectra object. Defaults to None.
  30
  31    Attributes
  32    -----------
  33    spectra_parser_class : class
  34        The class of the spectra parser used to create the mass spectra object.
  35    file_location : str or Path
  36        The location of the file containing the mass spectra data.
  37    sample_name : str
  38        The name of the sample; defaults to the file name if not provided to the parser.
  39    analyzer : str
  40        The type of analyzer used to generate the mass spectra data. Derived from the spectra parser.
  41    instrument_label : str
  42        The type of instrument used to generate the mass spectra data. Derived from the spectra parser.
  43    _scan_info : dict
  44        A dictionary containing the scan data with columns for scan number, scan time, ms level, precursor m/z,
  45        scan text, and scan window (lower and upper).
  46        Associated with the property scan_df, which returns a pandas DataFrame or can set this attribute from a pandas DataFrame.
  47    _ms : dict
  48        A dictionary containing mass spectra for the dataset, keys of dictionary are scan numbers. Initialized as an empty dictionary.
  49    _ms_unprocessed: dictionary of pandas.DataFrames or None
  50        A dictionary of unprocssed mass spectra data, as an (optional) intermediate data product for peak picking.
  51        Key is ms_level, and value is dataframe with columns for scan number, m/z, and intensity. Default is None.
  52
  53    Methods
  54    --------
  55    * add_mass_spectra(scan_list, spectrum_mode: str = 'profile', use_parser = True, auto_process=True).
  56        Add mass spectra (or singlel mass spectrum) to _ms slot, from a list of scans
  57    * get_time_of_scan_id(scan).
  58        Returns the scan time for the specified scan number.
  59    """
  60
  61    def __init__(
  62        self,
  63        file_location,
  64        analyzer="Unknown",
  65        instrument_label="Unknown",
  66        sample_name=None,
  67        spectra_parser=None,
  68    ):
  69        if isinstance(file_location, str):
  70            file_location = Path(file_location)
  71        else:
  72            file_location = file_location
  73        if not file_location.exists():
  74            raise FileExistsError("File does not exist: " + str(file_location))
  75
  76        if sample_name:
  77            self.sample_name = sample_name
  78        else:
  79            self.sample_name = file_location.stem
  80
  81        self.file_location = file_location
  82        self.analyzer = analyzer
  83        self.instrument_label = instrument_label
  84
  85        # Add the spectra parser class to the object if it is not None
  86        if spectra_parser is not None:
  87            self.spectra_parser_class = spectra_parser.__class__
  88            # Check that spectra_pasrser.sample_name is same as sample_name etc, raise warning if not
  89            if (
  90                self.sample_name is not None
  91                and self.sample_name != self.spectra_parser.sample_name
  92            ):
  93                warnings.warn(
  94                    "sample_name provided to MassSpectraBase object does not match sample_name provided to spectra parser object",
  95                    UserWarning,
  96                )
  97            if self.analyzer != self.spectra_parser.analyzer:
  98                warnings.warn(
  99                    "analyzer provided to MassSpectraBase object does not match analyzer provided to spectra parser object",
 100                    UserWarning,
 101                )
 102            if self.instrument_label != self.spectra_parser.instrument_label:
 103                warnings.warn(
 104                    "instrument provided to MassSpectraBase object does not match instrument provided to spectra parser object",
 105                    UserWarning,
 106                )
 107            if self.file_location != self.spectra_parser.file_location:
 108                warnings.warn(
 109                    "file_location provided to MassSpectraBase object does not match file_location provided to spectra parser object",
 110                    UserWarning,
 111                )
 112
 113        # Instantiate empty dictionaries for scan information and mass spectra
 114        self._scan_info = {}
 115        self._ms = {}
 116        self._ms_unprocessed = {}
 117
 118    @property
 119    def spectra_parser(self):
 120        """Returns an instance of the spectra parser class."""
 121        return self.spectra_parser_class(self.file_location)
 122
 123    def add_mass_spectrum(self, mass_spec):
 124        """Adds a mass spectrum to the dataset.
 125
 126        Parameters
 127        -----------
 128        mass_spec : MassSpectrum
 129            The corems MassSpectrum object to be added to the dataset.
 130
 131        Notes
 132        -----
 133        This is a helper function for the add_mass_spectra() method, and is not intended to be called directly.
 134        """
 135        # check if mass_spec has a scan_number attribute
 136        if not hasattr(mass_spec, "scan_number"):
 137            raise ValueError(
 138                "Mass spectrum must have a scan_number attribute to be added to the dataset correctly"
 139            )
 140        self._ms[mass_spec.scan_number] = mass_spec
 141
 142    def add_mass_spectra(
 143        self,
 144        scan_list,
 145        spectrum_mode=None,
 146        ms_level=1,
 147        use_parser=True,
 148        auto_process=True,
 149        ms_params=None,
 150    ):
 151        """Add mass spectra to _ms dictionary, from a list of scans or single scan
 152
 153        Notes
 154        -----
 155        The mass spectra will inherit the mass_spectrum, ms_peak, and molecular_search parameters from the LCMSBase object.
 156
 157
 158        Parameters
 159        -----------
 160        scan_list : list of ints
 161            List of scans to use to populate _ms slot
 162        spectrum_mode : str or None
 163            The spectrum mode to use for the mass spectra.
 164            If None, method will use the spectrum mode from the spectra parser to ascertain the spectrum mode (this allows for mixed types).
 165            Defaults to None.
 166        ms_level : int, optional
 167            The MS level to use for the mass spectra.
 168            This is used to pass the molecular_search parameters from the LCMS object to the individual MassSpectrum objects.
 169            Defaults to 1.
 170        using_parser : bool
 171            Whether to use the mass spectra parser to get the mass spectra.  Defaults to True.
 172        auto_process : bool
 173            Whether to auto-process the mass spectra.  Defaults to True.
 174        ms_params : MSParameters or None
 175            The mass spectrum parameters to use for the mass spectra.  If None, uses the globally set MSParameters.
 176
 177        Raises
 178        ------
 179        TypeError
 180            If scan_list is not a list of ints
 181        ValueError
 182            If polarity is not 'positive' or 'negative'
 183            If ms_level is not 1 or 2
 184        """
 185
 186        # check if scan_list is a list or a single int; if single int, convert to list
 187        if isinstance(scan_list, int):
 188            scan_list = [scan_list]
 189        if not isinstance(scan_list, list):
 190            raise TypeError("scan_list must be a list of integers")
 191        for scan in scan_list:
 192            if not isinstance(scan, int):
 193                raise TypeError("scan_list must be a list of integers")
 194
 195        # set polarity to -1 if negative mode, 1 if positive mode (for mass spectrum creation)
 196        if self.polarity == "negative":
 197            polarity = -1
 198        elif self.polarity == "positive":
 199            polarity = 1
 200        else:
 201            raise ValueError(
 202                "Polarity not set for dataset, must be a either 'positive' or 'negative'"
 203            )
 204
 205        # is not using_parser, check that ms1 and ms2 are not None
 206        if not use_parser:
 207            if ms_level not in self._ms_unprocessed.keys():
 208                raise ValueError(
 209                    "ms_level {} not found in _ms_unprocessed dictionary".format(
 210                        ms_level
 211                    )
 212                )
 213
 214        scan_list = list(set(scan_list))
 215        scan_list.sort()
 216        if not use_parser:
 217            if self._ms_unprocessed[ms_level] is None:
 218                raise ValueError(
 219                    "No unprocessed data found for ms_level {}".format(ms_level)
 220                )
 221            if (
 222                len(
 223                    np.setdiff1d(
 224                        scan_list, self._ms_unprocessed[ms_level].scan.tolist()
 225                    )
 226                )
 227                > 0
 228            ):
 229                raise ValueError(
 230                    "Not all scans in scan_list are present in the unprocessed data"
 231                )
 232            # Prepare the ms_df for parsing
 233            ms_df = self._ms_unprocessed[ms_level].copy().set_index("scan", drop=False)
 234
 235        if use_parser:
 236            # Use batch function to get all mass spectra at once
 237            if spectrum_mode is None:
 238                # get spectrum mode from _scan_info for each scan
 239                spectrum_modes = [self.scan_df.loc[scan, "ms_format"] for scan in scan_list]
 240                spectrum_mode_batch = spectrum_modes[0] if len(set(spectrum_modes)) == 1 else None
 241            else:
 242                spectrum_mode_batch = spectrum_mode
 243            
 244            ms_list = self.spectra_parser.get_mass_spectra_from_scan_list(
 245                scan_list=scan_list,
 246                spectrum_mode=spectrum_mode_batch,
 247                auto_process=False,
 248            )
 249            
 250            # Process each mass spectrum
 251            for i, scan in enumerate(scan_list):
 252                ms = ms_list[i] if i < len(ms_list) else None
 253                if ms is not None:
 254                    if ms_params is not None:
 255                        ms.parameters = ms_params
 256                    ms.scan_number = scan
 257                    if auto_process:
 258                        ms.process_mass_spec()
 259                    self.add_mass_spectrum(ms)
 260        else:
 261            # Original non-parser logic remains unchanged
 262            for scan in scan_list:
 263                ms = None
 264                if spectrum_mode is None:
 265                    # get spectrum mode from _scan_info
 266                    spectrum_mode_scan = self.scan_df.loc[scan, "ms_format"]
 267                else:
 268                    spectrum_mode_scan = spectrum_mode
 269                
 270                my_ms_df = ms_df.loc[scan]
 271                if spectrum_mode_scan == "profile":
 272                    # Check this - it might be better to use the MassSpectrumProfile class to instantiate the mass spectrum
 273                    ms = ms_from_array_profile(
 274                        my_ms_df.mz,
 275                        my_ms_df.intensity,
 276                        self.file_location,
 277                        polarity=polarity,
 278                        auto_process=False,
 279                    )
 280                else:
 281                   ms = ms_from_array_centroid(
 282                        mz = my_ms_df.mz,
 283                        abundance = my_ms_df.intensity,
 284                        rp = [np.nan] * len(my_ms_df.mz),
 285                        s2n = [np.nan] * len(my_ms_df.mz),
 286                        dataname = self.file_location,
 287                        polarity=polarity,
 288                        auto_process=False,
 289                    )
 290
 291                # Set the mass spectrum parameters, auto-process if auto_process is True, and add to the dataset
 292                if ms is not None:
 293                    if ms_params is not None:
 294                        ms.parameters = ms_params
 295                    ms.scan_number = scan
 296                    if auto_process:
 297                        ms.process_mass_spec()
 298                    self.add_mass_spectrum(ms)
 299
 300    def get_time_of_scan_id(self, scan):
 301        """Returns the scan time for the specified scan number.
 302
 303        Parameters
 304        -----------
 305        scan : int
 306            The scan number of the desired scan time.
 307
 308        Returns
 309        --------
 310        float
 311            The scan time for the specified scan number (in minutes).
 312
 313        Raises
 314        ------
 315        ValueError
 316            If no scan time is found for the specified scan number.
 317        """
 318        # Check if _retenion_time_list is empty and raise error if so
 319        if len(self._retention_time_list) == 0:
 320            raise ValueError("No retention times found in dataset")
 321        rt = self._retention_time_list[self._scans_number_list.index(scan)]
 322        return rt
 323
 324    @property
 325    def scan_df(self):
 326        """
 327        pandas.DataFrame : A pandas DataFrame containing the scan info data with columns for scan number, scan time, ms level, precursor m/z, scan text, and scan window (lower and upper).
 328        """
 329        scan_df = pd.DataFrame.from_dict(self._scan_info)
 330        return scan_df
 331        
 332    @property
 333    def ms(self):
 334        """
 335        dictionary : contains the key associated with mass spectra and values are the associated MassSpecProfiles
 336        """
 337        return self._ms
 338
 339    
 340    @scan_df.setter
 341    def scan_df(self, df):
 342        """
 343        Sets the scan data for the dataset.
 344
 345        Parameters
 346        -----------
 347        df : pandas.DataFrame
 348            A pandas DataFrame containing the scan data with columns for scan number, scan time, ms level,
 349            precursor m/z, scan text, and scan window (lower and upper).
 350        """
 351        self._scan_info = df.to_dict()
 352
 353    def __getitem__(self, scan_number):
 354        return self._ms.get(scan_number)
 355
 356
 357class LCMSBase(MassSpectraBase, LCCalculations, PHCalculations, LCMSSpectralSearch):
 358    """A class representing a liquid chromatography-mass spectrometry (LC-MS) data object.
 359
 360    This class is not intended to be instantiated directly, but rather to be instantiated by an appropriate mass spectra parser using the get_lcms_obj() method.
 361
 362    Parameters
 363    -----------
 364    file_location : str or Path
 365        The location of the file containing the mass spectra data.
 366    analyzer : str, optional
 367        The type of analyzer used to generate the mass spectra data. Defaults to 'Unknown'.
 368    instrument_label : str, optional
 369        The type of instrument used to generate the mass spectra data. Defaults to 'Unknown'.
 370    sample_name : str, optional
 371        The name of the sample; defaults to the file name if not provided to the parser. Defaults to None.
 372    spectra_parser : object, optional
 373        The spectra parser object used to create the mass spectra object. Defaults to None.
 374
 375    Attributes
 376    -----------
 377    polarity : str
 378        The polarity of the ionization mode used for the dataset.
 379    _parameters : LCMSParameters
 380        The parameters used for all methods called on the LCMSBase object. Set upon instantiation from LCMSParameters.
 381    _retention_time_list : numpy.ndarray
 382        An array of retention times for the dataset.
 383    _scans_number_list : list
 384        A list of scan numbers for the dataset.
 385    _tic_list : numpy.ndarray
 386        An array of total ion current (TIC) values for the dataset.
 387    eics : dict
 388        A dictionary containing extracted ion chromatograms (EICs) for the dataset.
 389        Key is the mz of the EIC. Initialized as an empty dictionary.
 390    mass_features : dictionary of LCMSMassFeature objects
 391        A dictionary containing mass features for the dataset.
 392        Key is mass feature ID. Initialized as an empty dictionary.
 393    spectral_search_results : dictionary of MS2SearchResults objects
 394        A dictionary containing spectral search results for the dataset.
 395        Key is scan number : precursor mz. Initialized as an empty dictionary.
 396
 397    Methods
 398    --------
 399    * get_parameters_json().
 400        Returns the parameters used for the LC-MS analysis in JSON format.
 401    * add_associated_ms2_dda(add_to_lcmsobj=True, auto_process=True, use_parser=True)
 402        Adds which MS2 scans are associated with each mass feature to the
 403        mass_features dictionary and optionally adds the MS2 spectra to the _ms dictionary.
 404    * add_associated_ms1(add_to_lcmsobj=True, auto_process=True, use_parser=True)
 405        Adds the MS1 spectra associated with each mass feature to the
 406        mass_features dictionary and adds the MS1 spectra to the _ms dictionary.
 407    * mass_features_to_df()
 408        Returns a pandas dataframe summarizing the mass features in the dataset.
 409    * set_tic_list_from_data(overwrite=False)
 410        Sets the TIC list from the mass spectrum objects within the _ms dictionary.
 411    * set_retention_time_from_data(overwrite=False)
 412        Sets the retention time list from the data in the _ms dictionary.
 413    * set_scans_number_from_data(overwrite=False)
 414        Sets the scan number list from the data in the _ms dictionary.
 415    * plot_composite_mz_features(binsize = 1e-4, ph_int_min_thresh = 0.001, mf_plot = True, ms2_plot = True, return_fig = False)
 416        Generates plot of M/Z features comparing scan time vs M/Z value
 417    """
 418
 419    def __init__(
 420        self,
 421        file_location,
 422        analyzer="Unknown",
 423        instrument_label="Unknown",
 424        sample_name=None,
 425        spectra_parser=None,
 426    ):
 427        super().__init__(
 428            file_location, analyzer, instrument_label, sample_name, spectra_parser
 429        )
 430        self.polarity = ""
 431        self._parameters = LCMSParameters()
 432        self._retention_time_list = []
 433        self._scans_number_list = []
 434        self._tic_list = []
 435        self.eics = {}
 436        self.mass_features = {}
 437        self.spectral_search_results = {}
 438
 439    def get_parameters_json(self):
 440        """Returns the parameters stored for the LC-MS object in JSON format.
 441
 442        Returns
 443        --------
 444        str
 445            The parameters used for the LC-MS analysis in JSON format.
 446        """
 447        return self.parameters.to_json()
 448
 449    def remove_unprocessed_data(self, ms_level=None):
 450        """Removes the unprocessed data from the LCMSBase object.
 451
 452        Parameters
 453        -----------
 454        ms_level : int, optional
 455            The MS level to remove the unprocessed data for. If None, removes unprocessed data for all MS levels.
 456
 457        Raises
 458        ------
 459        ValueError
 460            If ms_level is not 1 or 2.
 461
 462        Notes
 463        -----
 464        This method is useful for freeing up memory after the data has been processed.
 465        """
 466        if ms_level is None:
 467            for ms_level in self._ms_unprocessed.keys():
 468                self._ms_unprocessed[ms_level] = None
 469        if ms_level not in [1, 2]:
 470            raise ValueError("ms_level must be 1 or 2")
 471        self._ms_unprocessed[ms_level] = None
 472
 473    def add_associated_ms2_dda(
 474        self,
 475        auto_process=True,
 476        use_parser=True,
 477        spectrum_mode=None,
 478        ms_params_key="ms2",
 479        scan_filter=None,
 480    ):
 481        """Add MS2 spectra associated with mass features to the dataset.
 482
 483        Populates the mass_features ms2_scan_numbers attribute (on mass_features dictionary on LCMSObject)
 484
 485        Parameters
 486        -----------
 487        auto_process : bool, optional
 488            If True, auto-processes the MS2 spectra before adding it to the object's _ms dictionary. Default is True.
 489        use_parser : bool, optional
 490            If True, envoke the spectra parser to get the MS2 spectra. Default is True.
 491        spectrum_mode : str or None, optional
 492            The spectrum mode to use for the mass spectra.  If None, method will use the spectrum mode
 493            from the spectra parser to ascertain the spectrum mode (this allows for mixed types).
 494            Defaults to None. (faster if defined, otherwise will check each scan)
 495        ms_params_key : string, optional
 496            The key of the mass spectrum parameters to use for the mass spectra, accessed from the LCMSObject.parameters.mass_spectrum attribute.
 497            Defaults to 'ms2'.
 498        scan_filter : str
 499            A string to filter the scans to add to the _ms dictionary.  If None, all scans are added.  Defaults to None.
 500            "hcd" will pull out only HCD scans.
 501
 502        Raises
 503        ------
 504        ValueError
 505            If mass_features is not set, must run find_mass_features() first.
 506            If no MS2 scans are found in the dataset.
 507            If no precursor m/z values are found in MS2 scans, not a DDA dataset.
 508        """
 509        # Check if mass_features is set, raise error if not
 510        if self.mass_features is None:
 511            raise ValueError(
 512                "mass_features not set, must run find_mass_features() first"
 513            )
 514
 515        # reconfigure ms_params to get the correct mass spectrum parameters from the key
 516        ms_params = self.parameters.mass_spectrum[ms_params_key]
 517
 518        mf_df = self.mass_features_to_df().copy()
 519        # Find ms2 scans that have a precursor m/z value
 520        ms2_scans = self.scan_df[self.scan_df.ms_level == 2]
 521        ms2_scans = ms2_scans[~ms2_scans.precursor_mz.isna()]
 522        # drop ms2 scans that have no tic
 523        ms2_scans = ms2_scans[ms2_scans.tic > 0]
 524        if ms2_scans is None:
 525            raise ValueError("No DDA scans found in dataset")
 526
 527        if scan_filter is not None:
 528            ms2_scans = ms2_scans[ms2_scans.scan_text.str.contains(scan_filter)]
 529        # set tolerance in rt space (in minutes) and mz space (in daltons)
 530        time_tol = self.parameters.lc_ms.ms2_dda_rt_tolerance
 531        mz_tol = self.parameters.lc_ms.ms2_dda_mz_tolerance
 532
 533        # for each mass feature, find the ms2 scans that are within the roi scan time and mz range
 534        dda_scans = []
 535        for i, row in mf_df.iterrows():
 536            ms2_scans_filtered = ms2_scans[
 537                ms2_scans.scan_time.between(
 538                    row.scan_time - time_tol, row.scan_time + time_tol
 539                )
 540            ]
 541            ms2_scans_filtered = ms2_scans_filtered[
 542                ms2_scans_filtered.precursor_mz.between(
 543                    row.mz - mz_tol, row.mz + mz_tol
 544                )
 545            ]
 546            dda_scans = dda_scans + ms2_scans_filtered.scan.tolist()
 547            self.mass_features[i].ms2_scan_numbers = (
 548                ms2_scans_filtered.scan.tolist()
 549                + self.mass_features[i].ms2_scan_numbers
 550            )
 551        # add to _ms attribute
 552        self.add_mass_spectra(
 553            scan_list=list(set(dda_scans)),
 554            auto_process=auto_process,
 555            spectrum_mode=spectrum_mode,
 556            use_parser=use_parser,
 557            ms_params=ms_params,
 558        )
 559        # associate appropriate _ms attribute to appropriate mass feature's ms2_mass_spectra attribute
 560        for mf_id in self.mass_features:
 561            if self.mass_features[mf_id].ms2_scan_numbers is not None:
 562                for dda_scan in self.mass_features[mf_id].ms2_scan_numbers:
 563                    if dda_scan in self._ms.keys():
 564                        self.mass_features[mf_id].ms2_mass_spectra[dda_scan] = self._ms[
 565                            dda_scan
 566                        ]
 567
 568    def add_associated_ms1(
 569        self, auto_process=True, use_parser=True, spectrum_mode=None
 570    ):
 571        """Add MS1 spectra associated with mass features to the dataset.
 572
 573        Parameters
 574        -----------
 575        auto_process : bool, optional
 576            If True, auto-processes the MS1 spectra before adding it to the object's _ms dictionary. Default is True.
 577        use_parser : bool, optional
 578            If True, envoke the spectra parser to get the MS1 spectra. Default is True.
 579        spectrum_mode : str or None, optional
 580            The spectrum mode to use for the mass spectra.  If None, method will use the spectrum mode
 581            from the spectra parser to ascertain the spectrum mode (this allows for mixed types).
 582            Defaults to None. (faster if defined, otherwise will check each scan)
 583
 584        Raises
 585        ------
 586        ValueError
 587            If mass_features is not set, must run find_mass_features() first.
 588            If apex scans are not profile mode, all apex scans must be profile mode for averaging.
 589            If number of scans to average is not  1 or an integer with an integer median (i.e. 3, 5, 7, 9).
 590            If deconvolute is True and no EICs are found, did you run integrate_mass_features() first?
 591        """
 592        # Check if mass_features is set, raise error if not
 593        if self.mass_features is None:
 594            raise ValueError(
 595                "mass_features not set, must run find_mass_features() first"
 596            )
 597        scans_to_average = self.parameters.lc_ms.ms1_scans_to_average
 598
 599        if scans_to_average == 1:
 600            # Add to LCMSobj
 601            self.add_mass_spectra(
 602                scan_list=[
 603                    int(mf.apex_scan) for mf in self.mass_features.values()
 604                ],
 605                auto_process=auto_process,
 606                use_parser=use_parser,
 607                spectrum_mode=spectrum_mode,
 608                ms_params=self.parameters.mass_spectrum["ms1"],
 609            )
 610
 611        elif (
 612            (scans_to_average - 1) % 2
 613        ) == 0:  # scans_to_average = 3, 5, 7 etc, mirror l/r around apex
 614            apex_scans = list(set([int(mf.apex_scan) for mf in self.mass_features.values()]))
 615            # Check if all apex scans are profile mode, raise error if not
 616            if not all(self.scan_df.loc[apex_scans, "ms_format"] == "profile"):
 617                raise ValueError("All apex scans must be profile mode for averaging")
 618
 619            # First get sets of scans to average
 620            def get_scans_from_apex(ms1_scans, apex_scan, scans_to_average):
 621                ms1_idx_start = ms1_scans.index(apex_scan) - int(
 622                    (scans_to_average - 1) / 2
 623                )
 624                if ms1_idx_start < 0:
 625                    ms1_idx_start = 0
 626                ms1_idx_end = (
 627                    ms1_scans.index(apex_scan) + int((scans_to_average - 1) / 2) + 1
 628                )
 629                if ms1_idx_end > (len(ms1_scans) - 1):
 630                    ms1_idx_end = len(ms1_scans) - 1
 631                scan_list = ms1_scans[ms1_idx_start:ms1_idx_end]
 632                return scan_list
 633
 634            ms1_scans = self.ms1_scans
 635            scans_lists = [
 636                get_scans_from_apex(ms1_scans, apex_scan, scans_to_average)
 637                for apex_scan in apex_scans
 638            ]
 639
 640            # set polarity to -1 if negative mode, 1 if positive mode (for mass spectrum creation)
 641            if self.polarity == "negative":
 642                polarity = -1
 643            elif self.polarity == "positive":
 644                polarity = 1
 645
 646            if not use_parser:
 647                # Perform checks and prepare _ms_unprocessed dictionary if use_parser is False (saves time to do this once)
 648                ms1_unprocessed = self._ms_unprocessed[1].copy()
 649                # Set the index on _ms_unprocessed[1] to scan number
 650                ms1_unprocessed = ms1_unprocessed.set_index("scan", drop=False)
 651                self._ms_unprocessed[1] = ms1_unprocessed
 652
 653                # Check that all the scans in scan_lists are indexs in self._ms_unprocessed[1]
 654                scans_lists_flat = list(
 655                    set([scan for sublist in scans_lists for scan in sublist])
 656                )
 657                if (
 658                    len(
 659                        np.setdiff1d(
 660                            np.sort(scans_lists_flat),
 661                            np.sort(ms1_unprocessed.index.values),
 662                        )
 663                    )
 664                    > 0
 665                ):
 666                    raise ValueError(
 667                        "Not all scans to average are present in the unprocessed data"
 668                    )
 669
 670            for scan_list_average, apex_scan in zip(scans_lists, apex_scans):
 671                # Get unprocessed mass spectrum from scans
 672                ms = self.get_average_mass_spectrum(
 673                    scan_list=scan_list_average,
 674                    apex_scan=apex_scan,
 675                    spectrum_mode="profile",
 676                    ms_level=1,
 677                    auto_process=auto_process,
 678                    use_parser=use_parser,
 679                    perform_checks=False,
 680                    polarity=polarity,
 681                    ms_params=self.parameters.mass_spectrum["ms1"],
 682                )
 683                # Add mass spectrum to LCMS object and associated with mass feature
 684                self.add_mass_spectrum(ms)
 685
 686            if not use_parser:
 687                # Reset the index on _ms_unprocessed[1] to not be scan number
 688                ms1_unprocessed = ms1_unprocessed.reset_index(drop=True)
 689                self._ms_unprocessed[1] = ms1_unprocessed
 690        else:
 691            raise ValueError(
 692                "Number of scans to average must be 1 or an integer with an integer median (i.e. 3, 5, 7, 9)"
 693            )
 694
 695        # Associate the ms1 spectra with the mass features
 696        for mf_id in self.mass_features:
 697            self.mass_features[mf_id].mass_spectrum = self._ms[
 698                self.mass_features[mf_id].apex_scan
 699            ]
 700            self.mass_features[mf_id].update_mz()
 701
 702    def mass_features_to_df(self):
 703        """Returns a pandas dataframe summarizing the mass features.
 704
 705        The dataframe contains the following columns: mf_id, mz, apex_scan, scan_time, intensity,
 706        persistence, area, monoisotopic_mf_id, and isotopologue_type.  The index is set to mf_id (mass feature ID).
 707
 708        Returns
 709        --------
 710        pandas.DataFrame
 711            A pandas dataframe of mass features with the following columns:
 712            mf_id, mz, apex_scan, scan_time, intensity, persistence, area.
 713        """
 714
 715        def mass_spectrum_to_string(
 716            mass_spec, normalize=True, min_normalized_abun=0.01
 717        ):
 718            """Converts a mass spectrum to a string of m/z:abundance pairs.
 719
 720            Parameters
 721            -----------
 722            mass_spec : MassSpectrum
 723                A MassSpectrum object to be converted to a string.
 724            normalize : bool, optional
 725                If True, normalizes the abundance values to a maximum of 1. Defaults to True.
 726            min_normalized_abun : float, optional
 727                The minimum normalized abundance value to include in the string, only used if normalize is True. Defaults to 0.01.
 728
 729            Returns
 730            --------
 731            str
 732                A string of m/z:abundance pairs from the mass spectrum, separated by a semicolon.
 733            """
 734            mz_np = mass_spec.to_dataframe()["m/z"].values
 735            abun_np = mass_spec.to_dataframe()["Peak Height"].values
 736            if normalize:
 737                abun_np = abun_np / abun_np.max()
 738            mz_abun = np.column_stack((mz_np, abun_np))
 739            if normalize:
 740                mz_abun = mz_abun[mz_abun[:, 1] > min_normalized_abun]
 741            mz_abun_str = [
 742                str(round(mz, ndigits=4)) + ":" + str(round(abun, ndigits=2))
 743                for mz, abun in mz_abun
 744            ]
 745            return "; ".join(mz_abun_str)
 746
 747        cols_in_df = [
 748            "id",
 749            "apex_scan",
 750            "start_scan",
 751            "final_scan",
 752            "retention_time",
 753            "intensity",
 754            "persistence",
 755            "area",
 756            "dispersity_index",
 757            "normalized_dispersity_index",
 758            "tailing_factor",
 759            "gaussian_similarity",
 760            "noise_score",
 761            "noise_score_min",
 762            "noise_score_max",
 763            "monoisotopic_mf_id",
 764            "isotopologue_type",
 765            "mass_spectrum_deconvoluted_parent",
 766        ]
 767        df_mf_list = []
 768        for mf_id in self.mass_features.keys():
 769            # Find cols_in_df that are in single_mf
 770            df_keys = list(
 771                set(cols_in_df).intersection(self.mass_features[mf_id].__dir__())
 772            )
 773            dict_mf = {}
 774            # Get the values for each key in df_keys from the mass feature object
 775            for key in df_keys:
 776                dict_mf[key] = getattr(self.mass_features[mf_id], key)
 777            # Special handling for mass_spectrum and associated_mass_features_deconvoluted, since they are not single values
 778            if len(self.mass_features[mf_id].ms2_scan_numbers) > 0:
 779                # Add MS2 spectra info
 780                best_ms2_spectrum = self.mass_features[mf_id].best_ms2
 781                dict_mf["ms2_spectrum"] = mass_spectrum_to_string(best_ms2_spectrum)
 782            if len(self.mass_features[mf_id].associated_mass_features_deconvoluted) > 0:
 783                dict_mf["associated_mass_features"] = ", ".join(
 784                    map(
 785                        str,
 786                        self.mass_features[mf_id].associated_mass_features_deconvoluted,
 787                    )
 788                )
 789            # Check if EIC for mass feature is set
 790            df_mf_single = pd.DataFrame(dict_mf, index=[mf_id])
 791            df_mf_single["mz"] = self.mass_features[mf_id].mz
 792            df_mf_list.append(df_mf_single)
 793        df_mf = pd.concat(df_mf_list)
 794
 795        # rename _area to area and id to mf_id
 796        df_mf = df_mf.rename(
 797            columns={
 798                "id": "mf_id",
 799                "retention_time": "scan_time",            
 800            }
 801        )
 802
 803        # reorder columns
 804        col_order = [
 805            "mf_id",
 806            "scan_time",
 807            "mz",
 808            "apex_scan",
 809            "start_scan",
 810            "final_scan",
 811            "intensity",
 812            "persistence",
 813            "area",
 814            "half_height_width",
 815            "tailing_factor",
 816            "dispersity_index",
 817            "normalized_dispersity_index",
 818            "gaussian_similarity",
 819            "noise_score",
 820            "noise_score_min",
 821            "noise_score_max",
 822            "monoisotopic_mf_id",
 823            "isotopologue_type",
 824            "mass_spectrum_deconvoluted_parent",
 825            "associated_mass_features",
 826            "ms2_spectrum",
 827        ]
 828        # drop columns that are not in col_order
 829        cols_to_order = [col for col in col_order if col in df_mf.columns]
 830        df_mf = df_mf[cols_to_order]
 831
 832        # reset index to mf_id
 833        df_mf = df_mf.set_index("mf_id")
 834        df_mf.index.name = "mf_id"
 835
 836        return df_mf
 837
 838    def mass_features_ms1_annot_to_df(self):
 839        """Returns a pandas dataframe summarizing the MS1 annotations for the mass features in the dataset.
 840
 841        Returns
 842        --------
 843        pandas.DataFrame
 844            A pandas dataframe of MS1 annotations for the mass features in the dataset.
 845            The index is set to mf_id (mass feature ID)
 846
 847        Raises
 848        ------
 849        Warning
 850            If no MS1 annotations were found for the mass features in the dataset.
 851        """
 852        annot_df_list_ms1 = []
 853        for mf_id in self.mass_features.keys():
 854            if self.mass_features[mf_id].mass_spectrum is None:
 855                pass
 856            else:
 857                # Add ms1 annotations to ms1 annotation list
 858                if (
 859                    np.abs(
 860                        (
 861                            self.mass_features[mf_id].ms1_peak.mz_exp
 862                            - self.mass_features[mf_id].mz
 863                        )
 864                    )
 865                    < 0.01
 866                ):
 867                    # Get the molecular formula from the mass spectrum
 868                    annot_df = self.mass_features[mf_id].mass_spectrum.to_dataframe()
 869                    # Subset to pull out only the peak associated with the mass feature
 870                    annot_df = annot_df[
 871                        annot_df["Index"] == self.mass_features[mf_id].ms1_peak.index
 872                    ].copy()
 873
 874                    # If there are more than 1 row, remove any rows without a molecular formula
 875                    if len(annot_df) > 1:
 876                        annot_df = annot_df[~annot_df["Molecular Formula"].isna()]
 877
 878                    # Remove the index column and add column for mf_id
 879                    annot_df = annot_df.drop(columns=["Index"])
 880                    annot_df["mf_id"] = mf_id
 881                    annot_df_list_ms1.append(annot_df)
 882
 883        if len(annot_df_list_ms1) > 0:
 884            annot_ms1_df_full = pd.concat(annot_df_list_ms1)
 885            annot_ms1_df_full = annot_ms1_df_full.set_index("mf_id")
 886            annot_ms1_df_full.index.name = "mf_id"
 887
 888        else:
 889            annot_ms1_df_full = None
 890            # Warn that no ms1 annotations were found
 891            warnings.warn(
 892                "No MS1 annotations found for mass features in dataset, were MS1 spectra added and processed within the dataset?",
 893                UserWarning,
 894            )
 895
 896        return annot_ms1_df_full
 897
 898    def mass_features_ms2_annot_to_df(self, molecular_metadata=None):
 899        """Returns a pandas dataframe summarizing the MS2 annotations for the mass features in the dataset.
 900
 901        Parameters
 902        -----------
 903        molecular_metadata :  dict of MolecularMetadata objects
 904            A dictionary of MolecularMetadata objects, keyed by metabref_mol_id.  Defaults to None.
 905
 906        Returns
 907        --------
 908        pandas.DataFrame
 909            A pandas dataframe of MS2 annotations for the mass features in the dataset,
 910            and optionally molecular metadata. The index is set to mf_id (mass feature ID)
 911
 912        Raises
 913        ------
 914        Warning
 915            If no MS2 annotations were found for the mass features in the dataset.
 916        """
 917        annot_df_list_ms2 = []
 918        for mf_id in self.mass_features.keys():
 919            if len(self.mass_features[mf_id].ms2_similarity_results) > 0:
 920                # Add ms2 annotations to ms2 annotation list
 921                for result in self.mass_features[mf_id].ms2_similarity_results:
 922                    annot_df_ms2 = result.to_dataframe()
 923                    annot_df_ms2["mf_id"] = mf_id
 924                    annot_df_list_ms2.append(annot_df_ms2)
 925
 926        if len(annot_df_list_ms2) > 0:
 927            annot_ms2_df_full = pd.concat(annot_df_list_ms2)
 928            if molecular_metadata is not None:
 929                molecular_metadata_df = pd.concat(
 930                    [
 931                        pd.DataFrame.from_dict(v.__dict__, orient="index").transpose()
 932                        for k, v in molecular_metadata.items()
 933                    ],
 934                    ignore_index=True,
 935                )
 936                molecular_metadata_df = molecular_metadata_df.rename(
 937                    columns={"id": "ref_mol_id"}
 938                )
 939                annot_ms2_df_full = annot_ms2_df_full.merge(
 940                    molecular_metadata_df, on="ref_mol_id", how="left"
 941                )
 942            annot_ms2_df_full = annot_ms2_df_full.drop_duplicates(
 943                subset=["mf_id", "query_spectrum_id", "ref_ms_id"]
 944            ).copy()
 945            annot_ms2_df_full = annot_ms2_df_full.set_index("mf_id")
 946            annot_ms2_df_full.index.name = "mf_id"
 947        else:
 948            annot_ms2_df_full = None
 949            # Warn that no ms2 annotations were found
 950            warnings.warn(
 951                "No MS2 annotations found for mass features in dataset, were MS2 spectra added and searched against a database?",
 952                UserWarning,
 953            )
 954
 955        return annot_ms2_df_full
 956
 957    def plot_composite_mz_features(self, binsize = 1e-4, ph_int_min_thresh = 0.001, mf_plot = True, ms2_plot = True, return_fig = False):
 958        """Returns a figure displaying 
 959            (1) thresholded, unprocessed data
 960            (2) the m/z features
 961            (3) which m/z features are associated with MS2 spectra
 962
 963        Parameters
 964        -----------
 965        binsize :  float
 966            Desired binsize for the m/z axis of the composite feature map.  Defaults to 1e-4.
 967        mf_plot : boolean
 968            Indicates whether to plot the m/z features. Defaults to True.
 969        ms2_plot : boolean
 970            Indicates whether to identify m/z features with associated MS2 spectra. Defaults to True.
 971        return_fig : boolean
 972            Indicates whether to plot composite feature map (False) or return figure object (True). Defaults to False.
 973
 974        Returns
 975        --------
 976        matplotlib.pyplot.Figure
 977            A figure with the thresholded, unprocessed data on an axis of m/z value with respect to 
 978            scan time. Unprocessed data is displayed in gray scale with darker colors indicating 
 979            higher intensities. If m/z features are plotted, they are displayed in cyan. If m/z
 980            features with associated with MS2 spectra are plotted, they are displayed in red.
 981
 982        Raises
 983        ------
 984        Warning
 985            If m/z features are set to be plot but aren't in the dataset.
 986            If m/z features with associated MS2 data are set to be plot but no MS2 annotations 
 987            were found for the m/z features in the dataset.
 988        """
 989        if mf_plot:
 990            # Check if mass_features is set, raise error if not
 991            if self.mass_features is None:
 992                raise ValueError(
 993                    "mass_features not set, must run find_mass_features() first"
 994                )
 995            ## call mass feature data
 996            mf_df = self.mass_features_to_df()
 997
 998        if ms2_plot:
 999            if not mf_plot:
1000                # Check if mass_features is set, raise error if not
1001                if self.mass_features is None:
1002                    raise ValueError(
1003                        "mass_features not set, must run find_mass_features() first"
1004                    )
1005
1006            ## call m/z feature data
1007            mf_df = self.mass_features_to_df()
1008
1009            # Check if ms2_spectrum is set, raise error if not
1010            if 'ms2_spectrum' not in mf_df.columns:
1011                raise ValueError(                
1012                    "ms2_spectrum not set, must run add_associated_ms2_dda() first"            
1013                )
1014    
1015        ## threshold and grid unprocessed data
1016        df = self._ms_unprocessed[1].copy()
1017        df = df.dropna(subset=['intensity']).reset_index(drop = True)
1018        threshold = ph_int_min_thresh * df.intensity.max()
1019        df_thres = df[df["intensity"] > threshold].reset_index(drop = True).copy()
1020        df = self.grid_data(df_thres)
1021    
1022        ## format unprocessed data for plotting
1023        df = df.merge(self.scan_df[['scan', 'scan_time']], on = 'scan')
1024        mz_grid = np.arange(0, np.max(df.mz), binsize)
1025        mz_data = np.array(df.mz)
1026        df['mz_bin'] = find_closest(mz_grid, mz_data)
1027        df['ab_bin'] = df.groupby(['mz_bin', 'scan_time']).intensity.transform(sum)
1028        unproc_df = df[['scan_time', 'mz_bin', 'ab_bin']].drop_duplicates(ignore_index = True)
1029
1030        ## generate figure
1031        fig = plt.figure()
1032        plt.scatter(
1033            unproc_df.scan_time,
1034            unproc_df.mz_bin*binsize,
1035            c = unproc_df.ab_bin/np.max(unproc_df.ab_bin),
1036            alpha = unproc_df.ab_bin/np.max(unproc_df.ab_bin), 
1037            cmap = 'Greys_r',
1038            s = 1
1039        )
1040
1041        if mf_plot:
1042            if ms2_plot:
1043                plt.scatter(
1044                    mf_df[mf_df.ms2_spectrum.isna()].scan_time,
1045                    mf_df[mf_df.ms2_spectrum.isna()].mz,
1046                    c = 'c',
1047                    s = 4,
1048                    label = 'M/Z features without MS2'
1049                )
1050            else:
1051                plt.scatter(
1052                    mf_df.scan_time,
1053                    mf_df.mz,
1054                    c = 'c',
1055                    s = 4,
1056                    label = 'M/Z features'
1057                )
1058
1059        if ms2_plot: 
1060            plt.scatter(
1061                mf_df[~mf_df.ms2_spectrum.isna()].scan_time,
1062                mf_df[~mf_df.ms2_spectrum.isna()].mz,
1063                c = 'r',
1064                s = 2,
1065                label = 'M/Z features with MS2'
1066            )
1067
1068        if mf_plot == True or ms2_plot == True:
1069            plt.legend(loc = 'lower center', bbox_to_anchor = (0.5, -0.25), ncol = 2)
1070        plt.xlabel('Scan time')
1071        plt.ylabel('m/z')
1072        plt.ylim(0, np.ceil(np.max(df.mz)))
1073        plt.xlim(0, np.ceil(np.max(df.scan_time)))
1074        plt.title('Composite Feature Map')
1075
1076        if return_fig:
1077            plt.close(fig)
1078            return fig
1079
1080        else:
1081            plt.show()
1082
1083    def __len__(self):
1084        """
1085        Returns the number of mass spectra in the dataset.
1086
1087        Returns
1088        --------
1089        int
1090            The number of mass spectra in the dataset.
1091        """
1092        return len(self._ms)
1093
1094    def __getitem__(self, scan_number):
1095        """
1096        Returns the mass spectrum corresponding to the specified scan number.
1097
1098        Parameters
1099        -----------
1100        scan_number : int
1101            The scan number of the desired mass spectrum.
1102
1103        Returns
1104        --------
1105        MassSpectrum
1106            The mass spectrum corresponding to the specified scan number.
1107        """
1108        return self._ms.get(scan_number)
1109
1110    def __iter__(self):
1111        """Returns an iterator over the mass spectra in the dataset.
1112
1113        Returns
1114        --------
1115        iterator
1116            An iterator over the mass spectra in the dataset.
1117        """
1118        return iter(self._ms.values())
1119
1120    def set_tic_list_from_data(self, overwrite=False):
1121        """Sets the TIC list from the mass spectrum objects within the _ms dictionary.
1122
1123        Parameters
1124        -----------
1125        overwrite : bool, optional
1126            If True, overwrites the TIC list if it is already set. Defaults to False.
1127
1128        Notes
1129        -----
1130        If the _ms dictionary is incomplete, sets the TIC list to an empty list.
1131
1132        Raises
1133        ------
1134        ValueError
1135            If no mass spectra are found in the dataset.
1136            If the TIC list is already set and overwrite is False.
1137        """
1138        # Check if _ms is empty and raise error if so
1139        if len(self._ms) == 0:
1140            raise ValueError("No mass spectra found in dataset")
1141
1142        # Check if tic_list is already set and raise error if so
1143        if len(self.tic) > 0 and not overwrite:
1144            raise ValueError("TIC list already set, use overwrite=True to overwrite")
1145
1146        self.tic = [self._ms.get(i).tic for i in self.scans_number]
1147
1148    def set_retention_time_from_data(self, overwrite=False):
1149        """Sets the retention time list from the data in the _ms dictionary.
1150
1151        Parameters
1152        -----------
1153        overwrite : bool, optional
1154            If True, overwrites the retention time list if it is already set. Defaults to False.
1155
1156        Notes
1157        -----
1158        If the _ms dictionary is empty or incomplete, sets the retention time list to an empty list.
1159
1160        Raises
1161        ------
1162        ValueError
1163            If no mass spectra are found in the dataset.
1164            If the retention time list is already set and overwrite is False.
1165        """
1166        # Check if _ms is empty and raise error if so
1167        if len(self._ms) == 0:
1168            raise ValueError("No mass spectra found in dataset")
1169
1170        # Check if retention_time_list is already set and raise error if so
1171        if len(self.retention_time) > 0 and not overwrite:
1172            raise ValueError(
1173                "Retention time list already set, use overwrite=True to overwrite"
1174            )
1175
1176        retention_time_list = []
1177        for key_ms in sorted(self._ms.keys()):
1178            retention_time_list.append(self._ms.get(key_ms).retention_time)
1179        self.retention_time = retention_time_list
1180
1181    def set_scans_number_from_data(self, overwrite=False):
1182        """Sets the scan number list from the data in the _ms dictionary.
1183
1184        Notes
1185        -----
1186        If the _ms dictionary is empty or incomplete, sets the scan number list to an empty list.
1187
1188        Raises
1189        ------
1190        ValueError
1191            If no mass spectra are found in the dataset.
1192            If the scan number list is already set and overwrite is False.
1193        """
1194        # Check if _ms is empty and raise error if so
1195        if len(self._ms) == 0:
1196            raise ValueError("No mass spectra found in dataset")
1197
1198        # Check if scans_number_list is already set and raise error if so
1199        if len(self.scans_number) > 0 and not overwrite:
1200            raise ValueError(
1201                "Scan number list already set, use overwrite=True to overwrite"
1202            )
1203
1204        self.scans_number = sorted(self._ms.keys())
1205
1206    @property
1207    def ms1_scans(self):
1208        """
1209        list : A list of MS1 scan numbers for the dataset.
1210        """
1211        return self.scan_df[self.scan_df.ms_level == 1].index.tolist()
1212
1213    @property
1214    def parameters(self):
1215        """
1216        LCMSParameters : The parameters used for the LC-MS analysis.
1217        """
1218        return self._parameters
1219
1220    @parameters.setter
1221    def parameters(self, paramsinstance):
1222        """
1223        Sets the parameters used for the LC-MS analysis.
1224
1225        Parameters
1226        -----------
1227        paramsinstance : LCMSParameters
1228            The parameters used for the LC-MS analysis.
1229        """
1230        self._parameters = paramsinstance
1231
1232    @property
1233    def scans_number(self):
1234        """
1235        list : A list of scan numbers for the dataset.
1236        """
1237        return self._scans_number_list
1238
1239    @scans_number.setter
1240    def scans_number(self, scan_numbers_list):
1241        """
1242        Sets the scan numbers for the dataset.
1243
1244        Parameters
1245        -----------
1246        scan_numbers_list : list
1247            A list of scan numbers for the dataset.
1248        """
1249        self._scans_number_list = scan_numbers_list
1250
1251    @property
1252    def retention_time(self):
1253        """
1254        numpy.ndarray : An array of retention times for the dataset.
1255        """
1256        return self._retention_time_list
1257
1258    @retention_time.setter
1259    def retention_time(self, rt_list):
1260        """
1261        Sets the retention times for the dataset.
1262
1263        Parameters
1264        -----------
1265        rt_list : list
1266            A list of retention times for the dataset.
1267        """
1268        self._retention_time_list = np.array(rt_list)
1269
1270    @property
1271    def tic(self):
1272        """
1273        numpy.ndarray : An array of TIC values for the dataset.
1274        """
1275        return self._tic_list
1276
1277    @tic.setter
1278    def tic(self, tic_list):
1279        """
1280        Sets the TIC values for the dataset.
1281
1282        Parameters
1283        -----------
1284        tic_list : list
1285            A list of TIC values for the dataset.
1286        """
1287        self._tic_list = np.array(tic_list)