Crosslinking MS data analysis for structural biology using the xi pipeline

Who this tutorial is for

This tutorial is intended for users who receive crosslinking MS data from a facility and need to understand what to do next, users who want to reprocess raw-derived files or search outputs, users who need to interpret or leverage crosslinking MS data for structural interpretation, and users who are beginning to optimize crosslinking experiments in-house.

It is not a complete protocol for going from purified protein to raw mass spectrometry data. The experimental sections explain the design logic behind the dataset so that the analysis choices make sense, but they do not replace local wet-lab and MS facility methods.

By the end of the tutorial, you should understand how to set up a database search for crosslinking mass spectrometry. You should also be able to explain why xiFDR-filtered residue pairs are the correct result level for this structural workflow, and why score sliders in visualization tools are for inspection rather than redefining the accepted dataset.

The later modules move from network and sequence-level inspection in xiview to 3D distance checks, ChimeraX/X-MAS visualization, and modeling tools such as DisVis. The emphasis is on turning crosslinks into testable structural hypotheses, not treating every link as a final structural conclusion.

Learning goals

• Explain how crosslinking MS can test a mechanistic hypothesis about Vpr, Cullin4 ligase hijacking, and SAMHD1 recruitment.
• Connect the chemistry of sulfo-SDA to the xiSEARCH configuration used for this dataset.
• Distinguish a scored candidate match from an FDR-controlled crosslink result.
• Explain why error has to be propagated from spectra to peptide pairs, residue pairs, and protein pairs.
• Use xiview to inspect crosslink localization, spectra, condition-specific patterns, and structure-derived distances.
• Separate observations that support a structural model from observations that only motivate a new hypothesis.

How to work through the tutorial

Each module starts with the concept that motivates the action. Read that part first, then perform the boxed instruction or answer the boxed question. The checkboxes are only a local progress aid; they do not store or submit data.

Software and where to get it

Several steps use external tools. Install or open them before the practical session if you want to follow the complete workflow from search to structural interpretation.

• I can describe how raw spectra become structural restraints.
• I know where to download or open the tools used in the tutorial.
• I understand that this page links to external tools rather than embedding them.

Wet-lab processing before the search

The cullin4-ubiquitin ligase system was reconstituted with Vpr and SAMHD1 and purified by size exclusion chormatography, with a yield of about 150ug. This material was used for a crosslinking MS experiment aimed to identify the position of SAMHD1 within the complex, since this is missing in the cryo-EM density.

The crosslinker was first titrated to find a useful sulfo-SDA concentration. The chosen conditions were those where the monomer band was still visible, but the crosslinked complex had formed. This matters because too little crosslinker gives few restraints, while too much crosslinker can over-modify the complex and make the sample harder to interpret.

The lower-SDA lanes 2-4 were grouped together, and the higher-SDA lanes 5-6 were grouped together. Each grouped gel band was processed separately by in-gel digestion. The peptides from lanes 2-4 were then separated by peptide size exclusion chromatography, and the peptides from lanes 5-6 were separated in the same way on a separate peptide SEC run.

Each peptide SEC fraction that could contain crosslinked peptides was injected separately into the mass spectrometer. This is why the run names carry labels such as Ratio24 and Ratio56: they trace back to the lane groups that were digested, fractionated, and acquired separately. Later, when comparing conditions in xiview, those labels are experimental history rather than arbitrary file names.

• I downloaded files from the google drive link.
• I identified which local files are already available for 3D analysis.

Theory: what xiSEARCH is trying to solve

In a standard proteomics search, one spectrum is usually explained by one peptide. In crosslinking MS, a spectrum can be explained by two peptides connected by a crosslinker, by a loop-linked peptide, by a modified linear peptide, or by two non-covalently associated peptides that co-eluted and co-fragmented. The search space therefore grows quickly with the number of proteins, possible digestion products, modifications, crosslinker chemistries, and missed cleavages.

xiSEARCH handles this by scoring candidate explanations for each spectrum. The documented strategy first evaluates alpha peptide candidates, then considers compatible beta candidates based on precursor mass, and finally performs more complete scoring of the best peptide-pair candidates. The score is a ranking tool, not by itself an error estimate.

The target-decoy logic is built into the search output. Matches against target and decoy sequences are passed to xiFDR, which estimates how many accepted matches are expected to be false at the chosen result level.

Before opening xiSEARCH: define the chemical search space

A search engine can only compare spectra against the chemical possibilities that you give it. A useful xiSEARCH setup therefore starts with a realistic model of the experiment: which proteins were present, how they were digested, which crosslinker was used, which side reactions are plausible, and which modifications are common enough to search.

