Quick start guide

For RTT users is here. For all the others - please read carefully the text below.

Installation

List of supported (and tested) web browsers:

• Mozilla SeaMonkey
• Mozilla Firefox 2
• Opera 9
• Safari
• MSIE7 (also partially MSIE6)

The original package has been split recently into two packages, server and "client-side" Python script. The server-side package can be found at offline/Tools/DCubeServer, whereas the client-side python script is located at offline/Tools/DCubeClient.

Installing "server-side"

The server-side package ( offline/Tools/DCubeServer) consists two PHP files, one JS file , one CSS file and a bunch of gif images. After checking out the sources from Atlas CVS you should copy all subdirectory server somewhere on the web-browsable area. The directory structure on server-side should follow the structure:

• . (dot)
  • dcube.js.php ( JavaScript functions)
  • dcube.php (PHP classes)
  • rw.php (PHP class to color stdout)
  • preLoading.js (additional JavaScript file)
• css
  • dcube.css.php (cascade style sheet)
• images (icons, logos, check marks etc.)
  • favicon.gif
  • green.gif
  • red.gif
  • tdirectory_c.gif
  • tdirectory_o.gif
  • th1.gif
  • th2.gif
  • valid-css-blue.png
  • valid-html401-blue.png
  • yellow.gif

---

NEVER AND EVER CHANGE ABOVE FILE/DIRECTORIES STRUCTURE, without that DCube won't work.

---

Installing "client-side"

Just checkout from CVS package offline/Tools/DCubeClient. The python dcube.py script can be found under ./python subdirectory of the package.

As DCubeClient is a part of AtlasCore project, it is complied and installed by NICOS in every Atlas project release, so you don't have to checkout it from CVS to run. Just setup Atlas environment using cmt and dcube.py will be somewhere in your $PATH waiting to serve you.

Configuration

You don't have to care about shell environment to use DCube. It will work in standard shell set up by cmt.

Running

How it works?

Options and switches explained...

The usage of DCube, when invoked for the very first time, looks to be very complicated, but (I hope) you have to run it few times.

[lxplus240] ~/testarea % dcube.py --help
Usage: dcube.py [options] [args] [MONITORED.root]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -r REFERENCE, --reference=REFERENCE
                        reference root file
  -x OUTPUTXML, --xml=OUTPUTXML
                        XML output file
  -c CONFIGXML, --config=CONFIGXML
                        XML configuration file
  -l LOGNAME, --logname=LOGNAME
                        log file [default ./dcube.log]
  -t, --tests           statistics test to perform [default ['KS']]
  -f PFAIL, --pfail=PFAIL
                        p-value limit for test failure [default 0.75]
  -w PWARN, --pwarn=PWARN
                        p-value limit for test warning [default 0.95]
  -d YYYY-MM-DD, --date=YYYY-MM-DD
                        date of run in ISO format [default 2008-11-17]
  -s DCUBESERVER, --server=DCUBESERVER
                        path to DCubeServer
  --branch=BRANCH       branch name [default *]
  --cmtconfig=CMTCONFIG
                        CMTCONFIG name [default *]
  --install=INSTALL     install name [default *]
  --project=PROJECT     project name [default *]
  --jobId=JOBID         job identification name [default *]
  -g, --generate        trigger for configuration file generation [default
                        off]
  -p, --plots           trigger for histograms plots generation [default off]
  -b                    batch mode for PyROOT [always on]

Pretty much CLI options, huh? But don't be afraid. I'll try to explain their meanings right now.

Options

-r, --ref REFERENCE.root

sets the path (relative or absolute) to the root file with reference histograms, e.g.

-r /afs/cern.ch/user/g/gonzo/myRef.root

or

--ref ../../../myRef.root

-t, --tests TESTS

sets the list of statistics tests to perform on monitored and referenced histograms. The list of tests should be typed one by one, e.g.

-t KS bbb chi2

Allowed acronyms are: KS for Kolmogorov-Smirnov test, chi2 for Person's χ² test and bbb for "bin-by-bin" test, where p-value is counted using Equation:

Also you can set all tests at once using all keyword.

--branch BRANCH

This switch sets the branch name for your dcube run. The argument BRANCH should be a string with valid Atlas branch name (i.e. bugfix, dev, devval etc.) . The default value is * (any).

