Input/output
The I/O subsystem is a small registry of format-specific loaders
behind a single entry point: asymmetry.core.io.load() infers the
format from the file extension and dispatches to the appropriate
BaseLoader subclass. The current
loaders are NexusLoader (ISIS muon
NeXus V1 and V2, including multi-period files, which return a list of
MuonDataset),
PsiLoader (PSI BIN and MDU raw
histograms, with discovery of PSI .mon temperature sidecars), and
RootLoader (MusrRoot and LEM ROOT
files, including slow-control histograms). The format-specific quirks
each loader handles — bin-index conventions, per-detector \(t_0\),
deadtime and background metadata — are documented in
Loading Data. Custom formats can be added by
subclassing BaseLoader and
registering it with the
LoaderRegistry.
Main interface
- asymmetry.core.io.load(filepath, fmt=None, period=None, *, checkpoint=None, progress=None)[source]
Load a μSR data file and return a
MuonDataset.- Parameters:
filepath (str) – Path to the data file.
fmt (str, optional) – Force a specific format (e.g.
"nxs"). If None, the format is auto-detected from the file extension.period (int or str or PeriodMode, optional) – For period-mode (multi-period) files, select a single period and return just that
MuonDataset. Accepts a 1-based period number or, for two-period files, a"red"/"green"label. When None (default) the historical behaviour is preserved: single/two-period files return oneMuonDatasetand 3+ period files alist. Seeasymmetry.core.io.periods.checkpoint (callable, optional) – Cooperative cancellation callback, called between hash chunks and around decoding by the built-in loaders. Raising aborts the load.
progress (callable, optional) – Receives bytes read and total bytes for each of the two whole-file hash passes bracketing built-in decoding. Decoding itself is format-specific.
- Raises:
ValueError – If
periodis out of range or an unknown label.
Period selection
Period-mode (multi-period) runs — photo-μSR light-OFF/ON, RF on/off, ALC —
expose a scriptable selection API in asymmetry.core.io.periods. The same
helpers back the GUI red/green (“RG”) selector, so scripts and the desktop app
share one implementation. See Selecting periods (Red / Green) for a worked example.
- asymmetry.core.io.periods.select_period(data, period)[source]
Return a reduced
MuonDatasetfor a single period.- Parameters:
data – A loaded run: either a single
MuonDataset(single-period file, or a combined two-period file) or thelistreturned for 3+ period files.period – Period selector — see
resolve_period_index().
- Returns:
MuonDataset – The requested period with its own
time/asymmetry/errorand per-period provenance (period_number,run_label,good_frames,dead_time_us). t0, good-bin window, grouping, field and temperature are preserved from the parent run.
Notes
The arrays returned are the loader’s default reduction (
alpha = 1.0, no deadtime/background correction), identical to what the loader produces for a single-period file.
- asymmetry.core.io.periods.period_count(data)[source]
Return the number of periods reachable from
data.Accepts a loaded
MuonDataset, alistof datasets (as returned for 3+ period files), or aRun.
- asymmetry.core.io.periods.period_labels(data)[source]
Return human-facing labels for each selectable period.
Two-period runs return
["red", "green"]; otherwise the 1-based period numbers as strings.
- asymmetry.core.io.periods.resolve_period_index(period, count)[source]
Translate a user-supplied period selector to a 0-based index.
periodmay be a 1-based integer period number, a numeric string, or — whencount == 2— a"red"/"green"label (orPeriodModemember). RaisesValueErrorfor unknown labels or out-of-range numbers andTypeErrorfor unsupported types.
- asymmetry.core.io.periods.combine_mapped_periods(period_datasets, mapping, *, source_run_number=None, source_file='', cancel_check=None, _implicit_pairing=False)[source]
Map acquired periods with own-clock reduction and retained original inputs.
- asymmetry.core.io.periods.sum_period_histograms(period_histograms, *, coefficients=None, cancel_check=None)[source]
Sum per-period histogram lists detector-wise (count level).
Independent supplied variances add; genuinely raw Poisson contributions use their counts. NaN retains unknown source noise for scoped consumer validation. Timing follows the first contributor and bins use common raw-index support. This operation does not align different acquisition clocks. A unit singleton preserves supplied noise and records unknown raw noise too.
- asymmetry.core.io.periods.combine_period_asymmetry(red_time, red_asymmetry, red_error, green_time, green_asymmetry, green_error, mode)[source]
Difference independent curves; pooled G+R requires prepared counts.
Arrays alone cannot determine the pooled count ratio. Both curves must have identical time coordinates; errors of the difference add in quadrature.
The arrays-only helper supports G−R. Arrays of separate ratios cannot determine pooled G+R; use the histogram preparation API with verified acquired counts. Historical curve-only records remain readable, but a fresh RF pooled scan excludes them with an explicit reload reason. Count-backed RF scans use current settings; scan values/errors are fractions, whereas time curves are percentages.
Mapped and arithmetically combined runs retain original acquired Run records in
run.grouping["period_inputs"]. Mappings retain stored input order; run arithmetic
retains source order, then each source’s acquired periods. Input ordinal and
original acquired-period identity remain distinct.
period_mapping records authored membership; held histograms are pooled
inspection views. Normal reduction corrects each selected acquisition with its
own coefficient/exposure and aligns its own t0 on common observed support before
pooling. Extracted sets retain this context; selected-set reduction and histogram
replay use the same preparation. sum_period_histograms remains an explicit
raw-index addition helper. Pass the mapped dataset to combine_mapped_periods to remap these
retained acquisitions, including ignored periods. The inputs are transient: projects
reconstruct them from the source file and saved mapping. Fitting curve records
remove these replay arrays. NeXus selections distinguish data_period_number
from an evidenced dae_period_number and retain period_declaration
metadata, including unresolved correspondence.
Registry
Loaders
Base loader
- class asymmetry.core.io.base.BaseLoader[source]
Bases:
ABCInterface that every file-format loader must implement.
- extensions = []
File extensions this loader claims (e.g.
[".nxs"]).
- format_name = ''
Short human-readable name (e.g.
"ISIS NeXus (.nxs/.nexus)").
- abstractmethod load(filepath)[source]
Read filepath and return one or more
MuonDatasetobjects.Most formats return a single dataset. Multi-period NeXus files may return multiple datasets (one per period).
NeXus loader
- class asymmetry.core.io.nexus.NexusLoader[source]
Bases:
BaseLoaderRead ISIS muon
.nxsfiles and return one or more datasets.- extensions = ['.nxs', '.nexus']
File extensions this loader claims (e.g.
[".nxs"]).
- format_name = 'ISIS NeXus (.nxs, .nexus)'
Short human-readable name (e.g.
"ISIS NeXus (.nxs/.nexus)").
PSI loader
Loads PSI BIN/MDU raw histogram files using the musrfit-compatible binary
metadata interpretation. PSI-BIN .mon temperature sidecars are discovered
and parsed using Mantid LoadPSIMuonBin-compatible rules, then exposed as
metadata["nexus_time_series"] and in the Get Info metadata tables.
- class asymmetry.core.io.psi.PsiLoader[source]
Bases:
BaseLoaderRead PSI
.binand.mduraw histogram files.- extensions = ['.bin', '.mdu']
File extensions this loader claims (e.g.
[".nxs"]).
- format_name = 'PSI BIN/MDU (.bin, .mdu)'
Short human-readable name (e.g.
"ISIS NeXus (.nxs/.nexus)").
- load(filepath)[source]
Read filepath and return one or more
MuonDatasetobjects.Most formats return a single dataset. Multi-period NeXus files may return multiple datasets (one per period).
ROOT loader
Loads MusrRoot/LEM ROOT histograms and header metadata. MusrRoot slow-control
histograms under histos/SCAnaModule are exposed through
metadata["nexus_time_series"] and Get Info, including sample-temperature
logs such as hSampleTemperature. Serialized LEM headers support numeric
v4/v5 calibration; metadata["root_format"] retains the actual version,
declared_units records its format units, and root_histo_numbers maps
stored arrays to detector ordinals. See Loading Data for
supported v4 banks and unavailable timing.
- class asymmetry.core.io.root.RootLoader[source]
Bases:
BaseLoaderRead MusrRoot and PSI LEM ROOT files.
- extensions = ['.root']
File extensions this loader claims (e.g.
[".nxs"]).
- format_name = 'MusrRoot / LEM ROOT (.root)'
Short human-readable name (e.g.
"ISIS NeXus (.nxs/.nexus)").
- load(filepath)[source]
Read filepath and return one or more
MuonDatasetobjects.Most formats return a single dataset. Multi-period NeXus files may return multiple datasets (one per period).
NeXus writer
Writes synthetic or derived runs (see Synthetic runs and degraded statistics) as
loadable ISIS muon NeXus V1 files. Built from the
Run alone — any loaded run, PSI and
ROOT formats included, can act as the instrument template — with the
simulation provenance stored in a /run/simulation group.
Minimal ISIS muon NeXus V1 writer for synthetic and derived runs.
Writes a fresh HDF5 file containing exactly the layout
NexusLoader consumes for legacy /run
files (see docs/porting/simulate-mode/implementation-options.md for the
field table), plus a /run/simulation provenance group that the loader
surfaces through metadata["nexus_fields"]. Unlike WiMDA’s template-copy
save, the file is built from the Run alone, so any loaded run — PSI
.bin/.mdu included — can act as the instrument template, and no stale
sample logs leak into the synthetic file.
Notes on the V1 contract (verified against nexus.py):
Time zero is written the way ISIS writes it: a 1-based
t0_binattribute on thecountsdataset (one value per detector, so PSI-style staggered t0 survives) plushistogram_data_1/time_zeroin microseconds from the start of acquisition.first_good_bin/last_good_binare 1-based inclusive attributes on the same dataset. A round trip throughNexusLoaderis the identity.The file carries either the run’s file t0 throughout or its policy-resolved effective t0 throughout (
effective=True) — never a mix (F7).The loader treats the two lowest group ids in
groupingas forward and backward, so the writer renumbers the run’s forward group to 1 and backward to 2 (further groups follow in stable order).ISIS NeXus V1 has no balance-factor field, so α does not survive a round trip — the generating α is recorded in
/run/simulationfor reference only, exactly as with real data where α is an analysis-side calibration.
- asymmetry.core.io.nexus_writer.write_nexus_v1(run, path, *, effective=False)[source]
Write run as a loadable ISIS muon NeXus V1 (HDF5) file.
The file reloads through
asymmetry.core.io.load()with identical per-detector counts, bin width, per-detector t0 bins, exact t0, good-bin window, grouping (forward/backward renumbered to 1/2) and good frames. RaisesValueErrorfor runs without histograms or with ragged histogram lengths, andImportErrorwhenh5pyis unavailable.With
effective=Trueevery t0-derived field — the per-detector bins, the exacttime_zero, the good window andcorrected_time— comes from the grouping’s policy-resolved t0 instead of the file’s, so the written run is the analysed one. The two sets are never mixed.
Run arithmetic metadata
combine_runs retains the first caller-ordered input’s finite field and
temperature (or None), title, and instrument/facility/beamline identity.
combination.constituents records ordered leaf conditions, source identities,
effective signed coefficients, and the master relationship. input_ordinal
binds a live record to its retained acquisition; inactive authored inputs absent
from the numerical payload use null and remain provenance only. Rebuilding
reads current acquired conditions rather than cached composite summaries. The finite active
ranges are temperature_spread and field_spread; inactive terms stay
provenance. Composite sources do not inherit a single file identity or cached
single-acquisition diagnostics. implicit_period_inputs preserves implicit counterpart intent separately
from deliberate period selection/mapping. coadd_compatibility_error shares the core
correspondence/reuse checks without reducing or scanning counts.
The float-valued Run.field and Run.temperature convenience accessors
represent an explicit unknown (None) as NaN, so summaries and replay
identities can carry it without a fabricated zero.
Acquisition content facts and verification
Built-in loader reads attach an immutable SourceBinding to each Run.
The common load function and direct built-in loader calls accept checkpoint
and progress callbacks. Capture hashes the entire acquisition before and after
decoding, sharing one fact across acquired periods. Counts remain usable with
unknown provenance if content capture fails; cancellation raises. Sidecar monitor
files are outside this acquisition identity.
Explicit comparison accepts prepared declarations or caller-authored source roles:
from asymmetry.core.project import load_prepared_project
from asymmetry.core.data.acquisition import verify_sources
prepared = load_prepared_project("analysis.asymp")
facts = verify_sources(prepared.sources, checkpoint=check_cancelled)
# Each fact retains its expected declaration and independently observed bytes.
Pass candidates in declaration order to compare explicitly resolved relocated
paths. Verification does no search or substitution. Outcomes are matched,
changed, missing, legacy_unknown, and unreadable. An available
candidate without an expectation remains legacy_unknown; its observed digest
is returned separately. Missing/unreadable facts retain the original expectation.
One complete hash per candidate path is shared within a verification request,
while all source terms and coefficients remain distinct. Returned candidate
locators name the resolved target actually read, so retargeting an alias cannot
cache different bytes under another target. progress(done, total)
reports bytes for each file; checkpoint() may raise to cancel between chunks.
Cancellation returns no partial result. Neither operation mutates project history
or recomputes scientific results. Call long operations on a worker in GUI clients. The desktop disk-reference
fallback uses its existing cancellable scientific-input worker; collection and
serialization perform no acquisition reads.
Immutable byte identity, historical expectations, and explicit verification facts.
Content identity says nothing about computation compatibility or statistical independence. A missing expected digest cannot be reconstructed from today’s file.
- class asymmetry.core.data.acquisition.ContentIdentity(sha256)[source]
SHA-256 of the complete acquisition, independent of its locator.
- sha256
- classmethod read(path, **kwargs)[source]
Observe complete current bytes, with hash_file checkpoints/progress.
- __init__(sha256)
- class asymmetry.core.data.acquisition.SourceBinding(expected=None, observed=None)[source]
Saved expectation and actual read fact, with independent unknowns.
On a fresh acquisition both describe that read. Restoration retains the saved expectation (including None) and the new read’s observed fact.
- expected = None
- observed = None
- classmethod from_dict(value)[source]
Decode optional provenance; never promote an observed fact to expected.
- __init__(expected=None, observed=None)
- class asymmetry.core.data.acquisition.SourceOwner(address, active=False)[source]
An owned project address; only current inputs may accept replacements.
- address
- active = False
- __init__(address, active=False)
- class asymmetry.core.data.acquisition.SourceDeclaration(role, source_file, expected, run_number=None, period_number=None, coefficient=1.0, input_number=None, dae_period_number=None, owner=None)[source]
One ordered source role; matching content never merges scientific terms.
- role
- source_file
- expected
- run_number = None
- period_number = None
- coefficient = 1.0
- input_number = None
- dae_period_number = None
- owner = None
- __init__(role, source_file, expected, run_number=None, period_number=None, coefficient=1.0, input_number=None, dae_period_number=None, owner=None)
- class asymmetry.core.data.acquisition.SourceVerification(source, candidate_file, status, observed=None, diagnostic='')[source]
Fresh comparison only, never a persisted certification or state mutation.
- source
- candidate_file
- status
- observed = None
- diagnostic = ''
- __init__(source, candidate_file, status, observed=None, diagnostic='')
- asymmetry.core.data.acquisition.verify_sources(sources, *, candidates=None, checkpoint=<function <lambda>>, progress=<function <lambda>>)[source]
Compare caller-selected candidates; read each physical path once per request.
No path search, substitution, history edits, or recomputation occurs. Missing expectations remain legacy_unknown even when current bytes can be observed. Missing/unreadable candidates retain their separate availability outcomes. Cancellation raised by checkpoint aborts without returning partial facts.
Optional loader callbacks
The shared load boundary passes cancellation/progress callbacks only when a
loader’s call signature supports them. Built-in acquisition capture polls between
hash chunks and around decoding. A filepath-only external loader remains usable;
its opaque decode is polled immediately before and after it returns, and cannot
be cancelled internally through this interface. Unknown
capture remains unverified and is not replaced by the verifier’s candidate digest.
Periods
- asymmetry.core.io.periods.build_rf_difference_scan(runs, *, t_min=None, t_max=None, mode=PeriodMode.GREEN_MINUS_RED, order_key='field', method='integral', progress_callback=None, cancel_check=None)[source]
Build a fractional RF scan using the shared native-count scalar reducer.
integralsums corrected native counts before the ratio; G−R subtracts the period ratios and G+R pools prepared counts.differentialexplicitly requests the time-bin mean. Historical per-period curves support only that mean for G−R; they cannot reconstruct a count integral or pooled G+R. Dataset inputs require their verified histogram observation for count replay. Bounds are inclusive native sample centres in µs; omitted bounds use good bins.
Run range
- asymmetry.core.io.run_range.resolve_run_range(folder, first, last, *, prefix=None, ext=None)[source]
Expand
folder+ inclusive[first, last]run range to sorted files.Scans
folder(non-recursively) for files whose extension a loader claims — so sidecar logs (.txt/.mon) are ignored — parses the trailing digit group of each name as its run number, and returns the existing files whose run number falls in[first, last], sorted by run number. The match is padding-agnostic:MUSR00001276resolves to run1276regardless of zero-pad width.- Parameters:
folder (str or Path) – Directory holding the run files. Must exist and be a directory.
first, last (int) – Inclusive run-number bounds.
firstmust not exceedlast.prefix (str, optional) – Instrument/file prefix (e.g.
"MUSR"), matched case-insensitively against the leading text of each name. When None, the prefix is auto-detected from the files that fall in the range: exactly one prefix must be present, else aValueErrorlists the candidates so the caller can disambiguate.ext (str, optional) – Restrict the scan to a single extension (e.g.
"nxs"or".nxs"). When None, every loader-registered extension is considered.
- Returns:
list[pathlib.Path] – Existing files in
[first, last], sorted ascending by run number. Gaps are skipped silently — missing run numbers are simply absent, so a non-contiguous corpus yields the runs that do exist. An empty list means the folder held no matching runs in range (not an error).- Raises:
ValueError – If
folderdoes not exist or is not a directory, iffirst > last, or ifprefixis None and the in-range files carry more than one distinct prefix.