Merge pull request #233 from adrn/moar-docs

Docs improvements

CHANGES.rst

@@ -11,6 +11,8 @@ New Features
   objects, or to create Gala potential objects from a pre-existing Galpy
   potential.
 
+- Added a ``plot_3d()`` method for ``Orbit`` objects to make 3D plots of the
+  orbital trajectories.
 
 Bug fixes
 ---------
@@ -33,6 +35,8 @@ Bug fixes
 API changes
 -----------
 
+- Removed the deprecated ``gala.coordinates.get_galactocentric2019()`` function.
+
 
 1.3 (2020-10-27)
 ================

docs/conventions.rst

@@ -23,23 +23,23 @@ Array shapes
 ============
 
 The arrays and :class:`~astropy.units.Quantity` objects expected as input and
-returned as ouput throughout ``Gala`` have shapes that follow a particular
+returned as output throughout ``Gala`` have shapes that follow a particular
 convention, unless otherwise specified in function or class docstrings.
 
 For arrays containing coordinate or kinematic information, ``axis=0`` is assumed
-to be the coordinate dimension. For example, for representing 128 Cartesian 3D
-positions, the object would have shape ``(3,128)``.
+to be the coordinate dimension. For example, for representing 128 different 3D
+Cartesian positions, the object should have shape ``(3, 128)``.
 
-For collections of orbits, arrays have 3 axes. As above, ``axis=0`` is assumed
-to be the coordinate dimension, but now ``axis=1`` is interpreted as the time
-axis, and ``axis=2`` are the individual orbits.
+For collections of orbits, arrays or array-valued objects have three axes: As
+above, ``axis=0`` is assumed to be the coordinate dimension, ``axis=1`` is
+interpreted as the time axis, and ``axis=2`` are the different orbits.
 
 .. _energy-momentum:
 
 Energy and momentum
 ===================
 
 The `gala` documentation and functions often refer to energy and angular
-momentum and the respective quantities *per unit mass* interchangibly. Unless
+momentum and the respective quantities *per unit mass* interchangeably. Unless
 otherwise specified, all such quantities -- e.g., energy, angular momentum,
 momenta, conjugate momenta -- are in fact used and returned *per unit mass*.

docs/coordinates/greatcircle.rst

@@ -21,14 +21,14 @@ coordinate system, such as the ICRS. The great circle system is defined by a
 specified north pole, with a additional (optional) specification of the
 longitude zero point of the final system.
 
-Currently, ``gala`` supports great circle frames that are defined as a rotation
+`gala` currentlt supports great circle frames that are defined as a rotation
 away from the ICRS (ra, dec) through the
 `~gala.coordinates.GreatCircleICRSFrame` class. To create a new great circle
-frame, you must specify a pole using the ``pole=`` keywrod, and optionally
+frame, you must specify a pole using the ``pole=`` keyword, and optionally
 specify the longitude zero point either by specifying the right ascension of the
 longitude zero point, ``ra0``, or by specifying a final rotation to be applied
 to the transformation, ``rotation``. For example, to define a great circle
-system with the pole at (RA, Dec) = (32.5, 19.8), we first have to create a
+system with the pole at (RA, Dec) = (32.5, 19.8)º, we first have to create a
 coordinate object for the pole::
 
     >>> pole = coord.SkyCoord(ra=32.5*u.deg, dec=19.8*u.deg)
@@ -39,7 +39,7 @@ define our coordinate frame::
     >>> fr = gc.GreatCircleICRSFrame(pole=pole)
 
 We can then use this frame like any other Astropy coordinate frame. For example,
-we can transform other coordinate to this new coordinate system using::
+we can transform other coordinates to this new coordinate system using::
 
     >>> c = coord.SkyCoord(ra=[160, 53]*u.deg, dec=[-11, 9]*u.deg)
     >>> c_fr = c.transform_to(fr)
@@ -61,7 +61,8 @@ The transformation also works for velocity components. For example, if we have a
 sky position and proper motions, we can transform to the great circle frame in
 the same way::
 
-    >>> c = coord.SkyCoord(ra=160*u.deg, dec=-11*u.deg,
+    >>> c = coord.SkyCoord(ra=160*u.deg,
+    ...                    dec=-11*u.deg,
     ...                    pm_ra_cosdec=5*u.mas/u.yr,
     ...                    pm_dec=0.3*u.mas/u.yr)
     >>> c_fr = c.transform_to(fr)

docs/coordinates/index.rst

@@ -30,7 +30,7 @@ values adopted in Astropy v4.0:
 Stellar stream coordinate frames
 ================================
 
-`Gala` provides Astropy coordinate frame classes for transforming to several
+`gala` provides Astropy coordinate frame classes for transforming to several
 built-in stellar stream stream coordinate frames (as defined in the references
 below), and for transforming positions and velocities to and from coordinate
 systems defined by great circles or poles. These classes behave like the
@@ -42,15 +42,15 @@ with the Sagittarius stream with the `~gala.coordinates.SagittariusLaw10`
 frame::
 
     >>> c = coord.ICRS(ra=100.68458*u.degree, dec=41.26917*u.degree)
-    >>> sgr = c.transform_to(gc.SagittariusLaw10)
+    >>> sgr = c.transform_to(gc.SagittariusLaw10())
     >>> (sgr.Lambda, sgr.Beta) # doctest: +FLOAT_CMP
     (<Longitude 179.58511053544734 deg>, <Latitude -12.558450192162654 deg>)
 
 Or, to transform from `~gala.coordinates.SagittariusLaw10` coordinates to the
 `~astropy.coordinates.Galactic` frame::
 
     >>> sgr = gc.SagittariusLaw10(Lambda=156.342*u.degree, Beta=1.1*u.degree)
-    >>> c = sgr.transform_to(coord.Galactic)
+    >>> c = sgr.transform_to(coord.Galactic())
     >>> (c.l, c.b) # doctest: +FLOAT_CMP
     (<Longitude 182.5922090437946 deg>, <Latitude -9.539692094685893 deg>)
 
@@ -59,10 +59,10 @@ can be transformed between the systems. For example, to transform from
 `~gala.coordinates.GD1Koposov10` proper motions to
 `~astropy.coordinates.Galactic` proper motions::
 
-    >>> gd1 = gc.GD1Koposov10(phi1=-35.00*u.degree, phi2=0*u.degree,
+    >>> gd1 = gc.GD1Koposov10(phi1=-35*u.degree, phi2=0*u.degree,
     ...                       pm_phi1_cosphi2=-12.20*u.mas/u.yr,
     ...                       pm_phi2=-3.10*u.mas/u.yr)
-    >>> gd1.transform_to(coord.Galactic) # doctest: +FLOAT_CMP
+    >>> gd1.transform_to(coord.Galactic()) # doctest: +FLOAT_CMP
     <Galactic Coordinate: (l, b) in deg
         (181.28968151, 54.84972806)
      (pm_l_cosb, pm_b) in mas / yr
@@ -77,7 +77,7 @@ position and velocity, we can transform to a
     ...                       pm_phi1_cosphi2=-12.20*u.mas/u.yr,
     ...                       pm_phi2=-3.10*u.mas/u.yr,
     ...                       radial_velocity=-32*u.km/u.s)
-    >>> gd1.transform_to(coord.Galactocentric) # doctest: +FLOAT_CMP
+    >>> gd1.transform_to(coord.Galactocentric()) # doctest: +FLOAT_CMP
     <Galactocentric Coordinate (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
         (266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg): (x, y, z) in kpc
         (-12.61622659, -0.09870921, 6.43179403)
@@ -97,7 +97,8 @@ and returns a coordinate object with the solar motion added back in to the
 velocity components. This is useful for computing velocities in a Galactocentric
 reference frame, rather than a solar system barycentric frame.
 
-To use, you pass in a coordinate object with scalar or array values::
+The `~gala.coordinates.reflex_correct` function accepts a coordinate object with
+scalar or array values::
 
     >>> c = coord.SkyCoord(ra=[180.323, 1.523]*u.deg,
     ...                    dec=[-17, 29]*u.deg,
@@ -112,10 +113,12 @@ To use, you pass in a coordinate object with scalar or array values::
         [(139.47001884, 175.45769809, -47.09032586),
         (-61.01738781,  61.51055793, 163.36721898)]>
 
-By default, this uses the default solar location and velocity from the
-`astropy.coordinates.Galactocentric` frame class. To modify these, for example,
-to change the solar velocity, or the sun's height above the Galactic midplane,
-use the arguments of that class::
+By default, this uses the solar location and velocity from the
+`astropy.coordinates.Galactocentric` frame class. To modify these parameters,
+for example, to change the solar velocity, or the sun's height above the
+Galactic midplane, use the arguments of the `astropy.coordinates.Galactocentric`
+class and pass in an instance of the `astropy.coordinates.Galactocentric`
+frame::
 
     >>> vsun = coord.CartesianDifferential([11., 245., 7.]*u.km/u.s)
     >>> gc_frame = coord.Galactocentric(galcen_v_sun=vsun, z_sun=0*u.pc)
@@ -162,19 +165,18 @@ values of the proper motions) -- this is sometimes called "v_GSR"::
 Transforming a proper motion covariance matrix to a new coordinate frame
 ------------------------------------------------------------------------
 
-When working with Gaia or other astrometric data sets, we often need to
-transform the reported covariance matrix between proper motion components into a
-new coordinate system. For example, Gaia data are provided in the
+When working with Gaia or other astrometric data sets, you may need to transform
+the reported covariance matrix between proper motion components into a new
+coordinate system. For example, Gaia data are provided in the
 `~astropy.coordinates.ICRS` (equatorial) coordinate frame, but for Galactic
-science, we often want to instead work in the
-`~astropy.coordinates.Galactic` coordinate system.
-For this and other transformations that only require a rotation (i.e. the origin
-doesn't change), the astrometric covariance matrix can be transformed exactly
-through a projection of the rotation onto the tangent plane at a given location.
-The details of this procedure are explained in `this document from the Gaia data
-processing team
+science, we often want to instead work in the `~astropy.coordinates.Galactic`
+coordinate system. For this and other transformations that only require a
+rotation (i.e. the origin doesn't change), the astrometric covariance matrix can
+be transformed exactly through a projection of the rotation onto the tangent
+plane at a given location. The details of this procedure are explained in `this
+document from the Gaia data processing team
 <https://gea.esac.esa.int/archive/documentation/GDR2/Data_processing/chap_cu3ast/sec_cu3ast_intro/ssec_cu3ast_intro_tansforms.html>`_,
-and this functionality is implemented in gala. Let's first create a coordinate
+and this functionality is implemented in `gala`. Let's first create a coordinate
 object to transform::
 
     >>> c = coord.SkyCoord(ra=62*u.deg,
@@ -190,23 +192,22 @@ be constructed from a single row from a Gaia data release source catalog::
 
 This matrix specifies the 2D error distribution for the proper motion
 measurement *in the ICRS frame*. To transform this matrix to, e.g., the Galactic
-coordinate system, we can use the function
+coordinate system, use the function
 `~gala.coordinates.transform_pm_cov`::
 
-    >>> gc.transform_pm_cov(c, cov, coord.Galactic) # doctest: +FLOAT_CMP
+    >>> gc.transform_pm_cov(c, cov, coord.Galactic()) # doctest: +FLOAT_CMP
     array([[ 0.69450047, -0.309945  ],
            [-0.309945  ,  0.96413005]])
 
-Note that this works for all of the great circle or stellar stream coordinate
-frames implemented in gala::
+Note that this also works for all of the great circle or stellar stream
+coordinate frames implemented in `gala`::
 
-    >>> gc.transform_pm_cov(c, cov, gc.GD1Koposov10) # doctest: +FLOAT_CMP
+    >>> gc.transform_pm_cov(c, cov, gc.GD1Koposov10()) # doctest: +FLOAT_CMP
     array([[1.10838914, 0.19067958],
            [0.19067958, 0.55024138]])
 
-Also note that this works for multiple coordinates (i.e. array coordinates) as
-well, so try to avoid looping over this function and instead apply it to
-array-valued coordinate objects.
+This works for array-valued coordinates as well, so try to avoid looping over
+this function and instead apply it to array-valued coordinate objects.
 
 
 References

docs/dynamics/actionangle.rst

@@ -89,6 +89,7 @@ We will now integrate the orbit and plot it in the meridional plane::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     import astropy.coordinates as coord
     import astropy.units as u
@@ -110,10 +111,10 @@ We will now integrate the orbit and plot it in the meridional plane::
 To solve for the actions in the true potential, we first compute the actions in
 a "toy" potential -- a potential in which we can compute the actions and angles
 analytically. The two simplest potentials for which this is possible are the
-`~gala.potential.IsochronePotential` and
-`~gala.potential.HarmonicOscillatorPotential`. We will use the Isochrone
-potential as our toy potential for tube orbits and the harmonic oscillator for
-box orbits.
+`~gala.potential.potential.IsochronePotential` and
+`~gala.potential.potential.HarmonicOscillatorPotential`. We will use the
+Isochrone potential as our toy potential for tube orbits and the harmonic
+oscillator for box orbits.
 
 We start by finding the parameters of the toy potential (Isochrone in this case)
 by minimizing the dispersion in energy for the orbit::
@@ -138,6 +139,7 @@ Instead, the orbit is wobbly in the toy potential angles::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     toy_potential = gd.fit_isochrone(w)
     toy_actions,toy_angles,toy_freqs = toy_potential.action_angle(w)
@@ -160,6 +162,7 @@ time-independent in the toy potential::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     fig,ax = plt.subplots(1,1)
     ax.plot(w.t, toy_actions[0].to(u.km/u.s*u.kpc), marker='')
@@ -168,7 +171,7 @@ time-independent in the toy potential::
     fig.tight_layout()
 
 We can now find approximations to the actions in the true potential. We have to
-choose the maximum integer vector norm, `N_max`, which here we arbitrarilty set
+choose the maximum integer vector norm, `N_max`, which here we arbitrarily set
 to 8. This will change depending on the convergence of the action correction
 (the properties of the orbit and potential) and the accuracy desired::
 
@@ -200,6 +203,7 @@ actions computed using this machinery::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     import warnings
     with warnings.catch_warnings(record=True):
@@ -252,6 +256,7 @@ and the same initial conditions as above:
 .. plot::
     :align: center
     :include-source:
+    :width: 60%
 
     import astropy.coordinates as coord
     import astropy.units as u

docs/dynamics/index.rst

@@ -6,8 +6,7 @@
 Dynamics (`gala.dynamics`)
 ********************************
 
-For code blocks below and any pages linked below, we'll assume the following
-imports have already been executed::
+For the examples below the following imports have already been executed::
 
     >>> import astropy.units as u
     >>> import numpy as np
@@ -73,6 +72,7 @@ coordinate representation, for example, cylindrical radius :math:`\rho` and
 
 .. plot::
     :align: center
+    :width: 60%
 
     import astropy.units as u
     import gala.potential as gp

docs/dynamics/mockstreams.rst

@@ -45,8 +45,8 @@ km/s, and a scale radius of 15 kpc::
 
 The mock stream generation supports any of the reference frames implemented in
 ``gala`` (e.g., non-static / rotating reference frames), so we must create a
-`~gala.potential.Hamiltonian` object to use when generating streams. By default,
-this will use a static reference frame::
+`~gala.potential.hamiltonian.Hamiltonian` object to use when generating streams.
+By default, this will use a static reference frame::
 
     >>> H = gp.Hamiltonian(pot)
 
@@ -99,6 +99,7 @@ Let's plot the stream::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     import astropy.units as u
     import numpy as np
@@ -143,7 +144,7 @@ Hamiltonian. It is possible to include a potential object for the progenitor
 system to account for the self-gravity of the progenitor as stream star
 particles are released. We can use any of the ``gala.potential`` potential
 objects to represent the progenitor system, but here we will use a simple
-`~gala.potential.PlummerPotential`. We pass this in to the
+`~gala.potential.potential.PlummerPotential`. We pass this in to the
 `~gala.dynamics.mockstream.MockStreamGenerator` - let's see what the stream
 looks like when generated including self-gravity::
 
@@ -156,6 +157,7 @@ looks like when generated including self-gravity::
 .. plot::
     :align: center
     :context: close-figs
+    :width: 60%
 
     prog_pot = gp.PlummerPotential(m=prog_mass, b=2*u.pc, units=galactic)
     gen2 = ms.MockStreamGenerator(df, H, progenitor_potential=prog_pot)