--install INSTALL

This switch sets the installation of Atlas software that should bu used for testing. There are only two possible values: build if you want to test afs installation and kit for kit installation. The default value is * (any).

--cmtconfig CMTCONFIG

This switch sets the binary version for your test. The argument should be just valid CMTCONFIG value, as set by cmt. The default value is * (any).

--project PROJECT

This switch sets the Atlas project name aganist which you want to test. The argument should be a valid Atlas project name (i.e. AtlasProduction, AtlasTier0 etc.). The default value is * (any).

--jobId JOBID

This switch sets the test or job id for your test. As jobID hasn't been defined yet inside Atlas test frameworks, this option gives you one "degree of freedom" for your test name and its value depends only from your imagination. The default value is * (any).

-x, --xml OUTPUT.xml

sets the name of output XML file, which is then taken as an input to the DCubeServer. Notice that DCubeClient sets the work directory, where all the output files are stored to be the same as the directory of the OUTPUT.xml file. This directory should exist BEFORE you try to run dcube.py.

-c, --config CONFIG.xml

sets the name of DCube XML configuration file to use.

-l, --log LOGNAME.log

sets the name of DCubeClient log file, of not set, the default one (dcube.log) will be used.

-f, --pfail VALUE and -w, -pwarn VALUE

are setting the limits for marking failing and warning for the statistic tests based on test p-value. The VALUE of course should be a number (and value for pwarn should be greater than pfail...). If those arguments are absent the default one (0.7 for pfail and 0.9 for pwarn respectively) are used.

-d, --date YYYY-MM-DD

sets the date, which you want to display on the web-page (if absent, present day will be taken). Should I really explain the format of date (YYYY-MM-DD)?

-s, --php DCUBE-SERVER-PATH

sets the path (relative from your output directory!) to the DCubeServer installation directory (where you can find dcube.php file). When this option is used, dcube.py together with output XML file will create two ready-to-browse PHP files (OUTPUT.php and dcubelog.php), which would eventually display the DCube results on the web. If the switch is absent, producing of PHP files is switched off and you should prepare such files by your own... The minimalistic example is presented below:

<?php
$where = "path-to-DCubeServer-installation";
set_include_path($where);
require "dcube.php";
$xml_file = "OUTPUT.xml";
$log_file = "OUTPUT.log";
$dcube = new dcube( $xml_file, $log_file, $where );
?>   

Switches

-g, --generate

triggers generations of scratch configuration file.

-p, --plots

flag to indicate creation of png files. By default switched off.

-u, --usage and -v, --version

prints out help information or my name and exits.

Example session

If you want to use DCube by your own, please notice, that all below commands should be invoked in the web-server hosted area (e.g. in your ~/public_html directory). Also remember to setup Atlas env scripts.

Let's say you have downloaded Tools/DCubeServer and installed it under ~/public_html directory (e.g. in ~/public_html/Tools/DCubeServer/server). We are also assuming you want to hold your DCube output over there, e.g. in directory ~/public_html/dcube.

Generation of configuration XML file

Step 1. Scratch config

Generate yourself scratch configuration file using command syntax like in example below:

[lxplus999 ] > dcube.py -g  r REFERENCE.root [-c CONFIGFILENAME.xml]  [-f NUM] [-w NUM] [-t TESTS] [--branch BRANCH] [--install INSTALL] [--cmtconfig CMTCONFIG] [--project PROJECT] [--jobId JOBID]

where:

• -g switch to trigger generation of configuration file
• -c CONFIGFILEANEM.xml name of the configuration file
• -r REFERENCE.root name of the reference root file
• -f NUM presetting the p-value limit for marking stats test failure (NUM ∈ [0,1] )
• -w NUM presetting the p-value limit for marking stats test warning (NUM ∈ [0,1] )
• -t TESTS comma separated list of stats tests to be run; TESTS ∈ [ KS, chi2, =bbb=] , where:
  • KS Kolmogorov-Smirnov test
  • chi2 Person's test
  • bbb bin-by-bin test
  • meany avg effective mean y (for TProfiles only)

This file could keep configuration for different instances of dcube tests as long as one of BRANCH, INSTALL, CMTCONFIG, PROJECT or JOBID is different.

