Merge pull request #84 from nmdickson/feature/documentation-update

Feature/documentation update

Author: nmdickson

.gitignore

@@ -23,3 +23,7 @@ devnotes*
 *.cb
 *.cb2
 .*.lb
+
+# docs
+docs/build
+docs/source/**/generated/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Nolan Dickson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,62 +2,17 @@
 
 ## Fitting of static equilibrium globular cluster models
 
-Python package enabling the generalized fitting of globular cluster
-observations to distribution function based lowered isothermal
-([LIMEPY](https://github.com/mgieles/limepy)) models to various observational
-data products, via a parallelized [MCMC](https://github.com/dfm/emcee/) suite.
+Python package enabling the generalized fitting of distribution function based
+lowered isothermal ([LIMEPY](https://github.com/mgieles/limepy)) models to
+various observational Globular Cluster data products, via a parallelized
+sampling suite.
 
-## Installation
+## Documentation
+All documentation, including installation instructions and examples, can be
+found [here](https://GCfit.readthedocs.io).
 
-The `fitter` package can be easily installed from this repository using pip.
-A fork of the `ssptools` library must be installed seperately, as below. All
-other requisite packages will be installed automatically.
+## Attribution
 
-```
-pip install git+ssh://git@github.com/nmdickson/ssptools.git
-pip install git+ssh://git@github.com/nmdickson/GCfit.git
-```
-
-or this repo can be cloned locally and installed with pip.
-
-## Usage
-
-GCfit has two main functionalities; to fit globular cluster models, and to
-explore the results of those fitting runs.
-
-### Fitting
-
-Fitting of the clusters is done through the `fit` function of `fitter`.
-For ease of use, a command-line script is provided in `GCfitter`, which should
-be automatically placed in your path upon installation.
-
-`GCfitter` takes the name of the cluster you wish to fit, as well as a
-number of sampler directives. See `GCfitter -h` for a full list of arguments.
-
-#### Examples
-
-Fitting cluster "NGC0104" (also known as 47 Tucanae) for 2000 iterations of 100
-MCMC walkers, parallelized locally over 2 CPUs (default). Sampler output is
-saved to `~/.GCfit/47Tuc_sampler.hdf` (default).
-```
-GCfitter 47Tuc -N 2000 --Nwalkers 100 --verbose
-```
-
-Fitting cluster "NGC6397" for 1850 iterations of 150 walkers (default), using
-MPI. MPI parameters and allocations must be handled by your job
-script/scheduler separately. Output and debug info is saved to a local `results`
-folder.
-```
-srun GCfitter NGC6397 -N 1850 --mpi --savedir ./results --debug
-```
-
-Fitting cluster "NGC0104" for 2000 iterations of 150 walkers, with custom prior
-bounds specified in the file `alt_bounds`, parallelized locally with 4 CPUs.
-```
-echo '{"a3": [">=", "a2"], "delta": [0.45, 0.5]}' > alt_bounds.json
-GCfitter NGC104 -N 2000 --Ncpu 4 --bounds alt_bounds.json --debug
-```
-
-### Investigating Fitting Results
-
-TODO
+If you find this package useful in your research, please see the
+[documentation](https://GCfit.readthedocs.io/en/latest/citations.html) for
+information on what you should cite.

bin/GCfitter

@@ -132,7 +132,7 @@ if __name__ == '__main__':
     parser_nest.add_argument('--maxfrac', default=0.8, type=float,
                              help='The fractional threshold, relative to the '
                                   'peak weight, used to determine likelihood '
-                                  'bounds for dynamic sampling. Default to 80%')
+                                  'bounds for dynamic sampling. Default to 0.8')
     parser_nest.add_argument('--eff-samples', default=5000, type=pos_int,
                              help='Number of effective posterior samples '
                                   'stopping condition')

docs/CLUSTER_DPC_V2.pdf

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/make.bat

@@ -0,0 +1,93 @@
+=========
+Citations
+=========
+
+If you find this package useful in your research, please consider citing the
+relevant papers below:
+
+Observational Data
+==================
+
+Each observational dataset should come with it's own ``source`` metadata,
+typically in the form of a
+`bibcode <https://adsabs.harvard.edu/help/actions/bibcode>`_ identifier.
+
+While these can be accessed directly through the metadata attribute of each
+``Dataset``:
+
+.. code-block:: python
+    
+    >>> dset = obs['proper_motion/gedr3']
+    >>> dset.mdata['source']
+    '2021MNRAS.505.5978V'
+
+``GCfit`` also comes equipped with some utility functions to automatically
+convert bibcodes to useful formats, like bibtex. This functionality requires
+the `ads <https://github.com/andycasey/ads>`_ package to be installed correctly,
+with a valid ``ADS_DEV_KEY`` set.
+
+The ``Observations`` and ``Dataset`` objects can provide some of the available
+formats directly:
+
+.. code-block:: python
+
+    >>> sources = obs.get_sources()
+    >>> print(sources['proper_motion/gedr3'])
+    @ARTICLE{2021MNRAS.505.5978V,
+           author = {{Vasiliev}, Eugene and {Baumgardt}, Holger},
+    ...
+          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+    }
+    >>> dset.cite()
+    'Vasiliev & Baumgardt (2021)'
+
+Or the utility methods can be used directly:
+
+.. code-block:: python
+
+    >>> print(fitter.util.bibcode2bibtex(dset.mdata['source']))
+    @ARTICLE{2021MNRAS.505.5978V,
+           author = {{Vasiliev}, Eugene and {Baumgardt}, Holger},
+    ...
+          adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+    }
+    >>> fitter.util.bibcode2cite(dset.mdata['source'])
+    'Vasiliev & Baumgardt (2021)'
+
+
+Models
+======
+
+The equilibrium models used should be cited from the ``limepy`` paper:
+`2015MNRAS.454..576G <https://adsabs.harvard.edu/abs/2015MNRAS.454..576G>`_.
+
+
+Samplers
+========
+
+If you are using the MCMC fitter (``MCMC_fit``), the sampler source software
+should be cited as the ``emcee`` paper:
+`2013PASP..125..306F <https://adsabs.harvard.edu/abs/2013PASP..125..306F>`_.
+Specific proposal algorithm citations can be found within.
+
+Nested sampling fits (``nested_fit``) should cite the ``dynesty`` paper:
+`2020MNRAS.493.3132S <https://adsabs.harvard.edu/abs/2020MNRAS.493.3132S>`_.
+For specific bound and sampler algorithm sources, see the
+`dynesty documentation <https://dynesty.readthedocs.io/en/latest/references.html>`_.
+
+Other
+=====
+
+If Bayesian hyperparameters are used (``hyperparams=True`` in any fitting),
+the source paper
+`2002MNRAS.335..377H <https://adsabs.harvard.edu/abs/2002MNRAS.335..377H>`_
+can be cited.
+
+``GCfit`` makes extensive use of the
+`numpy <https://adsabs.harvard.edu/abs/2020Natur.585..357H>`_,
+`scipy <https://adsabs.harvard.edu/abs/2020NatMe..17..261V>`_ and
+`astropy <https://adsabs.harvard.edu/abs/2018AJ....156..123A>`_
+libraries. All plotting functionality is enabled by the
+`matplotlib <https://adsabs.harvard.edu/abs/2007CSE.....9...90H>`_ library.
+Parallelization pools are handled by the
+`schwimmbad <https://adsabs.harvard.edu/abs/2017JOSS....2..357P>`_ library

docs/source/_static/DPC.pdf

@@ -0,0 +1,82 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'GCfit'
+copyright = '2021, Nolan Dickson'
+author = 'Nolan Dickson'
+
+# The full version, including alpha/beta/rc tags
+release = '0.9'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
+    'sphinx_toggleprompt',
+    'numpydoc'
+]
+
+autosummary_generate = True
+
+numpydoc_show_class_members = False
+numpydoc_show_inherited_class_members = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "pydata_sphinx_theme"
+
+html_theme_options = {
+    "use_edit_page_button": True,
+    "icon_links": [{
+        "name": "GitHub",
+        "url": "https://github.com/nmdickson/GCfit",
+        "icon": "fab fa-github-square",
+        "type": "fontawesome",  # Default is fontawesome
+    }]
+}
+
+html_context = {
+    # "github_url": "https://github.com", # or your GitHub Enterprise interprise
+    "github_user": "nmdickson",
+    "github_repo": "GCfit",
+    "github_version": "develop",
+    "doc_path": "docs/source",
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']