The course slides describe the search as a set of competing chemical explanations: a true crosslinked peptide pair, noncovalently associated peptides, a Tris-quenched monolink, a hydrolyzed monolink, a loop link, or a linear peptide. These categories matter because they are not interchangeable. If a plausible side product is missing from the search, xiSEARCH may explain its spectrum with a worse but available candidate; if too many implausible products are included, the candidate space grows and the statistical model becomes less stable.

For this dataset, the crosslinker is sulfo-SDA. The relevant preset searches K, S, T, Y, and protein N-termini on one side against any amino acid on the other side. The tutorial also includes loop-linked and hydrolyzed SDA products as variable modifications because those products are chemically expected. BS3-related modifications should be deselected because they describe a different crosslinker chemistry and only add irrelevant candidate explanations. For the data processing, SDA and sulfo-SDA are the same crosslinker, and are treated interchangeably in this tutorial. However, sulfo-SDA (sulfo-NHS diazirine) is water soluble and SDA (NHS-diazirine) is not and needs to be solubilized in DMSO or dimethylformamide before use. After croslinking they yield the same chemical group with the same mass.

NonCovalent should be included as a competing explanation. Some spectra come from co-eluting peptides that fragment together without being covalently linked. If this class is not searched, those spectra may be forced into crosslink assignments that look plausible but are chemically misleading.

Before opening xiSEARCH: craft the sequence database

The FASTA database defines both sensitivity and statistical difficulty. A database that is too small can miss real explanations such as contaminants, tags, or alternate constructs. A database that is too broad creates many more candidate peptide pairs, increases RAM and runtime, and can make target-decoy modeling less stable if the search space is dominated by irrelevant proteins.

Notice this workflow uses a reduced .fasta database with only the proteins of interest to keep runtime manageable. Typically, the database would include the protein of interest, common mass spec contaminants, for example from the MaxQuant contaminant list of cRAPome, and additional proteins identified in the sample by a proteomics experiment.

For recombinant complexes, make sure each protein has a unique accession before the first space in the FASTA header. xiSEARCH parses protein names, accessions, and descriptions from the headers, and repeated or ambiguous accessions can later confuse xiFDR output and xiview labels. If custom decoys are provided, the target and decoy accessions should correspond cleanly, for example by adding a consistent REV_ prefix.

For system-wide or in-cell crosslinking experiments, the usual solution is not to search the full proteome directly. Instead, reduce the database first using sample-specific evidence, for example the top abundant proteins identified in a proteomics experiment, then search that smaller protein set with crosslinking-aware settings. For larger database searches, consider Scout, described in Nature Methods 2024.

What is inside an MGF peak file?

The recalibrated .mgf files are text files containing many MS/MS spectra. Conceptually, each spectrum is a two-dimensional array: fragment ion m/z values on the x axis and intensities on the y axis. These peak lists are the experimental evidence that xiSEARCH must explain.

Each MS2 scan also has precursor information in the spectrum header, such as the precursor m/z, charge state, scan title, and retention-time-related metadata. During the database search, xiSEARCH uses the precursor information to decide which peptide or peptide-pair masses could plausibly explain the scan, then compares the observed fragment peaks against theoretical fragments from those candidate explanations.

BEGIN IONS
TITLE=scan identifier and acquisition metadata
PEPMASS=precursor_mz precursor_intensity
CHARGE=precursor_charge+
fragment_mz fragment_intensity
fragment_mz fragment_intensity
END IONS

Walkthrough: Files tab

The Files tab defines the inputs and output destination. Load the recalibrated peak lists, here represented as recal*.mgf, then load the sequence database, here complex.fasta. Choose an output name that records the chemistry and key search settings, for example an SDA search with residue-pair FDR follow-up.

xiSEARCH automatically creates decoys from the uploaded FASTA unless a FASTA is explicitly marked as a decoy database. For this tutorial, use the standard target FASTA workflow unless you have a carefully paired target/decoy database.

Walkthrough: Parameters tab and Basic Config

The Parameters tab defines the search model. In Basic Config, choose the crosslinker chemistry, digestion rule, mass tolerances, missed cleavages, variable modifications, ion series, losses, memory, and thread count. These are not cosmetic settings: each one changes which theoretical explanations xiSEARCH will consider.

Fixed, variable, and variable-linear modifications

Fixed modifications are applied wherever their residue rule matches, so they are appropriate only when the chemistry is expected on every instance. Variable modifications are optional alternatives and therefore multiply the number of candidate peptides. Variable-linear modifications are optional but considered only for linear peptide explanations, which can help keep large crosslink searches tractable while still allowing common linear side products.

The practical rule is to model the real chemical space, not every conceivable mass shift. Adding modifications without a chemical reason increases runtime, RAM use, and the number of false alternatives competing for each spectrum.

xiSEARCH-specific note: variable linear modifications

A useful xiSEARCH feature is the distinction between ordinary variable modifications and variable linear modifications. Ordinary variable modifications are considered in the crosslinked peptide-pair search space, so every extra optional chemistry can multiply the number of alpha and beta peptide candidates. Variable linear modifications are only considered when xiSEARCH tests linear peptide explanations for a spectrum.

This is helpful because crosslinking searches need plausible linear competitors, but you often do not want every linear side product to explode the crosslinked search space. Use variable linear modifications for chemistry that should be allowed as a linear alternative but should not be treated as a general crosslinked-peptide modification unless the experiment supports it.

Advanced Config and reproducibility

Basic Config is the right entry point for this tutorial. Advanced Config exposes the backend text configuration that xiSEARCH also uses for saved config files and command-line or HPC runs. It is useful when you need reproducibility across machines, custom crosslinker definitions, non-default candidate limits, custom accession parsing, or settings not exposed clearly in the beginner-facing controls.

Do not start by changing advanced candidate limits unless there is a concrete problem to solve. For example, limits on modified peptides or candidate peptides can rescue memory-heavy searches, but they also change which explanations are allowed to compete.

• I loaded peak files and the FASTA in the xiSEARCH files tab.
• I checked that FASTA accessions are unique and appropriate for xiview and xiFDR output.
• I selected SDA and NonCovalent, set tolerances, memory, threads, missed cleavages, and modifications.
• I ticked Do FDR and set the residue-pair FDR threshold to 2%.
• I can explain why irrelevant modifications and oversized databases increase RAM and false alternatives.
• I understand why xiSEARCH output still needs xiFDR filtering.

Theory: why FDR is not a single universal number

A crosslinking MS result is aggregated in layers. The first layer is the CSM, where one spectrum supports one peptide-pair assignment. Multiple CSMs can support the same peptide pair. Multiple peptide pairs can point to the same residue pair because of missed cleavages, modifications, or site ambiguity. Several residue pairs can then support a protein-protein interaction.

Because each aggregation step changes the population being interpreted, the error rate must be propagated to the level used for biological interpretation. In this tutorial, the structural restraint is a residue pair, so residue-pair or link-level FDR is the relevant setting.

Self links and heteromeric links also require separate attention. The random search space for linking two residues within one protein differs from linking residues between two proteins, and heteromeric links can have different score behavior. xiFDR reports these classes separately, which is why the tutorial asks you to inspect self and heteromeric links independently.

Target-decoy logic in crosslinking MS

Target-decoy estimation depends on the idea that incorrect matches are similarly likely to hit target and decoy sequences. In crosslinking MS, a peptide pair can be target-target, target-decoy, or decoy-decoy. If the search space is well behaved, false target-target matches can be estimated from the decoy-containing matches.

The simplified relationship used here is:

Which FDR level answers which question?

Do not treat all FDR levels as interchangeable. A CSM-level threshold asks, "How many accepted spectrum assignments are expected to be wrong?" A peptide-pair threshold asks, "How many accepted linked peptide pairs are expected to be wrong?" A residue-pair threshold asks, "How many accepted crosslinked residue pairs are expected to be wrong?" A protein-pair threshold asks, "How many accepted protein-protein interactions are expected to be wrong?"

Those questions support different claims. Spectrum inspection happens at the CSM level. Structural restraint interpretation happens at the residue-pair level. Network-level biological summaries often happen at the protein-pair level. For this tutorial, the residue-pair level is the main decision point because the later xiview and structural modules ask whether specific residue pairs are compatible with 3D models.

Walkthrough: loading xiSEARCH results in xiFDR

If Do FDR was ticked in xiSEARCH, xiSEARCH can hand the results to xiFDR automatically. It is still useful to understand the standalone xiFDR step because it is where thresholds, result levels, and output files are defined.

Open xiFDR and load the xiSEARCH result file from the search output. Confirm that the FASTA/accession names are interpreted correctly, then keep the analysis focused on the level that matches the biological question. For this tutorial, use residue-pair or link-level FDR because the later analysis treats crosslinks as structural restraints. Keep the FDR threshold at 2%, and use the heteromeric-link boosting option described in the README workflow so interactions between different proteins are not lost simply because they form a smaller result class.

After filtering, export the result table used by xiview. That table is the version to inspect, visualize, and map onto structures. If you later want a stricter dataset, return to xiFDR and rerun the FDR calculation with stricter settings rather than filtering the already accepted table by score in xiview.

Interpreting xiFDR warnings

xiFDR warnings are not all equally serious. Always read the level at which the warning is reported: CSM, peptide pair, residue pair, protein pair, or protein group. A warning at a level you are not using for interpretation may be acceptable, while a warning at the residue-pair level is important in this tutorial because residue pairs become structural restraints.

A warning about not enough TT matches means there are too few target-target results to estimate the chosen FDR reliably at that level. This can happen when the dataset is nearly empty after filtering, when the search failed to identify enough plausible targets, or when the requested FDR threshold is too stringent for the amount of data. In that case, first ask whether the search settings, database, and chemistry were appropriate, then consider whether the FDR threshold or result level is too strict for the dataset.

A warning about too many DD matches is more concerning because it suggests the target-decoy assumptions are not behaving as expected. For a well-behaved crosslink search, target-decoy matches are expected to be more frequent than decoy-decoy matches, often approximately twice as frequent because there are two ways to form a target-decoy pair. If DD matches are too abundant, the decoy model may not be describing random matches well, the search space may be poorly balanced, or the result population may be too small or distorted for stable FDR estimation.

For this tutorial dataset, which contains only a small number of proteins, a warning at the protein-group level is not automatically alarming: there are not many possible protein groups to estimate. A warning at the residue-pair level is a much bigger problem because that is the level used to decide which crosslinks can be mapped onto structures and interpreted biologically.

Prefilters, score filters, and interpretation

Filtering before FDR estimation is part of defining the population whose error rate will be estimated. Filtering after FDR estimation creates a new population whose FDR has not been estimated. This distinction matters in xiview because the score slider is tempting: it can help you inspect spectra, but it should not be used to claim that a subset has a known FDR.

If a stricter result set is needed for biological interpretation, return to xiFDR and rerun the procedure with the stricter threshold or with justified prefilters applied before FDR calculation.

• I can explain TT, TD, DD, and the FDR formula.
• I can distinguish CSM, peptide-pair, residue-pair, and protein-pair FDR questions.
• I loaded or reviewed xiSEARCH results in xiFDR and exported the filtered result table.
• I set or reviewed the FDR threshold at the residue-pair level.
• I checked xiFDR warnings at the level used for interpretation, especially residue pairs.
• I understand why self and heteromeric links are treated separately.

Finding the main controls in xiview

xiview has a dense interface. Use these screenshots as a map before starting the exercises. The labels below refer to the same controls used later in the tutorial.

1 2 3

1 1 2 3 4

1 2 3 4

1 2

1

The protein name filter can be used to select crosslinks involving a single or multiple proteins. To select crosslinks between proteins, use:

SAMHD1-Cul
SAMHD1-Vpr
SAMHD1-DDB1
SAMHD1-DCAF
SAMHD1-Roc1

• I opened the xiview session and expanded proteins.
• I compared all links with heteromeric-only links.
• I inspected Vpr and SAMHD1 in circular view.

In the spectrum viewer, start with precursor mass error and charge state, then inspect sequence coverage and fragment-ion support. The usual peptide backbone fragments are b ions and y ions: b ions extend from the peptide N-terminus, while y ions extend from the C-terminus. A confident assignment should not be supported by one isolated peak; it should show a coherent pattern of fragments along both peptide sequences and a majority of the spectral intensity explained.

Crosslinked fragments are especially informative because they include one peptide plus the crosslinker and part or all of the partner peptide. xiview marks crosslinked fragments in bold. Move the cursor over sequence markers and peaks to use the dynamic highlighting: the viewer connects the peak, the fragment annotation, and the covered region of the sequence. Use this to ask whether the proposed crosslink site is actually supported by fragmentation or only inferred from limited coverage.

Sulfo-SDA can be cleaved in the mass spectrometer, especially when crosslinked to aspartic acid and glutamate, as discussed by the Sinz group. We accounted for this cleavability in the search, but the spectrum viewer does not display the cleaved crosslinker stubs by default. Inside the spectral viewer, click the wheel, open the custom tab, copy the following line, and press Apply.

crosslinker:AsymetricSingleAminoAcidRestrictedCrossLinker:Name:SDA;MASS:82.04186484;FIRSTLINKEDAMINOACIDS:*;SECONDLINKEDAMINOACIDS:K,S,T,Y,nterm;STUBS:A,82.041864,S,0

