<commit_before>isochrones
=======

``isochrones`` is a package built to simplify common tasks that are
often done with stellar model grids, such as simulating synthetic
stellar populations, plotting evolution tracks or isochrones,
or estimating the physical properties of a star
given photometric or spectroscopic observations.  The guts of this
code is a 3-d linear interpolation in mass--age--[Fe/H] space. That is,
the model predicts the various properties as functions of these
inputs.

While ``isochrones`` comes packaged with three different model grids
(Padova, BASTI, and Dartmouth), it can be easily extended to a
user-defined grid.  It uses `emcee
<http://dan.iel.fm/emcee/current/>`_ for MCMC sampling.

Note that the first time you import any of the pre-packaged model
grids, it will download the required data to a ``~/.isochrones``
folder.

I welcome community feedback to help improve this tool.  The code is
hosted at `GitHub <http://github.com/timothydmorton/isochrones>`_,
please feel free to contribute. 

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.

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.dartmouth import Dartmouth_Isochrone
    >>> dar = Dartmouth_Isochrone()
    >>> dar.radius(1.0, 9.7, 0.0) #M/Msun, log10(age), Fe/H
        1.0160123968403469

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

    >>> dar.radius([0.8, 1.0, 1.2], 9.7, 0.0)
        array([ 0.75105438,  1.0160124 ,  1.77470954])

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

.. code-block:: python

    from isochrones import StarModel
    from isochrones.dartmouth import Dartmouth_Isochrone

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

    model  = StarModel(dar, Teff=Teff, logg=logg, feh=feh)
    model.fit_mcmc()

The model now has a ``samples`` property that contains all of the
samples generated by the MCMC chain in a :class:`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.  If you have installed the handy `triangle
<https://github.com/dfm/triangle.py>`_ module, you can also
visualize the results:

.. code-block:: python

   model.triangle()

Note that a :class:`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.

If apparent magnitudes are included among the properties, then a call
to :func:`isochrones.StarModel.fit_mcmc` will fit for distance and extinction as
well as mass, age, and [Fe/H].  In this case, it is encouraged to set
the ``maxAV`` and ``max_distance`` arguments to appropriate values.

API Documentation
-----------------

.. toctree::
   :maxdepth: 2

   api
<commit_msg>doc edits<commit_after>isochrones
=======

``isochrones`` is a package built to simplify common tasks that are
often done with stellar model grids, such as simulating synthetic
stellar populations, plotting evolution tracks or isochrones,
or estimating the physical properties of a star
given photometric or spectroscopic observations.  The guts of this
code is a 3-d linear interpolation in mass--age--[Fe/H] space. That is,
the model predicts the various properties as functions of these
inputs.

While ``isochrones`` comes packaged with three different model grids
(Padova, BASTI, and Dartmouth), it can be easily extended to a
user-defined grid.  It uses `emcee
<http://dan.iel.fm/emcee/current/>`_ for MCMC sampling.

Note that the first time you import any of the pre-packaged model
grids, it will download the required data to a ``~/.isochrones``
folder.

I welcome community feedback to help improve this tool.  The code is
hosted at `GitHub <http://github.com/timothydmorton/isochrones>`_,
please feel free to contribute. 

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.

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.dartmouth import Dartmouth_Isochrone
    >>> dar = Dartmouth_Isochrone()
    >>> dar.radius(1.0, 9.7, 0.0) #M/Msun, log10(age), Fe/H
        1.0160123968403469

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

    >>> dar.radius([0.8, 1.0, 1.2], 9.7, 0.0)
        array([ 0.75105438,  1.0160124 ,  1.77470954])

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:

.. code-block:: python

    from isochrones import StarModel
    from isochrones.dartmouth import Dartmouth_Isochrone

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

    model  = StarModel(dar, Teff=Teff, logg=logg, feh=feh)
    model.fit_mcmc()

The model now has a ``samples`` property that contains all of the
samples generated by the MCMC chain in a :class:`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.  If you have installed the handy `triangle
<https://github.com/dfm/triangle.py>`_ module, you can also
visualize the results:

.. code-block:: python

   model.triangle()

Note that a :class:`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.

If apparent magnitudes are included among the properties, then a call
to :func:`isochrones.StarModel.fit_mcmc` will fit for distance and extinction as
well as mass, age, and [Fe/H].  In this case, it is encouraged to set
the ``maxAV`` and ``max_distance`` arguments to appropriate values.

After running the 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')


API Documentation
-----------------

.. toctree::
   :maxdepth: 2

   api

{'fraction_non_alphanumeric': 0.0951362907536077, 'fraction_numerical': 0.021913415285943347, 'mean_word_length': 3.7888675623800383, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 33, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6460048', 'n_tokens_mistral': 2358, 'n_tokens_neox': 2117, 'n_words': 938}