CoreMS version 4.0.0

Version 4.0 is a major release that focuses on multi-sample LC-MS analysis. It introduces a new LCMSCollection framework for aligning, gap-filling, and reporting on cohorts of related samples; overhauls molecular-annotation infrastructure by retiring the remote MetabRef API in favor of bundled offline libraries; and modernizes the build system and dependencies (Python ≥3.10, numpy ≥2.1, pandas ≥2.2, h5py ≥3.13). This release contains limited breaking API changes — please review the Removed and Changed sections before upgrading production pipelines.

Changelog

[4.0.0] — 2026-07-09

Added

Multi-sample LC-MS analysis (LCMSCollection framework)

• Added LCMSCollection class in corems/mass_spectra/factory/lc_class.py for organizing 2+ LCMSBase objects into a single processable unit with unified retention-time alignment, consensus mass-feature clustering, and cohort-level statistics.
• Added retention-time alignment with anchoring support and plot_alignments() visualization for diagnosing drift across a batch.
• Added consensus mass-feature generation, gap-filling for missing features across samples, and cluster assignment persistence.
• Added LCMSCollectionExport in corems/mass_spectra/output/export.py for saving collection manifests, alignment tables, cluster assignments, and induced (gap-filled) features to HDF5.
• Added ReadCoreMSHDFMassSpectraCollection parser for round-trip import of collection HDF5 files.
• Added MultiSamplePartitions utility in corems/chroma_peak/calc/subset.py for lazy m/z- or RT-windowed iteration over multi-sample DataFrames.
• See LCMS Collection tutorial notebook

Pluggable sample-operations pipeline for LCMSCollection framework

• Added new module corems/mass_spectra/calc/lc_calc_operations.py with SampleOperation base class and concrete operations (GapFillOperation, ReloadFeaturesOperation).
• Added process_consensus_features() and process_samples_pipeline() for chaining operations (gap-fill → representative-feature reload → MS1/MS2 association → molecular formula search → MS2 library search) into a single parallelized pass.
• Parallelized induced-mass-feature molecular-formula search and cosine-similarity molecular-network calculations.
• See LCMS Collection tutorial notebook

Peak-quality metrics for LCMSBase class

• Added gaussian_similarity, noise_score, and tailing_factor attributes to LCMSMassFeature in corems/chroma_peak/factory/chroma_peak_classes.py for quality-based feature ranking and filtering.
• Added corresponding calculators in corems/chroma_peak/calc/ChromaPeakCalc.py.

Metabolomics & lipidomics workflows

• Added LCMSMetabolomicsExport and refined LipidomicsExport classes with consensus lipid annotation to LIPID MAPS species/molecular-species levels.
• Extended LipidMetadata dataclass in corems/molecular_id/factory/lipid_molecular_metadata.py with lipid_category, lipid_class, lipid_subclass, lipid_summed_name, and structure_level fields.
• Added targeted mass-feature search: search_for_targeted_mass_features_batch() in corems/mass_spectra/calc/lc_calc.py queries known m/z values with configurable ppm and RT windows, in single-sample or batch mode.
• See LCMS Targeted Search Tutorial notebook

Offline spectral-library interfaces (MetabRef replacement)

• Added GCMSLibraryInterface for local MSP-based GC-MS spectral searches.
• Added LCLipidLibraryInterface for local SQLite-based lipid annotation (202412_lipid_ref.sqlite, downloaded on-demand).
• Added generic MSPInterface class for user-supplied MSP files.
• Bundled reference libraries: corems/molecular_id/data/PNNLMetV20191015.msp and corems/molecular_id/data/FAMES_REF.msp.
• Added environment variables GCMS_LIBRARY_PATH, FAMES_LIBRARY_PATH, COREMS_LIPIDOMICS_SQLITE_PATH for user overrides.

Instrument & format support

• Added basic Bruker imaging-mode ingestion via new helpers in corems/mass_spectra/input/brukerSolarix_utils.py. Note this just allows access to the ImagingInfo.xml scan indexes necessary for parsing the ser binary transient file. Imaging data analysis is not formally supported. The functions here will be updated in a future release per the TODO notes in the docstrings.
• Added instrument-info and acquisition-timestamp extraction to LC-MS parsers.
• Extended Thermo RawFileReader support and added safeguards for legacy Thermo TIC handling.
• Added "centroided_persistent_homology" peak-picking method for centroided LCMS data.
• Added auto_process parameter to ReadCoremsMasslist.get_mass_spectrum in corems/mass_spectrum/input/massList.py enabling delayed processing.

CI, packaging, and quality

