Skip to content

config Module

The config module describes the Spyral configuration object and its sub-categories.

ClusterParameters dataclass

Parameters for clustering, cluster joining, and cluster cleaning

Attributes:

Name Type Description
min_cloud_size int

The minimum size for a point cloud to be clustered
min_points int

min_samples parameter in scikit-learns' HDBSCAN algorithm
min_size_scale_factor int

Factor which is multiplied by the number of points in a point cloud to set the min_cluster_size parameter in scikit-learn's HDBSCAN algorithm
min_size_lower_cutoff int

min_cluster_size parameter in scikit-learn's HDBSCAN algorithm for events where n_points * min_size_scale_factor are less than this value.
cluster_selection_epsilon float

cluster_selection_epsilon parameter in scikit-learn's HDBSCAN algorithm. Clusters less than this distance apart are merged in the hierarchy
min_cluster_size_join int

The minimum size of a cluster for it to be included in the joining algorithm
circle_overlap_ratio float

minimum overlap ratio between two circles in the cluster joining algorithm
outlier_scale_factor float

Factor which is multiplied by the number of points in a trajectory to set the number of neighbors parameter for scikit-learns LocalOutlierFactor test
Source code in src/spyral/core/config.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
@dataclass
class ClusterParameters:
    """Parameters for clustering, cluster joining, and cluster cleaning

    Attributes
    ----------
    min_cloud_size: int
        The minimum size for a point cloud to be clustered
    min_points: int
        min_samples parameter in scikit-learns' HDBSCAN algorithm
    min_size_scale_factor: int
        Factor which is multiplied by the number of points in a point cloud to set
        the min_cluster_size parameter in scikit-learn's HDBSCAN algorithm
    min_size_lower_cutoff: int
        min_cluster_size parameter in scikit-learn's HDBSCAN algorithm for events where n_points * min_size_scale_factor
        are less than this value.
    cluster_selection_epsilon: float
        cluster_selection_epsilon parameter in scikit-learn's HDBSCAN algorithm. Clusters less than this distance apart
        are merged in the hierarchy
    min_cluster_size_join: int
        The minimum size of a cluster for it to be included in the joining algorithm
    circle_overlap_ratio: float
        minimum overlap ratio between two circles in the cluster joining algorithm
    outlier_scale_factor: float
        Factor which is multiplied by the number of points in a trajectory to set the number of neighbors parameter
        for scikit-learns LocalOutlierFactor test
    """

    min_cloud_size: int
    min_points: int
    min_size_scale_factor: float
    min_size_lower_cutoff: int
    cluster_selection_epsilon: float
    overlap_join: OverlapJoinParameters | None
    continuity_join: ContinuityJoinParameters | None
    outlier_scale_factor: float

ContinuityJoinParameters dataclass

Parameters for joining clusters based on continuity

Attributes:

Name Type Description
join_radius_fraction float

The percent difference allowed for the cylindrical radius. Used as radius_threshold = join_radius_fraction * (max_radius - min_radius) where max_radius and min_radius are the maximum, minimum radius value over both clusters being compared
join_z_fraction float

The percent difference allowed for the cylindrical z. Used as z_threshold = join_z_fraction * (max_z - min_z) where max_z and min_z are the maximum, minimum z value over both clusters being compared
Source code in src/spyral/core/config.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
@dataclass
class ContinuityJoinParameters:
    """Parameters for joining clusters based on continuity

    Attributes
    ----------
    join_radius_fraction: float
        The percent difference allowed for the cylindrical radius. Used as
        radius_threshold = join_radius_fraction * (max_radius - min_radius)
        where max_radius and min_radius are the maximum, minimum radius value over both
        clusters being compared
    join_z_fraction: float
        The percent difference allowed for the cylindrical z. Used as
        z_threshold = join_z_fraction * (max_z - min_z)
        where max_z and min_z are the maximum, minimum z value over both
        clusters being compared

    """

    join_radius_fraction: float
    join_z_fraction: float

DetectorParameters dataclass

Parameters describing the detector configuration

Attributes:

Name Type Description
magnetic_field float

The magnitude of the magnetic field in Tesla
electric_field float

The magnitude of the electric field in V/m
detector_length float

The detector length in mm
beam_region_radius float

The beam region radius in mm
micromegas_time_bucket float

The micromegas time reference in GET time buckets
window_time_bucket float

The window time reference in GET time buckets
get_frequency float

The GET DAQ sampling frequency in MHz. Typically 3.125 or 6.25
garfield_file_path str

Path to a Garfield simulation file containing electron drift corrections
Source code in src/spyral/core/config.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
@dataclass
class DetectorParameters:
    """Parameters describing the detector configuration

    Attributes
    ----------
    magnetic_field: float
        The magnitude of the magnetic field in Tesla
    electric_field: float
        The magnitude of the electric field in V/m
    detector_length: float
        The detector length in mm
    beam_region_radius: float
        The beam region radius in mm
    micromegas_time_bucket: float
        The micromegas time reference in GET time buckets
    window_time_bucket: float
        The window time reference in GET time buckets
    get_frequency: float
        The GET DAQ sampling frequency in MHz. Typically 3.125 or 6.25
    garfield_file_path: str
        Path to a Garfield simulation file containing electron drift corrections

    """

    magnetic_field: float  # Tesla
    electric_field: float  # V/m
    detector_length: float  # mm
    beam_region_radius: float  # mm
    micromegas_time_bucket: float
    window_time_bucket: float
    get_frequency: float  # MHz
    garfield_file_path: Path
    do_garfield_correction: bool

EstimateParameters dataclass

Parameters for physics estimation

Attributes:

Name Type Description
min_total_trajectory_points int

minimum number of points in a cluster for the cluster to be considered a particle trajectory
smoothing_factor float

smoothing factor for creation of smoothing splines. See scipy's documentaion for make_smoothing_splines and in particular the lam parameter for more details.
Source code in src/spyral/core/config.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
@dataclass
class EstimateParameters:
    """Parameters for physics estimation

    Attributes
    ----------
    min_total_trajectory_points: int
        minimum number of points in a cluster for the cluster to be considered a particle trajectory
    smoothing_factor: float
        smoothing factor for creation of smoothing splines. See scipy's documentaion for make_smoothing_splines
        and in particular the lam parameter for more details.
    """

    min_total_trajectory_points: int
    smoothing_factor: float

FribParameters dataclass

Parameters for FRIBDAQ (IC, Si, etc) trace signal analysis

Attributes:

Name Type Description
baseline_window_scale float

The scale factor for the basline correction algorithm
peak_separation float

The peak separation parameter used in scipy.signal.find_peaks
peak_prominence float

The peak prominence parameter used in scipy.signal.find_peaks
peak_max_width float

The maximum peak width parameter used in scipy.signal.find_peaks
peak_threshold float

The minimum amplitude of a valid peak
ic_delay_time_bucket int

The delay to the IC signal in FRIB TimeBuckets. All IC peaks before this TB are ignored when considering IC multiplicity/validity
ic_multiplicity int

The maximum allowed ion chamber multiplicity
Source code in src/spyral/core/config.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@dataclass
class FribParameters:
    """Parameters for FRIBDAQ (IC, Si, etc) trace signal analysis

    Attributes
    ----------
    baseline_window_scale: float
        The scale factor for the basline correction algorithm
    peak_separation: float
        The peak separation parameter used in scipy.signal.find_peaks
    peak_prominence: float
        The peak prominence parameter used in scipy.signal.find_peaks
    peak_max_width: float
        The maximum peak width parameter used in scipy.signal.find_peaks
    peak_threshold: float
        The minimum amplitude of a valid peak
    ic_delay_time_bucket: int
        The delay to the IC signal in FRIB TimeBuckets. All IC peaks
        before this TB are ignored when considering IC multiplicity/validity
    ic_multiplicity: int
        The maximum allowed ion chamber multiplicity
    """

    baseline_window_scale: float
    peak_separation: float
    peak_prominence: float
    peak_max_width: float
    peak_threshold: float
    ic_delay_time_bucket: int
    ic_multiplicity: int

GetParameters dataclass

Parameters for GET trace signal analysis

Attributes:

Name Type Description
baseline_window_scale float

The scale factor for the basline correction algorithm
peak_separation float

The peak separation parameter used in scipy.signal.find_peaks
peak_prominence float

The peak prominence parameter used in scipy.signal.find_peaks
peak_max_width float

The maximum peak width parameter used in scipy.signal.find_peaks
peak_threshold float

The minimum amplitude of a valid peak
Source code in src/spyral/core/config.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@dataclass
class GetParameters:
    """Parameters for GET trace signal analysis

    Attributes
    ----------
    baseline_window_scale: float
        The scale factor for the basline correction algorithm
    peak_separation: float
        The peak separation parameter used in scipy.signal.find_peaks
    peak_prominence: float
        The peak prominence parameter used in scipy.signal.find_peaks
    peak_max_width: float
        The maximum peak width parameter used in scipy.signal.find_peaks
    peak_threshold: float
        The minimum amplitude of a valid peak
    """

    baseline_window_scale: float
    peak_separation: float
    peak_prominence: float
    peak_max_width: float
    peak_threshold: float

OverlapJoinParameters dataclass

Parameters for joining clusters based on area of overlap

Attributes:

Name Type Description
min_cluster_size_join int

The minimum size of a cluster for it to be included in the joining algorithm
circle_overlap_ratio float

Minimum overlap ratio between two circles in the cluster joining algorithm. Used as area_overlap > circle_overlap_ratio * (min_area) where area_overlap is the area overlap and min_area is the minimum area of the two clusters being compared
Source code in src/spyral/core/config.py 
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
@dataclass
class OverlapJoinParameters:
    """Parameters for joining clusters based on area of overlap

    Attributes
    ----------
    min_cluster_size_join: int
        The minimum size of a cluster for it to be included in the joining algorithm
    circle_overlap_ratio: float
        Minimum overlap ratio between two circles in the cluster joining algorithm. Used
        as area_overlap > circle_overlap_ratio * (min_area) where area_overlap is the
        area overlap and min_area is the minimum area of the two clusters being compared
    """

    circle_overlap_ratio: float
    min_cluster_size_join: int

PadParameters dataclass

Parameters describing the pad map paths

Attributes:

Name Type Description
pad_geometry_path Path

Path to the csv file containing the pad geometry. If set to DEFAULT_MAP uses the packaged maps.
pad_gain_path Path

Path to the csv file containing the relative pad gains. If set to DEFAULT_MAP uses the packaged maps.
pad_time_path Path

Path to the csv file containing the pad time corrections. If set to DEFAULT_MAP uses the packaged maps.
pad_electronics_path Path

Path to the csv file containing the pad electronics ids. If set to DEFAULT_MAP uses the packaged maps.
Source code in src/spyral/core/config.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@dataclass
class PadParameters:
    """Parameters describing the pad map paths

    Attributes
    ----------
    pad_geometry_path: Path
        Path to the csv file containing the pad geometry. If set to DEFAULT_MAP
        uses the packaged maps.
    pad_gain_path: Path
        Path to the csv file containing the relative pad gains. If set to DEFAULT_MAP
        uses the packaged maps.
    pad_time_path: Path
        Path to the csv file containing the pad time corrections. If set to DEFAULT_MAP
        uses the packaged maps.
    pad_electronics_path: Path
        Path to the csv file containing the pad electronics ids. If set to DEFAULT_MAP
        uses the packaged maps.
    """

    pad_geometry_path: Path
    pad_time_path: Path
    pad_electronics_path: Path
    pad_scale_path: Path

SolverParameters dataclass

Parameters for physics solving

Attributes:

Name Type Description
gas_data_path str

Path to a spyral-utils GasTarget or GasMixtureTarget file
particle_id_filename str

Name of a particle ID cut file
ic_min_val float

Low value the desired beam region of the ion chamber spectrum
ic_max_value float

High value the desired beam region of the ion chamber spectrum
n_time_steps int

The number of timesteps used in the ODE solver
interp_ke_min float

The minimum value of kinetic energy used in the interpolation scheme in MeV
interp_ke_max float

The maximum value of kinetic energy used in the interpolation scheme in MeV
interp_ke_bins int

The number of kinetic energy bins used in the interpolation scheme
interp_polar_min float

The minimum value of polar angle used in the interpolation scheme in degrees
interp_polar_max float

The maximum value of polar angle used in the interpolation scheme in degrees
interp_polar_bins int

The number of polar angle bins used in the interpolation scheme
fit_vertex_rho bool

Control whether or not the vertex rho position is fitted (True=fitted, False=fixed)
fit_vertex_phi bool

Control whether or not the vertex phi position is fitted (True=fitted, False=fixed)
fit_azimuthal bool

Control whether or not the trajectory azimuthal angle is fitted (True=fitted, False=fixed)
fit_method str

What type of fitting to use, options are "lbfgsb" or "leastsq"
Source code in src/spyral/core/config.py 
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
@dataclass
class SolverParameters:
    """Parameters for physics solving

    Attributes
    ----------
    gas_data_path: str
        Path to a spyral-utils GasTarget or GasMixtureTarget file
    particle_id_filename: str
        Name of a particle ID cut file
    ic_min_val: float
        Low value the desired beam region of the ion chamber spectrum
    ic_max_value: float
        High value the desired beam region of the ion chamber spectrum
    n_time_steps: int
        The number of timesteps used in the ODE solver
    interp_ke_min: float
        The minimum value of kinetic energy used in the interpolation scheme in MeV
    interp_ke_max: float
        The maximum value of kinetic energy used in the interpolation scheme in MeV
    interp_ke_bins: int
        The number of kinetic energy bins used in the interpolation scheme
    interp_polar_min: float
        The minimum value of polar angle used in the interpolation scheme in degrees
    interp_polar_max: float
        The maximum value of polar angle used in the interpolation scheme in degrees
    interp_polar_bins: int
        The number of polar angle bins used in the interpolation scheme
    fit_vertex_rho: bool
        Control whether or not the vertex rho position is fitted (True=fitted, False=fixed)
    fit_vertex_phi: bool
        Control whether or not the vertex phi position is fitted (True=fitted, False=fixed)
    fit_azimuthal: bool
        Control whether or not the trajectory azimuthal angle is fitted (True=fitted, False=fixed)
    fit_method: str
        What type of fitting to use, options are "lbfgsb" or "leastsq"
    """

    gas_data_path: Path
    particle_id_filename: Path
    ic_min_val: float
    ic_max_val: float
    n_time_steps: int
    interp_ke_min: float
    interp_ke_max: float
    interp_ke_bins: int
    interp_polar_min: float
    interp_polar_max: float
    interp_polar_bins: int
    fit_vertex_rho: bool
    fit_vertex_phi: bool
    fit_azimuthal: bool
    fit_method: str

calculate_window_time(micromegas_time_bucket, drift_velocity, detector_length, get_frequency)

Calculate the window time from a drift velocity

Given a known micromegas time, drift velocity, detector length, and GET sampling frequency calculate the expected window time.

Parameters:

Name Type Description Default
micromegas_time_bucket float

The micromegas time in GET Time Buckets

 required
drift_velocity float

The electron drift velocity in mm/us

 required
detector_length float

The detector length in mm

 required
get_frequency float

The GET electronics sampling frequency

 required

Returns:

Type Description
float

The window time in GET time buckets
Source code in src/spyral/core/config.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def calculate_window_time(
    micromegas_time_bucket: float,
    drift_velocity: float,
    detector_length: float,
    get_frequency: float,
) -> float:
    """Calculate the window time from a drift velocity

    Given a known micromegas time, drift velocity, detector length, and GET sampling frequency
    calculate the expected window time.

    Parameters
    ----------
    micromegas_time_bucket: float
        The micromegas time in GET Time Buckets
    drift_velocity: float
        The electron drift velocity in mm/us
    detector_length: float
        The detector length in mm
    get_frequency: float
        The GET electronics sampling frequency

    Returns
    -------
    float
        The window time in GET time buckets
    """
    return (detector_length / drift_velocity) * get_frequency + micromegas_time_bucket