Toolbox library

This page gives a description of the

• Toolbox

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