input
^^^^^^^^^^^

This directory contains informations useful on the analysis, it can be
used also to store particular interesting files not stricly used for the
analysis. The standard files contained in this dir are reported in the
following list.

**Note**: Despite of files contained in the `config <running.html#config>`__
directory, it is not necessary to put inside the dir input all the
following files. It is just a convention.

 - `strain frames <#strain-frames>`__

list of strain frame files

 - `mdc frames <#mdc-frames>`__

list of mdc frame files & injection list

 `data quality <#data-quality>`__

data quality files

 `sky mask <#sky-mask>`__

sky mask used to select sky positions to be analized

| |LVK|

An example of input directory is in the example:
 `O2_SIM1_LF_BRST_LH_WP10_tutorial_root6_run1 <https://ldas-jobs.ligo.caltech.edu/~waveburst/reports/O2_SIM1_LF_BRST_LH_WP10_tutorial_root6_run1/dir/>`___

strain frames
^^^^^^^^^^^^^^^^^^^^^

| Data of GW detectors are usually stored in the *frame* format. These
  files are simple text files containing the complete list of frames files
  of GW detector data.
| To create a frame list, see `How to make gw frame file list with
  gw_data_find <faq.html#how-to-make-gw-frame-file-list-with-gw-data-find>`__
| However, the user can create by itself any frame list.

| Once obtained the file list, see `Files list <cwb_parameters.html#files-list>`__.

| Sometimes, it is possible that a single frame file is not
  **temporanealy** readable (so the analysis will be stopped). To avoid
  this problem, the reading function try to read up to 3 times every 60
  seconds. If after the third temptative the files is not still readable,
  the analysis is stopped (and can be resumed later).


mdc frames
^^^^^^^^^^^^^^^^^^

| This is a similar list as `strain frames <#strain-frames>`__ but it is
  referred to MDC strain. It is a unique list containing all the MDC
  channels for all detectors.
| To obtain this list, there are the same tools as `strain frames <#strain-frames>`__.

Moreover, together to the frame list, cWB needs also a *Log file*, which
contains specific informations for each injected MDC (arrival timing at
earth and each detector, source direction, hrss, antenna patterns, ...).
It is used by the pipeline to store informations related to the MDC in
the final root file.

| |LVK|

MDC frame and log files are produced with BurstMDC. O2 AllSky MDC files
documentation produced with BurstMDC are liksted in the following link :
`https://wiki.ligo.org/Bursts/O2-Allsky <https://wiki.ligo.org/Bursts/O2-Allsky>`__

| Once obtained the MDC files, see `Files list <cwb_parameters.html#files-list>`__.


sky mask
^^^^^^^^^^^^^^^^

The default analysis spans over all the sky to estimate candidate
events. (For the grid resolution see `Sky settings <cwb_parameters.html#sky-settings>`__).
It is possibile, however, to specify a resctricted region of the sky,
for istance for extrig searches. This is done by defining a sky mask,
which is simply a collection of 1/0 values for each sky position.

There are 2 type of skymask maps:

#. earth coordinates
    use parameter skyMaskFile
#. celestial coordinates
    use parameter skyMaskFileCC

| A script that construct a tyipical sky map is: `CreateSkyMask.C`

| A script that construct a tyipical celestial sky map is: `CreateCelestialSkyMask.C`


Data Quality
^^^^^^^^^^^^^^^^^^^^

Data qualities are a collection of time periods were the detectors are
in good/bad conditions for scientific purpouses. According to LIGO-Virgo
policy, there are different Data Quality definitions:

-  **Science segments (Category 0)**: Detector locked (i.e. in data taking)
-  **Category 1**: Detector not running in proper configuration
-  **Category 2**: Well understood instrumental problems
-  **Category 3**: Incompletely understood issues, not sure that are affecting the data
-  **Category 4**: hardware injections
-  **PEM** : Physical Environment Monitoring
-  **HVETO** : most significant correlation between an auxiliary channel and DARM_ERR

For a more detailed description see: `Data Quality @ GWOSC <https://www.gw-openscience.org/O1/>`__


| The parameters used to define the data quality in production stage are in `Files list <cwb_parameters.html#files-list>`__.

| The parameters used to define the data quality in poost-production
  stage are `Data Quality and veto <cwb_pparameters.html#data-quality-and-veto>`__.

The definition structure is the same in the two files:

-  **ifo** name of ifo as declared in the ifo parameter
-  **dqcat_file** path of data quality file
-  **dqcat** dq quality category [see below]
-  **shift** time shift applied to data quality (default = 0 sec)
-  **inverse** [false/true] if false then ranges declared in dqcat_file are the good periods (see below)
-  **4columns** [false/true] defines the format of the dqcat_file
    false -> each column contains : start stop
    true -> each column contains : index start stop stop-start
    NOTE : only start,stop are used

**dqcat** used by cWB are:

-  **CWB_CAT0** science mode segments
-  **CWB_CAT1** DQ_CAT1/CAT4 periods
-  **CWB_CAT2** DQ_CAT2
-  **CWB_CAT3** DQ_CAT3
-  **CWB_HVETO** hveto
-  **CWB_PEM** pem vetoe
-  **CWB_EXC** taking in account times in two detectors network not included in three detector network
-  **CWB_USER** user define vetoes

**inverse** is quite controversial, especially because the it has
            different meaning in `user_parameters.C <cwb_parameters.html#user-parameters-c>`__
            and `user_pparameters.C <cwb_pparameters.html#user-pparameters-c>`__ files:

-  user_parameters.C
    | **false**: the file containes period to be analyzed
    | **true**: the file containes period to be discarded
-  user_pparameters.C (CAT2)
    | **false**: the files contains period to be accepted
    | **true**: the files contains period to be discarded
-  user_pparameters.C (CAT3)
    | **false**: the files contains period to be discarded
    | **true**: the files contains period to be accepted

**Examples:**

Production Stage :

.. code-block:: bash

      // dq file list
      // {ifo, dqcat_file, dqcat[0/1/2], shift[sec], inverse[false/true], 4columns[true/false]}
      nDQF=12;
      // dqf is a temporary array
      dqfile dqf[nDQF]={
             {"L1" ,"input/S6A_OFFLINE_L1SCIENCE.txt",         CWB_CAT0, 0., false, false},
             {"L1" ,"input/S6A_OFFLINE_L1_DQCAT1SEGMENTS.txt", CWB_CAT1, 0., true,  false},
             {"L1" ,"input/S6A_OFFLINE_L1_DQCAT2SEGMENTS.txt", CWB_CAT2, 0., true,  false},
             {"L1" ,"input/S6A_OFFLINE_L1_DQCAT4SEGMENTS.txt", CWB_CAT1, 0., true,  false},
             {"H1" ,"input/S6A_OFFLINE_H1SCIENCE.txt",         CWB_CAT0, 0., false, false},
             {"H1" ,"input/S6A_OFFLINE_H1_DQCAT1SEGMENTS.txt", CWB_CAT1, 0., true,  false},
             {"H1" ,"input/S6A_OFFLINE_H1_DQCAT2SEGMENTS.txt", CWB_CAT2, 0., true,  false},
             {"H1" ,"input/S6A_OFFLINE_H1_DQCAT4SEGMENTS.txt", CWB_CAT1, 0., true,  false},
             {"V1" ,"input/S6A_OFFLINE_V1SCIENCE.txt",         CWB_CAT0, 0., false, false},
             {"V1" ,"input/S6A_OFFLINE_V1_DQCAT1SEGMENTS.txt", CWB_CAT1, 0., true,  false},
             {"V1" ,"input/S6A_OFFLINE_V1_DQCAT2SEGMENTS.txt", CWB_CAT2, 0., true,  false},
             {"V1" ,"input/S6A_OFFLINE_V1_DQCAT4SEGMENTS.txt", CWB_CAT1, 0., true,  false}
            };
      // temporary arrary is copied to the final array DQF
      for(int i=0;i<nDQF;i++) DQF[i]=dqf[i];

Post-Production Stage :

.. code-block:: bash

      const int nvdqf=4;
      dqfile vdqf[nvdqf] = {
             {"V1", "input/V1_KW_HVETO_S6A.txt",               CWB_HVETO, 0., false, false},
             {"L1", "input/S6A_OFFLINE_L1_DQCAT3SEGMENTS.txt", CWB_CAT3,  0., false, false},
             {"H1", "input/S6A_OFFLINE_H1_DQCAT3SEGMENTS.txt", CWB_CAT3,  0., false, false},
             {"V1", "input/S6A_OFFLINE_V1_DQCAT3SEGMENTS.txt", CWB_CAT3,  0., false, false}
            };