API

Hits

class liquidreco.hit.Hit(x=None, y=None, z=None, time=None, weight=None)

Very generic detector hit, probably shouldn’t use directly, should instead use one of the derived classes

time

time of the hit

weight

the β€œweight” of this hit. Typically the charge/light collected

x

x position of the hit

y

y position of the hit

z

z position of the hit

class liquidreco.hit.Hit2D(x=None, y=None, z=None, fiber_x=None, fiber_y=None, fiber_z=None, time=None, weight=None, secondary_hits=None)

Describes a 2D WLS fiber hit

static copy(old_hit: Hit2D) → Hit2D

Create a copy of an existing 2D hit

Parameters:

old_hit (Hit2D) – the hit to copy

Returns:

copied hit

Return type:

Hit2D

static get_mean_pos(hits: List[Hit2D], direction: str) → float

Get the mean position of a list of 2D hits in a particular dimension

Parameters:

  • hits (List[Hit2D]) – The hits to take the average of

  • direction (str) – the dimension to take the average in. e.g. β€˜x’ to get the mean x position β€˜y’ for mean y…

Returns:

the weighted mean position

Return type:

float

is_peak(direction: str) → bool

Checks if this hit is considered a peak in a particular direction i.e. more position info than just the fiber position

Parameters:

direction (str) – The direction to test

Returns:

True if this hit has peak info in the specified direction.

Return type:

bool

class liquidreco.hit.Hit3D(x=None, y=None, z=None, voxel_x=None, voxel_y=None, voxel_z=None, time=None, weight=None, x_fiber_hit=None, y_fiber_hit=None, z_fiber_hit=None)

Describes a 3D hit constructed from two or three WLS fibers

static from_fiber_hits(x_fiber_hit: Hit2D | None = None, y_fiber_hit: Hit2D | None = None, z_fiber_hit: Hit2D | None = None, n_required_peaks: int | None = None) → Hit3D

Create a Hit3D from some 2D fiber hits

Parameters:

  • x_fiber_hit (Hit2D) – The x fiber

  • y_fiber_hit (Hit2D) – The y fiber

  • z_fiber_hit (Hit2D, optional) – The (optional) z fiber, defaults to None

  • n_required_peaks (int) – require this number of peak hits to be present in each direction to successfuly create a hit. e.g. if n_required_peaks = 1 and 0 of the provided fibers are classified as z peaks, the hit will not be valid. defaults to None

Returns:

The constructed 3D hit, None if the n_required_peaks condition is not satisfied in any direction

Return type:

Hit3D

liquidreco.hit.build_3d_hits(x_fiber_hits: List[Hit2D], y_fiber_hits: List[Hit2D], z_fiber_hits: List[Hit2D], require_3_fibers: bool = True, pitch: Tuple[float] = (10.0, 10.0, 10.0), min_2d_hit_weight: float = 0.0, n_required_peaks: int | None = None, max_weighted_distance: float | None = None) → List[Hit]

Makes 3D hits from arrays of info about 2d fiber hits

Parameters:

  • x_fiber_hits (List[Hit2D]) – List of 2D YZ fibers

  • y_fiber_hits (List[Hit2D]) – List of 2D XZ fibers

  • z_fiber_hits (List[Hit2D]) – List of 2D XY fibers

  • require_3_fibers (bool, optional) – Whether to require 3 fibers to form a hit or allow only on x and one y fiber, defaults to True

  • pitch (Tuple[float], optional) – The distance between fibers in each direction, defaults to (10.0, 10.0, 10.0)

  • min_2d_hit_weight (float, optional) – The minimum weight a 2D fiber hit must have to be considered when building 3D hits, defaults to 0.0

  • n_required_peaks (int, optional) – The number of β€œpeak hits” required in each direction to form a valid 3D hit (see Hit3D.from_fiber_hits() for more details), defaults to None

  • max_weighed_distance – The maximum β€œreal” i.e. peak weighted discance between 2D hits in order for them to be considered for combining into a 3D hit. Specified as a fraction of fiber pitch, defaults to None

Returns:

list of 3d hits

Return type:

List[Hit]

liquidreco.hit.local_normalisation(event_hits, window_size, x_bins, y_bins, z_bins)

do a local normalisation of the hits so that lokal peaks have β€œcharge” of 1 and hits in the neighbourhood have their charges normalised by this value

Peak_finding

class liquidreco.peak_finding.LaplaceFitter(neighbourhood_dist: float = 45.0, peak_candidate_threshold: float = 100.0, amplitude_threshold: float = 50.0, fix_width: float | None = None, min_n_neighbours: int = 0, make_plots=False)

Performs a fit of an ensemble of laplace distributions to observed collected charges in fibers in order to try to determine which

class liquidreco.peak_finding.PeakFinder2D(peak_prominance_threshold: float = 1.0, fit_blobs: bool = False, make_plots: bool = False, DBSCAN_args={'eps': 10.5}, laplace_fit_args={})

Finds peaks in raw fiber hits and performs position corrections

cluster_hits(fiber_hits: List[Hit2D], u: str, v: str) → List[List[Hit2D]]

Cluster hits using this PeakFinder2Ds _clusterer (default is DBSCAN but you can set it to whatever you want)

Parameters:

  • fiber_hits (List['Hit2D']) – The hits to cluster

  • u (str) – the β€œu” direction, should be β€˜x’, β€˜y’ or β€˜z’ depending on the projection

  • v (str) – the β€œv” direction, should be β€˜x’, β€˜y’ or β€˜z’ depending on the projection

Returns:

hits broken down into clusters

Return type:

List[List[β€˜Hit2D’]]

finalise()

Tidy up and close open pdfs

Reconstruction

Module to be used to reconstruct tracks from hits.

class liquidreco.reconstruction.HesseRidgeDetection(events: list[Event], x_bounds: Tuple[float], y_bounds: Tuple[float], z_bounds: Tuple[float], plot_orthogonal_dirs=False)

Performs simple Hough line transform

class liquidreco.reconstruction.HoughTransform(events: list[Event], min_charge_thresh=80.0, max_plot_charge=100.0, make_gifs=False)

Performs simple Hough line transform

class liquidreco.reconstruction.LocalMeanDBSCAN(events: list[Event], mean_ball_radius=25.0, mean_iterations=1, dbscan_eps=9.0, dbscan_min_samples=25, min_charge_thresh=0.0)
class liquidreco.reconstruction.ReconstructionAlgorithm(events: list[Event])

Base reconstruction algorithm.

Should not be used directly but reconstruction algorithms should derive this.

Event Processor

Plotting

Apps

liquidreco

LiquidReco main app.

Takes a root file that contains 2D fiber hits, creates an EventProcessor based on the provided arguments, and processes the fiber hits using this.

raises ValueError:

if input args are not valid