Python modules for light curve work and variable star astronomy
waqasbhatti Merge pull request #67 from lgbouma/master
 lcfit: add `mandelagol_and_line_fit_magseries`
Latest commit 71c906e Nov 13, 2018

README.md

DOI

This is a bunch of Python modules I wrote for my astronomy work with the HAT surveys, mostly focused on handling light curves and characterizing variable stars. Module functions that deal with light curves (e.g. in the modules astrobase.lcmath, astrobase.periodbase, astrobase.varbase, astrobase.plotbase, and astrobase.checkplot) usually just require three numpy ndarrays as input: times, mags, and errs, so they should work with any time-series data that can be represented in this form. If you have flux time series measurements, most functions take a magsarefluxes keyword argument that makes them handle flux light curves correctly.

Full documentation is still a work in progress (as soon as I figure out how Sphinx works), but the docstrings are fairly good and an overview is provided below, along with Jupyter notebooks that demonstrate some of the functionality in a companion repository.

To install astrobase from the Python Package Index (PyPI):

$ pip install numpy # needed to set up Fortran wrappers
$ pip install astrobase

The package should work with Python >= 3.4 and Python 2.7. Using the newest Python 3 version available is recommended. See the installation instructions below for details.

Python 2.7: Python 2.7 Python 3.6: Python 3.6 Python 3.7: Python 3.7

Contents

notebooks

These are now located over at astrobase-notebooks.

astrobase

Most of the modules with useful external functions live in here. The astrobase.conf file contains module-wide settings that may need to be tweaked for your purposes.

  • astrokep: contains functions for dealing with Kepler and K2 Mission light curves from STScI MAST (reading the FITS files, consolidating light curves for objects over quarters), and some basic operations (converting fluxes to mags, decorrelation of light curves, filtering light curves, and fitting object centroids for eclipse analysis, etc.)

  • checkplot: contains functions to make checkplots: a grid of plots used to quickly decide if a period search for a possibly variable object was successful. Checkplots come in two forms:

    Python pickles: If you want to interactively browse through large numbers of checkplots (e.g., as part of a large variable star classification project), you can use the checkplotserver webapp that works on checkplot pickle files. This interface allows you to review all phased light curves from all period-finder methods applied, set and save variability tags, object type tags, best periods and epochs, and comments for each object using a browser-based UI (see below). The information entered can then be exported as CSV or JSON for the next stage of a variable star classification pipeline.

    The lightcurves-and-checkplots Jupyter notebook outlines how to do this. A more detailed example using light curves of an arbitrary format is available in the lc-collection-work notebook, which shows how to add in support for a custom LC format, add neighbor, cross-match, and color-mag diagram info to checkplots, and visualize these with the checkplotserver.

    Checkplot Server

    PNG images: Alternatively, if you want to simply glance through lots of checkplots (e.g. for an initial look at a collection of light curves), there's a checkplot-viewer webapp available that operates on checkplot PNG images. The lightcurve-work Jupyter notebook goes through an example of generating these checkplot PNGs for light curves. See the checkplot-viewer.js file for more instructions and checkplot-viewer.png for a screenshot.

  • coordutils: functions for dealing with coordinates (conversions, distances, proper motion)

  • emailutils: contains a simple emailer function suitable for use in long-running scripts and the like; this uses the provided credentials and server to send messages.

  • fakelcs: modules and functions to conduct an end-to-end variable star recovery simulation.

  • fortney2k7: giant planet models from Fortney et al. 2007, ApJ, 2659, 1661 made importable as Python dicts.

  • hatsurveys: modules to read, filter, and normalize light curves from various HAT surveys.

  • lcdb: a lightweight wrapper around the psycopg2 library to talk to PostgreSQL database servers.

  • lcmath: functions for light curve operations such as phasing, normalization, binning (in time and phase), sigma-clipping, external parameter decorrelation (EPD), etc.

  • lcproc: driver functions for running an end-to-end pipeline including: (i) object selection from a collection of light curves by position, cross-matching to external catalogs, or light curve objectinfo keys, (ii) running variability feature calculation and detection, (iii) running period-finding, and (iv) object review using the checkplotserver webapp for variability classification.

  • periodbase: parallelized functions (using multiprocessing.map) to run fast period searches on light curves, including: the generalized Lomb-Scargle algorithm from Zechmeister & Kurster (2008; periodbase.zgls), the phase dispersion minimization algorithm from Stellingwerf (1978, 2011; periodbase.spdm), the AoV and AoV-multiharmonic algorithms from Schwarzenberg-Czerny (1989, 1996; periodbase.saov, periodbase.smav), the BLS algorithm from Kovacs et al. (2002; periodbase.kbls), and the ACF period-finding algorithm from McQuillan et al. (2013a, 2014; periodbase.macf).

  • plotbase: functions to plot light curves, phased light curves, periodograms, and download Digitized Sky Survey cutouts from the NASA SkyView service.

  • services: modules and functions to query various astronomical catalogs and data services, including GAIA, SIMBAD, TRILEGAL, NASA SkyView, and 2MASS DUST.

  • timeutils: functions for converting from Julian dates to Baryocentric Julian dates, and precessing coordinates between equinoxes and due to proper motion; this will automatically download and save the JPL ephemerides de430.bsp from JPL upon first import.

  • varbase: functions for calculating variability indices for light curves, fitting and obtaining Fourier coefficients for use in classifications, and other variability features.

  • varclass: functions for calculating various variability, stellar color and motion, and neighbor proximity features, along with a Random Forest based classifier.

Installation

Requirements

This package requires the following other packages:

  • numpy
  • scipy
  • astropy
  • matplotlib
  • Pillow
  • jplephem
  • requests
  • tornado
  • pyeebls
  • tqdm
  • scikit-learn

For some extra functionality:

  • for astrobase.lcdb to work, you'll also need psycopg2-binary.
  • for varbase.lcfit.mandelagol_fit_magseries, you'll need batman-package, emcee, corner, and h5py.

Installing with pip

If you're using:

  • 64-bit Linux and Python 2.7, 3.4, 3.5, 3.6
  • 64-bit Mac OSX 10.12+ with Python 2.7 or 3.6
  • 64-bit Windows with Python 2.7 and 3.6

You can simply install astrobase with:

(venv)$ pip install astrobase

Otherwise, you'll need to make sure that a Fortran compiler and numpy are installed beforehand to compile the pyeebls package that astrobase depends on:

## you'll need a Fortran compiler.                              ##
## on Linux: dnf/yum/apt install gcc gfortran                   ##
## on OSX (using homebrew): brew install gcc && brew link gcc   ##

## make sure numpy is installed as well!                        ##
## this is required for the pyeebls module installation         ##

(venv)$ pip install numpy # in a virtualenv
# or use dnf/yum/apt install numpy to install systemwide

Once that's done, install astrobase.

(venv)$ pip install astrobase

Other installation methods

Or if you want to install the optional dependencies as well:

(venv)$ pip install astrobase[all]

Finally, if you want the latest version:

$ git clone https://github.com/waqasbhatti/astrobase
$ cd astrobase
$ python setup.py install
$ # or use pip install . to install requirements automatically
$ # or use pip install -e . to install in develop mode along with requirements

License

astrobase is provided under the MIT License. See the LICENSE file for the full text.