AngleCalibration

Class to calibrate the mythen detector parameters. For the calibration the “Best computing” BC parameters are used. However, as initial parameters it expects the “historic detector group” DG parameters. See Different Parameter Sets for a more detailed description of the different detector parameters.

Note

The calibration process will automatically be visualized if you compiled with option ANGCAL_PLOT (Installation).

Example Usage:

std::shared_ptr<MythenDetectorSpecifications> mythen_detector_ptr =
    std::make_shared<MythenDetectorSpecifications>();

mythen_detector_ptr->read_bad_channels_from_file("bad_channels.txt");

std::shared_ptr<FlatField> flat_field_ptr =
    std::make_shared<FlatField>(mythen_detector_ptr);

flat_field_ptr->read_flatfield_from_file("flatfield.raw");

flat_field_ptr->calculate_inverse_normalized_flatfield();

AngleCalibration anglecalibration(mythen_detector_ptr, flat_field_ptr);

anglecalibration.read_initial_calibration_from_file(
    "initial_DG_parameters.off");

//dummy acquisitions
std::vector<std::string> filelist{"file_01.hdf5", "file_02.hdf5", "file_03.hdf5"};

double base_peak_angle = -49.75;

//calibrate parameters for module 10
anglecalibration.calibrate(filelist, base_peak_angle, 10);

Note

The method read_initial_calibration_from_file expects a text file in the format below. Each line denotes the DG parameters for each module.

module 0 center  643.320033188550 +- 0.0000 conversion 0.657661167459868E-04 +- 0.0000 offset  0.00000000000000     +- 0.0000
module 1 center  633.044070300816 +- 0.0000 conversion 0.657618957538105E-04 +- 0.0000 offset  5.00486981153634     +- 0.0000

If youre file format deviates from the above format implement your custom file reader inheriting from the class SimpleFileInterface (SimpleFileInterface) and pass it to the constructor. Similarly for the acquisition files, AngleCalibration uses per default the class MythenFileReader (MythenFileReader) expecting hdf5 files with entries ‘data’, ‘DetectorAngle’ and ‘CounterMask’.

class AngleCalibration

Public Functions

AngleCalibration(std::shared_ptr<MythenDetectorSpecifications> mythen_detector_, std::shared_ptr<FlatField> flat_field_, std::optional<std::shared_ptr<MythenFileReader>> mythen_file_reader_ = std::nullopt, std::optional<std::shared_ptr<SimpleFileInterface>> custom_file_ptr_ = std::nullopt)

Constructor for AngleCalibration class.

Parameters:

• mythen_detector_ – ptr to MythenDetectorSpecifications storing all mythen specific parameters

• flat_field_ – ptr to FlatField class storing inverse normalized flat field

• mythen_file_reader – optional, pass if you use custom acquisition files - default: reads hdf5 files

• custom_file_ptr – optional, pass if you use custom files to store initial angle parameters - default: initial angle parameters supports following format module [module_index] center [center] +- [error] conversion [conversion] +- [error] offset [offset] +- [error]

void set_histogram_bin_width(double bin_width = 0.0036)

set the histogram bin width [degrees] default ‘0.0036°’

double get_histogram_bin_width() const

get histogram bin width [degrees]

ssize_t new_number_of_bins() const

number of bins of fixed angle width bin histogram

ssize_t get_base_peak_ROI_num_bins() const

number of bins covered by base peak region of interest default ‘101’ bins

void set_base_peak_ROI(const double base_peak_roi_ = 0.05)

set base peak region of interest

Parameters:

base_peak_roi_ – width of base peak ROI [degrees] e.g. [base_peak - base_peak_ROI, base_peak + base_peak_ROI] given in angles defaults to ‘0.05°’

double get_base_peak_ROI() const

base peak region of interest

Returns:

width of base peak ROI [degrees] e.g. [base_peak - base_peak_ROI, base_peak + base_peak_ROI] given in angles [degrees]

std::shared_ptr<MythenDetectorSpecifications> get_detector_specifications() const

void read_initial_calibration_from_file(const std::string &filename)

reads the historical Detector Group (DG) parameters from file and transforms them to Best Computing parameters

Warning

only works if member m_custom_detectot_file_ptr supports reading the format

const DGParameters &get_DGparameters() const

get the histoic DG parameters

const BCParameters &get_BCparameters() const

void calibrate(const std::vector<std::string> &file_list, const double base_peak_angle, std::optional<std::filesystem::path> output_file = std::nullopt)

calibrates the BC (best computing) parameters for all modules

Warning

method only works if mythen_file_reader supports reading the file format

Parameters:

• file_list – vector of file_names of acquisition files

• base_peak_angle – angle of the selcted base peak [degrees]

• output_file – optional, if provided the optimized BC parameters are converted back to DG parameters and are appended to the file (given as full file path)

void calibrate(const std::vector<std::string> &file_list_, const double base_peak_angle_, const size_t module_index)

calibrates the BC (best computing) parameters for one module

Warning

method only works if mythen_file_reader supports reading the file format

Parameters:

• file_list – vector of file_names of acquisition files

• base_peak_angle – angle of the selcted base peak given in degrees

• module_index – index of module to be calibrated

bool base_peak_is_in_module(const size_t module_index, const double detector_angle, std::optional<double> bounds_in_angles = std::nullopt) const

check if base peak ROI is contained within module region

Parameters:

• detector_angle – detector position (offset of first strip from default detector position) [degrees]

• bounds_in_angle – boundary that is acceptable [degrees]- per default the base peak ROI width is used (adjustable for debugging) //TODO deprecated

Returns:

true if [base_peak - base_peak_ROI, base_peak + base_peak_ROI] is fully contained within the module region

void set_base_peak_angle(const double base_peak_angle_)

set angle of base peak

Parameters:

base_peak_angle_ – base peak angle [degrees]

double get_base_peak_angle() const

get angle of base peak

Returns:

base peak angle [degrees]

bool module_is_disconnected(const size_t module_index) const

check if a module only has bad channels

NDArray<double, 1> redistribute_photon_counts_to_fixed_angle_width_bins(const MythenFrame &frame) const

redistribute photon counts to fixed angle width bins for given frame

Returns:

flatfield corrected and variance scaled photon counts redistributed to fixed angle width bins given in the range [min_angle, max_angle]

NDArray<double, 1> redistribute_photon_counts_to_fixed_angle_width_bins(const MythenFrame &frame, const size_t module_index) const

redistribute photon counts to fixed angle width bins for the specified module region

Parameters:

module_index – index of module region to redistribute

Returns:

flatfield corrected and variance scaled photon counts in the module region redistributed to fixed angle width bins array covers the range [min_angle, max_angle]

NDArray<double, 1> redistributed_photon_counts_in_base_peak_ROI(const MythenFrame &frame, const size_t module_index) const

redistribute photon counts to fixed angle width bins which are within base peak region

Parameters:

module_index – index of module region to redistribute

Returns:

flatfield corrected and variance scaled photon counts in the base peak region redistributed to fixed angle width bins array only covers the base peak region

double diffraction_angle_from_DG_parameters(const size_t module_index, const double detector_angle, size_t strip_index, const double distance_to_strip = 0) const

calculates diffraction angle from DG module parameters (used in Beer’s Law)

Parameters:

• detector_angle – detector position [degrees]

• strip_index – local strip index of module e.g. 0-1279

• distance_to_strip – distance to strip [given in strips]

Returns:

diffraction angle [degrees]

double diffraction_angle_from_BC_parameters(const size_t module_index, const double detector_angle, size_t strip_index, const double distance_to_strip = 0) const

calculates diffraction angle from BC (best computing) module parameters (used in Beer’s Law)

Parameters:

• detector_angle – detector position [degrees]

• strip_index – local strip index of module e.g. 0-1279

• distance_to_strip – distance to strip [given in strips]

Returns:

diffraction angle [degrees]

double diffraction_angle_from_EE_parameters(const double module_center_distance, const double normal_distance, const double angle, const double detector_angle, size_t strip_index, const double distance_to_strip = 0) const

calculates diffraction angle from EE module parameters (used in Beer’s Law)

Parameters:

• detector_angle – detector position [degrees]

• strip_index – local strip index of module

• distance_to_strip – distance to strip [given in strips]

Returns:

diffraction angle [degrees]

void write_to_file(const std::filesystem::path &filename) const

converts optimized best computing parameters back to DG parameters and writes them to file

Parameters:

filename – full path tooutput file

Private Functions

double angular_strip_width_from_DG_parameters(const size_t module_index, size_t local_strip_index) const

calculated the strip width expressed as angle from DG module parameters

Parameters:

• moudle_index – index of module

• strip_index – local strip index of module e.g. 0-1279

Returns:

strip width in angles [degrees]

double angular_strip_width_from_BC_parameters(const size_t module_index, const size_t local_strip_index) const

calculated the strip width expressed as angle from BC module parameters

Parameters:

• moudle_index – index of module

• strip_index – local strip index of module e.g. 0-1279

Returns:

strip width in angles [degrees]

double angular_strip_width_from_EE_parameters(const double module_center_distance, const double normal_distance, const double angle, const size_t local_strip_index) const

