Configuration files for cogwheelpipe
====================================

In order to allow cogwheel to be configured in a way which asimov understands we have introduced simple configuration files for cogwheel pipe which allow the inference code to be configured in a way which is easy to reproduce.

This page provides a guide as to the format of this configuration file.

The configuration file is written in YAML format, and we will sometimes use "inline YAML" to describe it here.
That means that the following hierarchical dictionary in YAML format

::

   waveform:
     approximant: IMRPhenomXPHM

Is written as ``waveform: approximant: IMRPhenomXPHM`` in this document, in order to make things a little more concise.

Event-specific Settings
-----------------------

These settings are specific to a given gravitational wave signal.

``event: name``
  The name of the gravitational wave event, for example

  ::

     event:
       name: GW150914

  This value can be set to automatically obtain data for a given event.

``event: event time``
  The GPS time of the gravitational wave event. This is optional when downloading 
  data from GWOSC (as the event time can be looked up automatically), but is 
  **required** when using frame files.

  ::

     event:
       name: GW150914
       event time: 1126259462.4

``event: fiducial parameters``
  The fiducial parameters, or "best guess" parameters for the event.
  For example
  
  ::

     event:
       fiducial parameters:
         chirp mass: 30

Data Settings
-------------

These settings control how strain data is acquired for the analysis.

``data``
  The data section contains configuration for frame files and channel names.
  This follows asimov's blueprint structure for data configuration.

``data: frame files``
  Specify GWF (Gravitational Wave Frame) files containing strain data for each 
  interferometer. This is useful when you want to use data from local files or 
  from previous analyses (e.g., from asimov-gwdata pipeline) instead of 
  downloading from GWOSC.

  When using frame files, the ``event: event time`` parameter is required.

  ::

     data:
       frame files:
         H1: /path/to/H-H1_GWOSC_16KHZ_R1-1126257415-4096.gwf
         L1: /path/to/L-L1_GWOSC_16KHZ_R1-1126257415-4096.gwf
         V1: /path/to/V-V1_GWOSC_16KHZ_R1-1126257415-4096.gwf

  If frame files are not specified, data will be downloaded from GWOSC.

``data: channels``
  Optionally specify custom channel names for each detector when reading frame files.
  If not specified, the default channel naming convention ``{IFO}:GWOSC-16KHZ_R1_STRAIN`` 
  is used.

  ::

     data:
       frame files:
         H1: /path/to/H1_frame.gwf
         L1: /path/to/L1_frame.gwf
       channels:
         H1: H1:GWOSC-16KHZ_R1_STRAIN
         L1: L1:GWOSC-16KHZ_R1_STRAIN

  This approach makes data handling compatible with bilby, allowing results from 
  the two pipelines to be compared directly.

``data: segment length``
  Optionally specify the total duration of data to read in seconds. Default is 32.0 seconds.
  The time before the event is calculated as: segment length - post trigger time.

  ::

     data:
       segment length: 32.0

``likelihood: post trigger time``
  Optionally specify the time after the event (in seconds) to include in the analysis.
  Default is 2.0 seconds. This is used to calculate the data segment boundaries and 
  padding for filtering/whitening operations.

  ::

     likelihood:
       post trigger time: 2.0

``quality: maximum frequency``
  Optionally specify the maximum frequency for the analysis in Hz. Default is 1024.0 Hz.
  Can be specified per-detector (as a dictionary) or as a single value. If specified 
  per-detector, the highest value will be used for all detectors.

  ::

     quality:
       maximum frequency:
         H1: 1024.0
         L1: 1024.0
       # Or as a single value:
       # maximum frequency: 1024.0

``psds``
  Specify Power Spectral Density (PSD) files for each interferometer. This is 
  useful when you want to use PSDs generated by other tools (e.g., BayesWave) 
  for on-source analysis.

  PSD files should be in two-column text format: frequency (Hz), PSD value.

  ::

     psds:
       H1: /path/to/H1_psd.txt
       L1: /path/to/L1_psd.txt

  Frame files and PSDs can be used together to provide complete control over 
  input data and noise characterization.

``psds: whitening_filter``
  Configure the whitening filter parameters when using custom PSDs.

  ::

     psds:
       H1: /path/to/H1_psd.txt
       L1: /path/to/L1_psd.txt
       whitening_filter:
         fmin: 15.0       # Minimum frequency (Hz), default: 15.0
         df_taper: 1.0    # Taper width (Hz), default: 1.0
  
Waveform settings
-----------------

These settings control the waveform approximant used in the analysis.

``waveform: approximant``
  The name of the waveform approximant to be used in the analysis, for example

  ::

     waveform:
       approximant: IMRPhenomXPHM

Sampler settings
----------------

These settings control the behaviour of the sampler.

``sampler: live points``
  The number of live points to use when sampling.
  If not specified directly a default of ``1000`` is used.


Likelihood settings
-------------------

These settings control the behaviour of the likelihood function.

``likelihood: marginalisation``
  Enable marginalisation over extrinsic parameters.

  You may need to alter your prior in order to use a marginalisation.
  
  For example, for distance marginalisation:

  ::
     likelihood:
       marginalisation:
         - distance

Prior settings
--------------

``prior: class``
  Use a specified prior class for the analysis.

  For example

  ::
     prior:
       class: CartesianintrinsicIASPrior

``prior: distributions``
  Set specific values for prior distributions.

  For example:

  ::
     prior:
       distributions:
         chirp mass:
	   minimum: 10
	   maximum: 40