Merge pull request #367 from sblunt/v3

V3!!!!!!!!!!!

.github/workflows/python-package.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v3
@@ -40,5 +40,9 @@ jobs:
       run: |
         pytest --cov
     - name: Coveralls GitHub Action
+      if: ${{ matrix.python-version }} == '3.12'
       uses: coverallsapp/github-action@v2
-
+      with:
+        parallel: true
+        flag-name: run-$
+

.github/workflows/run-notebooks.yml

@@ -0,0 +1,36 @@
+name: Test jupyter notebook tutorials
+
+on:
+  push:
+    branches: 
+      - main # only rerun tutorials when making PRs or changing main
+      - v3
+  pull_request:
+    branches: 
+      - '*'
+
+jobs:
+  build:
+
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install jupyter setuptools wheel nbmake
+        python -m pip install -r requirements.txt
+        python -m pip install . --no-build-isolation
+    - name: Run tutorial notebooks
+      run: |
+        py.test --nbmake --nbmake-timeout=3000 docs/tutorials/*.ipynb
+      

.gitignore

@@ -3,12 +3,14 @@ orbitize/example_data/rebound*.csv
 orbitize/example_data/*test.hdf5
 .vscode/launch.json
 .vscode/settings.json
+*.DS_Store
 
 # images & storage files generated by tutorials
 *.hdf5
 !orbitize/example_data/v1_posterior.hdf5
 *.fits
 *.png
+!docs/tutorials/eift_hd206893.png
 tests/test_results.h5
 tests/multiplanet*test.csv
 

docs/conf.py

@@ -51,8 +51,8 @@
 # Disable notebook timeout
 nbsphinx_timeout = -1
 
-# Always re-run notebooks when building docss
-nbsphinx_execute = "always"
+# Only re-run notebooks that have no outputs
+nbsphinx_execute = "auto"
 
 # Allow notebook errors
 nbsphinx_allow_errors = False

docs/index.rst

@@ -50,10 +50,24 @@ User Guide:
    faq
    contributing
    api
+   manual
 
 Changelog:
 ++++++++++
 
+**3.0.0 (2024-4-11)**
+
+- implementation of Hipparcos-Gaia catalog of accelerations fitting! (@semaphoreP)
+- fit arbitrary absolute astrometry (@sblunt)
+- implement O'Neil observation-based priors (@sblunt/@clarissardoo)
+- discuss MCMC autocorrelation in MCMC tutorial (@michaelkmpoon)
+- add time warning if OFTI doesn't accept an orbit in first 60 s (@michaelkmpoon)
+- add first parts of orbitize! manual (@sofiacovarrubias/@sblunt)
+- bugfix for rebound MCMC fits (issue #357; @sblunt)
+- implementation of residual plotting method for orbit plots (@Saanikachoudhary and @semaphoreP)
+- plot companion RVs (@chihchunhsu)
+- add documentation about referencing issues when modifying priors to tutorial (@wcroberson)
+
 **2.2.2 (2023-06-30)**
 
 - tests now overwrite any generated text files (@sblunt)

docs/manual.rst

@@ -0,0 +1,128 @@
+.. _manual:
+
+orbitize! Manual
+==============
+
+Intro to ``orbitize!``
++++++++++++++++++
+
+``orbitize!`` hinges on the two-body problem, which describes the paths of two
+bodies gravitationally bound to each other as a function of time, 
+given parameters determining the position and velocity of both objects at a particular epoch.
+There are many basis sets (orbital bases) that can be used to describe an orbit, 
+which can then be solved using Kepler’s equation, but first it is important to be explicit about coordinate systems. 
+
+.. Note:: 
+    For an interactive visualization to define and help users understand our coordinate system, 
+    you can check out `this GitHub tutorial <https://github.com/sblunt/orbitize/blob/main/docs/tutorials/show-me-the-orbit.ipynb>`_.
+
+    There is also a `YouTube video <https://www.youtube.com/watch?v=0e24VUhQmbM>`_  
+    with use and explanation of the coordinate system by Sarah Blunt.
+
+In its “standard” mode, ``orbitize!`` assumes that the user only has relative astrometric data to fit. 
+In the ``orbitize!`` coordinate system, relative R.A. and declination can be expressed as the following functions 
+of orbital parameters 
+
+.. math::
+    \Delta R.A. = \pi a(1-ecosE)[cos^2{i\over 2}sin(f+\omega_p+\Omega)-sin^2{i\over 2}sin(f+\omega_p-\Omega)]
+
+    \Delta decl. = \pi a(1-ecosE)[cos^2{i\over 2}cos(f+\omega_p+\Omega)+sin^2{i\over 2}cos(f+\omega_p-\Omega)]
+
+where 𝑎, 𝑒, :math:`\omega_p`, Ω, and 𝑖 are orbital parameters, and 𝜋 is the system parallax. f is
+the true anomaly, and E is the eccentric anomaly, which are related to elapsed time
+through Kepler’s equation and Kepler’s third law
+
+.. math::
+    M = 2\pi ({t\over P}-(\tau -\tau_{ref}))
+
+
+.. math::
+    ({P\over yr})^2 =({a\over au})^3({M_\odot \over M_{tot}})
+    
+    M =E-esinE 
+    
+    f = 2tan^{-1}[\sqrt{{1+e\over 1-e}}tan{E\over 2}]
+
+``orbitize!`` employs two Kepler solvers to convert between mean
+and eccentric anomaly: one that is efficient for the highest eccentricities, and Newton’s method, which in other cases is more efficient for solving for the average
+orbit. See `Blunt et al. (2020) <https://iopscience.iop.org/article/10.3847/1538-3881/ab6663>`_ for more detail.
+
+
+From scrutinizing the above sets of equations, one may observe
+a few important degeneracies:
+
+1. Individual component masses do not show up anywhere in this equation set.
+
+2. The degeneracy between semimajor axis 𝑎, total mass :math:`𝑀_{tot}`, and
+parallax 𝜋. If we just had relative astrometric measurements and no external knowledge of the system parallax, 
+we would not be able to distinguish between a system
+that has larger distance and larger semimajor axis (and therefore larger total mass,
+assuming a fixed period) from a system that has smaller distance, smaller semimajor
+axis, and smaller total mass. 
+
+3. The argument of periastron :math:`\omega_p` and the position angle of nodes Ω. 
+The above defined R.A. and decl. functions are invariant to the transformation:
+
+.. math::
+    \omega_p' = \omega_p + \pi
+    
+    \Omega' = \Omega - \pi
+
+which creates a 180◦ degeneracy between particular values of :math:`\omega_p` and Ω, and
+a characteristic “double-peaked” structure in marginalized 1D posteriors of these
+parameters. 
+
+Solutions to breaking degeneracies 1 and 3 can be found in the next section. 
+
+
+Using Radial Velocities 
++++++++++++++++++
+In the ``orbitize!`` coordinate system, and relative to the system barycenter, the
+radial velocity of the planet due to the gravitational influence of the star is:
+
+.. math::
+    rv_p(f) = \sqrt{{G\over (1-e^2)}}M_* sini(M_{tot})^{-1/2}a^{-1/2}(cos(\omega_p+f)+ecos\omega_p)
+
+    rv_*(f) = \sqrt{{G\over (1-e^2)}}M_p sini(M_{tot})^{-1/2}a^{-1/2}(cos(\omega_*+f)+ecos\omega_*)
+
+where 𝜔∗ is the argument of periastron of the star’s orbit, which is equal to 𝜔𝑝 +
+180◦.
+
+In these equations, the individual component masses m𝑝 and m∗ enter. This means
+radial velocity measurements break the total mass degeneracy and enable measurements of individual component masses 
+(“dynamical” masses). However it is crucial to keep in mind that radial velocities of a planet do not enable 
+dynamical mass measurements of the planet itself, but of the star. 
+Radial velocity measurements also break the Ω/𝜔 degeneracy discussed in the
+previous section, uniquely orienting the orbit in 3D space.
+
+``orbitize!`` can perform joint fits of RV and astrometric data in two different
+ways, which have complementary applications. 
+
+The first method is automatically triggered when an ``orbitize!`` user inputs radial velocity data. 
+``orbitize!`` automatically parses the data, sets up an appropriate model, 
+then runs the user’s Bayesian computation
+algorithm of choice to jointly constrain all free parameters in the fit. 
+``orbitize!`` can handle both primary and secondary RVs, and fits for the appropriate dynamical
+masses when RVs are present; when primary RVs are included, ``orbitize!`` fits for
+the dynamical masses of secondary objects, and vice versa. 
+Instrumental nuisance parameters (RV zeropoint offset, 𝛾, and white noise jitter, 𝜎) for each RV instrument
+are also included as additional free parameters in the fit if the user specifies different
+instrument names in the data file.
+
+The second method of jointly fitting RV and astrometric data in ``orbitize!`` separates out the fitting of 
+radial velocities and astrometry, enabling a user to fit “one at a
+time,” and combine the results in a Bayesian framework. First, a user performs a
+fit to just the radial velocity data using, for example, radvel (but can be any radial
+velocity orbit-fitting code). The user then feeds the numerical posterior samples
+into ``orbitize!`` through the ``orbitize.priors.KDEPrior`` object. This prior
+creates a representation of the prior using kernel density estimation 
+(`kernel density estimation <https://mathisonian.github.io/kde/>`_),
+which can then be used to generate random prior samples or compute the prior
+probability of a sample orbit. Importantly, this prior preserves covariances between
+input parameters, allowing ``orbitize!`` to use an accurate representation of the RV
+posterior to constrain the fit. This method can be referred to as the “posteriors as priors”
+method, since posteriors output from a RV fitting code are, through KDE sampling,
+being applied as priors in ``orbitize!`` .
+
+
+More coming soon!

docs/tutorials.rst

@@ -55,6 +55,8 @@ us if you are still confused).
    tutorials/Using_nonOrbitize_Posteriors_as_Priors.ipynb
    tutorials/Changing_bases_tutorial.ipynb
    tutorials/Hipparcos_IAD.ipynb
+   tutorials/HGCA_tutorial.ipynb
+   tutorials/abs_astrometry.ipynb