From f15f39483bca338582e1609e81f0d1be60705667 Mon Sep 17 00:00:00 2001 From: Andrew McCluskey Date: Thu, 23 Apr 2020 09:57:35 +0100 Subject: [PATCH] docs nice --- docs/source/conf.py | 4 + uravu/optimize.py | 53 +++++-------- uravu/plotting.py | 41 ++++------ uravu/relationship.py | 179 +++++++++++++++--------------------------- uravu/sampling.py | 82 ++++++------------- uravu/utils.py | 33 ++++---- 6 files changed, 146 insertions(+), 246 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 610e2f8..c0aa29c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -193,4 +193,8 @@ def setup(app): intersphinx_mapping = { 'pint': ('https://pint.readthedocs.io/en/0.11/', None), 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), + 'uncertainties': ('https://uncertainties-python-package.readthedocs.io/en/latest/', None), + 'dynesty': ('https://dynesty.readthedocs.io/en/latest/', None), + 'emcee': ('https://emcee.readthedocs.io/en/stable/', None), } + diff --git a/uravu/optimize.py b/uravu/optimize.py index 8515ba1..56df180 100644 --- a/uravu/optimize.py +++ b/uravu/optimize.py @@ -1,7 +1,6 @@ """ -The optimize module includes the functionality necessary for maximum -likelihood determination. Further, the natural log likelihood function used -in the ``mcmc`` and ``nested_sampling`` methods may be found here. +The optimize module includes the functionality necessary for maximum likelihood determination. +Furthermore, the natural log likelihood function used in the :func:`~uravu.sampling.mcmc()` and :func:`~uravu.sampling.nested_sampling()` methods may be found here. """ # Copyright (c) Andrew R. McCluskey @@ -9,28 +8,20 @@ # author: Andrew R. McCluskey import numpy as np -import uncertainties from scipy.optimize import minimize from uncertainties import unumpy as unp def max_ln_likelihood(relationship, x0=None, **kwargs): """ - Determine the variable values which maximize the likelihood for the - given relationship. For keyword arguments see the - `scipy.optimize.minimize()`_ documentation. + Determine the variable values which maximize the likelihood for the given relationship. For keyword arguments see the :func:`scipy.optimize.minimize()` documentation. Args: - relationship (uravu.relationship.Relationship): The relationship for - which variables should be found. - x0 (array_like, optional): Initial guesses for the variable values. - Default to the current ``relationship.variables`` values which - are initialized as all ones. + relationship (:py:class:`uravu.relationship.Relationship`): The relationship for which variables should be found. + x0 (:py:attr:`array_like`, optional): Initial guesses for the variable values. Default to the current :py:attr:`~uravu.relationship.Relationship.variables` values which are initialized as all :py:attr:`1`. Return: - (array_like): optimized variables for the relationship. - - .. _scipy.optimize.minimize(): https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html + :py:attr:`array_like`: Optimized variables for the relationship. """ if x0 is None: x0 = relationship.variable_medians @@ -51,19 +42,17 @@ def negative_lnl( variables, function, abscissa, ordinate, unaccounted_uncertainty=False ): """ - Calculate the negative natural logarithm of the likelihood given a set - of variables, when there is no uncertainty in the abscissa. + Calculate the negative natural logarithm of the likelihood given a set of variables, when there is no uncertainty in the abscissa. Args: - variables (array_like): Variables for the function evaluation. - function (callable): The function to be evaluated. - abscissa (array_like): The abscissa values. - ordinate (array_like): The ordinate values. - unaccounted_uncertainty (bool, optional): Should an unaccounted - uncertainty parameter be considered. Default is ``False``. + variables (:py:attr:`array_like`): Variables for the function evaluation. + function (:py:attr:`callable`): The function to be evaluated. + abscissa (:py:attr:`array_like`): The abscissa values. + ordinate (:py:attr:`array_like`): The ordinate values. + unaccounted_uncertainty (:py:attr:`bool`, optional): Should an unaccounted uncertainty parameter be considered. Default is :py:attr:`False`. Returns: - (float): Negative ln-likelihood between model and data. + :py:attr:`float`: Negative natural log-likelihood between model and data. """ return -ln_likelihood( variables, @@ -78,19 +67,17 @@ def ln_likelihood( variables, function, abscissa, ordinate, unaccounted_uncertainty=False ): """ - Calculate the natural logarithm of the likelihood given a set of - variables, when there is no uncertainty in the abscissa. + Calculate the natural logarithm of the likelihood given a set of variables, when there is no uncertainty in the abscissa. Args: - variables (array_like): Variables for the function evaluation. - function (callable): The function to be evaluated. - abscissa (array_like): The abscissa values. - ordinate (array_like): The ordinate values. - unaccounted_uncertainty (bool, optional): Should an unaccounted - uncertainty parameter be considered. Default is ``False``. + variables (:py:attr:`array_like`): Variables for the function evaluation. + function (:py:attr:`callable`): The function to be evaluated. + abscissa (:py:attr:`array_like`): The abscissa values. + ordinate (:py:attr:`array_like`): The ordinate values. + unaccounted_uncertainty (:py:attr:`bool`, optional): Should an unaccounted uncertainty parameter be considered. Default is :py:attr:`False`. Returns: - (float): ln-likelihood between model and data. + :py:attr:`float`: Natural log-likelihood between model and data. """ if unaccounted_uncertainty: var = variables[:-1] diff --git a/uravu/plotting.py b/uravu/plotting.py index 8a09686..afcdaba 100644 --- a/uravu/plotting.py +++ b/uravu/plotting.py @@ -1,10 +1,7 @@ """ -These are plotting functions that take either :class:`Relationship` -or :class:`Distribution` class objects. +These are plotting functions that take either :py:class:`~uravu.relationship.Relationship` or :py:class:`~uravu.distribution.Distribution` class objects. -The aim is to produce *publication quality* plots. However, we -recognise that taste exists, and ours may be different from yours. -The colorscheme in this work was chosen to be colorblind friendly. +The aim is to produce *publication quality* plots. However, we recognise that taste exists, and ours may be different from yours. The colorscheme in this work was chosen to be colorblind friendly. """ # Copyright (c) Andrew R. McCluskey @@ -28,19 +25,15 @@ def plot_relationship( relationship, axes=None, figsize=(10, 6) ): # pragma: no cover """ - Plot the relationship. Additional plots will be included on this if - the MCMC sampling has been used to find distributions. + Plot the relationship. Additional plots will be included on this if the MCMC sampling has been used to find distributions. Args: - relationship (uravu.relationship.Relationship): The relationship to - be plotted. - axes (matplotlib.axes): Axes to which the plot should be added. - If none given new axes will be created. - fig_size (tuple, optional): horizontal and veritcal size for - figure (in inches). Default is `(10, 6)`. + relationship (:py:class:`uravu.relationship.Relationship`): The relationship to be plotted. + axes (:py:class:`matplotlib.axes.Axes`): Axes to which the plot should be added. If none given new axes will be created. + fig_size (:py:attr:`tuple`, optional): horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`. Returns: - (matplotlib.axes): The axes with new plots. + (:py:class:`matplotlib.axes.Axes`): The axes with new plots. """ if axes is None: axes = plt.subplots(figsize=figsize)[1] @@ -116,13 +109,11 @@ def plot_distribution(distro, axes=None, figsize=(10, 6)): # pragma: no cover Plot the probability density function for a distribution. Args: - distro (uravu.distriobution.Distribution): The distribution to be - plotted. - fig_size (tuple): Horizontal and veritcal size for figure - (in inches). + distro (:py:class`uravu.distriobution.Distribution`): The distribution to be plotted. + fig_size (:py:class:`tuple`): Horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`. Returns: - (matplotlib.axes): The axes with new plots. + (:py:class:`matplotlib.axes.Axes`): The axes with new plots. """ if axes is None: axes = plt.subplots(figsize=figsize)[1] @@ -158,15 +149,13 @@ def plot_corner(relationship, figsize=(8, 8)): # pragma: no cover relationships variables. Args: - relationship (uravu.relationship.Relationship): The relationship - containing the distributions to be plotted. - fig_size (tuple, optional): horizontal and veritcal size for - figure (in inches). Default is `(10, 6)`. + relationship (:py:class:`uravu.relationship.Relationship`): The relationship containing the distributions to be plotted. + fig_size (:py:attr:`tuple`, optional): horizontal and veritcal size for figure (in inches). Default is :py:attr:`(10, 6)`. Returns: - (tuple): Tuple consisting of: - - (matplotlib.figure): The figure with new plots. - - (matplotlib.axes): The axes with new plots. + :py:attr:`tuple`: Containing: + - (:py:class:`matplotlib.figure.Figure`): The figure with new plots. + - (:py:class:`matplotlib.axes.Axes`): The axes with new plots. """ n = len(relationship.variables) if not all( diff --git a/uravu/relationship.py b/uravu/relationship.py index 015dddf..c7e9209 100644 --- a/uravu/relationship.py +++ b/uravu/relationship.py @@ -1,12 +1,8 @@ """ -The ``Relationship`` class is a foundational component of the ``uravu`` -package, and acts as an API for use of the package. -This class enables the storage of the relationship between the model and -the data. +The :py:class:`~uravu.relationship.Relationship` class is a foundational component of the :py:mod:`uravu` package, and acts as the main API for use of the package. +This class enables the storage of the relationship between the model and the data. -Objects of this class offer easy methods to perform maximum likelihood -evaluation, Markiv chain Monte Carlo (MCMC) for posterior probabiltiy -determination and Bayesian evidence estimation by nested sampling. +Objects of this class offer easy methods to perform maximum likelihood evaluation, Markiv chain Monte Carlo (MCMC) for posterior probabiltiy determination and Bayesian evidence estimation by nested sampling. See the `tutorials online`_ for more guidence of how to use this package. @@ -29,60 +25,32 @@ class Relationship: """ - The ``Relationship`` class is the base of the ``uravu`` package, enabling - the use of Bayesian inference for the assessment of a model's ability to - describe some data. + The :py:class:`~uravu.relationship.Relationship` class is the base of the :py:mod:`uravu` package, enabling the use of Bayesian inference for the assessment of a model's ability to describe some data. Attributes: - function (callable): The function that is modelled. - abscissa (array_like with pint.UnitRegistry()): The abscissa data - that the modelling should be performed from. This includes some - unit from the `pint`_ package. - abscissa_name (str): A name for the abscissa data, used in the - production of plots. - ordinate (array_like with pint.UnitRegistry()): The ordinate - data against with the model should be compared. This may include - uncertainty values and some unit. - ordinate_name (str): A name for the ordinate data, used in the - production of plots. - unaccounted_uncertainty (bool): This boolean describes if an - unaccounted for uncertainty should be considered in the modelling - process. - ln_evidence (uncertainties.core.Variable): The natural-log of the - Bayesian evidence for the model to the given data. + function (:py:attr:`callable`): The function that is modelled. + abscissa (:py:attr:`array_like` with :py:class:`~pint.unit.Unit`): The abscissa data that the modelling should be performed from. This includes some unit from :py:class:`~pint.unit.Unit`. + abscissa_name (:py:attr:`str`): A name for the abscissa data, used in the production of plots. + ordinate (:py:attr:`array_like` with :py:class:`~pint.unit.Unit`): The ordinate data against with the model should be compared. This may include uncertainty values and some unit. + ordinate_name (:py:attr:`str`): A name for the ordinate data, used in the production of plots. + variables (:py:attr:`list` of :py:attr:`float` or :py:class:`~uravu.distribution.Distribution`): Variables in the :py:attr:`~uravu.relationship.Relationship.function`. + unaccounted_uncertainty (:py:attr:`bool`): This boolean describes if an unaccounted for uncertainty should be considered in the modelling process. + ln_evidence (:py:class:`uncertainties.core.Variable`): The natural-log of the Bayesian evidence for the model to the given data. + mcmc_results (:py:attr:`dict`): The results from :func:`emcee.EnsembleSampler.run_mcmc()` sampling. + nested_sampling_results (:py:attr:`dict`): The results from :func:`ddynesty.NestedSampler.run_nested()` nested sampling. Args: - function (callable): The functional relationship to be modelled. - abscissa (array_like): The abscissa data. If multi-dimensional, the - array is expected to have the shape `(N, d)`, where `N` is the - number of data points and `d` is the dimensionality. - ordinate (array_like): The ordinate data. This should have a - shape `(N,)`. - ordinate_uncertainty (array_like, optional): The uncertainty in each - of the ordinate data points. This should have a shape `(N,)`. - Default to no uncertainties on the ordiante. If there is no - ordinate uncertainty, an unaccounted uncertainty is automatically - added. - abscissa_unit (pint.UnitRegistry(), optional): The unit for the - abscissa. If `abscissa` is multi-dimensional, this should be a - list with the units for each dimension. Default is dimensionless. - ordinate_unit (pint.UnitRegistry(), optional): The unit for the - ordinate. Default is dimensionless. - abscissa_name (str, optional): A name for the abscissa. Default - is `'x'`. - ordinate_name (str, optional): A name for the ordinate. Default - is `'y'`. - variable_names (list of str, optional): Names for each of the - variables. Default is the variable name in the ``function`` - definition. - variable_units (pint.UnitRegistry(), optional): The units for the - variables. Default is dimensionless. - unaccounted_uncertainty (bool, optional): Describes if an additional - variable be included to account for an unknown uncertainty in the - data. - - .. _pint: https://pint.readthedocs.io/ - .. _uncertainties: https://uncertainties-python-package.readthedocs.io/ + function (:py:attr:`callable`): The functional relationship to be modelled. + abscissa (:py:attr:`array_like`): The abscissa data. If multi-dimensional, the array is expected to have the shape :py:attr:`(N, d)`, where :py:attr:`N` is the number of data points and :py:attr:`d` is the dimensionality. + ordinate (:py:attr:`array_like`): The ordinate data. This should have a shape :py:attr:`(N,)`. + ordinate_uncertainty (:py:attr:`array_like`, optional): The uncertainty in each of the ordinate data points. This should have a shape :py:attr:`(N,)`. Default to no uncertainties on the ordiante. If there is no ordinate uncertainty, an unaccounted uncertainty is automatically added. + abscissa_unit (:py:class:`~pint.unit.Unit`, optional): The unit for the :py:attr:`abscissa`. If :py:attr:`abscissa` is multi-dimensional, this should be a list with the units for each dimension. Default is :py:attr:`~pint.unit.Unit.dimensionless`. + ordinate_unit (:py:class:`~pint.unit.Unit`, optional): The unit for the :py:attr:`ordinate`. Default is :py:attr:`~pint.unit.Unit.dimensionless`. + abscissa_name (:py:attr:`str`, optional): A name for the :py:attr:`abscissa`. Default is :py:attr:`'x'`. + ordinate_name (:py:attr:`str`, optional): A name for the :py:attr:`ordinate`. Default is :py:attr:`'y'`. + variable_names (:py:attr:`list` of :py:attr:`str`, optional): Names for each of the variables. Default is the variable name in the :py:attr:`function` definition. + variable_units (:py:class:`~pint.unit.Unit`, optional): The units for the variables. Default is :py:attr:`~pint.unit.Unit.dimensionless`. + unaccounted_uncertainty (:py:attr:`bool`, optional): Describes if an additional variable be included to account for an unknown uncertainty in the data. """ def __init__( @@ -155,13 +123,15 @@ def __init__( ) self.variable_units = variable_units self.ln_evidence = None + self.mcmc_results = None + self.nested_sampling_results = None def __str__(self): """ A custom string function. Returns: - (str): Custom string description. + :py:attr:`str`: Custom string description. """ string = "Function Name: {} \n".format(self.function.__name__) if self.abscissa.shape[0] < 4: @@ -236,7 +206,7 @@ def __repr__(self): A custom representation. Returns: - (str): Custom string description. + :py:attr:`str`: Custom string description. """ return self.__str__() @@ -246,7 +216,7 @@ def x(self): Abscissa values with unit and uncertainty (where present). Returns: - (array_like): Abscissa values. + :py:attr:`array_like`: Abscissa values. """ return self.abscissa @@ -256,7 +226,7 @@ def y(self): Ordinate values with unit and uncertainty. Returns: - (array_like): Ordinate values. + :py:attr:`array_like`: Ordinate values. """ return self.ordinate @@ -266,7 +236,7 @@ def x_m(self): Abscissa values without units. Returns: - (array_like): Abscissa values without units. + :py:attr:`array_like`: Abscissa values without units. """ return self.abscissa.m @@ -276,7 +246,7 @@ def y_m(self): Ordinate values without units. Returns: - (array_like): Ordinate values without units. + :py:attr:`array_like`: Ordinate values without units. """ return self.ordinate.m @@ -286,7 +256,7 @@ def x_u(self): Abscissa unit. Returns: - (pint.UnitRegistry()): Abscissa values. + :py:class:`~pint.unit.Unit`: Abscissa values. """ return self.abscissa.u @@ -296,7 +266,7 @@ def y_u(self): Ordinate unit. Returns: - (pint.UnitRegistry()): Ordinate unit. + :py:class:`~pint.unit.Unit`: Ordinate unit. """ return self.ordinate.u @@ -306,7 +276,7 @@ def x_n(self): Abscissa nominal values. Returns: - (array_like): Abscissa nominal values. + :py:attr:`array_like`: Abscissa nominal values. """ return unp.nominal_values(self.abscissa.m) @@ -316,7 +286,7 @@ def y_n(self): Ordinate nominal values. Returns: - (array_like): Ordinate nominal values. + :py:attr:`array_like`: Ordinate nominal values. """ return unp.nominal_values(self.ordinate.m) @@ -326,7 +296,7 @@ def y_s(self): Ordinate uncertainties. Returns: - (array_like): Ordinate uncertainties. + :py:attr:`array_like`: Ordinate uncertainties. """ if isinstance( self.ordinate.m.any(), uncertainties.core.AffineScalarFunc @@ -341,7 +311,7 @@ def variable_medians(self): The median values for each of the variables. Returns: - (array_like): The variable medians. + :py:attr:`array_like`: Variable medians. """ medians = np.zeros((len(self.variables))) for i, var in enumerate(self.variables): @@ -354,10 +324,10 @@ def variable_medians(self): @property def mcmc_done(self): """ - Has MCMC been performed, determined based on the type of the variables. + Has MCMC been performed? Determined based on the type of the variables. Returns: - (bool): Has MCMC been performed. + :py:attr:`bool`: Has MCMC been performed? """ for var in self.variables: if isinstance(var, Distribution): @@ -367,11 +337,10 @@ def mcmc_done(self): @property def nested_sampling_done(self): """ - Has nested sampling been performed, determined based on if the - ln_evidence has a value. + Has nested sampling been performed? Determined based on if the ln_evidence has a value. Returns: - (bool): Has nested sampling been performed. + :py:attr:`bool`: Has nested sampling been performed? """ if self.ln_evidence is not None: return True @@ -380,10 +349,10 @@ def nested_sampling_done(self): @property def citations(self): """ - Return the relevant citations. + Return the relevant references based on the analysis performed. Returns: - (str): The citations relevant to the analysis performed. + :py:attr:`str`: Relevant references. """ string = "Please consider citing the following:\n" string += " - Publication of uravu (to come).\n" @@ -451,7 +420,7 @@ def len_parameters(self): Determine the number of variables in the assessment function. Returns: - (int): number of variables. + :py:attr`int`: Number of variables. """ # The minus one is to remove the abscissa data which is a # argument in the assessment function @@ -461,10 +430,12 @@ def len_parameters(self): def bayesian_information_criteria(self): """ - Calculate the Bayesian information criteria for the relationship. + Calculate the `Bayesian information criteria`_ for the relationship. Returns: - (float): Bayesian information criteria. + :py:attr:`float`: Bayesian information criteria. + + .. _Bayesian information criteria: https://en.wikipedia.org/wiki/Bayesian_information_criterion """ self.max_likelihood() return np.log( @@ -479,24 +450,19 @@ def bayesian_information_criteria(self): def max_likelihood(self, x0=None, **kwargs): """ - Determine values for the variables which maximise the likelihood - for the relationship. For keyword arguments see the - `scipy.optimize.minimize()`_ documentation. - - .. _scipy.optimize.minimize(): https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html + Determine values for the variables which maximise the likelihood for the :py:class:`~uravu.relationship.Relationship`. For keyword arguments see the :func:`scipy.optimize.minimize()` documentation. + + Args: + x0 (:py:attr:`array_like`): Initial guess values for the parameters. """ self.variables = optimize.max_ln_likelihood(self, x0, **kwargs) def prior(self): """ - *Standard priors* for the relationship. These priors are broad, - uninformative, for normal variables running the range - [x - x * 10, x + x * 10) (where x is the variable). For an unaccounted - uncertainty natural log factor the range is [-10, 1). + *Standard priors* for the relationship. These priors are broad, uninformative, for normal variables running the range :py:attr:`[x - x * 10, x + x * 10)` (where :py:attr:`x` is the variable value). For an unaccounted uncertainty natural log factor the range is :py:attr:`[-10, 1)`. Returns: - (list of scipy.stats.rv_continuous): scipy.stats functions - describing the priors. + :py:attr:`list` of :py:class:`scipy.stats.rv_continuous`: :py:mod:`scipy.stats` functions describing the priors. """ priors = [] for var in self.variable_medians: @@ -517,22 +483,14 @@ def mcmc( seed=None ): """ - Perform MCMC to get the posterior probability distributions for - the variables of the relationship. Note running this method will - populate the `relationship.variables` attribute with - `uravu.distribution.Distribution` objects. + Perform MCMC to get the posterior probability distributions for the variables of the relationship. *Note*, running this method will populate the :py:attr:`~uravu.relationship.Relationship.variables` attribute with :py:class:`~uravu.distribution.Distribution` objects. Args: - prior_function (callable, optional): the function to populated - some prior distributions. Default is the broad uniform - priors in uravu.relationship.Relationship. - walkers (int, optional): Number of MCMC walkers. Default is `100`. - n_samples (int, optional): Number of sample points. Default - is `500`. - n_burn (int, optional): Number of burn in samples. Default - is `500`. - progress (bool, optional): Show tqdm progress for sampling. - Default is `True`. + prior_function (:py:attr:`callable`, optional): The function to populated some prior distributions. Default is the broad uniform priors in :func:`~uravu.relationship.Relationship.prior()`. + walkers (:py:attr:`int`, optional): Number of MCMC walkers. Default is :py:attr:`100`. + n_samples (:py:attr:`int`, optional): Number of sample points. Default is :py:attr:500`. + n_burn (:py:attr:`int`, optional): Number of burn in samples. Default is :py:attr:`500`. + progress (:py:attr:`bool`, optional): Show :py:mod:`tqdm` progress for sampling. Default is :py:attr:`True`. """ self.mcmc_results = sampling.mcmc( self, @@ -546,18 +504,11 @@ def mcmc( def nested_sampling(self, prior_function=None, progress=True, **kwargs): """ - Perform nested sampling to determine the Bayesian - natural-log evidence. For keyword arguments see the - `dynesty.run_nested()`_ documentation. + Perform nested sampling to determine the Bayesian natural-log evidence. For keyword arguments see the :func:`dynesty.NestedSampler.run_nested()` documentation. Args: - prior_function (callable, optional): the function to populated some - prior distributions. Default is the broad uniform priors in - uravu.relationship.Relationship. - progress (bool, optional): Show tqdm progress for sampling. - Default is `True`. - - .. _dynesty.run_nested(): https://dynesty.readthedocs.io/en/latest/api.html#dynesty.sampler.Sampler.run_nested + prior_function (:py:attr:`callable`, optional): The function to populate some prior distributions. Default is the broad uniform priors in :func:`~uravu.relationship.Relationship.prior()`. + progress (:py:attr:`bool`, optional): Show :py:mod:`tqdm` progress for sampling. Default is :py:attr:`True`. """ self.nested_sampling_results = sampling.nested_sampling( self, prior_function=prior_function, progress=progress, **kwargs diff --git a/uravu/sampling.py b/uravu/sampling.py index e03a53e..247b1ce 100644 --- a/uravu/sampling.py +++ b/uravu/sampling.py @@ -1,10 +1,5 @@ """ -The :mod:`sampling` module implements the use of a generalised -MCMC (using `emcee`_) and nested sampling (using `dynesty`_) for the -:class:`Relationship` objects. - -.. _emcee: https://emcee.readthedocs.io/ -.. _dynesty: https://dynesty.readthedocs.io/ +The :mod:`sampling` module implements the use of a generalised MCMC (using :py:mod:`emcee`) and nested sampling (using :py:mod:`dynesty`) for the :py:class:`~uravu.relationship.Relationship` objects. """ # Copyright (c) Andrew R. McCluskey @@ -27,27 +22,18 @@ def mcmc( progress=True, ): """ - Perform MCMC to get the probability distributions for the variables - of the relationship. + Perform MCMC to get the probability distributions for the variables of the relationship. Args: - relationship (uravu.relationship.Relationship): The relationship to - determine the posteriors of. - prior_function (callable, optional): The function to populated some - prior distributions. Default is - uravu.relationship.Relationship.prior. - walkers (int, optional): Number of MCMC walkers. Default is `100`. - n_samples (int, optional): Number of sample points. Default is - `500`. - n_burn (int, optional): Number of burn in samples. Default is - `500`. - progress (bool, optional): Show tqdm progress for sampling. - Default is `True`. + relationship (:py:class:`uravu.relationship.Relationship`): The relationship to determine the posteriors of. + prior_function (:py:attr:`callable`, optional): The function to populated some prior distributions. Default is :func:`uravu.relationship.Relationship.prior()`. + walkers (:py:attr:`int`, optional): Number of MCMC walkers. Default is :py:attr:`100`. + n_samples (:py:attr:`int`, optional): Number of sample points. Default is :py:attr:`500`. + n_burn (:py:attr:`int`, optional): Number of burn in samples. Default is :py:attr:`500`. + progress (:py:attr:`bool`, optional): Show tqdm progress for sampling. Default is :py:attr:`True`. Returns: - (dict): a dictionary with the Distrbutions as a list - ('distributions'), the chain ('chain') and the samples as an - ``array_like`` ('samples'). + :py:attr:`dict`: Dictionary with the distributions as a list (:py:attr:`'distributions'`), the chain (:py:attr:`'chain'`) and the samples as an :py:attr:`array_like` (:py:attr:`'samples'`). """ if prior_function is None: prior_function = relationship.prior @@ -101,19 +87,15 @@ def ln_probability( summing the prior and likelihood. Args: - variables (array_like): Variables for the function evaluation. - function (callable): The function to be evaluated. - abscissa (array_like): The abscissa values. - ordinate (array_like): The ordinate values. - unaccounted_uncertainty (bool): Should an unaccounted - uncertainty parameter be considered. - prior_function (callable, optional): The function to populated some - prior distributions. Default is - uravu.relationship.Relationship.prior. + variables (:py:attr:`array_like`): Variables for the function evaluation. + function (:py:attr:`callable`): The function to be evaluated. + abscissa (:py:attr:`array_like`): The abscissa values. + ordinate (:py:attr:`array_like`): The ordinate values. + unaccounted_uncertainty (:py:attr:`bool`): Should an unaccounted uncertainty parameter be considered. + prior_function (:py:attr:`callable`, optional): The function to populated some prior distributions. Default is :func:`~uravu.relationship.Relationship.prior()`. Returns: - (float): Negative ln-probability between model and data, considering - priors. + :py:attr:`float`: Negative natural log-probability between model and data, considering priors. """ log_prior = 0 for i, var in enumerate(variables): @@ -129,23 +111,16 @@ def nested_sampling( relationship, prior_function=None, progress=True, **kwargs ): """ - Perform the nested sampling in order to determine the Bayesian natural log - evidence. + Perform the nested sampling in order to determine the Bayesian natural log evidence. See the :py:func:`dynesty.NestedSampler.run_nested()` documentation. Args: - relationship (uravu.relationship.Relationship): The relationship to - estimate the evidence for. - prior_function (callable, optional): the function to populated some - prior distributions. Default is the broad uniform priors in - uravu.relationship.Relationship. - progress (bool, optional): Show tqdm progress for sampling. - Default is `True`. - - Keyword Args: - See the `dynesty.run_nested()` documentation. + relationship (:py:class:`~uravu.relationship.Relationship`): The relationship to estimate the evidence for. + prior_function (:py:attr:`callable`, optional): The function to populated some prior distributions. Default is the broad uniform priors in + :func:`~uravu.relationship.Relationship.prior()`. + progress (:py:attr:`bool`, optional): Show :py:mod:`tqdm` progress for sampling. Default is :py:attr:`True`. Returns: - (dict): The results from the dynesty run. + :py:attr:`dict`: The results from :py:func:`dynesty.NestedSampler.run_nested()`. """ if prior_function is None: prior_function = relationship.prior @@ -170,19 +145,14 @@ def nested_sampling( def nested_prior(array, priors): """ - Convert to dynesty prior style from at used within ``uravu``. + Convert to dynesty prior style from at used within :py:mod:`uravu`. Args: - array (array_like): An array of random uniform numbers (0, 1]. - The shape of which is M x N, where M is the number of - parameters and N is the number of walkers. - prior_function (callable, optional): The function to populated some - prior distributions. Default is - uravu.relationship.Relationship.prior. + array (:py:attr:`array_like`): An array of random uniform numbers (0, 1]. The shape of which is M x N, where M is the number of parameters and N is the number of walkers. + prior_function (:py:attr:`callable`, optional): The function to populated some prior distributions. Default is :func:`uravu.relationship.Relationship.prior()`. Returns: - (array_like): an array of random uniform numbers distributed in - agreement with the priors. + :py:attr:`array_like`: An array of random uniform numbers distributed in agreement with the priors. """ broad = np.copy(array) for i, prior in enumerate(priors): diff --git a/uravu/utils.py b/uravu/utils.py index c3668d0..591a876 100644 --- a/uravu/utils.py +++ b/uravu/utils.py @@ -17,45 +17,44 @@ def straight_line(abscissa, gradient, intercept): A one dimensional straight line function. Args: - abscissa (array_like): the abscissa data. - gradient (float): the slope of the line. - intercept (float): the y-intercept of the line. + abscissa (:py:attr:`array_like`): The abscissa data. + gradient (:py:attr:`float`): The slope of the line. + intercept (:py:attr:`float`): The y-intercept of the line. Returns: - (array_like): the resulting ordinate. + :py:attr:`array_like`: The resulting ordinate. """ return gradient * abscissa + intercept def bayes_factor(model_1, model_2): """ - Use the Bayes factor to compare two models. + Use the `Bayes factor`_ to compare two models. Using Table from `Kass and Raftery`_ to compare. Args: - model_1 (uncertainties.core.Variable or float): ln evidence for - model 1. - model_2 (uncertainties.core.Variable or float): ln evidence for - model 2. + model_1 (:py:class:`uncertainties.core.Variable` or :py:attr:`float`): ln evidence for model 1. + model_2 (:py:class:`uncertainties.core.Variable` or :py:attr:`float`): ln evidence for model 2. Return: - (uncertainties.core.Variable or float): 2ln(B) where B is the Bayes - Factor between the two models. + :py:class:`uncertainties.core.Variable` or :py:attr:`float`: 2ln(B), where B is the Bayes Factor between the two models. + + .. _Bayes factor: https://en.wikipedia.org/wiki/Bayes_factor + .. _Kass and Raftery: https://www.colorado.edu/amath/sites/default/files/attached-files/kassraftery95.pdf """ return 2 * (model_1 - model_2) def correlation_matrix(relationship): """ - Evalutate the Pearsons correlation coefficient matrix for the - variables in a given relationship. + Evalutate the `Pearsons correlation coefficient`_ matrix for the variables in a given relationship. Args: - relationship (uravu.relationship.Relationship): The relationship - to determine the posteriors of. + relationship (:py:class:`uravu.relationship.Relationship`): The relationship to determine the correlation matrix for. Returns: - (array_like): The correlation matrix for the relationships - variables. + :py:attr:`array_like`: The correlation matrix for the relationships variables. + + .. _Pearsons correlation coefficient: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient """ n = len(relationship.variables) matrix = np.zeros((n, n))