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