Completed spectrum viewer documentation and merged peptide

documentation. Various other documentation updates and fixes.
yeastrc · Oct 30, 2015 · 552e2af · 552e2af
1 parent e6cd0b2
commit 552e2af
Show file tree

Hide file tree

Showing 16 changed files with 276 additions and 9 deletions.
diff --git a/docs/images/get-help.png b/docs/images/get-help.png
diff --git a/docs/images/lorikeet-crosslink-ion-series.png b/docs/images/lorikeet-crosslink-ion-series.png
diff --git a/docs/images/lorikeet-example-crosslink.png b/docs/images/lorikeet-example-crosslink.png
diff --git a/docs/images/lorikeet-example-looplink.png b/docs/images/lorikeet-example-looplink.png
diff --git a/docs/images/lorikeet-example-monolink.png b/docs/images/lorikeet-example-monolink.png
diff --git a/docs/images/lorikeet-looplink-ion-series.png b/docs/images/lorikeet-looplink-ion-series.png
diff --git a/docs/images/manage-account.png b/docs/images/manage-account.png
diff --git a/docs/images/manage-users.png b/docs/images/manage-users.png
diff --git a/docs/images/merged-peptide-euler-diagram.png b/docs/images/merged-peptide-euler-diagram.png
diff --git a/docs/images/merged-peptide-page.png b/docs/images/merged-peptide-page.png
diff --git a/docs/images/signout.png b/docs/images/signout.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -20,10 +20,11 @@ Here you will find documentation for both using and installing ProXL.
 
    using/intro
    using/project
-   using/peptide
-   using/protein
    using/image
    using/structure
+   using/peptide
+   using/merged-peptide
+   using/protein
    using/spectrum-viewer
 
 

diff --git a/docs/using/intro.rst b/docs/using/intro.rst
@@ -87,6 +87,12 @@ Click the red (X) icon to the left of the project title on the project list to d
 that project. Only project owners may delete projects. Once a project is deleted,
 the project and all associated data will be removed.
 
+Get Help
+---------------------------------
+To view documentation for ProXL, click the (?) icon on the top-right nagivation
+bar present on all pages.
+
+.. image:: /images/get-help.png
 
 Manage Account
 ---------------------------------

