myana user guide

This page is under construction.

Introduction

LCLS Data Analysis frameworks are under development, and currently three approaches are being used and/or developed:

• myana ... simple C++ code to read xtc file. Provided (and used) by the DAQ group. Will likely be expanded in support of new hardware etc., and more examples might be provided, but otherwise no big changes anticipated.
• pyana ... python-based analysis framework. Anticipate more tools and examples to appear for this one.
• PSAna ... C++-based analysis framework, still in the design phase.

Currently only myana and pyana are usable for analysis.

This document attempts to explain some of the names and functions found in the myana code as well as the structure of the data file (xtc) and how to extract useful information from it.

Disclaimer: There is no more complete or up-to-date documentation than the code itself, so regard this document as an introduction and a user guide, not a complete documentation.

How to set up your own myana executable is explained in the DAQ section "A Simple Online Analysis Example".

myana makes use of the pdsdata library to read the datagrams from the xtc file.

xtc

The data from all the LCLS experiments are stored in xtc (extended container) files. These files contain "datagrams" which are an object of some type (TypeId) with associated status (Damage), source (Src) and extent (size). It is not an indexed file and does not provide random access, and can only be read seqencially. Thus, the example way to read the file shown here makes use of 'myana', a C++ executable that reads through the whole file and picks out the requested information. You can make your own version of 'myana' to extract other information.

MyAna .... C++ program to extract information from xtc file

This example fetches data for each event and writes it to a root histogram and stores the histogram in a root file. You may want to store your data differently, e.g. one histogram for each event, or everything in a root ntuple for further processing. Or you can write some other format that you'd like to work with (ascii file, ... ).

myana.cc - example code to make a simple averaging histogram
myana_morefeatures.cc - example code that does a little more.
main.cc - defines the functions used by myana.cc

Here's a brief description of the functions of myana.cc and main.cc:

myana.hh,cc:

main.hh,cc:

anafile(xtcname, maxevt, skip, iDebugLevel);

All the functionality needed to get data from the xtc file is (or should be) defined in main.cc and in the files it includes (including the pdsdata library). Get an uppdated list of all the available functions by looking at main.hh (implementations are in main.cc).

The following contains a few lines of explanation for some of the functions defined in main. But first some general remarks:

• Most of the functions return 0 if it was a successful function call, any other number means it failed.
• Values are obtained through the arguments of the function calls. E.g. declare an array in your myana.cc, and getXXXValue(&myarray[0]) will fill the array for you.
• Enums: Several of the functions can be used to extract data from several of the detectors. Which detector is specified by an enum (named constant integers). You are encouraged to use the names instead of the numbers, in case the underlying order changes in a new version of the program.

 Configuration and L1Accept Data retrieval functions:

 Acquiris digitizer

 int getAcqConfig      (AcqDetector det, int& numChannels, int& numSamples, double& sampleInterval);

 --> fetches the configuration information for any of the Acquiris
     devices.  Checks that the detector has been used / has data, and
     tells you the number of channels used, number of samples
     collected and the sample interval.  This is typically done in the
     myana::beginjob() or myana::beginrun() functions.  Specify with
     enum which device you want information from, and supply a pointer
     to two integers and a double: numChannels, numSamples,
     sampleInterval.

 int getAcqValue   (AcqDetector det, int channel, double*& time, double*& voltage);
 int getAcqValue   (AcqDetector det, int channel, double*& time, double*& voltage, double& trigtime);

 --> fetches waveform data from any of the Acquiris devices: Specify
     with enum which device you want the information from, and an
     integer to store channel information, as well as pointers two
     arrays of doubles. These will be filled with time and voltage
     information, respectively. Optional: to also get the trigger
     time, you can supply a *double as a fifth argument.

      In the myana.cc example, we fetch data from the AmoITof device (AMO Ion Time-of-flight).
      Other Acquiris devices (see main.hh for an up-to-date list):
      AMO:
            AmoIms      - ion momentum spectrometer
            AmoGasdet   - gas detector (in the Front End Enclusure)
            AmoETof     - electron time-of-flight
            AmoMbes     - magnetic bottle electron spectrometer
            AmoVmiAcq   - (Vmi = Velocity mapping imaging)
            AmoBpsAcq   - (Bps = Beam position screen)
            Camp        - for the CAMP experimental setup
        SXR:
            SxrBeamlineAcq1
            SxrBeamlineAcq2
            SxrEndstationAcq1
            SxrEndstationAcq2

 Any particular hardware?

 int getFrameConfig   (FrameDetector det);

 -->  Checks that the xtc file has got data from this device.

 int getFrameValue(FrameDetector det, int& frameWidth, int& frameHeight, unsigned short*& image );

 --> fetches an image from the FrameDetector of your choice.
     Specify the detector (using an appropriate enum), give pointers to
                  int frame width, frame height and short imgage of the Camera::FrameV1.

  Other frame detectors:
  AMO:
      AmoVmi
      AmoBps1
      AmoBps2
  SXR:
      SxrBeamlineOpal1
      SxrBeamlineOpal2
      SxrEndstationOpal1
      SxrEndstationOpal2
      SxrFccd
   XPP:
      XppSb1PimCvd
      XppMonPimCvd
      XppSb3PimCvd
      XppSb4PimCvd

 ------------------------------------------------------------------------------------------------------
 Princeton camera
 ------------------------------------------------------------------------------------------------------

 int getPrincetonConfig(Pds::DetInfo::Detector det, int iDevId,
                        int& width, int& height, int& orgX, int& orgY, int& binX, int&binY);
 -->

 int getPrincetonValue(Pds::DetInfo::Detector det, int iDevId, unsigned short *& image);
 -->

 ------------------------------------------------------------------------------------------------------
 Ipimb detector
 ------------------------------------------------------------------------------------------------------
 int getIpimbConfig(Pds::DetInfo::Detector det, int iDevId);
 -->

 int getIpimbVolts(Pds::DetInfo::Detector det, int iDevId,
                   float &channel0, float &channel1, float &channel2, float &channel3);
 -->

 ------------------------------------------------------------------------------------------------------
 Encoder detector
 ------------------------------------------------------------------------------------------------------

  int getEncoderConfig   (Pds::DetInfo::Detector det, int iDevId);
  -->

  int getEncoderCount(Pds::DetInfo::Detector det, int iDevId, unsigned int& encoderCount);
  -->

 ------------------------------------------------------------------------------------------------------
 Other functions that do not require (or have) configuration
 ------------------------------------------------------------------------------------------------------

 int getFeeGasDet  (double* shotEnergy);
 --> Gives you the shot energy to the array shotEnergy[4]. This information is obtained from
     the Front End Enclosure Gas Detector.

 int getEBeam(double& charge, double& energy, double& posx, double& posy,
              double& angx, double& angy);
 int getEBeam(double& charge, double& energy, double& posx, double& posy,
              double& angx, double& angy, double& pkcurr);
  --> Gives electron beam values for each of these doubles. The measured charge of the beam (in nC),
      the measured energy of the beam (in MeV), the 2D position of the beam (in mm) away from the origin
      (nominal beam position), and 2D angular position (in mrad) off the assumed direction. and the
      pkcurr = current? in (Amps)

 int getPhaseCavity(double& fitTime1, double& fitTime2, double& charge1,  double& charge2);
 --> Gives you the phase cavity fit time (low and high?) and charges (before and after?).

 int getPnCcdValue (int deviceId, unsigned char*& image, int& width, int& height );

 int getEvrDataNumber();

 int getEvrData    ( int id, unsigned int& eventCode, unsigned int& fiducial, unsigned int& timeStamp );

 ------------------------------------------------------------------------------------------------------
 EPICS
 ------------------------------------------------------------------------------------------------------

 Get integers, floats, strings from any EPICS channel (PV = process variable)
 int getPvInt      (const char* pvName, int& value);
 int getPvFloat    (const char* pvName, float& value);
 int getPvString   (const char* pvName, char*& value);

 /*
  * Control data retrieval functions
  */
 int getControlPvNumber();
 int getControlPvName  ( int pvId, const char*& pvName, int& arrayIndex );
 int getControlValue   (const char* pvName, int arrayIndex, double& value );

 int getMonitorPvNumber();
 int getMonitorPvName  ( int pvId, const char*& pvName, int& arrayIndex );
 int getMonitorValue   (const char* pvName, int arrayIndex, double& hilimit, double& lolimit );

 /*
  * Advanced Interface
  */
 int   getEpicsPvNumber();
 int   getEpicsPvConfig( int iPvId, const char*& sPvName, int& iType, int& iNumElements );
 int   getEpicsPvValue ( int pvId, const void*& value, int& dbrype, struct tm& tmTimeStamp, int& nanoSec );

 void  fillConstFrac(double* t, double* v, unsigned numSamples, float baseline,
                    float thresh, TH1* hist);
 void  fillConstFrac(double* t, double* v, unsigned numSamples, float baseline,
                    float thresh, double* edge, int& n);

   main.

defines a class myLevelIter, which inherits from XtcIterator. A utility class to
   traverse the xtc file. It has several process memeber functions, depending on which detector
   is being used.

   The MAIN function is making an output root file with the same name as the input xtc file.
   You can control through the myana.cc file what gets stored in the root output file.
   The main function calls the function anafile for one xtc file or for a list of xtc files.
   anafile opens the xtc file, makes and XtcFileIterator object, and loops through all the
   datagrams in the file. Each datagram corresponds to one event?

   EPICS = Experimental Physics and Industrial Control System, used for control of
   hardware, and EPICS also outputs all kinds of hardware related values, like voltages
   and currents at all given times of data collection.
   Example to get the value from a given Epics channel (e.g. "SXR:EXP:MMS1.RBV") for a given event,
   within the event() function, do:
     // get one PV
     float value;
     fail = getPvFloat( "SXR:EXP:MMS1.RBV", value );
   This gives the value to your declared float 'value'.

   * Get encoder data for DetInfo::SxrBeamline device ID 0
   */
  unsigned int count;
  fail = getEncoderCount(DetInfo::SxrBeamline, 0, count);