isochrones

isochrones

The isochrones Python package aims to provide a simple common interface to different stellar model grids, and to simplify the task of inferring model-based physical stellar properties given arbitrary observations of a star (or multiple stars).

The package is built around three basic objects: ModelGrid, which takes care of the bookkeeping aspects of storing and parsing a given grid of stellar models; Isochrone, which takes care of the grid interpolation; and StarModel, which is the top-level interface for fitting stellar properties.

While isochrones comes packaged with two different model grids (MIST and Dartmouth), it can be easily extended to other model grids. Of these two grid choices (accessible through the MIST_Isochrone and Dartmouth_Isochrone objects), MIST may be preferred because it covers a broader range of age, mass, and metallicity than the Dartmouth Models.

For posterior sampling, isochrones defaults to MultiNest/PyMultiNest for sampling (see here for installation instructions), but will fall back on emcee if (Py)MultiNest is not installed.

Note that the first time you import any of the pre-packaged model grids, it will download the required data for you. If you like, you can also download the data files directly and save them to ~/.isochrones (or to a location defined by an $ISOCHRONES environment variable.)

Note

The downloaded & unpacked data files, as well as some ancillary data created for convenience by the package, will take up about 10 Gb of disk space. So if you’re planning to use isochrones on a system on which you have a home directory quota, you may wish to explicitly define an $ISOCHRONES environment variable somewhere where you have more storage space.

I welcome community feedback to help improve this tool. The code is hosted at GitHub; please feel free to contribute.

Warning

If you have been a user of isochrones prior to v1.0, you will need to download the new grid data. There has also been significant change to the code base. Most backward compatibility should be preserved, but raise an issue if you have problems with the transition.

Installation

To install, you can get the most recently released version from PyPI:

pip install isochrones

Or you can clone from github:

git clone https://github.com/timothydmorton/isochrones.git
cd isochrones
python setup.py install

The last command may require --user if you don’t have root privileges.

After installation, run the test suite to check if everything works:

nosetests isochrones

Be patient the first time you do this, as it will have to download ~1.5 Gb of stellar grid data if you have not already done so. If there is a problem with the automated downloading, you can also directly download the necessary files from here and put them in ~/.isochrones (or $ISOCHRONES).

Basic Usage

To find, for example, what a stellar model grid predicts for stellar radius at a given mass, log(age), and metallicity:

>>> from isochrones.mist import MIST_Isochrone
>>> mist = MIST_Isochrone()
>>> mist.radius(1.0, 9.7, 0.0) #M/Msun, log10(age), Fe/H
    1.0429784536817184

Importantly (for purposes of synthesizing populations of stars, e.g.), you can pass array-like values, rather than single values:

>>> mist.radius([0.8, 1.0, 1.2], 9.7, 0.0)
    array([ 0.75965718,  1.04297845,  1.96445299])

You can also interpolate broadband magnitudes, at a given distance and A_V extinction, as follows:

>>> mass, age, feh, distance, AV = (0.95, 9.61, -0.2, 200, 0.2)
>>> mist.mag['g'](mass, age, feh, distance, AV)
    11.788065261437591

You can see what bands are available to an Isochrone object by checking the bands attribute:

>>> mist.bands
    ['B', 'G', 'H', 'J', 'K', 'Kepler', 'V', 'W1', 'W2', 'W3', 'g', 'i', 'r', 'z']

If you wish to use a different set of photometric bands, you may initialize the Isochrone with a bands keyword argument. However, the ModelGrid object used by the Isochrone must know how to interpret that band name, and where to get that data, via the get_band() method.

Fitting Stellar Properties

If you want to estimate physical parameters for a star for which you have measured spectroscopic properties, you would do something like the following:

from isochrones import StarModel
from isochrones.mist import MIST_Isochrone

#spectroscopic properties (value, uncertainty)
Teff = (5770, 80)
logg = (4.44, 0.08)
feh = (0.00, 0.10)

mist = MIST_Isochrone()

model  = StarModel(mist, Teff=Teff, logg=logg, feh=feh)
model.fit()

The model now has a samples property that contains all of the samples generated by the MultiNest/MCMC chain in a pandas.DataFrame object—or more specifically, it contains both the samples generated directly from the chain and the corresponding values of all the model properties (e.g. radius, synthetic photometry, etc.) evaluated at each chain link. You can also visualize the results using:

model.corner_physical()

Note that a isochrones.StarModel can be initialized with any arguments that correspond to properties predicted by the model grids—that is, in addition to spectroscopic properties, apparent magnitudes (and errors) may also be included among the keyword arguments, as well as parallax (in miliarcseconds) and asteroseismic properties (nu_max or delta_nu).

After running the MultiNest/MCMC chain, you can save the results:

model.save_hdf('starmodel.h5')

Which you can then read back in later as:

model = StarModel.load_hdf('starmodel.h5')

In addition, if you would like to entertain the possibility of a star having light from more than one component, you can also fit a binary or triple star model by providing the additional keyword argument N=2 or N=3 to the StarModel initialization. You can also set up a StarModel that allows for light from multiple stars to be blended in some bandpasses but resolved in others. See the demo notebook for more details on how to do this.

The easiest way to initialize and fit a StarModel is to create a star.ini file in a directory called mystar (for example), and then run the starfit command-line script that gets installed with isochrones. Again, see the demo notebook for more details.