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.
• PSAna ... C++-based analysis framework, still in the design phase.

The last two aim to provide a general framework with built-in tools useful for data analysis. Currently only myana and pyana are usable for analysis. This document will cover myana only, since pyana has it's own documentation.

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.

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.

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

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:

        This is the "user analysis module". It reads through the xtc sequencially, and records
        the information according to user choice. You can't access a given event (shot) randomly,
        not until you've made a first pass through all the events and stored the information in
        your format of choice. This module contain only the following functions:

         beginjob    ...    called at the beginning of an analysis job. E.g. book histograms here.
         beginrun    ...    called at the beginning of a run (the analysis job might analyze several runs)
         begincalib  ...    called for each calibration cycle

         event       ...    This is where you fetch information about each event (shot).

         endcalib    ...
         endrun      ...
         endjob      ...

         The example here fetches data from devices for each event and writes it to a root histogram.
         You may want to store the information in e.g. a root ntuple for further processing. Or to some
         other format that you'd like to work with (ascii file, ... ).

main.hh,cc:

All control and utility functions are defined in these files. The main() function is executed first,
 but after all other functions have been read. It calls the follwing function which controls the
 analysis:
    anafile(xtcname, maxevt, skip, iDebugLevel);
 This iterates through the xtc file, keeps track of all the datagrams in it, and makes sure to
 execute your beginjob() and event() functions and any others you might have implemented in your
 myana.cc file.

 All the functionality needed to get data from the xtc file is defined in main and in the files
 it includes (all in the package pdsdata (PDS == photon data system)). You get a list of all the
 available functions by looking at main.hh (implementations are in main.cc).

 Here are a few lines of explanation for *a few of* the functions defined in main:

 Enums:
 These define number mapping for each detector.  E.g. AcqDetector::AmoIms is equivalent to
 the constant 0. 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);