HOWTO Access Calibration Constants from JANA/DANA

From GlueXWiki
Jump to: navigation, search

Introduction

Here I am starting a page that will hopefully get updated as the calibration system is developed. Right now, the intention is to document the new features in JANA that provide a standard API for accessing calibration constants. Note that the API should support full database access across a network or even through web objects. Right now though, only a local file system mechanism is provided. Factory writers won't have to change any code when these other methods are finally implemented.

Accessing calibration constants from within a factory

Calibration constants can be obtained using one of four methods in JEventLoop. All are named GetCalib and are distinguished only by the data type of their second argument. The formats of the methods are:


// Get 1-D array of values indexed by name
bool GetCalib(string namepath, map<string, T> &vals)
 
// Get  1-D array of values indexed by row
bool GetCalib(string namepath, vector<T> &vals)

// Get 2-D table of values indexed by row and name
bool GetCalib(string namepath, vector< map<string, T> > &vals)

// Get 2-D table of values indexed by row and column
bool GetCalib(string namepath, vector< vector<T> > &vals)

All methods are templated. The "T" represents the data type you wish to have the values converted to when they are copied into your container. This should be one of int, float, double, or string. The "namepath" string specifies which constants you want. This should be a heirarchical, forward-slash separated list starting with the detector system name and ending with the name of the constants themselves.

The first method returns an array of values in an STL map container. This is appropriate for values best indexed by name. For example, if the constants were the result of a Gaussian fit, you might name them "mean" and "sigma". These names(keys) would be stored with the constants in the database. One could also use detector id values for the keys.

The second method copies the values into an STL vector container. This is appropriate for values that are best indexed by position in the array. For example, pedestal values for all of the channels of a calorimeter.

The third and fourth methods are similar to the first and second, only they are meant for reading in tables of data instead of arrays.

Example 1

In this example a set of 3 values representing a timewalk correction function for the FDC are retrieved. They are copied into data members of the class for use later in the evnt(...) method.


... in factory class definition ...

double slope, offset, exponent; 


... in brun() method ...

map<string, double> twpars;
loop->GetCalib("FDC/driftvelocity/timewalk_parameters", twpars);

slope    = twpars["slope"];
offset   = twpars["offset"];
exponent = twpars["exponent"];

Example 2

In this example a set of pedestal values are read in and stored in the vector peds.


... in factory class definition ...

vector<int> peds;


... in brun() method ...

loop->GetCalib("FCAL/pedestals", peds);


... in evnt() method ...

hit->ADC -= peds[hit->id];


Specifying the location and set of calibration constants

The location of the constants is specified using the JANA_CALIB_URL environment variable. Since the only mechanism currently implemented for storing the constants is through ascii files, this should start with "file://". For example, if I have my constants stored in the directory /home/davidl/HallD/calib, then I would set my JANA_CALIB_URL to:

file:///home/davidl/HallD/calib

Note that since this is a full path, it starts with a "/" thus, the 3 slashes before "home".

For the above example, the constants should be stored in the file /home/davidl/HallD/calib/FDC/driftvelocity/timewalk_parameters.

Format of ASCII files

For the calibration constants stored in flat files, the format is simple ASCII. Lines beginning with a "#" and empty lines are ignored. Files may optionally include labels or "keys" for the parameters they hold. These are useful for indexing the values by name in the code or simply for documenting what the constants are within the file.



Example file 1: Simple 1-D array without keys. Six values will be read from this file and will be indexed by 0-5 if read into a vector or by the strings "0", "1", "2", ... if read into a map.

# This line is a comment and will be ignored
37
43
56
# This line will also be ignored. 
22
63
38



Example file 2: Simple 1-D array with keys. Six values will be read from this file and will be indexed by 0-5 if read into a vector or by the strings "mean1", "sigma1", "offset1", ... if read into a map. Note that this and Example 1 will give the same results when read into a vector. This example, however, is better documented by the presence of the keys.

# This line is a comment and will be ignored
mean1   37
sigma1  43
offset1 56
# This line will also be ignored. 
mean2   22
sigma2  63
offset2 38



Example file 3: Table with keys. In order to specify keys in a table, one uses the special "#%" syntax. When read into a vector<map<string,T>>, the white-space-separated values on the #% line are used to index the map part. NOTE: When reading into a vector, one should NOT use #% and should just use # so that the keys are ignored. The reason is that if the keys are found, they won't be automatically generated and the result will be a vector quietly reordered by the key name into alphabetical order.

#% x z      bx bz     nx        nz
0 210.82 0 -2.1816 -0.328271 0.000871416
0 213.36 0 -2.1829 -0.329189 -0.000873593
0 215.9 0 -2.1842 -0.329705 -0.00100867
0 218.44 0 -2.1855 -0.329103 0.00163991
0 220.98 0 -2.1868 -0.328649 0.00188895
0 223.52 0 -2.1882 -0.328796 0.00165464
...