# ml-peak-shape-generator [![NPM version][npm-image]][npm-url] [![build status][ci-image]][ci-url] [![Test coverage][codecov-image]][codecov-url] [![npm download][download-image]][download-url] Generate various peak shapes. The current supported kinds of shapes: | Name | `kind` | Equation | | --------------------------- | ----------------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Gaussian | `gaussian` | $y\cdot exp\left[-\frac{1}{2}\frac{\delta}{\sigma^2}\right]$ | | Lorentzian | `lorentzian` | $y\cdot\frac{\omega^2}{4\delta + \omega^2}$ | | Lorentzian Dispersive | `lorentzianDispersive` | $y\cdot\frac{2\omega\delta}{4\delta^2 + \omega^2}$ | | Generalized Lorentzian | `generalizedLorentzian` | $y\cdot\left[(1-\gamma)\cdot\frac{1}{1+u} + \gamma\cdot\frac{1+\frac{u}{2}}{1+u+u^2}\right]$ | | Pseudo Voigt | `pseudoVoigt` | $y \cdot\left[mu\cdot exp\left[-\frac{1}{2}\frac{\delta}{\sigma^2}\right] + \left(1 - mu\right)\cdot\frac{\omega^2}{4\delta + \omega^2}\right]$ | | Pseudo Voigt (TCH) | `pseudoVoigtTCH` | The pseudo Voigt above, with independent gaussian and lorentzian widths `fwhmG` and `fwhmL`. The effective `fwhm` and `mu` are derived from them through the Thompson–Cox–Hastings approximation. | | Split Gaussian (asymmetric) | `splitGaussian` | Two gaussian halves sharing the apex: the lower-x half (`t ≤ x`) uses `fwhmLow`, the higher-x half (`t > x`) uses `fwhmHigh`. | The only 2D shape is `gaussian`, whose widths are set per axis. where | $\delta = \left(t - x\right)^2$ | $\sigma = \frac{FWHM}{2\sqrt{2 \cdot ln(2)}}$ | $\omega = FWHM$ | $u = \left(\frac{2\delta}{\omega}\right)^2$ | |---------------------: | :---------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------- | ## Installation `$ npm i ml-peak-shape-generator` This package allows to calculate various shapes. By default they will have a height of 1. ![demo.png](demo.png) You see the resulting functions using this [playground](https://codesandbox.io/s/lorentzian-u1upg0?file=/Example.tsx) ## Usage ```js import { getGaussianData, getLorentzianData, getPseudoVoigtData, } from 'ml-peak-shape-generator'; // It's possible to specify the windows size with factor option let data = getGaussianData({ sd: 500 }, { factor: 3.5 }); // or fix the number of points as Full Width at Half Maximum let data = getGaussianData({ fwhm: 500 }, { factor: 3.5 }); // It's possible to specify the windows size with factor option let data = getLorentzianData({ fwhm: 500 }, { factor: 5 }); // It's possible to specify the windows size with factor option let data = getPseudoVoigtData({ fwhm: 500 }, { factor: 5 }); ``` It is also possible to take an instance of each kind of shape: ```js import { Gaussian, gaussianFct, Gaussian2D } from 'ml-peak-shape-generator'; const gaussianShape = new Gaussian({ fwhm: 500 }); // It is possible to set a new value for fwhm gaussianShape.fwhm = 300; // By default the height value ensure a volume equal 1. const symmetric2DShape = new Gaussian2D({ fwhm: 500 }); // It is possible to set values for sd, fwhm and factor for each axes. const gaussian2DShape = new Gaussian2D({ fwhm: { x: 300, y: 500 } }); // It is possible to set new value for fwhm by: gaussian2DShape.fwhm = { x: 300, y: 500 }; // or set the same value for both axes. gaussian2DShape.fwhm = 400; // An instance of any shape has the same methods accessible for each // shape e.g. fct or getData, but these use the internal parameters. e.g: gaussianShape.fct(5); gaussianFct(5, 500); // getData gaussianShape.getData({ factor: 3.5 }); ``` ```js import { getShape1D, getShape2D } from 'ml-peak-shape-generator'; // If you want to dynamically select a shape you can use `getShape1D` / // `getShape2D`. They return an instance of the required kind of shape. const lorentzian = getShape1D({ kind: 'lorentzian', fwhm: 500 }); const gaussian2D = getShape2D({ kind: 'gaussian', sd: 500 }); ``` ## Descriptors, instances and serialization A shape exists in two forms: a **descriptor** — a plain object such as `{ kind: 'gaussian', fwhm: 500 }` — and an **instance**, the class that computes the curve. `getShape1D` / `getShape2D` turn a descriptor into an instance. An instance carries its own `kind` and serializes back to a descriptor, so a shape survives a trip through JSON: ```js import { getShape1D } from 'ml-peak-shape-generator'; const shape = getShape1D({ kind: 'pseudoVoigt', fwhm: 500, mu: 0.3 }); shape.kind; // 'pseudoVoigt' JSON.stringify(shape); // '{"kind":"pseudoVoigt","fwhm":500,"mu":0.3}' const restored = getShape1D(JSON.parse(JSON.stringify(shape))); restored.fct(5) === shape.fct(5); // true ``` `toJSON` emits the parameters the shape is defined by — those `getParameters()` reports — so a round trip preserves both the curve and its analytical derivatives. A `splitGaussian` therefore emits `fwhmLow` and `fwhmHigh` rather than its mean `fwhm`, and a `pseudoVoigtTCH` emits its component widths `fwhmG` and `fwhmL`. Options that are alternative ways to express a width, such as `sd`, are resolved first and emitted as the resulting `fwhm`. Because an instance is itself a valid descriptor, handing one back to the factory copies it: ```js const copy = getShape1D(shape); // a new instance with the same parameters ``` The `kind` strings are exported as types: ```ts import type { Shape1DKind, Shape2DKind } from 'ml-peak-shape-generator'; // Shape1DKind: 'gaussian' | 'lorentzian' | 'lorentzianDispersive' | // 'pseudoVoigt' | 'pseudoVoigtTCH' | 'generalizedLorentzian' | // 'splitGaussian' // Shape2DKind: 'gaussian' ``` It is also possible to get a function that allows to calculate y for any x ```js import { gaussianFct } from 'ml-peak-shape-generator'; const func = gaussianFct(x - mean, fwhm); ``` ## [API Documentation](https://mljs.github.io/peak-shape-generator/) ## License [MIT](./LICENSE) [npm-image]: https://img.shields.io/npm/v/ml-peak-shape-generator.svg [npm-url]: https://www.npmjs.com/package/ml-peak-shape-generator [ci-image]: https://github.com/mljs/peak-shape-generator/workflows/Node.js%20CI/badge.svg?branch=main [ci-url]: https://github.com/mljs/peak-shape-generator/actions?query=workflow%3A%22Node.js+CI%22 [codecov-image]: https://img.shields.io/codecov/c/github/mljs/peak-shape-generator.svg [codecov-url]: https://codecov.io/gh/mljs/peak-shape-generator [download-image]: https://img.shields.io/npm/dm/ml-peak-shape-generator.svg [download-url]: https://www.npmjs.com/package/ml-peak-shape-generator