From c41ec035436bf8e58ca01bc802a70d7f87ac874c Mon Sep 17 00:00:00 2001
From: Charlie Hoy <33521252+hoyc1@users.noreply.github.com>
Date: Fri, 3 Aug 2018 10:00:03 +0100
Subject: [PATCH] Adding doc to explain likelihood marginalization (#69)

* initial commit

* making example only marginalize over distance

* making it easier to understand
---
 docs/command-line/gwin_make_workflow.rst      |  9 +++
 .../GW150914_example/marginalized_gwin.ini    | 68 +++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 examples/workflow/GW150914_example/marginalized_gwin.ini

diff --git a/docs/command-line/gwin_make_workflow.rst b/docs/command-line/gwin_make_workflow.rst
index 77920d0..eee2c3f 100644
--- a/docs/command-line/gwin_make_workflow.rst
+++ b/docs/command-line/gwin_make_workflow.rst
@@ -78,6 +78,15 @@ A simple configuration file for parameter estimation on the ringdown is::
 
 If you want to use another variable parameter in the inference sampler then add its name to ``[variable_params]`` and add a prior section like shown above.
 
+The number of likelihood calculations grows exponentially with the number of variable parameters, and so in order to keep computational costs to a minimum, we can choose to marginalize over time and/or distance and/or phase. This removes the need to sample over those dimensions without affecting the other posterior PDFs. 
+
+We can turn on likehood marginalization by specifying the ``marginalized_gaussian_noise`` class in the ``[model]`` section. For example, we can modify the simple configuration file above to include distance marginalization,
+
+.. literalinclude:: ../../examples/workflow/GW150914_example/marginalized_gwin.ini           
+      :language: ini
+
+If you want to also marginalize over time and/or phase, then add its name to the ``[model]`` section and add a corresponding prior under the section ``[marginalized_prior-${VARIABLE}]`` like shown above. If this was the case, then for this trivial example, you would no longer need to sample over the phase and coalescence time.
+
 When working on real data, it is necessary to marginalise over calibration uncertainty.
 The model and parameters describing the calibration uncertainty can be passed in another ini file, e.g.:
 
diff --git a/examples/workflow/GW150914_example/marginalized_gwin.ini b/examples/workflow/GW150914_example/marginalized_gwin.ini
new file mode 100644
index 0000000..5ccf971
--- /dev/null
+++ b/examples/workflow/GW150914_example/marginalized_gwin.ini
@@ -0,0 +1,68 @@
+[model]
+name = marginalized_gaussian_noise
+distance_marginalization =
+
+[marginalized_prior-distance]
+; how to construct prior distribution for distance marginalization
+name = uniform
+min-distance = 50.
+max-distance = 5000.
+
+[variable_params]
+; parameters to vary in inference sampler
+tc =
+mass1 =
+mass2 =
+distance =
+coa_phase =
+inclination =
+ra =
+dec =
+polarization =
+
+[static_params]
+; parameters that do not vary in inference sampler
+approximant = SEOBNRv2_ROM_DoubleSpin
+f_lower = 28.0
+
+[prior-tc]
+; how to construct prior distribution
+name = uniform
+min-tc = 1126259462.2
+max-tc = 1126259462.6
+
+[prior-mass1]
+; how to construct prior distribution
+name = uniform
+min-mass1 = 10.
+max-mass1 = 80.
+
+[prior-mass2]
+; how to construct prior distribution
+name = uniform
+min-mass2 = 10.
+max-mass2 = 80.
+
+[prior-distance]
+; how to construct prior distribution
+name = uniform
+min-distance = 10
+max-distance = 500
+
+[prior-coa_phase]
+; how to construct prior distribution
+name = uniform_angle
+; uniform_angle defaults to [0,2pi), so we
+; don't need to specify anything here
+
+[prior-inclination]
+; how to construct prior distribution
+name = sin_angle
+
+[prior-ra+dec]
+; how to construct prior distribution
+name = uniform_sky
+
+[prior-polarization]
+; how to construct prior distribution
+name = uniform_angle