refs #92 some doc updates

docs/source/intro.rst

@@ -1,7 +1,7 @@
 Welcome To quickBayes
 =====================
 
-The quickBayes package is an open source library for calculating Bayesian quantities in a short period of time, by making some assumptions.
+The quickBayes package is an open source library for calculating a fast approximation of the Bayesian evidence for use in model selection.
 The package is cross platform, supporting Windows, Mac OS and Linux.
 This package has been developed by Anthony Lim from STFC’s ISIS Neutron and Muon facility.
 

docs/source/theory.rst

@@ -33,31 +33,31 @@ Assume a uniform prior :math:`P(M) = 1/N` for :math:`N` lines and :math:`P(D)` i
     P(M|D) \propto P(D|M)
 
 .. math::
-    :name: P(D|M)
+    :label: P(D|M)
 
     P(D|M) \propto \int \mathrm{d}^N\theta P(D | \theta, M) P(\theta | M)
 
 Assume that we have a known space to investigate
 
 .. math::
-   :name: x
+   :label: x
 
    x_\mathrm{min} \le x \le x_\mathrm{max}
 
 
 .. math::
-   :name: A
+   :label: A
 
    0 \le A_j \le A_\mathrm{max} \label{A}
 
-So the normalization prior must be the volume of the hyper cube from :ref:`equation 2<x>` and :ref:`equation 3<A>` top hat function due to asssume flat prior -> volume
+So the normalization prior must be the volume of the hyper cube from :math:numref:`x` and :math:numref:`A` top hat function due to asssume flat prior -> volume
 
 .. math::
-   :name: P(theta|M)
+   :label: P(theta|M)
 
     P(\theta | M) = [(x_\mathrm{max} – x_\mathrm{min}) A_\mathrm{max}]^{-N}
 
-substituting :ref:`equation 4<P(theta|M)>` into :ref:`equation 1<P(D|M)>`
+substituting :math:numref:`P(theta|M)` into :math:numref:`P(D|M)`
 
 .. math::
 
@@ -72,7 +72,7 @@ Assume that the data is subject to independent additive gaussian noise
 where :math:`\chi^2` is the chi squared value and is a function of :math:`\theta`
 
 .. math::
-   :name: almost
+   :label: almost
 
     P(D|M) \propto [(x_\mathrm{max} – x_\mathrm{min}) A_\mathrm{max}]^{-N}\int \mathrm{d}^N\theta \exp\left(-\frac{\chi^2}{2}\right)
 
@@ -87,22 +87,22 @@ Use a Taylor expansion
 Hence
 
 .. math::
-   :name: Taylor
+   :label: Taylor
 
    \int \mathrm{d}^N\theta \exp\left(-\frac{\chi^2}{2}\right) \approx \exp\left(-\frac{\chi^2_\mathrm{min}}{2}\right) \frac{(4\pi)^N}{\sqrt{(\mathrm{det}(\underline{\nabla} \ \underline{\nabla} \chi^2)) }}
 
 where :math:`\mathrm{det}(H) = \mathrm{det}(\underline{\nabla} \ \underline{\nabla} \chi^2))` is the determinant of the Hessian matrix :math:`H`.
-Substituting :ref:`equation 6<Taylor>` into :ref:`equation 5 <almost>` and for indistinguishable lines there are $N$ factorial possibilities
+Substituting :math:numref:`Taylor` into :math:numref:`almost` and for indistinguishable lines there are :math:`N` factorial possibilities
 
 .. math::
-   :name: sivia
+   :label: sivia
 
    P(D|M) \propto P(M|D) \propto \frac{N! (4\pi)^N }{[(x_\mathrm{max} - x_\mathrm{min})A_\mathrm{max}]^N \sqrt{H}} \exp\left(-\frac{\chi^2_0}{2}\right)
 
 Taking the logs and rearranging gives
 
 .. math::
-   :name: logs
+   :label: logs
 
    \log{[P(D|M)]} \propto \sum_{j=1}^{N}\log{(j)} +
    N\log{(4\pi)} - N\log{([x_\mathrm{max} - x_\mathrm{min}]A_\mathrm{max})} -
@@ -116,7 +116,7 @@ Including Unique Lines
 Define a model, :math:`M` as as sum of indistinguishable functions/lines and some other function :math:`g`
 
 .. math::
-   :name: big M
+   :label: big M
 
    M = \sum_i^k \alpha_i g_i(x, \underline{\theta}) + \sum_j^N A_j f(x, \underline{\theta})
 
@@ -134,55 +134,55 @@ Assume a uniform prior  :math:`P(M) = 1/N` for :math:`N` lines and :math:`P(D)`
 
    P(M|D) \propto P(D|M)
 
-The probabilities can be split into two parts corresponding to the two terms in :ref:`equation 9<big M>`
+The probabilities can be split into two parts corresponding to the two terms in :math:numref:`big M`
 
 .. math::
    P(D|M) = P(D|G + F)
 
 where :math:`G = \sum_j \alpha_j g_j(x, \underline{\theta})` and :math:`F = \sum_j A_j f(x, \underline{\theta})`.
 
 .. math::
-    :name: P(D|G + F)
+    :label: P(D|G + F)
 
     P(D|M) \propto \int \mathrm{d}\underline{\theta} P(D | \underline{\theta}, G + F) P(\underline{\theta} | G + F)
 
 assume that we have a known space to investigate
 
 .. math::
