stats-fns: Calculate simple statistics metrics

README.md

Statistics functions

Set of statistics functions for simple analysis.

Install

npm i gist:acb7729589f6ef734449c483045efe0c

Usage

import * as stats from 'stats-fns';
// or import { max, mean, stdev } from 'stats-fns';

const values = [1, 2, 3, 4, 5, 6, 7, 8, 9];

const max = stats.max(values);
const mean = stats.mean(values);
const stdev = stats.stdev(values);

Warning

For simplicity, the utility functions provided do not perform comprehensive input validation. It's the responsibility of the user to ensure that the inputs are of the correct type and within expected ranges.

index.d.ts

/**
 * Round a number
 * @param value Input number
 * @param decimals Number of decimals (optional, default 0)
 */
export declare const round: (value: number, decimals?: number) => number;

/**
 * Restrict a number between two limit values
 * @param value Input number
 * @param min Lower limit
 * @param max Upper limit
 */
export declare const clamp: (value: number, min: number, max: number) => number;

/**
 * Rescale a value from a given range to another range.
 * @param value Input number
 * @param minIn Lower limit for input range
 * @param maxIn Upper limit for input range
 * @param minOut Lower limit for output range (optional, defaults to 0)
 * @param maxOut Upper limit for output range (optional, defaults to 1)
 */
export declare const rescale: (value: number, minIn: number, maxIn: number, minOut?: number, maxOut?: number) => number;

/**
 * Compute the factorial n! of a number
 * @param value Input number
 */
export declare const factorial: (value: number) => number;

/**
 * Count the length of a numbers sequence
 * @param values Sequence of numbers
 */
export declare const count: (values: number[]) => number;

/**
 * Return the minimum value in a numbers sequence
 * @param values Sequence of numbers
 */
export declare const min: (values: number[]) => number;

/**
 * Return the maximum value in a numbers sequence
 * @param values Sequence of numbers
 */
export declare const max: (values: number[]) => number;

/**
 * Compute the range of a numbers sequence
 * @param values Sequence of numbers
 */
export declare const range: (values: number[]) => number;

/**
 * Compute the total sum of a numbers sequence
 * @param values
 */
export declare const sum: (values: number[]) => number;

/**
 * Compute the mean of a numbers sequence
 * @param values Sequence of numbers
 */
export declare const mean: (values: number[]) => number;

/**
 * Compute the nth quantile of a numbers sequence
 * @param values Sequence of numbers
 * @param proportion limit of the quantile, expressed from 0 to 1
 */
export declare const quantile: (values: number[], proportion: number) => number | null;

/**
 * Compute the median (or quantile 0.5) of a sequence of numbers
 * @param values Sequence of numbers
 */
export declare const median: (values: number[]) => number | null;

/**
 * Return all the numbers in a sequence and its occurence
 * @param values Sequence of numbers
 */
export declare const bins: (values: number[]) => [number, number][];

/**
 * Return the number in a seuqence that occurs most frequently
 * @param values Sequence of numbers
 */
export declare const mode: (values: number[]) => number;

/**
 * Compute the spread of numbers in a sequence
 * @param values Sequence of numbers
 */
export declare const variance: (values: number[]) => number;

/**
 * Compute the dispersion of numbers in a sequence
 * @param values Sequence of numbers
 */
export declare const stdev: (values: number[]) => number;

/**
 * Compute of how far from the mean are the numbers in a sequence
 * @param values Sequence of numbers
 */
export declare const zscore: (values: number[]) => number[];

/**
 * Compute outliers in a sequence of numbers due a zscore threshold
 * @param values Sequence of numbers
 * @param threshold Limit to consider a number an outlier. (optional, default -3/+3)
 */
export declare const outliers: (values: number[], threshold?: number) => number[];

/**
 * Compute the total normalized change of a value. Multiply by 100 for percentage
 * @param values Sequence of numbers
 */
export declare const growth: (values: number[]) => number;

index.js

/* Round a value with decimal precision. Default to 0 decimals */
export const round = (num, decimals = 0) => +num.toFixed(decimals);

/* Restrict a value between two other values */
export const clamp = (value, min, max) => (value < min ? min : value > max ? max : value);

/* Scale a value to another range. Default out range is normalized [0, 1] */
export const rescale = (value, minIn, maxIn, minOut = 0, maxOut = 1) => {
  return (value - minIn) * (maxOut - minOut) / (maxIn - minIn) + minOut;
};

/* Return the product of all positive integers less than or equal to a value */
export const factorial = value => [...Array(value).keys()].reduce((acc, i) => acc * (i + 1), 1);

/* Return the amount of values in a set of numbers */
export const count = values => values.length;

/* Return the lowest value of a set of numbers */
export const min = values => Math.min(...values);

/* Return the highest value of a set of numbers */
export const max = values => Math.max(...values);

/* Return the difference between the min and the max values of a set of numbers */
export const range = values => max(values) - min(values);

/* Return the sum of all values in a set of numbers numbers */
export const sum = values => values.reduce((acc, value) => acc + value, 0);

/* Return the typical or central value of a set of numbers */
export const mean = values => sum(values) / values.length;

/* Return the value where that contains a proportion of equal-sized, adjacent, subgroups of a set of numbers */
export const quantile = (values, proportion) => {
  const sorted = [...values].sort((a, b) => a - b);
  const pos = (sorted.length - 1) * proportion;
  const base = Math.floor(pos);
  const rest = pos - base;
  return sorted[base + 1]
    ? sorted[base] + (rest * (sorted[base + 1] - sorted[base]))
    : sorted[base] || null;
};

/* Return the middle value of a set of numbers. */
export const median = values => quantile(values, 0.5);

/* Return a list with all values in a set of numbers and its occurence [value, occurence] */
export const bins = values => Object.values(values.reduce((acc, value) => {
  if (acc[value]) acc[value][1] += 1;
  else acc[value] = [value, 1];
  return acc;
}, {}));

/* Return the value in a set of numbers that occurs most frequently. */
export const mode = values => bins(values).reduce((acc, pair) => pair[1] > acc[1] ? pair : acc)[0];

/* Return the spread between values in a setof numbers */
export const variance = values => {
  const _mean = mean(values);
  return sum(values.map(value => (value - _mean) ** 2)) / (values.length - 1);
};

/* Return the dispersion of a set of numbers relative to its mean */
export const stdev = values => Math.sqrt(variance(values));

/* Return the measurement of how far from the mean are the values in a set of numbers */
export const zscore = values => {
  const _mean = mean(values);
  const _stdev = stdev(values);
  return values.map(value => (value - _mean) / _stdev);
};

/* Return all values considered outliers in a set of numbers. Default zscore threshold is -3/+3 */
export const outliers = (values, threshold = 3) => {
  const _zscores = zscore(values);
  return values.filter((_, i) => Math.abs(_zscores[i]) > threshold);
};

/* Return the normalized change of a value. Multiply by 100 for percentage */
export const growth = values => {
  const { 0: prev, [values.length - 1]: last } = values;
  return (last - prev) / prev;
};

package.json

{
  "version": "1.3.1",
  "name": "stats-fns",
  "main": "index.js",
  "types": "index.d.ts"
}