• I opened scan 7144 in the spectrum viewer.
• I tested the custom SDA annotation and compared views.
• I inspected at least one low-scoring passing spectrum below score 5.

Theory: why counts and distributions matter

Crosslinking yield is not only a property of the protein complex. It also depends on crosslinker concentration, chromatographic fraction, precursor charge state, ionization, fragmentation quality, and how often a particular peptide pair was sampled. Before interpreting an interface, inspect whether the dataset behaves as expected across conditions and fractions.

Use run filters to compare low SDA concentration files labelled 24 or Ratio24 with high SDA concentration files labelled 56 or Ratio56. These are not arbitrary run names: they come from two crosslinker-concentration conditions that were processed separately by in-gel digestion, separated on two SEC columns, and analysed fraction by fraction. Count total links and heteromeric links in each condition. Then use histogram and scatterplot views to compare frac6 and frac9 for number of crosslinks, charge state, and precursor mass.

• I compared Ratio24 and Ratio56.
• I compared frac6 and frac9 in histogram or scatterplot views.
• I noted how chromatographic behavior affects experimental design.

• I uploaded state-3 and opened the 3D viewer.
• I colored links by distance using the tutorial cutoffs.
• I compared all links with heteromeric-only links on the model.

pbonds style dashes 0

The xiview export is the fastest route because xiview has already handled the residue mapping. You can also work from scratch in ChimeraX with X-MAS, provided the residue numbering in the structure and the xiFDR table align. This alignment step is automatic in xiview, but in ChimeraX/X-MAS you need to make sure the PDB numbering and protein identifiers match the result file.

color bfactor palette alphafold

• I mapped crosslinks in X-MAS or know which files are required to do so.
• I know how to remove pseudobond dashes for cleaner visualization.

Background: DisVis

DisVis is designed for restraint-driven exploration rather than producing a single final model. Given two macromolecular partners and a set of distance restraints, it systematically searches the relative translations and rotations of one partner against the other. The output describes which regions of space are compatible with the restraints and how many restraints are satisfied or violated at each location.

For this course, precomputed DisVis outputs for localizing Vpr are available in the disvis folder of the course Google Drive package. Use those files when the aim is to learn interpretation rather than spend tutorial time waiting for a webserver run to finish.

This is useful when crosslinking MS suggests where a missing or flexible domain could be, but the data are not sufficient to define a unique structure. In this tutorial, DisVis is used to locate the viral recruitment interface: the circle plot points to a stable interaction between Vpr and the C-terminus of SAMHD1, while the rest of SAMHD1 behaves flexibly. DisVis lets you ask where a SAMHD1 C-terminal model could be placed around Vpr or the ligase complex while satisfying the crosslink restraints.

For the precomputed run in the Google Drive folder, DisVis was run with a peptide representing the SAMHD1 C-terminus as the scanning chain and the state 3 Cullin4-Vpr structure as the fixed chain. The relevant residue-pair crosslinks were converted into DisVis distance restraints, and DisVis sampled possible positions of the scanning peptide around the fixed complex. The resulting density reports accessible interaction space: positions that satisfy more restraints receive higher support. It is not experimental electron density, and it does not prove that every allowed position is occupied.

For the biological interpretation, compare the DisVis-accessible space with the xiview circle plot and the half-link 3D view. A focused accessible space near Vpr supports a stable SAMHD1 C-terminal recruitment site. Broad half-link coverage over the rest of the complex supports the idea that the remaining SAMHD1 body is flexible, which explains why it can leave crosslinking evidence without appearing as a well-resolved cryo-EM density.

The DisVis server documentation recommends citing the DisVis webserver and method papers listed on the DisVis portal. It is a great tool to identify "patches" in protein complexes to which other proteins bind to. The software can also be installed locally from the linked DisVis GitHub repository when webserver use is not appropriate.

open state-3_fit-chains.pdb
open disvis/accessible_interaction_space.mrc
volume #2 level 4
transparency #2 55

Other modeling approaches

AlphaLink, IMP, Assembline, and HADDOCK provide alternative routes for model building with restraints. They differ in how explicitly they model uncertainty, sampling, scoring, and prior structural information. The correct tool depends on whether the question is exploratory, docking-like, integrative, or prediction-oriented.

• I connected crosslink distances to possible structural states.
• I identified at least one modeling tool appropriate for missing or flexible regions.
• I can state what evidence would strengthen the final biological interpretation.