Merge pull request #277 from California-Planet-Search/next-release

Version 1.3.0

.coveragerc

@@ -2,3 +2,17 @@
 omit =
     *__init__*
     radvel/utils.py
+
+[run]
+source = radvel
+
+; Run in parallel mode so that coverage can canonicalize the source paths
+; regardless of whether it runs locally or within a Docker container.
+parallel = True
+
+[paths]
+; the first path is the path on the local filesystem
+; the second path is the path as it appears within the Docker container
+source =
+  radvel/
+  /code/radvel/

.travis.yml

@@ -1,40 +1,23 @@
 language: python
-sudo: False
 
-cache:
-   directories:
-     - $HOME/download
-     - $HOME/miniconda2
-     - $HOME/miniconda3
-     - $HOME/.cache/pip
-     - $HOME/.ccache
+services:
+  - docker
 
-python:
-  - "3.7"
+env:
+  global:
+    CACHE_IMAGE: bjfultn/radvel
 
 before_install:
-    - export py="$(echo $TRAVIS_PYTHON_VERSION | head -c 1)"
-    - wget http://repo.continuum.io/miniconda/Miniconda${py}-latest-Linux-x86_64.sh -O miniconda.sh
-    - chmod +x miniconda.sh
-    - bash miniconda.sh -b -u -p $HOME/miniconda
-    - export PATH=/home/travis/miniconda/bin:$PATH
-    - conda update --yes conda
-
-install:
-    - if [ ${py} == "2" ]; then conda install --yes configparser==3.5.0b2; fi
-    - conda install --yes pip numpy scipy matplotlib>=2.0.0 cython pandas nose nbformat nbconvert jupyter_client ipykernel tornado==4.5.3
-    - pip install coveralls pybind11
-    - pip install celerite
-    - pip install .
-    - python setup.py build_ext -i
-
-# configure a headless display using xvbf to test plot generation
-before_script:
-    - "export DISPLAY=:99.0"
-    - sleep 2 # give xvfb some time to start
+  - docker pull $CACHE_IMAGE:latest || true
+  - docker build --cache-from $CACHE_IMAGE:latest --tag radvel .
 
 script:
-    - xvfb-run nosetests radvel --with-coverage --cover-package=radvel
+  - docker run --env TRAVIS_JOB_ID=$TRAVIS_JOB_ID radvel
 
-after_success:
-    - coveralls
+deploy:
+  provider: pypi
+  user: __token__
+  password:
+    secure: oWyzGLMo0nAJJP3r4wa3HiSm6g5e9xxgsfG8/vtAIYmVUt3MkeXrihrBO+rEBWXpeFjFyN7WDJdQQnMRikDssEBfm63QIpLlZ9dlb/40h1rqVBzdYl5JBbsDGqkO1watb6cJR5hWtd7Mm0OiiZSq2OGdxH8ympc5RxXyNg3yRt2uP8K6s4kXUwHuOaVshx7N1TayEQr/IaBZjk6HoYY8amZUVxuyJO3hOuCm4R+P3qcRiW/dFXwGn8C5dq4ZCXZZJYCzrrubRO7zd6PvsMcxB2T4YnKjoe8lSAR1ZoAKmA4D+0ahDMmfDnCF5CEy8sMV5ePe5feXHJh8cKvbahWt7V5qSEbJYGLfl9i9uQEsnW3biyonDUvZFdFkwn7j4Z6GQ9MGrNsy9wQnSjoaNnzVgzli4z+CxgFRcuJ31Z8Jo8bRWesA5MVfc01LHxzLBit4JmzK+z7vxiNh4hxytQMVkaLEjS/C10RntkSSvYcEcXf+KpXF//0ixTN5/7fA+Ha8+nyNZdM6V+fhSZ3CawK4kj6rmjmmW3IpN3DO9sAJ+4efP6P27bFnvFhJ1m6OlHntpASjkbkPPg/Sb8CyzZU7Jck29P1vwh/+nzdUVArocDbPMW/RFH/eWsbv5MYxyWL7yNha2UTFVuvxMAfXiq58/VBhRkv0Kp2YiLnY6F1ktWI=
+  on:
+    tags: 

Dockerfile

@@ -0,0 +1,31 @@
+FROM conda/miniconda3
+
+ENV TERM=xterm
+ENV TERMINFO=/etc/terminfo
+ENV COVERALLS_REPO_TOKEN=7ZpQ0LQWM2PNl5iu7ZndyFEisQnZow8oT
+
+
+RUN mkdir /code && \
+    mkdir /code/radvel && \
+    apt-get --yes update && \
+    apt-get install --yes gcc g++ git && \
+    conda config --add channels conda-forge && \
+    conda config --set channel_priority strict && \
+    conda update -n base -c defaults conda && \
+    pip install --no-cache-dir nose coveralls pybind11 && \
+    conda install -y -c conda-forge celerite
+
+WORKDIR /code/radvel
+ADD requirements.txt /code/radvel/requirements.txt
+
+RUN conda install -y --file requirements.txt && \
+    pip install --no-cache-dir -r requirements.txt
+
+ADD . /code/radvel
+
+
+RUN pip install --no-cache-dir . && \
+    python setup.py build_ext -i
+
+CMD nosetests radvel --with-coverage --cover-package=radvel && \
+    coveralls

README.md

@@ -3,7 +3,7 @@
 
 General Toolkit for Modeling Radial Velocities.
 
-[![Build Status](https://travis-ci.org/California-Planet-Search/radvel.svg?branch=master)](https://travis-ci.org/California-Planet-Search/radvel)
+[![Build Status](https://travis-ci.com/California-Planet-Search/radvel.svg?branch=master)](https://travis-ci.com/California-Planet-Search/radvel)
 [![Coverage Status](https://coveralls.io/repos/github/California-Planet-Search/radvel/badge.svg?branch=master)](https://coveralls.io/github/California-Planet-Search/radvel?branch=master)
 [![Documentation Status](https://readthedocs.org/projects/radvel/badge/?version=latest)](http://radvel.readthedocs.io/en/latest/?badge=latest)
 [![PyPI version](https://badge.fury.io/py/radvel.svg)](https://badge.fury.io/py/radvel)

docs/autocorrintro.rst

@@ -0,0 +1,58 @@
+.. _autocorrintro:
+
+Introduction to Autocorrelation Times
+===============
+
+.. _background:
+
+Background
+++++++++++++
+
+As of v1.3.0 there are two additional new convergence criterion in addition to `maxGR` and `minTz` used to evaluate whether or not the MCMC chains are converged/well-mixed.
+`MinAfactor` and `maxArchange` both rely on the autocorrelation time. While a more in-depth
+explanation of autocorrelation and its relation to convergence can be found in the
+`documentation for emcee <https://emcee.readthedocs.io/en/stable/tutorials/autocorr/>`_, we will provide a brief
+description here. The original RadVel convergence checks are also still in place and are described in `Fulton et al. (2018) <https://ui.adsabs.harvard.edu/abs/2018PASP..130d4504F/abstract>`_.
+
+Autocorrelation time is the number of steps the walker needs to take for the chain to "forget" its initial position.
+Therefore, it can be used to reduce the error in your MCMC run and to tell if it is well-mixed. Using ``emcee3``, we can
+estimate this value for each parameter in an ensemble; if multiple ensembles are run, we combine their chains to receive
+the autocorrelation times.
+
+As the chain progresses, the estimated value of the autocorrelation time (τ) becomes more accurate. In the plot below,
+you can see that the the estimated autocorrelation time quickly rises and then begins to plateau as it nears the true
+value.
+
+.. image:: plots/plateau.png
+
+minAfactor
++++++++++++
+
+The autocorrelation time can be used to evaluate whether or not a chain is sufficiently long to be considered well-mixed. Therefore, if N steps have been
+taken, N/τ ≥ c, where c is what we call the autocorrelation factor. The minimum autocorrelation factor to consider the
+chains converged is represented by the criterion ``minAfactor``. The default value for ``minAfactor`` is 50, however we find
+that lower values may be sufficient, particularly for runs that take a long time; alternate values can be specified
+using the ``minAfactor`` argument when calling the MCMC.
+
+The autocorrelation factor is calculated for each parameter and the minimum of these values
+is returned in real time as the MCMC run progresses.
+Once the minimum autocorrelation factor is below ``minAfactor``, this criterion
+for convergence is met. Whether or not ``minAfactor`` has been satisfied can be seen in the autocorrelation plot below. Once the
+maximum autocorrelation time has passed the dashed line labeled 'Autocorrelation Factor Criterion,' the chain is likely converged. After five consecutive status checks appear past the dashed line, the MCMC will halt if all other criterion have also been met.
+
+.. image:: plots/minAfactor.png
+
+maxArchange
++++++++++++++++++
+
+While we want the autocorrelation factor to be sufficiently large, we want to make sure that it is being calculated with
+an accurate estimate of the autocorrelation time. We know our estimate for τ is accurate once it begins to plateau,
+allowing us to use the relative change in the autocorrelation time to infer whether or not the estimate is reliable.
+We calculate the relative change in autocorrelation time for each parameter between every convergence check. The largest
+of these values is also returned in real time and for the chain to be considered converged, it must fall below the
+criterion ``maxArchange``.
+
+The default value for ``maxArchange`` is .07, where we consider the autocorrelation time to begin leveling off. Rarely should
+you need to increase the ``maxArchange`` argument when running `radvel mcmc`, but for more conservative criterion, you may
+want to decrease it, particularly for long chains with large autocorrelation times (in such cases, the relative change
+may be small, but τ has not reached its plateau).

docs/index.rst

@@ -23,6 +23,7 @@ Contents:
    :maxdepth: 2
 
    quickstartcli
+   autocorrintro
    tutorials
    api
 

docs/quickstartcli.rst

@@ -119,7 +119,7 @@ We can summarize our analysis with the `radvel report` command.
 
     $ radvel report -s /path/to/radvel/example_planets/HD164922.py
 
-whihc creates a LaTeX document and corresponding PDF to summarize the
+which creates a LaTeX document and corresponding PDF to summarize the
 results. Note that this command assembles values and plots that have been computed 
 through other commands, if you want to update, rerun the previous commands before 
 reruning `radvel report`

docs/requirements.txt

@@ -4,7 +4,7 @@ matplotlib>=1.5.3
 corner>=2.0
 cython>=0.23
 astropy>=1.1.2
-emcee>=2.2.1
+emcee>=3.0.0
 pandas>=0.20.0
 nbsphinx
 jupyter_client

docs/tutorials/164922_Fitting+MCMC.ipynb

@@ -25,12 +25,14 @@
      ]
     },
     {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/Users/bfulton/anaconda3/lib/python3.7/site-packages/radvel/gp.py:33: ImportWarning: celerite not installed. GP kernals using celerite will not work. Try installing celerite using 'pip install celerite'\n",
-      "  Try installing celerite using 'pip install celerite'\", ImportWarning)\n",
-      "numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject\n"
+     "ename": "ModuleNotFoundError",
+     "evalue": "No module named 'radvel'",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
+      "\u001b[0;32m<ipython-input-1-5b68983f59c2>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[1;32m      2\u001b[0m \u001b[0;31m#%pylab osx\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0mget_ipython\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mrun_line_magic\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'pylab'\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m'inline'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 4\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0mradvel\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      5\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mradvel\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mlikelihood\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      6\u001b[0m \u001b[0;32mfrom\u001b[0m \u001b[0mradvel\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mplot\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0morbit_plots\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
+      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'radvel'"
      ]
     }
    ],
@@ -500,7 +502,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.7.4"
   }
  },
  "nbformat": 4,

radvel/__init__.py

@@ -25,7 +25,7 @@ def _custom_warningfmt(msg, *a, **b):
 __all__ = ['model', 'likelihood', 'posterior', 'mcmc', 'prior', 'utils',
          'fitting', 'report', 'cli', 'driver', 'gp']
 
-__version__ = '1.2.13'
+__version__ = '1.3.0'
 __spec__ = __name__
 __package__ = __path__[0]
 

radvel/cli.py

@@ -48,7 +48,7 @@ def main():
     psr_plot = subpsr.add_parser('plot', parents=[psr_parent],)
     psr_plot.add_argument('-t', '--type',
                           type=str, nargs='+',
-                          choices=['rv', 'corner', 'trend', 'derived'],
+                          choices=['rv', 'auto', 'corner', 'trend', 'derived'],
                           help="type of plot(s) to generate"
                           )
     psr_plot.add_argument('--plotkw', dest='plotkw', action='store', default="{}", type=eval,
@@ -75,11 +75,20 @@ def main():
     psr_mcmc.add_argument('--nensembles', dest='ensembles', action='store', default=8, type=int,
                           help="Number of ensembles. Will be run in parallel on separate CPUs [8]"
                           )
+    psr_mcmc.add_argument('--minAfactor', dest='minAfactor', action='store', default=50, type=float,
+                          help="Minimum factor between autocorrelation time and number of samples for chains to be deemed well-mixed [50]"
+                          )
+    psr_mcmc.add_argument('--maxArchange', dest='maxArchange', action='store', default=.07, type=float,
+                          help="Max relative-change in autocorrelation time for chains to be deemed well-mixed [.07]"
+                          )
     psr_mcmc.add_argument('--maxGR', dest='maxGR', action='store', default=1.01, type=float,
                           help="Maximum G-R statistic for chains to be deemed well-mixed and halt the MCMC run [1.01]"
                           )
     psr_mcmc.add_argument('--burnGR', dest='burnGR', action='store', default=1.03, type=float,
-                          help="Maximum G-R statistic to stop burn-in period [1.03]"
+                          help="Maximum G-R statistic to stop burn-in period [1.03]. Burn-in ends once burnGr or burnAfactor are reached."
+                          )
+    psr_mcmc.add_argument('--burnAfactor', dest='burnAfactor', action='store', default=25, type=float,
+                          help='Minimum autocorrelation time factor to stop burn-in period [25]. Burn-in ends once burnGr or burnAfactor are reached.'
                           )
     psr_mcmc.add_argument('--minTz', dest='minTz', action='store', default=1000, type=int,
                           help="Minimum Tz to consider well-mixed [1000]"
@@ -137,7 +146,7 @@ def main():
     # Tables
     psr_table = subpsr.add_parser('table', parents=[psr_parent],)
     psr_table.add_argument('-t', '--type', type=str, nargs='+',
-                           choices=['params', 'priors', 'rv', 'ic_compare', 'derived'],
+                           choices=['params', 'priors', 'rv', 'ic_compare', 'derived', 'crit'],
                            help="type of tables(s) to generate"
                            )
     psr_table.add_argument('--header', action='store_true',