`tasks` — Tasks#

This module provide all the high-level simulation and analysis tasks of the package, each implemented as a single function with a precise signature, as well as the default values for their arguments.

More specifically, the following tasks are provided:

simulate(): simulate detector data from a source;
reconstruct(): reconstruct detector data;
display(): event display;
quicklook(): quick-look analysis.

Module documentation#

Basic simulation, reconstruction and analysis tasks.

hexsample.tasks.current_call(num_backward_steps: int = 2) → Tuple[str, dict][source]#

Return the name and arguments of the current function call.

Arguments#

num_backward_stepsint: The number of steps to go back in the call stack to find the function call.

hexsample.tasks.open_file(input_file_path: str | Path) → Tuple[DigiInputFileBase, dict, str][source]#: Open a digi file and extract the header and the readout type.

hexsample.tasks.create_readout(readout_mode: HexagonalReadoutMode, header: dict, *args) → HexagonalReadoutBase[source]#: Create and return a readout object based on the readout mode and the header information.

class hexsample.tasks.SimulationDefaults(num_events: int = 10000, output_file_path: str = PosixPath('/home/runner/hexsampledata/simulation.h5'), random_seed: int = None)[source]#

Default parameters for the simulation task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

num_events: int = 10000#

output_file_path: str = PosixPath('/home/runner/hexsampledata/simulation.h5')#

random_seed: int = None#

hexsample.tasks.simulate(source: Source, sensor: Sensor, readout: AbstractReadout, num_events: int = 10000, output_file_path: str = PosixPath('/home/runner/hexsampledata/simulation.h5'), random_seed: int = None, header_kwargs: dict = None) → str[source]#

Run a simulation.

Warning

The last header_kwargs argument is a temporary workaround to allow passing some metadata to be stored in the output file header. This will go away once we have a proper mechanism to handle metadata.

Arguments#

sourceSource: The X-ray source.
sensorSensor: The sensor.
readoutAbstractReadout: The readout chip.
num_eventsint: The number of events to simulate.
output_file_pathstr: The path to the output file.
random_seedint: The random seed to use.

Returns#

str: The path to the output file that the task has created.

class hexsample.tasks.ReconstructionDefaults(suffix: str = 'recon', zero_sup_threshold: float = 0.0, num_neighbors: int = 2, max_neighbors: int = -1, pos_recon_algorithm: str = 'centroid', position_cal: PositionCalibrationData | None = None)[source]#

Default parameters for the reconstruction task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

suffix: str = 'recon'#

zero_sup_threshold: float = 0.0#

num_neighbors: int = 2#

max_neighbors: int = -1#

pos_recon_algorithm: str = 'centroid'#

position_cal: PositionCalibrationData | None = None#

hexsample.tasks.reconstruct(input_file_path: str, noise_matrix: CalibrationMatrix, pedestal_matrix: CalibrationMatrix, equalization_matrix: CalibrationMatrix, suffix: str = 'recon', zero_sup_threshold: float = 0.0, num_neighbors: int = 2, max_neighbors: int = -1, pos_recon_algorithm: str = 'centroid', position_cal: PositionCalibrationData | None = None, header_kwargs: dict = None) → str[source]#

Run the reconstruction.

Warning

The last header_kwargs argument is a temporary workaround to allow passing some metadata to be stored in the output file header. This will go away once we have a proper mechanism to handle metadata.

Arguments#

input_file_pathstr: The path to the input file.
noise_matrixCalibrationMatrix: The noise matrix to use for the reconstruction.
pedestal_matrixCalibrationMatrix: The pedestal matrix to use for the reconstruction.
equalization_matrixCalibrationMatrix: The equalization matrix to use for the reconstruction.
suffixstr: The suffix to append to the output file name.
zero_sup_thresholdfloat: The zero-suppression threshold as a multiple of the noise.
num_neighborsint: The number of neighbor pixels to be used for the clustering.
max_neighborsint: The maximum number of neighbor pixels to be used for the clustering. If max_neighbors is specified (i.e. different from -1), it has priority over num_neighbors.
pos_recon_algorithmstr: The position reconstruction algorithm to use.
position_calPositionCalibrationData: The position calibration data to use.

hexsample.tasks.calibspec(input_file_path: str) → str[source]#

Create a probability density function from a reconstructed spectrum to use in the gain calibration.

Arguments#

input_file_pathstr: The path to the input recon file.

class hexsample.tasks.CalibrationPositionDefaults(bin_size: float = 0.01, num_bins: int = 20, zero_sup_threshold: float = 1.0)[source]#

Default parameters for the position algorithms calibration.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

bin_size: float = 0.01#

num_bins: int = 20#

zero_sup_threshold: float = 1.0#

