feat!: major refactoring

The commit refactor the project and add many breaking changes. Please check the README.md for more information.

`const peakList = gsd({x:[] ,y:[]}, options` now returns an array of `GSDPeak` that have the following properties:

- x: position of the peak on the x axis
- y: the height of the peak
- width: width at the level of the inflection points
- index: index in the 'x' and 'y' array of the peak
- ddY: second derivative value at the level of the peak. Allows to identify 'large' (soft) peaks
- inflectionPoints: an object with the position of the inflection points
  - from: { x, index }
  - to: { x, index }

`const peaks = optimizePeaks({x:[] ,y:[]}, peakList, options)` return `GSDPeakOptimized` that contains 5 properties
 - x: number;
 - y: number;
 - width: number;
 - fwhm: number;
 - shape: Shape1D;

Author: lpatiny

README.md

@@ -1,28 +1,39 @@
-# global-spectral-deconvolution
+# global-spectral-deconvolution and peak optimizer
 
 [![NPM version][npm-image]][npm-url]
 [![build status][ci-image]][ci-url]
 [![Test coverage][codecov-image]][codecov-url]
 [![npm download][download-image]][download-url]
 
-Global Spectra Deconvolution + Peak optimizer
+## Global Spectra Deconvolution
 
-`gsd`is using an algorithm that is searching for inflection points to determine the position of peaks and the width of the peaks are between the 2 inflection points. The result of GSD yield to an array of object containing {x, y fwhm and width}. However this width is based on the inflection point and may be different from the 'fwhm' (Full Width Half Maximum).
+`gsd`is using an algorithm that is searching for inflection points to determine the position and width of peaks. The width is defined as the distance between the 2 inflection points. Depending the shape of the peak this width may differ from 'fwhm' (Full Width Half Maximum).
 
-The second algorithm (`optimizePeaks`) will optimize the width and FWHM to match the original peak.
+Preprocessing of the data involves the following parameters
 
-## [API documentation](http://mljs.github.io/global-spectral-deconvolution/)
+- `maxCriteria`: search either for maxima or minima. We will invert the data and the results if searching for a minima
+- `sgOptions`: Savitzky-Golay filter that is used to smooth the data for the calculation of the derivatives
+- `smoothY`: If this value is true the SG filter is not only applied during the calculation of the derivatives but also on the original data
+
+### gsd({x:[], y:[]}, options)
+
+The result of GSD is an array of GSDPeak:
+
+- x: position of the peak on the x axis
+- y: the height of the peak
+- width: width at the level of the inflection points
+- index: index in the 'x' and 'y' array of the peak
+- ddY: second derivative value at the level of the peak. Allows to identify 'large' peaks
+- inflectionPoints: an object with the position of the inflection points
+  - from: { x, index }
+  - to: { x, index }
 
 ## Parameters
 
 #### minMaxRatio=0.00025 (0-1)
 
 Threshold to determine if a given peak should be considered as a noise, bases on its relative height compared to the highest peak.
 
-#### noiseLevel=0 (-inf, inf)
-
-Noise threshold in spectrum units
-
 #### maxCriteria=true [true||false]
 
 Peaks are local maximum(true) or minimum(false)
@@ -39,53 +50,66 @@ Use a quadratic optimizations with the peak and its 3 closest neighbors to deter
 
 Savitzky-Golay parameters. windowSize should be odd; polynomial is the degree of the polynomial to use in the approximations. It should be bigger than 2.
 
-#### heightFactor=0
-
-Factor to multiply the calculated height (usually 2).
-
-#### derivativeThreshold=0
-
-Filters based on the amplitude of the first derivative
-
 ## Post methods
 
 ### GSD.broadenPeaks(peakList, {factor=2, overlap=false})
 
 We enlarge the peaks and add the properties from and to.
 By default we enlarge of a factor 2 and we don't allow overlap.
 
-### GSD.joinBroadPeaks
-
-#### broadRatio=0.00 (0-1)
-
-If `broadRatio` is higher than 0, then all the peaks which second derivative smaller than `broadRatio * maxAbsSecondDerivative` will be marked with the soft mask equal to true.
+### GSD.optimizePeaks(data, peakList, options)
 
-### GSD.optimizePeaks
+Optimize the position (x), max intensity (y), full width at half maximum (fwhm) and the ratio of gaussian contribution (mu) if it's required. It currently supports three kind of shapes: gaussian, lorentzian and pseudovoigt
 
 ## Example
 
 ```js
 import { IsotopicDistribution } from 'mf-global';
-import { gsd, optimizePeaks } from '../src';
+import { gsd, optimizePeaks } from 'ml-gad';
 
 // generate a sample spectrum of the form {x:[], y:[]}
 const data = new IsotopicDistribution('C').getGaussian();
 
 let peaks = gsd(data, {
-  noiseLevel: 0,
   minMaxRatio: 0.00025, // Threshold to determine if a given peak should be considered as a noise
-  realTopDetection: true,
-  maxCriteria: true, // inverted:false
-  smoothY: false,
-  sgOptions: { windowSize: 7, polynomial: 3 },
+  realTopDetection: true, // Correction of the x and y coordinates using a quadratic optimizations
+  maxCriteria: true, // Are we looking for maxima or minima
+  smoothY: false, // should we smooth the spectra and return smoothed peaks ? Default false.
+  sgOptions: { windowSize: 7, polynomial: 3 }, // Savitzky-Golay smoothing parameters for first and second derivative calculation
 });
-console.log(peaks); // array of peaks {x, y, width, fwhw}, width = distance between inflection points
-// GSD
+console.log(peaks);
+/*
+  array of peaks containing {x, y, width, ddY, inflectionPoints}
+  - width = distance between inflection points
+  - ddY = second derivative on the top of the peak
+ */
 
 let optimized = optimizePeaks(data, peaks);
-console.log(optimized); // array of peaks {x, y, width, fwhm}.
+console.log(optimized);
+/*
+[
+  {
+    x: 11.99999999960885,
+    y: 0.9892695646808637,
+    shape: { kind: 'gaussian' },
+    fwhm: 0.010000209455943584,
+    width: 0.008493395898379276
+  },
+  {
+    x: 13.003354834590702,
+    y: 0.010699637653261198,
+    shape: { kind: 'gaussian' },
+    fwhm: 0.010000226962299321,
+    width: 0.008493410766908847
+  }
+]
+*/
 ```
 