So in our example the simplest invoking of would be:

[lxplus999 ] > mkdir -p ~/public_html/dcube; cd ~/public_html/dcube 
[lxplus999 ] > dcube.py -g -c my_dcube_config.xml -r path/to/reference.root

Step 2. Tweak it!

Open configuration file in your favorite editor (emacs? XMLSpear? XMLEdit? this list is endless, almost all today editors support XML) and chanage whatever you want. Follow the comments inside this file and DON'T FORGET TO REMOVE ALL UNNECESSARY ENTRIES FOR HISTOGRAMS YOU SUPPOSE YOU WILL NEVER CHECK, e.g. histograms produced by someone else's algorithms in Athena. The example configuration file:

<?xml version="1.0" ?>
<!--
 DCube configuration XML file = dcube_config.xml
 auto-generated using DCube 4.66920 by Krzysztof Daniel Ciba (Krzysztof.Ciba@NOSPAMagh.edu.pl)
 on Thu, 16 Oct 2008 13:20:37 CEST
 from Root reference file: reference.root
 Statistics tests:
 "['KS', 'bbb', 'chi2']"
 Legend:
 * KS   - Kolmogorov-Smirnov test (default)
 * chi2 - chi2 test
 * bbb  - bin-by-bin comparision
 * all  - all above tests
 Tweaks:
 [1] remove or comment out (using HTML comments tags) histograms not relevant
     to your analysis
 [2] provide a new content to "ref_desc" and "mon_desc" tags to something
     more meaningful
 [3] and of course feel free to change attribute "tests" in each "hist" tag
 [4] limits of p-value warning and failure can be set by changing attributes
     in <plimit> tag
 [5] if you want to make plots FOR EVERY histogram in your monitored file
     change attribute "inclusive" in <mode> tag to "true"
-->
<dcube_client_config>
 <dcube branch="dev" cmtconfig="*" install="*" jobId="*" project="*">
  <!--
  ###################################################
  DCubeClient for:
  [1] branch: dev
  [2] install: *
  [3] cmtconfig: *
  [4] project: *
  [5] jobId: *
  [6] reference root file: /afs/cern.ch/user/c/cibak/scratch1/dcube/runtest/reference.root
  [7] p-values limits FAIL = 0.750000 WARN = 0.950000
  ###################################################
-->
  <reference file="/afs/cern.ch/user/c/cibak/scratch1/dcube/runtest/reference.root"/>
  <ref_desc>
   PUT YOUR REFERENCE DESCRIPTION HERE
  </ref_desc>
  <test_desc>
   PUT YOUR TEST DESCRIPTION HERE
  </test_desc>
  <plimit fail="0.75" warn="0.95"/>
  <TDirectory name="/">
   ....
 </dcube>
<dcube branch="*" cmtconfig="*" install="*" jobId="*" project="*">
  <!--
  ###################################################
  DCubeClient for:
  [1] branch: *
  [2] install: *
  [3] cmtconfig: *
  [4] project: *
  [5] jobId: *
  [6] reference root file: /afs/cern.ch/user/c/cibak/scratch1/dcube/runtest/reference1.root
  [7] p-values limits FAIL = 0.750000 WARN = 0.950000
  ###################################################
-->
 .... 
 </dcube>
</dcube_client_config>

BTW if you were using elder version of DCubeClient (DCubeClient-00-00-17) you don't have to recreate your configuration files. There is a special script inside the new version of DCubeClient dcubeConvert.py, which does the transformation between old and new configuration formats for you. The usage is straight forward:

[lxplus999] ~ % dcubeConvert.py
Usage: $sh> dcubeConvert.py OLDCONFIG.XML [REFERENCE.root] [NEWCONFIG.XML]

It will create for you configuration file for default test environment (BRANCH = * , INSTALL = *, CMTCONFIG = *, PROJECT = * , JOBID = *).

Up, up and away! (obtaining the results)

Run dcube.py once again using syntax:

[lxplus999 ] > dcube.py  -c CONFIGFILENAME.xml  [--branch BRANCH] [--install INSTALL] [--cmtconfig CMTCONFIG] [--project PROJECT] [--jobId  JOBID]  [-s path/to/DCubeServer] MONITORED.root