hexsample.tasks.calibrate_position(input_file_path: str, noise_matrix: CalibrationMatrix, pedestal_matrix: CalibrationMatrix, equalization_matrix: CalibrationMatrix, bin_size: float = 0.01, num_bins: int = 20, zero_sup_threshold: float = 1.0) → str[source]#

Calibrate the position reconstruction algorithms, using the events from a digi file. The results are stored as a matrix in a HDF5 file.

The output file contains the data necessary for the eta reconstruction algorithm and the charge diffusion matrix for the MLE reconstruction algorithm.

Arguments#

input_file_pathstr: The path to the input file.
noise_matrixCalibrationMatrix: The noise matrix to use for the calibration.
pedestal_matrixCalibrationMatrix: The pedestal matrix to use for the calibration.
equalization_matrixCalibrationMatrix: The equalization matrix to use for the calibration.
bin_sizefloat: The size of the bins to use for the charge diffusion matrix.
num_binsint: The number of bins to use for the eta calibration fits.
zero_sup_thresholdfloat: The zero-suppression threshold as a multiple of the noise, to be used for the clustering of the events for the eta calibration.

class hexsample.tasks.SynthesizeCalibrationDefaults(percent_rms: int = 0, output_dir: str | Path = PosixPath('/home/runner/hexsampledata'), chip_name: str = 'xpol3', version: int = 1, random_seed: int = None)[source]#

Default values for the generate_calibration_file task.

percent_rms: int = 0#

output_dir: str | Path = PosixPath('/home/runner/hexsampledata')#

chip_name: str = 'xpol3'#

version: int = 1#

random_seed: int = None#

hexsample.tasks.synthesize_calibration_file(calibration_type: CalibrationType, mean: float, percent_rms: int = 0, chip_name: str = 'xpol3', output_dir: str | Path = PosixPath('/home/runner/hexsampledata'), version: int = 1, random_seed: int = None) → str[source]#

Generate a synthetic calibration file for the given calibration type and chip name.

Arguments#

calibration_typeCalibrationType: The type of calibration to generate.
meanfloat: The mean value of the sample distribution.
percent_rmsint, optional: The root mean square of the sample distribution, expressed as a percentage of the mean. note we treat this as an integer, assuming that we shall never be in the situation where we need a very precise fine tuning.
chip_namestr, optional: The name of the chip for which to generate the calibration file.
output_dirstr, optional: The directory where to save the generated calibration file.
versionint, optional: The version number the generated calibration file.
random_seedint, optional: The seed for the random number generator.

hexsample.tasks.calibrate_noise(input_file_path: str) → str[source]#

Calibrate noise of the readout chip using the events from a digi file. The results are stored as a matrix in a HDF5 file.

Arguments#

input_file_pathstr: The path to the input file.

class hexsample.tasks.CalibrationDarkDefaults(algorithm: str = 'welford', has_source: bool = True, batch_size: int = 5000000)[source]#

Default parameters for the dark calibration task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

algorithm: str = 'welford'#

has_source: bool = True#

batch_size: int = 5000000#

hexsample.tasks.calibrate_dark(input_file_path: str, algorithm: str = 'welford', has_source: bool = True, batch_size: int = 5000000) → Tuple[str, str][source]#

class hexsample.tasks.CalibrationEncDefaults(output_dir: str | Path = PosixPath('/home/runner/hexsampledata'))[source]#

Default parameters for the ENC calibration task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

output_dir: str | Path = PosixPath('/home/runner/hexsampledata')#

hexsample.tasks.calibrate_enc(noise_matrix: CalibrationMatrix, gain_matrix: CalibrationMatrix, output_dir: str | Path = PosixPath('/home/runner/hexsampledata')) → str[source]#

Calibrate the equivalent noise charge (ENC) of the readout chip using the noise and gain matrices. The results are stored as a matrix in a HDF5 file.

Arguments#

noise_matrixCalibrationMatrix: The noise calibration matrix to use for the ENC calibration.
gain_matrixCalibrationMatrix: The gain calibration matrix to use for the ENC calibration.

class hexsample.tasks.CalibrationEqualizationDefaults(algorithm: str = 'relative', pdf: SpectrumPDF | None = None, size: int = 10, zero_sup_threshold: float = 1.0)[source]#

Default parameters for the pixel equalization calibration task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

algorithm: str = 'relative'#

pdf: SpectrumPDF | None = None#

size: int = 10#

zero_sup_threshold: float = 1.0#

hexsample.tasks.calibrate_equalization(input_file_path: str, noise_matrix: CalibrationMatrix, pedestal_matrix: CalibrationMatrix, algorithm: str = 'relative', pdf: SpectrumPDF | None = None, size: int = 10, zero_sup_threshold: float = 1.0) → str[source]#

Calibrate pixel equalization of the readout chip using the events from a digi file. The results are stored as a matrix in a HDF5 file.

