Frequently Asked Questions
==========================

.. contents:: Table of contents
    :local:
    :backlinks: entry

What is a pairing file?
-------
A pairing file is a tab-delimited file that explicity pairs target and decoy
peptide sequences. Previous work has shown that taking advantage of paired
target and decoys can lead to improved number of peptide detections (see 
`Lin et al. <https://pubs.acs.org/doi/abs/10.1021/acs.jproteome.2c00282>`_).
This file can be generated by setting --peptide-list=T in tide-index within the
`Crux toolkit <https://crux.ms>`_ or by hand.

If this file is generated by hand the following three columns are required. One
column must be labeled 'target' must contain target sequences, a second 
column labeled 'decoy(s)' must contain decoy sequences, and a third column
labeled 'proteins' must contain a comma separated list of proteins the target
peptide could originate from.

Alternatively you can set pep_fdr_type argument within the assign_confidence
function to "psm-only". Note that this method obtains worse performance
compared to when paired information is used.

Why are PSM-level FDR estimates not guaranteed to control the FDR?
-------
The target-decoy competition (TDC) framework has been provably shown to control
the FDR under two assumptions (see 
`He et al. <https://arxiv.org/abs/1501.00537`_). First, an incorrect match is 
equally likely to match a target or decoy peptide, and second,
PSMs are independent from each other. When estimating the FDR at the PSM-level,
this second assumption is violated because the same peptide can generate 
multiple spectra. We note that while dynamic exclusion reduces the magnitude of
problem it does not solve it.

Empirical evidence that PSM-level FDR do not necessarily control the FDR can be 
found at `Lin et al. <https://pubs.acs.org/doi/abs/10.1021/acs.jproteome.2c00282>`_
and `He et al. <https://arxiv.org/abs/1501.00537`_.
