MuonDataLib API documentation: MuonData 
=========================================

`data.muon_data`.MuonData
--------------------------
An object that stores the relevant information for muon data (as definied by NeXus version 2).This is automatically created by `load_events`. 

**Required Parameters:** 
    - `sample`: The sample data. 
    - `raw_data`: The raw data (as defined by NeXus group). 
    - `source`: The source data (as defined by NeXus group). 
    - `periods`: The period data (as defined by NeXus group). 
    - `detector1`: The detector 1 data (as defined by NeXus group). 

**Returns:** MuonData object. 


`data.muon_data.MuonData`.save_histograms
------------------------------------------
Method for saving a MuonData object to a NeXus v2 histogram file This will skip calculating the filters if the cache is occupied. If just the resolution has changed it will not alter the filtered values. 

**Required Parameters:** 
    - `file_name`: The name of the file to save the NeXus v2 histogram file to. 

**Optional Parameters:** 
    - `N_threads`: The amount of parallelisation *Default value:* `1`.

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.save_histograms("HIFI00001_all.nxs",  resolution=0.01) 


`data.muon_data.MuonData`.histogram
------------------------------------
A method for constructing a histogram from a MuonData object. This method is helpful for checking results. This will skip calculating the filters if the cache is occupied. If just the resolution has changed it will not alter the filtered values. 


**Optional Parameters:** 
    - `N_threads`: The amount of parallelisation *Default value:* `1`.

**Returns:** A matrix of histograms (period, spectrum number, bin) and bin edges. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    hist, bins = data.histogram(resolution=0.01) 


`data.muon_data.MuonData`.set_histogram_settings
-------------------------------------------------
Change the histogram bounds and bin width. 


**Optional Parameters:** 
    - `min_time`: The lower time bound for the histogram. *Default value:* `0.0`.
    - `max_time`: The upper time bound for the histogram. *Default value:* `32.768`.
    - `num_bins`: The number of bins to use in the histogram. *Default value:* `2048`.


`data.muon_data.MuonData`.get_peak_property_histogram
------------------------------------------------------
Method for getting the histogram and bins for a specific property (e.g. Amplitude) of the peak used to generate the event in the NeXus v2 histogram file. The results are never filtered. 

**Required Parameters:** 
    - `name`: The name of the peak propertry to be histogrammed. Current peak property options are: Amplitudes 

**Returns:** A histogram of the distribution for the peak property and the bins 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    hist, bins = data.get_peak_property_histogram("Amplitudes") 


`data.muon_data.MuonData`.keep_data_peak_property_above
--------------------------------------------------------
Method for discriminating/filtering of the histogram on a specific property (e.g. Amplitude) of the peak used to generate the event in the NeXus v2 histogram file. Only data with greater than the user specified value will be kept. 

**Required Parameters:** 
    - `name`: The name of the peak propertry to be histogrammed. Current peak property options are: Amplitudes 
    - `value`: Only events with values greater than this will be used in the histogram. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.keep_data_peak_property_above("Amplitudes", 1.2) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.delete_data_peak_property_above
----------------------------------------------------------
Method to remove the discriminating/filtering of the histogram on a specific property (e.g. Amplitude) of the peak used to generate the event in the NeXus v2 histogram file. 

**Required Parameters:** 
    - `name`: The name of the peak propertry to be removed from filtering. Current peak property options are: Amplitudes 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.keep_data_peak_property_above("Amplitudes", 1.2) 
    data.delete_data_peak_property_above("Amplitudes", 1.2) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.add_sample_log
-----------------------------------------
A method to manually add a sample log to a MuonData object. 

**Required Parameters:** 
    - `name`: The name of the sample log. 
    - `x_data`: The x values for the sample log (time in seconds). 
    - `y_data`: The y values for the sample log 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    import numpy as np 
    data = load_events("HIFI00001.nxs"), 64 
    x_data, y_data = np.load("Temp.txt") 
    data.add_sample_log("sample_Temp", x_data, y_data) 


`data.muon_data.MuonData`.keep_data_sample_log_below
-----------------------------------------------------
A method to remove all frames containing data with a value above some threshold value for a specific sample log, when creating a histogram from a MuonData object. The histogram will be created with only complete frames of data. 

**Required Parameters:** 
    - `log_name`: The name of the sample log to apply the fitler to. 
    - `max_value`: The maximum log value that will be kept after the filter is applied. In the same units as the y values for the sample log. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.keep_data_sample_log_below("Temp", 5) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.keep_data_sample_log_above
-----------------------------------------------------
A method to remove all frames containing data with a value below some threshold value for a specific sample log, when creating a histogram from a MuonData object. The histogram will be created with only complete frames of data. 

**Required Parameters:** 
    - `log_name`: The name of the sample log to apply the fitler to. 
    - `min_value`: The minimum log value that will be kept after the filter is applied. In the same units as the y values for the sample log. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.keep_data_sample_log_above("Temp", 1.5) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.keep_data_sample_log_between
-------------------------------------------------------
A method to only keep frames containing data between a pair of values for a specific sample log, when creating a histogram from a MuonData object. The histogram will be created with only complete frames of data. 

**Required Parameters:** 
    - `log_name`: The name of the sample log to apply the fitler to. 
    - `min_value`: The minimum log value that will be kept after the filter is applied. In the same units as the y values for the sample log. 
    - `max_value`: The maximum log value that will be kept after the filter is applied. In the same units as the y values for the sample log. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs, 64") 
    data.keep_data_sample_log_between("Temp", 1.5, 2.7) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.delete_sample_log_filter
---------------------------------------------------
A method to delete a filter that acts upon sample logs from the MuonData object. 

**Required Parameters:** 
    - `name`: The name of the sample log filter to remove. Histograms need to be recalculated to upate the data. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.keep_data_sample_log_between("Temp", 1.5, 2.7) 
    data.delete_sample_log_filter("Temp") 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.only_keep_data_time_between
------------------------------------------------------
A method that only keeps complete frames from the specified time range, when creating histograms. The histogram will be created with only complete frames of data. 

**Required Parameters:** 
    - `name`: A unique name to identify the filter. 
    - `start`: The start time, in seconds, for the filter. The filter is applied when creating a histogram. 
    - `end`: The end time in seconds for the filter.The filter is applied when creating a histogram. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.only_keep_data_time_between("Beam on", 5.8, 200.1) 
    hist, bins = data.histogram() 


`data.muon_data.MuonData`.delete_only_keep_data_time_between
-------------------------------------------------------------
A method that removes the filter for keeping data within a specific time range, when creating a histograms. 

**Required Parameters:** 
    - `name`: The name of the time filter to remove. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.only_keep_data_time_between("Beam on", 5.8, 200.1) 
    data.delte_only_keep_data_time_between(Beam on") 


`data.muon_data.MuonData`.remove_data_time_between
---------------------------------------------------
A method to exclude data between two specified times from a MuonData object, when creating a histogram. If the filter only occupies part of the frame, the whole frame is discarded from the histogram genetation. 

**Required Parameters:** 
    - `name`: A unique name to identify the filter. 
    - `start`: The time to start removing data from, in seconds. 
    - `end`: The last time to remove data from, in seconds. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.remove_data_time_between("Beam off", 11.3, 34.6) 


`data.muon_data.MuonData`.delete_remove_data_time_between
----------------------------------------------------------
A method to delete a filter from the MuonData object that removes data between two user defined times. 

**Required Parameters:** 
    - `name`: The name of the time filter to remove when generating histograms 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.remove_data_time_between("Beam off", 11.3, 34.6) 
    data.delete_remove_data_time_between("Beam off") 


`data.muon_data.MuonData`.clear_filters
----------------------------------------
A method to remove all of the filters from the MuonData object. 


**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    # Add a filter 
    data.only_keep_data_time_between(1.0, 10.) 
    # Remove the filter 
    data.clear_filters() 


`data.muon_data.MuonData`.report_filters
-----------------------------------------
A method to return a dataclass of the filters that are currently active on the MuonData object. 


**Returns:** A Filters dataclass of the current filters 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    filters = data.report_filters() 


`data.muon_data.MuonData`.load_filters
---------------------------------------
A method to read and add filters to a MuonData object from a JSON file. 

**Required Parameters:** 
    - `file_name`: The name of the file, that contains the filters to be read and added to the MuonData object. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.load_filters("example_filters.json") 


`data.muon_data.MuonData`.save_filters
---------------------------------------
A method to save the current active filters from a MuonData object to a JSON file. 

**Required Parameters:** 
    - `file_name`: The name and path of the file to save to a NeXu v2 file. 

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    data.only_keep_data_time_between("Beam on", 5.8, 200.1) 
    data.keep_sample_log_below("Temp", 5.2) 
    data.save_filters("example_filters.json") 


`data.muon_data.MuonData`.get_frame_start_times
------------------------------------------------
A method to get the list of frame start times in seconds from a MuonData object. 


**Returns:** A list of the frame start times in seconds.  

**Example:** 

.. code:: python
 
    from MuonDataLib.data.loader.load_events import load_events 
    data = load_events("HIFI00001.nxs", 64) 
    start_times = data.get_frame_start_times()