AngleCalibration¶

Class to perform angular conversion and to calibrate the mythen detector parameters used for conversion. For the calibration the “Best computing” BC parameters are used. However, as initial parameters or for conversion 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 for Calibration:¶

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);

API:¶

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 function.

Note

The method read_bad_channels_from_file expects a text file using the format below. Each line denotes the index of a bad channel. Consecutive bad channels can be stored on one line e.g. channels with 20-42 are bad channels.

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 function.

class AngleCalibration¶

Public Functions

AngleCalibration(std::shared_ptr<MythenDetectorSpecifications> mythen_detector_, std::shared_ptr<FlatField> flat_field_, std::shared_ptr<MythenFileReader> mythen_file_reader_)¶

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 – file reader to read mythen acquisition files

void plot_all_base_peaks(PlotHandle gp)¶

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 num_fixed_angle_width_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_width(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_width() const¶

half odf the width of 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]

double get_base_peak_angle() const¶

get base peak angle

Returns:: angle of base peak [degrees]

void set_base_peak_angle(const double base_peak_angle_)¶

set base peak angle

Parameters:: base_peak_angle_ – angle of base peak [degrees]

void set_calibration_files(const std::vector<std::string> &file_list)¶

set vector of acquisitions files for calibration or conversion

Parameters:: file_list –

std::shared_ptr<MythenDetectorSpecifications> get_detector_specifications() const¶: get detector specifications

void read_initial_calibration_from_file(const std::string &filename, const std::shared_ptr<SimpleFileInterface> file_reader = std::make_shared<InitialAngCalParametersFile>())¶

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

Parameters:

filename – name of file
file_reader – filereader to read file (default InitialAngCalParametersFile: following format module [module_index] center [center] +- [error] conversion [conversion] +- [error] offset [offset] +- [error])

void read_bad_channels_from_file(const std::string &filename, std::shared_ptr<SimpleFileInterface> file_reader = std::make_shared<CustomBadChannelsFile>())¶

read bad channels from file

Parameters:

filename – bad channels filename
file_reader – file_reader to read bad channels file (default: CustomBadChannelsFile bad channel file is expected to be a text file where each line stores the channel index of a bad channel. Consecutive bad channels can be stored in one line by seperating the first and last channel index of the bad channel block e.g. bad_channel_index0-bad_channel_index1.))

NDView<bool, 1> get_bad_channels() const¶

void set_bad_channels(const NDArray<bool, 1> &bad_channels_)¶

set bad channels

Parameters:: bad_channels_ – boolean NDArray of size of total number of strips/channels in detector, stores ‘TRUE’ if strip is a bad channel otherwise ‘FALSE’

const DGParameters &get_DGparameters() const¶: get the histoic DG parameters

const BCParameters &get_BCparameters() const¶: get the current BC parameters

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

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_coupled_parameters(const std::vector<double> &detector_angles)¶

calibrates distance to module center and angle of module center and normal (L and delta) for all modules

Parameters:: detector_angles – vector of monitor positions for acquisition files

void calibrate_coupled_parameters(const size_t module_index, const std::vector<MythenFrame> &frames_width_base_peak_overlap)¶

calibrates distance to module center and angle of module center and normal (L and delta) for a specific module

Parameters:

module_index – index of module to be calibrated
frames_width_base_peak_overlap – frames with base peak overlap for the module

void calibrate_offset(const std::vector<double> &detector_angles)¶

calibrates the angle between center of module and beam (phi) for all modules

Parameters:: detector_angles – vector of monitor positions for acquisition files

void calibrate_offset(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap, const std::vector<MythenFrame> &frames_with_base_peak_overlap_prev_module)¶

calibrates the angle between center of module and beam (phi) for a specific module

Parameters:

module_index – index of module to be calibrated
frames_with_base_peak_overlap – frames with base peak overlap module to be calibrated
frames_with_base_peak_overlap_prev_module – frames with base peak overlap prev module

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

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

double center_base_peak(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap)¶

calculates the average angle of the base peak center over several acquisitions for a given module index

Parameters:

module_index – index of module to calculate base peak center for
frames_with_base_peak_overlap – frames with base peak overlap for the given module index

Returns:

average angle of base peak center [degrees]

bool base_peak_is_in_module(const size_t module_index, const double detector_angle) 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]
Returns:: true if [base_peak - base_peak_ROI, base_peak + base_peak_ROI] is fully contained within the module region

bool module_is_disconnected(const size_t module_index) const¶: check if a module only has bad channels

void set_scale_factor(const double scale_factor_)¶: set the scale factor to scale everything to a reasonable scale e.g. can be incident_intensity of first acquisition

double get_scale_factor() const¶: get the currently configured scale factor (if any)

void set_angular_range(const double min_angle, const double max_angle)¶

sets the angular range for the diffraction pattern e.g. diffraction pattern calculated for [min_angle, max_angle]

Parameters:

min_angle – minimum angle [degrees]
max_angle – maximum angle [degrees]

std::pair<double, double> get_angular_range() const¶

gets the angular range for the diffraction pattern e.g. diffraction pattern calculated for [min_angle, max_angle]

Returns:: pair of (min_angle, max_angle) [degrees]

NDArray<double, 1> convert(const std::vector<std::string> &file_list)¶

Performs angular conversion e.g. calculates from raw photon counts the resulting diffraction pattern.

Parameters:: file_list – vector of file_names of acquisition files
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)¶

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

Parameters:

frame – raw photons from acquisition
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)¶

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]

std::pair<double, double> rate_correction(const double photon_counts, const double photon_count_error, const double exposure_time) const¶

calculate the rate corrected photon counts taking into account the dead time

Parameters:

photon_counts – photon counts
photon_count_error – error of photon counts (generally variance error is used)
exposure_time – exposure time of acquisition [s]

Returns:

pair {corrected photon counts, propagated_error}

Public Static Functions

static void write_DG_parameters_to_file(const std::filesystem::path &filename, const DGParameters &parameters)¶

writes DG parameters 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

double elastic_correction(const double detector_angle) const¶

calculates the elastic correction factor for given detector angle based on torsional compliance correction model

Parameters:: detector_angle – detector axis motor position [degrees]

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, NDView<double, 1> sum_statistical_weights)¶

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
sum_statistical_weights – sum of statistical weights to normalize

double calculate_similarity_of_peaks_between_acquisitions(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap, PlotHandle gp = nullptr)¶

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)

Parameters:: frames_with_base_peak_overlap – vector of frames from acquisitions for which the base peak ROI is covered by the respective module region
Returns:: similarity of peaks

double calculate_similarity_of_peaks_between_modules(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap_module, const std::vector<MythenFrame> &frames_with_base_peak_overlap_prev_module, PlotHandle gp = nullptr)¶

double chi_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 optimize_coupled_parameters(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap, PlotHandle gp = nullptr, const double delta_parameter1 = 0.5, const double delta_parameter2 = 1.0e-6)¶

optimizes module center distance L and angle center module normal delta of BC parameters of given module based on chi similarity criterion

Parameters:

frames_with_base_peak_overlap – vector of frames from acquisitions for which the base peak ROI is covered by the respective module region
gp – plot wrapper for gnuplot plot to visualize calibration process (default nullptr)
delta_parameter1 – parameter step for parameter module center distance L (default ‘0.5’)
delta_parameter2 – parameter step for parameter angle between center of module and module normal (delta) (default ‘1.0e-6’)

void optimize_offset_parameter(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap, const std::vector<MythenFrame> &frames_with_base_peak_overlap_prev_module, PlotHandle gp = nullptr, double delta_parameter = 0.005)¶

optimizes angle between center of module and beam (\psi) of BC parameters of given module based on chi similarity criterion and center of base peak

Parameters:

frames_with_base_peak_overlap – vector of frames with base peak overlap for module
gp – plot wrapper for gnuplot plot to visualize calibration process (default nullptr)
delta_parameter – parameter step for angle between center of module and beam (default ‘0.005’)

std::pair<double, double> flatfield_correction(const double photon_counts, const double photon_counts_error, const size_t global_strip_index) const¶

calculated the flatfield corrected photon counts and the error

Parameters:

photon_counts – photon counts
photon_counts_error – error of photon counts (generally variance error is used)
global_strip_index – strip index of photon counts

Returns:

pair {corrected photon counts, propagated_error}

std::pair<double, double> incident_intensity_correction(const double photon_counts, const double photon_counts_error, const uint64_t incident_intensity) const¶

calculate the incident intensity corrected photon counts

Parameters:

photon_counts – photon counts
photon_counts_error – error of photon counts (generally variance error is used)
incident_intensity – incident intensity

Returns:

pair {corrected photon counts, propagated_error}

std::pair<double, double> transverse_width_correction(const double photon_counts, const double photon_counts_error, const size_t module_index, const size_t strip_index) const¶

std::pair<double, double> photon_count_correction(double photon_counts, const size_t global_strip_index, const uint64_t I0, const double exposure_time) const¶

calculate the corrected photon counts (flatfield, rate, incident intensity)

Parameters:

photon_counts – photon counts
global_strip_index – strip index of photon counts
I0 – incident intensity
exposure_time – exposure time of acquisition [s]

Returns:

pair {corrected photon counts, propagated_error}

void plot_calibration_step_coupled_parameters(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap, PlotHandle gp)¶

void plot_calibration_step_offset_parameter(const size_t module_index, const std::vector<MythenFrame> &frames_with_base_peak_overlap_module, const std::vector<MythenFrame> &frames_with_base_peak_overlap_prev_module, PlotHandle gp)¶

Private Members

DGParameters DGparameters = {}¶

BCParameters BCparameters = {}¶

NDArray<bool, 1> bad_channels = {}¶: Array of size strips/channels in detector, stores ‘TRUE’ if strip is a bad channel otherwise ‘FALSE’.

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_width = 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]

double base_peak_angle = {}¶: center of base peak to use for calibration [degrees]

double m_scale_factor = {1.0}¶: scale factor to scale everything to a reasonable scale e.g. can be incident_intensity of first acquisition @default 1.0

double m_min_angle = -180.0¶: minimum angle for angular conversion [degrees]

double m_max_angle = 180.0¶: maximum angle for angular conversion [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 mythen acquisition files

Private Static Functions

static void append_to_file(std::ofstream &file, const size_t module_index, const double center, const double conversion, const double offset)¶: appends given parameters to file