InternalReferencing: Chemical shift referencing.
In yclement/PepsNMR: Pre-process 1H-NMR FID signals

Description Usage Arguments Details Value Author(s) References Examples

Chemical shifts are referenced against a Reference Compound (RC, e.g. TMSP).

InternalReferencing(Spectrum_data, Fid_info, method = c("max", 
               "thres"), range = c("nearvalue", "all", "window"), 
               ppm.value = 0, direction = "left", 
               shiftHandling = c("zerofilling",  "cut", "NAfilling", 
               "circular"), c = 2, pc = 0.02, fromto.RC = NULL, 
               ppm.ir = TRUE, rowindex_graph = NULL, verbose = FALSE)

`Spectrum_data`	Matrix containing the spectra in ppm, one row per spectrum.
`Fid_info`	Matrix containing the information for each spectrum, one row per spectrum, as returned by `ReadFids`.
`method`	Method used to find the RC peak in the spectra, See the details section.
`range`	How the search zone is defined. Either accross the whole ppm axis (`"all"`), near the 0 ppm location (`nearvalue`) with parameter `pc`, or in a manually specified area of the ppm axis (`"window"`) with the non-null parameter `fromto.RC`.
`ppm.value`	By default, the ppm value of the reference compound is set to 0, but any arbitrary value in the ppm interval of spectra can be used instead.
`direction`	If `method = "thres"`, the direction towards which to search for the RC peak.
`shiftHandling`	See the details section.
`c`	If `method = "thres"`, parameter used to fix the threshold for the RC peak.
`pc`	If `range = "nearvalue"`, percentage of the ppm axis around the `ppm.value` ppm value to look for the RC peak (e.g. for `pc = 0.02`, intensities whose index values are 0.01% below and above 0 ppm are investiguated).
`fromto.RC`	If `range = "window"`, a list containing numerical vectors indicating the extremities of the intervals within which to search for the RC peak. These extremities are either frequencies in ppm (decreasing values) OR in column indices (increasing values) depending on the `ppm.ir` value (e.g. `fromto.RC = list(c(0,10000))` if `ppm.ir == FALSE` or `fromto.RC = list(c(1,-1))` if `ppm.ir == TRUE`).
`ppm.ir`	If `TRUE`, the values in `fromto.RC` represent frequencies in ppm (column names of spectra), if `FALSE` these values are column indices.
`rowindex_graph`	If not `NULL`, a numeric vector with the row numbers of spectra that need to be plotted for inspection.
`verbose`	If`"TRUE"`, will print processing information.

Once the search zone is defined with range, the RC is found depending on the method. If method = "thres", RC is the first peak in the spectrum higher than a predefined threshold which is computed as: c*(cumulated_mean/cumulated_sd). If method = "max", the maximum intensity in the search zone is defined as the RC.

Since the spectra can be shifted differently, we need to handle misalignment of the left and right of the spectrum.

This can be illustrated here:

| : TMSP peak

before
 1  2  3  |  5  6  7  8  9
 1  2  3  4  5  |  7  8  9
 1  2  3  4  |  6  7  8  9

shifted
-5 -4 -3 -2 -1  0  1  2  3  4  5 : ppm scale
       1  2  3  |  5  6  7  8  9
 1  2  3  4  5  |  7  8  9
    1  2  3  4  |  6  7  8  9

The different shift handlings (shiftHandling) are the following:

NAfilling

The extremities at which a spectrum is not defined are replaced by NA. It is detected by WindowSelection which produces a warning if there are NAs in the selected window.

-5 -4 -3 -2 -1  0  1  2  3  4  5  ppm scale
NA NA  1  2  3  |  5  6  7  8  9
 1  2  3  4  5  |  7  8  9 NA NA
NA  1  2  3  4  |  6  7  8  9 NA

zerofilling

The extremities at which a spectrum is not defined are replaced by 0. It makes sense since in practice the spectrum is close to zero at the extremities.

-5 -4 -3 -2 -1  0  1  2  3  4  5  ppm scale
 0  0  1  2  3  |  5  6  7  8  9
 1  2  3  4  5  |  7  8  9  0  0
 0  1  2  3  4  |  6  7  8  9  0

circular

The spectra are shifted circularly which means that the end of a spectrum is reproduced at the beginning. It makes sense since the spectrum is periodic since it is the result of FFT.

-5 -4 -3 -2 -1  0  1  2  3        ppm scale
 8  9  1  2  3  |  5  6  7
 1  2  3  4  5  |  7  8  9
 9  1  2  3  4  |  6  7  8

cut

The ppm values for which some spectra are not defined are removed.

      -3 -2 -1  0  1  2  3        ppm scale
       1  2  3  |  5  6  7
       3  4  5  |  7  8  9
       2  3  4  |  6  7  8

The difference between these shift handlings should not be critical in practice since the extremities of the spectra are not used most of the time and are removed in WindowSelection.

if rowindex_graph is NULL:

Spectrum_data

The matrix of the spectral value in the ppm scale.

if rowindex_graph is not NULL:

`Spectrum_data`	The matrix of the spectral value in the ppm scale.
`plots`	The spectra that need to be plotted for inspection.

Benoît Legat & Manon Martin

Martin, M., Legat, B., Leenders, J., Vanwinsberghe, J., Rousseau, R., Boulanger, B., & Govaerts, B. (2018). PepsNMR for 1H NMR metabolomic data pre-processing. Analytica chimica acta, 1019, 1-13.

Rousseau, R. (2011). Statistical contribution to the analysis of metabonomics data in 1H NMR spectroscopy (Doctoral dissertation, PhD thesis. Institut de statistique, biostatistique et sciences actuarielles, Université catholique de Louvain, Belgium).

1
2
3

require(PepsNMRData)
PpmConv.spec <- InternalReferencing(Data_HS_sp$Spectrum_data_HS_5, 
                             FidInfo_HS, shiftHandling = "zerofilling")