generic#

Generic algorithms.

This module contains algorithms that perform generic data processing operations, not tied to a specific experimental technique (e.g.: data accumulation, radial averaging, binning, etc.).

class RadialProfile(*, radius_pixel_map, parameters)#

Radial average calculation.

This algorithm stores all the parameters needed to calculate the pixel-based radial profile of a detector data frame. After the algorithm has been initialized, it can be invoked to compute the radial profile of a data frame.

Parameters:

  • radius_pixel_map (ndarray[Any, dtype[float64]]) –

    A pixel map storing radius information for the detector data frame on which the algorithm is applied.

    • The array must have the same shape as the data frame on which the algorithm is applied.

    • Each element of the array must store, for the corresponding pixel in the data frame, its distance (in pixels) from the origin of the detector reference system (usually the center of the detector).

  • parameters (RadialProfileParameters) –

    A set of OM configuration parameters collected together in a parameter group. The parameter group must contain the following entries:

    • radius_bin_size: The width, in pixels, of each radius bin in the radial profile.

    • bad_pixel_map_filename: The relative or absolute path to an HDF5 file containing a bad pixel map. The map can be used to exclude regions of the data frame from the calculation of the radial profile. If the value of this entry is None, the calculation includes the full frame. Defaults to None.

      • The map must be a numpy array with the same shape as the data frame on which the algorithm is applied.

      • Each pixel in the map must have a value of either 0, meaning that the corresponding pixel in the data frame should be ignored, or 1, meaning that the corresponding pixel should be included in the calculation of the profile.

      • The map is only used to exclude regions from the calculation: the data is not modified in any way.

    • bad_pixel_map_hdf5_path: The internal HDF5 path to the data block where the bad pixel map data is located. Defaults to None.

      • If the bad_pixel_map_filename entry is not None, this entry must also be provided, and cannot be None. Otherwise it is ignored.

get_radial_bin_labels()#

Gets the radial bin label information.

This function returns an array, with the same shape as the data frame on which the algorithm is applied, containing bin labelling information. Each element of the array corresponds to a pixel in the data frame, and stores the index of the radial bin in which the pixel falls according to the radius information provided to the algorithm.

Returns:

An array containing the bin labelling information.

Return type:

ndarray[Any, dtype[int64]]

get_bad_pixel_map()#

Gets the bad pixel map provided to the algorithm.

This function returns the bad pixel map provided to the algorithm at initialization. If no bad pixel map was provided, the function returns None.

Returns:

The bad pixel map provided to the algorithm at initialization, or None if no map was provided.

Return type:

ndarray[Any, dtype[bool_]] | None

calculate_profile(data)#

Calculates the radial profile for a detector data frame.

This function calculates the radial profile of a provided detector data frame.

Parameters:

data (ndarray[Any, dtype[float64 | int64]]) – the detector data frame for which the radial profile must be calculated.

Returns:

The radial profile.

Return type:

ndarray[Any, dtype[float64]]

class Binning(*, layout_info, parameters)#

Binning of detector data frames.

This algorithm stores all the parameters needed to bin the data in a detector data frame. After the algorithm has been initialized, it can be invoked to bin the data in a data frame, or to generate pixel maps and masks that are compatible with the binned data.

Parameters:

  • layout_info (DetectorLayoutInformation) – An object storing information about the internal data layout of the detector frame on which the algorithm is applied (number and size of ASICs, etc.).

  • parameters (BinningParameters) –

    A set of OM configuration parameters collected together in a parameter group. The parameter group must contain the following entries:

    • bin_size: The size of the binning area in pixels (A square area of bin_size x bin_size pixels in the original data frame is transformed by the algorithm into a single binned pixel).

    • bad_pixel_map_filename: The absolute or relative path to an HDF5 file containing a bad pixel map. The map can be used to exclude regions of the the data frame from the binning calculation. If the value of this entry is None, the full frame is used to compute the binned data. Defaults to None.

      • The map must be a numpy array of the same shape as the data frame on which the algorithm is applied.

      • Each pixel in the map must have a value of either 0, meaning that the corresponding pixel in the data frame must be ignored in the binning calculation, or 1, meaning that the pixel must be included in the calculation.

    • bad_pixel_map_hdf5_path: The internal HDF5 path to the data block where the bad pixel map is stored.

      • If the value of the bad_pixel_map_filename entry is not None, this parameter must also be provided, and cannot be None. Otherwise it is ignored.

    • min_good_pix_count: The minimum number of non-excluded pixels that must be present in a binning area for the generated binned pixel to be considered valid (pixels of the original frame can be excluded from the binning calculation using a bad pixel map). Defaults to a number corresponding to all the pixels in the binning area (the square value of the bin_size argument).

    • bad_pixel_value: The value to be written in the binned data frame when a pixel is invalid (too many pixels in the original inning area are excluded by the calculation). Defaults to MAXINT if the data to bin is of integer type, otherwise defaults to numpy.nan.

is_passthrough()#

Whether the algorithm performs a simple passthrough operation.

This function returns information on whether the algorithm performs a simple passthrough operation (See [BinningPassthrough][om.algorithms.generic.BinningPassthrough]). For this algorithm, the function always returns False.

Returns:

Whether the algorithm performs a simple passthrough operation.

Return type:

bool

get_bin_size()#

Gets the size of the binning area.

This function returns the size of the area in the original data that gets transformed in a single pixel in the binned data. Specifically, the function returns the length of the edge of the area: if an area of size bin size x bin size in the original data ends up in a single binned pixel, the function returns the value of bin_size.

Returns:

The length of the edge of the binning area.

Return type:

int

get_binned_layout_info()#

Gets the data layout information for the binned data frame.

This function returns information about the internal data layout of a binned frame generated by the algorithm.

Returns:

A dictionary with the data layout information for the binned frame.

Return type:

DetectorLayoutInformation

bin_detector_data(*, data)#

Computes a binned version of the detector data frame.

This function computes the binned version of a provided detector data frame. For each binning area in the original data frame, the function initially computes the average value of all pixels, excluding the ones that are must be ignored. It then multiplies the calculated average value by the total number of pixels in the binning area. The result is used to fill, in the binned frame, the binned pixel corresponding to the original area. If, however, the binned pixel is determined to be invalid (too many pixels in the original area must be ignored), this function uses a fallback value to fill it.

Parameters:

data (ndarray[Any, dtype[float64 | int64]]) – The detector data frame on which the binning must be performed.

Returns:

A binned version of the detector data frame.

Return type:

ndarray[Any, dtype[float64]]

bin_bad_pixel_map(*, mask)#

Computes a bad pixel map for a binned data frame.

Starting from a bad pixel map designed for the original detector frame, this function calculates a bad pixel map that can be used with a binned data frame generated by the algorithm.

In the bad pixel map computed by this function, only binned pixels originating from binning areas containing exclusively good pixels are marked as good. If even a single bad pixel was present in the original binning area, this function labels the corresponding binned pixel as bad.

Parameters:

mask (ndarray[Any, dtype[int64]] | None) –

An array storing a bad pixel map for the original data frame.

  • The map must be a numpy array of the same shape as the data frame on which the binning algorithm is applied.

  • Each pixel in the map must have a value of either 0, meaning that the corresponding pixel in the data frame should be considered bad, or 1, meaning that the corresponding pixel should be considered good.

  • This argument is mandatory. However, the argument can be set to None, in which case the function will do nothing and return None.

Returns:

Either an array containing the binned map or None if the mask input argument is None.

Return type:

ndarray[Any, dtype[int64]] | None

bin_pixel_maps(*, pixel_maps)#

Computes pixel maps for a binned data frame.

Starting from pixel maps designed for the original detector frame, this function calculates pixel maps that can be used with a binned data frame generated by the algorithm.

Parameters:

pixel_maps (PixelMaps) – A dictionary storing the pixel maps for the original detector frame.

Returns:

A dictionary storing the pixel maps for the binned frame.

Return type:

PixelMaps

bin_peak_positions(peak_list)#

Computes peaks positions for a binned data frame.

Starting from a list of peaks detected in the original detector frame, this function calculates the coordinates of the same peaks in a binned data frame generated by the algorithm.

Parameters:

peak_list (PeakList) – An dictionary storing information about a set of peaks detected in the original detector frame.

Returns:

A dictionary storing information about the detected peaks in the binned data frame.

Return type:

PeakList

class BinningPassthrough(*, layout_info)#

Passthrough binning of detector data frames.

This algorithm has the same interface as the [Binning][om.algorithms.generic.Binning] algorithm. All the functions, however, perform no operation at all, simply returning the original detector layout information, detector data frame, bad pixel map, or pixel maps.

This algorithm exists to avoid filling the code base with if statements that just check if binning is required and call the Binning algorithm accordingly.

After a single initial check of the form:

if binning_required:
    binning = Binning(...)
else:
    binning = BinningPassthrough(...)

The rest of the code can avoid performing checks and simply call the methods of the binning instance, expecting the correct behavior.

Parameters:

layout_info (DetectorLayoutInformation) – An object storing information about the internal layout of the detector data frame on which the algorithm is applied (number and size of ASICs, etc.).

is_passthrough()#

Whether the algorithm performs a passthrough operation.

This function returns information on whether the algorithm performs a simple passthrough operation. For this algorithm, the function always returns True.

Returns:

Whether the algorithm performs a simple passthrough operation.

Return type:

bool

get_bin_size()#

Gets the size of the binning area.

This function returns the size of the area in the original data that gets transformed in a single pixel in the binned data.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns 1.

Returns:

The size of the edge of binning area.

Return type:

int

get_binned_layout_info()#

Gets the data layout information for the binned data frame.

This function returns information about the internal data layout of a binned frame generated by the algorithm.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns the layout information initially provided to the algorithm.

Returns:

A dictionary with the data layout information for the binned frame.

Return type:

DetectorLayoutInformation

bin_detector_data(*, data)#

Computes a binned version of the detector data frame.

This function generates the binned version of a provided detector data frame.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns the detector data frame provided as input.

Parameters:

data (ndarray[Any, dtype[float64 | int64]]) – The detector data frame on which the binning must be performed.

Returns:

A binned version of the detector data frame.

Return type:

ndarray[Any, dtype[float64]]

bin_bad_pixel_map(*, mask)#

Computes a bad pixel map for the binned data frame.

Starting from a bad pixel map designed for the original detector frame, this function calculates a bad pixel map that can be used with a binned data frame generated by the algorithm.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns the bad pixel map provided as input.

Parameters:

mask (ndarray[Any, dtype[int64]] | None) –

An array storing a bad pixel map for the original data frame.

  • The map must be a numpy array of the same shape as the data frame on which the binning algorithm is applied.

  • Each pixel in the map must have a value of either 0, meaning that the corresponding pixel in the data frame should be considered bad, or 1, meaning that the corresponding pixel should be considered good.

  • This argument is mandatory. However, the argument can be set to None, in which case the function will do nothing and return None.

Returns:

Either an array containing the binned map or None if the mask input argument is None.

Return type:

ndarray[Any, dtype[int64]] | None

bin_pixel_maps(*, pixel_maps)#

Computes pixel maps for a binned data frame.

Starting from pixel maps designed for the original detector frame, this function calculates pixel maps that can be used with a binned data frame generated by the algorithm.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns the pixel maps provided as input.

Parameters:

pixel_maps (PixelMaps) – A dictionary storing the pixel maps for the original detector frame.

Returns:

A dictionary storing the pixel maps for the binned frame.

Return type:

PixelMaps

bin_peak_positions(peak_list)#

Computes peaks positions for a binned data frame.

Starting from a list of peaks detected in the original detector frame, this function calculates the coordinates of the same peaks in a binned data frame generated by the algorithm.

Since the BinningPassthrough algorithm performs no binning operation at all, this function always returns the peak list provided as input.

Parameters:

peak_list (PeakList) – An dictionary storing information about a set of peaks detected in the original detector frame.

Returns:

A dictionary storing information about the detected peaks in the binned data frame.

Return type:

PeakList