Warping: Warping of the spectra
In yclement/PepsNMR: Pre-process 1H-NMR FID signals

Description Usage Arguments Details Value Author(s) References Examples

Warps the frequency x-axis to minimize the pairwise distance between a sample spectrum and a reference spectrum.

Warping(Spectrum_data, normalization.type = c("median","mean",
        "firstquartile","peak","none"), fromto.normW = c(3.05, 4.05), 
        reference.choice = c("fixed", "before", 
        "after", "manual"), reference = 1, optim.crit = c("RMS", "WCC"), 
        ptw.wp = FALSE, K = 3, L = 40, lambda.smooth = 0, deg = 3, 
        lambda.bspline = 0.01, kappa = 0.0001, max_it_Bspline = 10, 
        returnReference = FALSE, returnWarpFunc = FALSE, verbose = FALSE)

`Spectrum_data`	Matrix containing the spectra in ppm, one row per spectrum.
`normalization.type`	Type of normalization applied to the spectra prior to warping. See `Normalization` for details about the different types. `none` means that no normalization is applied. It is advised to use `median` instead of the default `mean` normalization.
`fromto.normW`	Used by `Normalization` when `normalization.type` is `peak`.
`reference.choice`	Specifies how the reference will be chosen: `"fixed"` The reference is specified by the rowname given in `reference`. `"before"` The reference is taken as the spectrum with the minimum sum of square difference with the other spectra. `"after"` Each spectrum is taken as the reference and the sum of square difference with the other spectra is calculated after the warping. See details below. `"manual"` The reference spectrum is specified in the `reference` argument.
`reference`	The row number or name of the reference spectrum when `reference.choice` is `"fixed"` or a numeric vector with the reference spectrum when `reference.choice` is `"manual"`.
`optim.crit`	If `ptw.wp` is set to `TRUE`, `WCC` can also be considered as a criterion for optimization, see `ptw::ptw` for details.
`ptw.wp`	If set to `TRUE`, it applies the Parametric Time Warping with the `ptw::ptw` function to the data. In this case, the warping does not use B-splines and the arguments `L`, `deg`, `lambda.bspline`, `kappa` and `max_it_Bspline` are ignored.
`K`	It is the degree of the polynomial used for the warping (see details).
`L`	This is the number of B-splines that are used for the warping. It should be either 0 or greater than `deg`.
`lambda.smooth`	Nonnegative coefficient for the smoothing `lambda.smooth = 0` means no smoothing. See `ptw::difsm` for more details.
`deg`	Degree of the B-splines.
`lambda.bspline`	Nonnegative second-order smoothness penalty coefficient for the B-splines warping. See the reference for more details.
`kappa`	Nonnegative ridge (zero-order) penalty coefficient for the B-splines warping. See the reference for more details.
`max_it_Bspline`	Maximum number of iterations for the B-splines warping.
`returnReference`	If `TRUE`, will return the name of the reference spectrum.
`returnWarpFunc`	If `TRUE`, will return the warping functions.
`verbose`	If `"TRUE"`, will print processing information.

When reference.choice is "after", the reference with the minimum sum is taken as the reference and the warped spectra according to this reference (that have already been calculated at this stage) are returned. This is n times slower than the 2 others where n is the number of spectra.

Principle:

We try to find a warping function between a reference spectrum and a sample. This function is a sum of polynomial of degree K and L B-splines of degree deg. The unknowns are the polynomial and B-splines coefficients.

No warping is equivalent to warping with a, the polynomial identity and all the coefficients of the B-splines with value 0. See the reference for details.

First, the polynomial is estimated on the reference and the sample both smoothed with parameter lambda.smooth. The B-splines are estimated on the non-smoothed reference and sample using the polynomial just found.

The higher lambda.bspline and kappa are, the less flexible the warping function will be.

If returnReference = TRUE, the function will return the name of the reference spectrum and if returnWarpingfunc = TRUE, it will also return the warping functions.

`Spectrum_data`	The warped spectra.
`Reference`	The name of the reference spectrum.
`Warpingfunc`	The warping functions.

Benoît Legat, Manon Martin & Paul H. C. Eilers

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).

require(PepsNMRData)
Warp.spec <- Warping(Data_HS_sp$Spectrum_data_HS_8, reference.choice="fixed", 
                             reference = row.names(Data_HS_sp$Spectrum_data_HS_8)[1],
                             returnReference = FALSE)
#or
Warp.res <- Warping(Data_HS_sp$Spectrum_data_HS_8, reference.choice="fixed", 
                             reference = row.names(Data_HS_sp$Spectrum_data_HS_8)[1],
                             returnReference = TRUE)
Warp.spec <- Warp.res[["Spectrum_data"]]
Warp.res[["Reference"]]