corems.mass_spectra.output.export

   1__author__ = "Yuri E. Corilo"
   2__date__ = "Dec 14, 2010"
   3
   4
   5import csv
   6import json
   7import re
   8import uuid
   9import warnings
  10from datetime import datetime, timezone
  11from pathlib import Path
  12
  13import h5py
  14import numpy as np
  15import pandas as pd
  16from openpyxl import load_workbook
  17from pandas import DataFrame, ExcelWriter, read_excel
  18
  19from corems import __version__, corems_md5
  20from corems.encapsulation.output import parameter_to_dict
  21from corems.encapsulation.output.parameter_to_json import (
  22    dump_lcms_settings_json,
  23    dump_lcms_settings_toml,
  24)
  25from corems.mass_spectrum.output.export import HighResMassSpecExport
  26from corems.molecular_formula.factory.MolecularFormulaFactory import MolecularFormula
  27from corems.molecular_id.calc.SpectralSimilarity import methods_name
  28
  29ion_type_dict = {
  30    # adduct : [atoms to add, atoms to subtract when calculating formula of ion
  31    "M+": [{}, {}],
  32    "protonated": [{"H": 1}, {}],
  33    "[M+H]+": [{"H": 1}, {}],
  34    "[M+NH4]+": [{"N": 1, "H": 4}, {}],  # ammonium
  35    "[M+Na]+": [{"Na": 1}, {}],
  36    "[M+K]+": [{"K": 1}, {}],
  37    "[M+2Na+Cl]+": [{"Na": 2, "Cl": 1}, {}],
  38    "[M+2Na-H]+": [{"Na": 2}, {"H": 1}],
  39    "[M+C2H3Na2O2]+": [{"C": 2, "H": 3, "Na": 2, "O": 2}, {}],
  40    "[M+C4H10N3]+": [{"C": 4, "H": 10, "N": 3}, {}],
  41    "[M+NH4+ACN]+": [{"C": 2, "H": 7, "N": 2}, {}],
  42    "[M+H-H2O]+": [{}, {"H": 1, "O": 1}],
  43    "de-protonated": [{}, {"H": 1}],
  44    "[M-H]-": [{}, {"H": 1}],
  45    "[M+Cl]-": [{"Cl": 1}, {}],
  46    "[M+HCOO]-": [{"C": 1, "H": 1, "O": 2}, {}],  # formate
  47    "[M+CH3COO]-": [{"C": 2, "H": 3, "O": 2}, {}],  # acetate
  48    "[M+2NaAc+Cl]-": [{"Na": 2, "C": 2, "H": 3, "O": 2, "Cl": 1}, {}],
  49    "[M+K-2H]-": [{"K": 1}, {"H": 2}],
  50    "[M+Na-2H]-": [{"Na": 1}, {"H": 2}],
  51}
  52
  53
  54class LowResGCMSExport:
  55    """A class to export low resolution GC-MS data.
  56
  57    This class provides methods to export low resolution GC-MS data to various formats such as Excel, CSV, HDF5, and Pandas DataFrame.
  58
  59    Parameters:
  60    ----------
  61    out_file_path : str
  62        The output file path.
  63    gcms : object
  64        The low resolution GCMS object.
  65
  66    Attributes:
  67    ----------
  68    output_file : Path
  69        The output file path as a Path object.
  70    gcms : object
  71        The low resolution GCMS object.
  72
  73    Methods:
  74    -------
  75    * get_pandas_df(id_label="corems:"). Get the exported data as a Pandas DataFrame.
  76    * get_json(nan=False, id_label="corems:"). Get the exported data as a JSON string.
  77    * to_pandas(write_metadata=True, id_label="corems:"). Export the data to a Pandas DataFrame and save it as a pickle file.
  78    * to_excel(write_mode='a', write_metadata=True, id_label="corems:"),
  79        Export the data to an Excel file.
  80    * to_csv(separate_output=False, write_mode="w", write_metadata=True, id_label="corems:").
  81        Export the data to a CSV file.
  82    * to_hdf(id_label="corems:").
  83        Export the data to an HDF5 file.
  84    * get_data_stats(gcms).
  85        Get statistics about the GCMS data.
  86
  87    """
  88
  89    def __init__(self, out_file_path, gcms):
  90        self.output_file = Path(out_file_path)
  91
  92        self.gcms = gcms
  93
  94        self._init_columns()
  95
  96    def _init_columns(self):
  97        """Initialize the column names for the exported data.
  98
  99        Returns:
 100        -------
 101        list
 102            The list of column names.
 103        """
 104
 105        columns = [
 106            "Sample name",
 107            "Peak Index",
 108            "Retention Time",
 109            "Retention Time Ref",
 110            "Peak Height",
 111            "Peak Area",
 112            "Retention index",
 113            "Retention index Ref",
 114            "Retention Index Score",
 115            "Similarity Score",
 116            "Spectral Similarity Score",
 117            "Compound Name",
 118            "Chebi ID",
 119            "Kegg Compound ID",
 120            "Inchi",
 121            "Inchi Key",
 122            "Smiles",
 123            "Molecular Formula",
 124            "IUPAC Name",
 125            "Traditional Name",
 126            "Common Name",
 127            "Derivatization",
 128        ]
 129
 130        if self.gcms.molecular_search_settings.exploratory_mode:
 131            columns.extend(
 132                [
 133                    "Weighted Cosine Correlation",
 134                    "Cosine Correlation",
 135                    "Stein Scott Similarity",
 136                    "Pearson Correlation",
 137                    "Spearman Correlation",
 138                    "Kendall Tau Correlation",
 139                    "Euclidean Distance",
 140                    "Manhattan Distance",
 141                    "Jaccard Distance",
 142                    "DWT Correlation",
 143                    "DFT Correlation",
 144                ]
 145            )
 146
 147            columns.extend(list(methods_name.values()))
 148
 149        return columns
 150
 151    def get_pandas_df(self, id_label="corems:"):
 152        """Get the exported data as a Pandas DataFrame.
 153
 154        Parameters:
 155        ----------
 156        id_label : str, optional
 157            The ID label for the data. Default is "corems:".
 158
 159        Returns:
 160        -------
 161        DataFrame
 162            The exported data as a Pandas DataFrame.
 163        """
 164
 165        columns = self._init_columns()
 166
 167        dict_data_list = self.get_list_dict_data(self.gcms)
 168
 169        df = DataFrame(dict_data_list, columns=columns)
 170
 171        df.name = self.gcms.sample_name
 172
 173        return df
 174
 175    def get_json(self, nan=False, id_label="corems:"):
 176        """Get the exported data as a JSON string.
 177
 178        Parameters:
 179        ----------
 180        nan : bool, optional
 181            Whether to include NaN values in the JSON string. Default is False.
 182        id_label : str, optional
 183            The ID label for the data. Default is "corems:".
 184
 185        """
 186
 187        import json
 188
 189        dict_data_list = self.get_list_dict_data(self.gcms)
 190
 191        return json.dumps(
 192            dict_data_list, sort_keys=False, indent=4, separators=(",", ": ")
 193        )
 194
 195    def to_pandas(self, write_metadata=True, id_label="corems:"):
 196        """Export the data to a Pandas DataFrame and save it as a pickle file.
 197
 198        Parameters:
 199        ----------
 200        write_metadata : bool, optional
 201            Whether to write metadata to the output file.
 202        id_label : str, optional
 203            The ID label for the data.
 204        """
 205
 206        columns = self._init_columns()
 207
 208        dict_data_list = self.get_list_dict_data(self.gcms)
 209
 210        df = DataFrame(dict_data_list, columns=columns)
 211
 212        df.to_pickle(self.output_file.with_suffix(".pkl"))
 213
 214        if write_metadata:
 215            self.write_settings(
 216                self.output_file.with_suffix(".pkl"), self.gcms, id_label="corems:"
 217            )
 218
 219    def to_excel(self, write_mode="a", write_metadata=True, id_label="corems:"):
 220        """Export the data to an Excel file.
 221
 222        Parameters:
 223        ----------
 224        write_mode : str, optional
 225            The write mode for the Excel file. Default is 'a' (append).
 226        write_metadata : bool, optional
 227            Whether to write metadata to the output file. Default is True.
 228        id_label : str, optional
 229            The ID label for the data. Default is "corems:".
 230        """
 231
 232        out_put_path = self.output_file.with_suffix(".xlsx")
 233
 234        columns = self._init_columns()
 235
 236        dict_data_list = self.get_list_dict_data(self.gcms)
 237
 238        df = DataFrame(dict_data_list, columns=columns)
 239
 240        if write_mode == "a" and out_put_path.exists():
 241            writer = ExcelWriter(out_put_path, engine="openpyxl")
 242            # try to open an existing workbook
 243            writer.book = load_workbook(out_put_path)
 244            # copy existing sheets
 245            writer.sheets = dict((ws.title, ws) for ws in writer.book.worksheets)
 246            # read existing file
 247            reader = read_excel(out_put_path)
 248            # write out the new sheet
 249            df.to_excel(writer, index=False, header=False, startrow=len(reader) + 1)
 250
 251            writer.close()
 252        else:
 253            df.to_excel(
 254                self.output_file.with_suffix(".xlsx"), index=False, engine="openpyxl"
 255            )
 256
 257        if write_metadata:
 258            self.write_settings(out_put_path, self.gcms, id_label=id_label)
 259
 260    def to_csv(
 261        self,
 262        separate_output=False,
 263        write_mode="w",
 264        write_metadata=True,
 265        id_label="corems:",
 266    ):
 267        """Export the data to a CSV file.
 268
 269        Parameters:
 270        ----------
 271        separate_output : bool, optional
 272            Whether to separate the output into multiple files. Default is False.
 273        write_mode : str, optional
 274            The write mode for the CSV file. Default is 'w' (write).
 275        write_metadata : bool, optional
 276            Whether to write metadata to the output file. Default is True.
 277        id_label : str, optional
 278            The ID label for the data. Default is "corems:".
 279        """
 280
 281        if separate_output:
 282            # set write mode to write
 283            # this mode will overwrite the file without warning
 284            write_mode = "w"
 285        else:
 286            # set write mode to append
 287            write_mode = "a"
 288
 289        columns = self._init_columns()
 290
 291        dict_data_list = self.get_list_dict_data(self.gcms)
 292
 293        out_put_path = self.output_file.with_suffix(".csv")
 294
 295        write_header = not out_put_path.exists()
 296
 297        try:
 298            with open(out_put_path, write_mode, newline="") as csvfile:
 299                writer = csv.DictWriter(csvfile, fieldnames=columns)
 300                if write_header:
 301                    writer.writeheader()
 302                for data in dict_data_list:
 303                    writer.writerow(data)
 304
 305            if write_metadata:
 306                self.write_settings(out_put_path, self.gcms, id_label=id_label)
 307
 308        except IOError as ioerror:
 309            print(ioerror)
 310
 311    def to_hdf(self, id_label="corems:"):
 312        """Export the data to an HDF5 file.
 313
 314        Parameters:
 315        ----------
 316        id_label : str, optional
 317            The ID label for the data. Default is "corems:".
 318        """
 319
 320        # save sample at a time
 321        def add_compound(gc_peak, compound_obj):
 322            modifier = compound_obj.classify if compound_obj.classify else ""
 323            compound_group = compound_obj.name.replace("/", "") + " " + modifier
 324
 325            if compound_group not in peak_group:
 326                compound_group = peak_group.create_group(compound_group)
 327
 328                # compound_group.attrs["retention_time"] = compound_obj.retention_time
 329                compound_group.attrs["retention_index"] = compound_obj.ri
 330                compound_group.attrs["retention_index_score"] = compound_obj.ri_score
 331                compound_group.attrs["spectral_similarity_score"] = (
 332                    compound_obj.spectral_similarity_score
 333                )
 334                compound_group.attrs["similarity_score"] = compound_obj.similarity_score
 335
 336                compond_mz = compound_group.create_dataset(
 337                    "mz", data=np.array(compound_obj.mz), dtype="f8"
 338                )
 339                compond_abundance = compound_group.create_dataset(
 340                    "abundance", data=np.array(compound_obj.abundance), dtype="f8"
 341                )
 342
 343                if self.gcms.molecular_search_settings.exploratory_mode:
 344                    compound_group.attrs["Spectral Similarities"] = json.dumps(
 345                        compound_obj.spectral_similarity_scores,
 346                        sort_keys=False,
 347                        indent=4,
 348                        separators=(",", ":"),
 349                    )
 350            else:
 351                warnings.warn("Skipping duplicate reference compound.")
 352
 353        import json
 354        from datetime import datetime, timezone
 355
 356        import h5py
 357        import numpy as np
 358
 359        output_path = self.output_file.with_suffix(".hdf5")
 360
 361        with h5py.File(output_path, "w") as hdf_handle:
 362            timenow = str(datetime.now(timezone.utc).strftime("%d/%m/%Y %H:%M:%S %Z"))
 363            hdf_handle.attrs["time_stamp"] = timenow
 364            hdf_handle.attrs["data_structure"] = "gcms"
 365            hdf_handle.attrs["analyzer"] = self.gcms.analyzer
 366            hdf_handle.attrs["instrument_label"] = self.gcms.instrument_label
 367
 368            hdf_handle.attrs["sample_id"] = "self.gcms.id"
 369            hdf_handle.attrs["sample_name"] = self.gcms.sample_name
 370            hdf_handle.attrs["input_data"] = str(self.gcms.file_location)
 371            hdf_handle.attrs["output_data"] = str(output_path)
 372            hdf_handle.attrs["output_data_id"] = id_label + uuid.uuid4().hex
 373            hdf_handle.attrs["corems_version"] = __version__
 374
 375            hdf_handle.attrs["Stats"] = json.dumps(
 376                self.get_data_stats(self.gcms),
 377                sort_keys=False,
 378                indent=4,
 379                separators=(",", ": "),
 380            )
 381            hdf_handle.attrs["Calibration"] = json.dumps(
 382                self.get_calibration_stats(self.gcms, id_label),
 383                sort_keys=False,
 384                indent=4,
 385                separators=(",", ": "),
 386            )
 387            hdf_handle.attrs["Blank"] = json.dumps(
 388                self.get_blank_stats(self.gcms),
 389                sort_keys=False,
 390                indent=4,
 391                separators=(",", ": "),
 392            )
 393
 394            corems_dict_setting = parameter_to_dict.get_dict_data_gcms(self.gcms)
 395            hdf_handle.attrs["CoreMSParameters"] = json.dumps(
 396                corems_dict_setting, sort_keys=False, indent=4, separators=(",", ": ")
 397            )
 398
 399            scans_dataset = hdf_handle.create_dataset(
 400                "scans", data=np.array(self.gcms.scans_number), dtype="f8"
 401            )
 402            rt_dataset = hdf_handle.create_dataset(
 403                "rt", data=np.array(self.gcms.retention_time), dtype="f8"
 404            )
 405            tic_dataset = hdf_handle.create_dataset(
 406                "tic", data=np.array(self.gcms.tic), dtype="f8"
 407            )
 408            processed_tic_dataset = hdf_handle.create_dataset(
 409                "processed_tic", data=np.array(self.gcms.processed_tic), dtype="f8"
 410            )
 411
 412            output_score_method = (
 413                self.gcms.molecular_search_settings.output_score_method
 414            )
 415
 416            for gc_peak in self.gcms:
 417                # print(gc_peak.retention_time)
 418                # print(gc_peak.tic)
 419
 420                # check if there is a compound candidate
 421                peak_group = hdf_handle.create_group(str(gc_peak.retention_time))
 422                peak_group.attrs["deconvolution"] = int(
 423                    self.gcms.chromatogram_settings.use_deconvolution
 424                )
 425
 426                peak_group.attrs["start_scan"] = gc_peak.start_scan
 427                peak_group.attrs["apex_scan"] = gc_peak.apex_scan
 428                peak_group.attrs["final_scan"] = gc_peak.final_scan
 429
 430                peak_group.attrs["retention_index"] = gc_peak.ri
 431                peak_group.attrs["retention_time"] = gc_peak.retention_time
 432                peak_group.attrs["area"] = gc_peak.area
 433
 434                mz = peak_group.create_dataset(
 435                    "mz", data=np.array(gc_peak.mass_spectrum.mz_exp), dtype="f8"
 436                )
 437                abundance = peak_group.create_dataset(
 438                    "abundance",
 439                    data=np.array(gc_peak.mass_spectrum.abundance),
 440                    dtype="f8",
 441                )
 442
 443                if gc_peak:
 444                    if output_score_method == "highest_sim_score":
 445                        compound_obj = gc_peak.highest_score_compound
 446                        add_compound(gc_peak, compound_obj)
 447
 448                    elif output_score_method == "highest_ss":
 449                        compound_obj = gc_peak.highest_ss_compound
 450                        add_compound(gc_peak, compound_obj)
 451
 452                    else:
 453                        for compound_obj in gc_peak:
 454                            add_compound(gc_peak, compound_obj)
 455
 456    def get_data_stats(self, gcms):
 457        """Get statistics about the GCMS data.
 458
 459        Parameters:
 460        ----------
 461        gcms : object
 462            The low resolution GCMS object.
 463
 464        Returns:
 465        -------
 466        dict
 467            A dictionary containing the data statistics.
 468        """
 469
 470        matched_peaks = gcms.matched_peaks
 471        no_matched_peaks = gcms.no_matched_peaks
 472        unique_metabolites = gcms.unique_metabolites
 473
 474        peak_matchs_above_0p85 = 0
 475        unique_peak_match_above_0p85 = 0
 476        for match_peak in matched_peaks:
 477            gc_peak_above_85 = 0
 478            matches_above_85 = list(
 479                filter(lambda m: m.similarity_score >= 0.85, match_peak)
 480            )
 481            if matches_above_85:
 482                peak_matchs_above_0p85 += 1
 483            if len(matches_above_85) == 1:
 484                unique_peak_match_above_0p85 += 1
 485
 486        data_stats = {}
 487        data_stats["average_signal_noise"] = "ni"
 488        data_stats["chromatogram_dynamic_range"] = gcms.dynamic_range
 489        data_stats["total_number_peaks"] = len(gcms)
 490        data_stats["total_peaks_matched"] = len(matched_peaks)
 491        data_stats["total_peaks_without_matches"] = len(no_matched_peaks)
 492        data_stats["total_matches_above_similarity_score_0.85"] = peak_matchs_above_0p85
 493        data_stats["single_matches_above_similarity_score_0.85"] = (
 494            unique_peak_match_above_0p85
 495        )
 496        data_stats["unique_metabolites"] = len(unique_metabolites)
 497
 498        return data_stats
 499
 500    def get_calibration_stats(self, gcms, id_label):
 501        """Get statistics about the GC-MS calibration.
 502
 503        Parameters:
 504        ----------
 505        """
 506        calibration_parameters = {}
 507
 508        calibration_parameters["calibration_rt_ri_pairs_ref"] = gcms.ri_pairs_ref
 509        calibration_parameters["data_url"] = str(gcms.cal_file_path)
 510        calibration_parameters["has_input"] = id_label + corems_md5(gcms.cal_file_path)
 511        calibration_parameters["data_name"] = str(gcms.cal_file_path.stem)
 512        calibration_parameters["calibration_method"] = ""
 513
 514        return calibration_parameters
 515
 516    def get_blank_stats(self, gcms):
 517        """Get statistics about the GC-MS blank."""
 518        blank_parameters = {}
 519
 520        blank_parameters["data_name"] = "ni"
 521        blank_parameters["blank_id"] = "ni"
 522        blank_parameters["data_url"] = "ni"
 523        blank_parameters["has_input"] = "ni"
 524        blank_parameters["common_features_to_blank"] = "ni"
 525
 526        return blank_parameters
 527
 528    def get_instrument_metadata(self, gcms):
 529        """Get metadata about the GC-MS instrument."""
 530        instrument_metadata = {}
 531
 532        instrument_metadata["analyzer"] = gcms.analyzer
 533        instrument_metadata["instrument_label"] = gcms.instrument_label
 534        instrument_metadata["instrument_id"] = uuid.uuid4().hex
 535
 536        return instrument_metadata
 537
 538    def get_data_metadata(self, gcms, id_label, output_path):
 539        """Get metadata about the GC-MS data.
 540
 541        Parameters:
 542        ----------
 543        gcms : object
 544            The low resolution GCMS object.
 545        id_label : str
 546            The ID label for the data.
 547        output_path : str
 548            The output file path.
 549
 550        Returns:
 551        -------
 552        dict
 553            A dictionary containing the data metadata.
 554        """
 555        if isinstance(output_path, str):
 556            output_path = Path(output_path)
 557
 558        paramaters_path = output_path.with_suffix(".json")
 559
 560        if paramaters_path.exists():
 561            with paramaters_path.open() as current_param:
 562                metadata = json.load(current_param)
 563                data_metadata = metadata.get("Data")
 564        else:
 565            data_metadata = {}
 566            data_metadata["data_name"] = []
 567            data_metadata["input_data_url"] = []
 568            data_metadata["has_input"] = []
 569
 570        data_metadata["data_name"].append(gcms.sample_name)
 571        data_metadata["input_data_url"].append(str(gcms.file_location))
 572        data_metadata["has_input"].append(id_label + corems_md5(gcms.file_location))
 573
 574        data_metadata["output_data_name"] = str(output_path.stem)
 575        data_metadata["output_data_url"] = str(output_path)
 576        data_metadata["has_output"] = id_label + corems_md5(output_path)
 577
 578        return data_metadata
 579
 580    def get_parameters_json(self, gcms, id_label, output_path):
 581        """Get the parameters as a JSON string.
 582
 583        Parameters:
 584        ----------
 585        gcms : GCMS object
 586            The low resolution GCMS object.
 587        id_label : str
 588            The ID label for the data.
 589        output_path : str
 590            The output file path.
 591
 592        Returns:
 593        -------
 594        str
 595            The parameters as a JSON string.
 596        """
 597
 598        output_parameters_dict = {}
 599        output_parameters_dict["Data"] = self.get_data_metadata(
 600            gcms, id_label, output_path
 601        )
 602        output_parameters_dict["Stats"] = self.get_data_stats(gcms)
 603        output_parameters_dict["Calibration"] = self.get_calibration_stats(
 604            gcms, id_label
 605        )
 606        output_parameters_dict["Blank"] = self.get_blank_stats(gcms)
 607        output_parameters_dict["Instrument"] = self.get_instrument_metadata(gcms)
 608        corems_dict_setting = parameter_to_dict.get_dict_data_gcms(gcms)
 609        corems_dict_setting["corems_version"] = __version__
 610        output_parameters_dict["CoreMSParameters"] = corems_dict_setting
 611        output_parameters_dict["has_metabolite"] = gcms.metabolites_data
 612        output = json.dumps(
 613            output_parameters_dict, sort_keys=False, indent=4, separators=(",", ": ")
 614        )
 615
 616        return output
 617
 618    def write_settings(self, output_path, gcms, id_label="emsl:"):
 619        """Write the settings to a JSON file.
 620
 621        Parameters:
 622        ----------
 623        output_path : str
 624            The output file path.
 625        gcms : GCMS object
 626            The low resolution GCMS object.
 627        id_label : str
 628            The ID label for the data. Default is "emsl:".
 629
 630        """
 631
 632        output = self.get_parameters_json(gcms, id_label, output_path)
 633
 634        with open(
 635            output_path.with_suffix(".json"),
 636            "w",
 637            encoding="utf8",
 638        ) as outfile:
 639            outfile.write(output)
 640
 641    def get_list_dict_data(self, gcms, include_no_match=True, no_match_inline=False):
 642        """Get the exported data as a list of dictionaries.
 643
 644        Parameters:
 645        ----------
 646        gcms : object
 647            The low resolution GCMS object.
 648        include_no_match : bool, optional
 649            Whether to include no match data. Default is True.
 650        no_match_inline : bool, optional
 651            Whether to include no match data inline. Default is False.
 652
 653        Returns:
 654        -------
 655        list
 656            The exported data as a list of dictionaries.
 657        """
 658
 659        output_score_method = gcms.molecular_search_settings.output_score_method
 660
 661        dict_data_list = []
 662
 663        def add_match_dict_data():
 664            derivatization = "{}:{}:{}".format(
 665                compound_obj.classify,
 666                compound_obj.derivativenum,
 667                compound_obj.derivatization,
 668            )
 669            out_dict = {
 670                "Sample name": gcms.sample_name,
 671                "Peak Index": gcpeak_index,
 672                "Retention Time": gc_peak.retention_time,
 673                "Retention Time Ref": compound_obj.retention_time,
 674                "Peak Height": gc_peak.tic,
 675                "Peak Area": gc_peak.area,
 676                "Retention index": gc_peak.ri,
 677                "Retention index Ref": compound_obj.ri,
 678                "Retention Index Score": compound_obj.ri_score,
 679                "Spectral Similarity Score": compound_obj.spectral_similarity_score,
 680                "Similarity Score": compound_obj.similarity_score,
 681                "Compound Name": compound_obj.name,
 682                "Chebi ID": compound_obj.metadata.chebi,
 683                "Kegg Compound ID": compound_obj.metadata.kegg,
 684                "Inchi": compound_obj.metadata.inchi,
 685                "Inchi Key": compound_obj.metadata.inchikey,
 686                "Smiles": compound_obj.metadata.smiles,
 687                "Molecular Formula": compound_obj.formula,
 688                "IUPAC Name": compound_obj.metadata.iupac_name,
 689                "Traditional Name": compound_obj.metadata.traditional_name,
 690                "Common Name": compound_obj.metadata.common_name,
 691                "Derivatization": derivatization,
 692            }
 693
 694            if self.gcms.molecular_search_settings.exploratory_mode:
 695                out_dict.update(
 696                    {
 697                        "Weighted Cosine Correlation": compound_obj.spectral_similarity_scores.get(
 698                            "weighted_cosine_correlation"
 699                        ),
 700                        "Cosine Correlation": compound_obj.spectral_similarity_scores.get(
 701                            "cosine_correlation"
 702                        ),
 703                        "Stein Scott Similarity": compound_obj.spectral_similarity_scores.get(
 704                            "stein_scott_similarity"
 705                        ),
 706                        "Pearson Correlation": compound_obj.spectral_similarity_scores.get(
 707                            "pearson_correlation"
 708                        ),
 709                        "Spearman Correlation": compound_obj.spectral_similarity_scores.get(
 710                            "spearman_correlation"
 711                        ),
 712                        "Kendall Tau Correlation": compound_obj.spectral_similarity_scores.get(
 713                            "kendall_tau_correlation"
 714                        ),
 715                        "DFT Correlation": compound_obj.spectral_similarity_scores.get(
 716                            "dft_correlation"
 717                        ),
 718                        "DWT Correlation": compound_obj.spectral_similarity_scores.get(
 719                            "dwt_correlation"
 720                        ),
 721                        "Euclidean Distance": compound_obj.spectral_similarity_scores.get(
 722                            "euclidean_distance"
 723                        ),
 724                        "Manhattan Distance": compound_obj.spectral_similarity_scores.get(
 725                            "manhattan_distance"
 726                        ),
 727                        "Jaccard Distance": compound_obj.spectral_similarity_scores.get(
 728                            "jaccard_distance"
 729                        ),
 730                    }
 731                )
 732                for method in methods_name:
 733                    out_dict[methods_name.get(method)] = (
 734                        compound_obj.spectral_similarity_scores.get(method)
 735                    )
 736
 737            dict_data_list.append(out_dict)
 738
 739        def add_no_match_dict_data():
 740            dict_data_list.append(
 741                {
 742                    "Sample name": gcms.sample_name,
 743                    "Peak Index": gcpeak_index,
 744                    "Retention Time": gc_peak.retention_time,
 745                    "Peak Height": gc_peak.tic,
 746                    "Peak Area": gc_peak.area,
 747                    "Retention index": gc_peak.ri,
 748                }
 749            )
 750
 751        for gcpeak_index, gc_peak in enumerate(gcms.sorted_gcpeaks):
 752            # check if there is a compound candidate
 753            if gc_peak:
 754                if output_score_method == "highest_sim_score":
 755                    compound_obj = gc_peak.highest_score_compound
 756                    add_match_dict_data()
 757
 758                elif output_score_method == "highest_ss":
 759                    compound_obj = gc_peak.highest_ss_compound
 760                    add_match_dict_data()
 761
 762                else:
 763                    for compound_obj in gc_peak:
 764                        add_match_dict_data()  # add monoisotopic peak
 765
 766            else:
 767                # include not_match
 768                if include_no_match and no_match_inline:
 769                    add_no_match_dict_data()
 770
 771        if include_no_match and not no_match_inline:
 772            for gcpeak_index, gc_peak in enumerate(gcms.sorted_gcpeaks):
 773                if not gc_peak:
 774                    add_no_match_dict_data()
 775
 776        return dict_data_list
 777
 778
 779class HighResMassSpectraExport(HighResMassSpecExport):
 780    """A class to export high resolution mass spectra data.
 781
 782    This class provides methods to export high resolution mass spectra data to various formats
 783    such as Excel, CSV, HDF5, and Pandas DataFrame.
 784
 785    Parameters
 786    ----------
 787    out_file_path : str | Path
 788        The output file path.
 789    mass_spectra : object
 790        The high resolution mass spectra object.
 791    output_type : str, optional
 792        The output type. Default is 'excel'.
 793
 794    Attributes
 795    ----------
 796    output_file : Path
 797        The output file path without suffix
 798    dir_loc : Path
 799        The directory location for the output file,
 800        by default this will be the output_file + ".corems" and all output files will be
 801        written into this location
 802    mass_spectra : MassSpectraBase
 803        The high resolution mass spectra object.
 804    """
 805
 806    def __init__(self, out_file_path, mass_spectra, output_type="excel"):
 807        super().__init__(
 808            out_file_path=out_file_path, mass_spectrum=None, output_type=output_type
 809        )
 810
 811        self.dir_loc = Path(out_file_path + ".corems")
 812        self.dir_loc.mkdir(exist_ok=True)
 813        # Place the output file in the directory
 814        self.output_file = self.dir_loc / Path(out_file_path).name
 815        self._output_type = output_type  # 'excel', 'csv', 'pandas' or 'hdf5'
 816        self.mass_spectra = mass_spectra
 817        self.atoms_order_list = None
 818        self._init_columns()
 819
 820    def get_pandas_df(self):
 821        """Get the mass spectra as a list of Pandas DataFrames."""
 822
 823        list_df = []
 824
 825        for mass_spectrum in self.mass_spectra:
 826            columns = self.columns_label + self.get_all_used_atoms_in_order(
 827                mass_spectrum
 828            )
 829
 830            dict_data_list = self.get_list_dict_data(mass_spectrum)
 831
 832            df = DataFrame(dict_data_list, columns=columns)
 833
 834            scan_number = mass_spectrum.scan_number
 835
 836            df.name = str(self.output_file) + "_" + str(scan_number)
 837
 838            list_df.append(df)
 839
 840        return list_df
 841
 842    def to_pandas(self, write_metadata=True):
 843        """Export the data to a Pandas DataFrame and save it as a pickle file.
 844
 845        Parameters:
 846        ----------
 847        write_metadata : bool, optional
 848            Whether to write metadata to the output file. Default is True.
 849        """
 850
 851        for mass_spectrum in self.mass_spectra:
 852            columns = self.columns_label + self.get_all_used_atoms_in_order(
 853                mass_spectrum
 854            )
 855
 856            dict_data_list = self.get_list_dict_data(mass_spectrum)
 857
 858            df = DataFrame(dict_data_list, columns=columns)
 859
 860            scan_number = mass_spectrum.scan_number
 861
 862            out_filename = Path(
 863                "%s_scan%s%s" % (self.output_file, str(scan_number), ".pkl")
 864            )
 865
 866            df.to_pickle(self.dir_loc / out_filename)
 867
 868            if write_metadata:
 869                self.write_settings(
 870                    self.dir_loc / out_filename.with_suffix(""), mass_spectrum
 871                )
 872
 873    def to_excel(self, write_metadata=True):
 874        """Export the data to an Excel file.
 875
 876        Parameters:
 877        ----------
 878        write_metadata : bool, optional
 879            Whether to write metadata to the output file. Default is True.
 880        """
 881        for mass_spectrum in self.mass_spectra:
 882            columns = self.columns_label + self.get_all_used_atoms_in_order(
 883                mass_spectrum
 884            )
 885
 886            dict_data_list = self.get_list_dict_data(mass_spectrum)
 887
 888            df = DataFrame(dict_data_list, columns=columns)
 889
 890            scan_number = mass_spectrum.scan_number
 891
 892            out_filename = Path(
 893                "%s_scan%s%s" % (self.output_file, str(scan_number), ".xlsx")
 894            )
 895
 896            df.to_excel(self.dir_loc / out_filename)
 897
 898            if write_metadata:
 899                self.write_settings(
 900                    self.dir_loc / out_filename.with_suffix(""), mass_spectrum
 901                )
 902
 903    def to_csv(self, write_metadata=True):
 904        """Export the data to a CSV file.
 905
 906        Parameters:
 907        ----------
 908        write_metadata : bool, optional
 909            Whether to write metadata to the output file. Default is True.
 910        """
 911        import csv
 912
 913        for mass_spectrum in self.mass_spectra:
 914            columns = self.columns_label + self.get_all_used_atoms_in_order(
 915                mass_spectrum
 916            )
 917
 918            scan_number = mass_spectrum.scan_number
 919
 920            dict_data_list = self.get_list_dict_data(mass_spectrum)
 921
 922            out_filename = Path(
 923                "%s_scan%s%s" % (self.output_file, str(scan_number), ".csv")
 924            )
 925
 926            with open(self.dir_loc / out_filename, "w", newline="") as csvfile:
 927                writer = csv.DictWriter(csvfile, fieldnames=columns)
 928                writer.writeheader()
 929                for data in dict_data_list:
 930                    writer.writerow(data)
 931
 932            if write_metadata:
 933                self.write_settings(
 934                    self.dir_loc / out_filename.with_suffix(""), mass_spectrum
 935                )
 936
 937    def get_mass_spectra_attrs(self):
 938        """Get the mass spectra attributes as a JSON string.
 939
 940        Parameters:
 941        ----------
 942        mass_spectra : object
 943            The high resolution mass spectra object.
 944
 945        Returns:
 946        -------
 947        str
 948            The mass spectra attributes as a JSON string.
 949        """
 950        dict_ms_attrs = {}
 951        dict_ms_attrs["analyzer"] = self.mass_spectra.analyzer
 952        dict_ms_attrs["instrument_label"] = self.mass_spectra.instrument_label
 953        dict_ms_attrs["sample_name"] = self.mass_spectra.sample_name
 954
 955        return json.dumps(
 956            dict_ms_attrs, sort_keys=False, indent=4, separators=(",", ": ")
 957        )
 958
 959    def to_hdf(self, overwrite=False, export_raw=True):
 960        """Export the data to an HDF5 file.
 961
 962        Parameters
 963        ----------
 964        overwrite : bool, optional
 965            Whether to overwrite the output file. Default is False.
 966        export_raw : bool, optional
 967            Whether to export the raw mass spectra data. Default is True.
 968        """
 969        if overwrite:
 970            if self.output_file.with_suffix(".hdf5").exists():
 971                self.output_file.with_suffix(".hdf5").unlink()
 972
 973        with h5py.File(self.output_file.with_suffix(".hdf5"), "a") as hdf_handle:
 974            if not hdf_handle.attrs.get("date_utc"):
 975                # Set metadata for all mass spectra
 976                timenow = str(
 977                    datetime.now(timezone.utc).strftime("%d/%m/%Y %H:%M:%S %Z")
 978                )
 979                hdf_handle.attrs["date_utc"] = timenow
 980                hdf_handle.attrs["filename"] = self.mass_spectra.file_location.name
 981                hdf_handle.attrs["data_structure"] = "mass_spectra"
 982                hdf_handle.attrs["analyzer"] = self.mass_spectra.analyzer
 983                hdf_handle.attrs["instrument_label"] = (
 984                    self.mass_spectra.instrument_label
 985                )
 986                hdf_handle.attrs["sample_name"] = self.mass_spectra.sample_name
 987                hdf_handle.attrs["polarity"] = self.mass_spectra.polarity
 988                hdf_handle.attrs["parser_type"] = (
 989                    self.mass_spectra.spectra_parser_class.__name__
 990                )
 991                hdf_handle.attrs["original_file_location"] = (
 992                    self.mass_spectra.file_location._str
 993                )
 994
 995            if "mass_spectra" not in hdf_handle:
 996                mass_spectra_group = hdf_handle.create_group("mass_spectra")
 997            else:
 998                mass_spectra_group = hdf_handle.get("mass_spectra")
 999
1000            for mass_spectrum in self.mass_spectra:
1001                group_key = str(int(mass_spectrum.scan_number))
1002
1003                self.add_mass_spectrum_to_hdf5(
1004                    hdf_handle, mass_spectrum, group_key, mass_spectra_group, export_raw
1005                )
1006
1007
1008class LCMSExport(HighResMassSpectraExport):
1009    """A class to export high resolution LC-MS data.
1010
1011    This class provides methods to export high resolution LC-MS data to HDF5.
1012
1013    Parameters
1014    ----------
1015    out_file_path : str | Path
1016        The output file path, do not include the file extension.
1017    lcms_object : LCMSBase
1018        The high resolution lc-ms object.
1019    """
1020
1021    def __init__(self, out_file_path, mass_spectra):
1022        super().__init__(out_file_path, mass_spectra, output_type="hdf5")
1023
1024    def to_hdf(self, overwrite=False, save_parameters=True, parameter_format="toml"):
1025        """Export the data to an HDF5.
1026
1027        Parameters
1028        ----------
1029        overwrite : bool, optional
1030            Whether to overwrite the output file. Default is False.
1031        save_parameters : bool, optional
1032            Whether to save the parameters as a separate json or toml file. Default is True.
1033        parameter_format : str, optional
1034            The format to save the parameters in. Default is 'toml'.
1035
1036        Raises
1037        ------
1038        ValueError
1039            If parameter_format is not 'json' or 'toml'.
1040        """
1041        export_profile_spectra = (
1042            self.mass_spectra.parameters.lc_ms.export_profile_spectra
1043        )
1044
1045        # Write the mass spectra data to the hdf5 file
1046        super().to_hdf(overwrite=overwrite, export_raw=export_profile_spectra)
1047
1048        # Write scan info, ms_unprocessed, mass features, eics, and ms2_search results to the hdf5 file
1049        with h5py.File(self.output_file.with_suffix(".hdf5"), "a") as hdf_handle:
1050            # Add scan_info to hdf5 file
1051            if "scan_info" not in hdf_handle:
1052                scan_info_group = hdf_handle.create_group("scan_info")
1053                for k, v in self.mass_spectra._scan_info.items():
1054                    array = np.array(list(v.values()))
1055                    if array.dtype.str[0:2] == "<U":
1056                        array = array.astype("S")
1057                    scan_info_group.create_dataset(k, data=array)
1058
1059            # Add ms_unprocessed to hdf5 file
1060            export_unprocessed_ms1 = (
1061                self.mass_spectra.parameters.lc_ms.export_unprocessed_ms1
1062            )
1063            if self.mass_spectra._ms_unprocessed and export_unprocessed_ms1:
1064                if "ms_unprocessed" not in hdf_handle:
1065                    ms_unprocessed_group = hdf_handle.create_group("ms_unprocessed")
1066                else:
1067                    ms_unprocessed_group = hdf_handle.get("ms_unprocessed")
1068                for k, v in self.mass_spectra._ms_unprocessed.items():
1069                    array = np.array(v)
1070                    ms_unprocessed_group.create_dataset(str(k), data=array)
1071
1072            # Add LCMS mass features to hdf5 file
1073            if len(self.mass_spectra.mass_features) > 0:
1074                if "mass_features" not in hdf_handle:
1075                    mass_features_group = hdf_handle.create_group("mass_features")
1076                else:
1077                    mass_features_group = hdf_handle.get("mass_features")
1078
1079                # Create group for each mass feature, with key as the mass feature id
1080                for k, v in self.mass_spectra.mass_features.items():
1081                    mass_features_group.create_group(str(k))
1082                    # Loop through each of the mass feature attributes and add them as attributes (if single value) or datasets (if array)
1083                    for k2, v2 in v.__dict__.items():
1084                        if v2 is not None:
1085                            # Check if the attribute is an integer or float and set as an attribute in the mass feature group
1086                            if k2 not in [
1087                                "chromatogram_parent",
1088                                "ms2_mass_spectra",
1089                                "mass_spectrum",
1090                                "_eic_data",
1091                                "ms2_similarity_results",
1092                            ]:
1093                                if k2 == "ms2_scan_numbers":
1094                                    array = np.array(v2)
1095                                    mass_features_group[str(k)].create_dataset(
1096                                        str(k2), data=array
1097                                    )
1098                                elif k2 == "_half_height_width":
1099                                    array = np.array(v2)
1100                                    mass_features_group[str(k)].create_dataset(
1101                                        str(k2), data=array
1102                                    )
1103                                elif k2 == "_ms_deconvoluted_idx":
1104                                    array = np.array(v2)
1105                                    mass_features_group[str(k)].create_dataset(
1106                                        str(k2), data=array
1107                                    )
1108                                elif k2 == "associated_mass_features_deconvoluted":
1109                                    array = np.array(v2)
1110                                    mass_features_group[str(k)].create_dataset(
1111                                        str(k2), data=array
1112                                    )
1113                                elif (
1114                                    isinstance(v2, int)
1115                                    or isinstance(v2, float)
1116                                    or isinstance(v2, str)
1117                                    or isinstance(v2, np.integer)
1118                                    or isinstance(v2, np.bool_)
1119                                ):
1120                                    mass_features_group[str(k)].attrs[str(k2)] = v2
1121                                else:
1122                                    raise TypeError(
1123                                        f"Attribute {k2} is not an integer, float, or string and cannot be added to the hdf5 file"
1124                                    )
1125
1126            # Add EIC data to hdf5 file
1127            export_eics = self.mass_spectra.parameters.lc_ms.export_eics
1128            if len(self.mass_spectra.eics) > 0 and export_eics:
1129                if "eics" not in hdf_handle:
1130                    eic_group = hdf_handle.create_group("eics")
1131                else:
1132                    eic_group = hdf_handle.get("eics")
1133
1134                # Create group for each eic
1135                for k, v in self.mass_spectra.eics.items():
1136                    eic_group.create_group(str(k))
1137                    eic_group[str(k)].attrs["mz"] = k
1138                    # Loop through each of the attributes and add them as datasets (if array)
1139                    for k2, v2 in v.__dict__.items():
1140                        if v2 is not None:
1141                            array = np.array(v2)
1142                            eic_group[str(k)].create_dataset(str(k2), data=array)
1143
1144            # Add ms2_search results to hdf5 file
1145            if len(self.mass_spectra.spectral_search_results) > 0:
1146                if "spectral_search_results" not in hdf_handle:
1147                    spectral_search_results = hdf_handle.create_group(
1148                        "spectral_search_results"
1149                    )
1150                else:
1151                    spectral_search_results = hdf_handle.get("spectral_search_results")
1152                # Create group for each search result by ms2_scan / precursor_mz
1153                for k, v in self.mass_spectra.spectral_search_results.items():
1154                    spectral_search_results.create_group(str(k))
1155                    for k2, v2 in v.items():
1156                        spectral_search_results[str(k)].create_group(str(k2))
1157                        spectral_search_results[str(k)][str(k2)].attrs[
1158                            "precursor_mz"
1159                        ] = v2.precursor_mz
1160                        spectral_search_results[str(k)][str(k2)].attrs[
1161                            "query_spectrum_id"
1162                        ] = v2.query_spectrum_id
1163                        # Loop through each of the attributes and add them as datasets (if array)
1164                        for k3, v3 in v2.__dict__.items():
1165                            if v3 is not None and k3 not in [
1166                                "query_spectrum",
1167                                "precursor_mz",
1168                                "query_spectrum_id",
1169                            ]:
1170                                if k3 == "query_frag_types" or k3 == "ref_frag_types":
1171                                    v3 = [", ".join(x) for x in v3]
1172                                if all(v3 is not None for v3 in v3):
1173                                    array = np.array(v3)
1174                                if array.dtype.str[0:2] == "<U":
1175                                    array = array.astype("S")
1176                                spectral_search_results[str(k)][str(k2)].create_dataset(
1177                                    str(k3), data=array
1178                                )
1179
1180        # Save parameters as separate json
1181        if save_parameters:
1182            # Check if parameter_format is valid
1183            if parameter_format not in ["json", "toml"]:
1184                raise ValueError("parameter_format must be 'json' or 'toml'")
1185
1186            if parameter_format == "json":
1187                dump_lcms_settings_json(
1188                    filename=self.output_file.with_suffix(".json"),
1189                    lcms_obj=self.mass_spectra,
1190                )
1191            elif parameter_format == "toml":
1192                dump_lcms_settings_toml(
1193                    filename=self.output_file.with_suffix(".toml"),
1194                    lcms_obj=self.mass_spectra,
1195                )
1196
1197class LCMSMetabolomicsExport(LCMSExport):
1198    """A class to export LCMS metabolite data.
1199
1200    This class provides methods to export LCMS metabolite data to various formats and summarize the metabolite report.
1201
1202    Parameters
1203    ----------
1204    out_file_path : str | Path
1205        The output file path, do not include the file extension.
1206    mass_spectra : object
1207        The high resolution mass spectra object.
1208    """
1209
1210    def __init__(self, out_file_path, mass_spectra):
1211        super().__init__(out_file_path, mass_spectra)
1212        self.ion_type_dict = ion_type_dict
1213    
1214    @staticmethod
1215    def get_ion_formula(neutral_formula, ion_type):
1216        """From a neutral formula and an ion type, return the formula of the ion.
1217
1218        Notes
1219        -----
1220        This is a static method.
1221        If the neutral_formula is not a string, this method will return None.
1222
1223        Parameters
1224        ----------
1225        neutral_formula : str
1226            The neutral formula, this should be a string form from the MolecularFormula class
1227            (e.g. 'C2 H4 O2', isotopes OK), or simple string (e.g. 'C2H4O2', no isotope handling in this case).
1228            In the case of a simple string, the atoms are parsed based on the presence of capital letters,
1229            e.g. MgCl2 is parsed as 'Mg Cl2.
1230        ion_type : str
1231            The ion type, e.g. 'protonated', '[M+H]+', '[M+Na]+', etc.
1232            See the self.ion_type_dict for the available ion types.
1233
1234        Returns
1235        -------
1236        str
1237            The formula of the ion as a string (like 'C2 H4 O2'); or None if the neutral_formula is not a string.
1238        """
1239        # If neutral_formula is not a string, return None
1240        if not isinstance(neutral_formula, str):
1241            return None
1242
1243        # Check if there are spaces in the formula (these are outputs of the MolecularFormula class and do not need to be processed before being passed to the class)
1244        if re.search(r"\s", neutral_formula):
1245            neutral_formula = MolecularFormula(neutral_formula, ion_charge=0)
1246        else:
1247            form_pre = re.sub(r"([A-Z])", r" \1", neutral_formula)[1:]
1248            elements = [re.findall(r"[A-Z][a-z]*", x) for x in form_pre.split()]
1249            counts = [re.findall(r"\d+", x) for x in form_pre.split()]
1250            neutral_formula = MolecularFormula(
1251                dict(
1252                    zip(
1253                        [x[0] for x in elements],
1254                        [int(x[0]) if x else 1 for x in counts],
1255                    )
1256                ),
1257                ion_charge=0,
1258            )
1259        neutral_formula_dict = neutral_formula.to_dict().copy()
1260
1261        adduct_add_dict = ion_type_dict[ion_type][0]
1262        for key in adduct_add_dict:
1263            if key in neutral_formula_dict.keys():
1264                neutral_formula_dict[key] += adduct_add_dict[key]
1265            else:
1266                neutral_formula_dict[key] = adduct_add_dict[key]
1267
1268        adduct_subtract = ion_type_dict[ion_type][1]
1269        for key in adduct_subtract:
1270            neutral_formula_dict[key] -= adduct_subtract[key]
1271
1272        return MolecularFormula(neutral_formula_dict, ion_charge=0).string
1273
1274    @staticmethod
1275    def get_isotope_type(ion_formula):
1276        """From an ion formula, return the 13C isotope type of the ion.
1277
1278        Notes
1279        -----
1280        This is a static method.
1281        If the ion_formula is not a string, this method will return None.
1282        This is currently only functional for 13C isotopes.
1283
1284        Parameters
1285        ----------
1286        ion_formula : str
1287            The formula of the ion, expected to be a string like 'C2 H4 O2'.
1288
1289        Returns
1290        -------
1291        str
1292            The isotope type of the ion, e.g. '13C1', '13C2', etc; or None if the ion_formula does not contain a 13C isotope.
1293
1294        Raises
1295        ------
1296        ValueError
1297            If the ion_formula is not a string.
1298        """
1299        if not isinstance(ion_formula, str):
1300            return None
1301
1302        if re.search(r"\s", ion_formula):
1303            ion_formula = MolecularFormula(ion_formula, ion_charge=0)
1304        else:
1305            raise ValueError('ion_formula should be a string like "C2 H4 O2"')
1306        ion_formula_dict = ion_formula.to_dict().copy()
1307
1308        try:
1309            iso_class = "13C" + str(ion_formula_dict.pop("13C"))
1310        except KeyError:
1311            iso_class = None
1312
1313        return iso_class
1314    
1315    def report_to_csv(self, molecular_metadata=None):
1316        """Create a report of the mass features and their annotations and save it as a CSV file.
1317
1318        Parameters
1319        ----------
1320        molecular_metadata : dict, optional
1321            The molecular metadata. Default is None.
1322        """
1323        report = self.to_report(molecular_metadata=molecular_metadata)
1324        out_file = self.output_file.with_suffix(".csv")
1325        report.to_csv(out_file, index=False)
1326    
1327    def clean_ms1_report(self, ms1_summary_full):
1328        """Clean the MS1 report.
1329
1330        Parameters
1331        ----------
1332        ms1_summary_full : DataFrame
1333            The full MS1 summary DataFrame.
1334
1335        Returns
1336        -------
1337        DataFrame
1338            The cleaned MS1 summary DataFrame.
1339        """
1340        ms1_summary_full = ms1_summary_full.reset_index()
1341        cols_to_keep = [
1342            "mf_id",
1343            "Molecular Formula",
1344            "Ion Type",
1345            "Calculated m/z",
1346            "m/z Error (ppm)",
1347            "m/z Error Score",
1348            "Is Isotopologue",
1349            "Isotopologue Similarity",
1350            "Confidence Score",
1351        ]
1352        ms1_summary = ms1_summary_full[cols_to_keep].copy()
1353        ms1_summary["ion_formula"] = [
1354            self.get_ion_formula(f, a)
1355            for f, a in zip(ms1_summary["Molecular Formula"], ms1_summary["Ion Type"])
1356        ]
1357        ms1_summary["isotopologue_type"] = [
1358            self.get_isotope_type(f) for f in ms1_summary["ion_formula"].tolist()
1359        ]
1360
1361        # Reorder columns
1362        ms1_summary = ms1_summary[
1363            [
1364                "mf_id",
1365                "ion_formula",
1366                "isotopologue_type",
1367                "Calculated m/z",
1368                "m/z Error (ppm)",
1369                "m/z Error Score",
1370                "Isotopologue Similarity",
1371                "Confidence Score",
1372            ]
1373        ]
1374
1375        # Set the index to mf_id
1376        ms1_summary = ms1_summary.set_index("mf_id")
1377
1378        return ms1_summary
1379    
1380    def summarize_ms2_report(self, ms2_annot_report):
1381        """
1382        Summarize the MS2 report.
1383
1384        Parameters
1385        ----------
1386        ms2_annot_report : DataFrame
1387            The MS2 annotation DataFrame with all annotations, output of mass_features_ms2_annot_to_df.
1388        
1389        Returns
1390        -------
1391        """
1392    
1393    def summarize_metabolomics_report(self, ms2_annot_report):
1394        """Summarize the MS2 hits for a metabolomics report
1395        
1396        Parameters
1397        ----------
1398        ms2_annot : DataFrame
1399            The MS2 annotation DataFrame with all annotations.
1400
1401        Returns
1402        -------
1403        DataFrame
1404            The summarized metabolomics report.
1405        """
1406        columns_to_drop = [
1407            "precursor_mz",
1408            "precursor_mz_error_ppm",
1409            "cas",
1410            "data_id",
1411            "iupac_name",
1412            "traditional_name",
1413            "common_name",
1414            "casno",
1415        ]
1416        ms2_annot = ms2_annot_report.drop(
1417            columns=[col for col in columns_to_drop if col in ms2_annot_report.columns]
1418        )
1419        
1420        # Prepare information about the search results, pulling out the best hit for the single report
1421        # Group by mf_id,ref_mol_id grab row with highest entropy similarity
1422        ms2_annot = ms2_annot.reset_index()
1423        # Add column called "n_spectra_contributing" that is the number of unique values in query_spectrum_id per mf_id,ref_mol_id
1424        ms2_annot["n_spectra_contributing"] = (
1425            ms2_annot.groupby(["mf_id", "ref_mol_id"])["query_spectrum_id"]
1426            .transform("nunique")
1427        )
1428        # Sort by entropy similarity
1429        ms2_annot = ms2_annot.sort_values(
1430            by=["mf_id", "ref_mol_id", "entropy_similarity"], ascending=[True, True, False]
1431        )
1432        best_entropy = ms2_annot.drop_duplicates(
1433            subset=["mf_id", "ref_mol_id"], keep="first"
1434        )
1435
1436        return best_entropy
1437
1438    def clean_ms2_report(self, metabolite_summary):
1439        """Clean the MS2 report.
1440
1441        Parameters
1442        ----------
1443        metabolite_summary : DataFrame
1444            The full metabolomics summary DataFrame.
1445
1446        Returns
1447        -------
1448        DataFrame
1449            The cleaned metabolomics summary DataFrame.
1450        """
1451        metabolite_summary = metabolite_summary.reset_index()
1452        metabolite_summary["ion_formula"] = [
1453            self.get_ion_formula(f, a)
1454            for f, a in zip(metabolite_summary["formula"], metabolite_summary["ref_ion_type"])
1455        ]
1456
1457        col_order = [
1458            "mf_id",
1459            "ion_formula",
1460            "ref_ion_type",
1461            "formula",
1462            "inchikey",
1463            "name",
1464            "inchi",
1465            "chebi",
1466            "smiles",
1467            "kegg",
1468            "cas",
1469            "database_name",
1470            "ref_ms_id",
1471            "entropy_similarity",
1472            "ref_mz_in_query_fract",
1473            "n_spectra_contributing",
1474        ]
1475
1476        # Reorder columns
1477        metabolite_summary = metabolite_summary[
1478            [col for col in col_order if col in metabolite_summary.columns]
1479        ]
1480
1481        # Convert chebi (if present) to int:
1482        if "chebi" in metabolite_summary.columns:
1483            metabolite_summary["chebi"] = metabolite_summary["chebi"].astype(
1484                "Int64", errors="ignore"
1485            )
1486
1487        # Set the index to mf_id
1488        metabolite_summary = metabolite_summary.set_index("mf_id")
1489
1490        return metabolite_summary
1491    
1492    def combine_reports(self, mf_report, ms1_annot_report, ms2_annot_report):
1493        """Combine the mass feature report with the MS1 and MS2 reports.
1494
1495        Parameters
1496        ----------
1497        mf_report : DataFrame
1498            The mass feature report DataFrame.
1499        ms1_annot_report : DataFrame
1500            The MS1 annotation report DataFrame.
1501        ms2_annot_report : DataFrame
1502            The MS2 annotation report DataFrame.
1503        """
1504        # If there is an ms1_annot_report, merge it with the mf_report
1505        if not ms1_annot_report.empty:
1506            # MS1 has been run and has molecular formula information
1507            mf_report = pd.merge(
1508                mf_report,
1509                ms1_annot_report,
1510                how="left",
1511                on=["mf_id", "isotopologue_type"],
1512            )
1513        if ms2_annot_report is not None:
1514            # pull out the records with ion_formula and drop the ion_formula column (these should be empty if MS1 molecular formula assignment is working correctly)
1515            mf_no_ion_formula = mf_report[mf_report["ion_formula"].isna()]
1516            mf_no_ion_formula = mf_no_ion_formula.drop(columns=["ion_formula"])
1517            mf_no_ion_formula = pd.merge(
1518                mf_no_ion_formula, ms2_annot_report, how="left", on=["mf_id"]
1519            )
1520
1521            # pull out the records with ion_formula
1522            mf_with_ion_formula = mf_report[~mf_report["ion_formula"].isna()]
1523            mf_with_ion_formula = pd.merge(
1524                mf_with_ion_formula,
1525                ms2_annot_report,
1526                how="left",
1527                on=["mf_id", "ion_formula"],
1528            )
1529
1530            # put back together
1531            mf_report = pd.concat([mf_no_ion_formula, mf_with_ion_formula])
1532
1533        # Rename colums
1534        rename_dict = {
1535            "mf_id": "Mass Feature ID",
1536            "scan_time": "Retention Time (min)",
1537            "mz": "m/z",
1538            "apex_scan": "Apex Scan Number",
1539            "intensity": "Intensity",
1540            "persistence": "Persistence",
1541            "area": "Area",
1542            "half_height_width": "Half Height Width (min)",
1543            "tailing_factor": "Tailing Factor",
1544            "dispersity_index": "Dispersity Index",
1545            "ms2_spectrum": "MS2 Spectrum",
1546            "monoisotopic_mf_id": "Monoisotopic Mass Feature ID",
1547            "isotopologue_type": "Isotopologue Type",
1548            "mass_spectrum_deconvoluted_parent": "Is Largest Ion after Deconvolution",
1549            "associated_mass_features": "Associated Mass Features after Deconvolution",
1550            "ion_formula": "Ion Formula",
1551            "formula": "Molecular Formula",
1552            "ref_ion_type": "Ion Type",
1553            "annot_level": "Lipid Annotation Level",
1554            "lipid_molecular_species_id": "Lipid Molecular Species",
1555            "lipid_summed_name": "Lipid Species",
1556            "lipid_subclass": "Lipid Subclass",
1557            "lipid_class": "Lipid Class",
1558            "lipid_category": "Lipid Category",
1559            "entropy_similarity": "Entropy Similarity",
1560            "ref_mz_in_query_fract": "Library mzs in Query (fraction)",
1561            "n_spectra_contributing": "Spectra with Annotation (n)",
1562        }
1563        mf_report = mf_report.rename(columns=rename_dict)
1564        mf_report["Sample Name"] = self.mass_spectra.sample_name
1565        mf_report["Polarity"] = self.mass_spectra.polarity
1566        mf_report = mf_report[
1567            ["Mass Feature ID", "Sample Name", "Polarity"]
1568            + [
1569                col
1570                for col in mf_report.columns
1571                if col not in ["Mass Feature ID", "Sample Name", "Polarity"]
1572            ]
1573        ]
1574
1575        # Reorder rows by "Mass Feature ID"
1576        mf_report = mf_report.sort_values("Mass Feature ID")
1577
1578        # Reset index
1579        mf_report = mf_report.reset_index(drop=True)
1580
1581        return mf_report
1582    
1583    def to_report(self, molecular_metadata=None):
1584        """Create a report of the mass features and their annotations.
1585
1586        Parameters
1587        ----------
1588        molecular_metadata : dict, optional
1589            The molecular metadata. Default is None.
1590
1591        Returns
1592        -------
1593        DataFrame
1594            The report as a Pandas DataFrame.
1595        """
1596        # Get mass feature dataframe
1597        mf_report = self.mass_spectra.mass_features_to_df()
1598        mf_report = mf_report.reset_index(drop=False)
1599
1600        # Get and clean ms1 annotation dataframe
1601        ms1_annot_report = self.mass_spectra.mass_features_ms1_annot_to_df().copy()
1602        ms1_annot_report = self.clean_ms1_report(ms1_annot_report)
1603        ms1_annot_report = ms1_annot_report.reset_index(drop=False)
1604
1605        # Get, summarize, and clean ms2 annotation dataframe
1606        ms2_annot_report = self.mass_spectra.mass_features_ms2_annot_to_df(
1607            molecular_metadata=molecular_metadata
1608        )
1609        if ms2_annot_report is not None and molecular_metadata is not None:
1610            ms2_annot_report = self.summarize_metabolomics_report(ms2_annot_report)
1611            ms2_annot_report = self.clean_ms2_report(ms2_annot_report)
1612            ms2_annot_report = ms2_annot_report.dropna(axis=1, how="all")
1613            ms2_annot_report = ms2_annot_report.reset_index(drop=False)
1614        else:
1615            ms2_annot_report = None
1616
1617        report = self.combine_reports(
1618            mf_report=mf_report,
1619            ms1_annot_report=ms1_annot_report,
1620            ms2_annot_report=ms2_annot_report
1621        )
1622
1623        return report
1624class LipidomicsExport(LCMSMetabolomicsExport):
1625    """A class to export lipidomics data.
1626
1627    This class provides methods to export lipidomics data to various formats and summarize the lipid report.
1628
1629    Parameters
1630    ----------
1631    out_file_path : str | Path
1632        The output file path, do not include the file extension.
1633    mass_spectra : object
1634        The high resolution mass spectra object.
1635    """
1636
1637    def __init__(self, out_file_path, mass_spectra):
1638        super().__init__(out_file_path, mass_spectra)
1639
1640    def summarize_lipid_report(self, ms2_annot):
1641        """Summarize the lipid report.
1642
1643        Parameters
1644        ----------
1645        ms2_annot : DataFrame
1646            The MS2 annotation DataFrame with all annotations.
1647
1648        Returns
1649        -------
1650        DataFrame
1651            The summarized lipid report.
1652        """
1653        # Drop unnecessary columns for easier viewing
1654        columns_to_drop = [
1655            "precursor_mz",
1656            "precursor_mz_error_ppm",
1657            "metabref_mol_id",
1658            "metabref_precursor_mz",
1659            "cas",
1660            "inchikey",
1661            "inchi",
1662            "chebi",
1663            "smiles",
1664            "kegg",
1665            "data_id",
1666            "iupac_name",
1667            "traditional_name",
1668            "common_name",
1669            "casno",
1670        ]
1671        ms2_annot = ms2_annot.drop(
1672            columns=[col for col in columns_to_drop if col in ms2_annot.columns]
1673        )
1674
1675        # If ion_types_excluded is not empty, remove those ion types
1676        ion_types_excluded = self.mass_spectra.parameters.mass_spectrum[
1677            "ms2"
1678        ].molecular_search.ion_types_excluded
1679        if len(ion_types_excluded) > 0:
1680            ms2_annot = ms2_annot[~ms2_annot["ref_ion_type"].isin(ion_types_excluded)]
1681
1682        # If mf_id is not present, check that the index name is mf_id and reset the index
1683        if "mf_id" not in ms2_annot.columns:
1684            if ms2_annot.index.name == "mf_id":
1685                ms2_annot = ms2_annot.reset_index()
1686            else:
1687                raise ValueError("mf_id is not present in the dataframe")
1688
1689        # Attempt to get consensus annotations to the MLF level
1690        mlf_results_all = []
1691        for mf_id in ms2_annot["mf_id"].unique():
1692            mlf_results_perid = []
1693            ms2_annot_mf = ms2_annot[ms2_annot["mf_id"] == mf_id].copy()
1694            #FIXME: Fix this - it's not giving what we want!
1695            ms2_annot_mf["n_spectra_contributing"] = len(ms2_annot_mf)
1696
1697            for query_scan in ms2_annot["query_spectrum_id"].unique():
1698                ms2_annot_sub = ms2_annot_mf[
1699                    ms2_annot_mf["query_spectrum_id"] == query_scan
1700                ].copy()
1701
1702                if ms2_annot_sub["lipid_summed_name"].nunique() == 1:
1703                    # If there is only one lipid_summed_name, let's try to get consensus molecular species annotation
1704                    if ms2_annot_sub["lipid_summed_name"].nunique() == 1:
1705                        ms2_annot_sub["entropy_max"] = (
1706                            ms2_annot_sub["entropy_similarity"]
1707                            == ms2_annot_sub["entropy_similarity"].max()
1708                        )
1709                        ms2_annot_sub["ref_match_fract_max"] = (
1710                            ms2_annot_sub["ref_mz_in_query_fract"]
1711                            == ms2_annot_sub["ref_mz_in_query_fract"].max()
1712                        )
1713                        ms2_annot_sub["frag_max"] = ms2_annot_sub[
1714                            "query_frag_types"
1715                        ].apply(lambda x: True if "MLF" in x else False)
1716
1717                        # New column that looks if there is a consensus between the ranks (one row that is highest in all ranks)
1718                        ms2_annot_sub["consensus"] = ms2_annot_sub[
1719                            ["entropy_max", "ref_match_fract_max", "frag_max"]
1720                        ].all(axis=1)
1721
1722                        # If there is a consensus, take the row with the highest entropy_similarity
1723                        if ms2_annot_sub["consensus"].any():
1724                            ms2_annot_sub = ms2_annot_sub[
1725                                ms2_annot_sub["entropy_similarity"]
1726                                == ms2_annot_sub["entropy_similarity"].max()
1727                            ].head(1)
1728                            mlf_results_perid.append(ms2_annot_sub)
1729            if len(mlf_results_perid) == 0:
1730                mlf_results_perid = pd.DataFrame()
1731            else:
1732                mlf_results_perid = pd.concat(mlf_results_perid)
1733                if mlf_results_perid["name"].nunique() == 1:
1734                    mlf_results_perid = mlf_results_perid[
1735                        mlf_results_perid["entropy_similarity"]
1736                        == mlf_results_perid["entropy_similarity"].max()
1737                    ].head(1)
1738                else:
1739                    mlf_results_perid = pd.DataFrame()
1740                mlf_results_all.append(mlf_results_perid)
1741
1742        # These are the consensus annotations to the MLF level
1743        if len(mlf_results_all) > 0:
1744            mlf_results_all = pd.concat(mlf_results_all)
1745            mlf_results_all["annot_level"] = mlf_results_all["structure_level"]
1746        else:
1747            # Make an empty dataframe
1748            mlf_results_all = ms2_annot.head(0)
1749
1750        # For remaining mf_ids, try to get a consensus annotation to the species level
1751        species_results_all = []
1752        # Remove mf_ids that have consensus annotations to the MLF level
1753        ms2_annot_spec = ms2_annot[
1754            ~ms2_annot["mf_id"].isin(mlf_results_all["mf_id"].unique())
1755        ]
1756        for mf_id in ms2_annot_spec["mf_id"].unique():
1757            # Do all the hits have the same lipid_summed_name?
1758            ms2_annot_sub = ms2_annot_spec[ms2_annot_spec["mf_id"] == mf_id].copy()
1759            ms2_annot_sub["n_spectra_contributing"] = len(ms2_annot_sub)
1760
1761            if ms2_annot_sub["lipid_summed_name"].nunique() == 1:
1762                # Grab the highest entropy_similarity result
1763                ms2_annot_sub = ms2_annot_sub[
1764                    ms2_annot_sub["entropy_similarity"]
1765                    == ms2_annot_sub["entropy_similarity"].max()
1766                ].head(1)
1767                species_results_all.append(ms2_annot_sub)
1768
1769        # These are the consensus annotations to the species level
1770        if len(species_results_all) > 0:
1771            species_results_all = pd.concat(species_results_all)
1772            species_results_all["annot_level"] = "species"
1773        else:
1774            # Make an empty dataframe
1775            species_results_all = ms2_annot.head(0)
1776
1777        # Deal with the remaining mf_ids that do not have consensus annotations to the species level or MLF level
1778        # Remove mf_ids that have consensus annotations to the species level
1779        ms2_annot_remaining = ms2_annot_spec[
1780            ~ms2_annot_spec["mf_id"].isin(species_results_all["mf_id"].unique())
1781        ]
1782        no_consensus = []
1783        for mf_id in ms2_annot_remaining["mf_id"].unique():
1784            id_sub = []
1785            id_no_con = []
1786            ms2_annot_sub_mf = ms2_annot_remaining[
1787                ms2_annot_remaining["mf_id"] == mf_id
1788            ].copy()
1789            for query_scan in ms2_annot_sub_mf["query_spectrum_id"].unique():
1790                ms2_annot_sub = ms2_annot_sub_mf[
1791                    ms2_annot_sub_mf["query_spectrum_id"] == query_scan
1792                ].copy()
1793
1794                # New columns for ranking [HIGHER RANK = BETTER]
1795                ms2_annot_sub["entropy_max"] = (
1796                    ms2_annot_sub["entropy_similarity"]
1797                    == ms2_annot_sub["entropy_similarity"].max()
1798                )
1799                ms2_annot_sub["ref_match_fract_max"] = (
1800                    ms2_annot_sub["ref_mz_in_query_fract"]
1801                    == ms2_annot_sub["ref_mz_in_query_fract"].max()
1802                )
1803                ms2_annot_sub["frag_max"] = ms2_annot_sub["query_frag_types"].apply(
1804                    lambda x: True if "MLF" in x else False
1805                )
1806
1807                # New column that looks if there is a consensus between the ranks (one row that is highest in all ranks)
1808                ms2_annot_sub["consensus"] = ms2_annot_sub[
1809                    ["entropy_max", "ref_match_fract_max", "frag_max"]
1810                ].all(axis=1)
1811                ms2_annot_sub_con = ms2_annot_sub[ms2_annot_sub["consensus"]]
1812                id_sub.append(ms2_annot_sub_con)
1813                id_no_con.append(ms2_annot_sub)
1814            id_sub = pd.concat(id_sub)
1815            id_no_con = pd.concat(id_no_con)
1816
1817            # Scenario 1: Multiple scans are being resolved to different MLFs [could be coelutions and should both be kept and annotated to MS level]
1818            if (
1819                id_sub["query_frag_types"]
1820                .apply(lambda x: True if "MLF" in x else False)
1821                .all()
1822                and len(id_sub) > 0
1823            ):
1824                idx = id_sub.groupby("name")["entropy_similarity"].idxmax()
1825                id_sub = id_sub.loc[idx]
1826                # Reorder so highest entropy_similarity is first
1827                id_sub = id_sub.sort_values("entropy_similarity", ascending=False)
1828                id_sub["annot_level"] = id_sub["structure_level"]
1829                no_consensus.append(id_sub)
1830
1831            # Scenario 2: Multiple scans are being resolved to different species, keep both and annotate to appropriate level
1832            elif len(id_sub) == 0:
1833                for lipid_summed_name in id_no_con["lipid_summed_name"].unique():
1834                    summed_sub = id_no_con[
1835                        id_no_con["lipid_summed_name"] == lipid_summed_name
1836                    ]
1837                    # Any consensus to MLF?
1838                    if summed_sub["consensus"].any():
1839                        summed_sub = summed_sub[summed_sub["consensus"]]
1840                        summed_sub["annot_level"] = summed_sub["structure_level"]
1841                        no_consensus.append(summed_sub)
1842                    else:
1843                        # Grab the highest entropy_similarity, if there are multiple, grab the first one
1844                        summed_sub = summed_sub[
1845                            summed_sub["entropy_similarity"]
1846                            == summed_sub["entropy_similarity"].max()
1847                        ].head(1)
1848                        # get first row
1849                        summed_sub["annot_level"] = "species"
1850                        summed_sub["name"] = ""
1851                        no_consensus.append(summed_sub)
1852            else:
1853                raise ValueError("Unexpected scenario for summarizing mf_id: ", mf_id)
1854
1855        if len(no_consensus) > 0:
1856            no_consensus = pd.concat(no_consensus)
1857        else:
1858            no_consensus = ms2_annot.head(0)
1859
1860        # Combine all the consensus annotations and reformat the dataframe for output
1861        species_results_all = species_results_all.drop(columns=["name"])
1862        species_results_all["lipid_molecular_species_id"] = ""
1863        mlf_results_all["lipid_molecular_species_id"] = mlf_results_all["name"]
1864        no_consensus["lipid_molecular_species_id"] = no_consensus["name"]
1865        consensus_annotations = pd.concat(
1866            [mlf_results_all, species_results_all, no_consensus]
1867        )
1868        consensus_annotations = consensus_annotations.sort_values(
1869            "mf_id", ascending=True
1870        )
1871        cols_to_keep = [
1872            "mf_id",
1873            "ref_ion_type",
1874            "entropy_similarity",
1875            "ref_mz_in_query_fract",
1876            "lipid_molecular_species_id",
1877            "lipid_summed_name",
1878            "lipid_subclass",
1879            "lipid_class",
1880            "lipid_category",
1881            "formula",
1882            "annot_level",
1883            "n_spectra_contributing",
1884        ]
1885        consensus_annotations = consensus_annotations[cols_to_keep]
1886        consensus_annotations = consensus_annotations.set_index("mf_id")
1887
1888        return consensus_annotations
1889
1890    def clean_ms2_report(self, lipid_summary):
1891        """Clean the MS2 report.
1892
1893        Parameters
1894        ----------
1895        lipid_summary : DataFrame
1896            The full lipid summary DataFrame.
1897
1898        Returns
1899        -------
1900        DataFrame
1901            The cleaned lipid summary DataFrame.
1902        """
1903        lipid_summary = lipid_summary.reset_index()
1904        lipid_summary["ion_formula"] = [
1905            self.get_ion_formula(f, a)
1906            for f, a in zip(lipid_summary["formula"], lipid_summary["ref_ion_type"])
1907        ]
1908
1909        # Reorder columns
1910        lipid_summary = lipid_summary[
1911            [
1912                "mf_id",
1913                "ion_formula",
1914                "ref_ion_type",
1915                "formula",
1916                "annot_level",
1917                "lipid_molecular_species_id",
1918                "lipid_summed_name",
1919                "lipid_subclass",
1920                "lipid_class",
1921                "lipid_category",
1922                "entropy_similarity",
1923                "ref_mz_in_query_fract",
1924                "n_spectra_contributing",
1925            ]
1926        ]
1927
1928        # Set the index to mf_id
1929        lipid_summary = lipid_summary.set_index("mf_id")
1930
1931        return lipid_summary
1932
1933    def to_report(self, molecular_metadata=None):
1934        """Create a report of the mass features and their annotations.
1935
1936        Parameters
1937        ----------
1938        molecular_metadata : dict, optional
1939            The molecular metadata. Default is None.
1940
1941        Returns
1942        -------
1943        DataFrame
1944            The report of the mass features and their annotations.
1945
1946        Notes
1947        -----
1948        The report will contain the mass features and their annotations from MS1 and MS2 (if available).
1949        """
1950        # Get mass feature dataframe
1951        mf_report = self.mass_spectra.mass_features_to_df()
1952        mf_report = mf_report.reset_index(drop=False)
1953
1954        # Get and clean ms1 annotation dataframe
1955        ms1_annot_report = self.mass_spectra.mass_features_ms1_annot_to_df().copy()
1956        ms1_annot_report = self.clean_ms1_report(ms1_annot_report)
1957        ms1_annot_report = ms1_annot_report.reset_index(drop=False)
1958
1959        # Get, summarize, and clean ms2 annotation dataframe
1960        ms2_annot_report = self.mass_spectra.mass_features_ms2_annot_to_df(
1961            molecular_metadata=molecular_metadata
1962        )
1963        if ms2_annot_report is not None and molecular_metadata is not None:
1964            ms2_annot_report = self.summarize_lipid_report(ms2_annot_report)
1965            ms2_annot_report = self.clean_ms2_report(ms2_annot_report)
1966            ms2_annot_report = ms2_annot_report.dropna(axis=1, how="all")
1967            ms2_annot_report = ms2_annot_report.reset_index(drop=False)
1968        report = self.combine_reports(
1969            mf_report=mf_report,
1970            ms1_annot_report=ms1_annot_report,
1971            ms2_annot_report=ms2_annot_report
1972        )
1973        return report
1974
1975