-   :name: x2
+   :label: x2
 
    x_\mathrm{min} \le x \le x_\mathrm{max}
 
 For the :math:`F` terms:
 
 .. math::
-   :name: A2
+   :label: A2
 
    A_\mathrm{min} \le A_j \le A_\mathrm{max}
 
 For the :math:`G` terms:
 
 .. math::
-   :name: alpha
+   :label: alpha
 
    \alpha_{i_\mathrm{min}} \le \alpha_i \le \alpha_{i_\mathrm{max}}
 
-So the normalization prior must be the volume of the hyper cube from :ref:`equation 11<x2>`, :ref:`equation 12<A2>` and :ref:`equation 13 <alpha>`
+So the normalization prior must be the volume of the hyper cube from :math:numref:`x2`, :math:numref:`A2` and :math:numref:`alpha`
 
 .. math::
-   :name: P(theta|M2)
+   :label: P(theta|M2)
 
     P(\underline{\theta} | G + F) = [(x_\mathrm{max} – x_\mathrm{min}) (A_\mathrm{max}-A_\mathrm{max})]^{-N}(x_\mathrm{max} – x_\mathrm{min})^{-k}\prod_i^k (\alpha_{i_\mathrm{max}}-\alpha_{i_\mathrm{max}})]^{-1}
 
-The first part of this is just a more general version of :ref:`equation 4 <P(theta|M)>`, so let :math:`\beta =  [(x_\mathrm{max} – x_\mathrm{min}) (A_\mathrm{max}-A_\mathrm{max})]^{-N}` then :ref:`equation 14<P(theta|M2)>` becomes
+The first part of this is just a more general version of :math:numref:`P(theta|M)`, so let :math:`\beta =  [(x_\mathrm{max} – x_\mathrm{min}) (A_\mathrm{max}-A_\mathrm{max})]^{-N}` then :math:numref:`P(theta|M2)` becomes
 
 .. math::
-   :name: P(theta|M2)2
+   :label: P(theta|M2)2
 
    P(\underline{\theta} | G + F) = \beta (x_\mathrm{max} – x_\mathrm{min})^{-k}\prod_i^k (\alpha_{i_\mathrm{max}}-\alpha_{i_\mathrm{max}})]^{-1}
 
 
-substituting :ref:`equation 15<P(theta|M2)2>` into :ref:`equation 10 <P(D|G + F)>`
+substituting :math:numref:`P(theta|M2)2` into :math:numref:`P(D|G + F)`
 
 .. math::
 
@@ -197,7 +197,7 @@ Assume that the data is subject to independent additive gaussian noise
 where :math:`\chi^2` is the chi squared value and is a function of :math:`\underline{\theta}`
 
 .. math::
-   :name: almost2
+   :label: almost2
 
    P(D|G + F) \propto  \beta (x_\mathrm{max} – x_\mathrm{min})^{-k}\prod_i^k (\alpha_{i_\mathrm{max}}-\alpha_{i_\mathrm{max}})^{-1} \int \mathrm{d}\underline{\theta} \exp\left( - \frac{\chi^2}{2}\right)
 
@@ -212,15 +212,15 @@ Use a Taylor expansion
 Hence
 
 .. math::
-   :name: Taylor2
+   :label: Taylor2
 
    \int \mathrm{d}\underline{\theta} \exp\left(-\frac{\chi^2}{2}\right) \approx \exp\left(-\frac{\chi^2_\mathrm{min}}{2}\right) \frac{(4\pi)^{N+k}}{\sqrt{(\mathrm{det}(\underline{\nabla} \ \underline{\nabla} \chi^2)) }}
 
 where :math:`\mathrm{det}(H) = \mathrm{det}(\underline{\nabla} \ \underline{\nabla} \chi^2))` is the determinant of the Hessian matrix :math:`H`.
-Substituting :ref:`equation 17 <Taylor2>` into :ref:`equation 16<almost2>` and for indistinguishable lines there are :math:`N` factorial possibilities
+Substituting :math:numref:`Taylor2` into :math:numref:`almost2` and for indistinguishable lines there are :math:`N` factorial possibilities
 
 .. math::
-   :name: me
+   :label: me
 
    P(D|M) \propto P(M|D) \propto \frac{N! (4\pi)^{N+k}\beta }{\sqrt{H}(x_\mathrm{max} – x_\mathrm{min})^{k}\prod_i^k (\alpha_{i_\mathrm{max}}-\alpha_{i_\mathrm{max}})} \exp\left(-\frac{\chi^2_0}{2}\right)
 
@@ -251,4 +251,6 @@ If the :math:`k` distinguishable lines are the same for all models being conside
    \log{(\sqrt{H})}  -
    \frac{\chi^2_0}{2}
 
-In the case of positive definite amplitudes :math:`A_\mathrm{min} = 0` and substituting in for :math:`\beta` this reduces to :ref:`equation 8 <logs>`. Alternatively, substituting :ref:`equation 18 <me>` into the odds ratio would lead to the terms corresponding to the distinguishable lines cancelling out. So they can be neglected, this might happen in the case of a linear background term for all of the models.
+In the case of positive definite amplitudes :math:`A_\mathrm{min} = 0` and substituting in for :math:`\beta` this reduces to :math:numref:`logs`.
+Alternatively, substituting :math:numref:`me` into the odds ratio would lead to the terms corresponding to the distinguishable lines cancelling out.
+So they can be neglected, this might happen in the case of a linear background term for all of the models.