API¶

class musrpy.instruments.MuonInstrument(name, num_detectors, detector_groups, model_dict={}, mac=None, v1190=None, data=None, num_events=None, path=None, simana_histograms=None, sim_histograms=None)¶

The MuonInstrument object represents a muon spin spectroscopy instrument. It can be loaded with data from musrSim musrSimAna. The object has several methods to load this data, group the detectors, and to visualise and analyse the data.

Parameters

name (str) – Name of muon instrument
num_detectors (int) – Total number of detectors of the instrument. Used when loading and grouping detectors.
detector_groups (dict[str, list[int]] | dict[str, tuple[int, int]]) – How the detectors will be grouped.
model_dict (dict[str, Fitfunction]) – Optional. Where models fitted to data are stored.
mac (int) – Optional. Mac file number. Used when loading the data.
v1190 (int) – Optional. v1190 file number. Used when loading the data.
data (pd.DataFrame) – Optional. The raw or grouped detector data.
num_events (int) – Optional. Total number of events simulated. Defined in mac file via /run/beamOn command. Automatically obtained when loading data in.
path (str) – Optional. Path to directory. See section Creating a Muon instrument for details.
simana_histograms (list[str]) – Optional. List of histograms inside the .v1190.root tree. Obtained using get_histograms method.
sim_histograms (list[str]) – Optional. List of histograms inside the .root tree. Obtained using get_histograms method.

load_data(mac, v1190, path, bins=2000)¶

Loads data from ROOT histogram and parses into pandas dataframe with shape:

time detector1 detector2 ...
  .       .         .
  .       .         .
  .       .         .

Path must be to the folder containing the mac file and the data folder. See section Creating a Muon instrument for details. Data can be rebinned using the bins parameter. Note that this must be less than the number of bins defined inside the v1190 file.

Parameters

mac (int) – Mac file number of simulation to be loaded.
v1190 (int) – v1190 file number of simulation to be loaded.
path (str) – Path to directory containing mac file and data folder
bins (int) – Number of bins to put data into.

group_data()¶

Groups the detector histograms according to the detector_groups parameter. There must be data already loaded in using the load_data method. This methods transforms the data parameter dataframe into the following structure:

time    group1    group2 ...
  .       .         .
  .       .         .
  .       .         .

load_and_group_data(mac, v1190, path, bins=2000)¶

A convenience method that combines the load_data and group_data methods into a single method. It first calls load_data, then group_data.

Parameters

mac (int) – Mac file number of simulation to be loaded.
v1190 (int) – v1190 file number of simulation to be loaded.
path (str) – Path to directory containing mac file and data folder
bins (int) – Optional. Number of bins to put data into.

fit(name, function, start_time=0, end_time=15, initial_guess=None, bounds=None)¶

Fits curve to detector group histograms. Uses scipy’s curve_fit method Used by xx and xx methods. The resulting model will then be saved inside the model_dict attribute with key equal to the name parameter.

Parameters

name (str) – Name of detector group/pair to fit.
function (str) – Function to fit to data. Can be one of ExpDecayOsc, Sinusoid, ExpDecay, and Linear found in functions.
start_time (float) – Optional. Start time to regress from.
end_time (float) – Optional. End time to regress to.
initial_guess (list[float]) – Optional. List of initial parameters for regression. See curve_fit documentation for details. Default is obtained from functions.
bounds (tuple[list[float], list[float]]) – Optional. Bounds can be placed on the parameters. See curve_fit documentation for details.

plot_counts(group, plot_fit, start_time=0, end_time=15, save_path=None, show_plot=None, initial_guess=None, bounds=None)¶

Plots detector counts against time for a group. Option to plot fitted curve to data. Can plot just one group or multiple groups on one plot. Plots can be saved into a chosen directory.

Parameters

group (str | list[str]) – Detector grouping or list of groups to plot.
plot_fit (bool) – If true then the musrpy.instruments.MuonInstrument.fit method is called for the group(s) and is shown on the plot.
start_time (float) – Optional. Start time to regress from.
end_time (float) – Optional. End time to regress to.
save_path (str) – Optional. Will create a folder inside the specified directory and saves plot.
show_plot (bool) – Optional. If true then the plot will be shown when the method is called.
initial_guess (list[float]) – Optional. List of initial parameters for regression. See curve_fit documentation for details. Default is obtained from functions.
bounds (tuple[list[float], list[float]]) – Optional. Bounds can be placed on the parameters. See curve_fit documentation for details.

plot_asymmetry(pair, plot_fit, start_time=0, end_time=15, save_path=None, show_plot=None, initial_guess=None, bounds=None)¶

Plots asymmetry for a pair of groups. Option to plot fitted curve to data. Pairs can be created using the create_pair method.

Parameters

pair (str) – Group pair to plot.
plot_fit (bool) – If true then the musrpy.instruments.MuonInstrument.fit method is called for the pair and is shown on the plot.
start_time (float) – Optional. Start time to regress from.
end_time (float) – Optional. End time to regress to.
save_path (str) – Optional. Will create a folder inside the specified directory and saves plot.
show_plot (bool) – Optional. If true then the plot will be shown when the method is called.
initial_guess (list[float]) – Optional. List of initial parameters for regression. See curve_fit documentation for details. Default is obtained from functions.
bounds (tuple[list[float], list[float]]) – Optional. Bounds can be placed on the parameters. See curve_fit documentation for details.

get_histograms()¶

Returns lists of histograms contained in the .root and .v1190.root trees. These can then be plotted using the plot_histogram method. These lists are stored inside the simana_histograms and sim_histograms attributes.

Returns: Lists of histograms
Return type: tuple[list[str], list[str]]

plot_histogram(hist_name, bins=None, data_range=None, show_plot=None, save_path=None)¶

Method to plot other histograms stored inside the .root and .v1190.root trees. Can plot 2D histograms, 1D histograms and bar charts.

Parameters

hist_name (str) – Name of histogram to plot. Names of all histograms can be found using the get_histograms method.
bins (int) – Optional. Can rebin data. Default number of bins is determined from the data.
data_range (tuple[float, float] | tuple[tuple[float, float], tuple[float, float]]) – Optional. Range of data to plot. Format is (start, end) for 1D histograms, and ((start_x, end_x), (start_y, end_y)) for 2D histograms. Default is the full range of data in the tree.
show_plot (bool) – Optional. If true then the plot will be shown when the method is called.
save_path (str) – Optional. Will create a folder inside the specified directory and saves plot.

create_pair(pair_name, group_1, group_2)¶

Creates a pair object from the two given groups. This is saved as a new attribute of the MuonInstrument called pair_pair_name.

Parameters

pair_name (str) – Name of pair.
group_1 (str) – Name of first detector group in pair.
group_2 (str) – Name of second detector group in pair.

class musrpy.instruments.Pair(name, instrument, group_1, group_2)¶

An object representing a pair of detector groups. From this we can calculate the asymmetry between these two groups.

Parameters

name (str) – Name of pair.
instrument (MuonInstrument) – Associated MuonInstrument object.
group_1 (str) – Name of first (forward) detector group in pair.
group_2 (str) – Name of second (backward) detector group in pair.

get_alpha()¶

Estimates alpha (balance parameter) between the two groups. Used in calculation for asymmetry. Defined as sum(forward) / sum(backward).

Returns: Alpha (balance parameter)
Return type: float

get_asymmetry(alpha=None)¶

Calculates the asymmetry between the two groups. Defined as (forward - alpha * backward) / (forward + alpha * backward). Returns a pandas DataFrame object with the asymmetry, structured as:

time    asymmetry
  .       .
  .       .
  .       .

Parameters: alpha (float) – Optional. The balance parameter used in the calculation. By default, it is estimated using the get_alpha method.
Returns: Asymmetry dataframe.
Return type: pd.DataFrame

musrpy.models.exp_decay_osc(x, initial, asym, frequency, phase)¶

A decaying sinusoid function. A histogram of detector counts against time follows this model. Defined as

initial * np.exp(-0.455 * x) * (1 + asym * np.cos(frequency * x + phase))

Parameters

x (float) – The function variable.
initial (float) – Initial number of counts.
asym (float) – Asymmetry.
frequency (float) – Frequency of oscillations. Proportional to the strength of the transverse magnetic field.
phase (float) – Phase of oscillations.

Returns

Value of the function.

Return type

float

musrpy.models.sinusoid(x, amplitude, frequency, phase, offset)¶

A general sinusoid curve. See https://en.wikipedia.org/wiki/Sinusoidal_model . Used when fitting asymmetry.

Parameters

x (float) – The function variable.
amplitude (float) – Amplitude of sine wave.
frequency (float) – Frequency of sine wave.
phase (float) – Phase of sine wave.
offset (float) – Vertical offset of sine wave.

Returns

Value of the function.

Return type

float

musrpy.models.exp_decay(x, initial, decay)¶

An exponential decay model. Here the decay constant could be fixed at 0.455 as we are dealing with only muons decaying. See https://en.wikipedia.org/wiki/Exponential_decay .

Parameters

x (float) – The function variable.
initial – Initial number.
decay (float) – Decay constant.

Returns

Value of the function.

Return type

float

musrpy.models.linear(x, m, c)¶

A straight line y=mx+c.

Parameters

x (float) – The function variable.
m (float) – Gradient of line.
c (float) – Y-axis intercept of line.

Returns

Value of the function.

Return type

float

musrpy.models.functions¶

A dictionary containing standard initial guesses and graph labels for each function.

Type: dict[str, tuple[callable, list[float], str]]
Value: {“ExpDecayOsc”: (exp_decay_osc, [100, 0.2, 8.5, 1], “y = {0:.3f}*exp(-0.455*x)(1 + {1:.3f}*cos({2:.3f}*x + {3:.3f})”), “ExpDecay”: (exp_decay, [100, 0.455], “y = {0:.3f}*exp(-{1:.3f}*x)”), “Sinusoid”: (sinusoid, [0.2, 8.5, 0.1, 0.1], “y = {0:.3f}*cos({1:.3f}*x + {2:.3f}) + {3:.3f}”), “Linear”: (linear, [1, 1], “y = {0:.3f}*x + {:.3f}”)}

class musrpy.models.FitFunction(function, initial_guess=None, model=None, graph_label=None, rmse=None)¶

An object representing some function fitted to some data. Used by the plot_counts and plot_asymmetry methods when fitting data.

Parameters

function (str) – Name of function to be fitted to some data. Must be one of: ExpDecayOsc, Sinusoid, ExpDecay, and Linear.
initial_guess (list[float]) – Optional. Initial guess to use when fitting the data. By default it is determined from the functions parameter based on which function is being used for the fit.
model (tuple) – Optional. A tuple containing the parameters and the covariance of the parameters. See https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html for details. Is used by the musrpy.models.FitFunction.fit method.
graph_label (str) – Optional. The label which will appear on plots generated by the plot_counts and plot_asymmetry methods. By default it is determined from the functions parameter based on which function is being used for the fit.
rmse (float) – Optional. The root mean square error of the fit. Calculated in the musrpy.models.FitFunction.fit method

curve(x, *parameters)¶

Calls the function determined by the classes function parameter. Used in the plot_counts and plot_asymmetry methods.

Returns: The function evaluated at x.
Return type: float

fit(time, data, initial_guess=None, bounds=None, start_time=0, end_time=15)¶

Fits the data. Initial guess and bounds can be specified. Used in the plot_counts and plot_asymmetry methods.

Parameters

time (pd.DataFrame) – Independent variable, usually time.
data (pd.DataFrame) – Dependent variable.
initial_guess (list[float]) – Optional. List of initial parameters for regression. See curve_fit documentation for details. Default is obtained from functions.
bounds (tuple[list[float], list[float]]) – Optional. Bounds can be placed on the parameters. See curve_fit documentation for details.
start_time (float) – Optional. Start time to regress from.
end_time (float) – Optional. End time to regress to.

API¶

Previous topic

This Page