Skip to content

Quickstart guide

Jump to bottom
Matt Fido edited this page Aug 11, 2025 · 1 revision

LCMSpector – Step-by-Step Beginner’s Guide

No mass spectrometry knowledge required!

Welcome

Thank you for helping us test LCMSpector!
This guide will walk you through:

  1. Installing LCMSpector on your computer
  2. Downloading and opening a sample dataset
  3. Loading that sample into LCMSpector
  4. Choosing an ion/metabolite list to search for
  5. Running the analysis
  6. Looking at the results
  7. Exporting the results

You can follow along even if you have never used scientific software before.

Part 1: Installation

Step 1 – Download LCMSpector

  1. Open this page in your browser:
    LCMSpector Releases on GitHub
  2. Scroll to the latest release at the top.
  3. Under Assets, download the correct version for your computer:
    • Windows: Click the .zip file containing “Win11” in the name
    • macOS: Click the .zip file containing “macOS” in the name

Step 2 – Open and Install

For Windows

  1. Unpack the archive.
  2. Go into: 
    LC-Inspector/dist
  3. Find the .exe file and double-click it.
  4. If you see a “Windows protected your PC” screen:
    • Click More info
    • Click Run anyway
      (This happens because the app is not from the Microsoft Store — it doesn’t mean it’s unsafe.)
  5. If you see a Windows Defender SmartScreen pop-up in Protection history:
    • Open it
    • Select LCMSpector
    • Click Restore

For macOS

  1. Double-click the downloaded file to open it.
  2. If you see

    "LCMSpector cannot be opened because it is from an unidentified developer":

    • Go to System Settings → Privacy & Security
    • Scroll down and click Open Anyway next to LCMSpector
  3. If you get a

    "quarantined" or "broken" file warning:

    • Click Done (not "Move to Trash")
    • Open Terminal (Applications → Utilities)
    • Type: 
      xattr -d com.apple.quarantine /path/to/LCMSpector.app
      (Tip: Drag the LCMSpector app into the Terminal window after typing the command to auto-fill the path, then press Enter.)
  4. LCMSpector should now open.

For Linux (Docker Run)

  1. Make sure Docker is installed.
  2. Pull the image: 
    docker pull mateuszfido/lcmspector:latest
  3. Enable display access: 
    xhost +local:docker
  4. Run the container (adjust syntax per OS if needed): 
    docker run -it \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v /path/to/data_folder:/data \
    mateuszfido/lcmspector:latest

(If unsure, we can provide you with a ready-to-run Docker command for your OS.)

Part 2: Getting the Sample Dataset

  1. Go to: Sample Data Download
  2. Click Download ZIP.
  3. Once downloaded:
    • Windows: Right-click → Extract All
    • macOS: Double-click to unzip
  4. You will get a folder with one or more .mzML or .txt files.

    ✅ Do not rename the files.

Part 3: Opening the Data

  1. Open LCMSpector from your Applications or Start Menu.
  2. Drag and drop a .mzML or .txt file into the LCMSpector window.
    • You can also drag an entire folder
    • Or use the Browse button
  3. The file name will appear in the Data List panel.

Part 4: Choosing an Ion (Compound) List

  1. Look for the Ion List panel on the right.
  2. Using a preset list:
    • Click the dropdown menu
    • Select a built-in preset (e.g., Amino acids)
  3. Creating your own list:
    • Click New List or Edit List
    • Add names/identifiers and their m/z values

Part 5: Processing the Data

  1. Click the big Process button.
  2. Processing time varies — watch the progress bar.
  3. When complete, LCMSpector switches to the Results View automatically.

Part 6: Exploring the Results

You may see several visual panels:

  • Raw Chromatogram View – detector signal from chromatography, clickable to view spectrum in Raw MS View
  • Raw MS View – updates each time you click a chromatogram point
  • Annotated Chromatogram View – peaks for compounds annotated with MS data
  • TIC/XIC Traces – total or extracted ion traces for chosen m/z values

Tips:

  • Hover over peaks to view retention times and intensities
  • Zoom by click-dragging over an area
  • Right-click plots to change settings or export plots/data
  • Toggle overlays to declutter the view

Part 7: Exporting Results

Option 1 – Keyboard Shortcut

  • Press:
    • Windows/Linux: Ctrl + E
    • macOS: Cmd + E

Option 2 – Menu

  1. Go to File → Export
  2. Saves results as .csv with compound values and concentrations

You can also export plots as:

  • PNG, JPG, SVG (images)
  • CSV (tables)

💡 Choose a location you’ll remember (e.g., Desktop, Documents).

Part 8: Test Complete

At this point, you have:

  1. Installed LCMSpector
  2. Opened sample data
  3. Chosen an ion list
  4. Run an analysis
  5. Explored interactive plots
  6. Exported results

Finally, please complete the Usability Test Form:
https://forms.gle/X1cVyH85fXoZHekr9

Thank you! ⭐

Clone this wiki locally