This page provides a list of existing modules for psana framework. Only the modules that are included in the standard analysis releases appear on this page.

Package psana

Psana package include several simple modules which do generic tasks that do not need knowledge of the event data types.

Module psana.EventKeys

This module dumps the list of the event keys in the event or configuration store. Event key is a triplet of data type, data source address, and string key.

Example of the output produced by this module:

Event keys:
  EventKey(type=Psana::EvrData::DataV3, src=DetInfo(NoDetector.0:Evr.0))
  EventKey(type=Psana::Camera::FrameV1, src=DetInfo(CxiDg1.0:Tm6740.0))
  EventKey(type=Psana::Ipimb::DataV1, src=DetInfo(CxiDg1.0:Ipimb.0))
...

This module is useful to display the content of the events without dumping all the data. Example command which uses this module is:

% psana -m EventKeys <input-files>

Note that one can specify EventKeys instead of psana.EventKeys as psana package name is optional.

Module psana.PrintEventId

This module prints the content of the Event ID object on every event.

Example of the output produced by this module:

[info:psana.PrintEventId] event ID: XtcEventId(run=100, time=2010-12-12 11:09:36.300506429-08)
[info:psana.PrintEventId] event ID: XtcEventId(run=100, time=2010-12-12 11:09:36.317163082-08)

Module psana.PrintSeparator

This module prints separator line on every event. Can be used to indicate event boundaries in job's log.

Module has two configuration parameters:

• separator (default: "=") – separator string
• repeat (default: 80) – number of repeats of separator string on a separator line

Example of the output produced by this module with the default parameters (including output from PrintEventId module):

[info:/root/] ================================================================================
[info:psana.PrintEventId] event ID: XtcEventId(run=100, time=2010-12-12 11:09:36.300506429-08)
[info:/root/] ================================================================================
[info:psana.PrintEventId] event ID: XtcEventId(run=100, time=2010-12-12 11:09:36.317163082-08)

Package psana_examples

This package contains modules that are meant to be used as examples of accessing different data types or framework services. Can be used by developers as templates for new modules.

Module psana_examples.DumpAcqiris

Extracts and dumps the content of Acqiris configuration (Psana::Acqiris::ConfigV1) and event data (Psana::Acqiris::DataDescV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Acqiris)") – data source address

Module psana_examples.DumpAcqTdc

Extracts and dumps the content of Acqiris TDC configuration (Psana::Acqiris::TdcConfigV1) and event data (Psana::Acqiris::TdcDataV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:AcqTDC.0)") – data source address

Module psana_examples.DumpBld

Extracts and dumps the content of beamline data objects (Psana::Bld::BldDataEBeamV0, Psana::Bld::BldDataEBeam, Psana::Bld::BldDataPhaseCavity, Psana::Bld::BldDataFEEGasDetEnergy, and Psana::Bld::BldDataIpimb).

Module has four configuration parameters:

• eBeamSource (default: "BldInfo(EBeam)") – data source address for Psana::Bld::BldDataEBeam
• phaseCavSource (default: "BldInfo(PhaseCavity)") – data source address for Psana::Bld::BldDataPhaseCavity
• feeSource (default: "BldInfo(FEEGasDetEnergy)") – data source address for Psana::Bld::BldDataFEEGasDetEnergy
• ipimbSource (default: "BldInfo(NH2-SB1-IPM-01)") – data source address for Psana::Bld::BldDataIpimb

Module psana_examples.DumpCamera

Extracts and dumps the content of camera configuration (Psana::Camera::FrameFexConfigV1) and event data (Psana::Camera::FrameV1 and Psana::Camera::TwoDGaussianV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Opal1000)") – data source address

Module psana_examples.DumpControl

Extracts and dumps the content of scan control configuration (Psana::ControlData::ConfigV1) object.

Module has one configuration parameter:

• source (default: "ProcInfo()") – data source address

Module psana_examples.DumpCsPad

Extracts and dumps the content of CsPad configuration (Psana::CsPad::ConfigV*) and event data (Psana::CsPad::DataV*) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Cspad)") – data source address

Module psana_examples.DumpEncoder

Extracts and dumps the content of encoder configuration (Psana::Encoder::ConfigV1) and event data (Psana::Encoder::DataV*) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Encoder)") – data source address

Module psana_examples.DumpEpics

Extracts and dumps the list of EPICS PVs and their values and status information on every event.

Module psana_examples.DumpEvr

Extracts and dumps the content of Evr configuration (Psana::EvrData::ConfigV* and Psana::EvrData::IOConfigV1) and event data (Psana::EvrData::DataV*) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Evr)") – data source address

Module psana_examples.DumpFccd

Extracts and dumps the content of FCCD configuration (Psana::FCCD::FccdConfigV*) objects. To dump event data objects use psana_examples.DumpCamera module.

Module has one configuration parameter:

• source (default: "DetInfo(:Fccd)") – data source address

Module psana_examples.DumpIpimb

Extracts and dumps the content of IPIMB configuration (Psana::Ipimb::ConfigV1) and event data (Psana::Ipimb::DataV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Ipimb)") – data source address

Module psana_examples.DumpLusi

Extracts and dumps the content of LUSI configuration (Psana::Lusi::DiodeFexConfigV1, Psana::Lusi::IpmFexConfigV1, and Psana::Lusi::PimImageConfigV1) and event data (Psana::Lusi::DiodeFexV1 and Psana::Lusi::IpmFexV1) objects.

Module has two configuration parameters:

• tmSource (default: "DetInfo(:Tm6740)") – data source address for Psana::Lusi::PimImageConfigV1
• ipimbSource (default: "DetInfo(:Ipimb)") – data source address for other data

Module psana_examples.DumpOpal1k

Extracts and dumps the content of Opal1000 configuration (Psana::Opal1k::ConfigV1) object. To dump event data objects use psana_examples.DumpCamera module.

Module has one configuration parameter:

• source (default: "DetInfo(:Opal1000)") – data source address

Module psana_examples.DumpPnccd

Extracts and dumps the content of pnCCD configuration (Psana::PNCCD::ConfigV*) and event data (Psana::PNCCD::FrameV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:pnCCD)") – data source address

Module psana_examples.DumpPrinceton

Extracts and dumps the content of Princeton configuration (Psana::Princeton::ConfigV1) and event data (Psana::Princeton::FrameV1) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Princeton)") – data source address

Module psana_examples.DumpPulnix

Extracts and dumps the content of Pulnix configuration (Psana::Pulnix::TM6740ConfigV*) objects.

Module has one configuration parameter:

• source (default: "DetInfo(:Tm6740)") – data source address

Module psana_examples.EBeamHist

This module is an example of histogramming service usage. It extracts beam line data and fills couple of histograms with the beam parameters.

Module has one configuration parameter:

• eBeamSource (default: "BldInfo(EBeam)") – data source address

Package cspad_mod

Package cspad_mod contains common modules useful for analysis of data from CsPad detector.

Module cspad_mod.CsPadPedestals

This module is supposed to run on dark cspad2x2 frame data. It calculates average and standard deviation values for each pixel and writes these values to output files in text format.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – name of the data source; default value is adequate if there is only one CsPad device in setup, if there is more than one device then more specific value should be provided
• output (default: "cspad-pedestals.dat") – name of the output file for average values, if empty file will not be written
• noise (default: "cspad-noise.dat") – name of the output file for standard deviation values, if empty file will not be written

To use this module with default parameters one could use this command:

psana -m cspad_mod.CsPadPedestals input-files.xtc

which will produce files cspad-pedestals.dat and cspad-noise.dat in the current directory (if input file contains CsPad data).

To change module parameters one could create file with name psana.cfg in the current directory with a contents like this:

[psana]
modules = cspad_mod.CsPadPedestals

[cspad_mod.CsPadPedestals]
source = DetInfo(CxiDs1.0:Cspad.0)
output = pedestals.dat
noise =

and then run psana:

psana input-files.xtc

This should produce file pedestals.dat in the current directory. As the source address is more specific this configuration file can be used even if input data contain more than one CsPad device.

Module cspad_mod.CsPad2x2Pedestals

This module is supposed to run on cspad2x2 dark frame data. It calculates average and standard deviation values for each pixel and writes these values to output files in text format.

Module configuration parameters:

• source (default: "DetInfo(:Cspad2x2)") – name of the data source; default value is adequate if there is only one CsPad2x2 device in setup, if there is more than one device then more specific value should be provided
• output (default: "cspad2x2-pedestals.dat") – name of the output file for average values, if empty file will not be written
• noise (default: "cspad2x2-noise.dat") – name of the output file for standard deviation values, if empty file will not be written

To use this module with default parameters one could use this command:

psana -m cspad_mod.CsPad2x2Pedestals input-files.xtc

which will produce files cspad2x2-pedestals.dat and cspad2x2-noise.dat in the current directory (if input file contains CsPad2x2 data).

To change module parameters one could create file with name psana.cfg in the current directory with a contents like this:

[psana]
modules = cspad_mod.CsPad2x2Pedestals

[cspad_mod.CsPad2x2Pedestals]
source = DetInfo(CxiSc1.0:Cspad2x2.0)
output = pedestals.dat
noise =

and then run psana:

psana input-files.xtc

This should produce file pedestals.dat in the current directory. As the source address is more specific this configuration file can be used even if input data contain more than one CsPad2x2 device.

Module cspad_mod.CsPadCalib

This module performs standard CsPad calibration procedures: per-pixel pedestal subtraction and common mode correction. The algorithms used in calibrations are identical to translator algorithms, the result of calibration should be the same as the data stored in HDF5 files.

The module uses three input calibration files which should be located in the standard calibration directory of the corresponding experiment:

• pedestals – per-pixel pedestal data (produced by the CsPadPedestals module or standalone applications)
• pixel_status – hot/dead status for every pixel, used by common mode algorithm
• common_mode – file with parameters controlling common mode calculation
• pixel_gain – per-pixel gain data, inverse pixel gain (1/gain) as floating number

If any of the files is missing then corresponding algorithm is not executed, if pixel_status file is missing then all pixels are assumed to have working status. Algorithms inside module are executed following this order:

• common mode is calculated for every segment; common mode uses pedestal and pixel status values
• if common mode is calculated successfully it is subtracted from every pixel value in a segment
• if pedestals are defined pedestal values are subtracted from every pixel value
• if pixel gains are defined then each pixel value is multiplied by corresponding gain factor
• resulting pixel value is rounded to nearest integer and stored in the output image

The calibration is performed on every CsPad image (full or 2x2) found in the event and works even if there is more than one CsPad data object. The original objects are preserved in event and result of the calibration is stored in event with different string key ("calibrated" by default, can be changed with module parameter).

Module configuration parameters:

• inputKey (default is empty) – string key used to locate uncalibrated data objects in event
• outputKey (default is "calibrated") – string key used to store calibrated data objects in event
• doPedestals (default is "yes") – can be set to "no" to explicitly disable pedestal subtraction algorithm
• doPixelStatus (default is "yes") – can be set to "no" to explicitly disable reading of pixel status data, all pixels will be used for common mode
• doCommonMode (default is "yes") – can be set to "no" to explicitly disable common mode algorithm
• doPixelGain (default is "yes") – can be set to "no" to explicitly disable pixel gain correction algorithm

Module cspad_mod.CsPadFilter

This is a filter module which implements skipping for the events which have too low signal in CsPad. filtering algorithm can be controlled trough the module parameter and/or parameters in calibration file. The name of the calibration file is "filter" and it will be searched in the standard calibration directories of the experiment.

Module configuration parameters:

• inputKey (default is empty) – string key used to locate uncalibrated data objects in event
• source (default is "DetInfo(:Cspad)") – data source address
• skipIfNoData (default is "yes") – when set to "yes" if the module does not find CsPad data in an event then it skips event
• mode (default is -1) – filtering mode, see below
• parameters (default is all 0) – list of parameters for filtering algorithm, up to 16 floating numbers

Parameter mode defines where the filter get its parameters and how it works. If set to -1 (default) then it reads parameters and actual mode value from a calibration text file which should contain one integer number for mode and up to 16 floating point parameters. If parameter is set to 0 or if the value read from file is 0 then no filtering is done, all events are passed through. If mode is set to 1 (from parameter or file) then filter calculates the number of pixels above certain threshold. Filter expects two values in parameter array: threshold for pixel value and minimum number of pixels above threshold. If second parameter is negative then it's assumed to be a percentage of the full number of pixels.

Filter works on individual image arrays (quadrants). Module checks for CsPad::DataV1, CsPad::DataV2, and CsPad::MiniElementV1 objects in that order. If any object is found then module runs filter on images in that object. If any one image passes the filter then module returns and event is passed to downstream modules, otherwise framework skips this event.

With the default parameters module works with non-calibrated data, to switch to calibrated data add the module cspad_mod.CsPadCalib before filter and change inputKey parameter to calibrated.

Package CSPadPixCoords

Package CSPadPixCoords calculates the 2x1 section, quad, and CSPad pixel coordinates and produces the image.
For complete reference select Doxygen documentation.

Module CSPadPixCoords::PixCoordsTest

This module demonstrates of how to use the PixCoords2x1, PixCoordsQuad, and PixCoordsCSPad classes
in order to pre-calculate pixel coordinates, taking into account the calibration parameters.
Relevant images are produced in combination of the pixel coordinates with event data and saved in text files.

Module configuration parameters:

• calibDir (default: "/reg/d/psdm/CXI/cxi35711/calib") – directory with calibration files,
• typeGroupName (default: "CsPad::CalibV1") – data type and group names,
• source (default: "CxiDs1.0:Cspad.0") – source of data,
• runNumber (default: 32U) – run number for calibration file,
• events (default: 32U) – number of events before stop a job,
• filter (default: false) – on/off for potential selection filter.

Module CSPadPixCoords::CSPadImageProducer

CSPadImageProducer works in psana framework. It does a few operation as follows:

• gets the pixel coordinates from PixCoords2x1, PixCoordsQuad, and PixCoordsCSPad classes,
• gets data from the event,
• produces the Image2D<double> or ndarray<double,2> object with CSPad image for each event,
• adds the image object in the event for processing in other modules.
  Time consumed to fill the CSPad image array (currently 1750x1750) is measured to be about 40 msec/event on psana0105.

Module configuration parameters:

• calibDir (default: "") – directory with calibration files, by default it is set to .../<experiment>/calib
• typeGroupName (default: "CsPad::CalibV1") – calibration type and group names,
• source (default: "CxiDs1.0:Cspad.0") – source of data,
• key (default: "") – key for data processing stage,
• imgkey (default: "Image2D") – output key for image saved in event,
• events (default: 1<<31U) – number of events before stop a job,
• tiltIsApplied (default: true) – on/off for tilt angle of 2x1-sections and quads.
• print_bits (default: 0) – verbosity:
  • =0 - print nothing,
  • +1 - calib pars,
  • +2 - consumed time per event.

Remarks:

• By default the key corresponds to raw data.
• If the imgkey is defined as "Image2D", the image is saved in the event as a CSPadPixCoords::Image2D<double> object, otherwise (for other names) as a ndarray<double,2> object.

Module CSPadPixCoords::CSPadInterpolImageProducer

CSPadInterpolImageProducer works in psana framework. It does a few operation as follows:

• gets the pixel coordinates from PixCoords2x1, PixCoordsQuad, and PixCoordsCSPad classes,
• makes the arrays of neighbour addresses (quad, section, row, column) and weights as a function of the bin indexes (ix, iy) of the CSPad image,
• gets data from the event,
• produces the Image2D object with interpolated CSPad image for each event,
• adds the CSPadPixCoords::Image2D<double> or ndarray<double,2> object in the event for processing in other modules.
  In this module we use 4-node bi-linear interpolation algorithm.
  Time consumed to fill the CSPad image array (currently 1750x1750) is measured to be about 200 msec/event on psana0106. We consider options for acceleration using GPU or multi-core processing.

Module configuration parameters are the same as for the CSPadPixCoords::CSPadImageProducer.

Module CSPadPixCoords::CSPad2x2ImageProducer

CSPad2x2ImageProducer works in psana framework. It does a few operation as follows:

• gets the pixel coordinates from PixCoords2x1 and PixCoordsCSPad2x2 classes,
• gets data from the event,
• produces the Image2D<double> or ndarray<double,2> object with CSPad image for each event,
• adds the image object in the event for processing in other modules.
  The CSPad2x2 image array is currently shaped as (400,400).

Module configuration parameters:

• source (default: "DetInfo(:Cspad2x2)") – source of data,
• inkey (default: "") – key for data processing stage,
• outimgkey (default: "Image2D") – output key for image saved in event,
• tiltIsApplied (default: false) – on/off for tilt angle of 2x1-sections and quads - currently is not used,
• print_bits (default: 0) – verbosity:
  • =0 - print nothing,
  • +1 - calib pars,
  • +2 - eventID.

Remarks:

• By default the empty inkey corresponds to raw data.
• If the outimgkey is defined as "Image2D", the image is saved in the event as a CSPadPixCoords::Image2D<double> object, otherwise (for other names) as a ndarray<double,2> object.

See also Example for Module CSPadPixCoords::CSPad2x2ImageProducer.

Module CSPadPixCoords::SaveImageInFile

(Re-named from deprecated module CSPadPixCoords::CSPadImageGetTest)

SaveImageInFile is a psana module class, which works after the CSPadImageProducer or CSPadInterpolImageProducer. It receives the CSPadPixCoords::Image2D<double> or ndarray<double,2> image object from the event. (This image object may be used in further data processing.) For test purpose, the image of particular event, defined by the eventSave parameter in configuration file, is saved in the text file with standard predefined name like cspad_image_ev<number>.txt.

Module configuration parameters:

• source (default: "CxiDs1.0:Cspad.0") – source of data,
• key (default: "Image2D") – input image key,
• eventSave (default: 0) – event number to save the CSPad image file,
• saveAll (default: false) – save or not all selected events,
• fname (default: "cspad_image_ev") – common part of the output file name, event number with extension ".txt" will be added at the end.
• print_bits(default: 0) – verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - info about saved files.

Package ImgPixSpectra

For complete reference see the Doxygen documentation.

Package ImgPixSpectra is intended to accumulate the spectra for all pixels of the image array.
Different modules of this package work with different data types for detectors like CSPad, mini-CSPad, Opal, Princeton camera, etc. All modules have the same interface and the same functionality.
In the loop over events from beginJob to endJob the image pixel amplitudes are accumulated in the 2-d array,
of the shape (<number-of-pixels>, <number-of-spectral-bins>). The first parameter is defined by the image size. The second is passed as an external parameter of the psana configuration file (psana.cfg) along with minimal and maximal amplitudes. At the endJob the spectral array is saved in file with specified name. Auxiliary file with the name extension *.sha is created in order to save the shape parameters. For example, the "mini-cspad-pix-spectra.txt.sha" outpuit file contains

NPIXELS  143560
NBINS    100
AMIN     500
AMAX     1000
NEVENTS  2549
ARRFNAME mini-cspad-pix-spectra.txt

This information can be used in analysis or presentation of this array.

Module ImgPixSpectra::CSPadPixSpectra

Module configuration parameters:

• source (default: "CxiDs1.0:Cspad.0" ) – source of data for CSPad
• events (default: 1<<31U ) – number of events before stop a job
• inputKey (default: "" ) – input key for data processing stage
• amin (default: 0. ) – minimal spectral amplitude
• amax (default: 1000. ) – maximal spectral amplitude
• nbins (default: 100 ) – number of bins in spectra
• arr_fname (default: "..._spectral_array.txt" ) – output file name

Module ImgPixSpectra::MiniCSPadPixSpectra

The only difference in interface of this module from previous is in the default name for the source parameter and the output file name.

• source (default: "DetInfo(:Cspad2x2)" ) – source of data for MiniCSPad

Module ImgPixSpectra::CameraPixSpectra

The only difference in interface of this module from previous is in the default name for the source parameter and the output file name.

• source (default: "DetInfo(SxrBeamline.0:Opal1000.1)" ) – source of data for Opal camera
  or
• source (default: "DetInfo(:Princeton)" ) – source of data for Princeton camera

See also Example for Package ImgPixSpectra.

Package ImgAlgos

This packages contains a few psana modules for image processing

Module ImgAlgos::CSPadCommonModeCorrection

Alternative to the cspad_mod.CsPadCalib algorithm for the common mode correction.
Takes the CSPad data array with subtracted pedestals, evaluate the average amplitude for each 2x1 section for amplitudes below the threshold, and subtract it from all pixel amplitudes. This algorithm consumes about 30 ms/event on psana0205.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)" ) – source of data for CSPad
• inputKey (default: "calibrated" ) – key for input data, by default expects data from cspad_mod.CsPadCalib
• outputKey (default: "cm_subtracted" ) – output key for the next data processing stage
• ampthr (default: 30 ) – threshold to exclude the large pixel amplitudes in average

Module ImgAlgos::ImgPixAmpFilter

The ImgAlgos::ImgPixAmpFilter is a filter for event selection.
This filter counts the number of image pixels in the specified window with amplitude exceeding the threshold. If the number of high-amplitude pixels exceed the numPixMin, the event is passed for further analysis.

The algorithm performance was tested for CSPad images. This algorithm consumes up to 15 ms/event on psana0205 for full CSPad (1650x1650) window size. For smaller window consumed time is negligible, comparing to the image reconstruction time, which is ~70 ms/event (for cspad_mod.CsPadCalib and CSPadPixCoords::CSPadImageProducer) on psana0205.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – source of data
• key (default: "Image2D") – key for input image data
• threshold (default: 10) – minimal threshold on pixel amplitude
• numPixMin (default: 100) – minimal number of pixels with amplitude above the threshold
• filterIsOn (default: true) – On/Off the filter
• xmin (default: 0) – minimal column number
• xmax (default: 100000) – maximal column number
• ymin (default: 0) – minimal row number
• ymax (default: 100000) – maximal row number
• print_bits (default: 0) – verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - per event number of pixels above the threshold,
  • +8 - the same as previous, but for each 100's event,
  • +16 - event ID.

Remarks:

• The default key ("Image2D") stands for the CSPadPixCoords::Image2D<double> image object. Other key names work for the ndarray<double,2> image object.
• The xmin, xmax, ymin, ymax (in pixels) defines the window in the image for pixel counting. Default values means the entire image range.
• The threshold, numPixMin, and the window extents have to be adjusted for particular experiment.

Module ImgAlgos::ImgPeakFinder

This algorithm was motivated by users of amo42112:
1. Select the pixels in the window xmin, xmax, ymin, ymax
with amplitudes above the threshold_low.
2. Smear image for selected pixels, using 2-d matrix of weights over pixels
from -smear_radius to +smear_radius around each smeared pixel amplitude.
The matrix of weights is defined by the 2-d Gaussian function of width sigma.
3. Find peaks as pixels with absolute-maximal amplitude above the threshold_high in the center of the matrix -peak_radius to +peak_radius.
4. Put the vector of found peaks in the event with key peaksKey. Each entry of this vector has an object of the struct Peak, containing x, y positions, peak pixel amplitude, the total amplitude in the matrix, defined by the peak_radius, and the number of pixels in the matrix above threshold_low:

struct Peak{
   double x;
   double y; 
   double ampmax;  // amplitude in the peak masimum   
   double amptot;  // total amplitude in the range of {{peak_radius}}
   unsigned npix;  // number of pixels in the range of {{peak_radius}}
} ;

Module configuration parameters:

• source (default: "DetInfo()") – source of data
• key (default: "") – key for input image data
• peaksKey (default: "peaks") – key for output list of peaks
• threshold_low (default: 10) – low threshold on pixel amplitude
• threshold_high (default: 100) – high threshold on pixel amplitude
• sigma (default: 1.5) – width of the Gaussian for smearing
• smear_radius (default: 1) – radius in pixel for smearing
• peak_radius (default: 3) – radius in pixel for peak finding
• xmin (default: 0) – minimal column number
• xmax (default: 100000) – maximal column number
• ymin (default: 0) – minimal row number
• ymax (default: 100000) – maximal row number
• testEvent (default: 0) – event number to save images and print info for test purpose
• finderIsOn (default: true) – On/Off algorithm
• print_bits (default: 0) – finder verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - number of peaks in the event,
  • +8 - per event each peak parameters,
  • +16- info about input image format.

Remarks:

• This algorithm consumes ~15 ms/event on psana0101 for full Opal1000 (1024x1024) camera image.
• Smearing algorithm use a "safety margin" which is currently set to 10 pixels (offset from each boarder of the full image size).

See also Example for Module ImgAlgos::ImgPeakFinder.

Module ImgAlgos::ImgPeakFilter

This module use results and should work after the ImgAlgos::ImgPeakFinder.
It gets the vector of peaks for the source and key, loops over all founded peaks and counts the number of peaks above the thresholds threshold_peak and threshold_total. If the filterIsOn is "on" ("true" or "yes" state) and the number of found peaks exceeds the n_peaks_min the event is passed for further analysis/processing.

Module configuration parameters:

• source (default: "DetInfo()") – source of data
• key (default: "peaks") – key for input list of peaks, should be the same as peaksKey in ImgPeakFinder
• threshold_peak (default: 0) – threshold on peak amplitude
• threshold_total(default: 0) – threshold on total peak intensity (in the matrix around peak)
• n_peaks_min (default: 1) – minimal number of peaks above all thresholds
• filterIsOn (default: true) – On/Off the filter
• print_bits (default: 0) – filter verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - peaks' info,
  • +8 - event ID.

Module ImgAlgos::Tahometer

This module measures the time interval for entire job and for each dn events and prints the rate info as requested by the print_bits parameter.

Module configuration parameters:

• dn (default: 1) – number of events between printout
• print_bits (default: 0) – filter verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - start notice and summary at stop,
  • +4 - instant rate performance after each dn events.

Module ImgAlgos::TimeStampFilter

This module passes only the events if their time stamp is in the requested range.
The range of allowed time stamps is defined by the configuration parameters.

Module configuration parameters:

• tsinterval (default: "1970-01-01 00:00:00.000000000 / 2100-01-01 00:00:00.000000000") – time-stamp interval string
• tstamp_min (default: "1970-01-01 00:00:00.000000000") – minimal time-stamp string
• tstamp_max (default: "2100-01-01 00:00:00.000000000") – maximal time-stamp string
• filterIsOn (default: true) – On/Off the filter
• print_bits (default: 0) – filter verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - event ID,
  • +8 - time stamp variables for selected event.

The time-stamp string is accepted in various formats:

• YYYYMMDD HHMMSS.FFF
• YYYYMMDDTHHMMSS.F
• YYYY-MM-DD HH:MM:SS.FFF
  but the date field has to be presented mandatory.
  If the tsinterval is defined and is different from the default, it will be used in filter and override the tstamp_min and tstamp_max.

See also Example for TimeStampFilter and XtcOutputModule.

Module ImgAlgos::EventNumberFilter

This filter selects events by their number counting from the beginning of job, starting from 0. The event number is not a parameter which is associated with event. Use this filter cautiously on your own risk for debugging purpose only.

Module configuration parameters:

• filterIsOn (default: true) – On/Off filter.
• first (default: 0) – the first event from the beginning of job, starting from 0.
• last (default: 1<<31) – the last event from the beginning of job.
• evtstring (default: "") – the string of events of intervals from the beginning of job.
• print_bits (default: 0) – filter verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - selected event number and ID.

There are two modes of operation of this filter.

1. If the first and/or last event numbers are defined, then the filter will select events in this range only.
2. If the evtstring is defined, only listed events of event ranges will be selected. For example, the evtstring parameter can be defined as

    2,5,11-15,20-25,29,30
   

   that means the list of events:

     2  5  11  12  13  14  15  20  21  22  23  24  25  29  30
   

   In the evtstring parameter the comma "," and sign minus "-" as a dash are the only allowed separators. Blank spaces are also allowed. Other characters may abort the program. The evtstring mode has higher priority than the 1st mode.
   The filterIsOn allows easy turn on/off this filter in *.cfg file.

Module ImgAlgos::CSPadArrSaveInFile

This module saves the CSPad data array formatted as [5920=4*8*185][388] in output file for each passes event.
Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• key (default: "") – key for input data, for example, it might be "calibrated"
• outfile (default: "cspad-arr") – out file name prefix for saved array
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - event ID,
  • +4 - time stamp,
  • +8 - saved file names.

Module ImgAlgos::CSPadArrAverage

This module averages the CSPad data array and saves two files for averaged and rms values in CSPad format [5920=4*8*185][388]. In contrast to the [cspad_mod.CsPadPedestals], the input data can be specified with a key, that allows to average CSPad array for already pre-processed data, for example "calibrated". This feature can be used to evaluate the averaged signal or background event. Implemented algorithm of averaging allows to eliminate large statistical fluctuations in the pixel amplitude spectrum. In advanced case averaging may have up to three stages, depending on configuration parameters:

• 0-stage: the 1st portion of events from 0 to evts_stage1 is averaged without any constrains, the preliminary averaged and rms values are defined for each pixel
  at the end of this stage.
• 1-stage: starting from the event evts_stage1 data are collected only for abs(amplitude-average0) < gate_width1. At the end of this stage the preliminary averaged and rms values are defined for each pixel.
• 2-stage: starting from the event evts_stage2 data are collected only for abs(amplitude-average1) < gate_width2. At the end of this stage the preliminary averaged and rms values are defined for each pixel and saved in the files specified by the avefile and rmsfile parameters, respectively.

This type of averaging algorithm may be useful for pedestal defenition in case of large amplitude fluctuations.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• key (default: "") – key for input data, for example, it might be "calibrated"
• avefile (default: "cspad-ave.dat") – out file with averaged amplitudes
• rmsfile (default: "cspad-rms.dat") – out file with rms
• evts_stage1 (default: 1<<31U) – number of events before stage 1
• evts_stage2 (default: 100) – additional number of events before stage 2
• gate_width1 (default: 0) – gate_width for stage 1
• gate_width2 (default: 0) – gate_width for stage 2
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - beginning of 3 stages,
  • +4 - processed statistics at the end of each stage,
  • +8 - output in files,
  • +16 - event ID.

Default version of the configuration parameters works the same way as cspad_mod.CsPadPedestals. In this case module gets raw events and stage 0 continues for entire input data sample.

See also Example for Module ImgAlgos::CSPadArrAverage.

Module ImgAlgos::CSPadBkgdSubtract

This module uses the CSPad array, specified by the configuration parameters source and inputKey, subtracts the background, defined in the file bkgd_fname, and saves the resulting array in the event with outputKey. The subtracted background array is normalized on the sum of pixel amplitudes in the quad section norm_sector, which can be set from 0 to 7.

   shared_ptr<Psana::CsPad::ConfigV2> config2 = env.configStore().get(m_str_src);
   unsigned mask = config2->roiMask(quad_number); // should be in the range from 0 to 255

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• inputKey (default: " " ) – key for input data, by default use raw data
• outputKey (default: "bkgd_subtracted" ) – output key for the next data processing stage

• bkgd_fname (default: "cspad_background.dat" ) – file with CSPad array [4*8*185][388] of averaged background

• norm_sector (default: 0) – CSPad sector in quad from 0 to 7
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - event ID,
  • +4 - normalization factor for each event,
  • +8 - part of the background array.

See also Example for Module ImgAlgos::CSPadBkgdSubtract.

Module ImgAlgos::CSPadMaskApply

This module uses the CSPad array, defined by the configuration parameters source and inkey, apply the mask from file mask_fnname and saves the masked data with key outkey. For masked pixels the amplitude will be replaced by the value from masked_amp.

The file mask_fnname has the same structure as files for pedestals and background with dimensions [4*8*185][388]. Masked pixels are indicated by 0-th in this file. This file can be generated, for example, from the averaged background file, using amplitude threshold. This can be done with auxiliary python script MakePixelMask.py as explained in [Example for Module ImgAlgos::CSPadMaskApply].

Module configuration parameters:

• source (default: "DetInfo(:Cspad)" ) – input source of data
• inkey (default: " " ) – key for input data, by default use raw data
• outkey (default: "bkgd_subtracted" ) – output key for the next data processing stage

• mask_fname (default: "cspad_mask.dat" ) – file with CSPad mask array [4*8*185][388]

• masked_amp (default: 0) – this amplitude will replace the amplitude in each masked pixel
• mask_control_bits (default: 1) – control bits for applied mask:
  • =0 - do not apply any mask,
  • +1 - apply mask from file,
  • +2 - mask two long edges of 2x1,
  • +4 - mask two short edges of 2x1,
  • +8 - mask two short rows in the middle of 2x1 (rows with wide pixels).
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars (in beginJob),
  • +2 - event ID (in event),
  • +4 - mask statistics (in beginJob),
  • +8 - part of the mask array (in beginJob).

Module ImgAlgos::ImgRadialCorrection

This module averages the image pixel amplitude in r-phi bins, normalizes it per single pixel and subtracts the average amplitude from each pixel. Image is obtained from event by its source and inkey values. The output corrected image is saved in the event with outkey keyword. Carthesian to polar coordinate transformation is done with respect to center coordinates xcenter, ycenter. The central region (r<rmin) and edges of the image (r>rmax) pixels can be removed from further consideration by setting rmin and rmax. The number of radial bins is defined as an int(rmax-rmin). The number of angular bins is set by n_phi_bins.

Module configuration parameters:

• source (default: "DetInfo()") – input source of data
• inkey (default: " " ) – key for input data, by default use raw data
• outkey (default: "rad_corrected" ) – output key for further image processing
• xcenter (default: 850) – x coordinate of the image center
• ycenter (default: 850) – y coordinate of the image center
• rmin (default: 10) – radius minimal image is not processed for r<rmin
• rmax (default:1000) – radius maximal image is not processed for r>rmax
• n_phi_bins (default: 12) – number of angular sectors for the background averaging.
• event (default: 0) – test event for print/save
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - summary,
  • +4 - event ID,
  • +8 - info about input image type (ndarray<double,2> or Image2D<double>).

See also Example for Module ImgAlgos::ImgRadialCorrection.

Module ImgAlgos::CSPadArrNoise

This module works on CSPad data array (shaped as [5920=4*8*185][388]), uses the "median algorithm" to evaluate the signal and noise for each pixel, evaluates S/N ratio for each pixel, counts the fraction of events where S/N > SoNThr, and writes the same shape arrays for pixel mask and status information in the maskfile and statusfile, respectively. The statusfile contains for each pixel the fraction of events where S/N > SoNThr.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• key (default: "") – key for input data, for example, it might be "calibrated"
• statusfile (default: "cspad-pix-status.dat") – out file with pixel status: fraction of noisy images
• maskfile (default: "cspad-pix-mask.dat") – out file with pixel mask
• rmin (default: 3) – radial parameter of the area for median algorithm
• dr (default: 1) – radial band width of the area for median algorithm
• SoNThr (default: 3) – S/N threshold for each pixel to be considered as noisy
• frac_noisy_img (default: 0.1) – fraction of noisy images above which pixel is masked in the maskfile
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - empty,
  • +4 - processed statistics,
  • +8 - output in files,
  • +16 - event ID,
  • +32 - event time stamp,
  • +32 - vector of indexes and map of indexes for the median algorithm.

See also Example for Module ImgAlgos::CSPadArrNoise.

Module ImgAlgos::CSPadArrPeakFinder

This module extends features of the previous ImgAlgos::CSPadArrNoise module for the case of peak finding.
It works on CSPad data array (shaped as [5920=4*8*185][388]) as follows:

• in the constructor and beginJob(...) method:
  • enters input parameters,
  • (re)set the initial mask of noisy pixels from file hot_pix_mask_file (if its name is specified in the configuration file),
  • do necessary initialization of work arrays.

• in the event(...) method:
  • uses the "median algorithm" to evaluate the signal and noise for each pixel,

  • fills [4][8][185][388] per-pixel arrays:

    • m_stat - number of events with |S/N| > SoNThr,
    • m_signal - signal amplitude, or 0(zero) for masked pixels,
    • m_proc_status - sets 255 for S/N > SoNThr or 0(zero) for masked pixels.
  • use arrays m_proc_status and m_signal to find peaks:

    • iterate over [185][388] 2x1 pixels and find the connected regions (using recursive flood-filling algorithm)

    • create vector of peaks v_peaks of struct Peak, using peak_npix_min, peak_npix_max, and peak_amp_tot_thr parameters,
  • loop over v_peaks, count total amplitude and the number of peaks in the event.
  • decide if the event selected or not based on event_npeak_min, event_amp_tot_thr, and selection_mode parameters.
  • periodically dynamically re-generate the mask, based on m_stat array and frac_noisy_imgs parameter. When to start and for how many events to update the mask is defined by the nevents_mask_update and nevents_mask_accum parameters, respectively.
  • save m_signal in file for selected events, depending on out_file_bits parameter.
