cheetah#

Cheetah classes and functions.

This module contains classes and functions used by Cheetah, a data-processing program for Serial X-ray Crystallography, based on OM but not designed to be run in real time.

class ClassSumData(num_frames, sum_frames, peak_powder)#

Cheetah data class sum data.

A dictionary storing the number of detector frames belonging to a specific data class, their sum, and the virtual powder pattern generated from the Bragg peaks detected in them.

Parameters:

  • num_frames (int)

  • sum_frames (ndarray[Any, dtype[float64]])

  • peak_powder (ndarray[Any, dtype[float64]])

num_frames: int#

The number of detector frames belonging to the data class.

sum_frames: ndarray[Any, dtype[float64]]#

The sum of the detector frames belonging to the class.

peak_powder: ndarray[Any, dtype[float64]]#

The virtual powder pattern for the data class.

class FramelistData(timestamp, event_id, frame_is_hit, filename, index_in_file, num_peaks, average_intensity)#

Cheetah frame list data.

This named tuple is used to store the detector frame data which is later written into the frames.txt file.

Parameters:

  • timestamp (float64)

  • event_id (str | None)

  • frame_is_hit (int)

  • filename (str)

  • index_in_file (int)

  • num_peaks (int)

  • average_intensity (float64)

timestamp: float64#

The timestamp of the frame.

event_id: str | None#

A unique identifier for the event attached to the frame.

frame_is_hit: int#

A flag indicating whether the event attached to the frame is labelled as a hit.

filename: str#

The name of the file containing the frame.

index_in_file: int#

The index of the frame in the file.

num_peaks: int#

The number of peaks in the frame.

average_intensity: float64#

The average intensity of the Bragg peaks detected in the frame.

class CheetahStatusFileWriter(*, parameters)#

Cheetah status file writer.

This class stores information about the current status of data processing in Cheetah (number of processed frames, number of hits, etc.).

After the class has been initialized, the information it stores can be updated with new data processing statistics. Upon receiving them, this class writes the updated data processing information to a “status” file, which can then be inspected by external programs.

Parameters:

parameters (CheetahParameters) – A set of OM configuration parameters collected together in a parameter group.

update_status(*, status='', num_frames=0, num_hits=0)#

Updates the data processing information and writes the status to a file.

This function updates the data stored by this class with the provided data processing information. Additionally, it writes the updated data processing statistics to a status file. External program, like the Cheetah GUI, can inspect this file to get information about Cheetah’s current state.

Parameters:

  • status (str) – A string describing the current status of the data processing in Cheetah.

  • num_frames (int) – The number of detector frames processed so far by Cheetah.

  • num_hits (int) – The number of hits found so far by Cheetah.

Return type:

None

class CheetahlistFilesWriter(*, parameters)#

Cheetah list files writer.

This class manages the information that gets written to the ‘frames.txt’, ‘cleaned.txt’, ‘events.lst’, ‘hits.lst’ and ‘peaks.txt’ files, required by the Cheetah GUI.

  • ‘frames.txt’ contains a list of all the detector frames processed by Cheetah, with information about the frame timestamp, event ID, whether the frame is a hit, the name of the file containing the frame, the index of the frame in the file, the number of peaks detected in the frame, and the average intensity of the peaks in the frame.

  • ‘cleaned.txt’ contains a list of all the detector frames that have been identified as hits by Cheetah, with the same information as ‘frames.txt’.

  • ‘events.lst’ contains a list of all the event identifiers for the detector frames processed by Cheetah.

  • ‘hits.lst’ contains a list of all the event identifiers for the detector frames that have been identified as hits by Cheetah.

  • ‘peaks.txt’ contains a list of all the Bragg peaks detected by Cheetah, with information about the event ID of the frame to which the peak belongs, the number of peaks in the frame, the fast-scan and slow-scan coordinates of the peak, the peak intensity, the number of pixels in the peak, the maximum pixel intensity in the peak, and the signal-to-noise ratio of the peak.

Parameters:

parameters (CheetahParameters) – An object storing Cheetah’s configuration parameters.

add_frame(*, frame_data, peak_list)#

Adds a frame to the list files.

This function adds information related to a single detector data frame to the list files.

Parameters:

  • frame_data (FramelistData) – Information about the frame that must be added to the list files.

  • peak_list (PeakList) – The list of peaks detected in the frame being added to the files.

Return type:

None

flush_files()#

Flushes the list files.

This function flushes the list files to disk, writing on storage media the information still stored only in memory.

Return type:

None

sort_frames_and_close_files()#

Performs final operations on the list files.

This functions performs some operations on the list files just before closing them: it sorts the frames according to their event identifier and it writes the sorted data to the frames.txt, cleaned.txt and events.lst files. The function then closes all the list files.

Return type:

None

class CheetahClassSumsAccumulator(*, parameters, num_classes)#

Cheetah data class sum accumulator.

This class accumulates information about the sum and virtual powder pattern of all detector frames belonging to a specific data class.

After the accumulator has been initialized, data frame information can be added to it. The cumulative sum and virtual powder pattern for the data in the class can be retrieved from the accumulator either after a predefined number of frames have been added, or on-demand.

Parameters:

  • parameters (CheetahParameters) – A set of OM configuration parameters collected together in a parameter group.

  • num_classes (int) – The total number of data classes currently managed by Cheetah.

add_frame(*, class_number, frame_data, peak_list)#

Adds a detector frame to the accumulator.

This function adds information about a detector data frame to the accumulator.

Parameters:

  • class_number (int) – The data class number to which the frame being added belongs.

  • frame_data (ndarray[Any, dtype[float64 | int64]]) – Information about the detector data frame that must be added to the accumulator.

  • peak_list (PeakList) – The list of peaks detected in the frame being added to the accumulator.

Return type:

None

get_sums_for_sending(disregard_counter=False)#

Retrieves the frame sum and virtual powder pattern from the accumulator.

This function returns the data stored in the accumulator if the predefined number of frames has been added to the accumulator, or if the disregard_counter argument is True. Otherwise, it returns None.

Parameters:

disregard_counter (bool) – If the value of this argument is True, the accumulator’s internal frame counter is ignored, and the class sum and virtual powder pattern are returned. The frame counter is then reset.

Returns:

The sum and virtual powder plot stored by the accumulator, or None.

Return type:

list[ClassSumData] | None

class CheetahClassSumsCollector(*, parameters, num_classes)#

Cheetah data class sum collector.

This class collects accumulated data class information retrieved from the processing nodes, and stores the cumulative total information associated with the data class. The information collected by this class can optionally be written to an HDF5 file.

Parameters:

  • parameters (CheetahParameters) – A set of OM configuration parameters collected together in a parameter group.

  • num_classes (int) – The total number of data classes currently managed by Cheetah.

add_sums(*, class_sums)#

Adds information to the collectors

Adds class sums information, retrieved from the processing nodes, to the collector. If the predefined number of updates has been reached, the function triggers the writing of the collector’s data to an HDF5 file.

Parameters:

class_sums (list[ClassSumData]) – The information to be added to the collector.

Return type:

None

save_sums()#

Saves the collector’s data to an HDF5 file.

This function saves the collector’s accumulated data to an HDF5 file. It is called automatically by the collector when required, but can also be called manually.

Return type:

None

class HDF5Writer(*, node_rank, parameters)#

Event data writer.

This class creates HDF5 data files that store the event information processed by Cheetah. For each data event, this class saves into an HDF5 file a processed detector data frame, the list of Bragg peaks detected in the frame, and some additional information (timestamp, beam energy, detector distance, pump laser state).

Parameters:

  • parameters (CheetahParameters) – A set of OM configuration parameters collected together in a parameter group.

  • node_rank (int) – The rank of the OM node that writes the data in the output files.

write_frame(*, processed_data)#

Writes data into an HDF5 data file.

This function writes the provided data into an HDF5 data file, assuming that all the data belongs to the same processed data event.

Parameters:

processed_data (dict[str, Any]) – A dictionary containing the data to write into the HDF5 file.

Return type:

None

close()#

Closes the file currently being written.

This function closes the HDF5 file that the class is currently writing.

Return type:

None

get_current_filename()#

Retrieves the path to the file currently being written.

This function retrieves the full path to the file that the class is currently writing.

Returns:

The path to the file currently being written.

Return type:

Path

get_num_written_frames()#

Retrieves the number of data events already written to the current file.

This function retrieves the number of data events that the class has already saved into the file that is currently writing.

Returns:

The number of data events already written in the current file.

Return type:

int

class SumHDF5Writer(*, powder_class, parameters)#

Frame sum writer.

This class creates HDF5 data files to store the aggregate information collected by Cheetah. The function saves into an HDF5 file a sum of detector data frames, together with a virtual powder pattern created using the Bragg peaks detected in the frames. Different sum writers are usually created for different data classes.

Parameters:

  • powder_class (int) – A unique identifier for the data class to which the data being written belongs.

  • cheetah_parameters – A dictionary containing Cheetah’s configuration parameters.

  • parameters (CheetahParameters)

write_sums(*, data)#

Writes aggregated frame data into an HDF5 file.

This function writes the provided aggregated frame data into an HDF5 file.

Parameters:

data (ClassSumData) – A dictionary containing the aggregated data to write into the file.

Return type:

None