Nicolas ARNAUD (narnaud_at_lal.in2p3.fr) File created: 2005/10/21 (NA) Last major update: 2006/04/21 (NA) Last update: 2006/06/30 (NA) --------------------------------------------------- This README file aims at describing the package DrcBackgroundMonitor which is used to produce daily plots monitoring the DIRC background. The production version of the package can be found in the /nfs/bbr-nfs03/det/drc/drc/BackgroundMonitor/ directory. Cron jobs (located in ~babardrc/CronJobs) are run daily to produce the new plots and to update the webpages which allow an easy access to them. * The cronjob dailyBkgMonitorCronJob produces plots for the last 3 shifts. It runs few minutes after 8 am to get information from the previous day, swing and owl (just ended) shifts. * The cronjob biWeeklyBkgMonitorCronJob produces plots for the last two weeks (the idea is to compare the last 7 days with the previous week). It runs few minutes after Midnight. It includes the plot included on the Friday's background report presented at the MDI and BaBar-PEP meetings. * Both cron jobs run on bbr-dev102. The command trscrontab -e allows to see/modify the cron jobs scheduled by a given user -- for instance babardrc if you're logged under this account. * Logfiles are overwritten daily in ~babardrc/CronJobs when the cron jobs are running. The webpages are linked to the central DIRC background monitoring webpage: BFROOT/www/Detector/DIRC/BackgroundMonitoring/index.html. * The link 'Daily Plots' points to the webpage where the more recent plots (daily and biweekly) are displayed. * Other links should be present on the webpage: / 'demo' showing a (frozen) example of how plots should look like; / 'list' compiling links to all recent plots; / 'Documentation' (= this file... Should always be the most recent version: check in the package and in CVS in case of doubt) / 'Bkg report plot' (= the plot shown every Friday at the background reports). A short description of the different plots can be found in the webpages. /nfs/bbr-nfs03/det/drc/drc/BackgroundMonitor/ contains the following directories Demo DrcBackgroundMonitor Html LumiScale Plots Root Standalone Test * Demo ---- One can find here the demo plots and webpage available from the background monitoring webpage. Do not remove these files unless you're sure of what you're doing! * DrcBackgroundMonitor -------------------- The code itself -- standalone package. See below for a detailed description of its contents. * Html ---- This directory contains two types of files: the html sources of the webpages (generated in php at the end of the cron jobs) and the gif pictures embedded in the webpages. Each ROOT macro usually produces two sets of (identical) plots: / postscript files stored in the Plots/ directory. The names of the files are _YYYY-MM-DD.ps => they are stored 'forever' and the date tag allows a simple identification of past plots. To save space, they are gzipped. / gif files produced from the ps files. Their names are generic and so they are overwritten each time the macro is executed. * LumiScale --------- This directory contains a single file, lumiScale.txt, which is regenerated each time a monitoring script gets executed. That code has been copied from Mike Kelsey's package producing similar plots for the DCH. The raw luminosity value (provided by PEP) needs to be corrected to reflect the reality. The correction factor is updated every few days or so by mutual agreement between PEP and BaBar RCs. The script queries some IR2 DB to find which correction factor was used at a given time. * Plots ----- This directory contains all the gzipped plots which have been generated by the macro. Its contents can be easily browsed by using the webpages automatically generated at the end of the cron jobs. * Root ---- This directory aims at storing some output files which are updated each time the corresponding macros are executed. So far it only contains two files (one ROOT and one text) which provide information on the estimated charges collected by the HV channels powering the 12 DIRC scalers. These quantities are certainly not 100% reliable by they should give an idea of the ageing of the PMTs. * Standalone ---------- In addition to the cron job-produced plots, one can create custom plots to look at backgrounds during a particular time period. One script creates 3 files (ps and gif formats) identified by a name defined by the user. These plots are stored in that directory. * Test ---- Place to test some macros. Probably not that useful... The DIRC-related background quantities are computed live on the IOCs drc-mon (for the scalers) and drc-soft (for all other background variables, including in particular the scaler rate ratios). The packages currently running in these IOCs can be found in the directories * /nfs/bbr-srv01/u1/babar/boot/apps/drc-mon * /nfs/bbr-srv01/u1/babar/boot/apps/drc-soft ---------------------------------------------------------------------------- DrcBackgroundMonitor in a nutshell ---------------------------------- DrcBackgroundMonitor is organized in a way similar to the IR2Lumi package which creates BaBar Operation plots and has been developped by Matthias Wittgen. I (Nicolas) tried to adapt this code for the DIRC background monitoring. ROOT macros are activated by scripts which first setup the job framework (environment variables, time range of the plots, particular tag to make the output files unique etc.). When needed, php macros update the html pages used to access the plots. All data are read out from the Ambient DB using the program OdcNtupleMaker (see BFROOT/www/Computing/Online/Databases/Ambient/OdcNtupleMaker.html for details). The classes defined in DrcBkg*.h handle all this stuff. The output of OdcNtupleMaker is a ROOT-tuple which contains the data for all variables defined in the .input file called by the class constructor. The perl script updateLumiScale.pl refreshes that the table of the luminosity correction factors: it should be called by all scripts. The ROOT macros are the .C files in the package. Most of them are very similar -- they have been developped using extensively copy/paste commands. The aim was to have a robust code working quickly, not to have a package following the most stringent coding rules... The structure is the following: a) Time offset definition ------------------------- //Define Time offset: //1999/01/01 @ 00:00 must be chosen // to synchronize the (corrected) ROOT-tuple time // with the timeStamps of lumiScale.txt // (time-dependent lumi correction factors) TDatime T0( 1999, 01, 01, 00, 00, 00 ); timeOffset = T0.Convert(); gStyle->SetTimeOffset( timeOffset ); This is needed for two reasons: * first, to take into account the 'time origin' for BaBar time; * second, to have ROOT writting correct dates on the x-axis labels. b) Read the lumi correction factor table ---------------------------------------- //Creating the lumi correction factor array LumiScale *lumiScale; char lumiScaleFileName[ 1024 ]; sprintf( lumiScaleFileName, "%s/lumiScale.txt", getenv( "LUMISCALE_PATH" ) ); lumiScale = new LumiScale( lumiScaleFileName ); c) Collect the data stored in the ambient DB -------------------------------------------- For the background plots, the end time of the range studied is always equal to the end of the previous shift. That's fine as the cron jobs are run few minutes after Midnight (biweekly plots) and 8 am (daily plots). This is done in the script by setting the variable currentShift to 0 (<-> last shift). Otherwise, shift are identified by a tag: YYYYMMDDx with x = 0 (owl), 1 (day) and 2 (swing). Then, the start time is defined as w.r.t. this reference (1 day ago, 14 days ago, user's choice etc.). Once the time range is defined, the data are accessed via single-line instructions like DrcBkgOdcNtuple *ntuple = new DrcBkgOdcNtuple( startTime, stopTime, scanFreq4Seconds ); The class constructor runs Ambient and the output ntuple is stored in a temporary file. In this case, the parameters of the constructor are obvious: start and stop time of the DB query; scanning frequency of the DB. d) Compute plots ---------------- Instructions like c1 = makeScalerRatioVsLumiPlot( ntuple, lumiScale, lastThreeShifts, startTime, stopTime ); printCanvas( c1, now, "scalerRatioVsLumi_Daily", "Error: empty canvas for ScalerRatioVsLumiPlot", getenv( "PRODUCE_PICT" ) ); produce the plot on a TCanvas which is then used as parameter of the procedure printCanvas which creates the plot files. Depending on the value of the environment variable PRODUCE_PICT (normally setup in the script calling the ROOT macro), gif pictures are produced or not in addition to the ps files which are always generated. Some important files: --------------------- * Boundaries.h ------------ It defines the limits of the monitored variable ranges which are displayed on the background plots. For instance Float_t lumiMin = 1.0; // 10^{33} Float_t lumiMax = 10.0; // 10^{33} A modification of these values gets normally propagated in all relevent plots the next time the macros are executed -- there should be no hardcoded boundary in the code. Some boundaries may need to be adjusted (temporarily or permanently) when conditions change, for instance at the startup of a Run period or when PEP is scrubbing. * DrcBkgSetup.csh --------------- Script defining the environment variables needed to run properly the ROOT macros. It is normally run in all .csh scripts launching such background-monitoring macros. IMPORTANT: ---------- To use the package in your own directory, modify all the setenv definitions to point to _your_ target directories. The two variables LINK_* defines areas which are visible via the web to allow an easy access to the daily and biweekly plots automatically generated. * dailyPlots.csh & biWeeklyPlots.csh ---------------------------------- Scripts ran by the cron jobs to update the daily and biweekly plots * standalonePlots.csh ------------------- Script to produce several monitoring plots in standalone. Several variables need to be configured to run the job correctly. set firstShift = 200604030 ---> First shift taken into account set lastShift = 200604190 ---> Last shift taken into account set title = "sinceQ2Replacement" ---> Tag to identify output files set scanFreq = 60 ---> Ambient scanning frequency (in seconds) set scopePlotColor = 4 ---> Color of the scope plot set twoDPlotsColor = 4 ---> Color of the scatter plot [I like the blue !] setenv PRODUCE_PICT YES ---> YES: gif files are produced in addition to postscript set doNotUseEpicsRatios = "kFALSE" ---> FALSE: use directly the ratio variables computed in epics. ---> TRUE: compute the ratio 'by hand' by diving the 'raw' value coming from epics by the parameterization defined in the code via ExpectedRate objects. This can be interesting to test new sets of coefficients describing expected rates. set singleBeam = "kFALSE" ---> FALSE: standalone plots for colliding data taking. ---> TRUE: standalone plots for single beam data. Additional feature: ------------------- You can now _select_ the runs you want to use in the shift range whose boundaries are given in argument of standalonePlots.csh -- see the file listOfRunsForStandaloneAnalysis.h for details. You'll have to provide the number of runs (variable nRuns > 0) and the run numbers (array runList). For instance, this can be useful to look at some single beam runs spread over a few days. * plots.csh --------- Deprecated script used initally to run daily and bi-weekly macros. No more used now that the daily and bi-weekly cron jobs run at different times. * php.csh ------- Script managing the update of all webpages via php macros * ExpectedRate.h -------------- Class allowing to compute normalized 'raw over expected' ratios of an epics variable in ROOT macros, ignoring the value of the corresponding normalized epics variable if available. * LumiScale.h ----------- Code accessing the proper lumi ratio at a given time, using the table LumiScale/lumiScale.txt computed by the perl script updateLumiScale.pl. * NominalCurrents.h ----------------- Contains the (current: update if needed!) nominal values of the current measured in the 12 HV channels powering the scalers. These nominal values are defined as the currents readout when the channels are at runnable voltage ('V0' in the DIRC vocabulary) and there is no beam in PEP. The idea behind this is that an increase of current would trigger an increase of the background (more current <-> more charge <-> more hits). * Shift.h ------- Code steering the shift coding convention. * Utilities.h ----------- As indicated by its name, this file contains several general procedures extensively used in the ROOT macros.