ISAES scientific method catalog

This guide describes the seven methods released in pf_reporting/methods.py. They operate on retained numerical results using local NumPy, SciPy and scikit-learn. They do not call an AI provider, acquire hardware measurements, or rerun a simulation implicitly. The existing scalar, series, matrix, distribution and structure analyzers and the separately documented domain adapters remain available.

The method catalog has version 1.0. A finding retains its method identifier, version, prerequisites, limitations, dataset metadata and source reference. The product release remains r34; method versions and reporting schema versions are separate identities.

Supplying a dataset

Each example below has a dataset descriptor and the corresponding value. Put the descriptor in the reporting requirements' datasets list. Put the value at the descriptor's JSON pointer in the saved workflow result. These small numbers illustrate the schema and reference arithmetic; they are not experimental or simulation evidence.

For example:

from pf_reporting.engine import build

result = {"data": {"example": example["value"]}}
requirements = {
    "datasets": [example["dataset"]],
    "require": ["ensemble:example"]
}
report, registry = build(result, requirements)

Choose the required method identifier from the table below, and use the dataset name after the colon. A method can also be required by its name alone. Normal private-workflow execution supplies these saved results and reporting requirements through the existing report service.

The source can also use the established artifact-reference syntax. Optional common metadata includes a readable label, units, quantity, frame, basis, origin, named dimensions and coordinates. Do not fill unknown scientific semantics with plausible guesses. Input origin is separate from a model's predicted output origin.

A finding with status: "insufficient" retains useful descriptive information but does not satisfy a required analysis. Malformed inputs, missing dependencies, unsupported options and exceeded budgets produce an unavailable analysis with a reason. A required unavailable analysis remains unmet. Neither outcome is a numerical pass.

1. Correlated uncertainty propagation

{
  "dataset": {
    "name": "example", "kind": "uncertainty", "source": "/data/example",
    "model": "output = input_1 - input_2", "evaluation_point": [0, 0],
    "input_units": ["m", "m"], "output_units": ["m"]
  },
  "value": {
    "jacobian": [[1, -1]],
    "covariance": [[4, 3], [3, 9]]
  }
}

jacobian has one row per output and one column per input. covariance is the full input covariance at the declared evaluation point. Its dimension must match the Jacobian's input dimension. Unit lists and the evaluation-point vector must match the corresponding dimensions. Covariance entries carry the products of their input units; Jacobian entries carry the corresponding output/input units. This adapter uses those declared conventions; it does not infer or differentiate the model.

The method verifies numerical symmetry and positive semidefiniteness, then computes output_covariance = J C J^T. This example has output variance 7 m² and standard uncertainty sqrt(7) m, preserving the covariance term. It records the input covariance, Jacobian, model, evaluation point and output covariance. Tiny negative variance caused by accepted roundoff can be clipped for the square root only; the stored covariance is unchanged.

This is a first-order local approximation. It does not establish distributional coverage, bound nonlinear remainders or supply missing solver/model uncertainty. Monte Carlo model execution is not implemented by this adapter.

2. Independent ensembles

{
  "dataset": {
    "name": "example", "kind": "ensemble", "source": "/data/example",
    "sampling": "independent", "uncertainty_model": "normal", "confidence": 0.95,
    "quantity": "position", "units": "m"
  },
  "value": {
    "values": [[1, 3], [2, 5], [3, 7]],
    "columns": ["x", "y"], "replicate_ids": ["run-a", "run-b", "run-c"]
  }
}

One-dimensional values is a single measured quantity; a two-dimensional array has replicate rows and quantity columns. Optional columns identifies each quantity. Optional replicate_ids must identify every row uniquely. Repeated numerical values are permitted; repeated replicate identities are rejected.

With sampling: "independent", at least two rows supply sample covariance, covariance of the mean and standard errors. The declaration means independent identically distributed replicate rows. Within-row correlation is retained. Without that declaration, the method reports descriptive means and an insufficient outcome rather than treating time steps as independent trials.

