smath 1.16.0 → 2.1.0

package/README.md

@@ -23,3 +23,54 @@ npx smath normalize 4 0 10
 ```
 
 > Most `SMath` functions are available through `npx`, except for calculus functions which require a functional argument.
+
+## Data Fitting
+
+SMath also exports the `DataFit` object which contains only 1 function, `fit()` which is used for curve fitting. All other exports are purely for defining types used within `fit()`. `fit()` uses a genetic-style algorithm to fit a curve.
+
+### How it works
+
+It generates many sets of parameters to test, and keeps ones with smaller error than the previous iteration. Parameter sets with larger errors are discarded. Each subsequent iteration uses the sets of parameters with the least error and "mutates" them randomly.
+
+> Because of these random mutations, running the same code multiple times may yield slightly different results. See [best practices](#best-practices) for mitigation tactics.
+
+### Complexity
+
+The folling factors affect computation time and resources:
+
+- Number of iterations
+- Number of independent/unknown function parameters
+- Number of data points
+
+Each one alone has a linear effect on performance, but combined has an incremental effect.
+
+`time = iterations * ( parameters + dataset )`
+
+The dimensionality, or number of free `x` variables per data point, should not have an impact on computation time.
+
+### Best Practices
+
+For production software that relies on a best curve fit for data, it's best to avoid critical operations using `fit()` for a few reasons.
+
+1. `fit()` uses an algorithm that generates random mutations in a set of parameters, which could yield slightly different results, even if run on the same dataset.
+1. If the number of iterations is very high (in the millions or higher), it could have a significant effect on software performance.
+1. Due to a limitation in JavaScript/TypeScript, the input function parameters cannot be optional or have default values. If they do have default values, assign them inside the function body.
+
+To circumvent some of these issues, the following is recommended.
+
+1. Use `datafit` during the testing phase of application development, and use the best-fit parameters as constants in the final application.
+1. If that is not possible, `datafit` may be helpful for determining an initial guess of curve fit constants, which can be input to `fit()` during production. The number of iterations could be reduced if the initial guess is reasonably close to the desired result.
+1. Using `datafit` primarily for data visualization or rough estimation.
+1. For operations that *need* `datafit`, a suggestion would be to run multiple iterations of `fit()` itself, and using each output as the subsequent call's input. This will converge to a result more effectively but could take longer.
+
+And here are some general good practices.
+
+1. Avoid overfitting your data. That means, you should never have more function unknowns than the number of data points. `fit()` allows this for the rare chance that it is needed. Typically, having more, accurate data, is better for curve fitting.
+1. Reject outliers. `fit()` does not do this. Any outliers existing in the dataset will be treated like normal data points and could negatively impact the best fit.
+
+There are also some great arguments and use cases for this function, namely...
+
+1. Data analysis and visualization.
+1. Quickly iterating on different model functions for determining which best fits the data.
+1. Curve fitting for multivariate or nonlinear models.
+1. The ease of use of it all! It's just one function call with as little as 2 inputs!

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import * as SMath from './index.js';
+import { SMath } from './index.js';
 const func = (process.argv[2] ?? '').toLowerCase(), nums = process.argv.slice(3).map((arg, i) => {
     const num = Number.parseFloat(arg);
     if (Number.isFinite(num)) {
@@ -24,6 +24,7 @@ if (func.includes('help')) {
     console.log('  logspace <min> <max> <n> : Generate `n` logarithmically spaced numbers between `min` and `max`');
     console.log('  factorial <n>            : Compute `n!` (factorial)');
     console.log('  factors <n>              : List the prime factors of `n`');
+    console.log('  isPrime <n>              : Determine if `n` is prime');
     console.log('  round2 <n> <base>        : Round `n` to a multiple of any `base`');
     console.log('  error <exp> <act>        : Calculate the normaized percent error between `exp` and `act`');
     console.log('  sum <c0> [c1] ... [cn]   : Compute a total of `n` numbers');
@@ -85,6 +86,10 @@ switch (func) {
         console.log(SMath.factors(nums[0]));
         break;
     }
+    case ('isPrime'): {
+        console.log(SMath.isPrime(nums[0]));
+        break;
+    }
     case ('round2'): {
         console.log(SMath.round2(nums[0], nums[1]));
         break;

package/dist/datafit/index.js

@@ -0,0 +1,2 @@
+export * from './lib.js';
+export * from './types.js';

package/dist/datafit/lib.js

@@ -0,0 +1,72 @@
+import { SMath } from '../index.js';
+/**
+ * Minimize the sum of squared errors to fit a set of data
+ * points to a curve with a set of unknown parameters.
+ * @param f The model function for curve fitting.
+ * @param data The entire dataset, as an array of points.
+ * @param params_initial The initial guess for function
+ * parameters, which defaults to an array filled with zeroes.
+ * @param iterations The number of parameter sets to generate.
+ * @param maxDeviation The relative standard parameter deviation.
+ * This is a number [0.0-1.0] and affects the standard deviation
+ * on the first iteration. Every subsequent iteration has a
+ * decayed standard deviation until the final iteration.
+ * @returns The set of parameters and error for the best fit.
+ * @example
+ * // Define model function
+ * function f(x: number, a2: number = -0.5, a1: number = 3.9, a0: number = -1.2): number {
+ *     return a2 * x ** 2 + a1 * x + a0;
+ * }
+ * // Construct a data set
+ * const data: Datum<number>[] = [0, 2, 4].map(x => ({ x: x, y: f(x) }));
+ * // Compute best-fit summary
+ * const summary = fit(f, data);
+ */
+export function fit(f, data, params_initial = [], iterations = 1e3, maxDeviation = 1) {
+    const N_params = f.length - 1;
+    if (params_initial.length === 0) {
+        params_initial.length = N_params;
+        params_initial.fill(0);
+    }
+    if (params_initial.length !== N_params) {
+        throw new Error('The initial guess should contain ' + N_params + ' parameters.');
+    }
+    if (maxDeviation <= 0) {
+        throw new Error('Standard deviation should be a positive value.');
+    }
+    let params = params_initial, error = err(f, params, data);
+    for (let i = 0; i < iterations; i++) {
+        const params_i = mutate(params, SMath.translate(i, 0, iterations, maxDeviation, 0)), error_i = err(f, params_i, data);
+        if (error_i < error) {
+            params = params_i;
+            error = error_i;
+        }
+    }
+    return {
+        f: (x) => f(x, ...params),
+        params: params,
+        error: error,
+        errorAvgAbs: Math.sqrt(error / data.length),
+    };
+}
+/**
+ * Calculate the sum of squared errors for a set of function parameters.
+ * @param f The model function for curve fitting.
+ * @param params The array of parameters to check.
+ * @param data The entire dataset, as an array of points.
+ * @returns The sum of squared errors.
+ */
+function err(f, params, data) {
+    let sum = 0;
+    data.forEach(point => sum += (point.y - f(point.x, ...params)) ** 2);
+    return sum;
+}
+/**
+ * Randomly mutate the set of function parameters by some standard deviation.
+ * @param params The set of function parameters to mutate.
+ * @param deviation The standard relative amount to deviate in any direction.
+ * @returns A mutated set of parameters.
+ */
+function mutate(params, deviation) {
+    return params.map(c => SMath.rnorm(c, deviation * Math.max(1, Math.abs(c))));
+}

package/dist/datafit/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -1,513 +1,4 @@
-/**
- * @packageDocumentation
- * Small math function library
- *
- * ![NPM Downloads](https://img.shields.io/npm/d18m/smath)
- * ![NPM Last Update](https://img.shields.io/npm/last-update/smath)
- */
-/**
- * Check if two numbers are approximately equal with a maximum abolute error.
- * @param a Any number
- * @param b Any number
- * @param epsilon Maximum absolute error
- * @returns True if `a` is approximately `b`
- * @example
- * const b1 = SMath.approx(1 / 3, 0.33, 1e-6), // false
- *       b2 = SMath.approx(1 / 3, 0.33, 1e-2); // true
- */
-export function approx(a, b, epsilon = 1e-6) {
-    return a - b < epsilon && b - a < epsilon;
-}
-/**
- * Clamp a number within a range.
- * @param n The number to clamp
- * @param min The minimum value of the range
- * @param max The maximum value of the range
- * @returns A clamped number
- * @example
- * const n1 = SMath.clamp(5, 0, 10),  // 5
- *       n2 = SMath.clamp(-2, 0, 10); // 0
- */
-export function clamp(n, min, max) {
-    if (n < min) {
-        return min;
-    }
-    if (n > max) {
-        return max;
-    }
-    return n;
-}
-/**
- * Normalize the number `n` from the range `min, max` to the range `0, 1`
- * @param n The number to normalize
- * @param min The minimum value in the range
- * @param max The maximum value in the range
- * @returns A normalized value
- * @example
- * const y = SMath.normalize(18, 9, 99); // 0.1
- */
-export function normalize(n, min, max) {
-    if (min === max) {
-        return 0;
-    }
-    return (n - min) / (max - min);
-}
-/**
- * Expand a normalized number `n` to the range `min, max`
- * @param n A normalized number
- * @param min The minimum value in the range
- * @param max The maximum value in the range
- * @returns A value within the number range
- * @example
- * const y = SMath.expand(0.25, 4, 6); // 4.5
- */
-export function expand(n, min, max) {
-    return (max - min) * n + min;
-}
-/**
- * Translate a number `n` from the range `min1, max1` to the range `min2, max2`
- * @param n The number to translate
- * @param min1 The minimum value from the initial range
- * @param max1 The maximum value from the initial range
- * @param min2 The minimum value for the final range
- * @param max2 The maximum value for the final range
- * @returns A translated number in the final range
- * @example
- * const C = 20,
- *       F = SMath.translate(C, 0, 100, 32, 212); // 68
- */
-export function translate(n, min1, max1, min2, max2) {
-    return expand(normalize(n, min1, max1), min2, max2);
-}
-/**
- * Generate an array of linearly spaced numbers.
- * @param min The initial value of the linear space
- * @param max The final value of the linear space
- * @param count The number of values in the space
- * @returns The linear space as an array of numbers
- * @example
- * const space = SMath.linspace(1, 5, 6);
- * // [ 1, 1.8, 2.6, 3.4, 4.2, 5 ]
- */
-export function linspace(min, max, count) {
-    const space = [];
-    for (let i = 0; i < count; i++) {
-        space[i] = translate(i, 0, count - 1, min, max);
-    }
-    return space;
-}
-/**
- * Generate an array of logarithmically spaced numbers.
- * @param min The initial magnitude of the space
- * @param max The final magnitude of the space
- * @param count The number of values in the space
- * @returns The logarithmic space as an array of numbers
- * @example
- * const space = SMath.logspace(0, 2, 5);
- * // [ 1, 3.2, 10, 31.6, 100 ]
- */
-export function logspace(min, max, count) {
-    return linspace(min, max, count).map(n => 10 ** n);
-}
-/**
- * Compute the factorial of `n`.
- * @param n Any positive integer
- * @returns `n!`
- * @example
- * const y = SMath.factorial(5); // 120
- */
-export function factorial(n) {
-    if (n < 0 || (n | 0) !== n) {
-        throw new Error('Input must be a positive integer.');
-    }
-    else if (n === 0) {
-        return 1;
-    }
-    else if (n <= 2) {
-        return n;
-    }
-    else {
-        return n * factorial(n - 1);
-    }
-}
-/**
- * Factorize `n` into its prime factors.
- * @param n Any positive integer
- * @returns The array of prime factors
- * @example
- * const y = SMath.factors(12); // [ 2, 2, 3 ]
- */
-export function factors(n) {
-    if (n < 0 || (n | 0) !== n) {
-        throw new Error('Input must be a positive integer!');
-    }
-    if (n <= 3) {
-        return [n];
-    }
-    const f = [];
-    let i = 2;
-    while (n > 1 && i <= n) {
-        if ((n / i) === ((n / i) | 0)) {
-            n /= i;
-            f.push(i);
-        }
-        else {
-            i++;
-        }
-    }
-    return f;
-}
-/**
- * Round a number to the nearest multiple of an arbitrary
- * base. Does not round when the base is set to zero.
- * @param n Any number to round
- * @param base Any base to round to
- * @returns `n` rounded to the nearest multiple of `base`
- * @example
- * const y = SMath.round2(Math.PI, 0.2); // 3.2
- */
-export function round2(n, base) {
-    const rounded = base ? base * Math.round(n / base) : n;
-    const precision = 10; // Removes precision errors
-    return parseFloat(rounded.toFixed(precision));
-}
-/**
- * Calculate the relative normalized error or deviation from any
- * value to an accepted value. An error of 0 indicates that the
- * two values are identical. An error of -0.1 indicates that the
- * experimental value is 10% smaller than (90% of) the accepted
- * value. An error of 1.0 indicates that the experimental value
- * is 100% greater (or twice the size) of the accepted value.
- * @param experimental The value observed or produced by a test
- * @param actual The accepted or theoretical value
- * @returns The relative (normalized) error
- * @example
- * const e = SMath.error(22.5, 25); // -0.1
- */
-export function error(experimental, actual) {
-    if (experimental === 0 && actual === 0) {
-        return 0;
-    }
-    else {
-        return (experimental - actual) / actual;
-    }
-}
-/**
- * Add up all the inputs.
- * If none are present, returns 0.
- * @param data An array of numeric inputs
- * @returns The sum total
- * @example
- * const y = SMath.sum([1, 2, 3]); // 6
- */
-export function sum(data) {
-    return data.reduce((a, b) => a + b, 0);
-}
-/**
- * Multiply all the inputs.
- * If none are present, returns 1.
- * @param data An array of numeric inputs
- * @returns The product
- * @example
- * const y = SMath.prod([2, 2, 3, 5]); // 60
- */
-export function prod(data) {
-    return data.reduce((a, b) => a * b, 1);
-}
-/**
- * Compute the average, or mean, of a set of numbers.
- * @param data An array of numeric inputs
- * @returns The average, or mean
- * @example
- * const y = SMath.avg([1, 2, 4, 4]); // 2.75
- */
-export function avg(data) {
-    return sum(data) / data.length;
-}
-/**
- * Compute the median of a set of numbers.
- * @param data An array of numeric inputs
- * @returns The median of the dataset
- * @example
- * const y = SMath.median([2, 5, 3, 1]); // 2.5
- */
-export function median(data) {
-    data.sort((a, b) => a - b);
-    if (data.length % 2) {
-        return data[(data.length - 1) / 2];
-    }
-    return avg([data[data.length / 2 - 1], data[data.length / 2]]);
-}
-/**
- * Compute the variance of a **complete population**.
- * @param data An array of numeric inputs
- * @returns The population variance
- * @example
- * const y = SMath.varp([1, 2, 4, 4]); // 1.6875
- */
-export function varp(data) {
-    const mean = avg(data), squares = data.map(x => (x - mean) ** 2);
-    return sum(squares) / data.length;
-}
-/**
- * Compute the variance of a **sample**.
- * @param data An array of numeric inputs
- * @returns The sample variance
- * @example
- * const y = SMath.vars([1, 2, 4, 4]); // 2.25
- */
-export function vars(data) {
-    const mean = avg(data), squares = data.map(x => (x - mean) ** 2);
-    return sum(squares) / (data.length - 1);
-}
-/**
- * Compute the standard deviation of a **complete population**.
- * @param data An array of numeric inputs
- * @returns The population standard deviation
- * @example
- * const y = SMath.stdevp([1, 2, 3, 4]); // 1.118...
- */
-export function stdevp(data) {
-    return Math.sqrt(varp(data));
-}
-/**
- * Compute the standard deviation of a **sample**.
- * @param data An array of numeric inputs
- * @returns The sample standard deviation
- * @example
- * const y = SMath.stdevs([1, 2, 3, 4]); // 1.29...
- */
-export function stdevs(data) {
-    return Math.sqrt(vars(data));
-}
-/**
- * Generate a uniformly-distributed floating-point number within the range.
- * @param min The minimum bound
- * @param max The maximum bound
- * @returns A random float within the range
- * @example
- * const y = SMath.runif(-2, 2); // 0.376...
- */
-export function runif(min, max) {
-    return expand(Math.random(), min, max);
-}
-/**
- * Generate a uniformly-distributed integer within the range.
- * @param min The minimum bound (inclusive)
- * @param max The maximum bound (inclusive)
- * @returns A random integer within the range
- * @example
- * const y = SMath.rint(-4, 3); // -4
- */
-export function rint(min, max) {
-    min |= 0;
-    max |= 0;
-    if (min < 0) {
-        min--;
-    }
-    if (max > 0) {
-        max++;
-    }
-    return clamp(runif(min, max), min, max) | 0; // `| 0` pulls toward 0
-}
-/**
- * Generate a normally-distributed floating-point number.
- * @param mean The mean of the population distribution
- * @param stdev The standard deviation of the population
- * @returns A random float
- * @example
- * const y = SMath.rnorm(2, 3); // 1.627...
- */
-export function rnorm(mean = 0, stdev = 1) {
-    return mean + stdev * Math.sqrt(-2 * Math.log(Math.random())) * Math.cos(2 * Math.PI * Math.random());
-}
-/**
- * Generate a population of normally-distributed floating-point numbers.
- * @param count The number of values to generate
- * @param mean The mean of the population distribution
- * @param stdev The standard deviation of the population
- * @returns A population of random floats
- * @example
- * const dataset = SMath.rdist(3); // [ 1.051..., -0.779..., -2.254... ]
- */
-export function rdist(count, mean = 0, stdev = 1) {
-    const distribution = [];
-    for (let i = 0; i < count; i++) {
-        distribution[i] = rnorm(mean, stdev);
-    }
-    return distribution;
-}
-/**
- * Randomize an array of arbitrary elements.
- * @param stack An array of arbitrary elements
- * @returns The `stack` array in a random order
- * @example
- * const shuffled = SMath.shuffle(['a', 'b', 'c']); // [ 'c', 'a', 'b' ]
- */
-export function shuffle(stack) {
-    const rawData = [];
-    for (const item of stack) {
-        rawData.push({ index: Math.random(), value: item });
-    }
-    return rawData.sort((a, b) => a.index - b.index).map(a => a.value);
-}
-/**
- * Select a single item from an array at random with uniform weights.
- * @param stack An array of arbirary item
- * @returns A single randomly selected item
- * @example
- * const selected = SMath.selectRandom([10, 20, 30, 40]); // 30
- */
-export function selectRandom(stack) {
-    return stack[rint(0, stack.length - 1)];
-}
-/**
- * Select a single index in an array at random with different weights.
- * @param weights The weights for each item
- * @returns The 0-based index of the randomly selected item
- * @example
- * const index = SMath.selectRandomWeighted([3.5, 4, 1]); // 1
- */
-export function selectRandomWeighted(weights) {
-    const startWeights = [];
-    let accumulation = 0;
-    for (const weight of weights) {
-        accumulation += clamp(0, weight, Infinity);
-        startWeights.push(accumulation);
-    }
-    const random = runif(0, accumulation);
-    return startWeights.findIndex(weight => random < weight);
-}
-/**
- * Take the limit of a function. A return value of `NaN` indicates
- * that no limit exists either due to a discontinuity or imaginary value.
- * @param f Function `f(x)`
- * @param x The x-value where to take the limit
- * @param h The approach distance
- * @param discontinuity_cutoff The discontinuity cutoff
- * @returns `lim(f(x->x))`
- * @example
- * const y = SMath.lim(Math.log, 0); // -Infinity
- */
-export function lim(f, x, h = 1e-6, discontinuity_cutoff = 1e-3) {
-    const center = f(x), left1 = f(x - h), left2 = f(x - h / 2), right1 = f(x + h), right2 = f(x + h / 2);
-    let left, right;
-    if (Number.isFinite(center)) {
-        return center;
-    }
-    // Check the limit approaching from the left
-    if (Number.isFinite(left1) && Number.isFinite(left2)) {
-        if (approx(left1, left2, discontinuity_cutoff)) {
-            left = left2; // Converges
-        }
-        else if (left1 > 0 && left2 > left1) {
-            left = Infinity; // Diverges to +inf
-        }
-        else if (left1 < 0 && left2 < left1) {
-            left = -Infinity; // Diverges to -inf
-        }
-        else {
-            left = NaN; // Diverges
-        }
-    }
-    else {
-        left = NaN; // Discontinuous
-    }
-    // Check the limit approaching from the right
-    if (Number.isFinite(right1) && Number.isFinite(right2)) {
-        if (approx(right1, right2, discontinuity_cutoff)) {
-            right = right2; // Converges
-        }
-        else if (right1 > 0 && right2 > right1) {
-            right = Infinity; // Diverges to +inf
-        }
-        else if (right1 < 0 && right2 < right1) {
-            right = -Infinity; // Diverges to -inf
-        }
-        else {
-            right = NaN; // Diverges
-        }
-    }
-    else {
-        right = NaN; // Discontinuous
-    }
-    // Check if limits match or are close
-    if (left === right) { // Handles +/-Infinity case
-        return left;
-    }
-    else if (Number.isNaN(left) && Number.isNaN(right)) {
-        return center;
-    }
-    else if (!Number.isNaN(left) && Number.isNaN(right)) {
-        return left;
-    }
-    else if (Number.isNaN(left) && !Number.isNaN(right)) {
-        return right;
-    }
-    else if (approx(left, right, discontinuity_cutoff)) {
-        return avg([left, right]);
-    }
-    else {
-        return NaN;
-    }
-}
-/**
- * Take the derivative of a function.
- * @param f Function `f(x)`
- * @param x The x-value where to evaluate the derivative
- * @param epsilon Small step value
- * @returns `f'(x)`
- * @example
- * const y = SMath.differentiate(x => 3 * x ** 2, 2); // 12
- */
-export function differentiate(f, x, epsilon = 1e-6) {
-    return lim(h => (f(x + h) - f(x - h)) / (2 * h), 0, epsilon);
-}
-/**
- * Compute the definite integral of a function.
- * @param f Function `f(x)`
- * @param a The miminum integral bound
- * @param b The maximum integral bound
- * @param Ndx The number of rectangles to compute
- * @returns `F(b)-F(a)`
- * @example
- * const y = SMath.integrate(x => 3 * x ** 2, 1, 2); // 7
- */
-export function integrate(f, a, b, Ndx = 1e6) {
-    return ((b - a) / Ndx) * sum(linspace(a, b, Ndx).map(x => f(x)));
-}
-/**
- * Convert an arbitrary decimal number into a simplified fraction (or ratio).
- * See `mixed()` for instructions on how to break out the whole number part.
- * @param n The decimal number to convert
- * @param epsilon Maximum absolute error
- * @returns An object containing the fraction's numerator and denominator
- * @example
- * const frac = SMath.rat(0.625); // { num: 5, den: 8 }
- */
-export function rat(n, epsilon = 1e-6) {
-    let num = 0, den = 1;
-    const sign = n < 0 ? -1 : 1;
-    while (!approx(sign * n, num / den, epsilon)) {
-        if (sign * n > num / den) {
-            num++;
-        }
-        else {
-            den++;
-        }
-    }
-    return { num: sign * num, den: den };
-}
-/**
- * Convert an arbitrary decimal number into a simplified fraction, after
- * breaking out the whole number part first. See `rat()` for keeping the
- * number as a ratio without separating the whole number part.
- * @param n A decimal number to convert
- * @param epsilon Maximum absolute error
- * @returns An object containing the whole part and fraction numerator and denominator
- * @example
- * const frac = SMath.mixed(-8 / 6); // { whole: -1, num: 1, den: 3 }
- */
-export function mixed(n, epsilon = 1e-6) {
-    return { whole: n | 0, ...rat(n < -1 ? (n | 0) - n : n - (n | 0), epsilon) };
-}
+import * as SMath_1 from './smath.js';
+export { SMath_1 as SMath };
+import * as DataFit_1 from './datafit/index.js';
+export { DataFit_1 as DataFit };