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

LoadMuonNexus v2¶

Summary ¶

The LoadMuonNexus algorithm will read the given NeXus Muon data file Version 2 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. For single period data, the optional parameters can be used to control which spectra are loaded into the workspace. If spectrum_min and spectrum_max are given, then only that range to data will be loaded. If a spectrum_list is given than those values will be loaded.

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

Version Identification ¶

To be identified as a version 2 muon nexus file, the nexus file must have a IDF_version or idf_version item in its main group with an integer value of 2 and also a definition item with string value "muonTD" or "pulsedTD", else it will be identified as version 1.

The following properties apply only to Version 1:

AutoGroup
MainFieldDirection
DeadTimeTable
DetectorGroupingTable

Time series data ¶

The log data in the Nexus file (NX_LOG sections) will be loaded as TimeSeriesProperty data within the workspace. Time is stored as seconds from the Unix epoch.

Errors ¶

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

Details of data loaded ¶

Here are more details of data loaded from the Nexus file:

Description of Data	Found in Nexus file (within the main entry)	Placed in Workspace (Workspace2D) or output
Detector Data	First group of class NXData (henceforth referred as [DET])	Histogram Data of workspace
Instrument	group `Instrument`	Workspace instrument as loaded by LoadInstrumentFromNexus
Spectrum of each workspace index	[DET]``/spectrum_index``	Spectra-Detector mapping of workspace (see below)
Title (optional)	`title`	`title` in workspace
Note orcomment (optional)	`note`	`comment` in workspace
Time Zero (optional)	`instrument/detector_fb/time_zero` if found	TimeZero property
First good time (optional)	`instrument/detector_fb/first_good_time` if found	FirstGoodData property
Run	various places as shown later on	Run object of workspace
Sample name	`sample/name`	`name` in Sample Object of workspace
Time series	`sample/` groups of class `NXLog`	time series log in run object

Run Object ¶

LoadMuonNexus does not run LoadNexusLogs to load run logs. Information is loaded as follows:

Nexus	Workspace run object
`title`	`run_title`
(data)	`nspectra`
`start_time`	`run_start`
`end_time`	`run_end`
`run/good_total_frames`	`goodfrm`
`run/number_periods`	`nperiods`
(start & end times)	`dur_secs`

(data) indicates that the number is got from the histogram data in an appropriate manner.

Spectra-detector mapping ¶

Unlike muon v1 NeXus files, v2 files have the possibility that one spectrum maps to multiple detectors. This mapping is handled as follows:

The spectrum numbers are in run/detector_fb/spectrum_index.

The spectrum spectrum_index[j] maps to detector_count[j] detectors. Their detector IDs are contained in detector_list, starting at the index detector_index[j].

If the above optional entries detector_count, detector_list and detector_index are not present in the file, it is assumed that the mapping is one-to-one (spectrum number = detector ID). This is the case for most ISIS data at the moment.

Child Algorithms used ¶

The ChildAlgorithms used by LoadMuonNexus are:

LoadMuonNexus v1 - this loads the muon nexus file if not identified as version 2. It in turn uses the following child algorithm:
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.

Previous Versions ¶

Version 1 ¶

Version 1 supports the loading version 1.0 of the muon nexus format. This is still in active use, if the Load algorithm detects that it has been asked to load a previous version muon nexus file it will call the previous version of the LoadMuonNexus algorithm to perform the task.

See LoadMuonNexus v1 for more details about version 1.

Some algorithm properties apply to Version 1 only.

Usage ¶

Note

To run these usage examples please first download the usage data, and add these to your path. In Mantid this is done using Manage User Directories.

Example - Load ISIS muon MUSR dataset:

# Load MUSR dataset
ws = Load(Filename="MUSR00015189.nxs",EntryNumber=1)
print("Workspace has  {}  spectra".format(ws[0].getNumberHistograms()))

Output:

Workspace has  64  spectra

Example - Load event nexus file with time filtering:

# Load some spectra
ws = Load(Filename="MUSR00015189.nxs",SpectrumMin=5,SpectrumMax=10,EntryNumber=1)
print("Workspace has  {}  spectra".format(ws[0].getNumberHistograms()))

Output:

Workspace has  6  spectra

Example - Load dead times into table:

# Load some spectra
ws = Load(Filename="emu00006473.nxs",SpectrumMin=5,SpectrumMax=10,DeadTimeTable="deadTimeTable")
tab = mtd['deadTimeTable']
for i in range(0,tab.rowCount()):
    print("{} {:.12f}".format(tab.cell(i,0), tab.cell(i,1)))

Output:

0.001611122512
0.002150168177
0.010217159986
0.004316862207
0.007436056621
0.004211476538

Categories: AlgorithmIndex | DataHandling\Nexus | Muon\DataHandling

Source ¶

C++ header: LoadMuonNexus2.h

C++ source: LoadMuonNexus2.cpp