Toolbox library

This page gives a description of the

• Toolboxc

class. This class consists of several structures and functions written in C++ which can be used at the different stages of the CWB analysis.

The available structures are collected in the following list:

• CWB_CAT: enumeration of possible Data Quality (see data quality)
• dqfile information about a segment list of DQ (see data quality)
• frfile information on a frame file (name, start, stop)
• slag information regarding superlags environment (see What are super lags and how to use them)
• mdcshift information about possible shift on MDC (start, stop, shift)
• ifoparms information about a detector (see Detectors)

The available functions are collected in the following list:

segments method	Method for construction of segments
data quality method	Data Quality management
job methods	Job management
slag methods	Superlag management
condor methods	Condor submission management
merge methods	Merging management
history methods	Parameter history management
spectra methods	Detector PSD management
system methods	Substitute shell command
post-processing methods	Post-processing management
utility methods	Various utilities
Hilbert & Wigner-Ville Transforms methods	Utilities for Hilbert and Wigner-Ville Transforms

Method for construction of segments

cWB contains a struct: - waveSegment which describes a single segment period of the type [start, stop]. cWB manages segment list as c++ vector of waveSegment (segment list).

• CWB::Toolbox::unionSegments()

  Check if a segment list is in increasing order and join eventual consecutive waveSegment in the list

• CWB::Toolbox::mergeSegLists()

  Merge two segment list (create a new segment list which contains the coincidence times)

• CWB::Toolbox::getMaxSeg()

  Find the waveSegment with the maximum lenght

• CWB::Toolbox::getTimeSegList()

  Calculate the sum of segment lengths in the list

• CWB::Toolbox::dumpSegList()

  Dump a segment list in a txt file

• CWB::Toolbox::getSlagJobList()

  Modify the segment list to be composed of segments with lenght equal to the input parameter

Data Quality management

Data Quality are inserted in the cWB algorithm using the struct

• dqfile

Data Quality are labeled with the struct CWB_CAT

• CWB::Toolbox::readSegList()
  1. Check if the segment list contained in the dq file is in increasing order and join eventual consecutive waveSegment in the list
  2. Merge segment lists with DQ>maximum dq order
• CWB::Toolbox::setSlagShifts()

Job management

For the construction of segments, the pipeline follows the parameters specified in Job settings.

• CWB::Toolbox::getJobList()
  1. Construct the jobs segment list
  2. Construct the jobs segment list selecting the segments with a minimum lenght

• CWB::Toolbox::dumpJobList()

  Dump the job list in a txt file

• CWB::Toolbox::getSegList()

  Construct the job segment list taking in account superlag (see What are super lags and how to use them).

Superlag management

Superlag environment allows to perform time shift bigger than the job segment duration. See What are super lags and how to use them for detailed information.

The way to define segment list is more complex using superlag, all the following function define the final segment list including superlag.

The functions need the struct slag

• CWB::Toolbox::getSlagList()

  Contruct segment list

• CWB::Toolbox::dumpSlagList()

  Dump segment list in a file

• CWB::Toolbox::getSlag()

  Get slag structure referred to a certain job

• CWB::Toolbox::getSegList()

  Create the merged segment list considering DQ_CAT1

Condor submission management

cWB can use condor as batch system. The following functions manage this submission with the creation of the two files:

1. .sub : contains executable file and output condor files
2. .dag : submit one job for each segment in the final segment list

• CWB::Toolbox::createDagFile()

  produce the .dag file

• CWB::Toolbox::createSubFile()

  produce the .sub file

• CWB::Toolbox::getCondorJobList()

  get the job list from .dag file

• CWB::Toolbox::getJobBenchmark()

  extract benchmark info from bench status history line (see Benchmark parameters for more details)

Merging management

• CWB::Toolbox::mergeCWBTrees()

  merge selected trees contained in the root files inside a selected directory

• CWB::Toolbox::mergeTrees()

  merge selected trees contained in the root files listed in a txt file

• CWB::Toolbox::readFileList()

  read a list from a text file

