AUTHOR: Edmund WIDL CONTACT: Edmund.Erich.Widl@cern.ch

Overview

Installation

Using the Histogramer

File-Menu

Save Histogram To File

Save Histogram

Quit

New Query-Button

Draw-Button

Fit-Button

Save As-Button

Plot Non-Positive Values

Select Query

Select Draw-Option

Select Fit-Function

Select Number of Bins

User-defined Queries

Query-syntax

1D-histograms: HISTO1

1D-histograms filled with "vector-entries": HISTO1_VECTOR

2D-histograms: HISTO2

2D-histograms with a time-like x-axis: HISTO2_DATE and HISTO2_TDATE

2D-histograms filled with "vector-entries": HISTO2_VECTOR

Profile-histograms: HISTO2_PROFILE

3D-histograms: HISTO3

Overview

visualDB is a program (using the libxml2 library and ROOT) that enables the user to histogram data from the CMS Tracker database via a graphical user interface. Therefore it sends a requests via the relay-server to the database, parses the resulting xml-file and draws the corresponding histogram. The user can choose among a variety of standard plots, but can additionally decide to plot a user-defined query. Since visualDB needs only the libxml2 library and ROOT, which are both available for a large variety of platforms, it can be easily compiled and run on most pc. The only drawback is the fact that ROOT doesn't support the GUI classes for Windows at the moment - maybe this will be possible in the future (releases higher than 3.05/05).

back to top of page

Installation

First make sure that both the libxml2 library (version 2.4.19 recommended) and ROOT (version 3.05/05 recommended) are installed and running. This can be checked by typing:
```
prompt% xml2-config --version
prompt% root-config --version
```
Download the source code: visualDB.tar.gz

Unpack the file:

prompt% gzip -dc visualDB.tar.gz | tar -xf -

Change the directory:
```
prompt% cd visualDB
```
Compile the source code:
```
prompt% make
```
To run the application type:
```
prompt% ./visualDB
```

NOTE: visualDB will look for SQL-files in a subdirectory called queries relative to the directory it has been started from by default and load them into the Select Query-drop-down-menu. The number of files found is then printed in the Query status-field. Nevertheless one can still select files from different directories via the <Select User-defined Query>-entry.

back to top of page

Using the Histogramer

File-Menu

Save Histogram To File:

Histograms can be saved to root-files which makes it possible to process them afterwards again. When clicking on this menu-entry a file-dialog will appear for creating a new or opening an existing file.

Save Histogram:

Save histogram to the root-file which previously has been opened via Save Histogram To File. If no file was chosen the histogram will be stored in db_data.root by default.

Quit:

Quit the program.

New Query-Button

Send the selected query-file to the relay-server and draw a histogram from the received data with the defined options (drawing options, user-defined number of bins, etc.).

Redraw-Button

Redraw an already existing histogram without sending a new request to the relay-server.

Fit-Button

Add a fit to the current drawn histogram. The fit-function can be chosen via the Select Fit-Function-drop-down-menu.

Save As-Button

Opens a file-dialog window for saving the current histogram as eps-, ps- or gif-file. Enter the whole filename including the desired extension !!!

Plot Non-Positive Values

Since it may happen that some values in a result are missing (joined requests), the parser sets them by default to -1000. In order to avoid such faulty data to disturb the statistcs of a histogram only positive values are drawn. To plot zero and negative values anyhow click on this checkbox.

Select Query

This drop-down-menu enables the user to choose among several plots. When selecting <Select User-defined Query> a filedialog opens and lets the user choose query-files that are not located in the subdirectory queries (see section User-defined Queries for details on user-defined queries).

Select Draw-Option

ROOT histograms can be drawn with different styles. In this drop-down-menu one can select on of the follwing options:

<Default>: The histogram gets drawn with a default option.

SCAT : By default standard 2D- and 3D-histograms are drawn as scatter-plots. For each cell a number of points proportional to the cell content is drawn. A maximum of 500 points per cell are drawn, otherwise all contents are normalized to 500.

BOX : By default, 2D-histograms with time-formatted x-axis are drawn as box-plots. For each cell a box is drawn with a surface proportional to the cell's contents.

COL : For each cell a box is drawn with a olor associated to the cell's content. In addition the color palette is drawn.

LEGO : In a lego plot, the cell contents are drawn as 3D boxes, with the height of the box proportional to the cell content.

Select Fit-Function

In this drop-down-menu the kind of fit-function that shall be applied to an existing histogram can be selected. Gaussian, Landau, exponential, linear (y=k*x) and polynomial (grade 0 - 9) fits are possible.

Select Number of Bins

When drawing a histogram the program automatically computes a more or less reasonable binning. In cases where this binning is not expedient the number of bins for each axis can be defined. To get the default binning again, set these values to zero.

back to top of page

User-defined Queries

Query-syntax

The syntax for user-defined queries is almost the same as for standard SQL-queries for the relay-server except the header needed by visualDB:
#histogram_type column1 column2 column3 "histogram_title"
<select>

actual SQL-query

