regression-polynomial

ml-regression-polynomial is a focused TypeScript library from the mljs ecosystem for fitting polynomial regression models to a set of (x, y) data points. It solves the least-squares normal equations using matrix operations from ml-matrix, and shares its predict/score/serialization behavior with the rest of the mljs regression family through the ml-regression-base class.

Beyond a standard degree-N polynomial fit, it supports specifying an explicit array of powers (e.g. [1, 3, 5]) for sparse models, an interceptAtZero option to force f(0) = 0, and human-readable output via toString and toLaTeX. Models can be serialized to JSON and reloaded, making them easy to persist or transmit.

What You Get

• A PolynomialRegression class with a simple (x, y, degree, options) constructor
• Support for typed arrays (Float64Array, Int32Array, etc.) as well as plain number arrays
• An interceptAtZero option to force the fitted curve through the origin
• An explicit powers-array mode for sparse polynomials (e.g. only odd powers)
• toString and toLaTeX methods for human-readable formula output
• toJSON/load for serializing and restoring a fitted model

Common Use Cases

• Curve-fitting sensor or experimental data where the relationship is nonlinear but smooth
• Building calibration curves that must pass through the origin
• Generating human-readable regression formulas for reports or documentation
• Persisting a fitted model to JSON for reuse in another process or on a server

Under The Hood

Architecture The library is a single focused module (src/index.ts) exporting one class, PolynomialRegression, which extends BaseRegression from ml-regression-base to inherit predict/score/serialization plumbing shared across the mljs regression family. The constructor delegates to an internal regress() function that builds a design matrix from the requested powers (either 0..degree or an explicit powers array), forms the normal equations via matrix transpose-multiply, and solves them with ml-matrix’s solve(). A private _predict implements the polynomial evaluation used by the inherited predict/score methods, and toJSON/load provide a clean round-trip through a plain object. There is no other internal structure to speak of — the whole surface area is one class and one helper function, which keeps the mental model trivial and the blast radius of any change contained to a single file.

Tech Stack The package is pure TypeScript compiled with tsc to an ESM-only lib/ output (“type”: “module”, single export map entry). Its only runtime dependencies are ml-matrix (matrix construction, transpose views, and linear solve) and ml-regression-base (the shared BaseRegression class used across the mljs regression packages). Testing runs on Vitest with the v8 coverage provider; linting uses eslint-config-cheminfo-typescript via the flat ESLint config, and formatting is enforced with Prettier. CI and npm publishing are handled by zakodium’s shared reusable GitHub Actions workflows (nodejs.yml for lint/type-check/test, release.yml for automated npm releases), so there’s no bespoke build or release scripting to maintain.

Code Quality The test suite (src/tests/index.test.ts) is thorough for the library’s scope: it checks linear, quadratic, and quintic fits against precomputed coefficients, verifies behavior with typed-array inputs, exercises both the interceptAtZero option and the explicit-powers-array mode against the same expected solution, checks toString/toLaTeX formula rendering at different precisions, round-trips a model through toJSON/load, and includes a large-N (1,000,000-point) white-noise regression as a numerical-stability check. The test script chains vitest, tsc —noEmit, eslint, and prettier —check, and CI enforces lint and type-checking on every push and PR. Strict TypeScript typing is used throughout, with explicit @ts-expect-error annotations documenting the one deliberate type-unsafety (the internal load reconstruction path).

API Design The public API is intentionally minimal: new PolynomialRegression(x, y, degree, options) covers the common case, while passing an array of powers instead of a single degree number switches to a sparse-polynomial mode using the same constructor shape — a clean way to reuse one entry point for two related capabilities. Inherited predict/score methods keep the API consistent with sibling packages in the mljs regression family, lowering the learning cost for anyone already using another mljs regression module. toString/toLaTeX give a rare rendered-formula convenience most regression libraries skip, and toJSON/load give a straightforward persistence story. The design isn’t novel — it’s a standard least-squares polynomial fit — but the ergonomics and consistency with the broader mljs ecosystem are its real value.