0.10.1

Author: Samreay

README.md

@@ -48,12 +48,25 @@ Which compiles to something as shown below:
 
 -----------
 
+### Installation
 
 Install via `pip`:
 
     pip install chainconsumer
 
 
+----------
+
+## Contributing
+
+Users that wish to contribute to this project may do so in a number of ways.
+Firstly, for any feature requests, bugs or general ideas, please raise an issue
+via [Github](https://github.com/samreay/ChainConsumer/issues).
+
+If you wish to contribute code to the project, please simple fork the project on
+Github and then raise a pull request. Pull requests will be reviewed to determine
+whether the changes are major or minor in nature, and to ensure all changes are tested.
+
 ----------
 
 Please feel free to fork the project and open pull-requests, or

chainconsumer/chain.py

@@ -14,7 +14,7 @@ class ChainConsumer(object):
     """ A class for consuming chains produced by an MCMC walk
 
     """
-    __version__ = "0.10.0"
+    __version__ = "0.10.1"
 
     def __init__(self):
         logging.basicConfig()
@@ -44,12 +44,14 @@ def add_chain(self, chain, parameters=None, name=None, weights=None, posterior=N
         ----------
         chain : str|ndarray|dict
             The chain to load. Normally a ``numpy.ndarray``. If a string is found, it
-             interprets the string as a filename and attempts to load it in. If a ``dict``
-             is passed in, it assumes the dict has keys of parameter names and values of
-             an array of samples. Notice that using a dictionary puts the order of
-             parameters in the output under the control of the python ``dict.keys()`` function.
+            interprets the string as a filename and attempts to load it in. If a ``dict``
+            is passed in, it assumes the dict has keys of parameter names and values of
+            an array of samples. Notice that using a dictionary puts the order of
+            parameters in the output under the control of the python ``dict.keys()`` function.
         parameters : list[str], optional
-            A list of parameter names, one for each column (dimension) in the chain.
+            A list of parameter names, one for each column (dimension) in the chain. This parameter
+            should remain ``None`` if a dictionary is given as ``chain``, as the parameter names
+            are taken from the dictionary keys.
         name : str, optional
             The name of the chain. Used when plotting multiple chains at once.
         weights : ndarray, optional
@@ -164,6 +166,12 @@ def configure_general(self, bins=None, flip=True, rainbow=None, colours=None,
             How much to smooth the marginalised distributions using a gaussian filter.
             If ``kde`` is set to true, this parameter is ignored. Setting it to either
             ``0``, ``False`` or ``None`` disables smoothing.
+
+
+        Returns
+        -------
+        ChainConsumer
+            Itself, to allow chaining calls.
         """
         assert rainbow is None or colours is None, \
             "You cannot both ask for rainbow colours and then give explicit colours"
@@ -233,6 +241,11 @@ def configure_contour(self, sigmas=None, cloud=None, shade=None,
         shade_alpha : float|list[float], optional
             Filled contour alpha value override. Default is 1.0. If a list is passed, you can set the
             shade opacity for specific chains.
+
+        Returns
+        -------
+        ChainConsumer
+            Itself, to allow chaining calls.
         """
         num_chains = len(self.chains)
 
@@ -276,13 +289,20 @@ def configure_bar(self, summary=None, shade=None):  # pragma: no cover
         chain consumer, as the consume changes configuration values depending on
         the supplied data.
 
+        Parameters
+        ----------
         summary : bool, optional
             If overridden, sets whether parameter summaries should be set as axis titles.
             Will not work if you have multiple chains
         shade : bool|list[bool], optional
             If set to true, shades in confidence regions in under histogram. By default
             this happens if you less than 3 chains, but is disabled if you are comparing
             more chains. You can pass a list if you wish to shade some chains but not others.
+
+        Returns
+        -------
+        ChainConsumer
+            Itself, to allow chaining calls.
         """
         if summary is not None:
             summary = summary and len(self.chains) == 1
@@ -306,6 +326,16 @@ def configure_truth(self, **kwargs):  # pragma: no cover
         if you want some basic control.
 
         Default is to use an opaque black dashed line.
+
+        Parameters
+        ----------
+        kwargs : dict
+            The keyword arguments to unwrap when calling ``axvline`` and ``axhline``.
+
+        Returns
+        -------
+        ChainConsumer
+            Itself, to allow chaining calls.
         """
         if kwargs.get("ls") is None and kwargs.get("linestyle") is None:
             kwargs["ls"] = "--"
@@ -449,6 +479,11 @@ def get_parameter_text(self, lower, maximum, upper, wrap=False):
             The upper bound on the parameter
         wrap : bool
             Wrap output text in dollar signs for LaTeX
+
+        Returns
+        -------
+        str
+            The formatted text given the parameter bounds
         """
         if lower is None or upper is None:
             return ""
@@ -488,7 +523,30 @@ def get_parameter_text(self, lower, maximum, upper, wrap=False):
             text = "$%s$" % text
         return text
 
-    def divide_chain(self, i, num_walkers):
+    def divide_chain(self, num_walkers, i=0):
+        """
+        Returns a ChainConsumer instance containing ``num_walker`` chains,
+        each formed by splitting the ``i``th chain ``num_walker`` times.
+
+        This method might be useful if, for example, your chain was made using
+        MCMC with 4 walkers. To check the sampling of all 4 walkers agree, you could
+        call this with ``num_walkers=4`` and plot, and hopefully all four contours
+        you would see all agree.
+
+        Parameters
+        ----------
+        num_walkers : int
+            How many walkers (with equal number of samples) compose
+            this chain.
+        i : int,optional
+            The index of the chain you wish to divide
+
+        Returns
+        -------
+        ChainConsumer
+            A new ChainConsumer instance with the same settings as the parent instance, containing
+            ``num_walker`` chains.
+        """
         cs = np.split(self.chains[i], num_walkers)
         ws = np.split(self.weights[i], num_walkers)
         con = ChainConsumer()

doc/chain_api.rst

@@ -5,6 +5,10 @@
 Chain Consumer API
 ==================
 
+.. autosummary:: chainconsumer.ChainConsumer
+    :members:
+    :undoc-members:
+
 .. autoclass:: chainconsumer.ChainConsumer
     :members:
     :undoc-members:

doc/index.rst

@@ -2,9 +2,11 @@
 ChainConsumer
 =============
 
-I wrote this code after realising that the fantastic library
-`corner <https://github.com/dfm/corner.py>`_ could not plot everything I
-wanted to plot. And so here we are!
+ChainConsumer is a python package designed to do one thing - consume the chains
+output from Monte Carlo processes like MCMC. ChainConsumer can utilise these chains
+to produce plots of the posterior surface inferred from the chain distributions,
+to plot the chains as walks (to check for mixing and convergence), and to output
+parameter summaries in the form of LaTeX tables.
 
 To get things started, here is a basic example:
 
@@ -38,10 +40,24 @@ Contents
    chain_api
    examples/index
 
+Installation
+------------
+
 ChainConsumer requires the following dependencies:
 
 .. literalinclude:: ../requirements.txt
 
 ChainConsumer can be installed as follows::
 
-    pip install chainconsumer
+    pip install chainconsumer
+
+Contributing
+------------
+
+Users that wish to contribute to this project may do so in a number of ways.
+Firstly, for any feature requests, bugs or general ideas, please raise an issue
+via `Github <https://github.com/samreay/ChainConsumer/issues>`_.
+
+If you wish to contribute code to the project, please simple fork the project on
+Github and then raise a pull request. Pull requests will be reviewed to determine
+whether the changes are major or minor in nature, and to ensure all changes are tested.

doc/make.bat

@@ -86,8 +86,16 @@ if "%1" == "html" (
 	goto end
 )
 
+if "%1" == "htmlfull" (
+	%SPHINXBUILD% -E -a -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
 if "%1" == "rst" (
-	sphinx-apidoc -fM -o . ../dessn
+	sphinx-apidoc -fM -o . ../chainconsumer
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Made rst

paper/paper.bib

@@ -9,6 +9,32 @@ @article{matplotlib
     doi = {10.1109/MCSE.2007.55}
 }
 
+@Misc{scipy,
+  author =    {Eric Jones and Travis Oliphant and Pearu Peterson and others},
+  title =     {{SciPy}: Open source scientific tools for {Python}},
+  year =      {2001--},
+  url = "http://www.scipy.org/"
+}
+
+@article{numpy,
+ author = {Walt, Stefan van der and Colbert, S. Chris and Varoquaux, Gael},
+ title = {The NumPy Array: A Structure for Efficient Numerical Computation},
+ journal = {Computing in Science and Engg.},
+ issue_date = {March 2011},
+ volume = {13},
+ number = {2},
+ month = mar,
+ year = {2011},
+ issn = {1521-9615},
+ pages = {22--30},
+ numpages = {9},
+ url = {http://dx.doi.org/10.1109/MCSE.2011.37},
+ doi = {10.1109/MCSE.2011.37},
+ acmid = {1957466},
+ publisher = {IEEE Educational Activities Department},
+ address = {Piscataway, NJ, USA},
+ keywords = {NumPy, Python, Python, NumPy, scientific programming, numerical computations, programming libraries, numerical computations, programming libraries, scientific programming},
+}
 @online{github,
   author = {Samuel Hinton},
   title = {ChainConsumer},
@@ -22,5 +48,5 @@ @misc{zenodo
   title = {ChainConsumer},
   doi = {10.5281/zenodo.58511},
   year = 2016,
-  howpublished = {\url{http://dx.doi.org/10.5281/zenodo.58511}}
+  howpublished = {\url{http://dx.doi.org/10.5281/zenodo.60315}}
 }

paper/paper.json

@@ -4,10 +4,10 @@
   "author": [
     "Samuel Hinton"
   ],
-  "identifier": "http://dx.doi.org/10.5281/zenodo.58511",
+  "identifier": "http://dx.doi.org/10.5281/zenodo.60315",
   "codeRepository": "https://github.com/samreay/ChainConsumer",
   "datePublished": "2016-07-24",
-  "dateModified": "2016-07-24",
+  "dateModified": "2016-08-26",
   "dateCreated": "2016-07-24",
   "description": "A software package to consume chains produced by MCMC and similar algorithms, to provide likelihood surfaces, chain visualisations and parameter summaries in the form of LaTeX tables.",
   "keywords": "Python, visualization, mcmc",

paper/paper.md

@@ -31,7 +31,8 @@ the functionality to plot the chains as a series of walks in
 parameter values, which provides an easy visual check on chain 
 mixing and chain convergence.
 
-Plotting is performed via the matplotlib library [@matplotlib]. 
+Plotting is performed via the matplotlib library [@matplotlib], and 
+makes use of various numpy [@numpy] and scipy [@scipy] functions.
 
 Code archives can be found on Zenodo at [@zenodo] and any
 bugs or feature requests can be opened as issues on the Github

setup.py

@@ -47,6 +47,7 @@ def run_tests(self):
       author="Samuel Hinton",
       author_email="[email protected]",
       requires=["numpy", "scipy", "matplotlib", "statsmodels"],
+      install_requires=["numpy", "scipy", "matplotlib", "statsmodels"],
       tests_require=["pytest","pytest-cov"],
       cmdclass={"test": PyTest},
 )