| name | sns-snap-reduction-diagnostics |
| description | Diagnose quality issues in SNAP reduction outputs and propose targeted fixes. Use when reduced diffraction products show artifacts, unstable baselines, inconsistent normalization, or unexpected peak behavior.
|
| version | 2 |
| review | {"status":"human-reviewed","reviewer":"Malcolm Guthrie","reviewed_on":"2026-05-05T00:00:00.000Z","basis":["docs","code","instrument-science-review"],"notes":"Reviewed and approved for v2 publication. Confirmed diagnostics updates: calibration/continue-path behavior aligned with current abort defaults, SEE-sensitive diagnostic/provenance checks expanded, and formatting consistency corrected.\n","approved_commit":"review/sns-snap-reduction-diagnostics-v2","prior_review":{"status":"human-reviewed","reviewer":"Malcolm Guthrie","reviewed_on":"2026-04-30T00:00:00.000Z","basis":["docs","code","instrument-science-review"],"notes":"Clarified root-cause coverage to include sample-environment-specific corrections and added a high-value masking-failure check for large background artifacts.\n","approved_commit":"review/sns-snap-reduction-diagnostics-v1"}} |
| metadata | {"facility":"SNS","beamline":"BL3","instruments":["SNAP"],"software":["snapwrap","snapred","Mantid"],"data_phase":"reduction","techniques":["diffraction","powder-diffraction","time-of-flight","diagnostics"],"tags":["diagnostics","quality-control","troubleshooting","baseline","normalization"]} |
SNAP Reduction Diagnostics
This skill guides an agent through a structured inspection of SNAP reduction
outputs to identify failure modes, attribute root causes, and produce a
targeted rerun plan. It is invoked after an initial reduction run completes.
Related skills:
Evidence tracking
Phase 0 baseline (2026-04-29):
Phase 1 calibration foundation (2026-04-29):
- Sources:
- Clarified user policy: diagnostic outputs are valid for exploratory work, or can trigger
post-hoc calibration and rereduction.
Overview
This skill produces: (1) a ranked list of likely root causes for the observed
quality issue, (2) recommended parameter changes for the next run, and (3) an
explicit decision on whether to use the current output as exploratory results
or to recalibrate and rereduce for final output.
Software provenance:
- snapwrap (user interface — first): surfaces warnings, status labels, and
outputs that indicate calibration completeness; exposes decision points for
export, rerun, or deeper diagnostics.
- snapred (backend): determines whether full calibration context exists and
routes reduction accordingly; emits diagnostic pathways and can preserve
intermediate workspaces in CIS mode.
- Mantid (framework): produces diagnostic workspaces and metrics used to
inspect calibration quality, masking effects, and fit behavior.
Root-cause categories to consider:
- Calibration mismatch or stale calibration products.
- Sample-environment-specific corrections not represented in calibration or
reduction assumptions.
- Geometry or masking choices suppressing valid signal.
- Background or normalization configuration drift.
- Run metadata mismatch across grouped reductions.
When to Use
- Use when reduced diffraction products show artifacts, unstable baselines,
inconsistent normalization, or unexpected peak behavior.
- Use when output workspaces are labelled
diagnostic_ and the cause is
unknown.
- Use when peak positions differ unexpectedly between detector groups.
- Use when large background artifacts appear in the reduced output.
- Do NOT use as a substitute for the upstream reduction workflow — invoke
sns-snap-reduction-workflow-overview
first if a full reduction has not yet been attempted.
Process
Collect this context before starting:
- The run number(s) that produced the suspect output.
- The output workspace name(s), including the full prefix
(
reduced_ vs diagnostic_).
- The continue-policy flags used:
continueNoDifcal, continueNoVan, noNorm.
- Whether cycle-strict matching was active (
requireSameCycle=True).
- Whether CIS mode was enabled.
- The sample environment type (PE, DAC, cylinder, or none).
- Check the output label and continue-policy inputs — Confirm whether the
workspace prefix is
reduced_ or diagnostic_. Retrieve the continue flags
used in the run. Standard behavior with missing calibration and no intentional
continue flag is reduction abort (no output workspace). If a diagnostic_
workspace exists, attribute it to an intentional continue pathway first;
otherwise treat it as a configuration/traceability anomaly and investigate
logs before proceeding.
[CHECKPOINT]: The output state is understood: (a) reduced_,
(b) diagnostic_ via intentional continue pathway, or (c) reduction abort
with missing calibration while continue flags are unset.
-
Inspect reduction logs for warnings — Look for ContinueWarning,
MISSING_DIFFRACTION_CALIBRATION, MISSING_NORMALIZATION, or
ALTERNATE_DIFFRACTION_CALIBRATION flags in the reduction record. Note
every flag; each represents a deviation from full-calibration reduction.
-
Check calibration cycle matching — Confirm whether
requireSameCycle=True was active and whether a valid same-cycle calibration
existed for the run's instrument state. An out-of-cycle calibration that was
silently accepted (or rejected) is a common root cause of subtle peak-position
errors.
-
Inspect masking coverage — Examine the number and geometry of masked
pixels. Large contiguous masked regions, unexpected zero-count areas in the
detector image, or large background artifacts in the reduced output indicate
a mask that is missing, shifted, or overly aggressive. For high-pressure
devices, cross-check against the expected device-specific mask.
-
Inspect baseline and normalization stability across groups — Compare
reduced spectra from each pixel group (all, bank, column). Systematic
offsets between groups, wavelength-dependent intensity drift, or a group
that is an outlier relative to others points to a calibration issue
(difcal or normcal) or a grouping/masking mismatch. Although be aware that sample-specific corrections may also produce group-specific effects not due to calibration.
-
Validate peak shape and position — Compare peak positions and widths
against expected references (a known standard or a prior run in the same
state). Broadened or shifted peaks across all groups may indicate a
diffraction calibration (difcal) mismatch, but for high-pressure samples
can equally reflect pressure-driven structural changes (lattice strain,
phase transitions) in the sample itself. Broadening confined to one group
suggests a per-group calibration or masking issue rather than a sample
effect. See sns-snap-high-pressure-data-interpretation
for guidance on distinguishing sample-driven from instrument-driven peak
behaviour.
-
If CIS mode was active, inspect intermediate workspaces — Check retained
intermediate workspaces for offset saturation, failed pixels or groups, or unstable
fits. These provide the most direct and granular evidence of where the reduction pipeline
deviated.
[CHECKPOINT]: A ranked list of root causes is established. Each cause is
tied to at least one observable piece of evidence from steps 1–7.
-
Propose and record a rerun plan — For each attributed root cause, specify
the minimum parameter change needed (e.g., obtain missing calibration,
correct mask, relax cycle policy with documented justification). Record the
minimal reproducible parameter set.
-
Make an explicit output-intent decision — State clearly: keep the current
output for exploratory use only, OR recalibrate/remask and rereduce before
treating results as final. This decision must be recorded in the reduction
record (analysis notes and/or run log).
Exit criteria: A ranked root-cause list, a rerun parameter set, and an
explicit output-intent decision are all documented.
Rationalizations
| Rationalization | Why it is wrong |
|---|
"The output is diagnostic_ but the peaks look fine, so it's good enough." | diagnostic_ means an approximation pathway was used. Visual inspection of peaks does not reveal subtle TOF-to-d mapping errors or normalization drift. The label is ground truth about data provenance, not a visual quality score. |
| "I checked one group — they all look the same." | Cross-group comparison at step 5 is the diagnostic, not single-group inspection. Normalization and calibration failures often manifest as inter-group offsets invisible within a single spectrum. |
| "The masking looks fine — there are no obvious gaps." | Mask failures can produce large background artifacts rather than obvious gaps. Step 4 requires checking both the detector image and the reduced output for artifact signatures, not just visual coverage. |
| "CIS mode is off so there's nothing to inspect." | Steps 1–6 do not require CIS mode. CIS mode provides additional evidence at step 7; its absence does not justify skipping the earlier checks. |
| "I'll record the root cause after the rerun." | The decision at step 9 and the evidence at steps 1–7 must be recorded before the rerun. After a successful rerun, the diagnostic context is routinely lost. |
Red Flags
- Reduction aborted with missing calibration while continue flags are unset
(default) → expected behavior. Revisit steps 1–3 to resolve calibration
availability or intentionally enable a continue pathway.
MISSING_DIFFRACTION_CALIBRATION or ALTERNATE_DIFFRACTION_CALIBRATION
flag in the reduction record → peak positions and d-spacing values are
unreliable. Do not use for final results without recalibration.- Large contiguous zero-count region in the detector image not explained by
the expected device mask → pixel mask is missing, shifted, or
wrong for the current device. Revisit step 4 and invoke
sns-snap-sample-environment-reduction-special-cases.
- Systematic peak-position offset between groups →
difcal mismatch;
revisit step 3 and invoke sns-snap-calibration-and-geometry.
- Wavelength-dependent intensity drift in one or more groups →
normcal
issue; revisit step 5 and calibration state.
sampleFactor > 1 used → upsampling is lossy in current tooling and is
warned. Note this in the root-cause list; do not use upsampled output for
final intensity-dependent analysis.
Resampling reference
sampleFactor=1: no effective change in bin spacing.sampleFactor<1: coarsens bins (downsampling).sampleFactor>1: refines bins (upsampling) — warned this simply oversamples existing values; rebinning parameters are spectrum-specific within a pixel grouping
scheme.
Verification
Before marking this skill complete:
