pidp_tools.visualization module

This module contains all of the tools that are used for visualization.

pidp_tools.visualization.BCal_module()[source]

Displays a 2D model of a single Barrel Calorimeter (BCal) module, showing sector and layer segmentations.

pidp_tools.visualization.BCal_plot_2D()[source]

Displays a 2D plot of the modules of the Barrel Calorimeter (BCal).

pidp_tools.visualization.BCal_plot_3D()[source]

Displays a 3D model of the modules of the Barrel Calorimeter (BCal).

class pidp_tools.visualization.CDC_plot_2D(rings, title='Wire Positions in the GlueX CDC', wire_positions=None, showlegend=True)[source]

Bases: object

Creates a 2D model of the straws of the CDC.

Parameters:

rings : list

A list of rings to plot. All straws from the selected ring will be drawn. Each ring should be an integer between 1 and 28.

title : str, default “Wire Positions in the GlueX CDC”

The title of the figure.

wire_positions : wirePositions(), default None

A wirePositions() object to reference detector coordinates. By default, one will be created. However, if you wish to avoid creating multiple instances, you can provide one that is already created.

showlegend : bool, default True

Displays a legend to the right of the model. If True, displays the legend.

Attributes:

figure : plotly.graph_objects.Figure

A plotly figure that displays the requested rings of the GlueX CDC.

display(**kwargs)[source]

Displays the 2D CDC plot. This is done by calling the CDC_plot_2D.update_figure() method.

Parameters:

**kwargs:

The following keyword arguments correspond to the arguments of the track_fitting.update_figure() method. Each of these keyword arguments should be used for every call. Each of these keyword arguments can be assigned one of the following:

  • A tuple of the form “(min_value, max_value, step)” for numerical (float/int) arguments, which will generate a slider for the argument in question.

  • A boolean for boolean arguments, which will generate a checkbox, which allows the user to toggle the argument.

  • A list of strings or tuples, which will produce a dropdown menu of the provided options. If strings, the values in the dropdown will be passed directly to the CDC_plot_2D.update_figure() method. If a list of tuples is passed, they should be of the form (label, value), where the dropdown options are the “labels”, and the corresponding value to be passed to CDC_plot_2D.update_figure() is the “value”.

  • An instance of ipywidgets.widgets.interaction.fixed, which represents that the provided value cannot be changed by the user. No widget will be generated for this argument.

The below list of keyword arguments specifies the expected type of the arguments.

z : float or int

The z coordinate of the slice of the CDC you want to look at. Should be between 0 and 175 (this quantity is assumed to be in cm).

rings : list

A list of rings to be displayed. Each of the elements of this list should be an int, and should be between 1 and 28.

Examples:

>>> fig = CDC_plot_2D()
>>> fig.update()
>>> fig.display(z=(0,175,0.1), rings=fixed([1,2,3]))

The result of this code is a plot with a slider that allows the user to look at different z-slices of the CDC. The rings shown are fixed.

show()[source]

Shows the CDC plot track fitting applet. This is a wrapper method for plotly.graph_objects.Figure.show

update(*args, **kwargs)[source]

Updates the applet. This is a wrapper method for plotly.graph_objects.Figure.update(). Refer to its documentation for a list of all possible arguments.

update_figure(z=0, rings=[])[source]

Updates and draws the figure, recalculating the positions of the straws based on the provided z coordinate.

Parameters:

z : numerical

The z coordinate of the slice of the CDC you want to look at. Should be between 0 and 175 (this quantity is assumed to be in cm).

rings : list

A list of rings to be displayed. Each of the elements of this list should be an int, and should be between 1 and 28.

update_layout(*args, **kwargs)[source]

Updates the layout of the applet. This is a wrapper method for plotly.graph_objects.Figure.update_layout(). Refer to its documentation for a list of all possible arguments.

class pidp_tools.visualization.CDC_plot_3D(rings, wire_positions=None)[source]

Bases: object

Creates and displays a 3D model of the straws of the CDC.

Parameters:

rings : list

A list of rings to plot. All straws from the selected ring will be drawn. Each ring should be an integer between 1 and 28. Can supply at most 3 rings.

wire_positions : wirePositions, default None

A wirePositions object to reference detector coordinates. By default, one will be created. However, if you wish to avoid creating multiple instances, you can provide one that is already created.

Attributes:

figure : plotly.graph_objects.Figure

A plotly figure that displays the requested rings of the GlueX CDC.

pidp_tools.visualization.degrees_to_radians(degrees)[source]

Converts degrees to radians.

Parameters

degrees : float or numpy.array()

Angle (or array of angles) in degrees.

Returns

float or numpy.array()

Angle (or array of angles) in radians.

class pidp_tools.visualization.interactive_image(image_path='', x_max=1.0, y_max=2e-05)[source]

Bases: object

Creates an interactive image that can be used to find exponential cuts in 2D histograms.

Parameters

image_path : str, default “”

The path to the saved ROOT canvas.

x_max : float, default 1.

The maximum of the x axis, which is typically used for momentum. This should be in the same units as were used when creating the ROOT histogram.

y_max : float, default 2.*10**-5

The maximum of the y_axis. This should be in the same units as were used when creating the ROOT histogram.

Attributes

figure : plotly.graph_objects.Figure

A plotly FigureWidget that contains the interactive image.

x_max : float, default 1.

The maximum of the x axis, which is typically used for momentum. This should be in the same units as were used when creating the ROOT histogram.

y_max : float, default 2.*10**-5

The maximum of the y_axis. This should be in the same units as were used when creating the ROOT histogram.

display(**kwargs)[source]

Displays the sliders for the interactive image. This is done by calling the interactive_image.update_figure() method.

Parameters:

**kwargs:

The following keyword arguments correspond to the arguments of the interactive_image.update_figure() method. Each of these keyword arguments should be used for every call. Each of these keyword arguments can be assigned one of the following:

  • A tuple of the form (min_value, max_value, step) for numerical (float/int) arguments, which will generate a slider for the argument in question.

  • A boolean for boolean arguments, which will generate a checkbox, which allows the user to toggle the argument.

  • A list of strings or tuples, which will produce a dropdown menu of the provided options. If strings, the values in the dropdown will be passed directly to the interactive_image.update_figure() method. If a list of tuples is passed, they should be of the form (label, value), where the dropdown options are the “labels”, and the corresponding value to be passed to interactive_image.update_figure() is the “value”.

  • An instance of ipywidgets.widgets.interaction.fixed, which represents that the provided value cannot be changed by the user. No widget will be generated for this argument.

The below list of keyword arguments specifies the expected type of the arguments. Note that these correspond to the constants in the equation y= exp(a*p+b)+c. Also note that the y axis is automatically rescaled, and the rescaling factor will be printed out when initializing the image.

a : numerical

The exponential decay constant of the exponential function (e**(-a*p)).

b : numerical

A vertical rescaling factor for the exponential function (by a factor of e**b).

c : numerical

The vertical offset of the exponential function.

Examples:

>>> fig = interactive_image()
>>> fig.update()
>>> fig.display(a=(-10,-1, 0.1), b=(0,10,0.1), c=fixed(1))

The result of this code is a plot with a slider that allows the user to modify the values of a and b. The value of c will be fixed, so no slider will be displayed.

show()[source]

Shows the interactive image. This is a wrapper method for plotly.graph_objects.Figure.show

update(*args, **kwargs)[source]

Updates the layout of the applet. This is a wrapper method for plotly.graph_objects.Figure.update_layout(). Refer to its documentation for a list of all possible arguments.

update_figure(a=1, b=1, c=1)[source]

Updates and draws the interactive image, recalculating exponential equation y= exp(a*p+b)+c.

Parameters:

a : numerical

The exponential decay constant of the exponential function (e**(-a*p)).

b : numerical

A vertical rescaling factor for the exponential function (by a factor of e**b).

c : numerical

The vertical offset of the exponential function.

update_layout(*args, **kwargs)[source]

Updates the layout of the applet. This is a wrapper method for plotly.graph_objects.Figure.update_layout(). Refer to its documentation for a list of all possible arguments.

pidp_tools.visualization.plot_vector(x_val, y_val, z_val)[source]

Plots the vector with the supplied components.

Parameters

x_val : float

The x component of the vector to be plotted.

y_val : float

The y component of the vector to be plotted.

z_val : float

The z component of the vector to be plotted.

class pidp_tools.visualization.track_fitting(title='Hits in the GlueX CDC', wire_positions=None, event=None, showTrack=False, showlegend=False)[source]

Bases: object

Creates a track fitting applet with hits drawn based on the provided event.

Parameters

title : str, default “Hits in the GlueX CDC”

The title of the plot.

wire_positions : wirePositions, default None

A wirePositions object to reference detector coordinates. By default, one will be created. However, if you wish to avoid creating multiple instances, you can provide one that is already created.

event : pandas.DataFrame, default None

A row of a dataframe with the following columns:

  • “px” : The x component of the momentum of the generated particle.

  • “py” : The y component of the momentum of the generated particle.

  • “pz” : The z component of the momentum of the generated particle.

  • “vz” : The z coordinate of the vertex (“creation point”) of the generated particle.

  • “ring” : A list of rings that contain hits.

  • “straw” : A list of straws that contain hits.

showTrack : bool, default False

Draws the track. If True, a track will be drawn in red.

showlegend : bool, default False

Displays a legend. If True, a legend will be drawn to the right of the applet.

Attributes

figure : plotly.graph_objects.Figure

A plotly FigureWidget that contains the applet.

px : float

The x component of the momentum of the generated particle.

py : float

The y component of the momentum of the generated particle.

pz : float

The z component of the momentum of the generated particle.

current_px : float

The x component of the momentum, as determined by the current state of any available sliders.

current_py : float

The y component of the momentum, as determined by the current state of any available sliders.

current_pz : float

The z component of the momentum, as determined by the current state of any available sliders.

current_z0 : float

The z coordinate of the vertex (“creation point”), as determined by the current state of any available sliders.

current_charge : int or float

The charge, as determined by the current state of any available sliders.

ring : list

A list of rings that contain hits.

straw : list

A list of straws that contain hits.

vz : float

The z coordinate of the vertex (“creation point”) of the generated particle.

wirePositions : wirePositions

A wirePositions object that contains information about the GlueX CDC.

calc_z0(quiet=False)[source]

Finds the most likely z coordinate of the vertex by minimizing the RMSE of the hit positions.

Parameters:

quiet : bool, default False

Suppresses printing of z coordinate. If True, the correct z0 is simply returned and not printed.

Returns:

rmse : float

The root mean square error (RMSE) of the distances of the hits to the “correct” track. Only returned if quiet is True.

calculate_rmse(x_points, y_points)[source]

Calculates the RMSE of the distance between the points and the “correct” track. This is used to optimize the z coordinate of the vertex.

Parameters:

x_points : list

A list of x coordinates of hits in the CDC.

y_points : list

A list of y coordinates of hits in the CDC.

Returns:

rmse : float

The root mean square error (RMSE) of the distances of the hits to the “correct” track.

display(**kwargs)[source]

Displays the sliders corresponding to track parameters. This is done by calling the track_fitting.update_figure() method.

Parameters:

**kwargs:

The following keyword arguments correspond to the arguments of the track_fitting.update_figure() method. Each of these keyword arguments should be used for every call. Each of these keyword arguments can be assigned one of the following:

  • A tuple of the form (min_value, max_value, step) for numerical (float/int) arguments, which will generate a slider for the argument in question.

  • A boolean for boolean arguments, which will generate a checkbox, which allows the user to toggle the argument.

  • A list of strings or tuples, which will produce a dropdown menu of the provided options. If strings, the values in the dropdown will be passed directly to the track_fitting.update_figure() method. If a list of tuples is passed, they should be of the form (label, value), where the dropdown options are the “labels”, and the corresponding value to be passed to track_fitting.update_figure() is the “value”.

  • An instance of ipywidgets.widgets.interaction.fixed, which represents that the provided value cannot be changed by the user. No widget will be generated for this argument.

The below list of keyword arguments specifies the expected type of the arguments.

px : int or float

The x component of the momentum of the track.

py : int or float

The y component of the momentum of the track.

pz : int or float

The z component of the momentum of the track.

z0 : int or float

The z coordinate of the vertex that produced the track. In other words, this is the z component of the “starting point” of the track.

charge : int or float

The charge of the track. This can be a float, but it should usually be -1 or 1.

t_max : int or float

The length of the track to draw, measured in radians.

show_track : bool

Draws the track. If True, draws the track with the supplied parameters.

show_hits : bool

Draws the hits. If true, draws the hits detailed in the event passed during initialization.

Examples:

>>> fig = track_fitting()
>>> fig.update()
>>> fig.display(px=(-1,1,0.0001),py=(-1,1,0.0001),t_max=(0,2*np.pi,0.0001),charge = (-1,1,2),show_track=fixed(True),show_hits=fixed(False),pz=fixed(0),z0=fixed(75))

The result of this code is a track fitting applet with 4 sliders: px, py, t_max, and charge. The remaining arguments are fixed, and will not correspond to a displayed widget.

distance_to_curve(x, y)[source]

Calculates the distance between a point and the “correct” track. Used to find RMSE by varying the z coordinate of the vertex.

Parameters:

x : float

The x coordinate of the point.

y : float

The y coordinate of the point.

Returns:

distance_to_nearest_curve_point : float

The distance between the supplied point and the “correct” track, as determined by the parameters provided by the event.

show()[source]

Shows the track fitting applet. This is a wrapper method for plotly.graph_objects.Figure.show.

show_answer(charge=True, px=True, py=True, pz=False, z0=False)[source]

Prints the track parameters, as determined by the GlueX reconstruction algorithm. The z coordinate of the vertex is the one exception, as this is calculated by minimizing RMSE.

Parameters:

charge : bool, default True

Prints the charge of the particle. If True, the charge of the particle is printed

px : bool, default True

Prints the x component of the momentum of the track. If True, the x component of momentum is printed.

py : bool, default True

Prints the y component of the momentum of the track. If True, the y component of momentum is printed.

pz : bool, default False

Prints the z component of the momentum of the track. If True, the y component of momentum is printed.

z0 : bool, default False

Prints the z component of the vertex of the track. If True, the z component of the track vertex is printed.

update(*args, **kwargs)[source]

Updates the applet. This is a wrapper method for plotly.graph_objects.Figure.update(). Refer to its documentation for a list of all possible arguments.

update_figure(z0=0, px=0, py=0, charge=1, pz=0, t_max=3.141592653589793, show_track=True, show_hits=True)[source]

Updates and draws the figure, recalculating the positions of the hits and the track trajectory, based on the provided track parameters.

Parameters:

px : float, default 0

The x component of the momentum of the track.

py : float, default 0

The y component of the momentum of the track.

pz : float, default 0

The z component of the momentum of the track.

z0 : float, default 0

The z coordinate of the vertex that produced the track. In other words, this is the z component of the “starting point” of the track.

charge : float or int, default 1

The charge of the track. This can be a float, but it should usually be -1 or 1.

t_max : float, default 3.14

The length of the track to draw, measured in radians.

show_track : bool, default True

Draws the track. If True, draws the track with the supplied parameters.

show_hits : bool, default True

Draws the hits. If true, draws the hits detailed in the event passed during initialization.

update_layout(*args, **kwargs)[source]

Updates the layout of the applet. This is a wrapper method for plotly.graph_objects.Figure.update_layout(). Refer to its documentation for a list of all possible arguments.

pidp_tools.visualization.view_shower_2D(df, eventNum)[source]

Creates a displays a 2D visualization of the BCal shower in the provided row of the provided dataframe.

Parameters:

df : pandas.DataFrame

The dataframe containing events in the GlueX BCal. This dataframe should have 7 columns: “module”,”sector”, “layer”, “pulse_integral_up”, “pulse_integral_down”, “t_up”, and “t_down”. Each of these columns should contain a list, and all of these lists should be the same length across columns. Each element of each list corresponds to a single hit in the BCal.

eventNum : int

The row of the dataframe for which you want to plot the shower.

pidp_tools.visualization.view_shower_3D(df, eventNum)[source]

Creates a displays a 3D visualization of the BCal shower in the provided row of the provided dataframe.

Parameters:

df : pandas.DataFrame

The dataframe containing events in the GlueX BCal. This dataframe should have 7 columns: “module”,”sector”, “layer”, “pulse_integral_up”, “pulse_integral_down”, “t_up”, and “t_down”. Each of these columns should contain a list, and all of these lists should be the same length across columns. Each element of each list corresponds to a single hit in the BCal.

eventNum : int

The row of the dataframe for which you want to plot the shower.

class pidp_tools.visualization.wirePositions[source]

Bases: object

An object that stores a variety of properties of the straws of the GlueX Central Drift Chamber (CDC).

Attributes

wire_positions_df : pandas.DataFrame

A pandas dataframe with at least the following three columns:

  • “pos” : contains a list with two elements, each of which is a position vector. The first position vector is the position of the straw at the upstream end of the detector (z=s=0). The second position vector is the position of the straw at the downstream end of the detector (z=175, s=1). Positions in between can be expressed as a convex combination of the two vectors based on the normalized z coordinate.

  • “ring” : The ring the straw in question belongs to

  • “straw” : The straw in question

positionsMatrix : list

A 3D jagged array of wire positions. The first index of the array represents the ring, and the second index represents the straw number. The third index represents the end of the detector (index 0 is upstream, index 1 is downstream). The fourth index represents the coordinate of the position of the straw in question (index 0 is x, index 1 is y, and index 2 is z).

position(rings, wires, s, dataframe=False)[source]

Calculates the wire position.

Parameters

rings : list

A list of rings that represent the rings in which the wires provided are located.

wires : list

A list of wires whose positions will be calculated.

s : float or list

A number (or list of numbers) that represents a normalized z coordinate (z/175) of the wire. This is used because several wires are slanted, so their x and y coordinates depend on the z coordinate. If s is a float or int, all wire positions will be calculated with this same normalized z coordinate.

t : numpy.array()

An array of angles along the track (in radians) to calculate the x coordinate of

dataframe : bool, default False

Return a dataframe containing the x and y coordinates of the wires. If True, the coordinates will be returned in a dataframe with four columns: “ring”, “wire”, “x”, and “y”.

Returns

numpy.array() or pandas.DataFrame

An array or dataframe containing the x and y coordinates of the wires at the given normalized z coordinate(s).

pidp_tools.visualization.x_coord(r_curvature, theta_curvature, center_x, t, q)[source]

Calculates the x coordinate of a track based on its radius of curvature, starting point, center of curvature, and charge after t radians.

Parameters

r_curvature : float

The radius of curvature of the track.

theta_curvature : float

The phase offset of the track’s parametrization. This is necessary to ensure the track starts at the origin.

center_x : float

The x coordinate of the center of curvature of the track of the particle.

t : numpy.array()

An array of angles along the track (in radians) to calculate the x coordinate of.

q : int

The charge of the particle that left the track.

Returns

numpy.array()

The x coordinates of the points along the track with angles provided in the t argument.

pidp_tools.visualization.y_coord(r_curvature, theta_curvature, center_y, t, q)[source]

Calculates the y coordinate of a track based on its radius of curvature, starting point, center of curvature, and charge.

Parameters

r_curvature : float

The radius of curvature of the track.

theta_curvature : float

The phase offset of the track’s parametrization. This is necessary to ensure the track starts at the origin.

center_y : float

The y coordinate of the center of curvature of the track of the particle.

t : numpy.array()

An array of angles along the track (in radians) to calculate the y coordinate of.

q : int

The charge of the particle that left the track.

Returns

numpy.array()

The y coordinates of the points along the track with angles provided in the t argument.