MuonDataLib Tutorial 1: Getting started

Introduction

The MuonDataLib package is for processing ISIS muon event data into a muon nexus version 2 histogram file. The processing includes:

  • Converting the events into histograms

  • Filtering the events based on the time at which they occurred

The histogram nexus file is currently only compatible with Wimda.

Getting started

The first task is to install the latest version of MuonDataLib. This can easily be done by using Python (supports 3.8 to 3.12 on Windows, Mac and Linux) by using pip, see here for more details.

Data file paths

When using files in Python the path is always relative from where the code is ran (this does not have to be the same place as the file). It is possible to force the path to always be relative to your file with the following code

[1]:

import os

# path_to_this_dir = os.path.dirname(__file__)
name = 'file.txt'

# path_to_file = os.path.join(path_to_this_dir, '..', '..', '..', '..', 'test', 'data_files', name)
path_to_file = os.path.join( '..', '..', '..', '..', 'test', 'data_files', name)

The commented out line gets the path to the directory (folder) that contains this file, but this does not work in Jupyter and is not needed. The name is the name of the file we are interested in, for this example we assume its an input file.

This tutorial has 2 directories

  1. Tutorials

  2. Output_files

this file in in Tutorials as part of the documentation, so to get to the input files from the tests then we need to go back a few directories (.. is go up once). The final line adds the paths together, including the data_files.

Since these examples are all Jupyter notebooks, they will always be run from the file location. So we will be omitting the path_to_this_dir as it is superfluous.

Creating a nexus file

The simplest user case is creating a histogram nexus file from events data. The first step is to define the input event file and output histogram nexus file.

[2]:

input_file = os.path.join('..', '..', '..', '..', 'test', 'data_files', 'HIFI00195790.nxs')

output_file = os.path.join('..', 'Output_files', 'HIFI00195790.nxs')

The next step is to import the event data loader from MuonDataLib.

[3]:

from MuonDataLib.data.loader.load_events import load_events

The following two steps will load the event data and then save the histogram nexus file.

The load_events command takes two arguments, the event file and the number of detectors for that instrument (for HIFI that is 64). It the returns a muon event data object.

The save_histograms method of the muon event data object creates a histogram nexus file with the name given by output_file.

[4]:

event_data = load_events(input_file, 64)
event_data.save_histograms(output_file)

WARNING: The metadata **RUN** is missing. Using fallback values
WARNING: The metadata **TITLE** is missing. Using fallback values
WARNING: The metadata **EXPERIMENT IDENTIFIER** is missing. Using fallback values

This code should have written the histogram nexus file defined by output_file. To test that it has written correctly you can load it into Wimda.