fragment matching

Dear Laurent,

this PR adds the `crossMatching` method (and a lot of helper methods) that allows to match fragments between the identification and quantitation run for diagnostic purposes and to get rid of some non unique matches.

New user-visible functions/methods are:
- `updateSynapterObject` (it is hidden but throws a `message` if an update is performed)
- `loadSpectra` - loads the ugly `Spectrum.xml` files
- `loadFragments` - loads the `final_fragment.csv` files
- `crossMatching` - performs the cross matching
- `{set,get}CrossMatchingPpmTolerance` - set/get the mass tolerance in ppm
- `plotCrossMatching` - creates the spectra vs fragments plots 
- `plotCrossMatchingSummary` - creates the FDR/F1, TP, TN, ... plots and the boxplot
- `{set,get}CrossMatchingMinimalNumberOfCommonPeaks` - set/get the minimal number of common peaks
- `filterMatchedEMRTsByCommonPeaks` - tunrs non unqiue matches into unique ones

There is (at least) one question left: 
In `crossMatching` we calculate the common peaks for
 1. the identification spectra vs the quantitation fragments
 2. the quantitation spectra vs the identification fragments
 3. the identification fragments vs the quantitation fragments.

But we use only the information of 3. Should we avoid the calculation of 1. and 2.?
(They would be recalculated in the `plotCrossMatching` method anyway because we need the position of the common peaks and not only the absolute number of them.)

Best wishes,

Sebastian

P.S.: Please find the example Rmd file here: https://gist.github.com/sgibb/11305484
I add the output below for documentation:

# Cross Matching Example

## Default Synapter Preprocessing

(same as in `synergise`)

```s
suppressPackageStartupMessages(library("synapter"))
```

### File Import

```s
dataPath <- file.path("..", "..", "..", "playground", "data",
                      "biological_replicas_for_synapter")
iaPath <- file.path(dataPath, "HDMSE", "ia")
apexPath <- file.path(dataPath, "HDMSE", "apex")

input <- list(
  identpeptide=file.path(iaPath,
                         "fermentor_02_sample_15_HDMSE_01_20140303114821",
                         "fermentor_02_sample_15_HDMSE_01_IA_final_peptide.csv"),
  quantpeptide=file.path(iaPath,
                         "fermentor_03_sample_15_HDMSE_01_20140303120343",
                         "fermentor_03_sample_15_HDMSE_01_IA_final_peptide.csv"),
  quantpep3d=file.path(apexPath,
                       "fermentor_03_sample_15_HDMSE_01_20140302183822",
                       "fermentor_03_sample_15_HDMSE_01_Pep3DAMRT.csv"),
  fasta=file.path(dataPath,
                  "S.cerevisiae_uniprot_reference_canonical_16_09_13.fasta"))

## only for reproducibility
set.seed(1)
system.time(s <- Synapter(input))
```

```
## Reading identification final peptide file...
## Reading quantitation final peptide file...
## Reading quantitation Pep3D file...
## Filtering...
## Computing identification statistics...
```

```
##    user  system elapsed 
##  130.49    1.64  132.63
```


### Filtering

```s
filterUniqueDbPeptides(s, verbose=TRUE)
```

```
## Fasta file: 6621 proteins
##             179685 out of 192291 tryptic peptides are proteotypic.
```

```s
fdr <- fpr <- 0.05
ppm <- 20

filterIdentPepScore(s, method="BH", fdr=fdr)
filterQuantPepScore(s, method="BH", fdr=fdr)
filterIdentProtFpr(s, fpr=fpr)
filterQuantProtFpr(s, fpr=fpr)
filterIdentPpmError(s, ppm=ppm)
filterQuantPpmError(s, ppm=ppm)
```


### RT Model and Grid Search

```s
mergePeptides(s)

modelRt(s, span=0.05)

system.time(searchGrid(s, verbose=FALSE))
```

```
##    user  system elapsed 
##  34.666   0.576  35.324
```

```s

setBestGridParams(s)

findEMRTs(s)
s
```

```
## Object of class "Synapter" 
## Package version 1.7.2 
## Data files:
##  + Quantitation pep file: fermentor_03_sample_15_HDMSE_01_IA_final_peptide.csv 
##  + Identification pep file: fermentor_02_sample_15_HDMSE_01_IA_final_peptide.csv 
##  + Quantitation Pep3DAMRT file: fermentor_03_sample_15_HDMSE_01_Pep3DAMRT.csv 
##  + Fasta file: S.cerevisiae_uniprot_reference_canonical_16_09_13.fasta 
## Log:
## [1] "Instance created on Mon Apr 28 19:49:12 2014"
## [2] "Read identification peptide data [32308,66]" 
## [ 29 lines ]
## [32] "Set 'nsd' and 'ppm error' to 2 and 8 (best 'auto')"
## [33] "Matched identification peptides and quantitation EMRTs [6388,127] (rescue)"
```


