// Mainpage for Doxygen /** @mainpage package ModuleAnalysis * * @section intro Introduction * * A brief description on how to add code to the ModuleAnalysis package yourself * follows below. Please consult also * ModuleAnalysis documentation page * for using the package. *
*
    *
  1. General structure
    2. *
  2. How to call MA from another application
    3. *
  3. How to read additional data-types
    4. *
  4. How to add new plotting/analysis features  
    5. *
* *

General structure

 * * The program consists of three main parts: * * Other sub-classes are used from within these classes; a full list is available from the * links at the top of this page. * *

How to call MA from another application

 * *

Creating a TopWin object

* Recommended call for creating the TopWin main GUI * (TopWin *m_MAF should be a member of your control-GUI): * 
 * m_MAFwin = new TopWin(NULL,"MAFwin",0,TRUE);
 *
* The last argument being true indicates MA that it is controlled by another application; setting * this argument to FALSE will enable more user control function not desired for dependent-use of MA * and will shut down the entire QT application on exit. To open the panel just call * 
 * m_MAFwin->show();
 *
* *

Creating module items

* * A module item is created via the ModItem class; recommended call * (using the m_MAFwin pointer from above): * 
 * ModItem *module_item = new ModItem(m_MAFwin->ModuleList, [module name (const char*)]);
 *
* *

Adding data items to existing modules

* A data item should be a module sub-item and can be created via the ModItem class. * However, it is recommended to use the TopWin::DataToTree function: * 
 * ModItem *data_item = m_MAFwin->DataToTree(module_item,DATA)
 *
* where m_MAFwin and module_item are as above, and DATA is the pointer to a DatSet * object.
* Alternatively, you can have MA do all data loading for you, provided you want to read from a * TurboDAQ file: * 
 * ModItem *data_item = m_MAFwin->LoadData(module_item,filename, label,data_type); 
 *
* where filename is the full path of the file, label is the name under which the item * will appear in the tree-view of TopWin, and data_type is the type of data, * see FileTypes.h (items>100) or the list at the top of * TopWin.cpp. * *

How to read additional data-types

 *

Changes to the DatSet class

*

