Arka Glycan

This is the guide included in the app (Help in the header). Arka Glycan is in an invite-only beta; see Download.

Arka Glycan user guide

Arka Glycan finds the glycan compositions in released-glycan LC-MS/MS data. You give it a spectrum file; it matches every MS/MS precursor to glycan compositions, checks the fragment ions, and gives you a table of glycans with a confidence tier, the spectra behind each one, and CSV, Excel and Methods-text downloads.

Everything runs on your own computer. Your files never leave it, and no internet connection is needed except to download the optional Thermo converter.

Contents

Install

macOS (Apple Silicon)

  1. Unzip Arka-Glycan-macos-arm64.zip and drag Arka Glycan into Applications.
  2. Double-click it. Because the app is not yet signed by Apple, macOS shows "Arka Glycan" Not Opened with only Done and Move to Trash. Click Done.
  3. Open System Settings → Privacy & Security, scroll to the message about Arka Glycan and click Open Anyway, then confirm with your password. You only do this once.

Arka Glycan has no window or Dock icon: it opens a tab in your web browser. To stop it, click Quit in the page header. Opening the app again while it runs simply opens another tab.

Windows 10 and 11 (64-bit)

  1. Run Arka-Glycan-Setup.exe. Because the installer is not yet signed, Windows may show "Windows protected your PC". Click More info, then Run anyway.
  2. Follow the installer. It installs for your user only (no administrator rights needed) and adds Arka Glycan and Uninstall Arka Glycan to the Start menu.
  3. Start Arka Glycan from the Start menu. It opens a tab in your default browser; click Quit in the page header to stop it.

Uninstalling removes the program but keeps your analyses (see Where your data are).

First start: the Thermo converter

On first start Arka Glycan opens the Converter page. It is only needed for Thermo .raw files; mzML, mzXML and Bruker files work without it.

The converter, ThermoRawFileParser, contains Thermo's RawFileReader library, whose licence does not allow Arka Glycan to include it. So the page shows Thermo's licence text. If you agree, tick I have read and accept Thermo's licence terms and click Accept and download converter. Arka Glycan downloads it (about 33 MB on macOS, 51 MB on Windows) from the CompOmics release on GitHub, checks it against a fixed checksum, and installs it for you. Your acceptance is recorded with the date.

Click Not now (mzML / mzXML only) if you do not use .raw files; you can come back via Converter in the header at any time.

Try the example

On the Projects page, click Try an example. Arka Glycan analyses a bundled 6-minute slice of a public breast-cancer cell-surface N-glycan run (GlycoPOST GPST000536, reduced and permethylated, ion-trap CID) with the settings that were validated on that run. It takes a few seconds and finds about 60 glycan compositions, a quick way to see what results look like.

Start an analysis

Click New analysis, choose your file, check the settings and click Start analysis.

File What to upload
Thermo .raw the file itself; it is converted first (needs the converter)
Bruker timsTOF .d the .d folder compressed into a .zip (in Finder: right-click → Compress; in Windows: right-click → Send to → Compressed folder)
mzML or mzXML the file itself (from msconvert, ThermoRawFileParser or another converter)

The file is copied into the analysis folder on your computer. The analysis page shows progress; most runs take seconds to a few minutes. You can start several; they run one after another.

Bruker files: timsTOF DDA-PASEF and MS/MS (MRM) runs work. Older Bruker instruments (maXis, impact, amaZon) write a different format; convert those to mzML with ProteoWizard msconvert on Windows first.

The New analysis settings

The defaults are the settings validated on public datasets: reduced, permethylated human N-glycans analysed in positive mode. Change a setting when your sample or instrument differs.

Data

  • Spectrum file: see Start an analysis.
  • Name: how the analysis is listed. Leave it empty to use the file name.