Arguments#

input_file_pathstr: The path to the input file.
noise_matrixCalibrationMatrix: The calibration noise matrix to use for the pixel equalization calibration.
pedestal_matrixCalibrationMatrix: The pedestal matrix to use for the pixel equalization calibration.
algorithmstr, optional: The algorithm to use for the pixel equalization calibration. Supported values are “relative” and “absolute”.
pdfSpectrumPDF, optional: The spectrum probability density function to use for the pixel equalization calibration.
sizeint, optional: The length of the square region of the chip to fit simultaneously during the pixel equalization calibration.
zero_sup_thresholdfloat, optional: The zero-suppression threshold to use for the clustering in the pixel equalization calibration.

class hexsample.tasks.CalibrationGainDefaults(output_dir: str | Path = PosixPath('/home/runner/hexsampledata'), material_symbol: str = 'Si')[source]#

Default parameters for the gain calibration task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

output_dir: str | Path = PosixPath('/home/runner/hexsampledata')#

material_symbol: str = 'Si'#

hexsample.tasks.calibrate_gain(equalization_matrix: CalibrationMatrix, material_symbol: str = 'Si', output_dir: str | Path = PosixPath('/home/runner/hexsampledata')) → str[source]#

Calibrate the gain of the readout chip using the equalization matrix and the ionization potential of the sensor material. The results are stored as a matrix in a HDF5 file.

Arguments equalization_matrix : CalibrationMatrix

The equalization matrix to use for the gain calibration.

material_symbolstr: The symbol of the sensor material to use for the gain calibration, e.g. “Si” for silicon.

class hexsample.tasks.DisplayDefaults(noise_matrix: CalibrationMatrix | None = None, pedestal_matrix: CalibrationMatrix | None = None, equalization_matrix: CalibrationMatrix | None = None, position_cal: PositionCalibrationData | None = None)[source]#

Default parameters for the display task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

noise_matrix: CalibrationMatrix | None = None#

pedestal_matrix: CalibrationMatrix | None = None#

equalization_matrix: CalibrationMatrix | None = None#

position_cal: PositionCalibrationData | None = None#

hexsample.tasks.display(input_file_path: str, noise_matrix: CalibrationMatrix | None = None, pedestal_matrix: CalibrationMatrix | None = None, equalization_matrix: CalibrationMatrix | None = None, position_cal: PositionCalibrationData | None = None) → None[source]#

Display events from a digi file.

Arguments#

input_file_pathstr: The path to the digi file.
noise_matrixCalibrationMatrix, optional: The noise calibration matrix to use for the display.
pedestal_matrixCalibrationMatrix, optional: The pedestal calibration matrix to use for the display.
equalization_matrixCalibrationMatrix, optional: The equalization calibration matrix to use for the display.
position_calPositionCalibrationData, optional: The position calibration data to use for the display.

class hexsample.tasks.QuickLookDefaults[source]#

Default parameters for the quicklook task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

hexsample.tasks.quicklook(input_file_path: str) → None[source]#

Quicklook at events from a recon file.

Warning

This needs to be rebuilt from the ground up, but the intent is a good one, I think.

Arguments#

file_pathstr: The path to the input recon file.

class hexsample.tasks.CalibviewDefaults(mc_matrix: CalibrationMatrix | None = None, min_hits: int = 0, rel_error: float = inf, lower_quantile: float = 0.0, upper_quantile: float = 100.0)[source]#

Default parameters for the calibview task.

This is a small helper dataclass to help ensure consistency between the main task definition in this Python module and the command-line interface.

mc_matrix: CalibrationMatrix | None = None#

min_hits: int = 0#

rel_error: float = inf#

lower_quantile: float = 0.0#

upper_quantile: float = 100.0#

hexsample.tasks.calibview(matrix: CalibrationMatrix, mc_matrix: CalibrationMatrix | None = None, min_hits: int = 0, rel_error: float = inf, lower_quantile: float = 0.0, upper_quantile: float = 100.0) → None[source]#

Display a calibration matrix and plot some basic statistics about it. If the Monte Carlo truth matrix is provided, the correlation between the two matrices is also presented.

Arguments#

matrixCalibrationMatrix: The calibration matrix to display.
mc_matrixCalibrationMatrix, optional: The Monte Carlo truth calibration matrix to compare with.
min_hitsint, optional: The minimum number of hits in a pixel to be included in the statistics.
rel_errorfloat, optional: The maximum relative error in a pixel to be included in the statistics.
lower_quantilefloat, optional: The lower quantile of the values in the matrix to be included in the statistics.
upper_quantilefloat, optional: The upper quantile of the values in the matrix to be included in the statistics.

tasks — Tasks#

Module documentation#

Arguments#

Arguments#

Returns#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

Arguments#

`tasks` — Tasks#