## Cross Matching

new workflow part

### File Import

#### Spectra

```s
system.time(loadSpectrumXmlFiles(s, list(
  identspectrum=file.path(apexPath,
                          "fermentor_02_sample_15_HDMSE_01_20140302181938",
                          "fermentor_02_sample_15_HDMSE_01_Pep3D_Spectrum.xml"),
  quantspectrum=file.path(apexPath,
                          "fermentor_03_sample_15_HDMSE_01_20140302183822",
                          "fermentor_03_sample_15_HDMSE_01_Pep3D_Spectrum.xml")),
                        verbose=FALSE))
```

```
##    user  system elapsed 
## 539.206   9.624 558.788
```


#### Fragments

```s
system.time(loadFragmentCsvFiles(s, list(
  identfragments=file.path(iaPath,
                          "fermentor_02_sample_15_HDMSE_01_20140303114821",
                          "fermentor_02_sample_15_HDMSE_01_IA_final_fragment.csv"),
  quantfragments=file.path(iaPath,
                          "fermentor_03_sample_15_HDMSE_01_20140303120343",
                          "fermentor_03_sample_15_HDMSE_01_IA_final_fragment.csv")),
                          verbose=FALSE))
```

```
##    user  system elapsed 
## 397.377   8.997 411.308
```



```s
s
```

```
## Object of class "Synapter" 
## Package version 1.7.2 
## Data files:
##  + Quantitation pep file: fermentor_03_sample_15_HDMSE_01_IA_final_peptide.csv 
##  + Identification pep file: fermentor_02_sample_15_HDMSE_01_IA_final_peptide.csv 
##  + Quantitation Pep3DAMRT file: fermentor_03_sample_15_HDMSE_01_Pep3DAMRT.csv 
##  + Fasta file: S.cerevisiae_uniprot_reference_canonical_16_09_13.fasta 
## Log:
## [1] "Instance created on Mon Apr 28 19:49:12 2014"
## [2] "Read identification peptide data [32308,66]" 
## [ 33 lines ]
## [36] "Read identification fragment data [6276]"
## [37] "Read quantitation fragment data [21516]"
```


### Run Cross Matching

```s
## set mz tolerance (to consider two peaks as identical) to 25 ppm
setCrossMatchingPpmTolerance(s, 25)

crossMatching(s, verbose=FALSE)
```


### Plot Cross Matching Results


