\(\renewcommand\AA{\unicode{x212B}}\)

LoadMuonNexus v1

../_images/ImageNotFound.png

Enable screenshots using DOCS_SCREENSHOTS in CMake

Summary

The LoadMuonNexus algorithm will read the given NeXus Muon data file Version 1 and use the results to populate the named workspace. LoadMuonNexus may be invoked by LoadNexus if it is given a NeXus file of this type.

Properties

Name

Direction

Type

Default

Description

Filename

Input

string

Mandatory

The name of the Nexus file to load. Allowed extensions: [‘.nxs’]

OutputWorkspace

Output

Workspace

Mandatory

The name of the workspace to be created as the output of the algorithm. For multiperiod files, one workspace will be generated for each period

SpectrumMin

Input

number

0

Index number of the first spectrum to read

SpectrumMax

Input

number

Optional

Index of last spectrum to read (default the last spectrum)

SpectrumList

Input

int list

Array, or comma separated list, of indexes of spectra to load. If a range and a list of spectra are both supplied, all the specified spectra will be loaded.

AutoGroup

Input

boolean

False

Determines whether the spectra are automatically grouped together based on the groupings in the NeXus file, only for single period data (default no). Version 1 only.

EntryNumber

Input

number

0

0 indicates that every entry is loaded, into a separate workspace within a group. A positive number identifies one entry to be loaded, into one workspace

MainFieldDirection

Output

string

Output the main field direction if specified in Nexus file (run/instrument/detector/orientation, default longitudinal). Version 1 only. Allowed values: [‘Transverse’, ‘Longitudinal’]

TimeZero

Output

number

Time zero in units of micro-seconds (default to 0.0)

FirstGoodData

Output

number

First good data in units of micro-seconds (default to 0.0)

LastGoodData

Output

number

Last good data in the OutputWorkspace’s spectra

TimeZeroList

Output

dbl list

A vector of time zero values

TimeZeroTable

Output

Workspace

TableWorkspace containing time zero values per spectra.

CorrectTime

Input

boolean

True

Boolean flag controlling whether time should be corrected by timezero.

DeadTimeTable

Output

Workspace

Table or a group of tables containing detector dead times. Version 1 only.

DetectorGroupingTable

Output

Workspace

Table or a group of tables with information about the detector grouping stored in the file (if any). Version 1 only.

Description

The algorithm LoadMuonNexus will read a Muon Nexus data file (original format) and place the data into the named workspace. The file name can be an absolute or relative path and should have the extension .nxs or .NXS. If the file contains data for more than one period, a separate workspace will be generated for each. After the first period the workspace names will have “_2”, “_3”, and so on, appended to the given workspace name. The optional parameters can be used to control which spectra are loaded into the workspace. If SpectrumMin and SpectrumMax are given, then only that range of data will be loaded. If a SpectrumList is given, then those values will be loaded. If a range and a list are supplied, the algorithm will load all the specified spectra.

  • TODO get XML descriptions of Muon instruments. This data is not in existing Muon Nexus files.

Spectra-detector mapping

For all v1 muon Nexus files, there is a one-to-one mapping between spectrum number and detector ID.

Time series data

The log data in the Nexus file (NX_LOG sections) will be loaded as TimeSeriesProperty data within the workspace. Time (stored as seconds from the Unix epoch in the Nexus file) is corrected relative to the start time found in run/start_time.

This time series data comprises various values logged by SECI and includes magnetic fields, temperatures, status codes, count rate and beam logs.

See LoadMuonLog v1 for more details.

Errors

The error for each histogram count is set as the square root of the number of counts.

Time bin data

The corrected_times field of the Nexus file is used to provide time bin data and the bin edge values are calculated from these bin centre times.

Multiperiod data

To determine if a file contains data from more than one period the field switching_states is read from the Nexus file. If this value is greater than one it is taken to be the number of periods, \(N_p\) of the data. In this case the \(N_s\) spectra in the histogram_data field are split with \(N_s/N_p\) assigned to each period.

Dead times and detector grouping

Muon Nexus v1 files might contain dead time and detector grouping information. These are loaded as TableWorkspaces of the format accepted by ApplyDeadTimeCorr v1 and MuonGroupDetectors v1 accordingly. These are returned if and only if names are specified for the properties. For multi-period data workspace groups might be returned, if information in the Nexus files contains this information for each period.

If the file contains no grouping entry (or the entry is full of zeros), the grouping will be loaded from the IDF instead. If this also fails, a dummy grouping will be created. In either case, a message will be displayed in the log to explain this.

Details of data loaded

Here are more details of data loaded from the Nexus file. Conventionally, the first NX_ENTRY is called run and the first NX_DATA under this is called histogram_data_1, and these names are used below.

Description of Data

Found in Nexus file

Placed in Workspace (Workspace2D) or output

Detector data

  • Times (X): run/histogram_data_1/corrected_time

  • Counts (Y): run/histogram_data_1/counts (2D array of counts in each time bin per detector)

  • Errors: square root of counts

Histogram data of workspace

Instrument

Name from run/instrument/name

Uses child algorithm LoadInstrument to load the instrument of that name

Workspace instrument

(as loaded by LoadInstrument from IDF)

Title (optional)

run/title

Workspace title

Comment (optional)

run/notes

Workspace comment

Time zero (optional)

run/histogram_data_1/time_zero

TimeZero property

First good data (optional)

Calculated from first good bin and bin size.

  • First good bin: run/histogram_data_1/counts (attribute first_good_bin)

  • Bin size: run/histogram_data_1/resolution

FirstGoodData property

(First good data - time zero) also goes in run object under the name FirstGoodData

Detector grouping table (optional)

run/histogram_data_1/grouping

If not present, or invalid, loads from IDF.

If that also fails, creates dummy grouping (all detectors in one group).

DetectorGroupingTable property

Dead time table (optional)

run/instrument/detector/deadtimes

DeadTimeTable property

Main field direction (optional)

run/instrument/detector/orientation

Assumed to be longitudinal if not present

MainFieldDirection property

Also in run object as main_field_direction

Sample name

run/sample/name

Name of sample object

Run

See below

Run object (see below)

Run Object

Log values are loaded into the workspace run object as follows:

Nexus

Workspace run object

run/title

run_title

(data)

nspectra

run/start_time

run_start

run/stop_time

run_end

run/duration

dur, dur_secs (same), durunits = 1 (seconds)

run/number

run_number

run/sample/temperature

sample_temp

run/sample/magnetic_field

sample_magn_field

run/instrument/beam/frames_good (for single-period data)

(If frames_good not present, use frames instead.)

goodfrm (number of good frames)

run/instrument/beam/frames_period_daq (for multi-period data)

Other NX_LOG entries under run

time series (via LoadMuonLog)

ChildAlgorithms used

The ChildAlgorithms used by LoadMuonNexus are:

  • LoadMuonLog v1 - this reads log information from the Nexus file and uses it to create TimeSeriesProperty entries in the workspace.

  • LoadInstrument v1 - this algorithm looks for an XML description of the instrument and if found reads it.

  • LoadInstrumentFromNexus v1 - this is called if the normal LoadInstrument fails. As the Nexus file has limited instrument data, this only populates a few fields.

Categories: AlgorithmIndex | DataHandling\Nexus | Muon\DataHandling

Source

C++ header: LoadMuonNexus.h

C++ source: LoadMuonNexus.cpp