Package pyana

This package collects code which deals with various aspects of the analysis tasks.

Module event

This module is a collection of classes and methods to deal with the event data and everything related to it.

Class Event

Instance of this class contains all event data.

Construction

Usage: evt = pyana.event.Event(dg)

Creates event object from the corresponding XTC datagram object.

Parameters:

dg – datagram object of type _pdsdata.xtc.Dgram

Method seq()

Usage: s = evt.seq()

Returns _pdsdata.xtc.Seq object, equivalent to dg.seq

Method getTime()

Usage: t = evt.getTime()

Returns _pdsdata.xtc.ClockTime object, equivalent to dg.seq.clock()

Method find()

Usage: objects = evt.find(...)

Returns possibly empty list of data objects contained in the event. This method accepts a number of arguments, but all arguments are optional. If no arguments are given then a list of all data objects is returned. If some arguments are given then only those objects that satisfy a particular criteria are returned. The list of possible keyword arguments:

typeId – accepts one of the xtc.TypeId.Type.<Xxx>, only return objects which have that TypeId
version – accepts number, only return objects whose type version number is equal to number
level – accepts one of xtc.Level.<Xxx> values, only returns objects originated at that level
detector – accepts one of xtc.DetInfo.Detector.<Xxx> values, only returns objects produced by this detector
detId – accepts number, only returns objects produced by this detector ID
device – accepts one of xtc.DetInfo.Device.<Xxx> values, only returns objects produced by this device
devId – accepts number, only returns objects produced by this device ID
address – xtc.DetInfo object or an address string (see User Manual)

The parameters address and any of the detector, detId, device, devId are incompatible, specify only one or another.

Method findFirst()

Usage: object = evt.findFirst(...)

Accepts the same set of arguments as find() methods but instead of list of objects returns fist object found. If no object is satisfying all selection criteria then None is returned.

Method getAcqConfig()

Usage: acqConfig = evt.getAcqConfig(address)

Returns Acqiris configuration data of type acqiris.ConfigV* for specific device. If address given is not very specific then the first matching object is returned.

Parameters:

address – xtc.DetInfo object or an address string (see User Manual)

Ordinary configuration objects are contained in a Configure type datagrams only. For client code that means that this method can be used in beginjob() or beginrun() methods only. Note also that configuration objects are stored in the Pyana environment and preferred way to access configuration information is through the environment. This makes this method of little utility to end users.

Method getOpal1kConfig()

Usage: opalConfig = evt.getOpal1kConfig(address)

Returns Opal1k configuration data of type opal1k.ConfigV* for specific device. If address given is not very specific then the first matching object is returned.

Parameters:

address – xtc.DetInfo object or an address string (see User Manual)

Same caveats apply as for getAcqConfig() method.

Method getAcqValue()

Usage: acqData = evt.getAcqValue(address, channel, env)

Returns Acqiris data object of type acqiris.DataDescV* for specific device and channel. If address given is not very specific then the first matching object is returned.

Parameters:

address – xtc.DetInfo object or an address string (see User Manual)
channel – channel number from 0 to max number of channels
env – environment object containing Acqiris configuration object

Channel number is an integer number, total number of channels can be extracted from the Acqiris configuration object.

Method getPnCcdValue()

Usage: frame = evt.getPnCcdValue(address, env)

returns pnCCD data object of type pnccd.FrameV* for specific device and channel. If address given is not very specific then the first matching object is returned.

Parameters:

address – xtc.DetInfo object or an address string (see User Manual)
env – environment object containing pnCCD configuration object

Method getFeeGasDet()

Usage: array = evt.getFeeGasDet()

Returns the list of 4 numbers [f_11_ENRC, f_12_ENRC, f_21_ENRC, f_22_ENRC]

Method getPhaseCavity()

Usage: obj = evt.getPhaseCavity()

Returns data object of type bld.BldDataPhaseCavity.

Method getEBeam()

Usage: obj = evt.getEBeam()

Returns data object of type bld.BldDataEBeam or bld.BldDataEBeamV0 whichever is present in the event.