```s
set.seed(1) # only for demonstration
crossMatchingSummaryMatrix <- plotCrossMatchingSummary(s)
```
![cxsummary1](https://cloud.githubusercontent.com/assets/1828443/2822043/1fcf3fb4-cf0e-11e3-82d0-89181db39e7f.png)


```s
set.seed(1) # only for demonstration
plotCrossMatchingSummary(s, matchColumn="spectrum.identXfragments.quant")
```
![cxsummary2](https://cloud.githubusercontent.com/assets/1828443/2822045/252374c6-cf0e-11e3-982e-6116e043f99d.png)


```s
set.seed(1) # only for demonstration
plotCrossMatchingSummary(s, matchColumn="fragments.identXfragments.quant")
```
![cxsummary3](https://cloud.githubusercontent.com/assets/1828443/2822049/2b938f12-cf0e-11e3-84ef-ffebd8193929.png)


```s
kable(crossMatchingSummaryMatrix, row.names=FALSE)
```

|  ncommon|    tp|    fp|    tn|    fn|  accuracy|  precision|  recall|     fdr|      f1|
|--------:|-----:|-----:|-----:|-----:|---------:|----------:|-------:|-------:|-------:|
|        0|  1087|  1087|     0|     0|    0.5000|     0.5000|  1.0000|  0.5000|  0.6667|
|        1|  1056|   504|   583|    31|    0.7539|     0.6769|  0.9715|  0.3231|  0.7979|
|        2|   907|   244|   843|   180|    0.8050|     0.7880|  0.8344|  0.2120|  0.8105|
|        3|   706|   153|   934|   381|    0.7544|     0.8219|  0.6495|  0.1781|  0.7256|
|        4|   559|   101|   986|   528|    0.7107|     0.8470|  0.5143|  0.1530|  0.6400|
|        5|   448|    78|  1009|   639|    0.6702|     0.8517|  0.4121|  0.1483|  0.5555|
|        6|   351|    62|  1025|   736|    0.6329|     0.8499|  0.3229|  0.1501|  0.4680|
|        7|   288|    54|  1033|   799|    0.6076|     0.8421|  0.2649|  0.1579|  0.4031|
|        8|   235|    46|  1041|   852|    0.5869|     0.8363|  0.2162|  0.1637|  0.3436|
|        9|   186|    37|  1050|   901|    0.5685|     0.8341|  0.1711|  0.1659|  0.2840|
|       10|   157|    34|  1053|   930|    0.5566|     0.8220|  0.1444|  0.1780|  0.2457|
|       11|   128|    33|  1054|   959|    0.5437|     0.7950|  0.1178|  0.2050|  0.2051|
|       12|   104|    26|  1061|   983|    0.5359|     0.8000|  0.0957|  0.2000|  0.1709|
|       13|    85|    18|  1069|  1002|    0.5308|     0.8252|  0.0782|  0.1748|  0.1429|
|       14|    73|    15|  1072|  1014|    0.5267|     0.8295|  0.0672|  0.1705|  0.1243|
|       15|    57|    14|  1073|  1030|    0.5198|     0.8028|  0.0524|  0.1972|  0.0984|
|       16|    50|    13|  1074|  1037|    0.5170|     0.7937|  0.0460|  0.2063|  0.0870|
|       17|    34|    11|  1076|  1053|    0.5106|     0.7556|  0.0313|  0.2444|  0.0601|
|       18|    28|    11|  1076|  1059|    0.5078|     0.7179|  0.0258|  0.2821|  0.0497|
|       19|    24|    10|  1077|  1063|    0.5064|     0.7059|  0.0221|  0.2941|  0.0428|
|       20|    17|     9|  1078|  1070|    0.5037|     0.6538|  0.0156|  0.3462|  0.0305|
|       21|    14|     7|  1080|  1073|    0.5032|     0.6667|  0.0129|  0.3333|  0.0253|
|       22|    12|     7|  1080|  1075|    0.5023|     0.6316|  0.0110|  0.3684|  0.0217|
|       23|     7|     5|  1082|  1080|    0.5009|     0.5833|  0.0064|  0.4167|  0.0127|
|       24|     6|     4|  1083|  1081|    0.5009|     0.6000|  0.0055|  0.4000|  0.0109|
|       25|     4|     4|  1083|  1083|    0.5000|     0.5000|  0.0037|  0.5000|  0.0073|
|       26|     4|     4|  1083|  1083|    0.5000|     0.5000|  0.0037|  0.5000|  0.0073|
|       27|     2|     4|  1083|  1085|    0.4991|     0.3333|  0.0018|  0.6667|  0.0037|
|       28|     2|     2|  1085|  1085|    0.5000|     0.5000|  0.0018|  0.5000|  0.0037|
|       29|     1|     2|  1085|  1086|    0.4995|     0.3333|  0.0009|  0.6667|  0.0018|
|       30|     1|     1|  1086|  1086|    0.5000|     0.5000|  0.0009|  0.5000|  0.0018|
|       31|     1|     1|  1086|  1086|    0.5000|     0.5000|  0.0009|  0.5000|  0.0018|
|       32|     1|     0|  1087|  1086|    0.5005|     1.0000|  0.0009|  0.0000|  0.0018|
|       33|     1|     0|  1087|  1086|    0.5005|     1.0000|  0.0009|  0.0000|  0.0018|
|       34|     1|     0|  1087|  1086|    0.5005|     1.0000|  0.0009|  0.0000|  0.0018|
|       35|     1|     0|  1087|  1086|    0.5005|     1.0000|  0.0009|  0.0000|  0.0018|
|       36|     1|     0|  1087|  1086|    0.5005|     1.0000|  0.0009|  0.0000|  0.0018|


### Show Details Of Specific Data Points
find the `precursor.leID.ident` of the two false matches with more than 25
common peaks

```s
cx <- s$CrossMatching
precursor.leID.ident <- cx$precursor.leID.ident[
 grepl("false", cx$matchType) & cx$fragments.identXfragments.quant > 25]

plotCrossMatching(s, key=precursor.leID.ident, column="precursor.leID.ident",
                  verbose=FALSE)
```

![cxdetails1](https://cloud.githubusercontent.com/assets/1828443/2821713/9b91c694-cf09-11e3-9ad1-14e2374b6461.png)
![cxdetails2](https://cloud.githubusercontent.com/assets/1828443/2821714/9b93fb12-cf09-11e3-9b33-91969959b46b.png)
![cxdetails3](https://cloud.githubusercontent.com/assets/1828443/2821715/9b94c5ba-cf09-11e3-9c40-d6d9fd6ded92.png)
![cxdetails4](https://cloud.githubusercontent.com/assets/1828443/2821716/9b965380-cf09-11e3-9502-bebad4affdc2.png)
![cxdetails5](https://cloud.githubusercontent.com/assets/1828443/2821717/9b96e9da-cf09-11e3-9af0-4d1dfd865478.png)
![cxdetails6](https://cloud.githubusercontent.com/assets/1828443/2821718/9b98fc0c-cf09-11e3-94c9-a676928f6191.png)
![cxdetails7](https://cloud.githubusercontent.com/assets/1828443/2821719/9ba1a49c-cf09-11e3-9c84-ebffae89db5b.png)
![cxdetails8](https://cloud.githubusercontent.com/assets/1828443/2821720/9ba40278-cf09-11e3-9d6f-4bd2d52dd1a6.png)


```s
options(digits=10)
kable(cx[cx$precursor.leID.ident %in% precursor.leID.ident,
      c("protein.Entry", "peptide.seq", "precursor.mhp", "precursor.retT",
        "precursor.leID.ident", "matched.quant.spectrumIDs",
        "fragments.identXfragments.quant")])
```

|id    |protein.Entry  |peptide.seq      |  precursor.mhp|  precursor.retT|  precursor.leID.ident|  matched.quant.spectrumIDs|  fragments.identXfragments.quant|
|:-----|:--------------|:----------------|--------------:|---------------:|---------------------:|--------------------------:|--------------------------------:|
|5236  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      43715|                                1|
|5237  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      43956|                                4|
|5238  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      44152|                               27|
|5239  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      44169|                                0|
|5240  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      44460|                                2|
|5241  |ENO2_YEAST     |AVDDFLLSLDGTANK  |      1578.8067|        136.4560|                 49728|                      44769|                                0|
|5290  |ENO1_YEAST     |AVDDFLISLDGTANK  |      1578.8019|        140.2788|                 51851|                      46046|                                1|
|5291  |ENO1_YEAST     |AVDDFLISLDGTANK  |      1578.8019|        140.2788|                 51851|                      46048|                               27|


```s
matched.quant.spectrumIDs <-
  cx$matched.quant.spectrumIDs[cx$precursor.leID.ident %in% precursor.leID.ident]
pep3d <- s$QuantPep3DData
```


```s
kable(pep3d[pep3d$spectrumID %in% matched.quant.spectrumIDs,
      c("spectrumID", "mwHPlus", "ion_rt")])
```

|id      |  spectrumID|    mwHPlus|    ion_rt|
|:-------|-----------:|----------:|---------:|
|145696  |       43715|  1578.8116|  135.4174|
|146638  |       43956|  1578.8084|  135.8209|
|147387  |       44152|  1578.8048|  136.1956|
|147445  |       44169|  1578.8057|  136.2264|
|148522  |       44460|  1578.8041|  136.7750|
|149729  |       44769|  1578.8022|  137.3635|
|154464  |       46046|  1578.8059|  140.0355|
|154477  |       46048|  1578.8026|  140.0411|



```s
par(cex=5, mar=rep(0, 4))
plotFeatures(s, what="some", xlim=c(135, 137.7), ylim=c(1578.77, 1578.86))
```
![cxdetails31](https://cloud.githubusercontent.com/assets/1828443/2822060/524f6dd8-cf0e-11e3-9ad7-c42f8e35625b.png)


```s
plotFeatures(s, what="some", xlim=c(138.9, 141), ylim=c(1578.77, 1578.84))
```
![cxdetails32](https://cloud.githubusercontent.com/assets/1828443/2822063/56318d50-cf0e-11e3-8486-39d9c9f2adac.png)



Compare `"spectrum.identXfragments.quant` vs `"fragments.identXfragments.quant"`
and `"spectrum.quantXfragments.ident"` vs `"fragments.identXfragments.quant"`.

```s
plot(cx$fragments.identXfragments.quant, cx$spectrum.identXfragments.quant, col="#00000040", pch=19)
```

![cmpmatchcol1](https://cloud.githubusercontent.com/assets/1828443/2821729/b2615cfe-cf09-11e3-91b6-b8c97e5cf670.png)


```s
plot(cx$fragments.identXfragments.quant, cx$spectrum.quantXfragments.ident, col="#00000040", pch=19)
```

![cmpmatchcol2](https://cloud.githubusercontent.com/assets/1828443/2821732/b863cf42-cf09-11e3-95b9-bcdad8b6882b.png)


### Filtering Using The Cross Matching Results
`performance` before filtering

```s
performance(s)
```

```
## (S) Synapter: 5184 EMRTs uniquely matched.
## (I) Ident: 6388 peptides.
## (Q) Quant: 5910 peptides.
## Enrichment (S/Q): -12.28%
## Overlap:
##    Q    S   QS 
## 1872 1145 4038
```

cross match filtering

```s
setCrossMatchingMinimalNumberOfCommonPeaks(s, 3)
filterMatchedEMRTsByCommonPeaks(s)
```

`performance` after filtering

```s
performance(s)
```

```
## (S) Synapter: 5485 EMRTs uniquely matched.
## (I) Ident: 6388 peptides.
## (Q) Quant: 5910 peptides.
## Enrichment (S/Q): -7.19%
## Overlap:
##    Q    S   QS 
## 1581 1155 4329
```