DOCSEARCHbyAlgolia
Submit Docs

Casanovo: De novo peptide sequencing with a transformer model

repository·main·Indexed 41 days ago

https://github.com/noble-lab/casanovo

Casanovo is a deep learning tool that uses a transformer neural network to translate MS/MS spectra peaks into amino acid sequences. It is designed for de novo peptide sequencing, particularly for identifying unexpected sequences in immunopeptidomics, metaproteomics, paleoproteomics, and venomics. The tool provides a CLI for sequencing, database searching via Casanovo-DB, model training, and configuration management.

Tokens
12K
Snippets
32
Records
57
Agent score
52%

What's inside Casanovo

  1. Overview of Casanovo for de novo peptide sequencing

    main

    Casanovo is a deep learning tool used for de novo peptide sequencing. It utilizes a transformer neural network to "translate" peaks in MS/MS spectra into amino acid sequences.

    It is particularly useful for identifying unexpected peptide sequences in bottom-up tandem mass spectrometry datasets where peptides might not be present in existing protein databases. Key use cases include:

    • Immunopeptidomics
    • Metaproteomics
    • Paleoproteomics
    • Venomics

  2. How model weights are loaded and selected

    main

    Casanovo uses model weights (.ckpt extension) to define the neural network's functionality. These can be used during training, sequencing, or evaluation.

    Automatic Weight Loading

    If you do not provide a weights file, Casanovo automatically downloads and caches the most recent compatible weights from the official Casanovo GitHub repository. Weights are matched based on the Casanovo release version (major, minor, patch).

    Model Types

    Casanovo supports models optimized for different instruments:

    • orbitrap: The default model.
    • timsstof: Specified via the --model timstof flag.

    Selection Logic:

    • Matching is case-insensitive and ignores separators (e.g., Orbitrap, orbitrap, and orbi-trap all resolve to orbitrap).
    • Partial names are accepted if they match exactly one model (e.g., tims resolves to timsstof).
    • If weights for an identical release are unavailable, Casanovo attempts to find weights with matching (i) major and minor versions, or (ii) just matching major versions.

    Custom Weights

    You can provide custom weights by specifying:

    • A local file system path.
    • A URL pointing to a compatible .ckpt file (which will be downloaded and cached locally).

  3. Identify the best Casanovo model checkpoint after training

    main

    During training, Casanovo saves multiple model weight snapshots (checkpoints) to the output directory. To select the best model for inference, look for the file named <output_root>.best.ckpt. This file contains the weights from the validation run that achieved the lowest validation loss.

    Other files in the output directory include:

    • epoch=<epoch>-step=<step>.ckpt: Snapshots taken at the end of every training epoch.
    • Note: Snapshots from previous training epochs are overwritten by the latest training snapshot at the end of each epoch.

  4. Download and manage Casanovo model weights

    main

    Casanovo requires pretrained model weights (.ckpt files) for peptide sequencing.

    • Automatic Download: Casanovo automatically checks for compatible weights in the local cache before downloading from GitHub.
    • Cache Locations:
      • Linux: ~/.cache/casanovo/
      • macOS: ~/Library/Caches/casanovo/
      • Windows: %LOCALAPPDATA%\casanovo\
    • Manual Download: If you hit GitHub API rate limits (60 requests/IP/hour), download weights manually from the Casanovo Releases page and provide the path using the --model flag.
    • Version Matching: Casanovo matches weights by exact version (major, minor, patch), then falls back to major+minor, then major version only.

  5. Understand the mzTab output format

    main

    Casanovo outputs results in the mzTab format, which is both human and machine-readable. The file is divided into two primary sections:

    1. Metadata section: Contains general information about the file, the Casanovo task, PTMs used, and the active configuration settings.
    2. Peptide–spectrum match (PSM) section: Contains the details of the predicted peptide sequences for the MS/MS spectra.

    Programmatic Access:

    • Python: Use Pyteomics.
    • R: Use MSnbase.
    • Manual: Open with a text editor or spreadsheet software (using a tab delimiter).

  7. Enable Metal Performance Shaders (MPS) on Apple Silicon Macs

    main

    To leverage Apple's Metal Performance Shaders (MPS) on newer Mac computers and avoid NotImplementedError: The operator 'aten::index.Tensor'..., you must set the PYTORCH_ENABLE_MPS_FALLBACK environment variable to 1.

    export PYTORCH_ENABLE_MPS_FALLBACK=1

  8. Explore Casanovo results in the View tab

    main

    The View tab allows you to inspect .mzTab results directly within the application.

    Key Features

    • Peptide-to-protein mapping: By providing a reference FASTA file, the GUI maps de novo peptides to your proteome. This generates:
      • Overview charts (PSM/peptide counts vs. score, mapped peptides vs. score cutoff, and top proteins).
      • Sortable/filterable tables for proteins (mapped and unmapped).
      • Per-protein coverage maps.
      • Note: If the FASTA is left blank, the GUI simply loads every peptide without mapping.
    • Per-residue confidence: Double-clicking a peptide opens a residue-by-residue confidence track, showing Casanovo's per-amino-acid scores alongside supporting PSMs.
    • Spectrum visualization with PDV: If you have PDV open, clicking a peptide in CasanovoGUI will automatically select its best PSM and render the annotated spectrum in PDV.

  9. Install CasanovoGUI

    main

    CasanovoGUI is a cross-platform desktop application that wraps Casanovo's command-line tasks. Native installers bundle their own Java runtime, so no manual setup of Java, Python, or pip is required.

    Installation Steps

    1. Download the installer for your platform from the CasanovoGUI Releases page:
      • Windows: Unzip CasanovoGUI-<version>-windows-x64.zip and run CasanovoGUI.exe.
      • macOS (Apple Silicon): Open and drag CasanovoGUI-<version>-macos-arm64.dmg to Applications.
      • Linux: Install the .deb package or extract the .tar.gz and run it.
      • Any OS (Java 23+): Use the .jar file if you already have a Java 23+ runtime installed.

    Casanovo Environment Setup

    • Automatic: If Casanovo is not installed, the GUI will offer to install it for you automatically into ~/.casanovo-gui.
    • Manual/Conda: If you manage Casanovo via Conda, enable "Run inside a Conda environment" in the Settings menu to use your existing environment.

  10. Use the Casanovo Nextflow Workflow

    main

    To simplify the installation of Casanovo and its dependencies, you can use a dedicated Nextflow workflow. This workflow automates a complete mass spectrometry data pipeline, including:

    1. Data Conversion: Converts input mass spectrometry data files into a Casanovo-compatible format using msconvert.
    2. Peptide Inference: Uses Casanovo to infer peptide sequences from the converted data.
    3. Result Upload (Optional): Uploads the resulting data to Limelight, a platform for sharing and visualizing proteomics results.

    The workflow is compatible with POSIX-compliant systems (UNIX), Windows via WSL, and cloud platforms like AWS.

  11. Monitor for catastrophic forgetting during fine-tuning

    main

    When fine-tuning a model on new PTMs, the model might lose performance on its original training distribution (catastrophic forgetting).

    You can monitor this by using the --tracking_peak_path (-t) option. This allows you to track validation loss on original datasets without those datasets influencing the selection of the "best" checkpoint.

    • -p or --validation_peak_path: Files used to calculate the aggregate valid_CELoss for selecting the .best.ckpt.
    • -t or --tracking_peak_path: Files logged per-file (e.g., valid/original_validation) for monitoring only. They do not influence checkpoint selection.

    To view these per-file tracking losses in logs, ensure tb_summarywriter: true or log_metrics: true is set in your config.yaml.

    # Monitor original performance while training on new PTMs
