The Mapmanager provides a set of subroutine calls and programs which provide information from a database file according to a well defined prescription. Specifically, a piece of information is requested for a specific run-number; if the information exists in the database for that run number, the information is provided. If the database has no entry for that particular run number, however, it looks for a database entry in preceding run numbers until it finds one, and then returns that entry.
All run dependent quantities needed to correctly interpret the data should be placed into the map database. In this sense the map database is used to control the processing of a given data set. Typically, each reconstruction package (CC, EC etc...) provides a routine to initialize itself for a given run number. These routines contain calls to the mapmanager database. The master map database files are located in the /group/clas/parms/Maps area on the jlab Common Unix Environment(CUE) machines. A single environment variable, CLAS_PARMS provides the location for the parms area in all analysis packages. Knowledge of what set of map database files were used to analyze a given data file is critical to a repeatable and documented analysis of the data.
Mapmanager database files stored in the CLAS_PARMS/Maps area have the .map file extension. Because the .map files are binary files and are not directly human readable, a collection of command line operated UNIX utilities have been developed to allow one to interact with the map database files. These utilities allow one to determine the parameters stored in a database file, extract the contents, create new map files, create new database entries and fill database files. Two of these utilities, scan_map and print_map, are particularly useful when assessing the quality of calibrations.
The scan_map utility allows one to determine which database entries are stored in a map file and can print a time line of when a particular database item has been updated. The usage for scan_map is shown below:
Usage: scan_map [-t][-h] < map >
- lists all items and subsystems in map file
-t Draw a timeline for each item
-h Print this message
By default, scan_map lists which database entries are contained within the map file. scan_map also has two options, -h which prints the usage and -t. The -t option prints a timeline for each database entry contained within the map file. An example of the use of scan_map with the -t option is shown below:
jlabs2>scan_map $CLAS_PARMS/Maps/GEOMETRY.map -t
Map: /group/clas/parms/Maps/GEOMETRY.map
Subsystem: beam, nitems: 1
Item: position, length: 3, type: float, narray:17
INF <- 17746 <- 17591 <- 17395 <- 17233 <- 17135
<- 17094 <- 16941 <- 16833 <- 16634 <- 16506 <- 16288
<- 16186 <- 16152 <- 11000 <- 8400
<- 7400 <- 1 <- UNDEF
etc...
Listed are the various database entries stored in the GEOMETRY.map file. Each entry has two keys, the subsystem name and the item name. In the example shown, the map contains an entry with the subsystem tag beam and item name position. This beam position variable is stored in the map as an array of three floating point numbers. The narray variable confirms that this map entry has been updated seventeen times. The rest of the output is a time line of the run numbers that have been updated.
The print_map utility allows one to track the changes in a calibration constant over time. The usage for print_map is shown below:
Usage: print_map -m <map> -s <subsystem> -i <item>
print to stdout an array element from the map as a function of time
example:
print_map -m test.map -s testsub -i testitem -e 0
-m <mapfile> Map file
-s <subsys.> Subsystem name
-i <item> Subsystem name
-e <#> element number to print starting from zero
-n <#> number of elements to print (def. = 1)
-u <#> upper limit run number (def. = 99999999)
-l <#> lower limit run number (def. = 0)
One often uses this command to examine how rapidly a particular calibration constant is changing with time. If a calibration constant changes too quickly between updates, it may indicate that the constant must be updated more frequently. An example of the use of this command to examine the pedestal values for the time-of-flight system is shown below:
jlabs2>print_map -m $CLAS_PARMS/Maps/SC_CALIBRATIONS.map -s pedestals
-i left
18822 366.000000
18791 365.000000
18022 366.000000
17841 367.000000
16082 365.000000
16060 365.000000
15968 360.464996
14000 362.000000
12778 365.000000
etc...
In the first column is printed the run number and in the second column is printed the value of the first element of the array containing the mean value of the time-of-flight counter pedestals. The output format of this program (ASCII) can easily be used as input to a plotting program or a spreadsheet.
The mapmanager source code is located in packages/Map. The source for command line operated UNIX utilities is located in packages/utilities/maputil. Additional documentation for the map and its UNIX utilities is available on the off-line web pages.