Class Env

Instance of this class is a container for all sorts of environment data.

Construction

Usage: env = pyana.event.Env(jobName="pyana", hmgr=None, subproc=False)

Creates environment object.

Parameters:

jobName – analysis job name, arbitrary string
hmgr – histogram manager object
subproc – flag which must be set to true when running in pyana sub-process

Objects of this type are created by pyana itself and end users do not need to create new instances.

Method jobName()

Usage: jobName = env.jobName()

Returns analysis job name string.

Method hmgr()

Usage: hmgr = env.hmgr()

Returns histogram manager object of type pyana.histo.HistoManager*.

Method mkfile()

Usage: file = env.mkfile(filename, mode='w', bufsize=-1)

Opens file for writing output data. This is pyana's alternative for Python open() function which supports multi-processing. If user needs the data in this file to be merged with the files produced by other processes then mkfile() has to be used in place of open().

Parameters:

filename – output file name
mode – open mode, currently any "w*" modes are supported
bufsize – output buffer size, default is to use Python's default

In case of single-process job this method is equivalent to a regular Python open() method. In case of multi-processing when this method is called from a sub-process then the file is created somewhere in a temporary location (with unique name). At the end of the job files from all sub-processes are merged into one file with name filename and the temporary files are deleted.

Method epicsStore()

Usage: store = env.epicsStore()

This is the primary method for user code to access EPICS data. It returns event.EpicsStore object which can be used to retrieve the state of the individual EPICS channels.

Method update()

Usage: env.update(evt)

This method updates environment contents with selected data from event object. This is equivalent to calling env.updateEpics() and env.updateConfig().

Parameters:

evt – event object of type event.Event

This method is not supposed to be called from user code, pyana takes care of all updates itself.

Method updateEpics()

Usage: env.updateEpics(evt)

This method updates environment EPICS data from event object.

Parameters:

evt – event object of type event.Event

This method is not supposed to be called from user code, pyana takes care of all updates itself.

Method updateConfig()

Usage: env.updateConfig(evt)

This method copies configuration objects from event object into environment.

Parameters:

evt – event object of type event.Event

This method is not supposed to be called from user code, pyana takes care of all updates itself.

Method getAcqConfig()

Usage: acqConfig = env.getAcqConfig(...)

Returns Acqiris configuration object for a given device address. If more than one object is matched by the parameters then first arbitrary object is returned.

Keyword arguments:

detector – accepts one of xtc.DetInfo.Detector.<Xxx> values, only returns objects produced by this detector
detId – accepts number, only returns objects produced by this detector ID
device – accepts one of xtc.DetInfo.Device.<Xxx> values, only returns objects produced by this device
devId – accepts number, only returns objects produced by this device ID
address – xtc.DetInfo object or an address string (see User Manual)

Method getPnCCDConfig()

Usage: pnccdConfig = env.getPnCCDConfig(...)

Returns pnCCD configuration object for a given device address. If more than one object is matched by the parameters then first arbitrary object is returned.

Accepts the same keyword arguments as the getAcqConfig() method.

Method getOpal1kConfig()

Usage: opalConfig = env.getOpal1kConfig(...)

Returns Opal1k configuration object for a given device address. If more than one object is matched by the parameters then first arbitrary object is returned.

Accepts the same keyword arguments as the getAcqConfig() method.

Method result()

Usage: data = env.result()

Method used by pyana to extract the data produced by a single sub-process in multi-processing setup. Not to be used by end users.

Class EpicsStore

Instance of this class contains current status of all EPICS channels. It is updated from event data on every new event.

Construction

Usage: store = pyana.event.EpicsStore()

Creates EPICS store object.

Objects of this type are created by pyana itself and end users do not need to create new instances.

Method update()

Usage: store.update(evt)

This method updates environment EPICS data from event object.

Parameters:

evt – event object of type event.Event

This method is not supposed to be called from user code, pyana takes care of all updates itself.

Method value()

Usage epics = store.value(name)

