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 one MuonDataset and 3+ period files a list. See asymmetry.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 period is 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 MuonDataset for a single period.

Parameters:
  • data – A loaded run: either a single MuonDataset (single-period file, or a combined two-period file) or the list returned for 3+ period files.

  • period – Period selector — see resolve_period_index().

Returns:

MuonDataset – The requested period with its own time/asymmetry/error and 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, a list of datasets (as returned for 3+ period files), or a Run.

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.

period may be a 1-based integer period number, a numeric string, or — when count == 2 — a "red"/"green" label (or PeriodMode member). Raises ValueError for unknown labels or out-of-range numbers and TypeError for 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

class asymmetry.core.io.base.LoaderRegistry[source]

Bases: object

Central registry of available file-format loaders.

classmethod register(loader_cls)[source]
classmethod get_loader(filepath, fmt=None)[source]
classmethod supported_extensions()[source]
classmethod file_dialog_filter()[source]

Build a Qt file-dialog filter string from registered loaders.

Returns:

str – Filter string suitable for QFileDialog, including an aggregate “All Supported Files” entry, one entry per loader format, and a trailing “All files (*)” fallback.

Loaders

Base loader

class asymmetry.core.io.base.BaseLoader[source]

Bases: ABC

Interface 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 MuonDataset objects.

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: BaseLoader

Read ISIS muon .nxs files 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)").

load(filepath)[source]

Load a NeXus file and return reduced asymmetry dataset(s).

Parameters:

filepath – Path to a NeXus file.

Returns:

MuonDataset or list[MuonDataset] – Single dataset for single-period and two-period files. Files with more than two periods return one dataset per period.

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: BaseLoader

Read PSI .bin and .mdu raw 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 MuonDataset objects.

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: BaseLoader

Read 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 MuonDataset objects.

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_bin attribute on the counts dataset (one value per detector, so PSI-style staggered t0 survives) plus histogram_data_1/time_zero in microseconds from the start of acquisition. first_good_bin / last_good_bin are 1-based inclusive attributes on the same dataset. A round trip through NexusLoader is 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 grouping as 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/simulation for 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. Raises ValueError for runs without histograms or with ragged histogram lengths, and ImportError when h5py is unavailable.

With effective=True every t0-derived field — the per-detector bins, the exact time_zero, the good window and corrected_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
to_dict()[source]

Return the fixed-algorithm canonical codec.

classmethod from_dict(value)[source]

Decode a recorded identity; absence remains unknown.

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
to_dict()[source]

Encode both contexts without resolving any locator.

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.

asymmetry.core.data.acquisition.constituent_sources_for_project(dataset)[source]

Retain saved term expectations, with fresh observations kept separate.

Original role/order/selection/coefficient context belongs to the saved combination. A current reconstructed curve has its own result recipe.

asymmetry.core.data.acquisition.restore_constituent_expectations(dataset, saved)[source]

Transfer historical expected rows; absence stays unknown after reconstruction.

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.

integral sums corrected native counts before the ratio; G−R subtracts the period ratios and G+R pools prepared counts. differential explicitly 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: MUSR00001276 resolves to run 1276 regardless 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. first must not exceed last.

  • 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 a ValueError lists 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 folder does not exist or is not a directory, if first > last, or if prefix is None and the in-range files carry more than one distinct prefix.