uncertainty_model: "normal" enables marginal Student-t mean intervals using the specified confidence level. In the example, the sample covariance is [[1,2],[2,4]]; the mean covariance is that matrix divided by three. Coverage relies on the declared model. These intervals are not simultaneous bounds for all columns.

To use independent-unit resampling instead, set interval_method: "bootstrap_percentile", bootstrap_resamples and seed. This requires at least eight independent rows. It resamples complete rows, preserving correlation among columns. Its percentile bounds are marginal and have no guaranteed finite-sample coverage. Without a normal model or selected bootstrap method, covariance and standard errors are retained without confidence bounds.

Zero sample variance is reported explicitly. A collapsed t or bootstrap interval does not prove absent population or model uncertainty.

3. Paired and independent scenario comparisons

{
  "dataset": {
    "name": "example", "kind": "comparison", "source": "/data/example",
    "quantity": "position", "units": "m", "pairing": "paired",
    "sampling": "independent_pairs", "uncertainty_model": "normal"
  },
  "value": {
    "baseline": [10, 20, 30], "candidate": [33, 11, 22],
    "baseline_ids": ["a", "b", "c"], "candidate_ids": ["c", "a", "b"]
  }
}

The contrast is always candidate minus baseline. Paired mode aligns the scenarios by unique replicate identity. The example therefore has differences [1,2,3] and mean difference 2 m. Equal row counts alone do not establish pairing. The alternative replicate_ids field declares a common identity sequence for both arrays. Pairs must be independent of other pairs; values within each pair may be correlated.

For an unpaired contrast, use pairing: "independent" and sampling: "independent". Each scenario needs at least two observations. Its standard error retains unequal sample variances. Normal-model intervals use the Welch approximation; paired normal-model intervals use the paired differences.

Both modes support interval_method: "bootstrap_percentile". Paired mode resamples differences of matched pairs; independent mode resamples the two independent samples separately. Bootstrap work limits apply to the selected independent resampling units.

quantity and nonempty units are required. Optional baseline_units, candidate_units, and the corresponding frame, basis and quantity overrides must match each other and any declared global convention. Two matching scenario overrides cannot relabel a global time quantity as distance or meters as seconds. Otherwise the comparison is insufficient until an explicit conversion or alignment has been performed. This method does not interpolate coordinates or convert units implicitly.

Optional positive equivalence_margin uses the computed interval's strict containment within the declared positive/negative margin. The status is interval_within_margin or not_established; a small point estimate alone does not establish practical equivalence. This is a declared interval-containment criterion, not a universal equivalence, causality or physical-validation claim.

The report shows scenario means and, when available, the separate contrast with its actual interval. Sampling uncertainty does not subsume solver error or model discrepancy.

4. Numerical convergence

{
  "dataset": {
    "name": "example", "kind": "convergence", "source": "/data/example",
    "reference": "Analytic solution retained in the workflow reference artifact",
    "error_metric": "Absolute endpoint error", "error_units": "m"
  },
  "value": {
    "step_sizes": [1, 0.5, 0.25, 0.125],
    "errors": [1, 0.25, 0.0625, 0.015625]
  }
}

Supply distinct positive discretization scales and matching nonnegative errors already computed against the declared reference. The statistical arrays order observations from coarse to fine, and log(error) is fitted against log(step) using positive errors. The connected plot orders step sizes in ascending order and keeps each error paired with its exact step size. The example has observed order 2 and each adjacent local order is 2.

At least three positive-error scales are required for an observed order. Exact zero errors remain visible and are excluded from logarithmic fitting; they do not become infinite convergence orders. Outputs include local orders, log-fit quality and whether the error decreases under refinement.

This describes the supplied discretizations. It does not establish an asymptotic regime, verify the reference independently, or separate an inaccurate reference from numerical error. Keep reference identity and its actual calculation in the retained workflow evidence.

5. Ordered dynamics