</select>
where
histogram_type
defines the desired type of histogram to be created (HISTO1,HISTO1_VECTOR, HISTO2, HISTO2_DATE, HISTO2_TDATE, HISTO2_VECTOR, HISTO2_PROFILE, HISTO3).
ATTENTION: There should be no blank between the hash (#) and the type-declaration !!!
column1
defines which column of the result should be associated with the x-axis
column2
defines which column of the result should be associated with the y-axis
column3
defines which column of the result should be associated with the z-axis (must be 0 for 1D- and all kinds of 2D-histograms)
histogram_title
defines the title of the histogram
Except for the first line, all lines beginning with a hash (#) will be treated as comments.

NOTE: Since visualDB parses the axis-labels from the specified column-names from the query-result, one can change this labels by renaming these columns via the AS-command (see examples below). Additionally it is possible to use special characters (like greek or mathematical symbols) in the axis-labels via TLatex-expressions.

back to top of page

1D-histograms: HISTO1

Creates a standard 1D-histogram.

Example:

#HISTO1 2 0 0 "Depletion Voltages (IB2)"
<select db="prod">
   OBJECT_ID,
   V_DEPL_V AS "Depletion Voltage [V]"
 FROM
   CVTEST_1_SEN_
 WHERE
   OBJECT_ID LIKE '302_02'
   AND STATUS = 'reference'
</select>

1D-histograms filled with "vector-entries": HISTO1_VECTOR

Some records in the database are stored in so called "vectors", i.e., lines containig more than one entry (test series for instance). The entries of such vectors can be histogramed using this type of histogram.

Example:
#HISTO1_VECTOR 1 0 0 "Occurence of Capacitances"
<select db="prod">
   C_TOT AS "Capacity [pF]"
 FROM
   TSCV_1_SEN_
 WHERE
   OBJECT_ID LIKE '302_04'
   AND STATUS = 'reference'
</select>
back to top of page

2D-histograms: HISTO2

Creates a standard 2D-histogram (scatter-plot).

Example:

#HISTO2 1 2 0 "Depletion Voltage QTC vs. PQC"
<select db="prod">
   a.V_DEPL_V AS "Depletion Voltage QTC [V]",
   b.V_DEPL AS "Depletion Voltage PQC [V]"
 FROM
   CVTEST_1_SEN_ a,
   TSCV_1_SEN_ b
 WHERE
   a.OBJECT_ID = b.OBJECT_ID,
   AND a.STATUS = 'reference'
   AND b.STATUS = 'reference'
</select>

2D-histograms with a time-like x-axis: HISTO2_DATE and HISTO2_TDATE

This type of histogram allows to display either the production date of a sensor, calculated from the sensor's OBJECT_ID (type HISTO2_DATE), or a date extracted from a TDATE-entry (type HISTO2_TDATE) in the form "month/year" versus any other value in a 2-dimensional histogram. Thus the x-value (associated with the header-parameter column1) has to be the corresponding OBJECT_ID or TDATE.

Examples:
#HISTO2_DATE 2 1 0 "Depletion Voltage vs. Production Date for HPK"
<select db="prod">
   V_DEPL AS "Depletion Voltage [V]",
   OBJECT_ID AS "Production Date [month/year]"
 FROM
   TSCV_1_SEN_
 WHERE
   OBJECT_ID LIKE '3022%'
</select>
#HISTO2_TDATE 2 1 0 "Depletion Voltage vs. Date of Measurement for STM"
<select db="prod">
   V_DEPL AS "Depletion Voltage [V]",
   TDATE AS "Date [month/year]"
 FROM
   TSCV_1_SEN_
 WHERE
   OBJECT_ID LIKE '3021%'
</select>
back to top of page

2D-histograms filled with "vector-entries": HISTO2_VECTOR

Some records in the database are stored in so called "vectors", i.e., lines containig more than one entry (test series for instance). The entries of two such vectors can be histogramed against each other in a 2D-histogram using this type.

Example:
#HISTO2_VECTOR 1 2 0 "C-V test series"
<select db="prod">
   VOLTAGE AS "Voltage [V]",
   C_TOT AS "Total Capacity [pF]"
 FROM
   TSCV_1_SEN_
 WHERE
   OBJECT_ID LIKE '3022%'
   AND STATUS = 'reference'
</select>
back to top of page

Profile-histograms: HISTO2_PROFILE

Creates a so called profile-histogram, which in many cases can be an elegant replacement for 2D-histograms. Profile histograms display the mean value of Y and its RMS for each bin in X.

Example:
#HISTO2_PROFILE 1 2 0 "Depletion Voltages QTC vs. PQC"
<select db="prod">
   a.V_DEPL_V AS "Depletion Voltage QTC [V]",
   b.V_DEPL AS "Depletion Voltage PQC [V]"
 FROM
   CVTEST_1_SEN_ a,
   TSCV_1_SEN b
 WHERE
   a.OBJECT_ID = b.OBJECT_ID,
   AND a.STATUS = 'reference'
   AND b.STATUS = 'reference'
</select>
back to top of page

3D-histograms: HISTO3

Creates standard 3D histograms.

Example:

#HISTO3 2 1 3 "Test 3D-Histogram"
<select db="prod">
   a.V_DEPL_V AS " ",
   b.V_DEPL AS " ",
   b.C_TOT_DEPL AS " "
 FROM
   CVTEST_1_SEN_ a,
   TSCV_1_SEN b
 WHERE
   a.OBJECT_ID = b.OBJECT_ID
   AND a.STATUS = 'reference'
   AND b.STATUS = 'reference'
</select>

histogram_type	defines the desired type of histogram to be created (HISTO1,HISTO1_VECTOR, HISTO2, HISTO2_DATE, HISTO2_TDATE, HISTO2_VECTOR, HISTO2_PROFILE, HISTO3).
	ATTENTION: There should be no blank between the hash (#) and the type-declaration !!!
column1	defines which column of the result should be associated with the x-axis
column2	defines which column of the result should be associated with the y-axis
column3	defines which column of the result should be associated with the z-axis (must be 0 for 1D- and all kinds of 2D-histograms)
histogram_title	defines the title of the histogram

"visualDB" - A CMS Tracker DataBase Histograming Tool

Contents: