more docs

README.rst

@@ -10,11 +10,13 @@ GetDist
   :target: https://secure.travis-ci.org/cmbant/getdist
 .. image:: http://img.shields.io/pypi/v/GetDist.svg?style=flat
         :target: https://pypi.python.org/pypi/GetDist/
+.. image:: https://readthedocs.org/projects/getdist/badge/?version=latest
+   :target: https://getdist.readthedocs.org/en/latest
 
 Description
 ============
 
-GetDist is a package for analysing Monte Carlo samples, including correlated samples
+GetDist is a Python package for analysing Monte Carlo samples, including correlated samples
 from Markov Chain Monte Carlo (MCMC).
 
 * **Point and click GUI** - select chain files, view plots, marginalized constraints, latex tables and more
@@ -24,7 +26,8 @@ from Markov Chain Monte Carlo (MCMC).
 * **Convergence diagnostics** - including correlation length and diagonalized Gelman-Rubin statistics
 * **Latex tables** for marginalized 1D constraints
 
-See the `Plot Gallery and tutorial <https://github.com/cmbant/getdist/blob/master/docs/plot_gallery.ipynb>`_.
+See the `Plot Gallery and tutorial <https://github.com/cmbant/getdist/blob/master/docs/plot_gallery.ipynb>`_
+and `GetDist API reference <http://getdist.readthedocs.org/en/latest/index.html>`_.
 
 
 Getting Started
@@ -118,9 +121,9 @@ Loading samples
 To load an MCSamples object from text files do::
 
 	 from getdist import loadMCSamples
-	 samples = loadMCSamples('/path/to/xxx', dist_settings={'ignore_rows':0.3})
+	 samples = loadMCSamples('/path/to/xxx', settings={'ignore_rows':0.3})
 
-Here *dist_settings* gives optional parameter settings for the analysis. *ignore_rows* is useful for MCMC chains where you want to
+Here *settings* gives optional parameter settings for the analysis. *ignore_rows* is useful for MCMC chains where you want to
 discard some fraction from the start of each chain as burn in (use a number >0 to discard a fixed number of sample lines rather than a fraction).
 The MCSamples object can be passed to plot functions, or used to get many results. For example to plot marginalized parameter densities 
 for parameter names *x1* and *x2*::

docs/source/analysis_settings.rst

@@ -0,0 +1,9 @@
+Analysis settings
+==================================
+
+Samples are analysed using various analysis settings. These can be specified from a .ini file or overridden using a dictionary.
+
+Default settings from analysis_defaults.ini:
+
+.. literalinclude:: ../../getdist/analysis_defaults.ini
+   :language: ini

docs/source/conf.py

@@ -16,7 +16,7 @@
 import os
 import shlex
 
-# autoclass_content = 'both'
+autoclass_content = 'both'
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -41,7 +41,7 @@
                        'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                        'matplotlib': ('http://matplotlib.sourceforge.net/', None)}
 
-plot_formats = [('png', 80)]
+# plot_formats = [('png', 80)]
 plot_html_show_formats = False
 plot_html_show_source_link = False
 

docs/source/gui.rst

@@ -0,0 +1,42 @@
+GetDist GUI
+===================
+
+Run the GetDistGUI.py script to run the graphical user interface. This requires PySide to be installed, but will run on Windows, Linux and Mac.
+
+It allows you to open a folder of chain files, then easily select, open, plot and compare, as well as viewing standard GetDist outputs and tables.
+
+.. image:: http://cosmologist.info/cosmomc/pics/planck2015/gui_planck.png
+
+
+It can open chain files in a selected directry (and also `paramgrid <http://cosmologist.info/cosmomc/readme_grids.html>`_ directories as show above).
+See the `intro` for a description of chain file formats.
+
+After opening a directory, you can select each chain root name you want to plot. It is then added to the list box below. 
+The selected chains can be dragged and dropped to change the order if needed.  Then select the parameter names to plot in the checkboxes below that.
+
+The Gui supports 1D, 2D (line and filled), 3D (select two parameters and "color by"), and triangle and rectangle plots.
+
+Script preview
+###############
+
+Use the option on the File menu to export a plot as-is to PDF or other image file. For better quality (i.e. not formatted for the current window shape) 
+and fine control (e.g. add custom legend text, etc), export the script, edit and then run it separately. 
+The Script Preview tab also gives a convenient way to view the script for the current plot,
+and preview exactly what it will produce when run:
+
+.. image:: http://cosmologist.info/cosmomc/pics/planck2015/gui_script.png
+
+You can also edit and customize the script, or open and play with existing plot scripts.
+
+Statistics and tables
+######################
+
+The Data menu has an option to let you view the parameter statistics (.margestats) and latex tables, convergence stats, and view PCA constraints for 
+selected parameters. Note that you need a working latex installation to view rendered parameter tables.
+
+
+Settings
+###########
+
+The Options menu allows you to change a settings defining how limits, lines and contours are calculated, and customize plot options. 
+The "Plot module config" option lets you use a different module to define the plotting functions (the default is getdist.plots).

docs/source/index.rst

@@ -1,19 +1,28 @@
 GetDist
 ==================================
 
-GetDist is a Python package for analysing Monte Carlo samples, including correlated samples
-from Markov Chain Monte Carlo (MCMC). To get started see the `home page <https://github.com/cmbant/getdist/>`_ 
-or `Plot Gallery and tutorial <https://github.com/cmbant/getdist/blob/master/docs/plot_gallery.ipynb>`_.
+GetDist is a Python package for analysing and plotting Monte Carlo (or other) samples.
 
-Main high-level modules:
+.. toctree::
+   :maxdepth: 1
+
+   Introduction <intro>
+   Plot gallery and tutorial <https://github.com/cmbant/getdist/blob/master/docs/plot_gallery.ipynb>
+   GetDist GUI program <gui>
+
+High-level modules for analysing samples and plotting:
 
 .. toctree::
    :maxdepth: 2
 
    mcsamples
    plots
 
-See also :doc:`analysis_settings`.
+See also:
+
+.. toctree::
+
+	analysis_settings
 
 Other main modules:
 

docs/source/intro.rst

@@ -0,0 +1,3 @@
+.. title:: Introduction
+
+.. include:: ../../README.rst

getdist/mcsamples.py

@@ -108,9 +108,7 @@ class MCSamples(Chains):
     """
 
     def __init__(self, root=None, jobItem=None, ini=None, settings=None, ranges=None, **kwargs):
-        """
-        Initialize the MCSamples instance.
-        
+        """        
         For a description of the various analysis settings and default values see
         `analysis_defaults.ini <https://github.com/cmbant/getdist/blob/master/getdist/analysis_defaults.ini>`_.
 
@@ -1034,7 +1032,7 @@ def getAutoBandwidth1D(self, bins, par, param, mult_bias_correction_order=None,
         For details see the `notes <http://cosmologist.info/notes/GetDist.pdf>`_.
 
         :param bins: numpy array of binned weights for the samples
-        :param par: A :class:`~paramnames.ParamInfo` instance for the parameter to analyse
+        :param par: A :class:`~.paramnames.ParamInfo` instance for the parameter to analyse
         :param param: index of the parameter to use
         :param mult_bias_correction_order: order of multiplicative bias correction (0 is basic Parzen kernel); by default taken from instance settings.
         :param kernel_order: order of the kernel (0 is Parzen, 1 does linear boundary correction, 2 is a higher-order kernel) 
@@ -1066,8 +1064,8 @@ def getAutoBandwidth2D(self, bins, parx, pary, paramx, paramy, corr, rangex, ran
         For details see the `notes <http://cosmologist.info/notes/GetDist.pdf>`_.
 
         :param bins: 2D numpy array of binned weights
-        :param parx: A :class:`~paramnames.ParamInfo` instance for the x parameter
-        :param pary: A :class:`~paramnames.ParamInfo` instance for the y parameter
+        :param parx: A :class:`~.paramnames.ParamInfo` instance for the x parameter
+        :param pary: A :class:`~.paramnames.ParamInfo` instance for the y parameter
         :param paramx: index of the x parameter
         :param paramy: index of the y parameter
         :param corr: correlation of the samples
@@ -1076,7 +1074,7 @@ def getAutoBandwidth2D(self, bins, parx, pary, paramx, paramy, corr, rangex, ran
         :param base_fine_bins_2D: number of bins to use for re-binning in rotated parameter space
         :param mult_bias_correction_order: multiplicative bias correction order (0 is Parzen kernel); by default taken from instance settings
         :param min_corr: minimum correlation value at which to bother de-correlating the parameters
-        :param N_eff: effective number of samples. If not specified, currently uses very crudely estimate from effective numbers in x and y separately
+        :param N_eff: effective number of samples. If not specified, currently uses crude estimate from effective numbers in x and y separately
         :return: kernel density bandwidth matrix in parameter units
         """
         if N_eff is None:
@@ -1233,7 +1231,7 @@ def get1DDensity(self, name, **kwargs):
     def get1DDensityGridData(self, j, writeDataToFile=False, get_density=False, paramConfid=None, meanlikes=False,
                              **kwargs):
         """
-        Gets a :class:`~.densities.Density1D` instance for the marginalized 1D density of a parameter. Result is not cached.
+        Low-level function to get a :class:`~.densities.Density1D` instance for the marginalized 1D density of a parameter. Result is not cached.
 
         :param j: a name or index of the parameter
         :param writeDataToFile: True if should write to text file.
@@ -1477,10 +1475,10 @@ def get2DDensity(self, x, y, normalized=False, **kwargs):
     def get2DDensityGridData(self, j, j2, writeDataToFile=False,
                              num_plot_contours=None, get_density=False, meanlikes=False, **kwargs):
         """
-        Get 2D plot marginalized density and optional additional plot data.
+        Low-level function to get 2D plot marginalized density and optional additional plot data.
 
         :param j: name or index of the x parameter
-        :param j2: name or index of the x parameter.
+        :param j2: name or index of the y parameter.
         :param writeDataToFile: True if should write data to file
         :param num_plot_contours: number of contours to calculate and return in density.contours
         :param get_density: only get the 2D marginalized density, no additional plot data

getdist/paramnames.py

@@ -80,11 +80,11 @@ class ParamList(object):
     :ivar names: list of :class:`ParamInfo` objects
     """
 
-    def __init__(self, fileName=None, setParamNameFile=None, default=None, names=None):
+    def __init__(self, fileName=None, setParamNameFile=None, default=0, names=None):
         """
         :param fileName: name of .paramnames file to load from
         :param setParamNameFile: override specific parameter names' labels using another file
-        :param default: set to True to automatically generate default names and labels (param1, p_{1}, etc.)
+        :param default: set to int>0 to automatically generate that number of default names and labels (param1, p_{1}, etc.)
         :param names: a list of name strings to use
         """
         self.names = []

getdist/plots.py

@@ -208,9 +208,13 @@ def getPlotter(**kwargs):
 
 def getSinglePlotter(ratio=3 / 4., width_inch=6, **kwargs):
     """
-    Get a :class:`~.plots.GetDistPlotter` for making a single plot of fixed width 
+    Get a :class:`~.plots.GetDistPlotter` for making a single plot of fixed width. 
     
-    The default size is one page-column width.
+    For a half-column plot for a paper use width_inch=3.464.
+    
+    Use this or :func:`~getSubplotPlotter` to make a :class:`~.plots.GetDistPlotter` instance for making plots.
+    If you want customized sizes or styles for all plots, you can make a new module
+    defining these functions, and then use it exactly as a replacement for getdist.plots.
 
     :param ratio: The ratio between height and width.
     :param width_inch:  The width of the plot in inches
@@ -220,7 +224,6 @@ def getSinglePlotter(ratio=3 / 4., width_inch=6, **kwargs):
     plotter = getPlotter(**kwargs)
     plotter.settings.setWithSubplotSize(width_inch)
     plotter.settings.fig_width_inch = width_inch
-    # if settings is None: plotter.settings.rcSizes()
     plotter.make_figure(1, xstretch=1. / ratio)
     return plotter
 
@@ -230,7 +233,11 @@ def getSubplotPlotter(subplot_size=2, width_inch=None, **kwargs):
     Get a :class:`~.plots.GetDistPlotter` for making an array of subplots. 
     
     If width_inch is None, just makes plot as big as needed for given subplot_size, otherwise fixes total width 
-    and sets defaults from matplotlib's default rcParams.
+    and sets default font sizes etc. from matplotlib's default rcParams.
+
+    Use this or :func:`~getSinglePlotter` to make a :class:`~.plots.GetDistPlotter` instance for making plots.
+    If you want customized sizes or styles for all plots, you can make a new module
+    defining these functions, and then use it exactly as a replacement for getdist.plots.
 
     :param subplot_size: The size of each subplot in inches
     :param width_inch: Optional total width in inches
@@ -594,8 +601,6 @@ class GetDistPlotter(object):
     def __init__(self, plot_data=None, chain_dir=None, settings=None, analysis_settings=None, mcsamples=True):
         """
         
-        Initialize the plotter class instance.
-
         :param plot_data: (deprecated) directory name if you have pre-computed plot_data/ directory from GetDist; None by default
         :param chain_dir: Set this to a directory or grid root to search for chains (can also be a list of such, searched in order)
         :param analysis_settings: The settings to be used by :class:`MCSampleAnalysis` when analysing samples
@@ -1573,7 +1578,7 @@ def plots_1d(self, roots, params=None, legend_labels=None, legend_ncol=None, lab
             samples1, samples2 = gaussian_mixtures.randomTestMCSamples(ndim=4, nMCSamples=2)
             g = plots.getSubplotPlotter()
             g.plots_1d([samples1, samples2], ['x0', 'x1', 'x2'], nx=3, share_y=True, legend_ncol =2,
-                legend_labels = ['sim 1', 'sim 2'], markers={'x1':0}, colors=['red', 'green'], ls=['--', '-.'])
+                         markers={'x1':0}, colors=['red', 'green'], ls=['--', '-.'])
 
         """
         roots = makeList(roots)