Returns current value of the EPICS channel with the given name. The type of returned data is either pypdsdata.epics.EpicsPvCtrl or pypdsdata.epics.EpicsPvTime.

Parameters:

name – name of the EPICS channel

This is the primary method to access EPICS information in pyana jobs.

Module histo

This module is a collection classes and methods to create and manage histograms from user analysis modules.

Class HistoMgrRoot

This class represents histogram manager implementation based on ROOT library. Histograms that are created by this manager reside either in memory or in a ROOT file.

Construction

Usage: hmgr = pyana.histo.HistoMgrRoot(...)

Creates new histogram manager object. Users should not instantiate new objects, instead the environment method hmgr() should be used to obtain existing manager object.

Keyword arguments:

file – name of the ROOT file to store histograms, if missing then histograms will be memory-resident

Method h1d()

Usage: hist = hmgr.h1d(...)

Creates 1-dimensional histogram with bin contents stored as double precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH1D. The returned object also inherits most of the methods of the C++ class.

Method h1f()

Usage: hist = hmgr.h1f(...)

Creates 1-dimensional histogram with bin contents stored as single precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH1F. The returned object also inherits most of the methods of the C++ class.

Method h1i()

Usage: hist = hmgr.h1i(...)

Creates 1-dimensional histogram with bin contents stored as integer numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH1I. The returned object also inherits most of the methods of the C++ class.

Method h2d()

Usage: hist = hmgr.h2d(...)

Creates 2-dimensional histogram with bin contents stored as double precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH2D. The returned object also inherits most of the methods of the C++ class.

Method h2f()

Usage: hist = hmgr.h2f(...)

Creates 2-dimensional histogram with bin contents stored as single precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH2F. The returned object also inherits most of the methods of the C++ class.

Method h2i()

Usage: hist = hmgr.h2i(...)

Creates 2-dimensional histogram with bin contents stored as integer numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TH2F. The returned object also inherits most of the methods of the C++ class.

Method prof()

Usage: hist = hmgr.prof(...)

Creates 1-dimensional profile histogram with bin contents stored as double precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TProfile. The returned object also inherits most of the methods of the C++ class.

Method prof2d()

Usage: hist = hmgr.prof2d(...)

Creates 2-dimensional profile histogram with bin contents stored as double precision numbers.

Method accepts the same arguments as the constructors of the corresponding C++ ROOT class TProfile2D. The returned object also inherits most of the methods of the C++ class.

Function HistoMgr()

Usage: hmgr = HistoMgr(...)

Do not call it, it's for pyana internal use.

Module _pdsdata

This is a Python extension module which provides Python interface for all pdsdata classes and functions. It is implemented in C++ and exists as a loadable module (library). The Python classes in this module try to mimic the interfaces and behavior of their corresponding C++ classes as closely as possible. In many cases this is trivial to achieve, but there may be few differences which are noted explicitly in every case. One notable difference is C++ enums which define symbolic names for integral constants. Python emulation of enums is complicated for a number of reasons such as absence of true enum type in Python and dynamic nature of language. The implementation of the enums in Python in this case is done through the introduction of special new type with the static members whose names and values correspond to C++ enums. It is better explained with example. Suppose there is a class in C++:

class DetInfo {
  enum Detector{ NoDetector, AmoIms, AmoGasdet, ... };
};

Then the corresponding construct in Python can be expressed approximately like this:

class DetInfo :
  class Detector (int): 
    NoDetector = Detector(0)
    AmoIms = Detector(1)
    AmoGasdet = Detector(2)

The main difference in use is that in C++ to get enum value one needs to write DetInfo.AmoIms when in Python it needs to be DetInfo.Detector.AmoIms.

Module _pdsdata.xtc

This module contains classes corresponding to those in C++ pdsdata/xtc package.

Class BldInfo

Python wrapper for pdsdata/xtc/BldInfo class. Unlike C++ this class does not inherit from Src class (Src class does not exist in this module) but uses dynamic Python features to implement the same interface as in Src class. In addition to methods described here the class also defines __hash__ and __cmp__ methods based on the content of the object and can be used as a key in the dictionaries.

