Merge pull request #270 from sblunt/develop

v2 beta!

.gitignore

@@ -1,3 +1,16 @@
+# Added by orbitize! Developers
+orbitize/example_data/rebound*.csv
+orbitize/example_data/*test.hdf5
+.vscode/launch.json
+.vscode/settings.json
+
+# images & storage files generated by tutorials
+*.hdf5
+*.fits
+*.png
+tests/test_results.h5
+tests/multiplanet*test.csv
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -106,11 +119,3 @@ ENV/
 
 # utility scripts
 build.sh
-
-# images & storage files generated by tutorials
-*.hdf5
-*.fits
-*.png
-.vscode/settings.json
-tests/test_results.h5
-tests/multiplanet*test.csv

docs/basis.rst

@@ -0,0 +1,8 @@
+.. _basis:
+
+Basis
+=====
+.. module:: orbitize
+
+.. automodule:: orbitize.basis
+	:members:

docs/conversions.rst

@@ -0,0 +1,8 @@
+.. _conversions:
+
+Basis Conversions
+=================
+.. module:: orbitize
+
+.. automodule:: orbitize.conversions
+	:members:

docs/hipparcos.rst

@@ -0,0 +1,8 @@
+.. _hipparcos:
+
+Hipparcos API Module
+====================
+.. module:: orbitize
+
+.. automodule:: orbitize.hipparcos
+	:members:

docs/index.rst

@@ -35,7 +35,7 @@ Attribution:
 * If you use the OFTI algorithm, please also cite `Blunt et al (2017) <https://ui.adsabs.harvard.edu/#abs/2017AJ....153..229B/abstract>`_. 
 * If you use the Affine-invariant MCMC algorithm from ``emcee``, please also cite `Foreman-Mackey et al (2013) <https://ui.adsabs.harvard.edu/abs/2013PASP..125..306F/abstract>`_. 
 * If you use the parallel-tempered Affine-invariant MCMC algorithm from ``ptemcee``, please also cite `Vousden et al (2016) <https://ui.adsabs.harvard.edu/abs/2016MNRAS.455.1919V/abstract>`_. 
-
+* If you use the Hipparcos intermediate astrometric data (IAD) fitting capability, please also cite `Nielsen et al (2020) <https://ui.adsabs.harvard.edu/abs/2020AJ....159...71N/abstract>`_.
 
 
 User Guide:

docs/tutorials/Changing_bases_tutorial.ipynb

@@ -0,0 +1,228 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Fitting in different orbital bases\n",
+    "\n",
+    "In this tutorial, we show how one can perform orbit-fits in different coordinate bases amongst the ones supported by `orbitize`. Currently fitting in different bases is only supported in MCMC, so we will use MCMC to perform an orbit-fit in an orbital basis distinct from the default one. For a general introduction to MCMC, be sure to check out the [MCMC Introduction tutorial](https://orbitize.readthedocs.io/en/latest/tutorials/MCMC_tutorial.html) first!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The \"standard\" and \"XYZ\" bases"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The default way to define an orbit in `orbitize` is through what we call the 'standard basis', which consists of eight parameters: semi-major axis (sma), eccentricity (ecc), inclination (inc), argument of periastron (aop), position angle of the nodes (pan), epoch of periastron expressed as a fraction of the period past a reference epoch (tau), parallax (plx) and total system mass (mtot). Each orbital element has an associated default prior; to see how to explore and modify these priors check out the [Modifying priors tutorial](http://orbitize.info/en/latest/tutorials/Modifying_Priors.html).\n",
+    "\n",
+    "An alternative way to define an orbit is through its position and velocity components in XYZ space for a given epoch; we will call this the 'XYZ basis'. The orbit is thus defined with the array ($x$, $y$, $z$, $\\dot{x}$, $\\dot{y}$,$\\dot{z}$, plx, mtot), with position coordinates measured in AU and velocity components in $\\text{km s}^{-1}$. In this basis, the sky-plane coordinates ($x,y$) are the separations of the planet relative to the primary, with the positive $x$ and $y$ directions coinciding with the positive RA and Dec directions, respectively. The $z$ direction is the line-of-sight coordinate, such that movement in the positive $z$ direction causes a redshift. The default priors are uniform all uniform."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setting up Sampler in the XYZ basis"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The easiest way to run an orbit-fit in an alternative orbital basis in `orbitize` is through the `orbitize.driver.Driver` interface. The process is exactly like initializing a regular `Driver` object, but setting the `fitting_basis` keyword to 'XYZ':"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "import orbitize\n",
+    "from orbitize import driver\n",
+    "import multiprocessing as mp\n",
+    "\n",
+    "filename = \"{}/ \".format(orbitize.DATADIR) # a file with input in radec since rn it only works for that\n",
+    "\n",
+    "# system parameters\n",
+    "num_secondary_bodies = 1\n",
+    "system_mass = 1.75 # [Msol]\n",
+    "plx = 51.44 # [mas]\n",
+    "mass_err = 0.05 # [Msol]\n",
+    "plx_err = 0.12 # [mas]\n",
+    "\n",
+    "# MCMC parameters\n",
+    "num_temps = 5\n",
+    "num_walkers = 20\n",
+    "num_threads = mp.cpu_count() # or a different number if you prefer\n",
+    "\n",
+    "\n",
+    "my_driver = driver.Driver(\n",
+    "    filename, 'MCMC', num_secondary_bodies, system_mass, plx, mass_err=mass_err, plx_err=plx_err, fitting_basis='XYZ',\n",
+    "    mcmc_kwargs={'num_temps': num_temps, 'num_walkers': num_walkers, 'num_threads': num_threads}\n",
+    ")\n",
+    "\n",
+    "s = my_driver.sampler"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### (Properly) initializing walkers in the XYZ basis"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the standard basis at this point we would be ready to use the `s.run_sampler` method to start the sampling, but with the XYZ basis we have to make sure that all our walkers are initialized in a valid region of parameter space. This is because randomly generated values of ($x$, $y$, $z$, $\\dot{x}$, $\\dot{y}$, $\\dot{z}$) can result in unbound, invalid orbits with, for example, negative eccentricities (which is not cool). This can be easily corrected with the `s.validate_xyz_positions` method:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s.validate_xyz_positions()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "___________________"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "After this is done, the sampler can be run and the results saved normally:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "total_orbits = 6000 # number of steps x number of walkers (at lowest temperature)\n",
+    "burn_steps = 10 # steps to burn in per walker\n",
+    "thin = 2 # only save every 2nd step\n",
+    "\n",
+    "s.run_sampler(total_orbits, burn_steps=burn_steps, thin=thin)\n",
+    "s.results.save_results('my_posterior.hdf5')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Loading and converting results"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can load the results as you normally would. The orbit posteriors are saved in the `results.post` attribute, and the basis you used for the fit in the `results.fitting_basis` attribute:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from orbitize import results \n",
+    "\n",
+    "myResults = orbitize.results.Results() # create empty Results object\n",
+    "myResults.load_results('my_posterior.hdf5') \n",
+    "print('The used basis for the fit was ', myResults.fitting_basis)\n",
+    "print('The posteriors are ', myResults.post)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "It is important to note that, as you can probably see, the results will be saved in the XYZ basis, so we might want to convert those back to the standard basis to work with them. For this we can use the `orbitize.conversions` module, which can convert from the standard basis to the XYZ basis and back. To do this, remember that the XYZ basis gives the position and velocity of the planet at a given epoch; so before converting back to standard we need to check the epoch that was used for the fit through the `results.xyz_epochs` attribute:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(myResults.xyz_epochs)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Since we only fit for one planet, we only have one epoch. Now, we can use that epoch to convert back to the good old standard basis:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from orbitize import conversions\n",
+    "xyz_posterior = myResults.post\n",
+    "xyz_epoch = myResults.xyz_epochs\n",
+    "\n",
+    "standard_posterior = conversions.xyz_to_standard(xyz_epoch, xyz_posterior)\n",
+    "\n",
+    "print('My posterior in standard basis is ', standard_posterior)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And we're done! Enjoy the XYZ basis."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "cbafa42b6ff5e39c327df57f5a3bbaee7fd2ec257998acb6b9d49a010b26573d"
+  },
+  "kernelspec": {
+   "display_name": "Python 3.8.3  ('base': conda)",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": ""
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}