* Step 1
* The DatSet class can handle different data types as defined in the * FileTypes.h file. By convention, * values >100 are used as file types (otherwise it's considered a plot type, * see below). Define a new name and corresponding index for the new type * you want to use in there. *

*

* Step 2
* You have to create your own data reading routine, filling Root histograms as explained below, * and add it as function to the DatSet class. It should return an integer * containing a non-zero error code in case of problems. Having done so, go to the * constructor (the DatSet::DatSet(const char *name, const char *path, int type, int* rderr, DatSet* TOTCal, const char* cfgpath) version), look for the switch(type) part and add a case with * the type you defined in the beginning. In that case, add your new data reading routine. * The constructor argument path will provide an absolute path of the file to be read. * It expects rderr be filled with above error code.
* Data is typically stored in 2D root histograms if the data set contains * one value (or one avreage value) per pixel. So far, the private pointer * arrays *m_parmap[NPAR] is used for fit-output and the pointer array * *m_maps_2D[NRAW] for raw data (eg number of hits). Scan data (only 1D for now) * is stored in 1D histograms, one per pixel. A pointer **m_scanhi which points * to an array of 46060 TH1F histograms if needed (NULL otherwise) is private * DatSet member. Preferrably use one of those pointers to create new histograms which * will store the data.
* 1. Example for storing plain data (from DatSet::ReadBinData)
* Create a TH2F histogram and fill element of m_maps_2D array with pointer address: * 

 *  sprintf(htit,"rawmap%x",(int)this);
 *  m_maps_2D[HITS_HISTO] = new TH2F(htit,"Map of avg. hit data",NCOL*NCHIP/2,-.5,143.5,2*NROW,-.5,319.5);
 *
* ...later in the ascii reading loop: * 
 *  m_maps_2D[HITS_HISTO]->Fill(xval, yval, meas);
 *
* where you might want to use the DatSet::PixXY routine * (see DataStuff.h) * to convert from chip/column/row to histogram X-Y coordinates. *
* 2. Example for storing scan data (from ReadBinData):
* Create array of TH1F histograms and write pointer address into m_scanhi: * 
 *  if(scanno>1 && m_scanhi==NULL) m_scanhi = new TH1F*[NCHIP*NPIX];
 *
* somewhere in a 0<index<NCHIP*NPIX loop: * 
 *  m_scanhi[index] = new TH1F(htit,hname,scanno, scanmin, scanmax);
 *
* ...later in the ascii reading loop: * 
 *  bin = m_scanhi[PixIndex(chip,col,row)]->Fill(dac,meas);
 *
* using the DatSet::PixIndex routine * (see DataStuff.h) * to convert from chip/column/row to array-index. *

* Step 3
* To allow other routines to access your data stored in 2D histograms * you must add your data type to the * DatSet::GetMap(int chip, int type) routine, in the switch(type) list, * where type will be the data type defined in FileTypes.h. * 1D scan histograms are already accessible via the * DatSet::GetScanHi(int chip, int col, int row) function. *

* *

Changes to the TopWin class

* * The user action of reading data goes via the TopWin::TopWin * constructor. Add a line like * 
 *   m_fwin->AddType("Data type label","Filter (*.ext)",YOURNEWTYPE);
 *
* which calls the FileWin::AddType function. * It will add an according item in the file reading menu. "Data type label" is what * will show up in the type selection combo box of the file window, "Filter" should * have the indicated format, ie a description plus the extension in the format *.ext * in parentheses, and will be used in the browser (the type Any file (*.*) will be * added automatically).
* Finally you must * tell TopWin what type of action you want on the new data set type; see * bottom of next section for details. * *

How to add new plotting/analysis features

 * *

Changes to the RMain class

*

* Create a new (public) function in the RMain class. One of its arguments * must be of DatSet* type to allow hading over of the data. Tyhe DatSet functions * DatSet::GetMap(int chip, int type) or * DatSet::GetScanHi(int chip, int col, int row) will then allow to access * the actual data stored in 2D maps (1 bin per pixel) or 1D scan histograms (1 histo * per pixel). For existing data types, the following arguments can be used as type * in the DatSet::GetMap function (see FileTypes.h): *

* The existing canvas (pointer is stored in RMain::maincan) * should be used for plotting. * Call CheckCan() in the beginning to make sure the ROOT-canvas exists and is open. *

*

* TIP: If you just want simple plots of new data types, not * knowing the details of ROOT graphics, you can try * to use one of the already defined plotting routines (see * RootStuff.h): *

* Just add your type to the cases which call one of these functions in TopWin.cpp (see next * sub-section), the data type is retrieved in * these plot routines to get the right histogram with the DatSet::GetMap function. *

* *

Changes to the TopWin class

 *

* The various plot/analysis types are defined in the * FileTypes.h file. By convention, * values above zero and <100 are used as analysis types (otherwise it's considered a file type, * see above). Define a new name and corresponding index for the new type * you want to use in there. *

* The user action of plotting/analysing data goes via the TopWin main panel routine * TopWin::ModuleList_itemselected(ModItem* item) which is called upon * double-clicking items in the tree-view. Add your new plot type to the * switch(item->GetPID()) list to call above RMain function.
* Add your new type as case to the switch(type), where the ModItem class, ie a line like * 

 *  plotit = new ModItem(subi,"Brief description",did,PLOT-TYPE);
 *
* will create an according item in the TopWin tree-view. * Last not least, you have to add the new plot type to the corresponding data types. * It is done in the * TopWin::DataToTree(ModItem* item, DatSet *did) function. * Add your new type as case to the switch(type), where the ModItem class, ie a line like * 
 *  plotit = new ModItem(subi,"Brief description",did,PLOT-TYPE);
 *
* will create an according item in the TopWin tree-view. Make sure you add it to the * correct data-type case! *

* *
* General structure   * How to read additional data-types   * How to add new plotting/analysis features   * *
* @author Jörn Grosse-Knetter (Joern.Grosse-Knetter@uni-bonn.de): coordination * @author Jens Weingarten (weingart@physik.uni-bonn.de): system test related issues * */