+i
+
+## [API documentation](http://mljs.github.io/global-spectral-deconvolution/)
+
 ## License
 
 [MIT](./LICENSE)

examples/mf.ts

@@ -8,7 +8,6 @@ import { gsd, optimizePeaks } from '../src';
 const data = new IsotopicDistribution('C').getGaussian();
 
 let peaks = gsd(data, {
-  noiseLevel: 0,
   minMaxRatio: 0.00025, // Threshold to determine if a given peak should be considered as a noise
   realTopDetection: true,
   maxCriteria: true, // inverted:false

package.json

@@ -23,7 +23,7 @@
     "prepack": "npm run tsc",
     "prettier": "prettier --check src",
     "prettier-write": "prettier --write src",
-    "test": "npm run test-only && npm run eslint && npm run check-types",
+    "test": "npm run test-only && npm run eslint && npm run prettier && npm run check-types",
     "test-only": "jest --coverage",
     "tsc": "npm run clean && npm run tsc-cjs && npm run tsc-esm",
     "tsc-cjs": "tsc --project tsconfig.cjs.json",
@@ -58,30 +58,30 @@
     "trailingComma": "all"
   },
   "devDependencies": {
-    "@types/jest": "^27.0.3",
+    "@types/jest": "^27.4.0",
     "chemcalc": "^3.4.1",
     "cheminfo-build": "^1.1.11",
-    "eslint": "^8.4.1",
-    "eslint-config-cheminfo-typescript": "^10.2.4",
-    "eslint-plugin-jest": "^25.3.0",
+    "eslint": "^8.9.0",
+    "eslint-config-cheminfo-typescript": "^10.3.0",
+    "eslint-plugin-jest": "^26.1.0",
     "esm": "^3.2.25",
-    "jest": "^27.4.5",
+    "jest": "^27.5.1",
     "jest-matcher-deep-close-to": "^3.0.2",
-    "mf-global": "^1.4.7",
+    "mf-global": "^1.4.20",
     "ml-stat": "^1.3.3",
     "nodemon": "^2.0.15",
     "prettier": "^2.5.1",
     "rimraf": "^3.0.2",
-    "spectrum-generator": "^6.0.2",
-    "ts-jest": "^27.1.1",
-    "typescript": "^4.5.4",
-    "xy-parser": "^4.0.0"
+    "spectrum-generator": "^6.0.4",
+    "ts-jest": "^27.1.3",
+    "typescript": "^4.5.5",
+    "xy-parser": "^4.0.1"
   },
   "dependencies": {
-    "cheminfo-types": "^0.9.1",
-    "ml-peak-shape-generator": "^4.0.1",
-    "ml-savitzky-golay-generalized": "2.0.3",
-    "ml-spectra-fitting": "^3.0.3",
-    "ml-spectra-processing": "^8.0.3"
+    "cheminfo-types": "^0.10.1",
+    "ml-peak-shape-generator": "^4.0.3",
+    "ml-savitzky-golay-generalized": "4.0.0",
+    "ml-spectra-fitting": "^3.0.4",
+    "ml-spectra-processing": "^10.0.0"
   }
 }

src/GSDBroadenPeak.ts

@@ -0,0 +1,8 @@
+export interface GSDBroadenPeak {
+  x: number;
+  y: number;
+  width: number;
+  index: number;
+  from: { x: number };
+  to: { x: number };
+}

src/GSDPeak.ts

@@ -0,0 +1,21 @@
+export interface GSDPeak {
+  x: number;
+  y: number;
+  /**
+   * Width at the level of the inflection points
+   */
+  width: number;
+  /**
+   * index in the 'x' and 'y' array of the peak
+   */
+  index: number;
+  /**
+   * second derivative at the level of the peak
+   * This allows to determine if a peak is soft or not
+   */
+  ddY: number;
+  inflectionPoints: {
+    from: { x: number; index: number };
+    to: { x: number; index: number };
+  };
+}

src/GSDPeakOptimized.ts

@@ -0,0 +1,9 @@
+import { Shape1D } from 'ml-peak-shape-generator';
+
+export interface GSDPeakOptimized {
+  x: number;
+  y: number;
+  width: number;
+  fwhm: number;
+  shape: Shape1D;
+}