smath 1.15.1 → 2.0.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,10 +1,7 @@
 #!/usr/bin/env node
-"use strict";
-var _a, _b, _c, _d;
-Object.defineProperty(exports, "__esModule", { value: true });
-var SMath = require(".");
-var func = ((_a = process.argv[2]) !== null && _a !== void 0 ? _a : '').toLowerCase(), nums = process.argv.slice(3).map(function (arg, i) {
-    var num = Number.parseFloat(arg);
+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)) {
         return num;
     }
@@ -53,7 +50,7 @@ if (func.includes('help')) {
 }
 switch (func) {
     case ('approx'): {
-        console.log(SMath.approx(nums[0], nums[1], (_b = nums[2]) !== null && _b !== void 0 ? _b : 1e-6));
+        console.log(SMath.approx(nums[0], nums[1], nums[2] ?? 1e-6));
         break;
     }
     case ('clamp'): {
@@ -157,11 +154,11 @@ switch (func) {
         break;
     }
     case ('rat'): {
-        console.log(SMath.rat(nums[0], (_c = nums[1]) !== null && _c !== void 0 ? _c : 1e-6));
+        console.log(SMath.rat(nums[0], nums[1] ?? 1e-6));
         break;
     }
     case ('mixed'): {
-        console.log(SMath.mixed(nums[0], (_d = nums[1]) !== null && _d !== void 0 ? _d : 1e-6));
+        console.log(SMath.mixed(nums[0], nums[1] ?? 1e-6));
         break;
     }
     case (''): {

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