@@ -1631,6 +1636,7 @@ def plots_2d(self, roots, param1=None, params2=None, param_pairs=None, nx=None,
             from getdist import plots, gaussian_mixtures
             samples1, samples2 = gaussian_mixtures.randomTestMCSamples(ndim=4, nMCSamples=2)
             g = plots.getSubplotPlotter(subplot_size=4)
+            g.settings.legend_frac_subplot_margin = 0.05
             g.plots_2d([samples1, samples2], param_pairs=[['x0', 'x1'], ['x1', 'x2']], 
                                     nx=2, legend_ncol=2, colors=['blue', 'red'])
         """

getdist/types.py

@@ -428,8 +428,8 @@ def runCommand(command):
 
 class ParamResults(paramnames.ParamList):
     """
-    Base class for a set of parameter results, inheriting from :class:`.paramnames.ParamList`, 
-    so that self.names is a list of :class:`.paramnames.ParamInfo` instances for each parameter, which
+    Base class for a set of parameter results, inheriting from :class:`.~paramnames.ParamList`, 
+    so that self.names is a list of :class:`.~paramnames.ParamInfo` instances for each parameter, which
     have attribute holding results for the different parameters.
     """
     pass
@@ -527,7 +527,7 @@ def texValues(self, formatter, p, **kwargs):
 
 class ParamLimit(object):
     """
-    Class containing information about a parameter limit
+    Class containing information about a marginalized parameter limit.
     
     :ivar lower: lower limit
     :ivar upper: upper limit
@@ -537,13 +537,26 @@ class ParamLimit(object):
     """
 
     def __init__(self, minmax, tag='two'):
+        """
+        :param minmax: a [min,max] tuple with lower and upper limits. Entries be None if no limit.
+        :param tag: a text tag descibing the limit, one of ['two' | '>' | '<' | 'none']
+        """
+
         self.lower = minmax[0]
         self.upper = minmax[1]
         self.twotail = tag == 'two'
         self.onetail_upper = tag == '>'
         self.onetail_lower = tag == '<'
 
     def limitTag(self):
+        """        
+        :return: Short text tag describing the type of limit (one-tail or two tail):
+                
+                - *two*: two-tail limit
+                - *>*: a one-tail upper limit
+                - *<*: a one-tail lower limit
+                - *none*: no limits (both boundaries have high probability)
+        """
         if self.twotail:
             return 'two'
         elif self.onetail_upper:
@@ -554,6 +567,14 @@ def limitTag(self):
             return 'none'
 
     def limitType(self):
+        """        
+        :return: a text description of the type of limit. One of:
+         
+            - *two tail*
+            - *one tail upper limit*
+            - *one tail lower limit*
+            - *none*
+        """
         if self.twotail:
             return 'two tail'
         elif self.onetail_upper:
@@ -564,6 +585,9 @@ def limitType(self):
             return 'none'
 
     def __str__(self):
+        """
+        :return: string representation of lower and upper bounds, with text description of the limit type
+        """
         return "%g %g %s" % (self.lower, self.upper, self.limitTag())
 
 
@@ -573,13 +597,19 @@ class MargeStats(ParamResults):
     inheriting from :class:`ParamResults`. 
     
     Values are stored as attributes of the :class:`~.paramnames.ParamInfo` objects stored in self.names.
-    Use par= margeStats.parWithName('xxx') to get the ParamInfo for parameter xxx; values stored are:
-    - par.mean: parameter mean
-    - par.err: standard deviation
-    - limits: list of :class:`~.types.ParamLimit` objects for the stored number of marginalized limits
+    Use *par= margeStats.parWithName('xxx')* to get the :class:`~.paramnames.ParamInfo` for parameter *xxx*; 
+    Values stored are:
+    
+    - *par.mean*: parameter mean
+    - *par.err*: standard deviation
+    - *limits*: list of :class:`~.types.ParamLimit` objects for the stored number of marginalized limits
      
-    For example use margeStats.names.parWithName('xxx').limits[i] to get a  :class:`~.types.ParamLimit`
-    for the ith limit of parameter named xxx. By default i=0 is 68%, i=1 is 95%.  
+    For example to get the first and second lower limits (default 68% and 95%) for parameter *xxx*::
+    
+         print(margeStats.names.parWithName('xxx').limits[0].lower)
+         print(margeStats.names.parWithName('xxx').limits[1].lower)
+         
+    See  :class:`~.types.ParamLimit` for details of limits.
     """
 
     def loadFromFile(self, filename):