Sample

  • Derivative / label: how your glycans were prepared. The masses depend on it, so it must match your sample:
  • Native: free, unmodified glycans.
  • Reduced (alditol): reduced with borohydride, not derivatised (common for PGC-LC and O-glycans).
  • Permethylated or Reduced + permethylated: the most common choices for MALDI and positive-mode LC-MS of N-glycans.
  • 2-AB, Procainamide, RapiFluor-MS: fluorescently labelled glycans (HILIC-FLR-MS).
  • Glycan class: N-glycans (default) or O-glycans (mucin-type). It sets the glycan types, the composition ranges and the confidence rules used for the results, and choosing O-glycans turns off the N-glycan filter.
  • Sample type: Human excludes NeuGc, which humans cannot make (any NeuGc call would be a mis-assignment, as NeuGc + Fuc has the same mass as NeuAc + Hex). Choose Other species for animal samples, which can contain NeuGc.
  • N-glycan plausibility filter: only allows compositions that can be N-glycans: the GlcNAc₂Man₃ core (HexNAc ≥ 2 and Hex ≥ 3), at most one fucose per HexNAc beyond the first, and at most one sialic acid per antenna. Leave it on for N-glycans: it removes many chance matches. It is turned off for O-glycans.

Precursor matching

  • Adducts: the ions your precursors carry. Positive mode: H⁺ (protonated) and NH₄⁺ (ammonium, common with permethylated glycans in ammonium-containing solvents); Na⁺ and K⁺ for sodiated or potassiated ions. Negative mode: −H⁺ for deprotonated [M−H]⁻ ions. Positive and negative carriers cannot be combined; choosing one clears the other.
  • Mixed adducts: lets a doubly or triply charged ion carry different adducts, such as [M+H+NH₄]²⁺. Keep it on when you selected more than one positive adduct.
  • Precursor tolerance (ppm): how far a measured precursor may be from the theoretical mass. 10 ppm suits Orbitrap and timsTOF data. Use 20–50 ppm for lower-resolution instruments; a wider window gives more chance matches.
  • Maximum precursor charge: spectra recorded at a higher charge are skipped (6 by default).
  • ¹³C isotope offsets to consider: instruments sometimes pick the first or second ¹³C isotope peak instead of the monoisotopic one, especially for large glycans. 0–2 lets Arka Glycan correct for that. Use 0 only if your instrument always selects the monoisotopic peak.
  • Estimate isotope offset from MS1: looks at the MS1 spectrum just before each MS/MS to see whether the selected peak was an isotope peak, and starts the search there. Leave it on; it makes a large difference on serum data.

Fragment scoring

  • Spectra to score: All MS/MS, or only spectra from the Orbitrap (FTMS) or the ion trap (ITMS). Methods that record each precursor twice (for example HCD in the Orbitrap and CID in the ion trap) give two spectra per precursor; choosing one detector avoids counting them twice.
  • Fragment tolerance: how close a peak must be to a theoretical fragment. 20 ppm for high-resolution (Orbitrap, TOF) fragments; about 0.15 Da for ion-trap CID fragments.
  • Fragment calibration offset (Da): a constant shift added to all theoretical fragments, for instruments whose fragment masses are systematically off (for example +0.2 Da for some ion-trap data). Leave it at 0 unless matched fragments are consistently shifted in the spectrum viewer.
  • Let fragments break precursor ties: when two compositions match the precursor almost equally well (within 5 ppm), lets the fragment score choose between them. It is off by default because it did not improve agreement with published assignments; fragment scores are reported either way.

Reset to validated defaults restores all settings.

Reading the results

The analysis page lists one row per glycan composition, sorted by the number of supporting spectra. The line above the table summarises the glycan types, the fucosylated and sialylated fractions and the confidence tiers (all counted over compositions).

Column Meaning
Composition monosaccharide counts (Hex, HexNAc, dHex = fucose, NeuAc, NeuGc) with a schematic SNFG cartoon. Branching and linkages in the cartoon are assumed, not measured.
Confidence high, medium or low (see Confidence tiers); hover for the reason
Type N-glycans: paucimannose, high-mannose, hybrid, complex. O-glycans: Tn, core 1, extended. From the composition alone.
Neutral mass monoisotopic mass of the glycan in the form you analysed (derivative included)
Spectra MS/MS spectra assigned to this composition
Best scan the strongest supporting spectrum; click the composition to open it
RT (min) retention time of the best scan
Ion the precursor ion of the best scan, e.g. [M+2H]²⁺
ppm (best scan) precursor mass error of the best scan
q-value fragment-based false-discovery estimate of the best scan (lower is better). Treat it as a guide: on low-resolution ion-trap spectra it is often high even for correct assignments.
Score fragment score of the best scan (higher means more matched fragments than chance would give)