calculated the strip width expressed as angle from EE module parameters

Parameters:

• moudle_index – index of module

• strip_index – local strip index of module e.g. 0-1279

Returns:

strip width in angles [degrees]

size_t global_to_local_strip_index_conversion(const size_t global_strip_index) const

converts global strip index to local strip index

template<bool base_peak_ROI_only = false>
void redistribute_photon_counts_to_fixed_angle_width_bins(const size_t module_index, const MythenFrame &frame, NDView<double, 1> fixed_angle_width_bins_photon_counts, NDView<double, 1> inverse_fixed_angle_width_bins_photon_counts_variance, std::optional<NDView<double, 1>> S0 = std::nullopt, std::optional<NDView<double, 1>> S1 = std::nullopt, std::optional<NDView<double, 1>> S2 = std::nullopt) const

redistributes photon counts around designated region to fixed angle width bins

Template Parameters:

base_peak_ROI_only – false (redistribute entire module region), true: (only redistribute base peak ROI)

Parameters:

• module_index – index of module

• frame – data from acquisition (storing detector position and photon counts)

• fixed_angle_width_bin_photon_counts – stores redistributed photon counts for fixed angle width bin scaled by variance and flatfield corrected

• inverse_fixed_angle_width_bins_photon_counts_variance – stores inverse variance

• S0, S1, S2 – used to calculate similarity criterion between peaks

double calculate_similarity_of_peaks(const size_t module_index, PlotHandle gp = nullptr) const

redistributes photon counts to fixed angle width bins around base peak for all acquisitions in file_list and calculates the similarity between the found base peaks regions

plot wrapper for gnuplot plot to visualize calibration process (default nullptr)

Returns:

similarity of peaks

double similarity_criterion(const NDView<double, 1> S0, const NDView<double, 1> S1, const NDView<double, 1> S2, const size_t num_runs) const

compares multiple base peak ROIS from different acquisitions and calculate similarity/variance based on goodness_of_fit and weighted average //TODO explain better

Parameters:

• S0 – inverse photon_varaince over all runs

• S1 – inverse_photon_variance*photon_count over all runs

• S2 – inverse_photon_variance*photon_count² over all runs

• num_runs – number of frames for which base peak ROI is covered by the respective module

Returns:

similarity criterion

void optimization_algorithm(const size_t module_index, PlotHandle gp = nullptr, const double shift_parameter1 = 0.01, const double shift_parameter2 = 0.005)

optimizes BC parameters of given module based on similarity criterion

Parameters:

• gp – plot wrapper for gnuplot plot to visualize calibration process (default nullptr)

• shift_parameter1 – parameter step for parameter angle between module center and module normal (angle_center_module_normal) (default ‘0.01’)

• shift_parameter2 – parameter step for parameter distance between module center and sample (module_center_sample_distances) (default ‘0.005’)

std::pair<double, double> calculate_corrected_photon_counts(const double photon_counts, const size_t global_strip_index) const

calculated the corrected photon counts and its variance for a given raw photon count

Parameters:

photon_counts – raw photon counts

Returns:

pair {corrected photon counts, inverse variance of corrected photon counts}

double rate_correction_factor(const double photon_counts, const double expsoure_time) const

calculate the rate correction factor taking into account the dead time

Returns:

rate correction factor

void append_to_file(std::ofstream &file, const size_t module_index, const double center, const double conversion, const double offset) const

appends given parameters to file

Private Members

DGParameters DGparameters = {}

BCParameters BCparameters = {}

std::shared_ptr<MythenDetectorSpecifications> mythen_detector = {}

detector specifications

std::shared_ptr<FlatField> flat_field = {}

double histogram_bin_width = 0.0036

bin width of fixed angle bin histogram [degrees]

double base_peak_roi = 0.05

half the width of region of interest of base peak e.g. [base_peak_angle - base_peak_roi, base_peak_angle + base_peak_roi] [degrees]

ssize_t num_bins = {}

double base_peak_angle = {}

center of base peak to use for calibration [degrees]

std::vector<std::string> file_list = {}

list of acquisition files used for calibration

std::shared_ptr<MythenFileReader> mythen_file_reader = {}

file reader to read acquisition files default: expects hdf5 file with fields ‘data’, ‘DetectorAngle’ and ‘CounterMask’

std::shared_ptr<SimpleFileInterface> custom_file_ptr = std::make_shared<InitialAngCalParametersFile>()

file reader to read initial DG parameters deafult: expect text file with format [module [module_index] center [center] +- [error] conversion [conversion] +- [error] offset [offset] +- [error]