API Reference

Complete reference for the sciencekit Lua 5.4 module (sciencekit_lua 0.5.0), grounded directly in src/lib.rs, src/userdata/builder.rs, src/userdata/model.rs, src/engine/family.rs, src/error.rs, and tests/run.lua.

local sciencekit = require("sciencekit")

require("sciencekit") always returns a plain Lua table (type(sciencekit) == "table"), never a callable proxy.

Module table (sciencekit)

Native symbol

Builder userdata (SKLuaBuilder)

Returned by sciencekit.linear_regression() and sciencekit.standard_scaler().

Read-only fields

Methods

All configuration setters mutate the builder in place and return the same builder userdata (self), enabling fluent chaining.

builder:include_intercept(enabled) -> builder

• Parameters: enabled: boolean
• Supported families: "linear-regression" (raises sciencekit unsupported (4) on "standard-scaler").
• Description: Configures whether linear regression fits an intercept term.

builder:with_mean(enabled) -> builder

• Parameters: enabled: boolean
• Supported families: "standard-scaler" (raises sciencekit unsupported (4) on "linear-regression").
• Description: Configures whether each column is centered by subtracting its training mean.

builder:with_std(enabled) -> builder

• Parameters: enabled: boolean
• Supported families: "standard-scaler" (raises sciencekit unsupported (4) on "linear-regression").
• Description: Configures whether each column is divided by its training standard deviation.

builder:backend(backend) -> builder

• Parameters: backend: string | integer
• Supported families: "linear-regression", "standard-scaler"
• Accepted values:
  • "faer" or 0
  • "matrix-multiply" (alias "matrixmultiply") or 1
  • "ndarray-linalg" (alias "ndarray_linalg") or 2
• Errors: Raises sciencekit invalid-argument (3) if given an unknown string, an integer outside 0..2, or any other Lua type.

builder:fit(features[, targets]) -> Model

• Parameters:
  • features: table — non-empty rectangular 1-indexed table of numeric rows (N × D).
  • targets: table | nil — required when builder.family == "linear-regression" (flat sequence { y1, ..., yN } or column { {y1}, ..., {yN} } with length N); omitted (nil) for "standard-scaler".
• Returns: A new fitted Model userdata (model.family == builder.family, model.dtype == "f64"). The builder itself remains open.
• Errors: Raises sciencekit shape (2), sciencekit invalid-argument (3), or sciencekit invalid-handle (1).

builder:close() -> nil

• Description: Releases the underlying SKFfiBuilder handle immediately and marks builder.closed = true. Idempotent: subsequent calls are no-ops returning nil.

Metamethods

Fitted model userdata (SKLuaModel)

Returned by builder:fit(...) and sciencekit.load(path).

Read-only fields

Methods

model:predict(features) -> table

• Parameters: features: table — rectangular N × D table of numbers matching the fitted column count D.
• Supported families: "linear-regression" (raises sciencekit unsupported (4) on "standard-scaler").
• Returns: Fresh N × 1 Lua table of one-element rows: { { y1 }, { y2 }, ..., { yN } }.

model:transform(features) -> table

• Parameters: features: table — rectangular N × D table of numbers matching the fitted column count D.
• Supported families: "standard-scaler" (raises sciencekit unsupported (4) on "linear-regression").
• Returns: Fresh N × D Lua table of transformed rows.

model:score(features, targets) -> number

• Parameters:
  • features: table — rectangular N × D table of numbers.
  • targets: table — flat sequence or N × 1 table of rows with length N.
• Supported families: "linear-regression" (raises sciencekit unsupported (4) on "standard-scaler").
• Returns: Coefficient of determination (R²) as a Lua number (f64).

model:save(path) -> nil

• Parameters: path: string — filesystem path without interior NUL bytes.
• Supported families: "linear-regression" (raises sciencekit unsupported (4) on "standard-scaler").
• Returns: nil.

model:close() -> nil

• Description: Releases the underlying SKFfiModel handle immediately and marks model.closed = true. Idempotent.

Metamethods

Error format & status codes

Runtime error strings always match:

sciencekit <status-name> (<code>): <message>