{
  "dataset": {
    "name": "example", "kind": "dynamics", "source": "/data/example",
    "coordinate_units": "s", "units": "m", "origin": "deterministic_simulation"
  },
  "value": {
    "x": [0, 1, 2, 3, 4, 5, 6, 7],
    "y": [0, 1, 0, -1, 0, 1, 0, -1]
  }
}

Coordinates must increase strictly and match the value count. The method retains the trajectory, change and extrema. Fewer than eight points produces a useful trajectory with insufficient diagnostics.

With enough observations, nonconstant signals have descriptive autocorrelation after mean removal. Lags are sample-index lags; with irregular sampling they are not equal physical-time lags. Constant signals receive a constant-signal outcome rather than undefined normalized autocorrelation.

Only sufficiently uniform coordinates receive a SciPy periodogram. It removes a fitted linear trend and records frequencies, power spectral density, coordinate units and detrending convention. Frequency units are inverse coordinate units; power spectral density has signal-unit squared times coordinate-unit dimensions (for example, V²·s when frequency is in inverse seconds). Undeclared units remain explicitly unknown in statistics and visualization metadata. Irregular coordinates are neither silently resampled nor passed to an ordinary uniform-grid FFT. The spectral diagnostic does not assign peak significance. Sampling rate, finite-record resolution, aliasing and any preprocessing remain relevant limitations.

Ordered points do not become independent replicates merely because the plot contains many of them.

6. PCA and descriptive clustering

{
  "dataset": {
    "name": "example", "kind": "table", "source": "/data/example",
    "features": ["x", "y"], "clusters": 3, "seed": 0
  },
  "value": {
    "columns": ["x", "y"],
    "rows": [[0,0],[0,0],[0,0],[0,0],[1,1],[1,1],[1,1],[1,1]]
  }
}

At least eight rows and two numerical selected features are required. Prefer explicit feature roles. For legacy tables without features, numeric columns are selected and the inference is disclosed. Nonnumeric selected columns are excluded and named; they are not encoded as arbitrary numbers. Constant or numerically constant features are removed and recorded.

PCA uses standardized features and singular-value decomposition. It retains feature means/scales, loadings, explained-variance ratios and numerical rank. Standardized PCA scores have explicitly dimensionless plot axes, even when the original features carry physical units. Loadings use a deterministic sign convention; repeated singular values still permit nonunique component axes and are flagged. If only one usable feature remains, the second plotted coordinate is explicitly zero, not a fabricated second component. All-constant inputs are insufficient.

Clustering uses scikit-learn KMeans, fixed seeds, bounded restarts and a canonical fit-row ordering. Standardization and PCA also use canonical numeric row ordering; clustering fit/assignment limits numerical thread pools to one to control reduction-order variability. Original row identities are retained in the output order. The requested cluster count is capped by the number of distinct standardized rows. Only occupied centers and labels are retained. This example has rank one and two occupied groups, despite requesting three.

Outputs distinguish requested, fitted and occupied counts. They include inertia, a silhouette diagnostic where applicable, and adjusted Rand agreement across three additional optimization seeds. Silhouette uses at most 2,000 sampled rows. Restart agreement is optimization sensitivity, not bootstrap stability, independent replication or proof of physical phases. PCA/clustering remains exploratory and has no held-out prediction claim. The existing finding identifier multivariate:<dataset> is preserved.

7. Classical predictive regression

{
  "dataset": {
    "name": "example", "kind": "predictive", "source": "/data/example",
    "task": "regression", "features": ["x"], "target": "response",
    "feature_units": {"x": "m"}, "units": "s",
    "model": "ridge", "alpha": 1, "seed": 7,
    "split": {"kind": "group", "group_column": "experiment", "test_fraction": 0.25}
  },
  "value": {
    "columns": ["x", "response", "experiment", "time"],
    "rows": [
      [0,1,"a",0], [1,3,"a",1], [2,5,"a",2], [3,7,"a",3],
      [4,9,"b",4], [5,11,"b",5], [6,13,"b",6], [7,15,"b",7],
      [8,17,"c",8], [9,19,"c",9], [10,21,"c",10], [11,23,"c",11]
    ]
  }
}