Filters above the table narrow the list by confidence, composition text (e.g. NeuAc2), minimum number of spectra and maximum q-value. Columns shows or hides columns (for example the hidden "q ≤ 0.05" count). The table never removes glycans by itself: low-confidence rows are hidden only by the default "High and medium" filter, and the line under the filters says how many are hidden.

Confidence tiers

Every composition gets a tier from how much evidence supports it and how typical the composition is. Rows are never removed, only tiered.

N-glycans

  • High: at least 3 supporting spectra within a 2-minute window (the glycan elutes as a real peak) and a composition within typical ranges.
  • Medium: at least 2 spectra, or a composition slightly outside the ranges.
  • Low: a single spectrum, or an unusual composition.

Typical ranges: Hex ≤ HexNAc + 4 (up to Man9 for high-mannose), no more sialic acids than antennae, native mass up to 4,500 Da. "Slightly outside" means one rule missed by a little (2 Hex, 1 sialic acid or 500 Da).

O-glycans (when Glycan class is O-glycans)

  • High: within typical mucin O-glycan ranges, with 3 co-eluting spectra or 2 spectra with fragment evidence (q ≤ 0.01).
  • Medium: 2 spectra, or a single spectrum with fragment evidence. Direct-infusion and targeted runs give one summed spectrum per precursor, so this is where most of their glycans land.
  • Low: a single spectrum without fragment evidence, or an unusual composition.

Typical O-glycan ranges: at least one HexNAc, Hex ≤ HexNAc + 2, fucoses ≤ Hex + HexNAc − 1, sialic acids ≤ Hex + 1, native mass up to 3,000 Da. Sulfated O-glycans cannot yet be assigned.

The spectrum viewer

Click a composition to open its best spectrum. Peaks matched by a theoretical fragment are coloured: blue for B (and, in negative mode, C) ions from the non-reducing end, orange for Y (and Z) ions that keep the reducing end; grey peaks are unmatched. The dashed line marks the precursor. Hover over a peak for its m/z, intensity and matching ions; drag across the plot to zoom and click Reset zoom to go back. The table below the plot lists every matched fragment with its error. Other spectra of the same composition are listed below that.

Exports and Methods text

On the analysis page:

  • Download CSV and Download Excel save the complete table: every composition, whatever filters are set on screen, with its confidence, reason, type, masses and supporting-spectrum details. The Excel file has a "notes" sheet explaining the columns and the confidence rules.
  • Methods text gives a ready-to-paste Methods paragraph describing exactly how this analysis was run: software and version, how the file was read, derivative, adducts, tolerances, isotope handling, plausibility rules, fragment scoring and the confidence-tier rules, with references and a suggested citation. Copy it or download it as a text file, and adjust it to your own style.

Licence and trial

Arka Glycan runs as a 30-day free trial without a key. Add a licence key on the Licence page (paste the key you received; it starts with ARKA1.). The key is checked on your computer; no internet connection is needed. The header always shows your licence (tier and expiry) or the days left in the trial.

  • Subscriptions work until their expiry date and for 14 more days of grace.
  • After a trial or subscription ends, Arka Glycan is read-only: you can still open, view and export every past analysis, but you need a key to start new ones. Your data are never locked or deleted.
  • Perpetual licences keep working. After their update period ends, the header says so; newer versions need a renewal.

Where your data are

Analyses, settings, licence, converter
macOS ~/.glycan-tool (a hidden folder in your home folder; in Finder: Go → Go to Folder → ~/.glycan-tool)
Windows %LOCALAPPDATA%\Arka Glycan (paste it into the File Explorer address bar)

Each analysis has its own folder with the uploaded file, the converted mzML (if any), the per-spectrum results (spectra.tsv) and the glycan table (glycans.csv, glycans.xlsx). The app's log is app.log in the same place. Back this folder up to keep your analyses.

