Compatibility between MS²Rescore v3.1 and Sage >=v0.14.4, <v0.14.7 for direct Bruker raw file support

[RalfG]

Both MS²Rescore and Sage rely on the timsrust package to directly read Bruker raw files (.d directory or miniTDF). However, there is an inconsistency between the two tools in how they interpret scan numbers. This leads to an off-by-one issue. For instance, a spectrum with ID "3033" in MS²Rescore would have spectrum ID "3034" in the Sage results file.

This problem should be fixed in future Sage versions (lazear/sage#128 and lazear/sage#140). In the meantime, the following Python script can be used to correct the scan number in Sage result files, supporting both TSV and Parquet formats.

correct_sage_scannr.py

from pathlib import Path

import click
import pandas as pd

def correct_scannr(sage_psms: pd.DataFrame) -> None:
    sage_psms["scannr"] = (sage_psms["scannr"].astype(int) - 1).astype(str)

@click.command()
@click.argument("input_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
def correct_sage_scannr(input_path: Path):
    if input_path.suffix == ".tsv":
        sage_psms = pd.read_csv(input_path, sep="\t")
    elif input_path.suffix == ".parquet":
        sage_psms = pd.read_parquet(input_path)
    else:
        raise ValueError("Input file must be a TSV or Parquet file")

    output_path = input_path.with_name(f"{input_path.stem}_corrected{input_path.suffix}")

    sage_psms["scannr"] = (sage_psms["scannr"].astype(int) - 1).astype(str)

    if input_path.suffix == ".tsv":
        sage_psms.to_csv(output_path, sep="\t", index=False)

    elif input_path.suffix == ".parquet":
        sage_psms.to_parquet(output_path)

if __name__ == "__main__":
    correct_sage_scannr()

Run, for example:

python correct_sage_scannr.py results.sage.parquet