Merge branch 'develop'

Release v0.9

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

@@ -74,14 +74,9 @@ if __name__ == '__main__':
                                help='Likelihood components to '
                                     'exclude from posteriors')
 
-    shared_parser.add_argument('--no-hyperparams', dest='hyperparams',
-                               action='store_false',
-                               help="Don't use Bayesian hyperparams")
-
-    shared_parser.add_argument('--strict', nargs='+',
-                               metavar=('[STRICT]', 'LIKELIHOOD'),
-                               help="A (numeric) strictness factor to be "
-                                    "applied to each specified likelihood")
+    shared_parser.add_argument('--hyperparams', dest='hyperparams',
+                               action='store_true',
+                               help="Use Bayesian hyperparams")
 
     shared_parser.add_argument('--verbose', action='store_true')
     shared_parser.add_argument('--debug', action='store_true')
@@ -134,6 +129,13 @@ if __name__ == '__main__':
                              help='Posterior weighting fraction f_p')
     parser_nest.add_argument('--dlogz', default=0.25, type=float,
                              help='Δln(Z) tolerance initial stopping condition')
+    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 0.8')
+    parser_nest.add_argument('--eff-samples', default=5000, type=pos_int,
+                             help='Number of effective posterior samples '
+                                  'stopping condition')
     parser_nest.add_argument('--maxiter', default=None, type=pos_int,
                              help='Maximum number of iterations allowed. May '
                                   'end sampling before the stopping conditions '
@@ -184,16 +186,6 @@ if __name__ == '__main__':
         else:
             parser.error(f"Cannot access '{bnd_file}': No such file")
 
-    # TODO could also be a way here for setting `err_on_fail` in the priors
-    if args.strict is not None:
-        try:
-            args.strict[0] = float(args.strict[0])
-        except (ValueError, TypeError):
-            args.strict = [1.] + args.strict
-
-        if len(args.strict) == 1:
-            args.strict.append('*')
-
     pathlib.Path(args.savedir).mkdir(exist_ok=True)
 
     # ----------------------------------------------------------------------

bin/file_creator.py

@@ -0,0 +1,6 @@
+'''
+1) Create a Clusterfile
+2) Add metadata to created Clusterfile
+3) Create a bunch of Datasets
+    - Add them to created Clusterfile
+'''

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