Merge pull request #26 from kadrlica/master

Major update towards v1.7.0. Onward and upward...

.travis.yml

@@ -11,17 +11,18 @@ notifications:
   email: false
 
 # Setup dependencies and install package
+# -c jochym is needed for pyfits
 install:
   - wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
   - conda info -a
-  - conda create -q -n travis-env python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib astropy healpy pyyaml emcee nose -c fermipy -c astropy
+  - conda create -q -n travis-env python=$TRAVIS_PYTHON_VERSION numpy scipy matplotlib astropy healpy pyyaml emcee nose pyfits fitsio corner -c conda-forge -c jochym -c kadrlica
   - source activate travis-env
   - export UGALIDIR="$HOME/.ugali"
-  - python setup.py -q install --isochrones --isochrones-path $UGALIDIR
+  - python setup.py -q install --isochrones --catalogs
 
 # command to run tests
 script: 

README.md

@@ -1,64 +1,91 @@
 [![Build](https://img.shields.io/travis/DarkEnergySurvey/ugali.svg)](https://travis-ci.org/DarkEnergySurvey/ugali)
+[![PyPI](https://img.shields.io/pypi/v/ugali.svg)](https://pypi.python.org/pypi/ugali)
 [![Release](https://img.shields.io/github/release/DarkEnergySurvey/ugali.svg)](../../releases)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../)
 
 Overview
 --------
 
-The ultra-faint galaxy likelihood (UGaLi) toolkit provides a set of python classes and functions developed for maximum-likelihood-based studies of Milky Way satellite galaxies. The primary inputs are stellar object catalogs derived from optical photometric surveys and the coverage masks of those surveys.
+The ultra-faint galaxy likelihood (UGaLi) toolkit provides a set of python modules developed for maximum-likelihood-based studies of Milky Way satellite galaxies. The primary inputs are stellar object catalogs derived from optical photometric surveys and the coverage masks of those surveys. In addition, ugali ships with a set of synthetic isochrone libraries and catalogs of known resolved stellar systems.
 
 [Keith Bechtol](https://github.com/bechtol) & [Alex Drlica-Wagner](https://github.com/kadrlica)
 
 Installation
 ------------
 
-There are several ways to install `ugali` and it's complimentary isochrone library.
+There are several ways to install `ugali`.
 
-The easiest way to install `ugali` is through [PyPi](https://pypi.python.org/pypi) using `pip`:
-```
-# To install just the source code
-pip install ugali
+The most robust way is to follow the installation procedure for the automated builds documented in [.travis.yml](.travis.yml). This installation creates a `conda` environment with the necessary dependencies and installs `ugali`.
+```bash
+# Create and activate conda environment
+conda create -n ugali-env numpy scipy matplotlib astropy healpy pyyaml emcee nose pyfits fitsio -c conda-forge -c jochym -c kadrlica
+source activate ugali-env
+
+# Clone source code from the parent repository
+git clone https://github.com/DarkEnergySurvey/ugali.git && cd ugali
 
-# To install source code and isochrone library
-pip install ugali --install-option "--isochrones"
+# Install just the python source code
+python setup.py install 
 
-# To specify a path for the isochrone library
-pip install ugali --install-option "--isochrones" --install-option "--isochrones-path <PATH>"
+# Install source code with a minimal set of isochrone and catalog libraries
+python setup.py install --isochrones --catalogs
 ```
-The isochrone library is a ~100 MB tarball. The default isochrone installation location is set by the `UGALIDIR` environment variable and defaults to `$HOME/.ugali`. The download and unpacking of the isochrone files might make it appear that your `pip` installation has stalled. Unfortunately, `pip` [will not display a progress bar](https://github.com/pypa/pip/issues/2732#issuecomment-97119093) during this delay.
 
-To get the most up-to-date version of `ugali`, you can download the source code from github and install it using `setup.py`:
+In theory, the easiest way to get a stable release of `ugali` is through [PyPi](https://pypi.python.org/pypi) using `pip`:
+```bash
+# Install just the source code
+pip install ugali
+
+# Install source code with a minimal set of isochrone and catalog libraries
+pip install ugali --install-option "--isochrones" --install-option "--catalogs"
 ```
-# Clone source code from the parent repository
-git clone https://github.com/DarkEnergySurvey/ugali.git
-cd ugali
 
-# Install the python source code
-python setup.py install
+By default, the minimal isochrone and catalog libraries are installed into the directory specified by the `$UGALIDIR` environment variable (default: `$HOME/.ugali`). The download and unpacking of the isochrone and catalog files might make it appear that your `pip` installation has stalled. Unfortunately, `pip` [may not display a progress bar](https://github.com/pypa/pip/issues/2732#issuecomment-97119093) during this delay.
 
-# Also install the isochrone library
-python setup.py install --isochrones
+Auxiliary Libraries
+-------------------
 
-# Specify the isochrone install path
-python setup.py install --isochrones --isochrones-path=<PATH>
+The `ugali` source code is distributed with several auxiliary libraries for isochrone generation and catalog matching. These libraries can be downloaded directly from the [releases](../../releases) page, and unpacked in your `$UGALIDIR`. For example, to install the Bressan+ 2012 isochrones for the DES survey:
+
+```
+cd $UGALIDIR
+wget https://github.com/kadrlica/ugali/releases/download/v1.7.0rc0/ugali-des-bressan2012.tar.gz
+tar -xzf ugali-des-bressan2012.tar.gz
 ```
 
-The code uses the `UGALIDIR` environment variable to find the isochrones (defaults to `$HOME/.ugali`). If you install the isochrones in a non-standard location be sure to set `UGALIDIR` so `ugali` can find them:
+The `UGALIDIR` environment variable is used to point to the isochrone and catalog libraries. If you install the isochrones in a non-standard location be sure to set `UGALIDIR` so `ugali` can find them:
+
 ```
 export UGALIDIR=<PATH>
 ```
 
-If all else fails, check out the automated build installation procedure using `conda` in [.travis.yml](.travis.yml).
+An experimental interface for downloading the isochrone and catalog libraries also exists through `setup.py`:
+```
+# To install the Bressan+ 2012 isochrones for the DES survey
+python setup.py isochrones --survey des --model bressan2012
+
+# If you have isochrones already installed, you may need to force
+python setup.py isochrones --survey des --model bressan2012 --force
+
+# To install all available DES isochrones
+python setup.py isochrones --survey des
+
+# To install all available Bressan+ 2012 isochrones
+python setup.py isochrones --model bressan2012
+
+# To install the catalog libraries
+python setup.py catalogs
+```
 
 Usage Examples
 --------------
 Examples go here...
 
-Dependencies
-------------
-These should mostly be taken care of by PyPi with a `pip install`.
+Additional Information
+----------------------
 
-### Python packages:
+#### Dependencies
+These should mostly be taken care of by PyPi with a `pip install`.
 * [numpy](http://www.numpy.org/)
 * [scipy](https://www.scipy.org/)
 * [matplotlib](http://matplotlib.org/)
@@ -67,35 +94,20 @@ These should mostly be taken care of by PyPi with a `pip install`.
 * [astropy](http://www.astropy.org/)
 * [emcee](http://dan.iel.fm/emcee/current/)
 * [pyyaml](http://pyyaml.org/)
+* [fitsio](https://github.com/esheldon/fitsio)
 
-### Mangle:
-Not a strict dependency. Used to interface with masks produced by
-the Dark Energy Survey Data Mangement group. Download and documentation 
-available at http://space.mit.edu/~molly/mangle/
-
-### Isochrones:
-The `ugali` uses a library of stellar isochrones packaged with `ugali` releases. These isochrones come dominantly from two different groups:
-* Padova isochrones (http://stev.oapd.inaf.it/cgi-bin/cmd)
+#### Isochrones
+The isochrones used by `ugali` come dominantly from:
+* PARSEC isochrones from the Padova group (http://stev.oapd.inaf.it/cgi-bin/cmd)
 * Dartmouth isochrones (http://stellar.dartmouth.edu/models/isolf_new.html)
+* MESA isochrones (http://waps.cfa.harvard.edu/MIST/interp_isos.html)
 
-Conventions
------------
+More information can be found in the [isochrone](ugali/isochrone) module.
 
-### Indexing:
-array[index_z][index_y][index_x]
-
-### Naming:
-* package_name
-* module_name.py
-* ClassName
-* functionName
-* variable_name
-
-ABBREVIATIONS
--------------
-* IMF: initial mass function
+#### Abbreviations
 * CMD: color-magnitude diagram
 * ROI: region of interest
 * PDF: probability distribution function
-* LUT: look-up table
 * LKHD: likelihood
+* IMF: initial mass function
+* LUT: look-up table

TODO.md

@@ -26,6 +26,7 @@ a, b, c = rank by current importance (a > b)
 * (2b) Rewrite catalog reader to use fitsio
 * (2b) Compress isochrone data to easy distribution and allow for more extensive isochrone set
 * (1b) Fully incorporate completeness in isochrone fitting and simulation
+* (2b) Create 'bin' directory for command-line tools (also move pipeline to bin)
 
 ## DONE
 * (1c) Collector function to find peaks (in 3D)