diff --git a/docs/using/merged-peptide.rst b/docs/using/merged-peptide.rst
@@ -0,0 +1,225 @@
+====================================
+Merged Peptides View Page
+====================================
+
+.. image:: /images/merged-peptide-page.png
+
+To reach this page, select multiple searches on the project page and click
+"View Merged Peptides". (See :doc:`/using/project`.) This page combines and collates
+the data from multiple searches and presents the results as an interactive table.
+The searches do not need to be from the same software pipeline. For example,
+different versions of the same program may be compared, or the results from
+entirely different programs (e.g., Kojak and XQuest) may be compared. Currently,
+the total number of merged runs must be 2 or 3 and must be from the same
+project. Note, for the peptide view page seen when viewing a single search,
+see :doc:`/using/peptide`.
+
+Search List
+=========================
+The list of merged searches is presented below the top navigation. Each search
+is shown next to its assigned color for the page, and the color referencing
+this search is retained in the Euler diagram and in the peptide table. Clicking the
+[+] icon will expand that search to view details:
+
+Search Details
+---------------------------
+The "Path" is the location on disk from which the data were imported. The "Linker" is the
+name of the crossinker used in the experiment. "Search Program(s)" is the name and
+version number of the PSM search software used. "Upload date" is the date the data were
+uploaded into ProXL. "FASTA file" is the name of the FASTA file used to perform the
+PSM search.
+
+Filter Data
+=========================
+The data presented may be filtered according to the following criteria. Note: Only peptides
+that meet ALL of the specified criteria are returned.
+
+PSM q-value cutoff
+-------------------------
+Only peptides that were identified by at least one PSM with a q-value <= to the value
+specified will be shown.
+
+Peptide q-value cutoff
+-------------------------
+Only peptides that have a peptide-level q-value <= the value specified will be shown.
+As not all software produces peptide-level q-values, this field will have no effect
+on those data.
+
+Type filter
+-------------------------
+Only peptides of the checked type(s) will be returned. Proxl defines the types as:
+
+	* crosslink - A pair of peptides linked by a crosslinker.
+	* looplink - A single peptide with two residues linked by a crosslinker.
+	* monolink - A peptide containing at least one linked residue, where the other end of the linker is unlinked.
+	* unlinked - The peptide without a crosslinker on any residue.
+
+Checking multiple boxes will include any peptide that has at least one of the checked types.
+I.e., checking 'crosslinks' and 'looplinks' will only include peptides that are either
+crosslinks or looplinks. Only checking 'crosslinks' will only return crosslinked peptides.
+The 'monolinks' type will include any peptides that contain a monolink.
+
+
+Modification filter
+-------------------------
+Only peptides with at least one of the checked modifications will be included. Note that monolinks
+are considered modifications of residues in ProXL, so the mass of the crosslinker when found
+on monolinks is included here.
+
+Update
+-------------------------
+In order to apply new filter parameters to the shown data, the "Update" button must be clicked. This will
+fetch filtered data from the ProXL server and display the data on the web page.
+
+Euler diagram
+======================================
+.. image:: /images/merged-peptide-euler-diagram.png
+
+The Euler diagram (similar to a Venn diagram) provides a graphical depiction of the overlap
+between the peptides found in the merged searches. The colors in the diagram match
+the colors used for the search list above. The search list is provided  to the
+left of the diagram with their associated colors as a legend. The labels for each
+color include the search ID number and the number of distinct peptides found in each
+of the merged searches. The total number of peptides resulting from the merge is presented
+in the header above the legend next to "Peptides".
+
+The "[Download Data]" link in the legend header will download the data in the table as a
+tab-delimited text file.
+
+Table Description
+=========================
+The table presents columns describing the peptides and indicates in which of the merged searches
+the peptides were found. There is one row per peptide. A peptide on this page is defined as the
+unique combination of peptide sequence(s), link positions in those peptides, and dynamic modifications
+present on the peptides. So an unmodified peptide and a modified peptide with the same sequence will
+appear as separate rows in the table. Each row in the table may be clicked on to expand and view
+the peptide-level statistics for the given peptide from each search. Each of these searches may
+then be clicked on to view PSMs and spectra from those searches.
+
+Columns
+-------------------------
+The columns are described below. Note that all column headers may be clicked to toggle between ascending and
+descending sorting of that column. Holding the shift key while clicking column headers allow sorting on
+multiple columns.
+
+Search Columns
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The first 1-3 columns will be labeled with search ID numbers as headers, and provide an indication for
+whether or not the peptide in that row was found in that search. If found in that search, the cell for
+this search in this row will be shaded the same color associated with that search in the Euler diagram
+and search list at the top of the page. The column will also contain an asterisk. If not found, this
+cell is empty.
+
+Searches
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The number of the merged searches that contain this peptide. The [+] icon indicates that the row may be clicked on to
+be expanded to show underlying searches in which this peptide as found, the stats for this peptide from each
+search, and the ability to view PSMs and associated spectra.
+
+Type
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The type of peptide (crosslink, looplink, or unlinked).
+
+Peptide 1
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The parsed sequence of the peptide (or the first peptide in the case of crosslinks).
+
+Pos
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The position in that peptide containing the linker.
+
+Mods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+A comma-delimited list of dynamic modifications found for peptide 1 in the form of position(mass).
+E.g., 17(15.99), 20(14.02)
+
+Peptide 2
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The parse sequence of the second peptide in the crosslink.
+
+Pos
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The position in that peptide containing the linker.
+
+Mods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+A comma-delimited list of dynamic modifications found for peptide 2 in the form of position(mass).
+E.g., 17(15.99), 20(14.02)
+
+Protein 1
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The protein(s) to which the first peptide matches, and the position in that
+protein to which the linker position in that peptide matched. Mouse-over
+the protein name to get a description.
+
+Protein 2
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The protein(s) to which the second peptide matches, and the position in that
+protein to which the linker position in that peptide matched. Mouse-over
+the protein name to get a description.
+
+Best Q-value
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The best peptide-level q-value from the searches, if available.
+
+# PSMs
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The total number of PSMs from the searches for this peptide that have a q-value <= the specified PSM-level cutoff that identified this peptide. Note: click
+the table row containing the peptide to see all the PSMs.
+
+View PSMs
+=========================
+To view PSMs for a given peptide, first click on a row in the table to expand and view the peptide-level statistics for a given
+peptide from each search in which it was found (at the given cutoffs). Each of these searches may be clicked to expand and view all
+PSMs with a q-value <= the specified PSM-level cutoff. 
+
+Columns
+-------------------------
+The PSMs appear in a table with the following columns:
+
+Scan Num.
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The scan number from the spectral file (e.g., mzML file)
+
+Charge
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The predicted charge state of the precursor ion.
+
+Obs. m/z
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The observed m/z of the precursor ion.
+
+RT (min)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The retention time in minutes.
+
+Scan Filename
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The filename of the scan file.
+
+Q-value
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The q-value for the PSM.
+
+PEP
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The posterior error probabiliy for this PSM, if available.
+
+SVM Score
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The support vector machine score for this PSM, if available.
+
+View Spectra
+-------------------------
+The annotated mass spectrum may be viewed for any PSM by clicking the "View Spectrum" link. For help on our
+spectrum viewer, see the :doc:`/using/spectrum-viewer` page.
+
+Sort Data
+=========================
+All column headers may be clicked to toggle between ascending and
+descending sorting of that column. Holding the shift key while clicking column headers allow sorting on
+multiple columns.
+
+Download Data
+=========================
+Clicking the [Download Data] link in the header of the Euler diagram will download the shown data as a tab-delimited text file.
diff --git a/docs/using/peptide.rst b/docs/using/peptide.rst
@@ -8,14 +8,23 @@ The peptide view page provides a table view of the data at the peptide level.
 That is, all peptides (and crosslinked peptide pairs) identified by the search
 software may be viewed on this page--along with accompanying peptide spectrum
 matches (PSMs) and tandem mass spectra. The data presented may be filtered according
