update docs and version bump->0.4

lgbouma · May 30, 2024 · 95f9e12 · 95f9e12
1 parent cb9d615
commit 95f9e12
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 22 deletions.
diff --git a/docs/source/caveats.rst b/docs/source/caveats.rst
@@ -6,10 +6,10 @@ Stellar Evolution
 
 This code models the ensemble evolution of rotation periods for main-sequence
 stars with temperatures of 3800-6200 K (masses of 0.5-1.2 solar).  The 
-calibration data for the model span 0.08-2.6 Gyr.  At younger ages, rotation
+calibration data for the model span 0.08-4 Gyr.  At younger ages, rotation
 periods are less predictive of age, and other age indicators may be more
-useful.  At older ages, the effects of stellar evolution begin to become
-important, especially for the more massive stars.
+useful.  At older ages, the effects of stellar evolution become important,
+especially for the more massive stars.
 
 If you have auxiliary data, such as stellar surface gravities derived from
 spectra, they can help determine whether your star might have undergone

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,7 +22,7 @@
 author = 'Luke Bouma et al'
 
 # The full version, including alpha/beta/rc tags
-release = '0.3'
+release = '0.4'
 
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -1,12 +1,12 @@
 Examples
 ========================================
 
-Gyrochronal age for one star
+Rotation-based age for one star
 ++++++++++++++++++++++++++++++++++++++++
 
 Given a single star's rotation period, effective temperature, and
-uncertainties, what is the gyrochronological age posterior over a grid spanning
-0 to 2.6 Gyr?
+uncertainties, what is the rotation-based age posterior over a grid spanning 0
+to 2.6 Gyr?
 
 .. code-block:: python
 
@@ -69,8 +69,47 @@ period and temperature overlap with the era of "`stalled spin-down
 <https://ui.adsabs.harvard.edu/abs/2020ApJ...904..140C/abstract>`_".
 
 
+Age for an older star
+++++++++++++++++++++++++++++++++++++++++
+The oldest stars for which ``gyro-interp`` gives well-calibrated results are 
+4 Gyr old, which is the age of M67, the oldest calibration cluster.  For a
+longer rotation period, you could run
+
+.. code-block:: python
+
+  import numpy as np
+  from gyrointerp import gyro_age_posterior
+
+  # units: days
+  Prot, Prot_err = 31, 3
+
+  # units: kelvin
+  Teff, Teff_err = 5000, 100
+
+  # uniformly spaced grid between 0 and 5000 megayears
+  age_grid = np.linspace(0, 5000, 500)
+
+  # calculate the age posterior at each age in `age_grid`
+  age_posterior = gyro_age_posterior(
+      Prot, Teff,
+      Prot_err=Prot_err, Teff_err=Teff_err,
+      age_grid=age_grid,
+      bounds_error='4gyrextrap'
+  )
+
+The above example corresponds to a star that sits near the M67 rotation
+sequence (e.g., `Gruner+2023
+<https://ui.adsabs.harvard.edu/abs/2023A%26A...672A.159G/abstract>`_).  In this
+example, we called the keyword argument ``bounds_error`` and set it to
+``'4gyrextrap'``.  For the invested user, the origin of this setting is
+discussed in `this documentation note
+<https://docs.google.com/document/d/1X_tOf1y1e8yvRZFo7NgPTsOSSR5p2J1wsyb1NT3DDB4/edit?usp=sharing>`_,
+and in the `docstrings
+<https://gyro-interp.readthedocs.io/en/latest/gyrointerp.html#gyrointerp.gyro_posterior.gyro_age_posterior>`_.
+
+
 
-Gyrochronal ages for many stars
+Ages for many stars
 ++++++++++++++++++++++++++++++++++++++++
 
 Given the rotation periods, temperatures, and uncertainties for many stars,

diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst
@@ -31,17 +31,23 @@ What happens for stars older than 2.6 Gyr?
 +++++++++++++++++++++++++++++++++++++++++++
 
 For stars older than 2.6 Gyr, we have implemented a few possible extrapolation
-approaches.  Our default adopted approach, the ``pchip_m67`` extrapolation,
-provides one plausible interpolation between 2.6 and 4 Gyr based on the M67
-data, though it is subject to larger systematic errors than e.g., our model
-between 1 and 2.6 Gyr because the change of the slope in rotation period versus
-time is not as well-constrained.  After 4 Gyr, as for α Per we simply force the
-mean model’s rotation period to equal the highest reference rotation period
-values, but now as set by M67.  This yields posterior probability distributions
-that are uniformly distributed at ages older than 4 Gyr.
-
-So, the age posteriors for such systems will be lower limits, and they may or
-may not be useful for you!
+approaches.  Our default adopted approach is to say "please do not try to
+compute ages for such stars", because their spindown rates are currently less
+well-constrained by the data.  This default decision corresponds to calling
+``gyro_age_posteriors`` with ``interp_method=='pchip_m67'`` and
+``bounds_error=='4gyrlimit'``.
+This yields posterior probability distributions
+that are uniformly distributed at ages older than 4 Gyr - in other words, these
+uncertainties are biased near the 4 Gyr boundary!
+
+If you really wish to push the old age limit, this can be done up to 4 Gyr by
+setting ``interp_method=='pchip_m67'`` and ``bounds_error=='4gyrextrap'``.  For
+the invested user, the origin of this setting is discussed in `this
+documentation note
+<https://docs.google.com/document/d/1X_tOf1y1e8yvRZFo7NgPTsOSSR5p2J1wsyb1NT3DDB4/edit?usp=sharing>`_.
+This gives accurate and unbiased ages that reproduce the cluster data up to 4
+Gyr.  Beyond 4 Gyr, other age-dating methods might be a safer choice.
+
 
 Are there movies?
 +++++++++++++++++++++++++++++++++++++++++++

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -83,6 +83,12 @@ User Guide:
 Changelog:
 ++++++++++
 
+**0.4 (2024-05-30)**
+
+* Add ``bounds_error = '4gyrextrap'`` option for 2.6-4 Gyr extrapolation.  The rationale for this update is documented at `this google doc <https://docs.google.com/document/d/1X_tOf1y1e8yvRZFo7NgPTsOSSR5p2J1wsyb1NT3DDB4/edit?usp=sharing>`_.
+* Refactor ``helpers.get_summary_statistics`` for better numerical precision.
+* Add Gruner+2023 M67 data.
+
 **0.3 (2023-03-03)**
 
 * Bugfix a ModuleNotFoundError for calls to ``gyrointerp.plotting``

diff --git a/gyrointerp/__init__.py b/gyrointerp/__init__.py
@@ -1,4 +1,4 @@
-__version__ = 0.3
+__version__ = 0.4
 __uri__ = "https://gyro-interp.readthedocs.io/"
 __author__ = "Luke Bouma"
 __email__ = "[email protected]"

diff --git a/setup.py b/setup.py
@@ -48,7 +48,7 @@ def readme():
 ###############
 
 # run setup.
-version = 0.3
+version = 0.4
 setup(
     name='gyrointerp',
     version=version,
@@ -69,7 +69,7 @@ def readme():
     url='https://github.com/lgbouma/gyro-interp',
     download_url=f'https://github.com/lgbouma/gyro-interp/archive/refs/tags/v{str(version).replace(".","")}.tar.gz',
     author='Luke Bouma',
-    author_email='luke@astro.caltech.edu',
+    author_email='bouma.luke@gmail.com',
     license='MIT',
     packages=[
         'gyrointerp',