Features and the target must be explicit, distinct numerical columns. Missing/nonfinite numbers are rejected; no imputation or feature selection is hidden in the analysis. The released task is regression. Classification, Gaussian-process surrogates, automatic tuning and cross-validation are not supplied by this catalog.

Each method requires at least twelve input rows, six training rows and two held-out rows. A chosen split can still fail those requirements, especially with highly unequal groups or repeated times. An all-equal time coordinate cannot create a temporal holdout. Group/time policies reduce specified leakage; the user must still identify relevant shared experiments, feature availability, target construction and other dependencies correctly.

The default test_fraction is 0.25; the allowed range is 0.1 through 0.5. This is one fixed holdout, with no automatic model tuning or subsequent all-data refit. StandardScaler is fitted only on the training partition, as is the estimator. The test partition never supplies preprocessing statistics.

Available models:

• ridge: positive finite alpha (default 1.0), solved by SVD.
• random_forest: fixed 100 trees, maximum depth 12, maximum 32 leaves per tree, minimum two training rows per leaf, fixed seed and one worker thread.

Findings retain held-out predictions, observations and residuals; MAE, RMSE and R²; and the RMSE of a training-mean baseline on the same test rows. A constant held-out target has undefined R², represented by null. Constant training features and held-out rows outside the training feature ranges are reported explicitly. No predictive confidence interval is claimed. A classical prediction remains distinct from a newly executed simulation. Prediction plots explicitly carry model-prediction origin, retain acquisition origin, and identify the observed-versus-predicted components of each axis. Observed/predicted and residual views use the same held-out observation identities; both axes use the target units.

Retained model and repeat prediction

finding.values.model_record retains:

• Model/library version, hyperparameters and seed.
• Feature order and any declared units, target identity/units, fitted means/scales and training feature ranges/variances.
• Exact training/test row indices and group/time split details.
• Training-data, evaluation-data and full dataset digests.
• Empty tuning history and the fixed training policy.
• Ridge coefficients/intercept or bounded numerical tree arrays.
• A digest of the record for integrity checking.

Both models can be evaluated from this JSON record without loading executable pickle files:

from pf_reporting.methods import predict_from_record

predicted = predict_from_record(
    model_record,
    rows=[[2.5], [4.0]],
    features=["x"],
    feature_units={"x": "m"}
)

Feature order must match exactly. If feature units were declared at training, the caller must supply that same mapping; the function does not convert meters to kilometers implicitly. Prediction output uses the retained target convention. Forest inference reproduces scikit-learn's float32 input convention after standardization. Its bounded child/feature indices and traversal limit reject malformed/cyclic tree records. The digest detects a changed record relative to its stored digest; it is not an authorship signature.

Old reports and models are not silently retrained. A changed dataset, method, split or model is a new calculation with its own retained record and source dependencies.

Resource limits and reproducibility

These are reporting execution and serialization budgets, not alterations to physical models or observations. Exceeding a limit produces an explicit unavailable method rather than cropping the data silently.

The shared report and worker budgets also apply. A collection of otherwise valid large findings may require a smaller declared analysis or a separately qualified large-data adapter. Large-array storage libraries do not automatically remove numerical-method or report-size limits.

Seeds are unsigned 32-bit integers, default zero. Package versions and saved inputs matter as well as seeds; bitwise equality across arbitrary library/CPU versions is not promised. Imports remain local to numerical execution in the isolated reporting worker. Source syntax is compatible with Python 3.8; actual runtime qualification is reported separately by the release validation receipt.

The test module tests/test_isaes_methods.py checks independent reference arithmetic, paired identity alignment, covariance and resampling correlations, convergence slopes, spectral sampling, degenerate clusters, train-only transformations, group/time boundaries, portable prediction and invalid/resource-limited cases. It also exercises all seven methods through the shared report engine and actual HTML/PDF/PPTX/figure exports, checking convergence ordering, transformed axis units, prediction origin and preservation of asymmetric uncertainty bounds in figure JSON and CSV. Numerical tests qualify these implementations and fixtures; they do not constitute experimental validation of a user's physical theory or model.

