.. doctest-skip-all

.. _whatsnew-1.3:

==========================
What's New in Astropy 1.3?
==========================

Overview
--------

Astropy 1.3 is a major release that adds significant new functionality since
the 1.2.x series of releases.

In particular, this release includes:

* The :ref:`WCSAxes framework <whatsnew-1.3-wcsaxes>` for plotting points or
  images on celestial coordinates in matplotlib.
* A :ref:`new function <whatsnew-1.3-rgb>` in ``astropy.visualization`` to
  generate 3-color images from astronomy images in different bands.
* Astropy coordinate representations
  :ref:`now combine like vectors <whatsnew-1.3-representation-arithmetic>`,
  with useful mathematical operations that can be performed on them.
* Astropy coordinates and time objects now
  :ref:`behave much more consistently like arrays <whatsnew-1.3-instance-shapes>`
  when they are reshaped.
* Earth locations can now
  :ref:`be created from a postal address <whatsnew-1.3-of-address>`.
* JPL Ephemerides :ref:`can now be used <whatsnew-1.3-jpl-ephemerides>` in the
  coordinates sub-package to improve the accuracy of coordinate transformations
  and barycentric time corrections.
* A significant
  :ref:`change in the default behavior <whatsnew-1.3-tablechange>` of astropy
  tables when setting to an already-existing column.
* FORTRAN-style extended floating precision files like ``1.495D+238``
  :ref:`can now be read <whatsnew-1.3-fortan-exponents>` using
  ``astropy.io.ascii`` or ``Table.read``.
* Astropy objects can now be serialized to (or re-loaded from)
  :ref:`a standard YAML representation <whatsnew-1.3-yaml-serialization>`.
* FITS HDUs can now be :ref:`lazy loaded<whatsnew-1.3-lazy-loading-fits>`,
  improving performance in files with many HDUs.
* The default cosmology is now :ref:`Planck 2015 <whatsnew-1.3-cosmo>`.
* Coordinate frames with ``obsgeoloc`` and ``obsgeovel`` attributes
  :ref:`now contain representations rather than quantities <whatsnew-1.3-gcrs-repr>`.


In addition to these major changes, Astropy 1.3 includes a large number of
smaller improvements and bug fixes, which are described in the
:ref:`changelog`. By the numbers:

* 467 issues have been closed since v1.2
* 242 pull requests have been merged since v1.2
* 210 distinct people have contributed code

.. _whatsnew-1.3-wcsaxes:

New WCSAxes framework to make plots with celestial coordinates
--------------------------------------------------------------

The :ref:`visualization <astropy-visualization>` subpackage now include the
WCSAxes framework (previously distributed as a separate package) which makes it
possible to make plots in Matplotlib with celestial coordinates on the axes.
Examples and documentation are provided in :ref:`wcsaxes`.

.. plot::
   :context: reset
   :align: center

    import matplotlib.pyplot as plt

    from astropy.wcs import WCS
    from astropy.io import fits
    from astropy.utils.data import get_pkg_data_filename

    filename = get_pkg_data_filename('galactic_center/gc_msx_e.fits')

    hdu = fits.open(filename)[0]
    wcs = WCS(hdu.header)

    ax = plt.subplot(projection=wcs)

    ax.imshow(hdu.data, vmin=-2.e-5, vmax=2.e-4, origin='lower')

    ax.coords.grid(True, color='white', ls='solid')
    ax.coords[0].set_axislabel('Galactic Longitude')
    ax.coords[1].set_axislabel('Galactic Latitude')

    overlay = ax.get_coords_overlay('fk5')
    overlay.grid(color='white', ls='dotted')
    overlay[0].set_axislabel('Right Ascension (J2000)')
    overlay[1].set_axislabel('Declination (J2000)')

.. _whatsnew-1.3-rgb:

New function to contruct RGB images based on Lupton et al. (2004) algorithm
---------------------------------------------------------------------------

The :ref:`visualization <astropy-visualization>` subpackage now includes a
function to create RGB composite images from individual (high dynamic range)
images.  The technique is detailed in `Lupton et al. (2004)`_ and implemented in `~astropy.visualization.make_lupton_rgb`. For more details, see
:ref:`astropy-visualization-rgb`.


.. We use raw here because image directives pointing to external locations fail for some sphinx versions
.. raw:: html

    <a class="reference internal image-reference" href="http://data.astropy.org/visualization/ngc6976.jpeg"><img alt="lupton RGB image" src="http://data.astropy.org/visualization/ngc6976-small.jpeg" /></a>

.. _whatsnew-1.3-representation-arithmetic:

Vector arithmetic using representations
---------------------------------------

:ref:`Representations <astropy-coordinates-representations>` are used inside
coordinates as vectors to points on the sky, but they can more generally be
seen as vectors in any frame from the origin to a given point. In the latter
context, basic arithmetic such as addition and subtraction of vectors,
multiplication or division with a constant, or taking the norm, are all well
defined, and thus :ref:`have been implemented
<astropy-coordinates-representations-arithmetic>`.

.. _whatsnew-1.3-instance-shapes:

Times and coordinates can now be reshaped like arrays
-----------------------------------------------------

The shapes of :class:`~astropy.time.Time` and
:class:`~astropy.coordinates.SkyCoord` instances (as well as underlying frames
and realisations) can now be manipulated just like those of arrays, using
methods with the same name.  For more details, see
:ref:`astropy-time-shape-methods` and
:ref:`astropy-coordinates-array-operations`.


.. _whatsnew-1.3-of-address:

Earth locations can now be obtained by address
----------------------------------------------

With the new :meth:`~astropy.coordinates.EarthLocation.of_address` class
method, :class:`~astropy.coordinates.EarthLocation` objects can now be
easily created using a string address.  For example::

    >>> from astropy.coordinates import EarthLocation
    >>> loc = EarthLocation.of_address("350 5th Ave, New York, NY 10118")
    >>> loc
    <EarthLocation ( 1334938.47885339, -4651088.60103721,  4141299.41836111) m>
    >>> loc.geodetic
    (<Longitude -73.9856554 deg>,
     <Latitude 40.7484404 deg>,
     <Quantity -1.2647149866511903e-09 m>)

This works by querying the Google Maps API to
retrieve the latitude, longitude, and (optional) height of the specified
location. This can be useful for quickly transforming locally to the
:class:`~astropy.coordinates.AltAz` frame without having to look up the
spherical coordinates of a location::

    >>> from astropy.coordinates import SkyCoord, AltAz
    >>> m31 = SkyCoord.from_name('M31').transform_to(AltAz(obstime='2016-12-22 0:00', location=EarthLocation.of_address("350 5th Ave, New York, NY 10118")))
    >>> m31.alt, m31.az
    (<Latitude 85.3804464651436 deg>, <Longitude 279.6441719021479 deg>)


.. _whatsnew-1.3-jpl-ephemerides:

Coordinate transformations and barycentric corrections can use JPL Ephemerides
------------------------------------------------------------------------------

JPL ephemerides, which could already be used to calculate positions of solar
system bodies, can now also be used for :ref:`barycentric corrections
<time-light-travel-time>` and :ref:`coordinate transformations
<astropy-coordinates-transforming-ephemerides>`.


.. _whatsnew-1.3-tablechange:

Change in Table behavior when setting column
--------------------------------------------

Previous to 1.3, :ref:`Tables <astropy-table>` did in-place
modification of a table column when a column was set like
``tab['colname'] = val``.  In 1.3, the default behavior has been set to instead
*replace* a column.  That is, ``tab['colname'] = val`` is now more like
``t.replace_column('a', val)`` than ``tab['colname'][:] = val``.  This behavior
can be turned off for compatibility using the ``table.replace_inplace``
configuration setting (although is future versions of Astropy this capability
will be deprecated and removed).  For more details and examples on this change,
see :ref:`table-replace-1_3`.


.. _whatsnew-1.3-fortan-exponents:

Support for Fortran exponent formats in ASCII tables
----------------------------------------------------

The :ref:`fast reader <fast_ascii_io>` in :ref:`io.ascii <io-ascii>` now
supports FORTRAN-style floating point values (i.e. ``1.495978707D+238``), via
the ``fast_reader`` option ``exponent_style``.  The fast reader also now
supports extended precision to fully read fortran outputs. For more details see
:ref:`fortran_style_exponents`.

.. _whatsnew-1.3-yaml-serialization:

Serialization of Astropy classes to YAML
----------------------------------------

Astropy now has an :mod:`astropy.io.misc.yaml` module, which allows
converting astropy objects into a standard `YAML <http://yaml.org/>`_ format.
For example::

    >>> from astropy.io.misc import yaml
    >>> from astropy import units as u
    >>> print(yaml.dump(1*u.au))
    !astropy.units.Quantity
    unit: !astropy.units.Unit {unit: AU}
    value: 1.0

This functionality requires PyYaml version 3.12 or later.

.. _whatsnew-1.3-lazy-loading-fits:

Performance improvements with lazy-loading in the io.fits sub-package
---------------------------------------------------------------------

The :ref:`io.fits <astropy-io-fits>` sub-package now supports "lazy loading",
where all HDUs are not loaded until they are requested (or the file is closed).
This should provide substantial speedups for situations using the convenience
functions (e.g., :func:`~astropy.io.fits.getheader` or
:func:`~astropy.io.fits.getdata`) to get HDU's that are near the front of a
file with many HDU's.

In the future, this may enable larger speedups using the standard
:func:`astropy.io.fits.open` interface, but at the price of backwards
compatibility.  Currently the interface allows access to HDU's all the way at
the end of a file even after the file has been closed, preventing full use of
the "lazy" loading described above.  To begin discouraging this usage, a
deprecation warning will now be issued when an HDU is accessed in this manner.
Future versions of astropy may remove this capability completely to allow full
lazy HDU loading.


.. _whatsnew-1.3-cosmo:

Planck 2015 now the default cosmology
-------------------------------------

The default cosmology in the :ref:`astropy-cosmology` sub-package is
now the Planck 2015 cosmology, and the references have been updated
to reflect the published papers.

.. _whatsnew-1.3-gcrs-repr:

GCRS and PrecessedGeocentric attributes are now representations
---------------------------------------------------------------

The `astropy.coordinates.GCRS` and `astropy.coordinates.PrecessedGeocentric`
frames have been subtly changed such that their ``obsgeoloc`` and ``obsgeovel``
attributes return ``CartesianRepresentation`` objects, rather than ``Quantity``
objects.  This was judged to be an advanced enough use case that this change
will not include a deprecation period (as this would have added substantial
complexity to `astropy.coordinates`). To make code written for earlier versions
compatible with v1.3 and up, simply change all instances of
``<object>.obsgeoloc`` or ``<object>.obsgeovel`` to
``<object>.obsgeoloc.xyz``/``<object>.obsgeovel.xyz``.

Full change log
---------------

To see a detailed list of all changes in version v1.3, including changes in
API, please see the :ref:`changelog`.


.. _Lupton et al. (2004): http://adsabs.harvard.edu/abs/2004PASP..116..133L