Troubleshooting

These are the messages Arka Glycan can show, with what to do.

Installing and starting

  • "Arka Glycan" Not Opened (macOS) or Windows protected your PC (Windows): see Install. The apps are not yet code-signed.
  • Port … is in use: another program uses Arka Glycan's port. Arka Glycan normally picks the next free port by itself; this message only appears when a fixed port was set with GLYCAN_TOOL_PORT.
  • The browser tab says the page cannot be reached: Arka Glycan has stopped (Quit, or the computer slept). Open the app again.

Uploading files

  • Choose a Thermo .raw, a zipped Bruker .d folder, or an .mzML or .mzXML file.: the file type is not supported. Convert other vendor formats to mzML with ProteoWizard msconvert.
  • The upload is not a valid zip file.: re-create the zip of the .d folder.
  • The zip file must contain exactly one Bruker .d folder (found …).: zip one .d folder at a time, not its parent folder or several runs.
  • The zip file unpacks to more than 20 GB.: zip a single run.
  • … was recorded in negative mode, but the adducts chosen are positive-mode carriers. Choose [M-H]- (-H) instead. (or the reverse): change Adducts to match your instrument's polarity.
  • … is a BAF file (maXis, impact or amaZon) …: convert it to mzML with ProteoWizard msconvert on Windows and upload the mzML.
  • DIA-PASEF runs have no precursor per spectrum and are not supported …: use DDA-PASEF or MS/MS data.
  • … has no analysis.tdf and analysis.tdf_bin; only timsTOF (TDF) .d folders are supported.: the zip holds an incomplete or non-timsTOF .d folder.

Thermo .raw files and the converter

  • Thermo .raw files need ThermoRawFileParser, which was not found …: open Converter and install it, or upload an mzML file instead.
  • Conversion with ThermoRawFileParser failed: …: the file may be incomplete or from an unsupported instrument; try converting it with msconvert, or re-copy it from the instrument computer.
  • Download failed (…). Check the internet connection and retry.: the converter download needs internet once; retry on a connected network.
  • The downloaded file does not have the expected SHA-256 checksum; it was deleted.: the download was damaged or altered; retry. If it keeps failing, install the converter by hand (README).
  • The licence inside the download differs from the one you accepted …: the downloaded converter carries different licence terms; it was not installed. Report it.
  • There is no pinned converter build for this computer …: the one-click download exists for macOS on Apple Silicon and Windows x64; elsewhere, install ThermoRawFileParser by hand or use mzML.
  • Could not sign the converter: … (macOS): macOS refused the ad-hoc signature; reinstall from the Converter page or report it.

Running analyses

  • The server stopped before this analysis finished.: the app was quit (or the computer shut down) during the analysis; start it again.
  • This analysis is still running.: wait for it to finish before deleting it.
  • An analysis finishes with 0 glycans: usually a setting does not match the sample. Check the Derivative / label, the Adducts (and positive or negative mode), and Spectra to score. The Try an example analysis shows what a working run looks like.
  • Many glycans but most are low confidence: normal for short runs or direct infusion with N-glycan rules. For O-glycans choose Glycan class: O-glycans.
  • Glycans containing NeuGc in a human sample: choose Sample type: Human.
  • scan … has no glycan assignment in this analysis: the link points to a spectrum without an assignment (for example after re-running); open it from the results table instead.

Licence

  • … the trial ended … or … expired … with a red badge: Arka Glycan is read-only. Your analyses stay available; add a (renewed) key on the Licence page to start new ones.
  • this is not an Arka Glycan licence key (it should start with ARKA1.): paste the whole key, including ARKA1..
  • the key is damaged (not valid base64); paste it again in full: part of the key is missing or changed; copy it again from the e-mail. Line breaks are fine.
  • the key's signature does not match: it was altered or not issued for Arka Glycan: the key was changed or is not an Arka Glycan key; ask for a new one.
  • unsupported licence version …; update Arka Glycan: the key is newer than this version of the app.
  • The saved licence key cannot be used: …: the stored key no longer verifies (for example after an update that changed the signing key); paste a current key.