# API¶

This page details the methods and classes provided by the isochrones package. The ModelGrid object handles the book-keeping aspects of loading a given grid into a pandas.DataFrame object. However, ModelGrid works behind the scenes; you should usually only work directly through the Isochrone object, which handles the grid interpolation. Finally, the StarModel object is used to fit the stellar models constrained by observed data.

## ModelGrid¶

class isochrones.grid.ModelGrid(bands=None, **kwargs)[source]

Base class for Model Grids.

Subclasses must implement the following (shown below is the Dartmouth example):

name = 'dartmouth'
common_columns = ('EEP', 'MMo', 'LogTeff', 'LogG', 'LogLLo', 'age', 'feh')
phot_systems = ('SDSSugriz','UBVRIJHKsKp','WISE','LSST','UKIDSS')
phot_bands = dict(SDSSugriz=['sdss_z', 'sdss_i', 'sdss_r', 'sdss_u', 'sdss_g'],
UBVRIJHKsKp=['B', 'I', 'H', 'J', 'Ks', 'R', 'U', 'V', 'D51', 'Kp'],
WISE=['W4', 'W3', 'W2', 'W1'],
LSST=['LSST_r', 'LSST_u', 'LSST_y', 'LSST_z', 'LSST_g', 'LSST_i'],
UKIDSS=['Y', 'H', 'K', 'J', 'Z'])

default_kwargs = {'afe':'afep0', 'y':''}
zenodo_record = 159426  # if you want to store data here
zenodo_files = ('dartmouth.tgz', 'dartmouth.tri') # again, if desired
master_tarball_file = 'dartmouth.tgz'


Subclasses also must implement the following methods:

get_band, phot_tarball_file, get_filenames, get_feh, to_df, hdf_filename. See DartmouthModelGrid and MISTModelGrid for details.

df_all(phot)[source]

Subclasses may want to sort this

classmethod extract_master_tarball()[source]

Unpack tarball of tarballs

classmethod get_band(b)[source]

Must defines what a “shortcut” band name refers to.

Param: b (string) Band name. phot_system, band b maps to the band defined by phot_system as band.
classmethod get_feh(filename)[source]

Parse [Fe/H] from filename (returns float)

get_filenames(phot, **kwargs)[source]

Returns list of all filenames corresponding to phot system and kwargs.

hdf_filename(phot)[source]

Returns HDF filename of parsed/stored phot system

phot_tarball_file(phot, **kwargs)[source]

Returns name of tarball file for given phot system and kwargs

classmethod to_df(filename)[source]

Parses specific file to a pandas DataFrame

## Isochrone¶

Any usage of isochrones involves instantiating an Isochrone, usually through a specific subclass such as mist.MIST_Isochrone.

class isochrones.Isochrone(m_ini, age, feh, m_act, logL, Teff, logg, mags, tri=None, minage=None, maxage=None, ext_table=False)[source]

Basic isochrone class. Everything is a function of mass, log(age), Fe/H.

Can be instantiated directly, but will typically be used with a pre-defined subclass, such as dartmouth.Dartmouth_Isochrone. All parameters must be array-like objects of the same length, with the exception of mags, which is a dictionary of such array-like objects.

Parameters: m_ini (array-like) – Array of initial mass values [msun]. age – log10(age) [yr] feh – Metallicity [dex] m_act – Actual mass; same as m_ini if mass loss not implemented [msun] logL – log10(luminosity) [solar units] Teff – Effective temperature [K] logg – log10(surface gravity) [cgs] mags (dict) – Dictionary of absolute magnitudes in different bands tri (scipy.spatial.qhull.Delaunay, optional) – Triangulation object used to initialize the interpolation functions. If pre-computed triangulation not provided, then the constructor will calculate one. This might take several minutes, so be patient. Much better to use pre-computed ones, as provided in, e.g., dartmouth.Dartmouth_Isochrone. minage,maxage – If desired, a minimum or maximum age can be manually entered.
agerange(m, feh=0.0)[source]

For a given mass and feh, returns the min and max allowed ages.

delta_nu(*args)[source]

Returns asteroseismic delta_nu in uHz

reference: https://arxiv.org/pdf/1312.3853v1.pdf, Eq (2)

density(*args)[source]

Mean density in g/cc

evtrack(m, feh=0.0, minage=None, maxage=None, dage=0.02, return_df=True)[source]

Returns evolution track for a single initial mass and feh.

Parameters: m – Initial mass of desired evolution track. feh – (optional) Metallicity of desired track. Default = 0.0 (solar) maxage (minage,) – (optional) Minimum and maximum log(age) of desired track. Will default to min and max age of model isochrones. dage – (optional) Spacing in log(age) at which to evaluate models. Default = 0.02 return_df – (optional) Whether to return a DataFrame or dicionary. Default is True. Either a pandas.DataFrame or dictionary representing the evolution track—fixed mass, sampled at chosen range of ages.
isochrone(age, feh=0.0, minm=None, maxm=None, dm=0.02, return_df=True, distance=None, AV=0.0)[source]

Returns stellar models at constant age and feh, for a range of masses

Parameters: age – log10(age) of desired isochrone. feh – (optional) Metallicity of desired isochrone (default = 0.0) maxm (minm,) – (optional) Mass range of desired isochrone (will default to max and min available) dm – (optional) Spacing in mass of desired isochrone. Default = 0.02 Msun. return_df – (optional) Whether to return a :class:pandas.DataFrame or dictionary. Default is True. distance – Distance in pc. If passed, then mags will be converted to apparent mags based on distance (and AV). AV – V-band extinction (magnitudes). pandas.DataFrame or dictionary containing results.
nu_max(*args)[source]

Returns asteroseismic nu_max in uHz

reference: https://arxiv.org/pdf/1312.3853v1.pdf, Eq (3)

random_points(n, minmass=None, maxmass=None, minage=None, maxage=None, minfeh=None, maxfeh=None)[source]

Returns n random mass, age, feh points, none of which are out of range.

Parameters: n – Number of desired points. maxmass (minmass,) – (optional) Desired allowed range. Default is mass range of self. maxage (minage,) – (optional) Desired allowed range. Default is log10(age) range of self. maxfeh (minfehs,) – (optional) Desired allowed range. Default is feh range of self. np.ndarray arrays of randomly selected mass, log10(age), and feh values within allowed ranges. Used, e.g., to initialize random walkers for StarModel fits.

## MIST¶

Stellar model grids from the MESA Isochrones and Stellar Tracks. These grids cover a larger range in mass, age, and [Fe/H], compared to the Dartmouth grids, and are thus preferred. Because this is a larger grid, interpolation here is implemented via the FastIsochrone implementation, rather than the standard Delaunay triangulation-based Isochrone implementation.

class isochrones.mist.MIST_Isochrone(*args, **kwargs)[source]

MESA Isochrones and Stellar Tracks

Parameters: bands – (optional) List of desired photometric bands. Default list of bands is ['G','B','V','J','H','K','W1','W2','W3','g','r','i','z','Kepler']. Here B and V are Tycho-2 mags, griz are SDSS, and G is Gaia G-band.

Details of models are here.

modelgrid

alias of isochrones.mist.grid.MISTModelGrid

## Dartmouth¶

Stellar model grids from the Dartmouth Stellar Evolution Database. Because these grids contain fewer points, both interpolation options are available: Dartmouth_Isochrone and Dartmouth_FastIsochrone.

class isochrones.dartmouth.Dartmouth_Isochrone(bands=None, afe='afep0', y='', **kwargs)[source]

Dotter (2008) Stellar Models, at solar a/Fe and He abundances.

Parameters: bands – (optional) List of desired photometric bands. Default list of bands is ['B','V','g','r','i','z','J','H','K','W1','W2','W3','Kepler'].

Model grids are obtained from here

agerange(m, feh=0.0)[source]

For a given mass and feh, returns the min and max allowed ages.

## StarModel¶

Estimating a star’s physical properties based on a set of observed properties involves instantiating a StarModel.

class isochrones.StarModel(ic, obs=None, N=1, index=0, name='', use_emcee=False, RA=None, dec=None, coords=None, **kwargs)[source]
Parameters: ic – Isochrone object used to model star. obs – (optional) ObservationTree object containing photometry information. If not provided, then one will be constructed from the provided keyword arguments (which must include at least one photometric bandpass). This should only happen in the simplest case of a single star system—if multiple stars are detected in any of the observations being used, an ObservationTree should be passed. If obs is a string, then it is assumed to be a filename of an obs summary DataFrame. N – Number of model stars to assign to each “leaf node” of the ObservationTree. If you want to model a binary star, provide N=2. **kwargs – Keyword arguments must be properties of given isochrone, e.g., logg, feh, Teff, and/or magnitudes. The values represent measurements of the star, and must be in (value,error) format. All such keyword arguments will be held in self.properties. parallax is also a valid property, and should be provided in miliarcseconds, as is density [g/cc], and nu_max and delta_nu (asteroseismic parameters in uHz.)
corner_observed(**kwargs)[source]

Makes corner plot for each observed node magnitude

evidence

Log(evidence) from multinest fit

fit_mcmc(nwalkers=300, nburn=200, niter=100, p0=None, initial_burn=None, ninitial=50, loglike_kwargs=None, **kwargs)[source]

Fits stellar model using MCMC.

