wzyn20051216/matlab-agent-skills / skills/matlab-data-analysis
matlab-data-analysis
VerifiedMATLAB data analysis workflow for tables, timetables, numerical verification, ODE solving, statistics, fitting, uncertainty, error propagation, and reproducible experiments. Use whenever the user asks MATLAB to analyze data, integrate or differentiate numerically, solve or verify ODE solutions, solve or check linear systems, assess convergence and conditioning, clean tables with missing/outlier accounting, fit models, test significance, propagate uncertainty, or reproduce figures and numbers.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.4 KB |
| references/data-verification-contract.md | markdown | 22.7 KB |
| scripts/mas_converge_check.m | other | 8.3 KB |
| scripts/mas_fit_check.m | other | 12.4 KB |
| scripts/mas_linsolve_check.m | other | 8.7 KB |
| scripts/mas_ode_check.m | other | 30.9 KB |
| scripts/mas_quad_check.m | other | 12.5 KB |
| scripts/mas_repro_check.m | other | 6.0 KB |
| scripts/mas_stat_check.m | other | 15.4 KB |
| scripts/mas_table_audit.m | other | 9.0 KB |
| scripts/mas_uncert_check.m | other | 10.3 KB |
| tests/test_data_contract.m | other | 20.6 KB |
| tests/test_ode_contract.m | other | 13.1 KB |
| tests/test_ode_field_contract.m | other | 7.9 KB |
| tests/test_table_audit.m | other | 6.0 KB |
scripts/mas_uncert_check.m
View on GitHubfunction r = mas_uncert_check(f, x0, sigma, claims)
%MAS_UNCERT_CHECK Check an uncertainty claim against direct sampling.
%
% r = mas_uncert_check(@(x) x(1).*x(2), [2; 3], [0.02; 0.03], ...
% struct('sigma', 0.078, 'sigmaTolRel', 0.02))
%
% f scalar function of a k-vector
% x0 k-vector of nominal values
% sigma k-vector of independent 1-sigma input uncertainties
% claims .value claimed f(x0) (optional)
% .sigma claimed output uncertainty (optional)
% .sigmaTolRel relative tolerance for it (default 0.05)
% .usedMethod 'montecarlo' (default) | 'linearized' -- what produced
% the claim, reported for diagnosis, not trusted
% .nMC Monte Carlo draws (default 10000)
% .seed RNG seed (default 20261021)
%
% r.verdict PASS | FAIL | UNDETERMINED
% r.sigmaLin, r.sigmaMC, r.mcSE, r.mcCI, r.mcBias, r.J, r.sensitivity
%
% WHY THE FIRST-ORDER FORMULA IS NOT THE ANSWER
% The textbook propagation sigma_y = sqrt(sum((df/dxi * sigma_i)^2)) is a
% first-order Taylor approximation. It is exact for a linear f and can be wrong
% by tens of percent for a curved one -- and nothing in the formula announces
% when it has stopped applying. This tool therefore computes BOTH routes:
%
% linearized: a Jacobian (complex step when f is analytic, verified against
% central differences; central differences otherwise);
% Monte Carlo: sampled f(x0 + sigma.*randn), whose own sampling error is
% reported as mcSE and gated against the tolerance being asked of
% the claim. A Monte Carlo reference that is noisier than the
% tolerance cannot certify anything: that is UNDETERMINED, not
% PASS, and the fix is more draws.
%
% The claim is graded against the Monte Carlo value, because that is the honest
% estimate of the output distribution; the linearized value is reported beside
% it and the gap is surfaced as the nonlinearity diagnosis. Correlated inputs are
% NOT supported -- with a covariance matrix the linearized route is J*C*J' and the
% sampling route must draw correlated normals; pretending independence here would
% understate the output uncertainty, so the limitation is stated in r.notes.
%
% The RNG state is saved and restored, so checking an uncertainty does not move
% the caller's random stream.
if nargin < 4 || isempty(claims), claims = struct(); end
if ~isa(f, 'function_handle'), error('mas_uncert_check:f', 'f must be a function handle'); end
if ~isnumeric(x0) || ~isvector(x0) || ~isnumeric(sigma) || ~isvector(sigma)
error('mas_uncert_check:args', 'x0 and sigma must be numeric vectors');
end
x0 = x0(:); sigma = sigma(:);
if numel(x0) ~= numel(sigma)
error('mas_uncert_check:args', 'x0 and sigma must have the same length (got %d and %d)', ...
numel(x0), numel(sigma));
end
if any(~isfinite(x0)) || any(~isfinite(sigma))
error('mas_uncert_check:args', 'x0 and sigma must be finite');
end
if any(sigma < 0)
error('mas_uncert_check:args', 'sigma entries must be non-negative');
end
tolS = local_field(claims, 'sigmaTolRel', 0.05);
N = round(local_field(claims, 'nMC', 10000));
seed = local_field(claims, 'seed', 20261021);
usedMethod = 'montecarlo';
if isfield(claims, 'usedMethod') && ischar(claims.usedMethod)
usedMethod = lower(claims.usedMethod);
end
if ~any(strcmp(usedMethod, {'montecarlo', 'linearized'}))
error('mas_uncert_check:claims', 'usedMethod must be montecarlo or linearized');
end
if N < 100
error('mas_uncert_check:claims', 'nMC must be at least 100');
end
C = local_check_empty();
notes = {'independent inputs assumed; correlated inputs require the covariance form and are not supported'};
y0 = f(x0);
if ~isnumeric(y0) || ~isscalar(y0) || ~isreal(y0) || ~isfinite(y0)
error('mas_uncert_check:f', 'f must return a finite real scalar');
end
C = local_check_add(C, 'dims', true, sprintf('%d inputs, %d draws, f(x0) = %.10g', ...
numel(x0), N, y0));
% ---- Jacobian: complex step, verified against central differences ---------
k = numel(x0);
Jc = zeros(k, 1); Jd = zeros(k, 1);
csOK = true;
for i = 1:k
h = max(abs(x0(i)), 1)*1e-20;
xc = x0; xc(i) = xc(i) + 1i*h;
try
Jc(i) = imag(f(xc))/h;
if ~isfinite(Jc(i)), csOK = false; end
catch
csOK = false;
Jc(i) = NaN;
end
end
for i = 1:k
h = max(abs(x0(i)), 1)*1e-5;
xp = x0; xm = x0;
xp(i) = xp(i) + h;
xm(i) = xm(i) - h;
Jd(i) = (f(xp) - f(xm))/(2*h);
end
jacGap = NaN;
if csOK && all(isfinite(Jc))
jacGap = max(abs(Jc - Jd))/max(1, max(abs(Jd)));
end
if csOK && jacGap <= 1e-4
J = Jc; jacHow = 'complex step';
else
J = Jd; jacHow = 'central differences';
if csOK
notes{end+1} = sprintf(['complex step and central differences disagree by %.2e: ' ...
'f is not analytic here, central differences used'], jacGap);
else
notes{end+1} = 'complex step unavailable: central differences used';
end
end
sigmaLin = sqrt(sum((J.*sigma).^2));
% ---- Monte Carlo with a seeded, restored stream --------------------------
st = rng;
rng(seed);
Y = zeros(N, 1);
for i = 1:N
yi = f(x0 + sigma.*randn(k, 1));
if ~isnumeric(yi) || ~isscalar(yi) || ~isreal(yi)
rng(st);
error('mas_uncert_check:f', 'f must return a finite real scalar (draw %d)', i);
end
Y(i) = yi;
end
rng(st);
mY = mean(Y);
sigmaMC = std(Y);
seS = sigmaMC/sqrt(2*(N - 1));
ciMC = sigmaMC + [-1 1]*1.96*seS;
bias = mY - y0;
floorS = 100*eps*max(1, abs(y0));
if sigmaMC <= floorS
C = local_check_add(C, 'mcPrecision', true, ...
'sampled output is constant at the roundoff floor');
else
precRatio = 3*seS/sigmaMC;
if precRatio <= tolS
C = local_check_add(C, 'mcPrecision', true, sprintf( ...
'Monte Carlo standard error is %.2f%% of sigma (3*SE = %.1f%% of sigma, tolerance %.1f%%)', ...
100*seS/sigmaMC, 100*precRatio, 100*tolS));
else
% Not the claimant's fault: the reference is too noisy to decide at this
% tolerance. That is undetermined, not a failure of the claim.
C = local_check_add(C, 'mcPrecision', NaN, sprintf( ...
['Monte Carlo standard error is %.2f%% of sigma (3*SE = %.1f%% of sigma, ' ...
'tolerance %.1f%%): increase nMC -- this reference cannot certify that tolerance'], ...
100*seS/sigmaMC, 100*precRatio, 100*tolS));
notes{end+1} = 'Monte Carlo reference is noisier than the tolerance: more draws required';
end
end
% ---- the claim ------------------------------------------------------------
if isfield(claims, 'value') && isscalar(claims.value)
relV = abs(y0 - claims.value)/max(1, abs(y0));
C = local_check_add(C, 'valueVsClaim', relV <= 1e-9, sprintf( ...
'f(x0) = %.10g vs reported %.10g (dev %.2e)', y0, claims.value, relV));
else
C = local_check_add(C, 'valueVsClaim', 'na', 'no output value reported');
end
if isfield(claims, 'sigma') && isscalar(claims.sigma)
if sigmaMC <= floorS
den = max(1, abs(y0));
C = local_check_add(C, 'claimedVsRef', ...
abs(claims.sigma) <= 100*eps*den, sprintf( ...
'sampled sigma is zero (floor %.2e); reported sigma %.3e', floorS, claims.sigma));
else
relS = abs(claims.sigma - sigmaMC)/sigmaMC;
precOK = true;
if sigmaMC > floorS
precOK = 3*seS/sigmaMC <= tolS;
end
if precOK
C = local_check_add(C, 'claimedVsRef', relS <= tolS, sprintf( ...
['reported sigma %.6g vs Monte Carlo %.6g (dev %.2f%%, tolerance %.1f%%); ' ...
'linearized route would give %.6g'], ...
claims.sigma, sigmaMC, 100*relS, 100*tolS, sigmaLin));
else
C = local_check_add(C, 'claimedVsRef', NaN, sprintf( ...
['reported sigma %.6g and Monte Carlo %.6g differ by %.2f%%, but the ' ...
'sampled reference is too noisy at this tolerance to decide'], ...
claims.sigma, sigmaMC, 100*relS));
end
end
else
C = local_check_add(C, 'claimedVsRef', NaN, sprintf( ...
['no sigma reported; Monte Carlo sigma is %.6g and the linearized value ' ...
'is %.6g'], sigmaMC, sigmaLin));
end
if sigmaMC > floorS
gapPct = 100*abs(sigmaLin - sigmaMC)/sigmaMC;
if gapPct > 100*tolS
notes{end+1} = sprintf(['linearized propagation (%.6g) differs from Monte Carlo ' ...
'(%.6g) by %.1f%%: nonlinearity is significant over these 1-sigma ranges'], ...
sigmaLin, sigmaMC, gapPct);
end
end
if strcmp(usedMethod, 'linearized')
notes{end+1} = 'claim states a linearized method: acceptable only where the gap above is small';
end
sens = (J.*sigma).^2;
if sigmaLin > 0
sens = sens/sum(sens);
end
sensTbl = table((1:k).', x0, sigma, J, sens, ...
'VariableNames', {'index', 'x0', 'sigma', 'dfdx', 'share'});
stc = {C.status};
if any(strcmp(stc, 'fail'))
r.verdict = 'FAIL';
elseif any(strcmp(stc, 'undetermined'))
r.verdict = 'UNDETERMINED';
else
r.verdict = 'PASS';
end
r.checks = C;
r.notes = notes;
r.y0 = y0;
r.sigmaLin = sigmaLin;
r.sigmaMC = sigmaMC;
r.mcSE = seS;
r.mcCI = ciMC;
r.mcBias = bias;
r.mcMean = mY;
r.sigmaRef = sigmaMC;
r.usedMethod = usedMethod;
r.J = J;
r.jacobianMethod = jacHow;
r.sensitivity = sensTbl;
r.relUncert = sigmaMC/max(abs(y0), realmin);
r.nMC = N;
r.seed = seed;
r.nChecks = numel(C);
r.nPass = nnz(strcmp(stc, 'pass'));
r.nFail = nnz(strcmp(stc, 'fail'));
r.nUndetermined = nnz(strcmp(stc, 'undetermined'));
r.nNa = nnz(strcmp(stc, 'na'));
r.detail = sprintf('%s: %d pass, %d fail, %d undetermined, %d na', ...
r.verdict, r.nPass, r.nFail, r.nUndetermined, r.nNa);
bad = strcmp(stc, 'fail') | strcmp(stc, 'undetermined');
if any(bad)
r.detail = sprintf('%s (%s)', r.detail, strjoin({C(bad).id}, ', '));
end
end
% ===========================================================================
function v = local_field(s, f, dflt)
v = dflt;
if isfield(s, f) && isscalar(s.(f)), v = s.(f); end
end
function C = local_check_empty()
C = struct('id', {}, 'status', {}, 'detail', {});
end
function C = local_check_add(C, id, pass, detail)
if ischar(pass)
st = pass;
elseif isnan(pass)
st = 'undetermined';
elseif pass
st = 'pass';
else
st = 'fail';
end
C(end+1) = struct('id', id, 'status', st, 'detail', detail); %#ok<AGROW>
end
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |