This note describes area detector interface methods to access raw and calibrated data, reconstruct image for mutli-panel detector, retrieve calibration constants, geometry parameters, define the mask for pixel array, etc.

Set environment

Code discussed in this note works on psana nodes which have access to data in lcls2 environment described in LCLS-II psana Environment.

To run examples one has to ssh to psana node and set environment

Login to psana node and set lcls2 environment on pcds 
ssh -Y pslogin.slac.stanford.edu
ssh -Y psana
source /cds/sw/ds/ana/conda1/manage/bin/psconda.sh
Login to psana node and set lcls2 environment on s3df
ssh -Y s3dflogin.slac.stanford.edu
ssh -Y psana
source /sdf/group/lcls/ds/ana/sw/conda1/manage/bin/psconda.sh

Code examples

Most updated description of this interface is on git in the head of the file detector/areadetector.py

Create DataSource, Run, and Detector objects

    from psana import DataSource
    ds = DataSource(exp='tmoc00318',run=10, dir='/cds/data/psdm/prj/public01/xtc')
    orun = next(ds.runs())
    det = orun.Detector('epix100')

Loop over events and access detector data

Methods guaranteed for all area detectors - raw, calib, and image:

    for evt orun.events():
        o = det.raw
        raw = o.raw(evt)
        clb = o.calib(evt)
        img = o.image(evt)

Optional parameters

kwa = <dict-of-mask-parameters>
a = o.calib(evt, cmpars=(7,2,100,10), **kwa)
a = o.image(evt, nda=None, **kwa) # reduced shape for available segment only
a = o.image(evt, nda=None, value_for_missing_segments=800, **kwa) # full image including missing segments

cmpars

This kwarg is used to set common-mode parameters.  We are trying to adopt a uniform interface for this for LCLS2 area detectors with the following three rules:

  • if cmpars is set to None then no common-mode algorithm is applied
  • if no cmpars kwarg is supplied, a given detector type may or may not apply common-mode by default (whatever is deemed the best behavior for the detector in question)
  • To have a uniform interface across detector-types, cmpars values (that are not None) should be a tuple of parameter values, e.g. (1,0,3.7) where the meaning of the parameter values is detector-type specific.  This should be done even if a particular detector's common-mode algorithm doesn't use the parameters (e.g. archon).

Calibration constants

All detector calibration constants (np.array) and associated  metadata (dict) are available through the dictionary det.calibconst with calibration type as a key. For example:

peds, meta = det.calibconst['pedestals']

Possible calibration types: pedestals, pixel_status,  pixel_rms,  pixel_gain, pixel_mask, etc.

Mask

See for details Area detector mask examples.

Instantiation of the Mask object
from psana.detector.mask import Mask, DTYPE_MASK

kwa = {'status':True, 'status_bits':0xffff, 'stextra_bits':(1<<64)-1, 'gain_range_inds':(0,1,2,3,4),\
       'neighbors':False, 'rad':3, 'ptrn':'r',\
       'edges':False, 'width':0, 'edge_rows':10, 'edge_cols':5,\
       'center':False, 'wcenter':0, 'center_rows':5, 'center_cols':3,\
       'calib':False,\
       'umask':None,\
       'force_update':False, 'dtype':DTYPE_MASK}

m = Mask(det, **kwa)

m = Mask(det) # minimal version.
Combined and separate mask methods
m.set_mask(**kwa) # forced update of cached mask.
mask = m.mask(**kwa) # returns cached mask.
mask = m.mask_default()
mask = m.mask_calib_or_default() # if available returns mask from "pixel_mask" calibration type, otherwise array of ones.
mask = m.mask_from_status(status_bits=0xffff, stextra_bits:(1<<64)-1, gain_range_inds=(0,1,2,3,4), dtype=DTYPE_MASK)
mask = m.mask_edges(width=0, edge_rows=1, edge_cols=1, dtype=DTYPE_MASK)
mask = m.mask_center(wcenter=0, center_rows=1, center_cols=1, dtype=DTYPE_MASK)
mask = m.mask_neighbors(mask, rad=9, ptrn='r')
  • default combined mask parameters (status=True, neighbors=False, edges=False, center=False, calib=False, umask=None) are set to define mask for pixel_status only.
  • mask is used in det.raw.calib/image mask at evaluation of common mode correction, but by default it is not applied to data.
  • to apply mask to data use multiplication calib *= mask.

Other useful area detector methods

# direct access to calibration constants and derived arrays
peds = o._pedestals()
gain = o._gain() # ADU/keV
gfac = o._gain_factor() # keV/ADU
rms  = o._rms()
status = o._status()

arrx, arry, arrz = o._pixel_coords(do_tilt=True, cframe=0)
indx, indy, indz = o._pixel_coord_indexes(pix_scale_size_um=None, xy0_off_pix=None, do_tilt=True, cframe=0)
  
# array of the common mode increment
incr = o._common_mode_increment(evt, cmpars=(0,7,100,10))

References

  • No labels