e.g.:

[lxplus999 ] > dcube.py -c my_dcube_config.xml -r path/to/reference.root -s ../Tools/DCubeSever/server path/to/monitored.root

Invoking this command ends with creation of xml output file (monitored.root.dcube.xml), subdirectory plots with bunch of png images and two php files dcubelog.php and monitored.root.dcube.php

Now open in the web browser URL: http://server.that.host.your.public.html/~yourloginname/dcube/monitored.root.dcube.php.

Understanding UI

Header - basic information

On top of the page the header is displayed, which shows whatever you put to the and inside DCube configuration file plus some additional information (like file locations etc.).

Log viewer

Inside header there are two links to display DCube output log files, one which serves you plain/text and another text/html. If you click on as HTML link, it will display color log file:

Static and floating legend

Just below header you can find a legend, which displays the color coding for marking the test failure, warning and success.

By clicking somewhere inside above legend you can show/hide floating legend, which will be displayed at the bottom of the web page:

Panes

The web page has four different panes for presenting the results:

• Normal View which presents the root file structure
• Plots View which shows all plots in a customizable gallery
• Summary View which displays DCubeClient run status, summary table and spotted errors
• Settings View which holds form to personalize page look

Clicking on pane tab will show pane content from above list.

Normal View

The Normal View shows the content of the monitored root file, color-coded results from statistic tests and status from DQMF and DCube processing. In the row with root TDirectory name there is also the summary of success/warn and failing tests for histograms inside.

Clicking on the directory row expands tha main table and shows the histograms in it. The p-values for each performed test is shown in columns 2 (KS), 3(χ²) and 4("bin-by-bin").

Histogram view

By clicking on the histogram row you trigger to display basis statistics and plots:

• basic statistics:
  

• histogram plots:
  

By clicking on buttons above plots you can display "normal" and "difference" plot (for 2D histograms also projections in X and Y).

Plots gallery

The Plots View shows all plots created by DCubeClient grouped in galleries.

It has navigation buttons on top and bottom that allow to switch between galleries.

Summary View

The Summary View contains DCubeClient overall status, summary table for statistics tests and list of errors and warnings spotted during processing.

Settings View

There is a form on Settings View that allows you to change the default DCubeServer web page appearance:

You can select the number of plots in one gallery in Plots View or change the pane that would be selected when you open DCubeServer web page.

HOWTO

Produce plot with logarithmic scale on X,Y or Z axis? (DCubeClient version DCubeClient-00-00-22 or higher)

This can be done by setting plotopts attribute in hist1D, hist2D or graph tags in DCube configuration file, e.g.:

<hist1D name="diff TH1D" plotopts="logy" tests="KS,bbb,chi2" type="TH1D"/>

A valid value for plotopts attribute is a semicolon separated list of strings logx, logy or logz , where logA sets the logarithmic scale on axis A (in above example Y axis will be logarithmic).

Plot normalized histograms? (DCubeClient version DCubeClient-00-00-22 or higher)

This can be done by extending hist1D, hist2D or graph tags by string norm, e.g.:

<hist1D name="diff TH1D" plotopts="logy;norm" tests="KS,bbb,chi2" type="TH1D"/>

Troubleshooting

Memory limit

---

If you can see the message like this:

Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 10159613 bytes) in dcube.php on line 625

please, put to your output php file line like this:

ini_set( "memory_limit" , "48M");

(notice , that you can adjust the value of memory_limit to match your requirements).

If above trick didn't solve your problem, put to the output directory .htaccess file with lines:

<FilesMatch "\.(php|html?)$">
php_value memory_limit 48M
</FilesMatch>

In those tricks haven't worked, contact your ISP and ask to change memory_limit value in global php.ini file.

---

"Buggy" root 5.16

If you plan to run DCube for some huge root file, e.g. with a hundreds of histograms, please switch to the newer root version (at least 5.17/03). The previous are "buggy".

Links

• DCube API for program lawyers (Doxygen generated documentation)
• DCube test page
• DCube in RTT

---

-- KrzysztofCiba - 24 Oct 2008 -- KrzysztofCiba - 18 Sep 2007 -- KrzysztofCiba - 21 Jan 2009