• CWB::Toolbox::dumpFileList()

  write a list to a text file

• CWB::Toolbox::getMergeJobList()

  return a vector of jobs number from a file list. The job number is extracted from root file name of the type : *_job#.root

History management

Output root files produced by cWB contains (if desired) the complete set of parameters from user_parameters.C and user_pparameters.C files used to produce that files.

• CWB::Toolbox::readFile()

  Read history from a file and creates a string containing variable values

• CWB::Toolbox::getEnvCWB()

  Creates a string containing variable values extracting from the running environment

Detector PSD management

These functions manage the PSD calculation from a discretizated time evolution of a certain period.

PSD can be calculated averaging PSD calculated in sub-periods of the total time.

• CWB::Toolbox::makeSpectrum()

  Calculate PSD. It is possible to save in a text file

• CWB::Toolbox::getSimNoise()

  Create Gaussian noise coloured according a given PSD

• CWB::Toolbox::convertSampleRate()

  Resample data

• CWB::Toolbox::GetDetectorPSD()

  Extract PSD from a text file

Substitute shell commands

• CWB::Toolbox::getFileListFromDir()

  Create a list of files contained in a directory

• CWB::Toolbox::checkFile()

  Check if a files exists

• CWB::Toolbox::mkDir()

  Create a directory if not exists (if exists ask confirmation)

• CWB::Toolbox::rmDir()

  Remove a directory, asking a confirmation

• CWB::Toolbox::PrintProcInfo()

  Print on shell information about memory usage and date

• CWB::Toolbox::getTemporaryFileName()

  get name of temporary file on the node

• CWB::Toolbox::mksTemp()

  call the mksTemp linux command

Post processing management

• CWB::Toolbox::setVeto()

  apply Data Quality and veto to waveburst in ifname root file and create an output root file adding a flag for each Data Quality

• CWB::Toolbox::setCuts()

  Apply some selection cuts on a tree, called by the command cwb_setcuts

• CWB::Toolbox::setUniqueEvents()

  Apply unique event selection on a sim tree, called by the command cwb_setcuts

• CWB::Toolbox::getLiveTime()

  Calculate background livetime

• CWB::Toolbox::getZeroLiveTime()

  Calculate zero-lag livetime

• CWB::Toolbox::doPoissonPlot()

  Produce Poisson plot in the web page (see Background part)

• CWB::Toolbox::isLeafInTree()

  Check if a leaf is present in a tree

• CWB::Toolbox::setMultiplicity()

  Calculate Multiplicity for Rate vs threshold figure (see Background part)

• CWB::Toolbox::getRate()

  Calculate FAR rate at a certain rho treshold

Various utilities

• CWB::Toolbox::resampleToPowerOfTwo()

  Resample to the minimum power of two bigger than original rate

• CWB::Toolbox::getJobId()

  return jobId from the file name

• CWB::Toolbox::getParameter()

  Get parameter values from a string written in shell command

• CWB::Toolbox::getFileName()

  Get file name from a c++ pointer or link

• CWB::Toolbox::getUniqueFileList()

  Merge various files list in a unique one and write in a text files

• CWB::Toolbox::WriteFrameFile()

  Create a frame file containing data from time domain

Utilities for Hilbert and Wigner-Ville Transforms

The Hilbert & Wigner-Ville transforms are used where?

• CWB::Toolbox::getHilbertTransform()

  Calculate the Hilbert transform

• CWB::Toolbox::getHilbertEnvelope()

  Return the envelope from analytic signal analysis

• CWB::Toolbox::getHilbertIFrequency()

  Return the instantaneous frequency from analytic signal analysis

• CWB::Toolbox::getWignerVilleTransform()

  Return Time-Frequency map

• CWB::Toolbox::unWrapPhase()

  Phase unwrapping ensures that all appropriate multiples of 2pi have been included in phase evolution

• CWB::Toolbox::getSineFittingParams()

  return from a sine fitting: A sin ( wt + f ) the values of A, w and f