Enum Type

This enum is an embedded type of BldInfo class. Following enum members are defined currently:

BldInfo.Type.EBeam
BldInfo.Type.PhaseCavity
BldInfo.Type.FEEGasDetEnergy
BldInfo.Type.NumberOf

Construction

Usage: bld = xtc.BldInfo(processId, type)

Arguments:

processId – integer number
type – one of the BldInfo.Type enum values

Method level()

Usage: lvl = bld.level()

Returns enum value of type xtc.Level which defines source level.

Method log()

Usage: log = bld.log()

Returns logical address of data source as integer number.

Method phy()

Usage: phy = bld.phy()

Returns physical address of data source as integer number.

Method processId()

Usage: processId = bld.processId()

Returns process ID as integer number.

Method type()

Usage: type = bld.type()

Returns BldInfo type which is a value of BldInfo.Type.

Class ClockTime

Python wrapper for pdsdata/xtc/ClockTime class. In addition to methods described here the class also defines __hash__ and __cmp__ methods based on the content of the object and can be used as a key in the dictionaries.

Construction

Usage: clock = xtc.ClockTime([seconds, [nanoseconds]])

Creates new instance of type.

Arguments:

seconds – seconds since UNIX epoch
nanosecods – nanoseconds within second

If any argument is missing it is assumed to be 0.

Method seconds()

Usage: sec = clock.seconds()

Returns the number of seconds as integer number.

Method nanoseconds()

Usage: nsec = clock.nanoseconds()

Returns the number of nanoseconds as integer number.

Class Damage

Python wrapper for pdsdata/xtc/Damage class.

Enum Value

This enum is an internal type of Damage class. Following enum members are defined currently:

Damage.Value.DroppedContribution
Damage.Value.OutOfOrder
Damage.Value.OutOfSynch
Damage.Value.UserDefined
Damage.Value.IncompleteContribution
Damage.Value.ContainsIncomplete

The values of enum constants define the bit number in the damage mask.

Enum Mask

Python Only

This enum does not exist in C++ class, has been added to Python for convenience

This enum is an internal type of Damage class. Following enum members are defined currently:

Damage.Mask.DroppedContribution
Damage.Mask.OutOfOrder
Damage.Mask.OutOfSynch
Damage.Mask.UserDefined
Damage.Mask.IncompleteContribution
Damage.Mask.ContainsIncomplete

The values of enum constants define the bit mask in the damage mask. Mask enum is equivalent to 1<<Value enum.

Construction

Usage: dmg = xtc.Damage([value])

Arguments:

value – complete damage mask as an integer number, if missing then assumed 0

Method value()

Usage: mask = dmg.value()

Returns complete damage mask as integer number.

Method hasDamage()

Usage: result = dmg.hasDamage(value)

Returns true if the corresponding damage bit is set.

Arguments:

value – bit number of the damage mask, one of the Damage.Value enums

Class DetInfo

Python wrapper for pdsdata/xtc/DetInfo class. Unlike C++ this class does not inherit from Src class (Src class does not exist in this module) but uses dynamic Python features to implement the same interface as in Src class. In addition to methods described here the class also defines __hash__ and __cmp__ methods based on the content of the object and can be used as a key in the dictionaries.

Enum Detector

This enum is an embedded type of DetInfo class. Following enum members are defined currently:

DetInfo.Detector.NoDetector
DetInfo.Detector.AmoIms
DetInfo.Detector.AmoGasdet
DetInfo.Detector.AmoETof
DetInfo.Detector.AmoITof
DetInfo.Detector.AmoMbes
DetInfo.Detector.AmoVmi
DetInfo.Detector.AmoBps
DetInfo.Detector.Camp
DetInfo.Detector.EpicsArch
DetInfo.Detector.BldEb
DetInfo.Detector.NumDetector

Enum Device

This enum is an embedded type of DetInfo class. Following enum members are defined currently:

DetInfo.Device.NoDevice
DetInfo.Device.Evr
DetInfo.Device.Acqiris
DetInfo.Device.Opal1000
DetInfo.Device.TM6740
DetInfo.Device.pnCCD
DetInfo.Device.NumDevice

Construction

Usage: det = xtc.DetInfo(processId, detector, detId, device, devId)

Arguments:

processId – integer number
detector – one of the DetInfo.Detector enum values
detId – detector ID as integer number
device – one of the DetInfo.Device enum values
devId – device ID as integer number

Method level()

Usage: lvl = det.level()

Returns enum value of type xtc.Level which defines source level.

Method log()

Usage: log = det.log()

Returns logical address of data source as integer number.

Method phy()

Usage: phy = det.phy()

Returns physical address of data source as integer number.

Method processId()

Usage: processId = det.processId()

Returns process ID as integer number.

Method detector()

Usage: detector = det.detector()

Returns detector enum which is a value of DetInfo.Detector.

Method device()

Usage: device = det.device()

Returns device enum which is a value of DetInfo.Device.

Method detId()

Usage: detId = det.detId()

Returns detector ID as integer number.

Method devId()

Usage: devId = det.devId()

Returns device ID as integer number.

Class Dgram

Python wrapper for pdsdata/xtc/Dgram class.

Construction

Usage: dg = xtc.Dgram(buffer)

One of the ways to create Dgram objects is from a Python buffer objects.

Arguments:

buffer – any object that implements buffer interface

Property env

Usage: env = dg.env

Returns the env field as an integer number.

Property seq

Usage: seq = dg.seq

Returns the seq field as an object of type xtc.Seq.

Property xtc

Usage: x = dg.xtc

Returns top-level Xtc as object of type xtc.Xtc.

Class Level

Python wrapper for pdsdata/xtc/Level class. C++ class does not define any data members or methods, it only defines single enum type. C++ cannot be instantiated in any meaningful way. Python class in addition to defining corresponding enum constants can also be instantiated, the instances are regular integer numbers with additional printing enhancements.

Enum Type

Unlike other enum types which create separate new type inside original Python type, the enums in Level class are defined directly in the class. Known enums:

Level.Control
Level.Source
Level.Segment
Level.Event
Level.Recorder
Level.Observer
Level.Reporter
Level.NumberOfLevels

Construction

Usage: lvl = xtc.Level(number)

Arguments:

number – any of the above enums can be used

Method str

Usage: s = str(lvl)

Returns a name of the corresponding enum.

Method repr

Usage: s = repr(lvl)

Returns a string in the form "<Level(num):name>" where num and name are the value and the name of the corresponding enum.

Class ProcInfo

Python wrapper for pdsdata/xtc/ProcInfo class. Unlike C++ this class does not inherit from Src class (Src class does not exist in this module) but uses dynamic Python features to implement the same interface as in Src class. In addition to methods described here the class also defines __hash__ and __cmp__ methods based on the content of the object and can be used as a key in the dictionaries.

Construction

Usage: proc = xtc.ProcInfo(level, processId, ipAddr)

Arguments:

level – instance of xtc.Level class
processId – integer number
ipAddr – IP address of the host as integer number

Method level()

Usage: lvl = proc.level()

Returns enum value of type xtc.Level which defines source level.

Method log()

Usage: log = proc.log()

Returns logical address of data source as integer number.

Method phy()

Usage: phy = proc.phy()

Returns physical address of data source as integer number.

Method processId()

Usage: processId = proc.processId()

Returns process ID as integer number.

Method ipAddr()

Usage: ipAddr = proc.ipAddr()

Returns host IP address as an integer number.

Class Sequence

Python wrapper for pdsdata/xtc/Sequence class.

Enum Type

This enum is an embedded type of Sequence class. Following enum members are defined currently:

Sequence.Type.Event
Sequence.Type.Occurrence
Sequence.Type.Marker

Construction

This class cannot be instantiated directly, it is instantiated by some other classes, e.g. by Dgram.seq property.

Method type()

Usage: type = seq.type()

Returns the type of this sequence, one of Sequence.Type.* values.

Method service()

Usage: svc = seq.service()

Returns the transition type as object of xtc.TransitionId type.

Method isExtended()

Usage: val = seq.isExtended()

Returns True for extended sequence.

Method isEvent()

Usage: val = seq.isEvent()

Returns True for event sequence.

Method clock()

Usage: clock = seq.clock()

Returns clock value for sequence as an object of xtc.ClockTime type.

Method stamp()

Usage: stamp = seq.stamp()

Returns timestamp value for sequence as an object of xtc.TimeStamp type.

Class TimeStamp

Python wrapper for pdsdata/xtc/TimeStamp class. In addition to methods described here the class also defines __hash__ and __cmp__ methods based on the content of the object and can be used as a key in the dictionaries.

Construction

Usage: ts = xtc.TimeStamp(ticks, fiducials, vector, [control])

Creates new instance of this type. All arguments are of integer type and have the same meaning as in corresponding C++ constructor.

Method ticks()

Usage: ticks = ts.ticks()

Returns the ticks value as integer number.

Method fiducials()

Usage: fiducials = ts.fiducials()

Returns the fiducials value as integer number.

Method control()

Usage: control = ts.control()

Returns the control value as integer number.

Method vector()

Usage: vector = ts.vector()

Returns the vector value as integer number.

Class TransitionId

Python wrapper for pdsdata/xtc/TransitionId class. C++ class does not define any data members or methods, it only defines single enum type. C++ cannot be instantiated in any meaningful way. Python class in addition to defining corresponding enum constants can also be instantiated, the instances are regular integer numbers with additional printing enhancements.

Enum Value

Unlike other enum types which create separate new type inside original Python type, the enums in TransitionId class are defined directly in the class. Known enums:

TransitionId.
TransitionId.Unknown
TransitionId.Reset
TransitionId.Map
TransitionId.Unmap
TransitionId.Configure
TransitionId.Unconfigure
TransitionId.BeginRun
TransitionId.EndRun
TransitionId.BeginCalibCycle
TransitionId.EndCalibCycle
TransitionId.Enable
TransitionId.Disable
TransitionId.L1Accept
TransitionId.NumberOf

Construction

Usage: transId = xtc.TransitionId(number)

Arguments:

number – any of the above enums can be used

Method str

Usage: s = str(transId)

Returns a name of the corresponding enum.

Method repr

Usage: s = repr(transId)

Returns a string in the form "<TransitionId(num):name>" where num and name are the value and the name of the corresponding enum.

Page tree

Pyana Reference Manual

Package pyana

Module event

Class Event

Construction

Method seq()

Method getTime()

Method find()

Method findFirst()

Method getAcqConfig()

Method getOpal1kConfig()

Method getAcqValue()

Method getPnCcdValue()

Method getFeeGasDet()

Method getPhaseCavity()

Method getEBeam()

Class Env

Construction

Method jobName()

Method hmgr()

Method mkfile()

Method epicsStore()

Method update()

Method updateEpics()

Method updateConfig()

Method getAcqConfig()

Method getPnCCDConfig()

Method getOpal1kConfig()

Method result()

Class EpicsStore

Construction

Method update()

Method value()

Module histo

Class HistoMgrRoot

Construction

Method h1d()

Method h1f()

Method h1i()

Method h2d()

Method h2f()

Method h2i()

Method prof()

Method prof2d()

Function HistoMgr()

Module _pdsdata

Module _pdsdata.xtc

Class BldInfo

Enum Type

Construction

Method level()

Method log()

Method phy()

Method processId()

Method type()

Class ClockTime

Construction

Method seconds()

Method nanoseconds()

Class Damage

Enum Value

Enum Mask

Construction

Method value()

Method hasDamage()

Class DetInfo

Enum Detector

Enum Device

Construction

Method level()

Method log()

Method phy()

Method processId()

Method detector()

Method device()

Method detId()

Method devId()

Class Dgram

Construction

Method str

Method repr

Method str

Method repr