-to confidence, type of peptide, and which modifications are present on the peptide.
+to confidence, type of peptide, and which modifications are present on the peptide. Note,
+this document covers the peptide view page for a single search. For the view page seen
+when merging multiple searches, see :doc:`/using/merged-peptide`.
 
 Search Information
 =========================
 The name of the search (and internal search ID reference number) from which these
-data were obtained is shown first. The red [+] icon may be clicked to reveal more
-information about the search, including the path the data were imported from,
-the linker that was used, the upload date, and the FASTA file that was searched.
+data were obtained is shown first. The red [+] icon may be clicked to reveal details
+about the search.
+
+Search Details
+---------------------------
+The "Path" is the location on disk from which the data were imported. The "Linker" is the
+name of the crossinker used in the experiment. "Search Program(s)" is the name and
+version number of the PSM search software used. "Upload date" is the date the data were
+uploaded into ProXL. "FASTA file" is the name of the FASTA file used to perform the
+PSM search.
 
 Filter Data
 =========================

diff --git a/docs/using/spectrum-viewer.rst b/docs/using/spectrum-viewer.rst
@@ -137,13 +137,39 @@ Modifications present in the PSM are shown in this panel. "Static Modifications"
 given residue in the PSM search. "Variable Modifications" mass modifications that may or may not be present on the given residue
 during the search. The position of the variable modification in the peptide sequence is given in brackets.
 
-Monolink Spectra
+Monolink Spectrum
 ========================================
+Monolinks in ProXL are treated as modifications on residues in the same way as other post-translational modifications. There may be multiple
+monolinks present in the sequence, and monolinks may appear in unlinked, crosslinked or looplinked peptides. In the example
+below, the modification on the lysine at position 7 has a mass of 156.08, the mass of the crosslinker used in this experiment when it has bound
+to an amino acid on one end (but not the other). This residue is highlighted in the "PSM Details" area and in the sequence presented in
+the "Fragment Ion Series" panel. The modification is also listed in the "Residue Mass Modifications" below the "Fragment Ion Series" panel.
 
-Crosslink Spectra
+.. image:: /images/lorikeet-example-monolink.png
+
+Crosslink Spectrum
 ========================================
+Crosslinks between peptides may, from the point of view of each peptide, be thought of a large mass modification on the linked residue equal to the
+mass of the reacted crosslinker plus the mass of the other peptide. This is illustrated in the figure below. The hypothetical b- and y-ion series for the "circle" peptide
+and "square" peptide are given. Note that the opposite peptide is present as a modification on the linked residue in each peptide.
+
+.. image:: /images/lorikeet-crosslink-ion-series.png
+
+ProXL displays the ion series for each of the linked peptides separately. The sequences and positions of the crosslink are presented graphically at the top of
+the window. In the sequence presented in the "Fragment Ion Series" panel for each peptide, the linked residue is highlighted green.
 
-Looplink Spectra
+.. image:: /images/lorikeet-example-crosslink.png
+
+Looplink Spectrum
 ========================================
+Looplink peptides contain a crosslinker that has linked two residues in the single peptide. When calculating ion series, ProXL treats the sub-sequence
+between the linked residues (inclusive) as a single unit, as cleavages between the linked residues would result in crosslinked peptides--not a looplinked
+peptide. As a result, a hypothetical b- and y-ion series for a looplinked peptide would look be as follows:
+
+.. image:: /images/lorikeet-looplink-ion-series.png
 
+The subunit "PTI" is treated as a single residue normally would be when calculating the theoretical ion series. Below is an example spectrum displayed
+in Lorikeet that treats the looplinked subunit as a single entity. Note when moving to b9/y19, the mass is increased by the sum of KFPK plus the
+crosslinker.
 
+.. image:: /images/lorikeet-example-looplink.png