Table of Contents

Package Detector

Module Detector.AreaDetector

Class contains a collection of access methods to detector data and meta-data.

Access method to calibration and geometry parameters, raw data, etc. Low level implementation is done on C++ or python.

Usage:

# !!! NOTE: None is returned whenever requested information is missing.

# import
import psana

# retreive parameters from psana etc.
dsname = 'exp=xpptut15:run=54'
src = 'XppGon.0:Cspad.0' # or its alias 'cspad'

ds  = psana.DataSource(dsname)
env = ds.env()
evt = ds.events().next()
runnum = evt.run()

# parameter par can be either runnum or evt    
par = runnum # or = evt
cmpars=(1,25,10,91) # custom tuple of common mode parameters

det = psana.Detector(src, env, pbits=0)

# or directly
from Detector.AreaDetector import AreaDetector    
det = AreaDetector(src, env, pbits=0)

# set parameters, if changed
det.set_env(env)
det.set_source(source)
det.set_print_bits(pbits)

# for Camera type of detector only
det.set_do_offset(do_offset=False) # NOTE: should be called right after det object is created, before getting data

# print info
det.print_attributes()    
det.print_config(evt)

# get pixel array shape, size, and nomber of dimensions
shape = det.shape(par=0)
size  = det.size(par=0)
ndim  = det.ndim(par=0)
instrument = det.instrument()

# access intensity calibration parameters
peds   = det.pedestals(par) # returns array of pixel pedestals from calib store type pedestals
rms    = det.rms(par)       # returns array of pixel dark noise rms from calib store type pixel_rms
gain   = det.gain(par)      # returns array of pixel gain from calib store type pixel_gain
bkgd   = det.bkgd(par)      # returns array of pixel background from calib store type pixel_bkgd
status = det.status(par)    # returns array of pixel status from calib store type pixel_status
stmask = det.status_as_mask(par, mode=0) # returns array of masked bad pixels in det.status 
                                         # mode=0/1/2 masks zero/four/eight neighbors around each bad pixel
mask   = det.mask_calib(par)  # returns array of pixel mask from calib store type pixel_mask
cmod   = det.common_mode(par) # returns 1-d array of common mode parameters from calib store type common_mode

# per-pixel (int16) gain mask from configuration data; 1/0 for low/high gain pixels,
# or (float) per-pixel gain factors if gain is not None
gmap = det.gain_mask(par, gain=None) # returns array of pixel gains using configuration data
gmnz = det.gain_mask_non_zero(par, gain=None) # returns None if ALL pixels have high gain and mask should not be applied

# set gfactor=high/low gain factor for CSPAD(2X2) in det.calib and det.image methods
det.set_gain_mask_factor(gfactor=6.85)

# set flag (for Chuck)
det.do_reshape_2d_to_3d(flag=False) 

# get raw data
nda_raw = det.raw(evt)

# get calibrated data (applied corrections: pedestals, common mode, gain mask, gain, pixel status mask)
nda_cdata = det.calib(evt)
# and with custom common mode parameter sequence
nda_cdata = det.calib(evt, cmpars=(1,25,10,91)) # see description of common mode algorithms in confluence,
# and with combined mask.
nda_cdata = det.calib(evt, mbits=1) # see description of det.mask_comb method.

# common mode correction for pedestal-subtracted numpy array nda:
det.common_mode_apply(par, nda)
cm_corr_nda = det.common_mode_correction(par, nda)
# or with custom common mode parameter sequence
det.common_mode_apply(par, nda, cmpars)
cm_corr_nda = det.common_mode_correction(par, nda, cmpars)

# access geometry information
geo        = det.geometry(par)   # returns geometry object (top-most)
cx         = det.coords_x(par)   # returns array of pixel x coordinates
cy         = det.coords_y(par)   # returns array of pixel y coordinates
cz         = det.coords_z(par)   # returns array of pixel z coordinates
cx, cy     = det.coords_xy(par)  # returns arrays of pixel x and y coordinates
cx, cy, cz = det.coords_xyz(par) # returns arrays of pixel x, y, and z coordinates
areas      = det.areas(par)      # returns array of pixel areas relative smallest pixel
mask_geo   = det.mask_geo(par, mbits=15) # returns mask of segment-specific pixels
                                         #  mbits = +1-edges; +2-wide central cols;
                                         #          +4/+8/+16-non-bond / with four / with eight neighbors
ix         = det.indexes_x(par)  # returns array of pixel indexes along x for image
iy         = det.indexes_y(par)  # returns array of pixel indexes along y for image
ix, iy     = det.indexes_xy(par) # returns arrays of pixel indexes along x and y for image
pixel_size = det.pixel_size(par) # returns array of pixel sizes
ipx, ipy   = det.point_indexes(par, pxy_um=(0,0)) # by default returns detector origin indexes

# change geometry object parameters
det.move_geo(par, dx, dy, dz)    # move detector it 3-d space
det.tilt_geo(par, dtx, dty, dtz) # tilt detector around 3 axes

# access to combined mask
# NOTE: by default none of mask keywords is set to True, returns None.
mask = det.mask(par, calib=False, status=False, edges=False, central=False, unbond=False, unbondnbrs=False, unbondnbrs8=False)

# or cashed mask with mbits - bitword control
mask = det.mask_comb(par, mbits)
# where mbits has bits for pixel_status, pixel_mask, edges, central, unbond, unbondnbrs, unbondnbrs8, respectively

# static-mask methods for n-d mask arrays
mask_nbr = det.mask_neighbors(mask, allnbrs=True) # allnbrs=False/True for 4/8 neighbors
mask_edg = det.mask_edges(mask, mrows=1, mcols=1)

# reconstruct image
img   = det.image(evt) # uses calib() by default
img   = det.image(evt, img_nda)
xaxis = det.image_xaxis(par)
yaxis = det.image_yaxis(par)

# special case of indexing using non-default pixel scale size and x, y coordinate offset
ix       = det.indexes_x(par, pix_scale_size_um=110, xy0_off_pix=(1000,1000))
iy       = det.indexes_y(par, pix_scale_size_um=None, xy0_off_pix=None)
ix, iy   = det.indexes_xy(par, pix_scale_size_um=None, xy0_off_pix=None)
ipx, ipy = det.point_indexes(par, pxy_um=(0,0), pix_scale_size_um=None, xy0_off_pix=None) 
img      = det.image(evt, img_nda, pix_scale_size_um=None, xy0_off_pix=None)
xaxis    = det.image_xaxis(par, pix_scale_size_um=None, x0_off_pix=None)
yaxis    = det.image_yaxis(par, pix_scale_size_um=None, y0_off_pix=None)

# converting 2-d image to non-assembled array using pixel geometry information.
# if geometry info is missing - returns None, except the case when flag is set by det.do_reshape_2d_to_3d(True).  
nda      = det.ndarray_from_image(par, image, pix_scale_size_um=None, xy0_off_pix=None)

# save n-d numpy array in the text file with metadata (global methods under hood of the class object)
det.save_txtnda(fname='nda.txt', ndarr=myndarr, cmts=('comment1', 'comment2'), fmt='%.1f', verbos=False, addmetad=True)
# or convenience method for cspad2x2
det.save_asdaq(fname='nda.txt', ndarr=myndarr, cmts=('comment1', 'comment2'), fmt='%.1f', verbos=False, addmetad=True)

# load n-d numpy array from the text file with metadata
nda = det.load_txtnda(fname)

# merge photons split between pixels and return array with integer number of photons per pixel
nda_nphotons = det.photons(self, evt, nda_calib=None, mask=None, adu_per_photon=None)

See also: classes

Detector.PyDetector - factory for different detectors

Detector.DetectorAccess - c++ access interface to data

Detector.PyDetectorAccess - Python access interface to data

Detector.WFDetector - access waveform detector data ACQIRIS and IMP

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Version: $Id: AreaDetector.py 12946 2016-12-08 02:15:42Z jscott@SLAC.STANFORD.EDU $

Author: Mikhail S. Dubrovin

Class Detector.AreaDetector.AreaDetector

class Detector.AreaDetector.AreaDetector(src, env, pbits=0, iface='P')[source]

Python access to area detector data. Low level access is implemented on python or C++ through the boost::python wrapper

Constructor of the class AreaDetector.

src : str - data source, ex: ‘CxiDs2.0:Cspad.0’ env : psana.Env - environment, ex: env=ds.env(), where ds=psana.DataSource(‘exp=cxif5315:run=169’) pbits : int - print control bit-word iface : char - preferable interface: ‘C’ - C++ (everything) or ‘P’ - Python based (everything except common mode)

_nda_or_none_(nda)[source]

Returns ndarray or None.

_print_warning(msg='')[source]
_shape_daq_(par=0)[source]

Returns 2- or 3-d shape of the detector pixel-array as in DAQ.

par : int or psana.Event() - integer run number or psana event object. Returns ——- np.array - detector pixel-array shape. If ndim .gt. 3 shape is reduced to 3-d.

Ex.: the shape like (4,8,185,388) is reduced to (32,185,388)
_shaped_array_(rnum, arr, calibtype=None)[source]

Returns shaped numpy.array if shape is defined and constants are loaded from file, None othervise.

areas(par)[source]

Returns per-pixel array of pixel area.

par : int or psana.Event() - integer run number or psana event object.

np.array - array of pixel areas.

bkgd(par)[source]

Returns per-pixel array of background intensities from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pixel_bkgd.

calib(evt, cmpars=None, mbits=1, **kwargs)[source]

Returns per-pixel array of calibrated data intensities.

Gets raw data ndarray, applys baic corrections and return thus calibrated data. Applied corrections: - pedestal subtraction, returns det.raw(evt) if file with pedestals is missing - apply common mode correction - gain_mask or “hybrid” gain from configuration object for CSPAD(2x2) only - gain if pixel_gain calibration file is available - apply mask generated from pixel status (“bad pixels”

from calibration). Optionally apply other masks if “mbits” parameter set

evt : psana.Event() - psana event object. cmpars : list - common mode parameters, ex.: (1,50,50,100)

By default uses parameters from calib directory.
mbits : int - mask control bit-word. optional.
defaults to 1. Bit definitions:
  • 1 - pixel_status (“bad pixels” deployed by calibman)
  • 2 - pixel_mask (deployed by user in “pixel_mask” calib dir)
  • 4 - edge pixels
  • 8 - big “central” pixels of a cspad2x1
  • 16 - unbonded pixels
  • 32 - unbonded pixel with four neighbors
  • 64 - unbonded pixel with eight neighbors

np.array - per-pixel array of calibrated intensities from data.

calib_data(evt)[source]

Alias for depricated method renamed to calib.

common_mode(par)[source]

Returns array of common mode correction parameters.

par : int or psana.Event() - integer run number or psana event object.

np.array - values loaded for calibration type common_mode.

common_mode_apply(par, nda, cmpars=None, **kwargs)[source]

Apply common mode correction algorithm.

Apply common mode correction to nda (assuming that nda is data ndarray with subtracted pedestals) nda.dtype = np.float32 (or 64) is considered only, because common mode does not make sense for int data. If cmpars is not None then this sequence is used to override default common mode parameters coming from calib/.../common_mode/...

par : int or psana.Event() - integer run number or psana event object. nda : np.array - input: raw data with subtracted pedestals, output: cm corrected data. cmpars : list - common mode parameters, ex.: (1,50,50,100).

By default uses parameters from calib directory.

I/O parameter nda : np.array - per-pixel corrected intensities.

common_mode_correction(par, nda, cmpars=None)[source]

Returns per-pixel array of common mode correction offsets.

par : int or psana.Event() - integer run number or psana event object. nda : np.array - raw data with subtracted pedestals. Input data is not modified. cmpars : list - common mode parameters, ex.: (1,50,50,100)

By default uses parameters from calib directory.

np.array - per-pixel common mode correction offsets.

coords_x(par)[source]

Returns per-pixel array of x coordinates.

par : int or psana.Event() - integer run number or psana event object.

np.array - array of pixel x coordinates.

coords_xy(par)[source]

Returns per-pixel arrays of x and y coordinates.

par : int or psana.Event() - integer run number or psana event object.

np.array - 2 arrays of pixel x and y coordinates, respectively.

coords_xyz(par)[source]

Returns per-pixel arrays of x, y, and z coordinates.

par : int or psana.Event() - integer run number or psana event object.

np.array - 3 arrays of pixel x, y, and z coordinates, respectively.

coords_y(par)[source]

Returns per-pixel array of y coordinates.

par : int or psana.Event() - integer run number or psana event object.

np.array - array of pixel y coordinates.

coords_z(par)[source]

Returns per-pixel array of z coordinates.

par : int or psana.Event() - integer run number or psana event object.

np.array - array of pixel z coordinates.

do_reshape_2d_to_3d(flag=False)[source]

For Chuck - if flag is True - reshape 2-d arrays to 3-d. Parameters ———- flag : bool - False(def)/True

gain(par)[source]

Returns per-pixel array of gain factors from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pixel_gain.

gain_mask(par, gain=None)[source]

Returns per-pixel array with gain mask evaluated from detector configuration data.

par : int or psana.Event() - integer run number or psana event object. gain : float - gain factor; mask will be multiplied by this factor if it is specified.

np.array - per-pixel gain mask; (int16) 1/0 or (float) gain/1 for low/high gain pixels.

gain_mask_non_zero(par, gain=None)[source]

The same as gain_mask, but return None if ALL pixels have high gain.

par : int or psana.Event() - integer run number or psana event object. gain : float - gain factor; mask will be multiplied by this factor if it is specified.

np.array - per-pixel gain mask; (int16) 1/0 or (float) gain/1 for low/high gain pixels.

geometry(par)[source]

Creates and returns detector geometry object.

par : psana.Event() | int - psana event object or run number

PSCalib.GeometryAccess - detector geometry object.

image(evt, nda_in=None, pix_scale_size_um=None, xy0_off_pix=None, do_update=False)[source]

Returns 2-d array of intensities for imaging.

evt : psana.Event() - psana event object. nda_in : input n-d array which needs to be converted in image; default - use calib methood. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined. do_update : bool - force to update cached array.

np.array - 2-d array of intensities for imaging.

image_xaxis(par, pix_scale_size_um=None, x0_off_pix=None)[source]

Returns array of pixel x coordinates associated with image x-y grid.

par : int or psana.Event() - integer run number or psana event object. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. x0_off_pix : float - origin x coordinate offset in number of pixels

np.array - array of pixel x coordinates of image x-y grid.

image_yaxis(par, pix_scale_size_um=None, y0_off_pix=None)[source]

Returns array of pixel x coordinates associated with image x-y grid.

par : int or psana.Event() - integer run number or psana event object. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. y0_off_pix : float - origin y coordinate offset in number of pixels

np.array - array of pixel y coordinates of image x-y grid.

indexes_x(par, pix_scale_size_um=None, xy0_off_pix=None, do_update=False)[source]

Returns array of pixel integer x indexes.

par : int or psana.Event() - integer run number or psana event object. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined. do_update : bool - force to update cached array.

np.array - array of pixel x indexes.

indexes_xy(par, pix_scale_size_um=None, xy0_off_pix=None, do_update=False)[source]

Returns two arrays of pixel integer x and y indexes.

par : int or psana.Event() - integer run number or psana event object. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined. do_update : bool - force to update cached array.

(np.array, np.array) - list of two arrays of pixel x and y indexes, respectively.

indexes_y(par, pix_scale_size_um=None, xy0_off_pix=None, do_update=False)[source]

Returns array of pixel integer y indexes.

par : int or psana.Event() - integer run number or psana event object. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined. do_update : bool - force to update cached array.

np.array - array of pixel y indexes.

instrument()[source]

Returns name of instrument.

str - name of instrument, ex.: ‘AMO’, ‘XPP’, ‘SXR’, ‘CXI, ‘MEC’, ‘XCS’, etc.

is_cspad()[source]

Returns True/False for CSPAD/other detector type

bool - True if current detector is CSPAD, False otherwise.

is_cspad2x2()[source]

Returns True/False for CSPAD2x2/other detector type

bool - True if current detector is CSPAD2x2, False otherwise.

load_txtnda(fname)[source]

Returns n-d array loaded from specified formatted text file.

fname : str - input file name.

np.array - array with values loaded from file,
shaped in accordance with metadata (if available). If metadata is missing, output array will have 2- or 1-d shape; spaces and ‘

‘ characters in the text file are used to find the shape of the array.

loading_status(par, calibtype=None)[source]

Returns loading status of calibration constants of specified type. Parameters ———- rnum : int - run number calibtype : int - enumerated value from the list

gu.PEDESTALS, PIXEL_STATUS, PIXEL_RMS, PIXEL_GAIN, PIXEL_MASK, PIXEL_BKGD, COMMON_MODE.

int - enumerated value from the list gu.LOADED, DEFAULT, UNREADABLE, UNDEFINED, WRONGSIZE, NONFOUND.

mask(par, calib=False, status=False, edges=False, central=False, unbond=False, unbondnbrs=False, unbondnbrs8=False)[source]

Returns per-pixel array with mask values (per-pixel product of all requested masks).

par : int or psana.Event() - integer run number or psana event object. calib : bool - True/False = on/off mask from calib directory. status : bool - True/False = on/off mask generated from calib pixel_status.

Other parameters make sense for cspad 2x1 sensors only: edges : bool - True/False = on/off mask of edges. central : bool - True/False = on/off mask of two central columns. unbond : bool - True/False = on/off mask of unbonded pixels. unbondnbrs : bool - True/False = on/off mask of unbonded pixel with four neighbors. unbondnbrs8: bool - True/False = on/off mask of unbonded pixel with eight neighbors.

np.array - per-pixel mask values 1/0 for good/bad pixels.

mask_calib(par)[source]

Returns per-pixel array of mask from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pixel_mask.

mask_comb(par, mbits=0)[source]

Returns per-pixel array with combined mask controlled by mbits bit-word.

This method has same functionality as method mask(...) but under control of a single bit-word mbits.

par : int or psana.Event() - integer run number or psana event object. mbits : int - mask control bit-word.

= 0 - returns None + 1 - pixel_status (“bad pixels” deployed by calibman) + 2 - pixel_mask (deployed by user in “pixel_mask” calib dir) + 4 - edge pixels + 8 - big “central” pixels of a cspad2x1 + 16 - unbonded pixels + 32 - unbonded pixel with four neighbors + 64 - unbonded pixel with eight neighbors

np.array - per-pixel mask values 1/0 for good/bad pixels.

mask_edges(mask, mrows=1, mcols=1)[source]

Returns n-d array of mask with masked mrows and mcols edges on each 2-d segment.

mask : np.array - input mask of good/bad (1/0) pixels mrows : int - number of edge rows to mask mcols : int - number of edge columns to mask

np.array - mask with masked edges, shape = mask.shape

mask_geo(par, mbits=255)[source]

Returns per-pixel array with mask controlled by mbits bit-word.

par : int or psana.Event() - integer run number or psana event object. mbits : int - mask control bit-word.

= 0 - returns None + 1 - edges + 2 - central + 4 - unbond + 8 - unbondnbrs

np.array - per-pixel mask values 1/0 for good/bad pixels.

mask_neighbors(mask, allnbrs=True)[source]

Returns n-d array of mask with masked neighbors on each 2-d segment.

mask : np.array - input mask of good/bad (1/0) pixels allnbrs : bool - False/True masks 4/8 of neighbors around each bad pixel

np.array - mask with masked neighbors, shape = mask.shape

move_geo(par, dx, dy, dz)[source]

Moves detector.

par : int or psana.Event() - integer run number or psana event object. dx, dy, dz : float - three coordinate increments [um] of the detector motion.

ndarray_from_image(par, image, pix_scale_size_um=None, xy0_off_pix=None, do_update=False)[source]

Returns n-d array of intensities extracted from image using image bin indexes.

par : int or psana.Event() - integer run number or psana event object. image : np.array - input 2-d array which will be converted to n-d array. pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined. do_update : bool - force to update cached array.

np.array - n-d array of intensities made from image.

ndim(par)[source]

Returns number of dimensions of current detector pixel numpy array.

par : int or psana.Event() - integer run number or psana event object.

int - number of dimensions of current detector pixel numpy array. If ndim>3 then returns 3.

pedestals(par)[source]

Returns per-pixel array of pedestals (dark run intensities) from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pedestals.

photons(evt, nda_calib=None, mask=None, adu_per_photon=None)[source]

Returns 2-d or 3-d array of integer number of merged photons - algorithm suggested by Chuck.

evt : psana.Event() - psana event object. nda_calib : (float, double, int, int16) numpy.array - calibrated data, float number of photons per pixel. mask : (uint8) numpy.array user defined mask. adu_per_photon : float conversion factor which is applied as nda_calib/adu_per_photon.

np.array - 2-d or 3-d array of integer number of merged photons.

pixel_size(par)[source]

Returns pixel scale size in [um].

par : int or psana.Event() - integer run number or psana event object.

float - pixel size in [um].

point_indexes(par, pxy_um=(0, 0), pix_scale_size_um=None, xy0_off_pix=None)[source]

Returns (ix, iy) indexes of the point (x,y) specified in [um].

par : int or psana.Event() - integer run number or psana event object. pxy_um : list of two float values - coordinates of the point in the detector frame, default (0,0) pix_scale_size_um : float - pixel scale size [um] which is used to convert coordinate in index. xy0_off_pix : list of floats - image (x,y) origin offset in order to make all indexes positively defined.

tuple - (ix, iy) tuple of two indexes associated with input point coordinates.

print_attributes()[source]

Prints some of object attributes.

print_config(evt)[source]

Prints configuration parameters if available.

evt : psana.Event() - psana event object.

print_members()[source]

Depricated method renamed to print_attributes()

raw(evt)[source]

Returns per-pixel array of intensities from raw data.

evt : psana.Event() - psana event object.

np.array - per-pixel intensities [ADU] of raw data.

raw_data(evt)[source]

Alias for depricated method renamed to raw(evt)

rms(par)[source]

Returns per-pixel array of RMS values from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pixel_rms.

runnum(par)[source]

Returns integer run number from different options of input parameter.

par : int or psana.Event() - integer run number or psana event object.

int - run number

save_asdaq(fname='nda.txt', ndarr=None, cmts=(), fmt='%.1f', verbos=False, addmetad=True)[source]

Saves per-pixel n-d array shaped and ordered as in DAQ.

The same functionality as in the method save_txtnda(...), but array is shuffled to DAQ order. Currently re-shuffle pixels for cspad2x2 only from natural shape=(2,185,388) to daq shape (185,388,2). For all other detectors n-d array is saved unchanged.

fname : str - output file name. ndarr : np.array - array of numerical values to save in text file. cmts : list of str - list of strings which will be saved as comments in the file header. fmt : str - format of values in the file. verbose : bool - True/False = on/off messages from this method (about saved file etc.) addmetad : bool - True/False = on/off saving methadata (data type, and shape info) in file.

save_txtnda(fname='nda.txt', ndarr=None, cmts=(), fmt='%.1f', verbos=False, addmetad=True)[source]

Saves n-d array in the formatted text file with hash-type cumments and metadata.

fname : str - output file name. ndarr : np.array - array of numerical values to save in text file. cmts : list of str - list of strings which will be saved as comments in the file header. fmt : str - format of values in the file. verbose : bool - True/False = on/off messages from this method (about saved file etc.) addmetad : bool - True/False = on/off saving methadata (data type, and shape info) in file.

set_do_offset(do_offset=False)[source]

Switch mode of the Camera type of detector.

do_offset : bool - control parameter to turn on/off Camera intensity offset, default=False

set_env(env)[source]

Sets environment variable.

env : psana.Env() - psana environment variable, ex.: env=ds.env()

set_gain_mask_factor(gfactor=6.85)[source]

Sets the gain factor which is passed to gain_mask(...) in the det.calib and det.image methods.

set_print_bits(pbits)[source]

Sets print-control bitword.

pbits : int - print-control bitword, ex.: 0377 (octal)

set_source(srcpar, set_sub=True)[source]

Sets data source parameter.

srcpar : str - regular source or its alias, ex.: ‘XppEndstation.0:Rayonix.0’ or ‘rayonix’ set_sub : bool - default=True - propagates source parameter to low level package

shape(par=0)[source]

Returns shape of the detector pixel-array.

For all detectors except cspad2x2 shape is the same as in DAQ.

par : int or psana.Event() - integer run number or psana event object.

np.array - shape of the detector pixel-array, ex. for cspad (32,185,388).

shape_config(env)[source]
size(par)[source]

Returns size of the detector pixel-array.

par : int or psana.Event() - integer run number or psana event object.

int - size of the detector numpy pixel-array (number of pixels)

status(par)[source]

Returns array of pixel-status from calib directory.

par : int or psana.Event() - integer run number or psana event object.

np.array - per-pixel values loaded for calibration type pixel_status.
status bits: 0 - good pixel
1 - saturated intensity 2 - hot rms 4 - cold 8 - cold rms
status_as_mask(par, mode=0)[source]

Returns per-pixel array of mask generated from pixel_status.

par : int or psana.Event() - integer run number or psana event object. mode : int - 0/1/2 masks zero/four/eight neighbors around each bad pixel

np.array - mask generated from calibration type pixel_status (1/0 for status 0/>0, respectively).

tilt_geo(par, dtx, dty, dtz)[source]

Tilts detector.

par : int or psana.Event() - integer run number or psana event object. dtx, dty, dtz : float - three angular increments [deg] of the detector tilt.

Module Detector.ControlDataDetector

Class Detector.ControlDataDetector.ControlDataDetector

class Detector.ControlDataDetector.ControlDataDetector(source_string, env)[source]

An object that can be used to query the names/states of motors used in a DAQ scan. See PSDM confluence building-block examples documentation. Create this object with Detector(‘ControlData’).

source_string:
User must pass string ‘ControlData’ to the Detector constructor
env : psana.Env
The environment, for example from psana.DataSource.env()

Module Detector.DdlDetector

Class Detector.DdlDetector.DdlDetector

class Detector.DdlDetector.DdlDetector(source, env=None)[source]

This class is a generic wrapper for the DAQ system data types. It looks through the event keys for the object that have the user-specified psana source string. If there is more than one, an exception is thrown.

DDL stands for “Data Definition Language” which is a language that was written for LCLS to express the DAQ data objects in a language-independent way (i.e. for both python/C++).

source : str
A psana source string (not a psana.Source object), e.g. ‘DetInfo(CxiDsd.0:Cspad.0)’, ‘BldInfo(FEEGasDetEnergy)’, or an alias e.g. ‘cspad’.
_fetch_configs()[source]

Get the config store object pertaining to this Source.

_fetch_ddls(evt)[source]
_find_types(evt)[source]
get(evt)[source]

Default behavior for detectors who’s special Detector class has not been implemented.

evt: a psana event object

DAQ object associated with this event

Function Detector.DdlDetector.source_is_same

Detector.DdlDetector.source_is_same(source1, source2)[source]

Compares strings

Module Detector.DetectorTypes

This file contains static declarations of the known & interpretable detector types.

Class Detector.DetectorTypes.MissingDet

class Detector.DetectorTypes.MissingDet(name, *args, **kwargs)[source]

This detector is returned by the Detector interface when the user requests that the software not crash when a detector is missing. It returns a method that returns None for all attributes.

_none(*args, **kwargs)[source]

Function Detector.DetectorTypes.no_device_exception

Detector.DetectorTypes.no_device_exception(*args)[source]

Module Detector.EpicsDetector

Class Detector.EpicsDetector.EpicsDetector

class Detector.EpicsDetector.EpicsDetector(pv_string, env)[source]

This class is used to access data that is typically acquired at a rate slower than the LCLS shot rate (e.g. temperatures, voltages) using the EPICS slow-control system.

pv_string : str
The full-name or alias of an EPICS variable
env : psana.Env
The psana environment, for example from psana.DataSource.env()

Module Detector.EvrDetector

Detector interface for the EVR

Class Detector.EvrDetector.EvrDetector

class Detector.EvrDetector.EvrDetector(source, env=None)[source]

The EVR device is used by the DAQ system to control what happens from shot-to-shot (e.g. which devices are triggered (e.g. a camera, or a shutter)). For each event this object provides a list of “event codes” which can be used to understand which devices were activated in a particular LCLS event.

source : str
A psana source string (not a psana.Source object), e.g. ‘DetInfo(CxiDsd.0:Cspad.0)’, ‘BldInfo(FEEGasDetEnergy)’, or an alias e.g. ‘cspad’.
eventCodes(evt, this_fiducial_only=False)[source]

evt: a psana event object this_fiducial_only: bool.

If true, returns only eventcodes that were sent on precisely the fiducial corresponding to evt.

A list of integer event-codes associated with the input event

Module Detector.Generic1DDetector

Detector interface for the Generic1D type

Class Detector.Generic1DDetector.Generic1DDetector

class Detector.Generic1DDetector.Generic1DDetector(*args)[source]

Module Detector.GenericWFDetector

Detector interface for the Generic1D type, but specialized for the case where it represents waveforms with a time axis. This interface is intended to be identical to the WFDetector

Class Detector.GenericWFDetector.GenericWFDetector

class Detector.GenericWFDetector.GenericWFDetector(*args)[source]

This class returns a list of arrays of values (one entry in the list for each channel) and a corresponding list of time arrays that are used as oscilloscope-style channels.

raw(*args)[source]

evt: a psana event object

a list of waveform arrays, not converted into voltage

wftime(evt=None)[source]

(optional) evt: a psana event object. not used in this method but allowed to allow the interface similar to other Detector interface methods

a list of 1D arrays of time values of each sample, in seconds

Module Detector.GlobalUtils

Contains Global Utilities

This software was developed for the SIT project. If you use all or part of it, please give an appropriate acknowledgment.

Version: $Id: GlobalUtils.py 11967 2016-05-20 18:41:01Z dubrovin@SLAC.STANFORD.EDU $

Author: Mikhail S. Dubrovin

Function Detector.GlobalUtils.divide_protected

Detector.GlobalUtils.divide_protected(num, den, vsub_zero=0)[source]

Returns result of devision of numpy arrays num/den with substitution of value vsub_zero for zero den elements.

Function Detector.GlobalUtils.print_ndarr

Detector.GlobalUtils.print_ndarr(nda, name='', first=0, last=5)[source]

Module Detector.IpimbDetector

Detector interface for the Ipimb

Class Detector.IpimbDetector.IpimbDetector

class Detector.IpimbDetector.IpimbDetector(source, env=None)[source]

Detector interface for the IPIMB, the which monitors the beam intensity and position. Methods of note:

– sum – channel – xpos – ypos

source : str
A psana source string (not a psana.Source object), e.g. ‘DetInfo(CxiDsd.0:Cspad.0)’, ‘BldInfo(FEEGasDetEnergy)’, or an alias e.g. ‘cspad’.
_ddldata_or_none(evt, fxn_name)[source]
_fetch_ddls(evt)[source]

Overrides DdlDetector’s _fetch_ddls() method. Should find two DDL objects in the event’s .keys() that map to our source. We are only interested in the Fex one right now.

channel(evt)[source]

Return the intensities in all channels of the IPIMB.

evt : psana.Event
The event to retrieve data from.
channel : np.ndarray
The intensity of the beam measured in each of four individual channels. Units arbitrary.
sum(evt)[source]

Return the beam intensity measured by the IPIMB.

evt : psana.Event
The event to retrieve data from.
sum : float
The sum of the beam intensities in all channels.
xpos(evt)[source]

Compute the beam position along the x-axis as measured by the IPIMB.

evt : psana.Event
The event to retrieve data from.
xpos : float
The estimated x-position.
ypos(evt)[source]

Compute the beam position along the y-axis as measured by the IPIMB.

evt : psana.Event
The event to retrieve data from.
ypos : float
The estimated y-position.

Module Detector.OceanDetector

Detector interface for the Generic1D type

Class Detector.OceanDetector.OceanDetector

class Detector.OceanDetector.OceanDetector(*args)[source]
_raw(evt)[source]
intensity(evt)[source]

evt: a psana event object

A 1D array of intensities from the spectrometer, corrected for non-linearities if possible

wavelength(evt)[source]

evt: a psana event object

A 1D array of wavelength values in nm.

Module Detector.PyDataAccess

Function Detector.PyDataAccess.get_acqiris_config_object

Detector.PyDataAccess.get_acqiris_config_object(env, src)[source]

get acqiris config object

Function Detector.PyDataAccess.get_acqiris_data_object

Detector.PyDataAccess.get_acqiris_data_object(evt, src)[source]

get acqiris data object

Function Detector.PyDataAccess.get_andor_config_object

Detector.PyDataAccess.get_andor_config_object(env, src)[source]

get andor config object

Function Detector.PyDataAccess.get_andor_data_object

Detector.PyDataAccess.get_andor_data_object(evt, src)[source]

get andor data object

Function Detector.PyDataAccess.get_camera_config_object

Detector.PyDataAccess.get_camera_config_object(env, src)[source]

get camera config object

Function Detector.PyDataAccess.get_camera_data_object

Detector.PyDataAccess.get_camera_data_object(evt, src)[source]

get camera data object

Function Detector.PyDataAccess.get_cspad2x2_config_object

Detector.PyDataAccess.get_cspad2x2_config_object(env, src)[source]

get cspad2x2 config object

Function Detector.PyDataAccess.get_cspad2x2_data_object

Detector.PyDataAccess.get_cspad2x2_data_object(evt, src)[source]

get cspad2x2 data object

Function Detector.PyDataAccess.get_cspad_config_object

Detector.PyDataAccess.get_cspad_config_object(env, src)[source]

get cspad config object

Function Detector.PyDataAccess.get_cspad_data_object

Detector.PyDataAccess.get_cspad_data_object(evt, src)[source]

get cspad data object

Function Detector.PyDataAccess.get_epix_config_object

Detector.PyDataAccess.get_epix_config_object(env, src)[source]

get epix config object

Function Detector.PyDataAccess.get_epix_data_object

Detector.PyDataAccess.get_epix_data_object(evt, src)[source]

get epix data object

Function Detector.PyDataAccess.get_evr_data_object

Detector.PyDataAccess.get_evr_data_object(evt, src)[source]

get evr data object for event codes

Function Detector.PyDataAccess.get_fccd960_config_object

Detector.PyDataAccess.get_fccd960_config_object(env, src)[source]

get fccd960 config object

Function Detector.PyDataAccess.get_fccd960_data_object

Detector.PyDataAccess.get_fccd960_data_object(env, src)[source]

get fccd960 data object

Function Detector.PyDataAccess.get_fccd_config_object

Detector.PyDataAccess.get_fccd_config_object(env, src)[source]

get fccd config object

Function Detector.PyDataAccess.get_fccd_data_object

Detector.PyDataAccess.get_fccd_data_object(env, src)[source]

get fccd data object

Function Detector.PyDataAccess.get_fli_config_object

Detector.PyDataAccess.get_fli_config_object(env, src)[source]

get fli config object

Function Detector.PyDataAccess.get_fli_data_object

Detector.PyDataAccess.get_fli_data_object(evt, src)[source]

get fli data object

Function Detector.PyDataAccess.get_imp_config_object

Detector.PyDataAccess.get_imp_config_object(env, src)[source]

get imp config object

Function Detector.PyDataAccess.get_imp_data_object

Detector.PyDataAccess.get_imp_data_object(evt, src)[source]

get imp data object

Function Detector.PyDataAccess.get_jungfrau_config_object

Detector.PyDataAccess.get_jungfrau_config_object(env, src)[source]

Function Detector.PyDataAccess.get_jungfrau_data_object

Detector.PyDataAccess.get_jungfrau_data_object(evt, src)[source]

get jungfrau data object

Function Detector.PyDataAccess.get_opal1k_config_object

Detector.PyDataAccess.get_opal1k_config_object(env, src)[source]

get camera config object

Function Detector.PyDataAccess.get_orca_config_object

Detector.PyDataAccess.get_orca_config_object(env, src)[source]

get orca config object

Function Detector.PyDataAccess.get_pimax_config_object

Detector.PyDataAccess.get_pimax_config_object(env, src)[source]

get pimax config object

Function Detector.PyDataAccess.get_pimax_data_object

Detector.PyDataAccess.get_pimax_data_object(evt, src)[source]

get pimax data object

Function Detector.PyDataAccess.get_pnccd_config_object

Detector.PyDataAccess.get_pnccd_config_object(env, src)[source]

get pnccd config object

Function Detector.PyDataAccess.get_pnccd_data_object

Detector.PyDataAccess.get_pnccd_data_object(evt, src)[source]

get pnccd data object

Function Detector.PyDataAccess.get_princeton_config_object

Detector.PyDataAccess.get_princeton_config_object(env, src)[source]

get princeton config object

Function Detector.PyDataAccess.get_princeton_data_object

Detector.PyDataAccess.get_princeton_data_object(evt, src)[source]

get princeton data object

Function Detector.PyDataAccess.get_quartz_config_object

Detector.PyDataAccess.get_quartz_config_object(env, src)[source]

get quartz config object

Function Detector.PyDataAccess.get_quartz_data_object

Detector.PyDataAccess.get_quartz_data_object(evt, src)[source]

get quartz data object

Function Detector.PyDataAccess.get_rayonix_config_object

Detector.PyDataAccess.get_rayonix_config_object(env, src)[source]

get rayonix config object

Function Detector.PyDataAccess.get_rayonix_data_object

Detector.PyDataAccess.get_rayonix_data_object(evt, src)[source]

get rayonix data object

Function Detector.PyDataAccess.get_timepix_config_object

Detector.PyDataAccess.get_timepix_config_object(env, src)[source]

get timepix config object

Function Detector.PyDataAccess.get_timepix_data_object

Detector.PyDataAccess.get_timepix_data_object(evt, src)[source]

get timepix data object

Function Detector.PyDataAccess.get_tm6740_config_object

Detector.PyDataAccess.get_tm6740_config_object(env, src)[source]

get pulnix tm6740 config object

Module Detector.PyDetector

Method detector_factory(src,env) returns instance of the detector data accessor.

Method detector_factory(src,env) switches between detector data access objects depending on source parameter. Currently implemented detector data access classes:

Detector.AreaDetector - access to area detector data

Detector.WFDetector - access to waveform detector data

Detector.EvrDetector - access to EVR data

Detector.DdlDetector - access to DDL data

Detector.EpicsDetector - access to EPICS data

Usage:

# Import
import psana

# Input parameters
# str object for data source can be defined using DAQ detector name
src = 'XppGon.0:Cspad.0' # or its alias 'cspad'
# The list of available detector names and alieses for data set can be printed by the command like
# detnames exp=xpptut15:run=54

# env object can be defined from data set
ds = psana.DataSource('exp=xpptut15:run=54')
env = ds.env()

# Create detector object
det = psana.Detector(src, env)

# in ipython the list of det methods can be seen using "tab completion" operation - type "det." and hit the Tab key.

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Class Detector.PyDetector.DetInfo

class Detector.PyDetector.DetInfo(source_string)[source]

A class that provides a consistent string repr for all detectors, e.g. BldInfo() types that have only a single name and DetInfo() types that adhere to ”.:.” syntax.

If that didn’t mean anything to you, then you don’t need this class.

Interpret a string like ‘DetInfo(CxiDs2.0:Cspad.0)’ in terms of:

detector_type –> ‘CxiDs2’ detector_id –> 0 device_type –> ‘Cspad’ device_id –> 0

Function Detector.PyDetector.detector_factory

Detector.PyDetector.detector_factory(source_string, env, *args, **kwargs)[source]

See psana/src/det_interface.py for documentation

Function Detector.PyDetector.dettype

Detector.PyDetector.dettype(source_string, env, accept_missing=False, *args, **kwargs)[source]

Create a python Detector-class “type” from a string identifier.

source_string : str
A string identifying a piece of data to access, examples include:
  • ‘cspad’ # a DAQ detector alias
  • ‘XppGon.0:Cspad.0’ # a DAQ detector full-name
  • ‘DIAG:FEE1:202:241:Data’ # an EPICS variable name (or alias)
  • ‘EBeam’ # a BldInfo identifier

The idea is that you should be able to pass something that makes sense to you as a human here, and you automatically get the right detector object in return.

env : psana.Env
The psana environment object associated with the psana.DataSource you are interested in (from method DataSource.env()).

The type of the appropriate detector class

Function Detector.PyDetector.map_alias_to_source

Detector.PyDetector.map_alias_to_source(source_string, env)[source]

Check to see if source_string is in the env alias map, and if so use the alias map to look it up and return the psana Source string corresponding to that alias.

source_string : str
A string identifying a piece of data to access, examples include:
env : psana.Env
The psana environment object associated with the psana.DataSource you are interested in (from method DataSource.env()).
source_string : str
De-aliased source string – a unique identifier.

Module Detector.PyDetectorAccess

Class contains a collection of direct python access methods to detector associated information.

Access method to calibration and geometry parameters, raw data, etc. Low level implementation is done on python.

See also: classes

Detector.PyDetector - factory for different detectors

Detector.DetectorAccess - c++ access interface to data

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Version: $Id: PyDetectorAccess.py 13030 2016-12-19 22:50:20Z cpo@SLAC.STANFORD.EDU $

Author: Mikhail S. Dubrovin

Module Detector.TDCDetector

Detector interface for the TDC type

Class Detector.TDCDetector.TDCDetector

class Detector.TDCDetector.TDCDetector(*args)[source]

Provides access to hit times from a TDC device with multiple channels.

_times(evt, overflows=0)[source]
overflows(evt)[source]

evt: a psana event object

A list of arrays, or None if data not found. Each array contains the times (in seconds) of TDC hits for a channel, for cases where the time value has “wrapped”.

times(evt)[source]

evt: a psana event object

A list of arrays, or None if data not found. Each array contains the times (in seconds) of TDC hits for a channel.

Module Detector.UsdUsbDetector

Detector interface for the UsdUsb Encoder Box

Class Detector.UsdUsbDetector.UsdUsbDetector

class Detector.UsdUsbDetector.UsdUsbDetector(source, env)[source]

Detector interface for the USDUSB encoder box, the which monitors the encoder counts of a device. Methods of note:

– descriptions - user defined descriptions of each channel – values

source : str
A psana source string (not a psana.Source object), e.g. ‘DetInfo(CxiDsd.0:Cspad.0)’, ‘BldInfo(FEEGasDetEnergy)’, or an alias e.g. ‘cspad’.
_ddlcfglist_or_none(fxn_name, is_fex)[source]
_ddldata_or_none(evt, fxn_name, is_fex)[source]
_fetch_cfg_ddls(is_fex)[source]

Similar to DdlDetector’s _fetch_ddls() method. Should find two DDL objects in the config’s .keys() that map to our source. We are only interested in the Fex one right now.

_fetch_ddls(evt, is_fex=False)[source]

Overrides DdlDetector’s _fetch_ddls() method. Should find two DDL objects in the event’s .keys() that map to our source.

descriptions()[source]

Return the description field for all channels of the USDUSB.

descriptions : list
Description string for each of the four individual channels.
values(evt)[source]

Return the calibrated encoder values in all channels of the USDSUB if available. If no calibrated values are available it returns the raw encoder counts.

The calibrated value is calculated for each channel as follows:
value = scale * (raw_count + offset)

The scale and offset values can be retrieved from the configStore.

evt : psana.Event
The event to retrieve data from.
values : np.ndarray
The calibrated encoder value measured in each of the four individual channels. Units depend on chosen calibration.

Module Detector.WFDetector

Class contains a collection of access methods to waveform detector data.

Usage:

# !!! NOTE: None is returned whenever requested information is missing.

# import
import psana
from Detector.WFDetector import WFDetector    

# retreive parameters from psana etc.
dsname = 'exp=sxri0414:run=88'
src = 'SxrEndstation.0:Acqiris.2' # or its alias 'acq02'

ds  = psana.DataSource(dsname)
env = ds.env()
evt = ds.events().next()
runnum = evt.run()

# parameret par can be either runnum or evt    
par = runnum
# or
par = evt

det = WFDetector(src, env, pbits=0, iface='P') # iface='P' or 'C' - preferable low level interface (not used in this class)

# set parameters, if changed
det.set_env(env)
det.set_source(source)
det.set_print_bits(pbits)

# print info
det.print_attributes()    
det.print_config(evt)

instrument = det.instrument()

# get array with waveforms
wf = det.waveform(evt)

# get array with waveform sample times
wt = det.wftime(evt)

#--------------------------- 
# Detector-specific methods
#---------------------------

# access to Acqiris data
det.set_correct_acqiris_time(correct_time=True) # (by default)
wf, wt = det.raw(evt)
# returns two np.array-s with shape = (nbrChannels, nbrSamples) for waveform and associated timestamps or (single) None.

# access to Imp data
det.set_calib_imp(do_calib_imp=True) # Imp calibration will subtract base level with changing dtype to np.int32
wf = det.raw(evt)
# returns numpy array with shape=(4, 1023) - samples for 4 channels or None if unavailable.

See also: Detector.PyDetectorAccess, Detector.AreaDetector, Detector.PyDetector

This software was developed for the LCLS project. If you use all or part of it, please give an appropriate acknowledgment.

Version: $Id: WFDetector.py 11009 2015-11-18 18:10:30Z dubrovin@SLAC.STANFORD.EDU $

Author: Mikhail S. Dubrovin