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