Skip to content

Commit c8e6e9b

Browse files
authored
Merge pull request #13 from BioFSharp/developer
Add gh-pages documentation for BioFSharp.Mz
2 parents 2ea4929 + 67f8219 commit c8e6e9b

17 files changed

Lines changed: 83434 additions & 5 deletions

‎build/DocumentationTasks.fs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ let buildDocs =
1212

1313
runDotNet
1414
(sprintf
15-
"fsdocs build --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
15+
"fsdocs build --clean --properties Configuration=Release --parameters root https://biofsharp.com/BioFSharp.Mz/ fsdocs-package-version %s"
1616
stableVersionTag)
1717
"./"
1818
}
@@ -23,7 +23,7 @@ let buildDocsPrerelease =
2323

2424
runDotNet
2525
(sprintf
26-
"fsdocs build --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
26+
"fsdocs build --clean --properties Configuration=Release --parameters root https://biofsharp.com/BioFSharp.Mz/ fsdocs-package-version %s"
2727
prereleaseTag)
2828
"./"
2929
}
Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
(**
2+
---
3+
title: Peaks and peak arrays
4+
category: Spectrum processing
5+
categoryindex: 1
6+
index: 1
7+
---
8+
*)
9+
10+
(*** hide ***)
11+
12+
(*** condition: prepare ***)
13+
#r "nuget: FSharpAux, 2.1.0"
14+
#r "nuget: FSharpAux.IO, 2.1.0"
15+
#r "nuget: FSharp.Stats, 0.6.0"
16+
#r "nuget: BioFSharp, 2.0.0"
17+
#r "../src/BioFSharp.Mz/bin/Release/netstandard2.0/BioFSharp.Mz.dll"
18+
19+
(*** condition: ipynb ***)
20+
#if IPYNB
21+
#r "nuget: BioFSharp.Mz, {{fsdocs-package-version}}"
22+
#endif // IPYNB
23+
24+
(**
25+
[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/BioFSharp/BioFSharp.Mz/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
26+
[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
27+
[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
28+
29+
# Peaks and peak arrays
30+
31+
A mass spectrometer separates ions by their mass-to-charge ratio (m/z) and records how
32+
many of them arrive at the detector. A peak is the recorded signal of one ion species.
33+
In raw profile data that signal is a bump spanning many measured points around the
34+
ion's true m/z. Centroiding reduces each such bump to a single representative pair of
35+
an m/z value and an intensity, a step covered on the
36+
[signal detection]({{root}}01_02_signal_detection.html) page. The `Peak` type in
37+
BioFSharp.Mz models exactly this centroided form, and it is the smallest unit
38+
everything else is built from. Fragment matching, database search, spectrum scoring and
39+
similarity comparisons all consume or produce peaks.
40+
41+
This page loads a measured MS2 spectrum from an mgf file, represents it as a `PeakArray`,
42+
introduces tagged peaks and peak families (the vocabulary of fragment ion matching), and
43+
finally converts the spectrum into the binned and sparse forms that spectrum scoring
44+
works on.
45+
46+
## Reading a spectrum from an mgf file
47+
48+
Mascot generic format (mgf) is a plain text format for MS2 data. Every entry holds a
49+
peak list plus metadata such as the precursor m/z (the m/z of the intact peptide ion
50+
that was selected for fragmentation) and its charge state. BioFSharp ships a reader in
51+
`BioFSharp.IO.MGF`, and the entry type with its metadata accessors lives in
52+
`BioFSharp.FileFormats.MGF`. The example file contains a single MS2 scan of the doubly
53+
charged peptide ANLGMEVMHER.
54+
*)
55+
56+
open BioFSharp.FileFormats.MGF
57+
open BioFSharp.IO
58+
open BioFSharp.Mz
59+
60+
let ms2 =
61+
MGF.read (__SOURCE_DIRECTORY__ + "/data/ms2Example.mgf")
62+
|> List.head
63+
64+
printfn "%s" (MGFEntry.tryGetTitle ms2 |> Option.defaultValue "no title")
65+
66+
match MGFEntry.tryGetPrecursorMZ ms2, MGFEntry.tryGetPrecursorCharges ms2 with
67+
| Some mz, Some charges -> printfn "precursor m/z %f at charge %A" mz charges
68+
| _ -> printfn "no precursor information"
69+
70+
(**
71+
```text
72+
MS/MS scan at 20.93388333 min with Intensity: 501.0 and Sequence ANLGMEVMHER
73+
precursor m/z 643.803548 at charge [2]
74+
```
75+
76+
The reader hands back the m/z and intensity values as two separate arrays. `PeakArray.zip`
77+
pairs them up into one `PeakArray`, an array of `Peak` values. `Peak` is a small struct
78+
carrying `Mz` and `Intensity`, and it implements the `IPeak` interface that all peak-like
79+
types in the library share.
80+
*)
81+
82+
let spectrum : PeakArray<Peak> = PeakArray.zip ms2.Mass ms2.Intensity
83+
84+
printfn "peak count: %i" spectrum.Length
85+
86+
spectrum
87+
|> Array.truncate 3
88+
|> Array.iter (fun p -> printfn "m/z %f intensity %f" p.Mz p.Intensity)
89+
90+
(**
91+
```text
92+
peak count: 971
93+
m/z 100.666675 intensity 10.000000
94+
m/z 103.057515 intensity 12.000000
95+
m/z 103.068913 intensity 12.000000
96+
```
97+
98+
Some of the 971 entries are adjacent samples of the same ion signal, so the list is denser than a fully centroided spectrum, a distinction the
99+
[signal detection]({{root}}01_02_signal_detection.html) page develops. The low
100+
intensity values are typical for a single MS2 scan of a low abundance precursor.
101+
102+
## Creating and transforming peaks
103+
104+
Single peaks are created with `Peaks.createPeak`. Because `PeakArray` is a plain array
105+
under the hood, the familiar `Array` functions work on it, and `PeakArray.map` builds a
106+
new peak array from an existing one. A common use is normalizing all intensities to the
107+
most intense peak of the spectrum (the base peak), which makes spectra of different
108+
absolute intensity comparable.
109+
*)
110+
111+
let singlePeak = Peaks.createPeak 175.119 24.
112+
printfn "m/z %f intensity %f" singlePeak.Mz singlePeak.Intensity
113+
114+
let basePeakIntensity =
115+
spectrum |> Array.map (fun p -> p.Intensity) |> Array.max
116+
117+
let normalized =
118+
spectrum
119+
|> PeakArray.map (fun p -> Peaks.createPeak p.Mz (p.Intensity / basePeakIntensity))
120+
121+
normalized
122+
|> Array.truncate 3
123+
|> Array.iter (fun p -> printfn "m/z %f relative intensity %f" p.Mz p.Intensity)
124+
125+
(**
126+
```text
127+
m/z 175.119000 intensity 24.000000
128+
m/z 100.666675 relative intensity 0.058824
129+
m/z 103.057515 relative intensity 0.070588
130+
m/z 103.068913 relative intensity 0.070588
131+
```
132+
133+
`PeakList` is the list-backed sibling of `PeakArray` with the same `zip` and `map`
134+
functions. When you need the raw m/z and intensity sequences back, for example
135+
to feed a plotting library, `PeakList.unzip` splits a peak list into its two component
136+
lists.
137+
*)
138+
139+
let mzList, intensityList =
140+
spectrum |> List.ofArray |> PeakList.unzip
141+
142+
printfn "m/z values: %A" (mzList |> List.truncate 3)
143+
printfn "intensity values: %A" (intensityList |> List.truncate 3)
144+
145+
(**
146+
```text
147+
m/z values: [100.666675; 103.057515; 103.068913]
148+
intensity values: [10.0; 12.0; 12.0]
149+
```
150+
151+
## Tagging peaks with ion types
152+
153+
When a peptide is fragmented in the mass spectrometer, its backbone breaks at
154+
characteristic positions. A fragment that keeps the N-terminus is called a b ion, one
155+
that keeps the C-terminus a y ion (there are more series, a, c, x and z). A peak on its
156+
own does not know which fragment it belongs to. For fragment matching the library
157+
attaches that information as a tag: `Ions.IonTypeFlag` is a flags enum naming the ion
158+
series, `TaggedMass` pairs a flag with a mass, and `TaggedPeak.TaggedPeak` pairs a flag
159+
with an m/z and an intensity.
160+
161+
The tags become concrete with two fragments of ANLGMEVMHER, computed by hand from the
162+
monoisotopic residue masses. The b2 ion covers the first two residues, the y1 ion is the
163+
C-terminal arginine.
164+
*)
165+
166+
// b2 of ANLGMEVMHER: A + N + proton = 71.03711 + 114.04293 + 1.00728
167+
let b2 = TaggedMass.createTaggedMass Ions.IonTypeFlag.B 186.08732
168+
169+
// y1 of ANLGMEVMHER: R + H2O + proton = 156.10111 + 18.01056 + 1.00728
170+
let y1 = TaggedMass.createTaggedMass Ions.IonTypeFlag.Y 175.11895
171+
172+
printfn "%A ion at m/z %f" b2.Iontype b2.Mass
173+
printfn "%A ion at m/z %f" y1.Iontype y1.Mass
174+
175+
(**
176+
```text
177+
B ion at m/z 186.087320
178+
Y ion at m/z 175.118950
179+
```
180+
181+
Fragments often show up together with satellite peaks, for example the same ion minus a
182+
water molecule (18.01056 Da lighter). `TaggedMass.createTaggedH2OLoss` builds such a
183+
loss tag by combining the ion series flag with the `lossH2O` flag, and
184+
`Peaks.createPeakFamily` groups a main peak with its dependent satellite peaks into a
185+
`PeakFamily`. The [in silico fragmentation]({{root}}02_01_fragmentation.html) page
186+
produces exactly this shape, `PeakFamily<TaggedMass>` values for every fragment of a
187+
peptide, so the type is introduced here on a small example.
188+
*)
189+
190+
let y1WaterLoss =
191+
TaggedMass.createTaggedH2OLoss Ions.IonTypeFlag.Y (175.11895 - 18.01056)
192+
193+
let y1Family = Peaks.createPeakFamily y1 [ y1WaterLoss ]
194+
195+
printfn "main peak: %A at m/z %f" y1Family.MainPeak.Iontype y1Family.MainPeak.Mass
196+
y1Family.DependentPeaks
197+
|> List.iter (fun t -> printfn "dependent peak: %A at m/z %f" t.Iontype t.Mass)
198+
199+
(**
200+
```text
201+
main peak: Y at m/z 175.118950
202+
dependent peak: Y, lossH2O at m/z 157.108390
203+
```
204+
205+
The dependent peak carries both flags at once, which is what a flags enum is for. A
206+
matching function can later ask for the series with `Ions.hasFlag`.
207+
208+
Because ANLGMEVMHER is the peptide that was actually fragmented in our example scan, its
209+
y1 ion should be present in the measured spectrum. It is.
210+
*)
211+
212+
spectrum
213+
|> Array.filter (fun p -> abs (p.Mz - y1.Mass) < 0.05)
214+
|> Array.iter (fun p -> printfn "measured peak near y1: m/z %f intensity %f" p.Mz p.Intensity)
215+
216+
(**
217+
```text
218+
measured peak near y1: m/z 175.118252 intensity 12.000000
219+
measured peak near y1: m/z 175.120109 intensity 12.000000
220+
measured peak near y1: m/z 175.121966 intensity 24.000000
221+
```
222+
223+
A `TaggedPeak.TaggedPeak` adds an intensity to the tag and implements `IPeak` like every
224+
other peak type, so tagged peaks fit into a `PeakArray` as well.
225+
*)
226+
227+
let y1Peak = TaggedPeak.createTaggedPeak Ions.IonTypeFlag.Y 175.11895 24.
228+
printfn "%A peak at m/z %f with intensity %f" y1Peak.Iontype y1Peak.Mz y1Peak.Intensity
229+
230+
(**
231+
```text
232+
Y peak at m/z 175.118950 with intensity 24.000000
233+
```
234+
235+
## Binning a spectrum into unit dalton bins
236+
237+
SEQUEST-style scoring compares a measured spectrum against a predicted one as vectors.
238+
For that the continuous m/z axis is discretized into bins of 1 Da width, and every peak
239+
is assigned to its nearest bin. `PeakArray.peaksToNearestUnitDaltonBinVector` performs
240+
this conversion between a lower and an upper mass border and returns an `FSharp.Stats`
241+
vector. When several peaks fall into the same bin, the bin keeps the highest intensity.
242+
The produced vector has length `maxMassBoarder - minMassBoarder`, here 900 bins covering
243+
m/z 100 to 1000.
244+
*)
245+
246+
open FSharp.Stats
247+
248+
let binned = PeakArray.peaksToNearestUnitDaltonBinVector spectrum 100.0 1000.0
249+
250+
printfn "vector length: %i" (Vector.length binned)
251+
252+
let occupied =
253+
binned
254+
|> Vector.toArray
255+
|> Array.indexed
256+
|> Array.filter (fun (_, intensity) -> intensity > 0.)
257+
258+
printfn "occupied bins: %i" occupied.Length
259+
260+
occupied
261+
|> Array.truncate 5
262+
|> Array.iter (fun (i, intensity) -> printfn "bin %i (m/z %i): %f" i (i + 100) intensity)
263+
264+
(**
265+
```text
266+
vector length: 900
267+
occupied bins: 378
268+
bin 1 (m/z 101): 10.000000
269+
bin 3 (m/z 103): 12.000000
270+
bin 4 (m/z 104): 12.000000
271+
bin 10 (m/z 110): 24.000000
272+
bin 12 (m/z 112): 10.000000
273+
```
274+
275+
971 peaks collapse into 378 occupied bins because peaks closer together than 1 Da share
276+
a bin. The bin index is simply the rounded m/z minus the lower mass border, so bin 0
277+
collects the peaks around m/z 100.
278+
279+
## Comparing spectra with sparse peak arrays
280+
281+
Most of the 900 bins above are zero. `SparsePeakArray` stores only the occupied bins in
282+
a dictionary from bin index to intensity, which saves memory and makes comparing two
283+
spectra a walk over one dictionary with lookups in the other.
284+
`SparsePeakArray.peaksToNearestBinVector` builds one from a peak array. The first two
285+
arguments control the binning: with a bin width of 1.0 and an offset of 0.5 every peak
286+
lands in its nearest unit bin. In the sparse form, peaks sharing a bin are summed. The
287+
record also carries the two conversion functions `MzToBinIdx` and `BinIdxToMz` so you
288+
can move between m/z values and bin indices.
289+
*)
290+
291+
let sparse =
292+
spectrum
293+
|> SparsePeakArray.peaksToNearestBinVector 1.0 0.5 100.0 1000.0
294+
295+
printfn "occupied bins: %i" sparse.Data.Count
296+
printfn "bin index of the y1 m/z: %i" (sparse.MzToBinIdx 175.11895)
297+
298+
(**
299+
```text
300+
occupied bins: 378
301+
bin index of the y1 m/z: 175
302+
```
303+
304+
`SparsePeakArray.dot` computes the dot product of two sparse spectra: for every bin both
305+
spectra occupy, it multiplies the intensities and sums the products. The dot product
306+
(usually after normalization) is the standard similarity measure between binned spectra,
307+
and a spectrum compared with itself gives the maximal value.
308+
309+
The example file contains only one scan, so we simulate a spectrum of an unrelated
310+
peptide by shifting every measured m/z by 7.3 Da. The shifted copy has the same
311+
intensity distribution, only in different bins.
312+
*)
313+
314+
// same peaks moved by 7.3 Da: a stand-in for a spectrum of an unrelated peptide
315+
let shifted =
316+
spectrum
317+
|> PeakArray.map (fun p -> Peaks.createPeak (p.Mz + 7.3) p.Intensity)
318+
319+
let sparseShifted =
320+
shifted
321+
|> SparsePeakArray.peaksToNearestBinVector 1.0 0.5 100.0 1000.0
322+
323+
printfn "self dot product: %f" (SparsePeakArray.dot sparse sparse)
324+
printfn "cross dot product: %f" (SparsePeakArray.dot sparse sparseShifted)
325+
326+
(**
327+
```text
328+
self dot product: 3692147.000000
329+
cross dot product: 163836.000000
330+
```
331+
332+
The spectrum agrees with itself far better than with the shifted copy, exactly what a
333+
similarity measure should say. The remaining cross product comes from bins where a
334+
shifted peak happens to land on another real peak.
335+
336+
The next step is generating predicted fragment peaks to match against, the topic of the
337+
[in silico fragmentation]({{root}}02_01_fragmentation.html) page.
338+
*)

0 commit comments

Comments
 (0)