diff --git a/backend/tests/test_scientific_fitting.py b/backend/tests/test_scientific_fitting.py new file mode 100644 index 00000000..28a2eaa0 --- /dev/null +++ b/backend/tests/test_scientific_fitting.py @@ -0,0 +1,268 @@ +"""Independent published oracles for the Fitting and Inference scientific pack.""" + +import copy +import json +import math +from pathlib import Path + +import pytest + +from graphlink_plugins.scientific.catalog import PACKS, operations +from graphlink_plugins.scientific.core import VERSION, readable_result, run_operation +from graphlink_plugins.scientific.packs import fitting + +FIXTURE = json.loads(Path(__file__).with_name("test_scientific_fitting_nist.json").read_text(encoding="utf-8")) + + +def _run(operation_id, inputs): + operation = next(o for o in operations("fitting") if o.id == operation_id) + return run_operation("fitting", operation, inputs) + + +def _certified(actual, reference, digits): + """Compare all *published* significant digits, not an arbitrary tolerance.""" + assert format(actual, f".{digits - 1}e") == format(reference, f".{digits - 1}e"), (actual, reference) + + +def test_manifest_and_all_examples_have_verifiable_receipts(): + import tomllib + + assert PACKS["fitting"][0] == "Fitting and Inference" + manifest_path = Path(__file__).resolve().parents[2] / "plugins" / "science_fitting" / "plugin.toml" + with manifest_path.open("rb") as f: + manifest = tomllib.load(f) + assert manifest["plugin"]["id"] == "science_fitting" + assert manifest["plugin"]["version"] == VERSION + assert manifest["scopes"]["grants"] == ["graph.read", "graph.mutate"] + assert manifest["persistence"]["passive_node_kinds"] == ["workbench"] + assert {op.id for op in operations("fitting")} == { + "weighted_linear_least_squares", "nonlinear_least_squares", "welch_t_test", "chi_square_gof" + } + for operation in operations("fitting"): + result = _run(operation.id, operation.example) + assert result["provenance"]["packId"] == "fitting" + assert result["provenance"]["packVersion"] == VERSION + assert readable_result({"version": 1, "latest": result}, "fitting") + corrupted = copy.deepcopy(result) + key = next(iter(corrupted["values"])) + corrupted["values"][key] = "corrupted" + assert not readable_result({"version": 1, "latest": corrupted}, "fitting") + + +def test_longley_all_15_certified_digits_from_the_raw_nist_rows(): + item = FIXTURE["longley"] + rows = item["data_y_x1_x2_x3_x4_x5_x6"] + values = _run("weighted_linear_least_squares", { + "predictors": [row[1:] for row in rows], "response": [row[0] for row in rows], + "weights": [1] * len(rows), + }) + result = values["values"] + for i, expected in enumerate(item["coefficients"]): + _certified(result[f"coefficient_{i}"], expected, item["digits"]) + for i, expected in enumerate(item["standard_errors"]): + _certified(result[f"standard_error_{i}"], expected, item["digits"]) + _certified(result["residual_standard_deviation"], item["residual_standard_deviation"], item["digits"]) + _certified(result["r_squared"], item["r_squared"], item["digits"]) + assert result["degrees_of_freedom"] == 9 + assert len(values["table"]["rows"]) == 7 # 7 x 7 coefficient covariance + for i in range(7): + for j in range(7): + _certified(values["table"]["rows"][i][j + 1], + values["table"]["rows"][j][i + 1], 14) + assert math.sqrt(values["table"]["rows"][i][i + 1]) == pytest.approx(result[f"standard_error_{i}"], rel=1e-14) + assert len(values["plot"]["y"]) == 16 + assert abs(math.fsum(values["plot"]["y"])) < 1e-7 + assert result["weighted_residual_sum_squares"] == pytest.approx(836424.055505915, rel=2e-15) + + +@pytest.mark.parametrize("case", ["misra1a", "thurber", "mgh09"]) +@pytest.mark.parametrize("start_number", [0, 1]) +def test_nist_nonlinear_all_11_certified_digits_from_both_starts(case, start_number): + item = FIXTURE[case] + rows = item["data_y_x"] + result = _run("nonlinear_least_squares", { + "model": item["model"], "x": [row[1] for row in rows], "y": [row[0] for row in rows], + "weights": [1] * len(rows), "initial_parameters": item["starts"][start_number], + }) + values = result["values"] + assert values["converged"] == "true" + assert 1 <= values["iterations"] < 1201 + assert values["accepted_steps"] > 0 + assert values["degrees_of_freedom"] == len(rows) - len(item["parameters"]) + for i, expected in enumerate(item["parameters"]): + _certified(values[f"parameter_{i}"], expected, item["digits"]) + for i, expected in enumerate(item["standard_errors"]): + _certified(values[f"standard_error_{i}"], expected, item["digits"]) + _certified(values["weighted_residual_sum_squares"], item["residual_sum_squares"], item["digits"]) + assert values["reduced_chi_square"] == pytest.approx( + values["weighted_residual_sum_squares"] / values["degrees_of_freedom"], rel=1e-14 + ) + assert len(result["plot"]["y"]) == len(rows) + for j in range(len(item["parameters"])): + estimate = values[f"parameter_{j}"] + assert values[f"ci95_lower_{j}"] < estimate < values[f"ci95_upper_{j}"] + assert values[f"ci95_upper_{j}"] - estimate == pytest.approx( + fitting._student_t_ppf(0.975, values["degrees_of_freedom"]) * values[f"standard_error_{j}"], + rel=1e-12, abs=1e-14, + ) + + +@pytest.mark.parametrize("model,parameters,x", [ + ("exponential", [2.0, -0.3, 4.0], list(range(1, 12))), + ("power_law", [3.0, 1.25], list(range(1, 12))), + ("gaussian", [2.0, 10.0, 0.5, 1.25], [i / 2 for i in range(-10, 13)]), + ("polynomial", [2.0, -1.0, 0.5, 0.125], list(range(-5, 7))), +]) +def test_other_nonlinear_families_recover_known_parameters(model, parameters, x): + # Generated from the declared equation and analytic Jacobian, without + # calling the fitter; add small deterministic noise for nonzero SEs. + y = [float(fitting._model(model, fitting._d(xx), list(map(fitting._d, parameters)))[0]) + + (i % 3 - 1) * 0.0001 for i, xx in enumerate(x)] + initial = [v * 1.02 if v else 0.02 for v in parameters] + if model == "gaussian": + initial[2] += 0.1 + result = _run("nonlinear_least_squares", { + "model": model, "x": x, "y": y, "weights": [1] * len(x), "initial_parameters": initial, + }) + for i, expected in enumerate(parameters): + assert result["values"][f"parameter_{i}"] == pytest.approx(expected, rel=0.003, abs=0.002) + assert result["values"][f"standard_error_{i}"] > 0 + assert result["values"]["weighted_residual_sum_squares"] < 1e-6 + + +def test_analytic_model_jacobians_agree_with_centered_finite_differences(): + examples = [ + ("exponential", 2, [2.0, -0.3, 4.0]), ("saturating_exponential", 10, [25, 0.01]), + ("power_law", 2, [3, 1.5]), ("gaussian", 0.4, [1, 3, 0.5, 1.3]), + ("polynomial", 2, [1, -2, 3]), ("thurber", 0.4, [1000, 1000, 400, 40, 0.7, 0.3, 0.03]), + ("mgh09", 0.5, [0.2, 0.2, 0.1, 0.15]), + ] + for name, xx, params in examples: + dparams = list(map(fitting._d, params)) + _, derivatives = fitting._model(name, fitting._d(xx), dparams) + for j, derivative in enumerate(derivatives): + step = fitting._d(1e-6 * max(abs(params[j]), 1)) + higher, lower = dparams.copy(), dparams.copy() + higher[j] += step + lower[j] -= step + high = fitting._model(name, fitting._d(xx), higher)[0] + low = fitting._model(name, fitting._d(xx), lower)[0] + numerical = (high - low) / (2 * step) + assert float(derivative) == pytest.approx(float(numerical), rel=1e-9, abs=1e-9), (name, j) + + +def test_distribution_functions_against_nist_published_tables(): + # https://www.itl.nist.gov/div898/handbook/eda/section3/eda3672.htm + assert fitting._student_t_cdf(2.228, 10) == pytest.approx(0.975, abs=2e-5) + assert fitting._student_t_cdf(-2.228, 10) == pytest.approx(0.025, abs=2e-5) + assert fitting._student_t_ppf(.975, 10) == pytest.approx(2.228, abs=0.0005) + assert fitting._student_t_ppf(.025, 10) == pytest.approx(-2.228, abs=0.0005) + # https://www.itl.nist.gov/div898/handbook/eda/section3/eda3674.htm + assert fitting._chi_square_cdf(18.307, 10) == pytest.approx(0.95, abs=2e-5) + assert fitting._chi_square_cdf(3.841, 1) == pytest.approx(0.95, abs=2e-5) + assert fitting._normal_cdf(1.959963984540054) == pytest.approx(.975, abs=2e-14) + assert fitting._normal_cdf(0) == .5 + assert fitting._normal_cdf(-20) == pytest.approx(0, abs=3e-89) + assert fitting._gamma_q(1, 5) == pytest.approx(math.exp(-5), rel=2e-13) + assert fitting._gamma_q(1, 0) == 1 + assert fitting._beta_i(.5, .5, .1) == pytest.approx(2 / math.pi * math.asin(math.sqrt(.1)), rel=2e-14) + assert fitting._beta_i(.5, .5, .9) == pytest.approx(2 / math.pi * math.asin(math.sqrt(.9)), rel=2e-14) + assert fitting._beta_i(1, 1, 0) == 0 + assert fitting._beta_i(1, 1, 1) == 1 + assert fitting._student_t_cdf(0, 8) == .5 + # Independent central Taylor coefficient: t-density at the origin. + # Using I(df/(df+t²)) here would round to 1 and return exactly 0.5. + df, tiny_t = 1000, 1e-8 + density_zero = math.exp(math.lgamma((df + 1) / 2) - math.lgamma(df / 2)) / math.sqrt(df * math.pi) + expected_cdf = 0.5 + density_zero * tiny_t + assert fitting._student_t_cdf(tiny_t, df) == pytest.approx(expected_cdf, abs=5e-15) + assert fitting._student_t_cdf(-tiny_t, df) == pytest.approx(1 - expected_cdf, abs=5e-15) + assert fitting._student_t_cdf(1e200, 10) == 1 + + +def test_welch_two_sided_p_and_chi_square_p(): + welch = _run("welch_t_test", {"sample_a": [1, 3, 5, 7], "sample_b": [2, 4, 6, 8]})["values"] + # Equal sample variance in this case: t = -sqrt(0.3), df = 6. + assert welch["t_statistic"] == pytest.approx(-math.sqrt(.3), rel=1e-14) + assert welch["degrees_of_freedom"] == pytest.approx(6, rel=1e-14) + assert welch["p_value"] == pytest.approx( + fitting._beta_i(3, .5, 6 / (6 + .3)), rel=1e-14 + ) + assert 0 < welch["p_value"] < 1 + chi = _run("chi_square_gof", {"observed": [24, 36, 40], "expected": [30, 30, 40]}) + assert chi["values"]["chi_square"] == pytest.approx(2.4, rel=1e-14) + assert chi["values"]["degrees_of_freedom"] == 2 + assert chi["values"]["p_value"] == pytest.approx(math.exp(-1.2), rel=1e-13) + assert sum(row[-1] for row in chi["table"]["rows"]) == pytest.approx(2.4) + + +@pytest.mark.parametrize("op,inputs", [ + ("weighted_linear_least_squares", {"predictors": [[1], [2]], "response": [2, 4], "weights": [1, 1]}), + ("weighted_linear_least_squares", {"predictors": [[1], [1], [1]], "response": [2, 4, 6], "weights": [1, 1, 1]}), + ("weighted_linear_least_squares", {"predictors": [[1], [2], [3]], "response": [2, 4, 6], "weights": [1, 0, 0]}), + ("weighted_linear_least_squares", {"predictors": [[1], [2], [3]], "response": [2, 4, 6], "weights": [1, -1, 1]}), + ("weighted_linear_least_squares", {"predictors": [[1], [2], [3]], "response": [2, 4], "weights": [1, 1, 1]}), + ("nonlinear_least_squares", {"model": "bogus", "x": [1, 2, 3], "y": [2, 4, 6], "weights": [1, 1, 1], "initial_parameters": [1, 2]}), + ("nonlinear_least_squares", {"model": "power_law", "x": [0, 1, 2], "y": [2, 3, 4], "weights": [1, 1, 1], "initial_parameters": [1, 2]}), + ("nonlinear_least_squares", {"model": "gaussian", "x": [1, 2, 3, 4, 5], "y": [1, 2, 4, 2, 1], "weights": [1] * 5, "initial_parameters": [1, 3, 2, 0]}), + ("nonlinear_least_squares", {"model": "mgh09", "x": [0, 1, 2, 3, 4], "y": [1, 2, 3, 4, 5], "weights": [1] * 5, "initial_parameters": [1, 2, 3]}), + ("nonlinear_least_squares", {"model": "polynomial", "x": [1, 2, 3], "y": [1, 2, 3], "weights": [1] * 3, "initial_parameters": [1, 1, 1]}), + ("welch_t_test", {"sample_a": [1], "sample_b": [1, 3]}), + ("welch_t_test", {"sample_a": [1, 1], "sample_b": [2, 2]}), + ("chi_square_gof", {"observed": [1, 2], "expected": [1, 1]}), + ("chi_square_gof", {"observed": [1, -1], "expected": [1, 1]}), + ("chi_square_gof", {"observed": [1.5, 2.5], "expected": [2, 2]}), + ("chi_square_gof", {"observed": [2, 2], "expected": [0, 4]}), + ("chi_square_gof", {"observed": [10], "expected": [10]}), + ("weighted_linear_least_squares", {"predictors": [[0], [1], [2]], "response": [0, 1, float("nan")], "weights": [1, 1, 1]}), +]) +def test_invalid_inputs_rejected_by_operation_and_shared_validator(op, inputs): + with pytest.raises(ValueError): + _run(op, inputs) + + +@pytest.mark.parametrize("function,args", [ + (fitting._gamma_q, (0, 1)), (fitting._gamma_q, (2, -1)), + (fitting._beta_i, (-1, 1, .5)), (fitting._beta_i, (1, 2, 1.1)), + (fitting._student_t_cdf, (1, 0)), (fitting._student_t_ppf, (1, 2)), +]) +def test_invalid_distribution_domains_are_rejected(function, args): + with pytest.raises(ValueError): + function(*args) + + +def test_weighted_linear_matches_independent_hand_calculation(): + # Fit y = 1 + 2*x with a nonzero noisy endpoint and one ignored row. + # All normal-equation sums below can be verified by hand. + result = _run("weighted_linear_least_squares", { + "predictors": [[-1], [0], [1], [2], [10]], + "response": [-1, 1, 3, 6, 1e5], "weights": [1, 1, 1, 1, 0], + }) + values = result["values"] + assert values["positive_weight_observations"] == 4 + assert values["degrees_of_freedom"] == 2 + assert values["coefficient_0"] == pytest.approx(1.1) + assert values["coefficient_1"] == pytest.approx(2.3) + assert values["residual_4"] == pytest.approx(1e5 - 24.1) + assert values["r_squared"] <= 1 + assert values["r_squared"] >= 0 + + +def test_constant_response_r_squared_undefined_and_singular_nonlinear_rejected(): + linear = _run("weighted_linear_least_squares", { + "predictors": [[0], [1], [2], [3]], + "response": [4, 4, 4, 4], "weights": [1] * 4, + }) + assert "r_squared" not in linear["values"] + with pytest.raises(ValueError, match="rank deficient|unidentifiable"): + _run("nonlinear_least_squares", { + "model": "polynomial", "x": [1, 1, 1, 1], + "y": [1, 2, 3, 4], "weights": [1] * 4, + "initial_parameters": [0, 0], + }) + + +def test_float_underflow_is_rejected_not_silently_rounded_to_zero(): + from decimal import Decimal + with pytest.raises(ValueError, match="numeric range"): + fitting._as_float(Decimal("1e-500"), "Tiny covariance") diff --git a/backend/tests/test_scientific_fitting_nist.json b/backend/tests/test_scientific_fitting_nist.json new file mode 100644 index 00000000..ce275835 --- /dev/null +++ b/backend/tests/test_scientific_fitting_nist.json @@ -0,0 +1,55 @@ +{ + "source": "https://www.itl.nist.gov/div898/strd/", + "longley": { + "data_y_x1_x2_x3_x4_x5_x6": [ + [60323,83.0,234289,2356,1590,107608,1947], + [61122,88.5,259426,2325,1456,108632,1948], + [60171,88.2,258054,3682,1616,109773,1949], + [61187,89.5,284599,3351,1650,110929,1950], + [63221,96.2,328975,2099,3099,112075,1951], + [63639,98.1,346999,1932,3594,113270,1952], + [64989,99.0,365385,1870,3547,115094,1953], + [63761,100.0,363112,3578,3350,116219,1954], + [66019,101.2,397469,2904,3048,117388,1955], + [67857,104.6,419180,2822,2857,118734,1956], + [68169,108.4,442769,2936,2798,120445,1957], + [66513,110.8,444546,4681,2637,121950,1958], + [68655,112.6,482704,3813,2552,123366,1959], + [69564,114.2,502601,3931,2514,125368,1960], + [69331,115.7,518173,4806,2572,127852,1961], + [70551,116.9,554894,4007,2827,130081,1962] + ], + "coefficients": [-3482258.63459582,15.0618722713733,-0.0358191792925910,-2.02022980381683,-1.03322686717359,-0.0511041056535807,1829.15146461355], + "standard_errors": [890420.383607373,84.9149257747669,0.0334910077722432,0.488399681651699,0.214274163161675,0.226073200069370,455.478499142212], + "residual_standard_deviation": 304.854073561965, + "r_squared": 0.995479004577296, + "digits": 15 + }, + "misra1a": { + "model": "saturating_exponential", + "data_y_x": [[10.07,77.6],[14.73,114.9],[17.94,141.1],[23.93,190.8],[29.61,239.9],[35.18,289.0],[40.02,332.8],[44.82,378.4],[50.76,434.8],[55.05,477.3],[61.01,536.8],[66.40,593.1],[75.47,689.1],[81.78,760.0]], + "starts": [[500,0.0001],[250,0.0005]], + "parameters": [238.94212918,0.00055015643181], + "standard_errors": [2.7070075241,0.0000072668688436], + "residual_sum_squares": 0.12455138894, + "digits": 11 + }, + "thurber": { + "model": "thurber", + "data_y_x": [[80.574,-3.067],[84.248,-2.981],[87.264,-2.921],[87.195,-2.912],[89.076,-2.840],[89.608,-2.797],[89.868,-2.702],[90.101,-2.699],[92.405,-2.633],[95.854,-2.481],[100.696,-2.363],[101.060,-2.322],[401.672,-1.501],[390.724,-1.460],[567.534,-1.274],[635.316,-1.212],[733.054,-1.100],[759.087,-1.046],[894.206,-0.915],[990.785,-0.714],[1090.109,-0.566],[1080.914,-0.545],[1122.643,-0.400],[1178.351,-0.309],[1260.531,-0.109],[1273.514,-0.103],[1288.339,0.010],[1327.543,0.119],[1353.863,0.377],[1414.509,0.790],[1425.208,0.963],[1421.384,1.006],[1442.962,1.115],[1464.350,1.572],[1468.705,1.841],[1447.894,2.047],[1457.628,2.200]], + "starts": [[1000,1000,400,40,0.7,0.3,0.03],[1300,1500,500,75,1,0.4,0.05]], + "parameters": [1288.1396800,1491.0792535,583.23836877,75.416644291,0.96629502864,0.39797285797,0.049727297349], + "standard_errors": [4.6647963344,39.571156086,28.698696102,5.5675370270,0.031333340687,0.014984928198,0.0065842344623], + "residual_sum_squares": 5642.7082397, + "digits": 11 + }, + "mgh09": { + "model": "mgh09", + "data_y_x": [[0.1957,4.0],[0.1947,2.0],[0.1735,1.0],[0.1600,0.5],[0.0844,0.25],[0.0627,0.167],[0.0456,0.125],[0.0342,0.1],[0.0323,0.0833],[0.0235,0.0714],[0.0246,0.0625]], + "starts": [[25,39,41.5,39],[0.25,0.39,0.415,0.39]], + "parameters": [0.19280693458,0.19128232873,0.12305650693,0.13606233068], + "standard_errors": [0.011435312227,0.19633220911,0.080842031232,0.090025542308], + "residual_sum_squares": 0.00030750560385, + "digits": 11 + } +} diff --git a/docs/SCIENTIFIC_FITTING_REFERENCE.md b/docs/SCIENTIFIC_FITTING_REFERENCE.md new file mode 100644 index 00000000..1194376c --- /dev/null +++ b/docs/SCIENTIFIC_FITTING_REFERENCE.md @@ -0,0 +1,77 @@ +# Scientific Fitting and Inference: quantitative reference + +The **Fitting and Inference** pack is a standalone Scientific Workbench plugin (`science_fitting`). Enable it in **Settings → Plugins**, then choose **Plugins → Scientific Workbench → Fitting and Inference**. It uses only Python's standard library, runs locally, requires `graph.read` and `graph.mutate` grants, and uses the existing version **1.1.0** Scientific Workbench result and receipt protocol. The operation catalog and worked examples are available from the enabled plugin. The host validates exact field names, finite measurements, numeric dimensions and immutable source citations before calculation; failed runs do not overwrite the last successful result. + +All measurements use the caller's consistent units. Quantitative answers are conditional on the stated statistical model and data collection assumptions. An exact p-value or numerical confidence interval is **not** evidence that those assumptions hold. + +## Weighted linear least squares (`weighted_linear_least_squares`) + +Inputs: `predictors` is an *n × k* rectangular matrix (one observation per row), `response` contains *n* values, and `weights` contains *n* nonnegative **relative inverse-variance weights**. A constant intercept is added implicitly: the coefficient vector has *p = k + 1* elements, indexed `0` through `k`. Up to 15 supplied predictors are accepted. The design matrix must have full column rank and more positive-weight rows than parameters; zero-weight rows do not contribute to the fit or its residual degrees of freedom. For unweighted least squares, use all weights equal to 1. + +With *W = diag(w)*, solve + +\[\hat\beta = (X^\mathsf{T} W X)^{-1} X^\mathsf{T}Wy,\quad r=y-X\hat\beta,\quad S=\sum_i w_i r_i^2.\] + +The implementation evaluates and equilibrates the normal equations in **76-digit decimal arithmetic**, followed by pivoted elimination. That avoids the ordinary binary64 loss of precision from squaring the condition number for the tested inputs, but does **not** make a nearly unidentifiable design statistically meaningful. Rank-deficient and zero-information designs are rejected; there is no coefficient regularization or automatic predictor selection. Inputs are decimalized from the normalized, finite numbers in the shared workbench validator. Very extreme scales may still exceed finite output range. + +Let *n₊* denote rows with positive weights, *ν = n₊ − p*, and *s² = S/ν*. The estimated **coefficient covariance matrix** is *s²(XᵀWX)⁻¹*; `standard_error_j = sqrt(covariance[j,j])`. Thus a common scale factor applied to all weights does not change estimates or their standard errors. This assumes the weight ratios are proportional to inverse observation variances and estimates the unknown common noise scale from residuals. These are **not** known-variance standard errors. `r_squared = 1 − S/Σwᵢ(yᵢ−ȳw)²` uses a weighted, centered total sum of squares and is omitted if the response is constant (undefined denominator). The operation returns coefficient and error scalars, a covariance **table** (`parameter`, `beta_0`, ...), each `residual_i` scalar, and the ordered residual trace as a **plot**. `weighted_residual_sum_squares`, `reduced_chi_square` and `residual_standard_deviation` are also reported. Reduced chi-square is an estimated weighted residual variance; its reference value is not expected to be 1 when weights are only relative. + +Do not interpret the fit causally. Correlated errors, omitted variables, nonlinear responses, outliers, highly correlated predictors and incorrectly specified weight ratios invalidate or distort conventional uncertainty estimates. + +## Nonlinear Levenberg–Marquardt (`nonlinear_least_squares`) + +Inputs: `model`, `x`, `y`, `weights` (one per paired observation), and `initial_parameters` (in the exact order below). Use **positive** or **zero** weights with more positive-weight points than unknown parameters. The objective is *S(β) = Σᵢwᵢ[yᵢ − f(xᵢ,β)]²*. Each model provides analytic derivatives. The solver constructs *JᵀWJ* and *JᵀWr* using 76-digit decimal arithmetic, and solves the diagonally damped and column-equilibrated LM system with pivoted elimination: + +\[(J^\mathsf{T}WJ + \lambda\operatorname{diag}(J^\mathsf{T}WJ))\Delta\beta = J^\mathsf{T}Wr.\] + +Candidate steps that fail to reduce the weighted objective are rejected and damping increases; accepted steps reduce damping. A small-step/high-precision objective-reduction criterion or a sufficiently small rejected step stops the iterations. At most **1,200** outer iterations and 55 damping trials per iteration are allowed. A failed, singular or non-convergent fit produces a validation error, **not** a misleading success artifact. Diagnostics: `converged`, `iterations`, `accepted_steps`, `rejected_steps`, `final_damping`, `gradient_infinity_norm`, weighted residual sum of squares, reduced chi-square, and residual standard deviation. + +| Model name | Model equation | Starting parameter order / restrictions | +| --- | --- | --- | +| `exponential` | *a exp(bx) + c* | `[a, b, c]` (amplitude, rate, baseline) | +| `saturating_exponential` | *a [1 − exp(−bx)]* | `[a, b]`; NIST Misra1a equation | +| `power_law` | *a xᵇ* | `[a, b]`; **all x must be strictly positive** | +| `gaussian` | *c + a exp(−(x−μ)²/(2σ²))* | `[c, a, μ, σ]`; σ must be nonzero (sign is not identifiable, so choose positive σ) | +| `polynomial` | *Σⱼβⱼxʲ* | `[β₀, β₁, ...]` in ascending power order; 1–12 parameters | +| `thurber` | *(β₁+β₂x+β₃x²+β₄x³)/(1+β₅x+β₆x²+β₇x³)* | Seven parameters; NIST StRD rational cubic/cubic | +| `mgh09` | *β₁(x²+β₂x)/(x²+β₃x+β₄)* | Four parameters; NIST StRD rational model | + +The strings are case-insensitive. The two rational models are included because the specified NIST StRD certification cases **cannot** be represented by the other four model families. Rational denominators equal to zero at observed points are rejected for that trial. Models are not arbitrary Python expressions; no expression evaluator, network access or arbitrary code execution is involved. + +At convergence, the local linearized covariance estimate is *C ≈ [S/(n₊−p)] (JᵀWJ)⁻¹*. Each `standard_error_j` is `sqrt(C[j,j])`; `ci95_lower_j` and `ci95_upper_j` equal *β̂ⱼ ± t₀.₉₇₅,ν × standard_error_j*. The fitted parameter table and residual plot are included in the artifact. **These are approximate local Wald confidence intervals**, not profile-likelihood intervals, bootstrap intervals, simultaneous intervals, or rigorous coverage guarantees for nonlinear or non-Gaussian data. Strong correlations, boundary parameters, non-identifiability, heteroscedasticity, narrow samples and nonnormal errors can render them unreliable. Reduced chi-square assumes inverse-variance weighting and a valid model. LM is a **local** method sensitive to starting parameters; failure to find a global minimum must not be reported as a verified global optimum. For polynomial fits, the linear solver is usually preferable. + +## Welch two-sample t test (`welch_t_test`) + +Inputs: two independent numeric samples, each of size at least 2; unequal population variances are allowed. Sample means and unbiased sample variances (*s₁²*, *s₂²*, with divisors *n−1*) give + +\[t=\frac{\bar x_1-\bar x_2}{\sqrt{s_1^2/n_1+s_2^2/n_2}},\quad +\nu=\frac{(v_1+v_2)^2}{v_1^2/(n_1-1)+v_2^2/(n_2-1)},\quad v_j=s_j^2/n_j.\] + +The **two-sided** p-value is *I_{ν/(ν+t²)}(ν/2, 1/2)*, where *I* is the regularized incomplete beta function. Degrees of freedom use the Welch–Satterthwaite approximation and need not be integers. If both samples have zero variance, the test is undefined and rejected. Population independence and a meaningful sample distribution approximation are necessary; the pack does not perform pairing, multiple-test correction, normality tests or effect-size adjustment. `t_statistic`, `degrees_of_freedom`, `p_value`, means and sample sizes are reported. + +## Pearson chi-square goodness of fit (`chi_square_gof`) + +Inputs: matched vectors of at least two categories, `observed` **nonnegative integer counts** and `expected` **strictly positive** expected frequencies. Expected totals must equal observed totals (within 1e−12 relative or 1e−10 absolute rounding tolerance). The plugin **never silently normalizes** probabilities, so expected frequencies must be supplied as frequencies, not probabilities. Expected frequencies are assumed specified **before** observing the sample, with no fitted nuisance parameters. The statistic is *χ² = Σ(Oᵢ−Eᵢ)²/Eᵢ*, degrees of freedom are *k−1*, and the **upper-tail** p-value is the regularized incomplete gamma *Q((k−1)/2, χ²/2)*. The result includes category contributions and `expected_count_below_5` as a validity warning. The usual asymptotic chi-square approximation can be poor when expected counts are small (commonly, below 5), observations are dependent, or parameters were estimated from the data. Bin merging and adjustment of degrees of freedom must be performed deliberately outside this operation. + +## Numerical probability functions + +`_normal_cdf(x)` uses `math.erfc` rather than subtracting nearly equal probabilities in the tails. Student *t* probabilities and quantiles use a **regularized incomplete beta** calculation with a modified-Lentz continued fraction and symmetry transformations, plus monotone bisection for the critical *t* quantile. The chi-square survival function uses **regularized upper incomplete gamma**: a convergent power series below *x < a+1* (with `expm1` complement evaluation) and a continued fraction otherwise. `math.lgamma` supplies logarithmic normalization to reduce overflow and underflow. The functions have explicit domain checks, finite iteration limits, and may correctly return **0** for tails too small for binary64. All reported p-values are bounded to `[0,1]`; **no** external numerical libraries (`numpy`, `scipy`) are imported. A p-value is a probability of data at least as extreme under the null model, not the probability the null model is true. + +## Certified tests and reproducibility + +The independent numerical oracles live in `backend/tests/test_scientific_fitting_nist.json`, with certification assertions and adversarial cases in `backend/tests/test_scientific_fitting.py`. The data rows, both prescribed starting vectors and published certified coefficients/standard errors are taken from the NIST StRD ASCII datasets, not generated by the implementation under test. Assertions compare all **15 published significant digits** for the Longley linear estimates/standard errors and all **11 published significant digits** for Misra1a, Thurber and MGH09 estimates/standard errors (from *both* starts), along with residual diagnostics. This is a certification against those inputs, **not** a guarantee of arbitrary input accuracy. Other tests cover synthetic exponential, power-law, Gaussian and polynomial data, analytic Jacobians, exact distribution identities, NIST published Student-t and chi-square critical values, invalid domains and workbench receipt tampering. The existing scientific test suites are unchanged. + +Official reference inputs and results: + +- [NIST Longley ASCII data](https://www.itl.nist.gov/div898/strd/lls/data/LINKS/DATA/Longley.dat) and [certified results](https://www.itl.nist.gov/div898/strd/lls/data/LINKS/v-Longley.shtml). +- [NIST Misra1a ASCII data](https://www.itl.nist.gov/div898/strd/nls/data/LINKS/DATA/Misra1a.dat), [NIST Thurber ASCII data](https://www.itl.nist.gov/div898/strd/nls/data/LINKS/DATA/Thurber.dat), and [NIST MGH09 ASCII data](https://www.itl.nist.gov/div898/strd/nls/data/LINKS/DATA/MGH09.dat). +- [NIST Student-t critical values](https://www.itl.nist.gov/div898/handbook/eda/section3/eda3672.htm) and [chi-square critical values](https://www.itl.nist.gov/div898/handbook/eda/section3/eda3674.htm). + +From a complete checkout with test dependencies installed, run: + +```sh +python -m pytest -n0 backend/tests/test_scientific_fitting.py +python -m pytest -n0 backend/tests/test_scientific*.py tests/test_scientific*.py +``` + +Result artifacts and receipts are part of the existing Scientific Workbench graph node; their hashes include the pack ID, operation ID, validated input fingerprint, pack version and output. A separate receipt hash covers UTC time and input provenance. Export JSON preserves those canonical measurements and hashes for later verification. diff --git a/graphlink_plugins/scientific/catalog.py b/graphlink_plugins/scientific/catalog.py index 02a9ca8a..b321c79d 100644 --- a/graphlink_plugins/scientific/catalog.py +++ b/graphlink_plugins/scientific/catalog.py @@ -17,6 +17,7 @@ "environment": ("Environmental Science", "Calculate flow-weighted concentrations, runoff and growing degree days."), "materials": ("Materials Science", "Analyze measured density, tensile response and apparent porosity."), "signals": ("Signal Processing", "Smooth, transform and resample measured signals."), + "fitting": ("Fitting and Inference", "Weighted and nonlinear fits, Welch tests and chi-square goodness-of-fit."), } diff --git a/graphlink_plugins/scientific/packs/fitting.py b/graphlink_plugins/scientific/packs/fitting.py new file mode 100644 index 00000000..353477d2 --- /dev/null +++ b/graphlink_plugins/scientific/packs/fitting.py @@ -0,0 +1,525 @@ +"""Reproducible least-squares fits and frequentist tests, without external solvers.""" + +from __future__ import annotations + +import math +import statistics +from decimal import Decimal, InvalidOperation, localcontext + +from graphlink_plugins.scientific.core import Field, Operation + +# Working precision protects strongly correlated regressors (NIST Longley) and +# the covariance/uncertainty calculation after nonlinear convergence. +_PRECISION = 76 +_PIVOT_FLOOR = Decimal("1e-36") + + +def _d(value): + # Scientific inputs arrive as validated binary64. str(float) recovers the + # decimal measurements entered by the user, including the NIST data. + return Decimal(str(value)) + + +def _as_float(value, description): + try: + result = float(value) + except (OverflowError, ValueError): + raise ValueError(f"{description} is outside the supported numeric range.") from None + if not math.isfinite(result) or (value != 0 and result == 0): + raise ValueError(f"{description} is outside the supported numeric range.") + return result + + +def _normal_solve(gram, rhs, *, inverse=False): + """Equilibrated, pivoted Gauss-Jordan solve; optionally recover G inverse. + + Normal equations are evaluated in high-precision decimal, *not* in + binary64. Scaling by sqrt(G_jj) prevents differing parameter units from + deciding which pivot is numerically detectable. + """ + p = len(rhs) + scales = [gram[j][j].sqrt() for j in range(p)] + if any(v <= 0 for v in scales): + raise ValueError("The fit has a non-identifiable parameter (zero derivative).") + rows = [ + [gram[i][j] / (scales[i] * scales[j]) for j in range(p)] + + [rhs[i] / scales[i]] + + ([Decimal(int(i == j)) for j in range(p)] if inverse else []) + for i in range(p) + ] + for k in range(p): + pivot = max(range(k, p), key=lambda i: abs(rows[i][k])) + if abs(rows[pivot][k]) < _PIVOT_FLOOR: + raise ValueError("The fit is rank deficient or numerically unidentifiable.") + rows[pivot], rows[k] = rows[k], rows[pivot] + divisor = rows[k][k] + rows[k] = [element / divisor for element in rows[k]] + for i in range(p): + if i == k: + continue + factor = rows[i][k] + if factor: + rows[i] = [a - factor * b for a, b in zip(rows[i], rows[k])] + solution = [rows[i][p] / scales[i] for i in range(p)] + if not inverse: + return solution + covariance_base = [[rows[i][p + 1 + j] / (scales[i] * scales[j]) for j in range(p)] for i in range(p)] + # Use the symmetric estimate to suppress insignificant elimination asymmetry. + covariance_base = [[(covariance_base[i][j] + covariance_base[j][i]) / 2 for j in range(p)] for i in range(p)] + return solution, covariance_base + + +def _linear(data): + matrix, y, weights = data["predictors"], data["response"], data["weights"] + n = len(y) + if len(matrix) != n or len(weights) != n: + raise ValueError("Provide one predictor row, response and weight per observation.") + p = len(matrix[0]) + 1 + if p > 16: + raise ValueError("At most 15 predictors plus an intercept are supported.") + if any(w < 0 for w in weights): + raise ValueError("Least-squares weights must be nonnegative.") + positive = sum(w > 0 for w in weights) + if positive <= p: + raise ValueError("More positive-weight observations than fitted parameters are required.") + try: + with localcontext() as context: + context.prec = _PRECISION + x = [[Decimal(1)] + list(map(_d, row)) for row in matrix] + ys, ws = list(map(_d, y)), list(map(_d, weights)) + gram = [[sum((w * row[i] * row[j] for row, w in zip(x, ws)), Decimal(0)) + for j in range(p)] for i in range(p)] + rhs = [sum((w * row[i] * yy for row, yy, w in zip(x, ys, ws)), Decimal(0)) for i in range(p)] + beta, inverse = _normal_solve(gram, rhs, inverse=True) + residuals = [yy - sum((v * b for v, b in zip(row, beta)), Decimal(0)) + for row, yy in zip(x, ys)] + sse = sum((w * r * r for w, r in zip(ws, residuals)), Decimal(0)) + dof = positive - p + reduced = sse / dof + covariance = [[reduced * value for value in row] for row in inverse] + errors = [max(covariance[j][j], Decimal(0)).sqrt() for j in range(p)] + mean = sum((w * yy for w, yy in zip(ws, ys)), Decimal(0)) / sum(ws) + total = sum((w * (yy - mean) ** 2 for yy, w in zip(ys, ws)), Decimal(0)) + values = { + "observations": n, "positive_weight_observations": positive, + "parameters": p, "degrees_of_freedom": dof, + "weighted_residual_sum_squares": _as_float(sse, "Weighted residual sum of squares"), + "reduced_chi_square": _as_float(reduced, "Reduced chi-square"), + "residual_standard_deviation": _as_float(reduced.sqrt(), "Residual standard deviation"), + } + if total: + values["r_squared"] = _as_float(Decimal(1) - sse / total, "R squared") + for i, (value, error) in enumerate(zip(beta, errors)): + values[f"coefficient_{i}"] = _as_float(value, "Coefficient") + values[f"standard_error_{i}"] = _as_float(error, "Standard error") + for i, residual in enumerate(residuals): + values[f"residual_{i}"] = _as_float(residual, "Residual") + return { + "summary": "Weighted linear least squares with an intercept; weights are relative inverse variances. " + "Covariance is scaled by weighted residual sum of squares / residual degrees of freedom.", + "values": values, + "table": {"columns": ["parameter"] + [f"beta_{i}" for i in range(p)], + "rows": [[f"beta_{i}"] + [_as_float(v, "Covariance") for v in row] + for i, row in enumerate(covariance)]}, + "plot": {"title": "Weighted linear fit residuals", "xLabel": "Observation index (zero-based)", + "yLabel": "Observed minus fitted", "x": list(range(n)), + "y": [_as_float(r, "Residual") for r in residuals]}, + } + except (InvalidOperation, OverflowError, ZeroDivisionError): + raise ValueError("The regression exceeds the supported numerical range.") from None + + +def _model(name, x, b): + """Return model value and its analytic derivative w.r.t. parameters.""" + one = Decimal(1) + if name == "exponential": # a exp(b x) + c + a, rate, baseline = b + e = (rate * x).exp() + return a * e + baseline, [e, a * x * e, one] + if name == "saturating_exponential": # NIST Misra1a + a, rate = b + e = (-rate * x).exp() + return a * (one - e), [one - e, a * x * e] + if name == "power_law": # a x^b, x positive + if x <= 0: + raise ValueError("Power-law fitting requires strictly positive x values.") + a, exponent = b + lx = x.ln() + power = (exponent * lx).exp() + return a * power, [power, a * power * lx] + if name == "gaussian": # baseline + amplitude exp(-(x-center)^2/(2 width^2)) + baseline, amplitude, center, width = b + if not width: + raise ValueError("Gaussian width must be nonzero.") + z = (x - center) / width + e = (-z * z / 2).exp() + f = baseline + amplitude * e + return f, [one, e, amplitude * e * z / width, amplitude * e * z * z / width] + if name == "polynomial": + terms = [one] + for _ in range(1, len(b)): + terms.append(terms[-1] * x) + return sum((v * t for v, t in zip(b, terms)), Decimal(0)), terms + if name == "thurber": # NIST rational cubic / cubic + powers = [one, x, x * x, x * x * x] + numerator = sum((b[j] * powers[j] for j in range(4)), Decimal(0)) + denominator = one + sum((b[j + 3] * powers[j] for j in range(1, 4)), Decimal(0)) + if not denominator: + raise ValueError("Rational denominator is zero at an observation.") + f = numerator / denominator + return f, [v / denominator for v in powers] + [-f * v / denominator for v in powers[1:]] + if name == "mgh09": # NIST Kowalik-Osborne rational model + xx = x * x + denominator = xx + x * b[2] + b[3] + if not denominator: + raise ValueError("Rational denominator is zero at an observation.") + numerator = xx + x * b[1] + f = b[0] * numerator / denominator + return f, [numerator / denominator, b[0] * x / denominator, + -f * x / denominator, -f / denominator] + raise ValueError("Unknown nonlinear fitting model.") + + +_MODEL_PARAMS = {"exponential": 3, "saturating_exponential": 2, "power_law": 2, + "gaussian": 4, "thurber": 7, "mgh09": 4} + + +def _objective(model, x, y, w, b, *, jacobian=False): + predictions, derivatives = [], [] + for xx in x: + prediction, derivative = _model(model, xx, b) + predictions.append(prediction) + if jacobian: + derivatives.append(derivative) + residuals = [yy - prediction for yy, prediction in zip(y, predictions)] + sse = sum((ww * r * r for ww, r in zip(w, residuals)), Decimal(0)) + if not jacobian: + return sse + p = len(b) + gram = [[sum((ww * row[i] * row[j] for ww, row in zip(w, derivatives)), Decimal(0)) + for j in range(p)] for i in range(p)] + grad = [sum((ww * row[i] * r for ww, row, r in zip(w, derivatives, residuals)), Decimal(0)) + for i in range(p)] + return sse, gram, grad, residuals + + +def _nonlinear(data): + model = data["model"].strip().lower() + initial = data["initial_parameters"] + p = len(initial) + if model not in _MODEL_PARAMS and model != "polynomial": + raise ValueError("Choose exponential, saturating_exponential, power_law, gaussian, polynomial, thurber or mgh09.") + if (model in _MODEL_PARAMS and p != _MODEL_PARAMS[model]) or (model == "polynomial" and not 1 <= p <= 12): + raise ValueError("The initial parameter count does not match the selected model.") + xs, ys, weights = data["x"], data["y"], data["weights"] + n = len(xs) + if n != len(ys) or n != len(weights): + raise ValueError("Provide equally many x, y and weight observations.") + if any(w < 0 for w in weights): + raise ValueError("Least-squares weights must be nonnegative.") + positive = sum(w > 0 for w in weights) + if positive <= p: + raise ValueError("More positive-weight observations than parameters are required.") + if model == "power_law" and any(x <= 0 for x in xs): + raise ValueError("Power-law fitting requires strictly positive x values.") + if model == "gaussian" and initial[3] == 0: + raise ValueError("Gaussian width must be nonzero.") + try: + with localcontext() as context: + context.prec = _PRECISION + x, y, w, beta = list(map(_d, xs)), list(map(_d, ys)), list(map(_d, weights)), list(map(_d, initial)) + damping = Decimal("0.001") + accepted = rejected = 0 + converged = False + for iteration in range(1, 1201): + sse, gram, grad, residuals = _objective(model, x, y, w, beta, jacobian=True) + # Stop only when the predicted change is negligible at a + # precision much higher than the certified 10-11 digits. + step = None + next_sse = None + for _ in range(55): + modified = [row.copy() for row in gram] + for j in range(p): + modified[j][j] += damping * max(gram[j][j], Decimal("1e-70")) + try: + step = _normal_solve(modified, grad) + candidate = [b + db for b, db in zip(beta, step)] + next_sse = _objective(model, x, y, w, candidate) + except (ValueError, InvalidOperation, OverflowError, ZeroDivisionError): + next_sse = None + if next_sse is not None and next_sse < sse: + break + rejected += 1 + damping *= 10 + else: + # If no decrease is representable even with high working + # precision, this is convergence only for a tiny step. + if step is not None and max(abs(db) / max(abs(b), Decimal(1)) + for b, db in zip(beta, step)) < Decimal("1e-22"): + converged = True + break + raise ValueError("Levenberg–Marquardt failed to find a decreasing step.") + accepted += 1 + relative_step = max(abs(db) / max(abs(b), Decimal(1)) for b, db in zip(beta, step)) + relative_improvement = (sse - next_sse) / max(sse, Decimal(1)) + beta = candidate + damping = max(damping / 3, Decimal("1e-35")) + if relative_step < Decimal("1e-21") and relative_improvement < Decimal("1e-30"): + converged = True + break + if not converged: + raise ValueError("Levenberg–Marquardt did not converge within 1200 iterations.") + sse, gram, grad, residuals = _objective(model, x, y, w, beta, jacobian=True) + _, inverse = _normal_solve(gram, [Decimal(0)] * p, inverse=True) + dof = positive - p + reduced = sse / dof + errors = [(max(inverse[j][j] * reduced, Decimal(0))).sqrt() for j in range(p)] + # Local linearized Wald intervals use Student t for the residual + # degrees of freedom, not a large-sample Gaussian quantile. + critical95 = _d(_student_t_ppf(0.975, dof)) + values = { + "observations": n, "parameters": p, "degrees_of_freedom": dof, + "iterations": iteration, "accepted_steps": accepted, "rejected_steps": rejected, + "converged": "true", "final_damping": _as_float(damping, "Damping"), + "weighted_residual_sum_squares": _as_float(sse, "Residual sum of squares"), + "reduced_chi_square": _as_float(reduced, "Reduced chi-square"), + "residual_standard_deviation": _as_float(reduced.sqrt(), "Residual standard deviation"), + "gradient_infinity_norm": _as_float(max(map(abs, grad)), "Gradient"), + } + rows = [] + for j, (b, error) in enumerate(zip(beta, errors)): + values[f"parameter_{j}"] = _as_float(b, "Parameter") + values[f"standard_error_{j}"] = _as_float(error, "Standard error") + low, high = b - critical95 * error, b + critical95 * error + values[f"ci95_lower_{j}"] = _as_float(low, "Confidence limit") + values[f"ci95_upper_{j}"] = _as_float(high, "Confidence limit") + rows.append([f"beta_{j}", values[f"parameter_{j}"], values[f"standard_error_{j}"], + values[f"ci95_lower_{j}"], values[f"ci95_upper_{j}"]]) + return { + "summary": f"Levenberg–Marquardt {model} fit converged in {iteration} iterations. " + "95% intervals use the local linearized covariance and Student t quantile.", + "values": values, + "table": {"columns": ["parameter", "estimate", "standard error", "95% lower", "95% upper"], "rows": rows}, + "plot": {"title": "Nonlinear fit residuals", "xLabel": "Predictor x", "yLabel": "Observed minus fitted", + "x": xs, "y": [_as_float(r, "Residual") for r in residuals]}, + } + except (InvalidOperation, OverflowError, ZeroDivisionError): + raise ValueError("The nonlinear fit exceeds the supported numerical range.") from None + + +def _gamma_q(shape, x): + """Regularized upper incomplete gamma, with series/continued fractions.""" + if not math.isfinite(shape) or not math.isfinite(x) or shape <= 0 or x < 0: + raise ValueError("Gamma distribution requires positive shape and nonnegative argument.") + if x == 0: + return 1.0 + pref_log = shape * math.log(x) - x - math.lgamma(shape) + epsilon = 4e-15 + if x < shape + 1: + term = total = 1.0 / shape + for k in range(1, 10001): + term *= x / (shape + k) + total += term + if abs(term) <= abs(total) * epsilon: + result_log = pref_log + math.log(total) + return max(0.0, min(1.0, -math.expm1(min(0.0, result_log)))) + else: + tiny = 1e-300 + b = x + 1 - shape + c = 1 / tiny + d = 1 / (b if abs(b) > tiny else tiny) + h = d + for k in range(1, 10001): + a = -k * (k - shape) + b += 2 + d = a * d + b + if abs(d) < tiny: + d = tiny + c = b + a / c + if abs(c) < tiny: + c = tiny + d = 1 / d + factor = d * c + h *= factor + if abs(factor - 1) <= epsilon: + return max(0.0, min(1.0, math.exp(pref_log) * h)) + raise ValueError("The incomplete gamma computation did not converge.") + + +def _beta_cf(a, b, x): + """Modified Lentz continued fraction for incomplete beta.""" + tiny = 1e-300 + c, d = 1.0, 1.0 - (a + b) * x / (a + 1) + if abs(d) < tiny: + d = tiny + d = 1 / d + h = d + for m in range(1, 10001): + aa = m * (b - m) * x / ((a + 2 * m - 1) * (a + 2 * m)) + d = 1 + aa * d + if abs(d) < tiny: + d = tiny + c = 1 + aa / c + if abs(c) < tiny: + c = tiny + d = 1 / d + h *= d * c + aa = -(a + m) * (a + b + m) * x / ((a + 2 * m) * (a + 2 * m + 1)) + d = 1 + aa * d + if abs(d) < tiny: + d = tiny + c = 1 + aa / c + if abs(c) < tiny: + c = tiny + d = 1 / d + factor = d * c + h *= factor + if abs(factor - 1) < 4e-15: + return h + raise ValueError("The incomplete beta computation did not converge.") + + +def _beta_i(a, b, x): + if not all(math.isfinite(v) for v in (a, b, x)) or a <= 0 or b <= 0 or not 0 <= x <= 1: + raise ValueError("Incomplete beta requires positive shapes and x in [0, 1].") + if x == 0: + return 0.0 + if x == 1: + return 1.0 + if x > (a + 1) / (a + b + 2): + return max(0.0, min(1.0, 1 - _beta_i(b, a, 1 - x))) + front = math.exp(math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + + a * math.log(x) + b * math.log1p(-x)) + return max(0.0, min(1.0, front * _beta_cf(a, b, x) / a)) + + +def _normal_cdf(x): + return math.erfc(-x / math.sqrt(2)) / 2 + + +def _student_t_cdf(t, df): + if not math.isfinite(t) or not math.isfinite(df) or df <= 0: + raise ValueError("Student t distribution requires finite t and positive degrees of freedom.") + # Near t=0, df/(df+t*t) rounds to 1 and destroys all digits + # of the central probability. Evaluate the complementary beta + # parameterization directly rather than subtracting nearly equal values. + if abs(t) <= 1: + x = t * t / (df + t * t) + half = _beta_i(0.5, df / 2, x) / 2 + return 0.5 - half if t < 0 else 0.5 + half + x = (df / (df + t * t)) if math.isfinite(t * t) else 0.0 + half = _beta_i(df / 2, 0.5, x) / 2 + return half if t < 0 else 1 - half + + +def _student_t_ppf(probability, df): + """Monotone inversion of the stable t CDF for two-sided intervals.""" + if not 0 < probability < 1 or not math.isfinite(df) or df <= 0: + raise ValueError("A Student t quantile needs probability in (0, 1) and positive df.") + if probability == 0.5: + return 0.0 + if probability < 0.5: + return -_student_t_ppf(1 - probability, df) + lo, hi = 0.0, 1.0 + while _student_t_cdf(hi, df) < probability: + hi *= 2 + if hi > 1e150: + raise ValueError("Student t quantile exceeds the supported range.") + for _ in range(90): + midpoint = (lo + hi) / 2 + if _student_t_cdf(midpoint, df) < probability: + lo = midpoint + else: + hi = midpoint + return (lo + hi) / 2 + + +def _chi_square_cdf(x, df): + return 1 - _gamma_q(df / 2, x / 2) + + +def _welch(data): + a, b = data["sample_a"], data["sample_b"] + if len(a) < 2 or len(b) < 2: + raise ValueError("Welch's test requires at least two observations in each sample.") + mean_a, mean_b = statistics.mean(a), statistics.mean(b) + v_a = statistics.variance(a) / len(a) + v_b = statistics.variance(b) / len(b) + scale = v_a + v_b + if scale <= 0 or not math.isfinite(scale): + raise ValueError("Welch's test needs at least one sample with positive variance.") + t = (mean_a - mean_b) / math.sqrt(scale) + if not math.isfinite(t): + raise ValueError("The test statistic exceeds the supported numeric range.") + # Normalized variance contributions avoid underflow of (small variance)^2. + wa, wb = v_a / scale, v_b / scale + df = 1 / (wa * wa / (len(a) - 1) + wb * wb / (len(b) - 1)) + if not math.isfinite(df) or df <= 0: + raise ValueError("Welch degrees of freedom cannot be evaluated for these samples.") + p = (1 - _beta_i(0.5, df / 2, t * t / (df + t * t))) if abs(t) <= 1 else ( + _beta_i(df / 2, 0.5, df / (df + t * t)) if math.isfinite(t * t) else 0.0) + return { + "summary": "Two-sided Welch independent-samples t test with unequal variances and Satterthwaite degrees of freedom.", + "values": {"mean_a": mean_a, "mean_b": mean_b, "t_statistic": t, "degrees_of_freedom": df, + "p_value": p, "sample_size_a": len(a), "sample_size_b": len(b)}, + } + + +def _chi_square(data): + observed, expected = data["observed"], data["expected"] + if len(observed) != len(expected) or len(observed) < 2: + raise ValueError("Provide at least two corresponding observed and expected categories.") + if any(v < 0 or not v.is_integer() for v in observed) or any(v <= 0 for v in expected): + raise ValueError("Observed counts must be nonnegative integers and expectations strictly positive.") + if not math.isclose(math.fsum(observed), math.fsum(expected), rel_tol=1e-12, abs_tol=1e-10): + raise ValueError("Observed and expected category totals must agree; no normalization is performed.") + chi2 = math.fsum((o - e) ** 2 / e for o, e in zip(observed, expected)) + if not math.isfinite(chi2): + raise ValueError("Chi-square statistic exceeds the supported numeric range.") + df = len(observed) - 1 # No fitted parameters; expected probabilities specified a priori. + p = _gamma_q(df / 2, chi2 / 2) + return { + "summary": "Pearson chi-square goodness-of-fit test; expected counts fixed a priori, no fitted parameters.", + "values": {"chi_square": chi2, "degrees_of_freedom": df, "p_value": p, + "categories": len(observed), "expected_count_below_5": sum(e < 5 for e in expected)}, + "table": {"columns": ["category (zero-based)", "observed", "expected", "chi-square contribution"], + "rows": [[i, o, e, (o - e) ** 2 / e] for i, (o, e) in enumerate(zip(observed, expected))]}, + } + + +OPERATIONS = ( + Operation( + "weighted_linear_least_squares", "Weighted linear least squares", + "Fit an intercept and up to 15 predictors with nonnegative relative inverse-variance weights; " + "return coefficients, errors, covariance, weighted R² and per-observation residuals.", + (Field("predictors", "Predictors (rows × columns; intercept implicit)", "matrix"), + Field("response", "Response y", "vector"), + Field("weights", "Relative inverse-variance weights", "vector")), + {"predictors": [[1], [2], [3], [4], [5]], "response": [2.1, 4.2, 5.9, 8.0, 10.2], + "weights": [1, 2, 1, 2, 1]}, _linear, + ), + Operation( + "nonlinear_least_squares", "Levenberg–Marquardt nonlinear fit", + "Fit exponential, saturating_exponential, power_law, gaussian, polynomial, thurber " + "or mgh09 models with analytic Jacobians, convergence diagnostics, errors and 95% Wald intervals.", + (Field("model", "Model (case-insensitive names in description)", "text"), + Field("x", "Predictor x", "vector"), Field("y", "Observed response", "vector"), + Field("weights", "Relative inverse-variance weights", "vector"), + Field("initial_parameters", "Starting parameters in documented order", "vector")), + {"model": "saturating_exponential", "x": [1, 2, 3, 4, 5], + "y": [1.8, 3.2, 4.3, 5.1, 5.6], "weights": [1, 1, 1, 1, 1], + "initial_parameters": [8, 0.25]}, _nonlinear, + ), + Operation( + "welch_t_test", "Welch two-sample t test", "Two-sided Welch t test; independent samples and unequal population variances.", + (Field("sample_a", "Sample A", "vector"), Field("sample_b", "Sample B", "vector")), + {"sample_a": [6, 8, 10, 7], "sample_b": [9, 11, 12, 10, 13]}, _welch, + ), + Operation( + "chi_square_gof", "Chi-square goodness of fit", + "Pearson goodness-of-fit test for categories with fixed expected counts and matching totals.", + (Field("observed", "Observed category counts", "vector"), + Field("expected", "Expected counts (fixed in advance)", "vector")), + {"observed": [25, 30, 45], "expected": [30, 30, 40]}, _chi_square, + ), +) diff --git a/plugins/science_fitting/plugin.py b/plugins/science_fitting/plugin.py new file mode 100644 index 00000000..7e070c02 --- /dev/null +++ b/plugins/science_fitting/plugin.py @@ -0,0 +1,7 @@ +"""Graphlink Fitting and Inference pack.""" + +from graphlink_plugins.scientific.workbench import register_pack + + +def register(host): + register_pack(host, "fitting") diff --git a/plugins/science_fitting/plugin.toml b/plugins/science_fitting/plugin.toml new file mode 100644 index 00000000..83d1c0c8 --- /dev/null +++ b/plugins/science_fitting/plugin.toml @@ -0,0 +1,16 @@ +[plugin] +id = "science_fitting" +name = "Fitting and Inference" +description = "Weighted and nonlinear fits, Welch tests and chi-square goodness-of-fit." +version = "1.1.0" +sdk_api_version = 1 +entry_point = "plugin:register" + +[scopes] +grants = ["graph.read", "graph.mutate"] + +[frontend] +view = "generic" + +[persistence] +passive_node_kinds = ["workbench"]