Parameters: nwalkers – (optional) Number of walkers to pass to emcee.EnsembleSampler. Default is 200. nburn – (optional) Number of iterations for “burn-in.” Default is 100. niter – (optional) Number of for-keeps iterations for MCMC chain. Default is 200. p0 – (optional) Initial parameters for emcee. If not provided, then chains will behave according to whether inital_burn is set. initial_burn – (optional) If True, then initialize walkers first with a random initialization, then cull the walkers, keeping only those with > 15% acceptance rate, then reinitialize sampling. If False, then just do normal burn-in. Default is None, which will be set to True if fitting for distance (i.e., if there are apparent magnitudes as properties of the model), and False if not. ninitial – (optional) Number of iterations to test walkers for acceptance rate before re-initializing. loglike_args – Any arguments to pass to StarModel.loglike(), such as what priors to use. **kwargs – Additional keyword arguments passed to emcee.EnsembleSampler constructor. emcee.EnsembleSampler object.
fit_multinest(n_live_points=1000, basename=None, verbose=True, refit=False, overwrite=False, test=False, **kwargs)[source]

Fits model using MultiNest, via pymultinest.

Parameters: n_live_points – Number of live points to use for MultiNest fit. basename – Where the MulitNest-generated files will live. By default this will be in a folder named chains in the current working directory. Calling this will define a _mnest_basename attribute for this object. verbose – Whether you want MultiNest to talk to you. overwrite (refit,) – Set either of these to true if you want to delete the MultiNest files associated with the given basename and start over. **kwargs – Additional keyword arguments will be passed to pymultinest.run().
classmethod from_ini(ic, folder='.', ini_file='star.ini', **kwargs)[source]

Initialize a StarModel from a .ini file

The “classic” format (version <= 0.9) should still work for a single star, where all properties are just listed in the file; e.g.,

J = 10, 0.05 H = 9.5, 0.05 K = 9.0, 0.05 Teff = 5000, 150

If there are multiple stars observed, you can either define them in the ini file, or use the obsfile keyword, pointing to a file with the summarized photometric observations. In this case, spectroscopic/parallax info should still be included in the .ini file; e.g.,

obsfile = obs.csv Teff = 5000, 150

The obsfile should be a comma-separated table with the following columns: [name, band, resolution, mag, e_mag, separation, pa, relative].

• name is the name of instrument
• band is the photometric bandpass
• resolution is the approximate spatial resolution of instrument
• mag, e_mag describe magnitude of source (absolute or relative)
• separation, pa describe position of source
• relative: single-bit flag; if 1 then magnitudes taken with this instrument are assumed to be relative rather than absolute.

If an obsfile is not provided, you can also define all the same information in the ini file, following these rules:

• Every instrument/survey gets its own [section]. Sections are only

created for different photometric observations.

• if photometry relates to all stars in aperture, there is no extra info in the section, just the photometry. In this case, it is also assumed that the photometry is absolute. (relative=False)
• If ‘resolution’ is an attribute under a particular survey section (and

‘relative’ is not explicitly stated), then the survey is assumed to have relative photometry, and to be listing information about companion stars. In this case, there must be “separation” and “PA” included for each companion. If there is more than one companion star, they must be identifed by tag, e.g., separation_1, PA_1, Ks_1, J_1, etc. The tag can be anything alphanumeric, but it must be consistent within a particular section (instrument). If there is no tag, there is assumed to be only one companion detected.

• If there are no sections, then bands will be interpreted at face value

and will all be assumed to apply to all stars modeled.

• Default is to model each star in the highest-resolution observation as a

single star, at the same distance/age/feh/AV.

The N and index parameters may also be provided, to specify the relations between the model stars. If these are not provided, then N will default to 1 (one model star per star observed in highest-resolution observation) and index will default to all 0 (all stars physically associated).

classmethod load_hdf(filename, path='', name=None)[source]

A class method to load a saved StarModel from an HDF5 file.

File must have been created by a call to StarModel.save_hdf().

Parameters: filename – H5 file to load. path – (optional) Path within HDF file. StarModel object.
maxlike(p0, **kwargs)[source]

Finds (local) optimum in parameter space.

mnest_analyzer

PyMultiNest Analyzer object associated with fit.

See PyMultiNest documentation for more.

mnest_basename

Full path to basename

mnest_loglike(cube, ndim, nparams)[source]

loglikelihood function for multinest

print_ascii()[source]

Prints an ascii representation of the observation tree structure.

random_samples(n)[source]

Returns a random sampling of given size from the existing samples.

Parameters: n – Number of samples pandas.DataFrame of length n with random samples.
sampler

Sampler object from MCMC run.

samples

Dataframe with samples drawn from isochrone according to posterior

Columns include both the sampling parameters from the MCMC fit (mass, age, Fe/H, [distance, A_V]), and also evaluation of the Isochrone at each of these sample points—this is how chains of physical/observable parameters get produced.

save_hdf(filename, path='', overwrite=False, append=False)[source]

Saves object data to HDF file (only works if MCMC is run)

Samples are saved to /samples location under given path, ObservationTree is saved to /obs location under given path.

Parameters: filename – Name of file to save to. Should be .h5 file. path – (optional) Path within HDF file structure to save to. overwrite – (optional) If True, delete any existing file by the same name before writing. append – (optional) If True, then if a file exists, then just the path within the file will be updated.