Completion catalog: explicit missingness and nonlinear uncertainty

masked_numeric_v1 is a lossless JSON transport representation, not an imputation. Its values, boolean mask, and typed missing_kinds arrays have identical shapes. A raw nonfinite entry is transported as null with type nan, positive_infinity, or negative_infinity. Other missing/excluded entries keep their original numeric value when it exists. Observed entries are finite and use observed. The original source digest and typed mask remain in the scientific input record. Named-array adapters can expose a mask as NaN locally without putting nonfinite numbers into report JSON.

The default treatment is rejection. Explicit missingness: {policy: "exclude_rows", mechanism: "MCAR", reason: "..."} is qualified only for declared independent ensemble, table, density and anomaly rows. Entire affected rows are selected out; feature-wise independent omission is forbidden. The transformation retains original/result digests, retained and excluded row indices and aligned source row IDs. MAR, MNAR, and unknown mechanisms are recorded but withhold population-inference qualification. MCAR is a supplied assumption, not a conclusion from the observed data. Time series, paired comparisons, predictive split membership and quantum states need a separately qualified missingness model; they are not silently shortened.

monte_carlo evaluates a bounded scalar-expression model on samples from an explicit joint distribution. Source form:

{
  "dataset": {"name": "nonlinear", "kind": "monte_carlo", "source": "/data/nonlinear",
              "input_units": ["1", "1"], "output_units": ["1", "1"], "samples": 20000, "seed": 10},
  "value": {
    "model": {"inputs": ["x", "y"], "outputs": {"sum": "x+y", "product": "x*y"}},
    "distribution": {
      "kind": "multivariate_normal", "mean": [1, 2],
      "covariance": [[1, 0.5], [0.5, 2]]
    }
  }
}

The alternative joint_empirical distribution requires samples rows and unique row_ids; whole rows are sampled together to preserve cross-input dependence. Empirical-source uncertainty is not automatically estimated. Dataset metadata must provide input_units and output_units, with optional samples (1,000–100,000), unsigned seed, and confidence. Input/output cells are bounded to four million. Unit lists identify declared semantics; the expression evaluator does not establish dimensional consistency of a physical equation or implicitly convert units.

The expression language supports finite constants, declared scalar inputs, + - * /, literal powers of magnitude at most 16, and unary sqrt exp log sin cos tanh abs. Attribute access, indexing, comprehensions, Python execution, arbitrary calls and input-dependent exponents are rejected. A domain error on any draw stops the method; failed draws are never omitted.

The result separately retains propagated output covariance and propagated_output_standard_uncertainties, Monte Carlo standard errors of estimated means, central output quantiles and binomial order-statistic uncertainty intervals for each quantile. The latter measure simulation precision, not uncertainty in the physical model. Intervals are marginal, conditional on the declared IID distribution; atoms can make them conservative. No general model-discrepancy, solver-error or simultaneous-coverage claim is made. Correlated-normal analytic moment tests, exact correlated empirical degeneracy, repeated median-coverage trials and unsafe-model refusal fixtures qualify this path.

Completion catalog: density, anomaly and reference diagnostics

Density exploration and anomaly reference sets are bounded to 8–2,048 rows; anomaly evaluation supports 1–2,048 rows, all with at most 32 features with positive user-declared scales. IDs are never inferred as numeric features. Residual vectors are bounded to 512 entries. A chi-square survival probability requires explicit residual_model: "normal_prespecified" and chi_square_dof exactly equal to the numerical rank of the known residual covariance. An arbitrary reduction of degrees of freedom is rejected. Estimated covariance or a fitted reference requires a separately validated model and is not silently accepted as known. Singular covariance does not hide discrepancies outside its support. References, scales, duplicates, degeneracy and limitations remain in findings.