ml-peak-shape-generator

Generate various peak shapes.

The current supported kinds of shapes:

| Name | kind | Equation | | --------------------------- | ----------------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Gaussian | gaussian | | | Lorentzian | lorentzian | | | Lorentzian Dispersive | lorentzianDispersive | | | Generalized Lorentzian | generalizedLorentzian | | | Pseudo Voigt | pseudoVoigt | | | 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

| | | | | |---------------------: | :---------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------- |

Installation

$ npm i ml-peak-shape-generator

This package allows to calculate various shapes. By default they will have a height of 1.

You see the resulting functions using this playground

Usage

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:

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 });

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:

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:

const copy = getShape1D(shape); // a new instance with the same parameters

The kind strings are exported as types:

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

import { gaussianFct } from 'ml-peak-shape-generator';
const func = gaussianFct(x - mean, fwhm);

API Documentation

License

MIT