• put the vector with peaks v_peaks in the evt with key=key_peaks_out.

• in the endJob(...) method, depending on bit status in out_file_bits :
  • save current hot-pixel mask in the file hot_pix_mask_out_file
  • save current fraction of events with noisy/signal pixels in the file frac_noisy_evts_file

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• key (default: "") – key for input data, for example, it might be "calibrated"
• key_signal_out (default: "") – key for output signal array. If the string non-empty, the array is added in the datagram for each event (before selection).
• key_peaks_out (default: "peaks") – key for vector of found peaks in the selected event
• hot_pix_mask_inp_file (default: "cspad-pix-mask-in.dat") – in read the pixel mask from file
• hot_pix_mask_out_file (default: "cspad-pix-mask-out.dat") – out write current pixel mask in the file
• frac_noisy_evts_file (default: "cspad-pix-frac-out.dat") – out file with per-pixel fraction of noisy images
• evt_file_out (default: "./cspad-ev-") – out file with signal CSPad array. Time stamp is added.
• rmin (default: 3) – radial parameter of the area for median algorithm
• dr (default: 1) – radial band width of the area for median algorithm
• SoNThr_noise (default: 3) – S/N threshold for each pixel to be considered as noisy
• SoNThr_signal (default: 5) – S/N threshold for each pixel to be considered as noisy
• frac_noisy_imgs (default: 0.9) – fraction of noisy images above which pixel will be masked
• peak_npix_min (default: 4) – minimal number of connected pixels for the good peak
• peak_npix_max (default: 25) – maximal number of connected pixels for the good peak
• peak_amp_tot_thr (default: 0.) – threshold on total signal amplitude of the group of connected pixels, if =0:OFF
• peak_SoN_thr (default: 7.) – threshold on peak S/N (S and N are sums over connected pixels)
• event_npeak_min (default: 10) – threshold on minimal number of good peaks for the event selection
• event_npeak_max (default: 10000) – threshold on maximal number of good peaks for the event selection
• event_amp_tot_thr(default: 0.) – threshold on total signal amplitude in ADU of all good peaks for the event selection, if =0:OFF
• nevents_mask_update (default: 0) – number of skipped events before each mask re-evaluation cycle
• nevents_mask_accum (default: 50) – number of events for the mask re-evaluation
• selection_mode (default: SELECTION_ON) – selection mode, other allowed values are: SELECTION_OFF, or SELECTION_INV
• out_file_bits (default: 0) – control on writting of files:
  • =0 - do not write files,
  • +1 - save the hot_pix_mask_out_file file with current mask array in the endJob(...) method.
  • +2 - save the frac_noisy_evts_file file with current fraction of noisy events array in the endJob(...) method.
  • +4 - save the CSPad signal array for selected events in the file with name like <evt_file_out>-<counter>-<run>-<time stamp>.txt.
  • +8 - save the vector of found peaks in file <evt_file_out>-<counter>-<run>-<time-stamp>-peaks.txt.
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars (once in beginJob),
  • +2 - initial and current mask statistics (in constructor and when mask is updated),
  • +4 - event selection parameters (for each event); event no., time-stamp, mode, number of peaks, and amp_tot.
  • +8 - output in files (for selected events),
  • +16 - start/stop to collect data for mask re-evaluation (driven by the mode counters),
  • +32 - event time stamp (for each event),
  • +64 - vector of indexes and map of indexes for the median algorithm (once in beginJob),
  • +128 - peak parameters before selection (for each event),
  • +256 - peak parameters saved in file (for selected events),
  • +512 - selection statistics (N<5: for each event; N<50: for each 10-th; N<500: for each 100-th, then for each 1000-th),
  • Always print:
    • Summary at the endJob.

See also Example for Module ImgAlgos::CSPadArrPeakFinder.

Module ImgAlgos::CSPadArrPeakAnalysis

This module is intended for analysis of the results obtained in the peak finding algorithm implemented in the ImgAlgos::CSPadArrPeakFinder module.

1. It gets the vector of peaks defined by the key parameter,
2. fills ROOT-style histograms and ntuples, and
3. saves histograms and ntuples in file defined by the fname_root parameter.

Module configuration parameters:

• source (default: "DetInfo(:Cspad)") – input source of data
• key (default: "peaks") – key for input data for peaks found in event
• fname_root (default: "file.root") – name of the output file with root histograms and ntuples
• print_bits (default: 0) – module verbosity:
  • =0 - print nothing,
  • +1 - input pars (once in beginJob),
  • +2 - summary, number of processed and collected events (in endJob),
  • +4 - peak parameters (in event),
  • +8 - event ID (in event).

See also Example for Module ImgAlgos::CSPadArrPeakAnalysis.

Module ImgAlgos::PnccdImageProducer

Functionality:

• gets the pnccd data from the event, based on specified source and inkey parameters,
• puts the ndarray<double,2> object with pnccd 1024x1024 image in the event using specified outimgkey parameter.

Module configuration parameters:

• source (default: "DetInfo(:pnCCD)") – source of data,
• inkey (default: "") – key for input data,
• outimgkey (default: "pnccdimg") – output key for image saved in event,
• print_bits (default: 0) – verbosity:
  • =0 - print nothing,
  • +1 - input pars,
  • +2 - initial portion of pnccd array,
  • +4 - configuration pars.

See also Example for Module ImgAlgos::PnccdImageProducer.