corems.mass_spectrum.output.export

   1__author__ = "Yuri E. Corilo"
   2__date__ = "Nov 11, 2019"
   3
   4import json
   5from datetime import datetime, timezone
   6from pathlib import Path
   7from threading import Thread
   8
   9import h5py
  10import numpy as np
  11from numpy import nan as NaN
  12from pandas import DataFrame
  13
  14# Labels is referenced only inside eval() below. Ruff cannot see that use.
  15from corems.encapsulation.constant import (
  16    Atoms,
  17    DEFAULT_HDF5_COMPRESSION,
  18    Labels,  # noqa: F401
  19)
  20from corems.encapsulation.output import parameter_to_dict
  21from corems.encapsulation.output.parameter_to_json import _dumps_toml
  22from corems.mass_spectrum.factory.MassSpectrumClasses import MassSpecfromFreq
  23
  24
  25def hdf5_dataset_kwargs(shape, compression=DEFAULT_HDF5_COMPRESSION, vlen_str=False):
  26    """Build ``h5py.Group.create_dataset`` filter kwargs for a compression choice.
  27
  28    Centralizes the HDF5 writers' compression choice (one helper used by every
  29    ``create_dataset`` call on the mass spectrum / LC-MS export path) and the
  30    filter exceptions h5py enforces: it refuses chunk/filter options on scalar
  31    (``shape == ()``) or zero-length datasets, and the fletcher32 checksum
  32    filter gains nothing (and h5py can reject it) on variable-length string
  33    datasets.
  34
  35    Parameters
  36    ----------
  37    shape : tuple
  38        Shape of the data about to be written.
  39    compression : int, str or None, optional
  40        A gzip level 0-9, ``"lzf"``, or ``None``/``"none"`` for no
  41        compression. Default is 4. ``"lzf"`` is h5py's own filter, not part
  42        of core HDF5 -- a file written with it needs h5py (or another tool
  43        with the lzf plugin available) to read the compressed datasets
  44        back; gzip is the portable choice across other HDF5 tools.
  45    vlen_str : bool, optional
  46        True when the dataset's dtype is a variable-length string
  47        (``h5py.string_dtype()``); skips the shuffle/fletcher32 filters that
  48        don't apply to vlen data. Default is False.
  49
  50    Returns
  51    -------
  52    dict
  53        Keyword arguments to splat into ``create_dataset`` (besides ``data``
  54        and ``dtype``).
  55    """
  56    if not shape or 0 in shape:
  57        return {}
  58
  59    kwargs = {"chunks": True}
  60
  61    if compression not in (None, "none"):
  62        if compression == "lzf":
  63            kwargs["compression"] = "lzf"
  64        else:
  65            kwargs["compression"] = "gzip"
  66            kwargs["compression_opts"] = int(compression)
  67
  68    if not vlen_str:
  69        kwargs["shuffle"] = True
  70        kwargs["fletcher32"] = True
  71
  72    return kwargs
  73
  74
  75class HighResMassSpecExport(Thread):
  76    """A class for exporting high-resolution mass spectra.
  77
  78    Parameters
  79    ----------
  80    out_file_path : str
  81        The output file path.
  82    mass_spectrum : MassSpectrum
  83        The mass spectrum to export.
  84    output_type : str, optional
  85        The type of output file. Defaults to 'excel'. Can be 'excel', 'csv', 'pandas', 'parquet' or 'hdf5'.
  86
  87    Attributes
  88    ----------
  89    output_file : Path
  90        The output file path.
  91    output_type : str
  92        The type of output file.
  93    mass_spectrum : MassSpectrum
  94        The mass spectrum to export.
  95    atoms_order_list : list
  96        The list of assigned atoms in the order specified by Atoms.atoms_order list.
  97    columns_label : list
  98        The column labels in order.
  99
 100    Methods
 101    -------
 102    * save().
 103        Save the mass spectrum data to the output file.
 104    * run().
 105        Run the export process.
 106    * get_pandas_df().
 107        Returns the mass spectrum data as a pandas DataFrame.
 108    * write_settings(output_path, mass_spectrum).
 109        Writes the settings of the mass spectrum to a JSON file.
 110    * to_pandas(write_metadata=True).
 111        Exports the mass spectrum data to a pandas DataFrame and saves it as a pickle file.
 112    * to_excel(write_metadata=True).
 113        Exports the mass spectrum data to an Excel file.
 114    * to_csv(write_metadata=True).
 115        Exports the mass spectrum data to a CSV file.
 116    * to_parquet(write_metadata=True).
 117        Exports the mass spectrum data to a Parquet file.
 118    * to_json().
 119        Exports the mass spectrum data to a JSON string.
 120    * to_hdf().
 121        Exports the mass spectrum data to an HDF5 file.
 122    * parameters_to_toml().
 123        Converts the mass spectrum parameters to a TOML string.
 124    * parameters_to_json().
 125        Converts the mass spectrum parameters to a JSON string.
 126    * get_mass_spec_attrs(mass_spectrum).
 127        Returns the mass spectrum attributes as a dictionary.
 128    * get_all_used_atoms_in_order(mass_spectrum).
 129        Returns the list of assigned atoms in the order specified by Atoms.atoms_order list.
 130    * list_dict_to_list(mass_spectrum, is_hdf5=False).
 131        Returns the mass spectrum data as a list of dictionaries.
 132    * get_list_dict_data(mass_spectrum, include_no_match=True, include_isotopologues=True, isotopologue_inline=True, no_match_inline=False, is_hdf5=False).
 133        Returns the mass spectrum data as a list of dictionaries.
 134
 135    """
 136
 137    def __init__(self, out_file_path, mass_spectrum, output_type="excel"):
 138        Thread.__init__(self)
 139
 140        self.output_file = Path(out_file_path)
 141
 142        # 'excel', 'csv' or 'pandas'
 143        self.output_type = output_type
 144
 145        self.mass_spectrum = mass_spectrum
 146
 147        # collect all assigned atoms and order them accordingly to the Atoms.atoms_order list
 148        self.atoms_order_list = self.get_all_used_atoms_in_order(self.mass_spectrum)
 149
 150        self._init_columns()
 151
 152    def _init_columns(self):
 153        """Initialize the columns for the mass spectrum output."""
 154        # column labels in order
 155        self.columns_label = [
 156            "Index",
 157            "m/z",
 158            "Calibrated m/z",
 159            "Calculated m/z",
 160            "Peak Height",
 161            "Peak Area",
 162            "Resolving Power",
 163            "S/N",
 164            "Ion Charge",
 165            "m/z Error (ppm)",
 166            "m/z Error Score",
 167            "Isotopologue Similarity",
 168            "Confidence Score",
 169            "DBE",
 170            "O/C",
 171            "H/C",
 172            "Heteroatom Class",
 173            "Ion Type",
 174            "Adduct",
 175            "Is Isotopologue",
 176            "Mono Isotopic Index",
 177            "Molecular Formula",
 178        ]
 179
 180    @property
 181    def output_type(self):
 182        """Returns the output type of the mass spectrum."""
 183        return self._output_type
 184
 185    @output_type.setter
 186    def output_type(self, output_type):
 187        output_types = ["excel", "csv", "pandas", "parquet", "hdf5"]
 188        if output_type in output_types:
 189            self._output_type = output_type
 190        else:
 191            raise TypeError(
 192                'Supported types are "excel", "csv", "pandas", "parquet" or "hdf5", %s entered'
 193                % output_type
 194            )
 195
 196    def save(self):
 197        """Save the mass spectrum data to the output file.
 198
 199        Raises
 200        ------
 201        ValueError
 202            If the output type is not supported.
 203        """
 204
 205        if self.output_type == "excel":
 206            self.to_excel()
 207        elif self.output_type == "csv":
 208            self.to_csv()
 209        elif self.output_type == "pandas":
 210            self.to_pandas()
 211        elif self.output_type == "parquet":
 212            self.to_parquet()
 213        elif self.output_type == "hdf5":
 214            self.to_hdf()
 215        else:
 216            raise ValueError(
 217                "Unkown output type: %s; it can be 'excel', 'csv', 'pandas', 'parquet' or 'hdf5'"
 218                % self.output_type
 219            )
 220
 221    def run(self):
 222        """Run the export process.
 223
 224        This method is called when the thread starts.
 225        It calls the save method to perform the export."""
 226        self.save()
 227
 228    def get_pandas_df(self, additional_columns=None):
 229        """Returns the mass spectrum data as a pandas DataFrame.
 230
 231        Parameters
 232        ----------
 233        additional_columns : list, optional
 234            Additional columns to include in the DataFrame. Defaults to None.
 235            Suitable additional columns are: 'Aromaticity Index', 'NOSC', 'Aromaticity Index (modified)'.
 236
 237        Returns
 238        -------
 239        DataFrame
 240            The mass spectrum data as a pandas DataFrame.
 241        """
 242        if additional_columns is not None:
 243            possible_additional_columns = [
 244                "Aromaticity Index",
 245                "NOSC",
 246                "Aromaticity Index (modified)",
 247            ]
 248            if additional_columns:
 249                for column in additional_columns:
 250                    if column not in possible_additional_columns:
 251                        raise ValueError("Invalid additional column: %s" % column)
 252            columns = (
 253                self.columns_label
 254                + additional_columns
 255                + self.get_all_used_atoms_in_order(self.mass_spectrum)
 256            )
 257        else:
 258            columns = self.columns_label + self.get_all_used_atoms_in_order(
 259                self.mass_spectrum
 260            )
 261        dict_data_list = self.get_list_dict_data(
 262            self.mass_spectrum, additional_columns=additional_columns
 263        )
 264        df = DataFrame(dict_data_list, columns=columns)
 265        df.attrs["name"] = self.output_file
 266        return df
 267
 268    def write_settings(self, output_path, mass_spectrum):
 269        """Writes the settings of the mass spectrum to a JSON file.
 270
 271        Parameters
 272        ----------
 273        output_path : str
 274            The output file path.
 275        mass_spectrum : MassSpectrum
 276            The mass spectrum to export.
 277        """
 278
 279        import json
 280
 281        dict_setting = parameter_to_dict.get_dict_data_ms(mass_spectrum)
 282
 283        dict_setting["MassSpecAttrs"] = self.get_mass_spec_attrs(mass_spectrum)
 284        dict_setting["analyzer"] = mass_spectrum.analyzer
 285        dict_setting["instrument_label"] = mass_spectrum.instrument_label
 286        dict_setting["sample_name"] = mass_spectrum.sample_name
 287
 288        with open(
 289            output_path.with_suffix(".json"),
 290            "w",
 291            encoding="utf8",
 292        ) as outfile:
 293            output = json.dumps(
 294                dict_setting, sort_keys=True, indent=4, separators=(",", ": ")
 295            )
 296            outfile.write(output)
 297
 298    def to_pandas(self, write_metadata=True):
 299        """Exports the mass spectrum data to a pandas DataFrame and saves it as a pickle file.
 300
 301        Parameters
 302        ----------
 303        write_metadata : bool, optional
 304            Whether to write the metadata to a JSON file. Defaults to True.
 305        """
 306
 307        columns = self.columns_label + self.get_all_used_atoms_in_order(
 308            self.mass_spectrum
 309        )
 310
 311        dict_data_list = self.get_list_dict_data(self.mass_spectrum)
 312
 313        df = DataFrame(dict_data_list, columns=columns)
 314
 315        df.to_pickle(self.output_file.with_suffix(".pkl"))
 316
 317        if write_metadata:
 318            self.write_settings(self.output_file, self.mass_spectrum)
 319
 320    def to_excel(self, write_metadata=True):
 321        """Exports the mass spectrum data to an Excel file.
 322
 323        Parameters
 324        ----------
 325        write_metadata : bool, optional
 326            Whether to write the metadata to a JSON file. Defaults to True.
 327        """
 328
 329        columns = self.columns_label + self.get_all_used_atoms_in_order(
 330            self.mass_spectrum
 331        )
 332
 333        dict_data_list = self.get_list_dict_data(self.mass_spectrum)
 334
 335        df = DataFrame(dict_data_list, columns=columns)
 336
 337        df.to_excel(self.output_file.with_suffix(".xlsx"))
 338
 339        if write_metadata:
 340            self.write_settings(self.output_file, self.mass_spectrum)
 341
 342    def to_csv(self, write_metadata=True):
 343        """Exports the mass spectrum data to a CSV file.
 344
 345        Parameters
 346        ----------
 347        write_metadata : bool, optional
 348            Whether to write the metadata to a JSON file. Defaults to True.
 349        """
 350
 351        columns = self.columns_label + self.get_all_used_atoms_in_order(
 352            self.mass_spectrum
 353        )
 354
 355        dict_data_list = self.get_list_dict_data(self.mass_spectrum)
 356
 357        import csv
 358
 359        try:
 360            with open(self.output_file.with_suffix(".csv"), "w", newline="") as csvfile:
 361                writer = csv.DictWriter(csvfile, fieldnames=columns)
 362                writer.writeheader()
 363                for data in dict_data_list:
 364                    writer.writerow(data)
 365            if write_metadata:
 366                self.write_settings(self.output_file, self.mass_spectrum)
 367
 368        except IOError as ioerror:
 369            print(ioerror)
 370
 371    def to_parquet(self, write_metadata=True):
 372        """Exports the mass spectrum data to a Parquet file.
 373
 374        Parameters
 375        ----------
 376        write_metadata : bool, optional
 377            Whether to write the metadata to a JSON file. Defaults to True.
 378
 379        Notes
 380        -----
 381        Requires ``pyarrow`` (or ``fastparquet``) for pandas Parquet I/O.
 382        """
 383
 384        columns = self.columns_label + self.get_all_used_atoms_in_order(
 385            self.mass_spectrum
 386        )
 387
 388        dict_data_list = self.get_list_dict_data(self.mass_spectrum)
 389
 390        df = DataFrame(dict_data_list, columns=columns)
 391
 392        df.to_parquet(self.output_file.with_suffix(".parquet"), index=False)
 393
 394        if write_metadata:
 395            self.write_settings(self.output_file, self.mass_spectrum)
 396
 397    def to_json(self):
 398        """Exports the mass spectrum data to a JSON string."""
 399
 400        columns = self.columns_label + self.get_all_used_atoms_in_order(
 401            self.mass_spectrum
 402        )
 403
 404        dict_data_list = self.get_list_dict_data(self.mass_spectrum)
 405
 406        df = DataFrame(dict_data_list, columns=columns)
 407
 408        # for key, values in dict_data.items():
 409        #    if not values: dict_data[key] = NaN
 410
 411        # output = json.dumps(dict_data, sort_keys=True, indent=4, separators=(',', ': '))
 412        return df.to_json(orient="records")
 413
 414    def add_mass_spectrum_to_hdf5(
 415        self,
 416        hdf_handle,
 417        mass_spectrum,
 418        group_key,
 419        mass_spectra_group=None,
 420        export_raw=True,
 421        compression=DEFAULT_HDF5_COMPRESSION,
 422        profile_dtype="f4",
 423    ):
 424        """Adds the mass spectrum data to an HDF5 file.
 425
 426        Parameters
 427        ----------
 428        hdf_handle : h5py.File
 429            The HDF5 file handle.
 430        mass_spectrum : MassSpectrum
 431            The mass spectrum to add to the HDF5 file.
 432        group_key : str
 433            The group key (where to add the mass spectrum data within the HDF5 file).
 434        mass_spectra_group : h5py.Group, optional
 435            The mass spectra group. Defaults to None (no group, mass spectrum is added to the root).
 436        export_raw : bool, optional
 437            Whether to export the raw data. Defaults to True.
 438            If False, only the processed data (peaks) is exported (essentially centroided data).
 439        compression : int, str or None, optional
 440            Compression for the written datasets: a gzip level 0-9, ``"lzf"``,
 441            or ``None``/``"none"``. Default is 4. ``"lzf"`` is h5py's own
 442            filter, not a standard HDF5 one -- it needs h5py (or a tool
 443            with the lzf plugin) to read the result back.
 444        profile_dtype : str, optional
 445            dtype used for the stored profile m/z/abundance arrays
 446            (``"f4"`` or ``"f8"``). Default is ``"f4"``.
 447        """
 448        if mass_spectra_group is None:
 449            # Check if the file has the necessary attributes and add them if not
 450            # This assumes that if there is a mass_spectra_group, these attributes were already added to the file
 451            if not hdf_handle.attrs.get("date_utc"):
 452                timenow = str(
 453                    datetime.now(timezone.utc).strftime("%d/%m/%Y %H:%M:%S %Z")
 454                )
 455                hdf_handle.attrs["date_utc"] = timenow
 456                hdf_handle.attrs["file_name"] = mass_spectrum.filename.name
 457                hdf_handle.attrs["data_structure"] = "mass_spectrum"
 458                hdf_handle.attrs["analyzer"] = mass_spectrum.analyzer
 459                hdf_handle.attrs["instrument_label"] = mass_spectrum.instrument_label
 460                hdf_handle.attrs["sample_name"] = mass_spectrum.sample_name
 461
 462        list_results = self.list_dict_to_list(mass_spectrum, is_hdf5=True)
 463
 464        dict_ms_attrs = self.get_mass_spec_attrs(mass_spectrum)
 465
 466        setting_dicts = parameter_to_dict.get_dict_data_ms(mass_spectrum)
 467
 468        columns_labels = json.dumps(
 469            self.columns_label + self.get_all_used_atoms_in_order(mass_spectrum),
 470            sort_keys=False,
 471            indent=4,
 472            separators=(",", ": "),
 473        )
 474
 475        group_key = group_key
 476
 477        if mass_spectra_group is not None:
 478            hdf_handle = mass_spectra_group
 479
 480        if group_key not in hdf_handle.keys():
 481            scan_group = hdf_handle.create_group(group_key)
 482
 483            # If there is raw data (from profile data) save it
 484            if not mass_spectrum.is_centroid and export_raw:
 485                # "mz" is always the experimental (uncalibrated) profile; a
 486                # separate "mz_cal" row is added only when the spectrum is
 487                # actually calibrated. mz_cal_profile alone isn't enough to
 488                # tell: MzDomainCalibration.__init__ pre-populates it before
 489                # any calibration has run, so a never-calibrated spectrum
 490                # can still have a (stale/placeholder) mz_cal_profile.
 491                row_labels = ["mz", "abundance"]
 492                rows = [
 493                    np.asarray(mass_spectrum._mz_exp),
 494                    np.asarray(mass_spectrum.abundance_profile),
 495                ]
 496                mz_cal_profile = mass_spectrum.mz_cal_profile
 497                if mass_spectrum.is_calibrated and mz_cal_profile is not None:
 498                    row_labels.append("mz_cal")
 499                    rows.append(np.asarray(mz_cal_profile))
 500
 501                mz_abun_array = np.array(rows, dtype=profile_dtype)
 502
 503                raw_ms_dataset = scan_group.create_dataset(
 504                    "raw_ms",
 505                    data=mz_abun_array,
 506                    dtype=profile_dtype,
 507                    **hdf5_dataset_kwargs(mz_abun_array.shape, compression=compression),
 508                )
 509                raw_ms_dataset.attrs["row_labels"] = json.dumps(row_labels)
 510                # Recorded independently of whether an "mz_cal" row was
 511                # written, so a reader can trust this over row presence.
 512                raw_ms_dataset.attrs["is_calibrated"] = bool(
 513                    mass_spectrum.is_calibrated
 514                )
 515
 516                # Add metadata to the raw_ms dataset when it exists
 517                raw_ms_dataset.attrs["MassSpecAttrs"] = json.dumps(dict_ms_attrs)
 518
 519                if isinstance(mass_spectrum, MassSpecfromFreq):
 520                    raw_ms_dataset.attrs["TransientSetting"] = json.dumps(
 521                        setting_dicts.get("TransientSetting"),
 522                        sort_keys=False,
 523                        indent=4,
 524                        separators=(",", ": "),
 525                    )
 526            else:
 527                # For centroided data, store metadata directly on the scan group
 528                scan_group.attrs["MassSpecAttrs"] = json.dumps(dict_ms_attrs)
 529
 530                if isinstance(mass_spectrum, MassSpecfromFreq):
 531                    scan_group.attrs["TransientSetting"] = json.dumps(
 532                        setting_dicts.get("TransientSetting"),
 533                        sort_keys=False,
 534                        indent=4,
 535                        separators=(",", ": "),
 536                    )
 537
 538        else:
 539            scan_group = hdf_handle.get(group_key)
 540
 541        # Next processed-data index: one past the highest existing numeric
 542        # key, or 0 if there are none. "raw_ms" and "peak_profile_indices_*"
 543        # are not processed-data indices (get_time_index_to_pull also only
 544        # considers numeric keys, for the same reason). Using the max rather
 545        # than a count matters for a legacy file that already has "raw_ms"
 546        # and "1" (an old off-by-one: pre-fix code counted "raw_ms" as an
 547        # occupied slot) -- counting numeric keys would give "1" again and
 548        # collide with the existing one; max+1 gives "2".
 549        numeric_keys = [int(k) for k in scan_group.keys() if k.isdigit()]
 550        index_processed_data = str(max(numeric_keys) + 1) if numeric_keys else "0"
 551
 552        # Per-peak (left, apex, right) indices into the profile arrays above,
 553        # in mspeaks order, so a reloaded centroid-with-profile mass
 554        # spectrum doesn't need to re-derive peak boundaries from the peak
 555        # table's row position (which isn't a profile index). Written once
 556        # per peak-table version (same suffix as the processed-data index
 557        # below), since the profile itself (raw_ms) doesn't change across
 558        # reprocessing but the picked peaks do -- except raw_ms itself is
 559        # only ever written on the group's first creation (just above), so
 560        # if *this* mass_spectrum's profile is a different length (e.g. a
 561        # later reprocessing that re-picked over different raw data), these
 562        # indices would point into a profile that was never stored. Skip
 563        # writing them in that case; the reader falls back to a search.
 564        existing_raw_ms = scan_group.get("raw_ms")
 565        if (
 566            not mass_spectrum.is_centroid
 567            and export_raw
 568            and existing_raw_ms is not None
 569            and existing_raw_ms.shape[-1] == len(mass_spectrum.abundance_profile)
 570        ):
 571            peak_indices = np.array(
 572                [
 573                    (
 574                        mspeak.peak_left_index,
 575                        mspeak.peak_apex_index,
 576                        mspeak.peak_right_index,
 577                    )
 578                    for mspeak in mass_spectrum.mspeaks
 579                ],
 580                dtype=np.int32,
 581            ).reshape(-1, 3)
 582            scan_group.create_dataset(
 583                f"peak_profile_indices_{index_processed_data}",
 584                data=peak_indices,
 585                **hdf5_dataset_kwargs(peak_indices.shape, compression=compression),
 586            )
 587
 588        timenow = str(datetime.now(timezone.utc).strftime("%d/%m/%Y %H:%M:%S %Z"))
 589
 590        # Convert list_results to numpy array and optimize data types
 591        array_results = np.array(list_results)
 592
 593        # Apply data type optimization for numeric columns
 594        if array_results.dtype == np.float64:
 595            array_results = array_results.astype(np.float32)
 596        elif array_results.dtype == np.int64:
 597            array_results = array_results.astype(np.int32)
 598
 599        processed_dset = scan_group.create_dataset(
 600            index_processed_data,
 601            data=array_results,
 602            **hdf5_dataset_kwargs(array_results.shape, compression=compression),
 603        )
 604
 605        processed_dset.attrs["date_utc"] = timenow
 606
 607        processed_dset.attrs["ColumnsLabels"] = columns_labels
 608
 609        processed_dset.attrs["MoleculaSearchSetting"] = json.dumps(
 610            setting_dicts.get("MoleculaSearch"),
 611            sort_keys=False,
 612            indent=4,
 613            separators=(",", ": "),
 614        )
 615
 616        processed_dset.attrs["MassSpecPeakSetting"] = json.dumps(
 617            setting_dicts.get("MassSpecPeak"),
 618            sort_keys=False,
 619            indent=4,
 620            separators=(",", ": "),
 621        )
 622
 623        processed_dset.attrs["MassSpectrumSetting"] = json.dumps(
 624            setting_dicts.get("MassSpectrum"),
 625            sort_keys=False,
 626            indent=4,
 627            separators=(",", ": "),
 628        )
 629
 630    def to_hdf(self, compression=DEFAULT_HDF5_COMPRESSION, profile_dtype="f4"):
 631        """Exports the mass spectrum data to an HDF5 file.
 632
 633        Parameters
 634        ----------
 635        compression : int, str or None, optional
 636            Compression for the written datasets: a gzip level 0-9,
 637            ``"lzf"``, or ``None``/``"none"``. Default is 4. ``"lzf"`` is
 638            h5py's own filter, not a standard HDF5 one -- it needs h5py (or
 639            a tool with the lzf plugin) to read the result back.
 640        profile_dtype : str, optional
 641            dtype used for the stored profile m/z/abundance arrays
 642            (``"f4"`` or ``"f8"``). Default is ``"f4"``.
 643        """
 644
 645        with h5py.File(self.output_file.with_suffix(".hdf5"), "a") as hdf_handle:
 646            self.add_mass_spectrum_to_hdf5(
 647                hdf_handle,
 648                self.mass_spectrum,
 649                str(self.mass_spectrum.scan_number),
 650                compression=compression,
 651                profile_dtype=profile_dtype,
 652            )
 653
 654    def parameters_to_toml(self):
 655        """Converts the mass spectrum parameters to a TOML string.
 656
 657        Returns
 658        -------
 659        str
 660            The TOML string of the mass spectrum parameters.
 661        """
 662
 663        dict_setting = parameter_to_dict.get_dict_data_ms(self.mass_spectrum)
 664
 665        dict_setting["MassSpecAttrs"] = self.get_mass_spec_attrs(self.mass_spectrum)
 666        dict_setting["analyzer"] = self.mass_spectrum.analyzer
 667        dict_setting["instrument_label"] = self.mass_spectrum.instrument_label
 668        dict_setting["sample_name"] = self.mass_spectrum.sample_name
 669
 670        output = _dumps_toml(dict_setting)
 671
 672        return output
 673
 674    def parameters_to_json(self):
 675        """Converts the mass spectrum parameters to a JSON string.
 676
 677        Returns
 678        -------
 679        str
 680            The JSON string of the mass spectrum parameters.
 681        """
 682
 683        dict_setting = parameter_to_dict.get_dict_data_ms(self.mass_spectrum)
 684
 685        dict_setting["MassSpecAttrs"] = self.get_mass_spec_attrs(self.mass_spectrum)
 686        dict_setting["analyzer"] = self.mass_spectrum.analyzer
 687        dict_setting["instrument_label"] = self.mass_spectrum.instrument_label
 688        dict_setting["sample_name"] = self.mass_spectrum.sample_name
 689
 690        output = json.dumps(dict_setting)
 691
 692        return output
 693
 694    def get_mass_spec_attrs(self, mass_spectrum):
 695        """Returns the mass spectrum attributes as a dictionary.
 696
 697        Parameters
 698        ----------
 699        mass_spectrum : MassSpectrum
 700            The mass spectrum to export.
 701
 702        Returns
 703        -------
 704        dict
 705            The mass spectrum attributes.
 706        """
 707
 708        dict_ms_attrs = {}
 709        dict_ms_attrs["polarity"] = mass_spectrum.polarity
 710        dict_ms_attrs["rt"] = mass_spectrum.retention_time
 711        dict_ms_attrs["tic"] = mass_spectrum.tic
 712        dict_ms_attrs["mobility_scan"] = mass_spectrum.mobility_scan
 713        dict_ms_attrs["mobility_rt"] = mass_spectrum.mobility_rt
 714        dict_ms_attrs["Aterm"] = mass_spectrum.Aterm
 715        dict_ms_attrs["Bterm"] = mass_spectrum.Bterm
 716        dict_ms_attrs["Cterm"] = mass_spectrum.Cterm
 717        dict_ms_attrs["baseline_noise"] = mass_spectrum.baseline_noise
 718        dict_ms_attrs["baseline_noise_std"] = mass_spectrum.baseline_noise_std
 719
 720        return dict_ms_attrs
 721
 722    def get_all_used_atoms_in_order(self, mass_spectrum):
 723        """Returns the list of assigned atoms in the order specified by Atoms.atoms_order list.
 724
 725        Parameters
 726        ----------
 727        mass_spectrum : MassSpectrum
 728            The mass spectrum to export.
 729
 730        Returns
 731        -------
 732        list
 733            The list of assigned atoms in the order specified by Atoms.atoms_order list.
 734        """
 735
 736        atoms_in_order = Atoms.atoms_order
 737        all_used_atoms = set()
 738        if mass_spectrum:
 739            for ms_peak in mass_spectrum:
 740                if ms_peak:
 741                    for m_formula in ms_peak:
 742                        for atom in m_formula.atoms:
 743                            all_used_atoms.add(atom)
 744
 745        def sort_method(atom):
 746            return [atoms_in_order.index(atom)]
 747
 748        return sorted(all_used_atoms, key=sort_method)
 749
 750    def list_dict_to_list(self, mass_spectrum, is_hdf5=False):
 751        """Returns the mass spectrum data as a list of dictionaries.
 752
 753        Parameters
 754        ----------
 755        mass_spectrum : MassSpectrum
 756            The mass spectrum to export.
 757        is_hdf5 : bool, optional
 758            Whether the mass spectrum is being exported to an HDF5 file. Defaults to False.
 759
 760        Returns
 761        -------
 762        list
 763            The mass spectrum data as a list of dictionaries.
 764        """
 765
 766        column_labels = self.columns_label + self.get_all_used_atoms_in_order(
 767            mass_spectrum
 768        )
 769
 770        dict_list = self.get_list_dict_data(mass_spectrum, is_hdf5=is_hdf5)
 771
 772        all_lines = []
 773        for dict_res in dict_list:
 774            result_line = [NaN] * len(column_labels)
 775
 776            for label, value in dict_res.items():
 777                label_index = column_labels.index(label)
 778                result_line[label_index] = value
 779
 780            all_lines.append(result_line)
 781
 782        return all_lines
 783
 784    def get_list_dict_data(
 785        self,
 786        mass_spectrum,
 787        include_no_match=True,
 788        include_isotopologues=True,
 789        isotopologue_inline=True,
 790        no_match_inline=False,
 791        is_hdf5=False,
 792        additional_columns=None,
 793    ):
 794        """Returns the mass spectrum data as a list of dictionaries.
 795
 796        Parameters
 797        ----------
 798        mass_spectrum : MassSpectrum
 799            The mass spectrum to export.
 800        include_no_match : bool, optional
 801            Whether to include unassigned (no match) data. Defaults to True.
 802        include_isotopologues : bool, optional
 803            Whether to include isotopologues. Defaults to True.
 804        isotopologue_inline : bool, optional
 805            Whether to include isotopologues inline. Defaults to True.
 806        no_match_inline : bool, optional
 807            Whether to include unassigned (no match) data inline. Defaults to False.
 808        is_hdf5 : bool, optional
 809            Whether the mass spectrum is being exported to an HDF5 file. Defaults to False.
 810
 811        Returns
 812        -------
 813        list
 814            The mass spectrum data as a list of dictionaries.
 815        """
 816
 817        dict_data_list = []
 818
 819        if is_hdf5:
 820            encode = ".encode('utf-8')"
 821        else:
 822            encode = ""
 823
 824        def add_no_match_dict_data(index, ms_peak):
 825            """
 826            Export dictionary of mspeak info for unassigned (no match) data
 827            """
 828            dict_result = {
 829                "Index": index,
 830                "m/z": ms_peak._mz_exp,
 831                "Calibrated m/z": ms_peak.mz_exp,
 832                "Peak Height": ms_peak.abundance,
 833                "Peak Area": ms_peak.area,
 834                "Resolving Power": ms_peak.resolving_power,
 835                "S/N": ms_peak.signal_to_noise,
 836                # Unassigned: polarity only (±1); no formula charge exists yet
 837                "Ion Charge": ms_peak.polarity,
 838                "Heteroatom Class": eval("Labels.unassigned{}".format(encode)),
 839            }
 840
 841            dict_data_list.append(dict_result)
 842
 843        def add_match_dict_data(index, ms_peak, mformula, additional_columns=None):
 844            """
 845            Export dictionary of mspeak info for assigned (match) data
 846            """
 847            formula_dict = mformula.to_dict()
 848
 849            dict_result = {
 850                "Index": index,
 851                "m/z": ms_peak._mz_exp,
 852                "Calibrated m/z": ms_peak.mz_exp,
 853                "Calculated m/z": mformula.mz_calc,
 854                "Peak Height": ms_peak.abundance,
 855                "Peak Area": ms_peak.area,
 856                "Resolving Power": ms_peak.resolving_power,
 857                "S/N": ms_peak.signal_to_noise,
 858                # Assigned: formula charge state (may be multi-charge); not peak polarity
 859                "Ion Charge": mformula.ion_charge,
 860                "m/z Error (ppm)": mformula.mz_error,
 861                "Confidence Score": mformula.confidence_score,
 862                "Isotopologue Similarity": mformula.isotopologue_similarity,
 863                "m/z Error Score": mformula.average_mz_error_score,
 864                "DBE": mformula.dbe,
 865                "Heteroatom Class": eval("mformula.class_label{}".format(encode)),
 866                "H/C": mformula.H_C,
 867                "O/C": mformula.O_C,
 868                "Ion Type": eval("mformula.ion_type.lower(){}".format(encode)),
 869                "Is Isotopologue": int(mformula.is_isotopologue),
 870                "Molecular Formula": eval("mformula.string{}".format(encode)),
 871            }
 872            if additional_columns is not None:
 873                possible_dict = {
 874                    "Aromaticity Index": mformula.A_I,
 875                    "NOSC": mformula.nosc,
 876                    "Aromaticity Index (modified)": mformula.A_I_mod,
 877                }
 878                for column in additional_columns:
 879                    dict_result[column] = possible_dict.get(column)
 880
 881            if mformula.adduct_atom:
 882                dict_result["Adduct"] = eval("mformula.adduct_atom{}".format(encode))
 883
 884            if mformula.is_isotopologue:
 885                dict_result["Mono Isotopic Index"] = mformula.mspeak_index_mono_isotopic
 886
 887            if self.atoms_order_list is None:
 888                atoms_order_list = self.get_all_used_atoms_in_order(mass_spectrum)
 889            else:
 890                atoms_order_list = self.atoms_order_list
 891
 892            for atom in atoms_order_list:
 893                if atom in formula_dict.keys():
 894                    dict_result[atom] = formula_dict.get(atom)
 895
 896            dict_data_list.append(dict_result)
 897
 898        score_methods = mass_spectrum.molecular_search_settings.score_methods
 899        selected_score_method = (
 900            mass_spectrum.molecular_search_settings.output_score_method
 901        )
 902
 903        if selected_score_method in score_methods:
 904            # temp set score method as the one chosen in the output
 905            current_method = mass_spectrum.molecular_search_settings.score_method
 906            mass_spectrum.molecular_search_settings.score_method = selected_score_method
 907
 908            for index, ms_peak in enumerate(mass_spectrum):
 909                # print(ms_peak.mz_exp)
 910
 911                if ms_peak:
 912                    m_formula = ms_peak.best_molecular_formula_candidate
 913
 914                    if m_formula:
 915                        if not m_formula.is_isotopologue:
 916                            add_match_dict_data(
 917                                index,
 918                                ms_peak,
 919                                m_formula,
 920                                additional_columns=additional_columns,
 921                            )
 922
 923                            for (
 924                                iso_mspeak_index,
 925                                iso_mf_formula,
 926                            ) in m_formula.mspeak_mf_isotopologues_indexes:
 927                                iso_ms_peak = mass_spectrum[iso_mspeak_index]
 928                                add_match_dict_data(
 929                                    iso_mspeak_index,
 930                                    iso_ms_peak,
 931                                    iso_mf_formula,
 932                                    additional_columns=additional_columns,
 933                                )
 934                else:
 935                    if include_no_match and no_match_inline:
 936                        add_no_match_dict_data(index, ms_peak)
 937
 938            if include_no_match and not no_match_inline:
 939                for index, ms_peak in enumerate(mass_spectrum):
 940                    if not ms_peak:
 941                        add_no_match_dict_data(index, ms_peak)
 942            # reset score method as the one chosen in the output
 943            mass_spectrum.molecular_search_settings.score_method = current_method
 944
 945        else:
 946            for index, ms_peak in enumerate(mass_spectrum):
 947                # check if there is a molecular formula candidate for the msPeak
 948
 949                if ms_peak:
 950                    # m_formula = ms_peak.molecular_formula_lowest_error
 951                    for m_formula in ms_peak:
 952                        if mass_spectrum.molecular_search_settings.output_min_score > 0:
 953                            if (
 954                                m_formula.confidence_score
 955                                >= mass_spectrum.molecular_search_settings.output_min_score
 956                            ):
 957                                if m_formula.is_isotopologue:  # isotopologues inline
 958                                    if include_isotopologues and isotopologue_inline:
 959                                        add_match_dict_data(
 960                                            index,
 961                                            ms_peak,
 962                                            m_formula,
 963                                            additional_columns=additional_columns,
 964                                        )
 965                                else:
 966                                    add_match_dict_data(
 967                                        index,
 968                                        ms_peak,
 969                                        m_formula,
 970                                        additional_columns=additional_columns,
 971                                    )  # add monoisotopic peak
 972
 973                            # cutoff because of low score
 974                            else:
 975                                add_no_match_dict_data(index, ms_peak)
 976
 977                        else:
 978                            if m_formula.is_isotopologue:  # isotopologues inline
 979                                if include_isotopologues and isotopologue_inline:
 980                                    add_match_dict_data(
 981                                        index,
 982                                        ms_peak,
 983                                        m_formula,
 984                                        additional_columns=additional_columns,
 985                                    )
 986                            else:
 987                                add_match_dict_data(
 988                                    index,
 989                                    ms_peak,
 990                                    m_formula,
 991                                    additional_columns=additional_columns,
 992                                )  # add monoisotopic peak
 993                else:
 994                    # include not_match
 995                    if include_no_match and no_match_inline:
 996                        add_no_match_dict_data(index, ms_peak)
 997
 998            if include_isotopologues and not isotopologue_inline:
 999                for index, ms_peak in enumerate(mass_spectrum):
1000                    for m_formula in ms_peak:
1001                        if m_formula.is_isotopologue:
1002                            if (
1003                                m_formula.confidence_score
1004                                >= mass_spectrum.molecular_search_settings.output_min_score
1005                            ):
1006                                add_match_dict_data(
1007                                    index,
1008                                    ms_peak,
1009                                    m_formula,
1010                                    additional_columns=additional_columns,
1011                                )
1012
1013            if include_no_match and not no_match_inline:
1014                for index, ms_peak in enumerate(mass_spectrum):
1015                    if not ms_peak:
1016                        add_no_match_dict_data(index, ms_peak)
1017
1018        # remove duplicated add_match data possibly introduced on the output_score_filter step
1019        res = []
1020        [res.append(x) for x in dict_data_list if x not in res]
1021
1022        return res