• Added GitHub Actions workflow (.github/workflows/tests.yml) running on ubuntu-latest / Python 3.13 with ci-test-source and ci-test-notebooks targets, harmonized with the GitLab CI source and shared Makefile targets.
• Introduced pyproject.toml as the primary build definition; setup.py reduced to a shim.
• Added first-pass molecular-formula database validation with auto-heal (corems/molecular_id/factory/molecularSQL.py, tests in tests/test_molecular_formula_db_factory.py).
• Added lipidomics_db and molecular_db pytest markers plus --skip-lipidomics-db / --skip-molecular-db options in conftest.py so CI can skip tests that require the SQLite lipidomics library or the Postgres molecular-formula database.
• Added cross-platform Makefile targets (Windows-friendly lipidomics download, ci-test-source / ci-test-notebooks, per-notebook selection) and pytest-xdist as a dev dependency for parallel test execution.
• Added CITATION.cff with author ORCIDs and future-proofed Zenodo references.
• Reorganized and deduplicated .gitignore.
• Added ~2,700 lines of new tests: tests/test_lcms_collection.py, tests/test_lcms_metabolomics.py, tests/test_noise_calc.py, tests/test_time_range_filtering.py, tests/test_input.py, plus expansions to existing suites.

Changed

• MassSpectraBase.spectra_parser converted from attribute to on-demand property, backed by spectra_parser_class; added raw_file_location property to support relocated raw data files after HDF5 round-trip.
• LCMSBase.mass_features_to_df() now accepts induced_features, drop_na_cols, and include_cols (all defaulted; backwards compatible).
• LCMSBase.mass_features_ms1_annot_to_df() and mass_features_ms2_annot_to_df() now accept suppress_warnings (defaulted; backwards compatible).
• LCMSExport now delegates collection-level state (manifests, alignments, cluster assignments) to LCMSCollectionExport; sample-level exports keep the sample-only surface.
• Refactored persistent-homology 2D peak picking for large memory savings, with a speed/memory tradeoff parameter on the LC rollup routine (ph_centroid_memory_improvements).
• Refactored SQL database connection handling in corems/molecular_id/search/molecularFormulaSearch.py to support safe parallel searches.
• Improved noise-based intensity filtering with SNR fallback for centroid-only data.
• Reorganized example notebooks and archived legacy examples.
• Modernized Dockerfile to python:3.13-slim base with inline .NET 8 runtime installation.

Fixed

• Fixed TIC/MS-level retrieval in ImportMassSpectraThermoMSFileReader.
• Fixed noise ROI inclusive-selection logic with regression tests.
• Fixed mzML parser handling of non-spectral data.
• Added checker to prevent duplicate reprocessing when adding mass spectra to a collection.
• Fixed division-by-zero in percentage_assigned reporting; corrected SNR recalibration edge case.
• Fixed Windows-specific HDF5 and mzML parser issues.

Removed

• Removed MetabRefGCInterface and MetabRefLCInterface and the majority of MetabRefInterface from corems/molecular_id/search/database_interfaces.py. The remote MetabRef API has been retired; code importing these classes must migrate to GCMSLibraryInterface, LCLipidLibraryInterface, or MSPInterface. A deprecation stub of MetabRefInterface remains for one release with a DeprecationWarning pointing users to bundled libraries.
• Removed old MetabRef bundled data files: FAMES_REF.MSL, PNNLMetV20191015.MSL, gcms_library_raw.json, fames_library_raw.json. Replaced by the .msp bundles listed under Added.
• Removed transient corems/mass_spectra/factory/lc_collection.py; its class definitions now live inline in corems/mass_spectra/factory/lc_class.py.
• Removed unused NMDC support scripts under support_code/nmdc/ (metadata parser/generator, workflow shims).
• Removed obsolete lipidomics example mzML fixture; replaced with test_centroid_neg_RP_metab.mzML and companion ...

CoreMS version 3.3.0

What's changed

• Fixed setup path for pip install
• Updated GC/MS workflow and associated test
• Fixed some bugs regarding verbose settings
• Restructure format for Metabref queries for MetabRef DatabaseInterface so they do not require a token
• Fix a bug that had a hard coded parameter in calculation of deconvoluted MS1 in lc_calc module

Full Changelog: v3.0.0...v3.3.0

CoreMS version 3.0

The new release, version 3.0, has focused on improving the multidimensional data processing and molecular annotation capabilities. By enhancing the foundation core modules, this update aims to provide a more reliable and stable solution for chromatographic-based mass spectrometry data processing. Along with bug fixes, we have also improved the documentation of the primary classes and added advanced algorithms for noise threshold, peak picking, and more.

Changelog

[3.0.0] - 2023-10-29

Added

