-
Notifications
You must be signed in to change notification settings - Fork 8
Quickstart Guide
If you've already installed MULE and initialised it with no issues you should see your terminal displaying something along the lines of:
(MULE-3.12-10-24) user@local_machine:MULE$
This initial part (MULE-3.12-10-24) is the conda environment, which controls the required packages for MULE. To reinitialise MULE in a new terminal, go to the MULE directory and rerun source setup.sh.
MULE works by taking some form of input; a binary file to be decoded, an ascii file* to be reformatted, or already processed h5 files that require some form of further processing.
In our examples below, we'll be working with CAEN digitiser data:
Here we will be using WaveDump 1 data produced using a V1730B digitiser. The data is called wave6.dat; the standard output from channel 6 of a WD1 digitiser. Lets say we saved this data in ~/Downloads/test_data/:
(MULE-3.12-10-24) user@local_machine:MULE$ cd ~/Downloads/QS_directory/
(MULE-3.12-10-24) user@local_machine:QS_directory$ ls
wave6.datYou first want to generate a config for this data. Example configs are found here.
Lets write a WaveDump 1 config, we'll call it WD1_config.conf:
[required]
process = 'decode' # the process you wish to apply, currently decode is the only available choice.
wavedump_edition = 1 # wavedump edition for this processing
sample_size = 2 # the sample size in ns between your data points. digitiser specific
file_path = './wave6.dat' # input path
save_path = './decoded_ch6.h5' # output path
[optional] # you don't need to fill these in
overwrite = False # overwrite the prior data
print_mod = 100 # how many events should occur before an update print is output.So your directory should now look like this:
(MULE-3.12-10-24) user@local_machine:QS_directory$ ls
wave6.dat WD1_config.confYou can then write:
(MULE-3.12-10-24) user@local_machine:QS_directory$ mule proc WD1_config.conf
and thats it! MULE should be decoding your WD1 data into a h5 file as we speak!
Once its finished running you will be able to open a h5 file within python like so:
>> import pandas as pd
>> import sys
>> sys.path.append("~/Documents/MULE/")
>> from packs.core.io import reader
>> decoded_event_info = pd.read_hdf('decoded_ch6.h5', 'RAW/event_info')
>> print(decoded_event_info)
event_number timestamp samples sampling_period channels
0 0 44253 130 2 1
1 1 169253 130 2 1
2 2 294255 130 2 1
3 3 419255 130 2 1
4 4 544255 130 2 1
... ... ... ... ... ...
9997 9997 1249674263 130 2 1
9998 9998 1249799263 130 2 1
9999 9999 1249924265 130 2 1
10000 10000 1250049265 130 2 1
10001 10001 1250174265 130 2 1
[10002 rows x 5 columns]
>> # read in the rwf
>> decoded_data = reader('decoded_ch6.h5', 'RAW', 'rwf')
>> print(decoded_data)
>> <generator object reader at 0x7c4e2b5bf9a0>
>> # ^^ generator object as raw waveforms can be quite big!
>> row = next(decoded_data)
>> print(row.dtype.names) # print the columns
('event_number', 'channels', 'rwf')
>> print(row) # print the row
(0, 0, [10553, 11003, 10745, 11890, 13307, 15866, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16383, 16125, 12541, 5370, 2746, 2810, 2106, 2298, 1530, 1786, 1273, 1274, 763, 1274, 761, 786, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]])The readout to a pandas dataframe for raw waveforms is mildly annoying at the moment, this will be fixed soon! (issue #59)
To be written
Warning
These features are more untested than the regular features, and aren't available in the master branch. It is used as an example to demonstrate the extendability of MULE for your own purposes.
To be written
*ascii decoding not yet implemented.
Features for averaging the waveforms in a single or multiple H5 files are available in the ana pack. This includes options for baseline subtractions, baseline suppression and secondary peak removal. The output waveform is saved as an H5 file.
An example config for using this feature looks like this:
[required]
files = ['waveforms.h5'] # files to average
window_args = {
'WINDOW_START' : 4e2, # start of the signal region within the waveform
'WINDOW_END' : 3e4, # end of the signal region within the waveform
'BASELINE_POINT_1' : 1e6, # first baseline position
'BASELINE_POINT_2' : 1.5e6, # second baseline position
'BASELINE_RANGE_1' : 40e3, # range around the first baseline position
'BASELINE_RANGE_2' : 40e3} # range around the second baseline position
bin_size = 4 # time spacing between bins
chunk_size = 5 # number of waveforms passed through the processing at a time
# with more memory, you can have a much larger chunk size
negative = True # boolean for whether the waveform is negative or not
baseline_mode = 'median' # baseline subtraction method (median, mean, or none)
verbose = 1 # verbosity of the function
peak_threshold = 1000 # Extra peaks after the waveform window are rejected.
# `peak_threshold` describes the maximum height at which
# values within a waveform after the `WINDOW_END` can exist
# before the waveform is rejected.
suppression_threshold = 10 # values below this within the waveform will be set to 0
overwrite = True # overwrite an existing file
save_path = 'average_waveform.h5' # save path of the filePlease ensure these ranges and windows don't overlap. It is helpful to visualise some waveforms to figure the window arguments out before using the average waveform function.
To use this feature, setup the config file and enter: mule ana average_waveform.conf.
Return to The Saddle.