casanovo train --model pretrained.ckpt -p new_ptm_validation.mgf -t original_validation.mgf training_spectra.mgf

  12. How to cite Casanovo

    main

    When using Casanovo in your research, please cite the relevant scientific publications to acknowledge the work and contributions behind the tool.

    General Use

    For general use of Casanovo, cite the following paper:

    Yilmaz, M., Fondrie, W. E., Bittremieux, W., Oh, S. & Noble, W. S. De novo mass spectrometry peptide sequencing with a transformer model. in Proceedings of the 39th International Conference on Machine Learning - ICML '22 vol. 162 25514–25522 (PMLR, 2022). https://proceedings.mlr.press/v162/yilmaz22a.html

    Specific Versions and Functionalities

    Depending on your specific use case, you may also need to cite these additional publications:

    • Casanovo v4.x (Improved performance via MassIVE-KB training, immunopeptidomics, metaproteomics, and dark human proteome applications): Yilmaz, M., et al. Sequence-to-sequence translation from mass spectra to peptides with a transformer model. in Nature Communications 15, 6427 (2024). doi:10.1038/s41467-024-49731-x

    • Casanovo v4.2.x (Enhanced performance on tryptic and non-tryptic data): Melendez, C., et al. Accounting for digestion enzyme bias in Casanovo. in Journal of Proteome Research 23, 4761–4769 (2024). doi:10.1021/acs.jproteome.4c00422

    • Casanovo-DB (Using Casanovo as a learned score function for sequence database searching): Ananth, V., et al. A learned score function improves the power of mass spectrometry database search. in Bioinformatics 40, i410–i417 (2024). doi:10.1093/bioinformatics/btae218

    • Casanovo v5.x (General performance and usability improvements): Straub, G., et al. Improvements to Casanovo, a deep learning de novo peptide sequencer. in bioRxiv (2025). doi:10.1101/2025.07.25.666826