• Introduced a SpectraParserInterface abstact base class object that all mass spectra parsers should adhere to.
• Added the LCMSMassFeature class to the chroma_peak/factory/ChromaPeakClasses.py module.
• Added a MZMLSpectraParser (child of SpectraParserInterface) to ingest .mzml files and instantiate MassSpectraBase and LCMSBase objects.
• Added print, copy, and check equality methods for all encapsulated parameter classes.
• Added parameters to the LiquidChromatographySettings class to declare which parts of the LCMSBase object to export.
• Implemented functionality for GCMS workflow to use MetabRef database.
• Added calculations for persistent homology to mass_spectra/calc/lc_calc module as PHCalculations class
• Added inheritance of new PHCalculations class to mass_spectra/factory/lc_class LCMSBase class.
• Added test that incorporates input, instantiating LCMSBase, and peak picking to tests.
• Added HDF5 export and import capability for LCMSBase objects.
• Added MetabRefInterface class and subclasses MetabRefGCInterface and MetabRefLCInterface.
• Added LCMSMassFeatures class to chroma_peak/factory module for storing information about LCMS mass features.
• Added calcuations for LCMSMassFeatures class (LCMSMassFeatureCalculation) to chroma_peak/calc module including peak shape metrics
• Added LCMSSpectralSearch class to enable spectral searching against a reference database for LCMSMassFeatures within the LCMSBase class.
• Added SpectrumSearchResults class to store the spectral search results.
• Added LipidomicsExport class and lipidomics workflow test.
• Added functionality for (optional) deconvolution of ms1 spectra for LCMSMassFeatures, including import, export, and plotting capabilities.
• Added verbose processing parameter to the encapsulated parameters for the MSParameters, LCMSParameters, and GCMSParameters classes.
• Added stoichiometry calculations for aromaticity index and nominal oxidation state to MolecularFormulaCalc module and ability to add these to output reporting dataframes.

Changed

• Heavily edited ImportMassSpectraThermoMSFileReader to instantiate MassSpectraBase and LCMSBase objects.
  • Removed the inheritance of LC_Calculations (now inherited by MassSpectraBase objects).
  • Moved some functionality from ImportMassSpectraThermoMSFileReader to support code for better logical separation.
• Heavily edited the LCMSBase class object within the mass_spectra/factory module.
• Incorporated some functionality of the DataDependentLCMS class into the LCMSBase class.
• Restructured the LCMSParameters class and altered all functions that call the mass spectrum-related parameters from this class.
  • This restructuring re-uses the MSParameters class within the LCMSParameters class (indexed by ms1 and ms2 by default). This adds the flexibility to attach different MSParameters instances to the ms1 and ms2 spectra within an LCMSBase object.
• Renamed two modules (LC_Class and LC_Calc) to snake_case to adhere by PEP8 formating.
• Improved functionality for exporting LCMSBase objects to HDF5.
• Changed many print statements to warnings.

Fixed

• Fixed small bug in signal processing when dealing with the end of the EIC.

Removed

• Removed win_only spectra parsers.
• Removed the DataDependentLCMS class as its functionality has been incorporated into the LCMSBase class.
• Removed the DataDependentPeak class within the chroma_peak/factory/ChromaPeakClasses.py module and incorporated functionality as needed into the LCMSMassFeature class.
• Removed old (deprecated) version of mass spectra HDF5 importer and exporter from tests.
• Removed the min_op_filter, min_hc_filter, min_oc_filter, max_oc_filter attributes from the MolecularLookupDictSettings class.

Full Changelog: v2.0.0...v3.0.0

CoreMS version 2.0

The new release, version 2.0.0, has been designed to address multiple bugs and issues that were affecting the fundamental functionalities of signal processing and molecular formula assignment. The primary purpose of this update is to provide a more reliable and stable solution for mass spectrometry data processing by enhancing the foundation core modules. Along with bug fixes, we have also improved the documentation of the primary classes and added advanced algorithms for noise threshold, peak picking, and more.

What's Changed

• Fix for a bug causing an index error in mass_spectrum\calc\PeakPicking.py by @Kzra in #2
• Bump urllib3 from 1.25.4 to 1.25.8 by @dependabot in #1
• Added options for nominal kendrick mass calculation by @Kzra in #3
• Stable by @corilo in #4
• Bump urllib3 from 1.25.8 to 1.26.5 by @dependabot in #5
• Lcms by @deweycw in #11
• Adjust thermo reader to comply with pythonnet 3.0 changes by @jmrd98 in #14
• Update core_ms tutorial by @GeorgiosDolias in #16
• Update rawFileReader.py by @jmrd98 in #15

New Contributors

• @Kzra made their first contribution in #2
• @dependabot made their first contribution in #1
• @corilo made their first contribution in #4
• @deweycw made their first contribution in #11
• @jmrd98 made their first contribution in #14
• @GeorgiosDolias made their first contribution in #16

Full Changelog: https://github.com/EMSL-Computing/CoreMS/commits/v2.0.0