.. include:: images.rst Toolbox library --------------- This page gives a description of the - :cwb_library:`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 `__) - :cwb_library:`dqfile` information about a segment list of DQ (see `data quality `__) - :cwb_library:`frfile` information on a frame file (name, start, stop) - :cwb_library:`slag` information regarding superlags environment (see `What are super lags and how to use them `__) - :cwb_library:`mdcshift` information about possible shift on MDC (start, stop, shift) - :cwb_library:`ifoparms` information about a detector (see `Detectors `__) The available functions are collected in the following list: +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `segments method <#segments-method>`__ | Method for construction of segments | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `data quality method <#data-quality-method>`__ | Data Quality management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `job methods <#job-methods>`__ | Job management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `slag methods <#slag-methods>`__ | Superlag management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `condor methods <#condor-methods>`__ | Condor submission management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `merge methods <#merge-methods>`__ | Merging management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `history methods <#history-methods>`__ | Parameter history management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `spectra methods <#spectra-methods>`__ | Detector PSD management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `system methods <#system-methods>`__ | Substitute shell command | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `post-processing methods <#post-processing-methods>`__ | Post-processing management | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `utility methods <#utility-methods>`__ | Various utilities | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | `Hilbert & Wigner-Ville Transforms methods <#hilbert-wigner-ville-transforms-methods>`__ | Utilities for Hilbert and Wigner-Ville Transforms | +-------------------------------------------------------------------------------------------------------+------------------------------------------------------+ | .. _segments-method: Method for construction of segments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ cWB contains a struct: - :cwb_library:`waveSegment` which describes a single segment period of the type [start, stop]. cWB manages segment list as c++ vector of waveSegment (**segment list**). - :cwb_library:`CWB::Toolbox::unionSegments` Check if a segment list is in increasing order and join eventual consecutive waveSegment in the list - :cwb_library:`CWB::Toolbox::mergeSegLists` Merge two segment list (create a new segment list which contains the coincidence times) - :cwb_library:`CWB::Toolbox::getMaxSeg` Find the waveSegment with the maximum lenght - :cwb_library:`CWB::Toolbox::getTimeSegList` Calculate the sum of segment lengths in the list - :cwb_library:`CWB::Toolbox::dumpSegList` Dump a segment list in a txt file - :cwb_library:`CWB::Toolbox::getSlagJobList` Modify the segment list to be composed of segments with lenght equal to the input parameter .. _data-quality-method: Data Quality management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | Data Quality are inserted in the cWB algorithm using the struct - :cwb_library:`dqfile` | Data Quality are labeled with the struct CWB_CAT - :cwb_library:`CWB::Toolbox::readSegList` #. Check if the segment list contained in the dq file is in increasing order and join eventual consecutive waveSegment in the list #. Merge segment lists with DQ>maximum dq order - :cwb_library:`CWB::Toolbox::setSlagShifts` .. _job-methods: Job management ~~~~~~~~~~~~~~~~~~~ For the construction of segments, the pipeline follows the parameters specified in `Job settings <#job-settings>`__. - :cwb_library:`CWB::Toolbox::getJobList` #. Construct the jobs segment list #. Construct the jobs segment list selecting the segments with a minimum lenght - :cwb_library:`CWB::Toolbox::dumpJobList` Dump the job list in a txt file - :cwb_library:`CWB::Toolbox::getSegList` Construct the job segment list taking in account superlag (see `What are super lags and how to use them <#what-are-super-lags-and-how-to-use-them>`__). .. _slag-methods: 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 <#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_library:`CWB::Toolbox::getSlagList` Contruct segment list - :cwb_library:`CWB::Toolbox::dumpSlagList` Dump segment list in a file - :cwb_library:`CWB::Toolbox::getSlag` Get slag structure referred to a certain job - :cwb_library:`CWB::Toolbox::getSegList` Create the merged segment list considering DQ_CAT1 .. _condor-methods: Condor submission management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ cWB can use condor as batch system. The following functions manage this submission with the creation of the two files: #. **.sub** : contains executable file and output condor files #. **.dag** : submit one job for each segment in the final segment list - :cwb_library:`CWB::Toolbox::createDagFile` produce the .dag file - :cwb_library:`CWB::Toolbox::createSubFile` produce the .sub file - :cwb_library:`CWB::Toolbox::getCondorJobList` get the job list from .dag file - :cwb_library:`CWB::Toolbox::getJobBenchmark` extract benchmark info from bench status history line (see `Benchmark parameters <#benchmark-parameters>`__ for more details) .. _merge-methods: Merging management ~~~~~~~~~~~~~~~~~~~~~~~ - :cwb_library:`CWB::Toolbox::mergeCWBTrees` merge selected trees contained in the root files inside a selected directory - :cwb_library:`CWB::Toolbox::mergeTrees` merge selected trees contained in the root files listed in a txt file - :cwb_library:`CWB::Toolbox::readFileList` read a list from a text file - :cwb_library:`CWB::Toolbox::dumpFileList` write a list to a text file - :cwb_library:`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-methods: History management ~~~~~~~~~~~~~~~~~~~~~~~ | Output root files produced by cWB contains (if desired) the complete set of parameters from `user_parameters.C <#user-parameters-c>`__ and `user_pparameters.C <#user-pparameters-c>`__ files used to produce that files. | - :cwb_library:`CWB::Toolbox::readFile` Read history from a file and creates a string containing variable values - :cwb_library:`CWB::Toolbox::getEnvCWB` Creates a string containing variable values extracting from the running environment .. _spectra-methods: 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_library:`CWB::Toolbox::makeSpectrum` Calculate PSD. It is possible to save in a text file - :cwb_library:`CWB::Toolbox::getSimNoise` Create Gaussian noise coloured according a given PSD - :cwb_library:`CWB::Toolbox::convertSampleRate` Resample data - :cwb_library:`CWB::Toolbox::GetDetectorPSD` Extract PSD from a text file .. _system-methods: Substitute shell commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :cwb_library:`CWB::Toolbox::getFileListFromDir` Create a list of files contained in a directory - :cwb_library:`CWB::Toolbox::checkFile` Check if a files exists - :cwb_library:`CWB::Toolbox::mkDir` Create a directory if not exists (if exists ask confirmation) - :cwb_library:`CWB::Toolbox::rmDir` Remove a directory, asking a confirmation - :cwb_library:`CWB::Toolbox::PrintProcInfo` Print on shell information about memory usage and date - :cwb_library:`CWB::Toolbox::getTemporaryFileName` get name of temporary file on the node - :cwb_library:`CWB::Toolbox::mksTemp` call the mksTemp linux command .. _post-processing-methods: Post processing management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :cwb_library:`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_library:`CWB::Toolbox::setCuts` Apply some selection cuts on a tree, called by the command `cwb_setcuts <#cwb-setcuts>`__ - :cwb_library:`CWB::Toolbox::setUniqueEvents` Apply unique event selection on a sim tree, called by the command `cwb_setcuts <#cwb-setcuts>`__ - :cwb_library:`CWB::Toolbox::getLiveTime` Calculate background livetime - :cwb_library:`CWB::Toolbox::getZeroLiveTime` Calculate zero-lag livetime - :cwb_library:`CWB::Toolbox::doPoissonPlot` Produce Poisson plot in the web page (see `Background part <#background-part>`__) - :cwb_library:`CWB::Toolbox::isLeafInTree` Check if a leaf is present in a tree - :cwb_library:`CWB::Toolbox::setMultiplicity` Calculate Multiplicity for Rate vs threshold figure (see `Background part <#background-part>`__) - :cwb_library:`CWB::Toolbox::getRate` Calculate FAR rate at a certain rho treshold .. _utility-methods: Various utilities ~~~~~~~~~~~~~~~~~~~~~~~ - :cwb_library:`CWB::Toolbox::resampleToPowerOfTwo` Resample to the minimum power of two bigger than original rate - :cwb_library:`CWB::Toolbox::getJobId` return jobId from the file name - :cwb_library:`CWB::Toolbox::getParameter` Get parameter values from a string written in shell command - :cwb_library:`CWB::Toolbox::getFileName` Get file name from a c++ pointer or link - :cwb_library:`CWB::Toolbox::getUniqueFileList` Merge various files list in a unique one and write in a text files - :cwb_library:`CWB::Toolbox::WriteFrameFile` Create a frame file containing data from time domain .. _hilbert-wigner-ville-transforms-methods: Utilities for Hilbert and Wigner-Ville Transforms ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Hilbert & Wigner-Ville transforms are used where? - :cwb_library:`CWB::Toolbox::getHilbertTransform` Calculate the Hilbert transform - :cwb_library:`CWB::Toolbox::getHilbertEnvelope` Return the envelope from analytic signal analysis - :cwb_library:`CWB::Toolbox::getHilbertIFrequency` Return the instantaneous frequency from analytic signal analysis - :cwb_library:`CWB::Toolbox::getWignerVilleTransform` Return Time-Frequency map - :cwb_library:`CWB::Toolbox::unWrapPhase` Phase unwrapping ensures that all appropriate multiples of 2pi have been included in phase evolution - :cwb_library:`CWB::Toolbox::getSineFittingParams` return from a sine fitting: A sin ( wt + f ) the values of A, w and f