|
| 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 | +[](https://mybinder.org/v2/gh/BioFSharp/BioFSharp.Mz/gh-pages?filepath={{fsdocs-source-basename}}.ipynb)  |
| 26 | +[]({{root}}{{fsdocs-source-basename}}.fsx)  |
| 27 | +[]({{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