.. doctest-skip-all

.. _whatsnew-3.2:

**************************
What's New in Astropy 3.2?
**************************

Overview
========

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

In particular, this release includes:

* :ref:`whatsnew-3.2-timeseries`
* :ref:`whatsnew-3.2-codata`
* :ref:`whatsnew-3.2-ecliptic`
* :ref:`whatsnew-3.2-table-performance`
* :ref:`whatsnew-3.2-table-pandas`
* :ref:`whatsnew-3.2-table-help`

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

* 551 issues have been closed since v3.1
* 256 pull requests have been merged since v3.1
* 67 distinct people have contributed to this release, 24 of which are first
  time contributors to Astropy


.. _whatsnew-3.2-timeseries:

New Sub-package for Time Series
===============================

Astropy 3.2 includes a new experimental sub-package: :ref:`astropy-timeseries`.
Currently this sub-package provides classes to represent sampled and binned
time series as well as some basic analysis tasks.

The following example shows a simple example of reading in a Kepler light curve,
finding the period of the transits, and folding the light curve.

.. plot::
   :include-source:
   :context: reset

   import numpy as np
   import matplotlib.pyplot as plt
   from astropy.timeseries import TimeSeries
   from astropy.utils.data import get_pkg_data_filename
   from astropy import units as u

   filename = get_pkg_data_filename('timeseries/kplr010666592-2009131110544_slc.fits')
   ts = TimeSeries.read(filename, format='kepler.fits')

   plt.figure(figsize=(10,5))

   # Show the original light curve
   plt.subplot(1, 2, 1)
   plt.plot(ts.time.mjd, ts['sap_flux'], 'k.', markersize=1)
   plt.xlabel('Barycentric Modified Julian Date')
   plt.ylabel('SAP Flux (e-/s)')

   # Find the transit period and fold the light curve
   from astropy.timeseries import BoxLeastSquares
   periodogram = BoxLeastSquares.from_timeseries(ts, 'sap_flux')
   results = periodogram.autopower(0.2 * u.day)
   best = np.argmax(results.power)
   ts_folded = ts.fold(period=results.period[best],
                       midpoint_epoch=results.transit_time[best])

   # Show the folded light curve
   plt.subplot(1, 2, 2)
   plt.plot(ts_folded.time.jd, ts_folded['sap_flux'], 'k.', markersize=1)
   plt.xlabel('Time relative to epoch (days)')
   plt.gca().get_yaxis().set_visible(False)

This sub-package should be considered experimental and subject to API changes in
the future if user feedback calls for it.

Note that the :class:`~astropy.timeseries.LombScargle` and
:class:`~astropy.timeseries.BoxLeastSquares` periodogram classes have now moved
from the :mod:`astropy.stats` to the :mod:`astropy.timeseries` module. These
classes have been improved and can now take absolute times as an alternative
to relative times.

Finally, the :class:`~astropy.timeseries.LombScargle` class now includes a
:func:`~astropy.timeseries.LombScargle.model_parameters` method  to make it easier to
compute the best-fit parameters for a given frequency, as well as
:func:`~astropy.timeseries.LombScargle.design_matrix` and
:func:`~astropy.timeseries.LombScargle.offset` to inspect the model further.


.. _whatsnew-3.2-codata:

New SI/CODATA 2018 Constants
============================

The new redefinition of the SI system and its base units came into force on
2019-05-20.  Accompanying that redefinition was a new set of physical constants
(CODATA2018).  Astropy v3.2 contains these new CODATA2018 phsical constants,
which contain in particular quite different uncertainties due to the
redefinition. E.g.,::

    >>> from astropy import constants
    >>> from astropy.constants import codata2018
    >>> constants.m_e
    <<class 'astropy.constants.codata2014.CODATA2014'> name='Electron mass' value=9.10938356e-31 uncertainty=1.1e-38 unit='kg' reference='CODATA 2014'>
    >>> constants.m_e.uncertainty, codata2018.m_e.uncertainty
    (1.1e-38, 2.8e-40)
    >>> constants.mu0.uncertainty, codata2018.mu0.uncertainty
    (0.0, 1.9e-16)

While CODATA2018 will not be the default in astropy v3.2, a future version will
transition to the new values (with units similarly matched where relevant).

For more background on the values and measurements of these constants see `the CODATA web site <http://www.codata.org/committees-and-groups/fundamental-physical-constants>`_,
or see
`the wikipedia article on the new SI system <https://en.wikipedia.org/wiki/2019_redefinition_of_the_SI_base_units>`_ for a
more accessible description of the revised system.

.. _whatsnew-3.2-ecliptic:

Additions and changes to Ecliptic Transformations
=================================================

The Ecliptic frames and associated transformations in
:ref:`astropy.coordinates <astropy-coordinates>`
have been updated to correctly reflect the "True" and "Mean" terminology. In
this release there are now ``*MeanEcliptic`` frames now which include precession but
not nutation, and ``*TrueEcliptic`` frames which also include nutation.
Additionally, new frames (`~astropy.coordinates.HeliocentricEclipticIAU76` and
`~astropy.coordinates.CustomBarycentricEcliptic`) have been added with specific
conventions used in particular fields. For more details on the motivation behind
these changes, see `PR #8394 <https://github.com/astropy/astropy/pull/8394>`_
and the associated discussion.

As an example, this shows the evolution of the ecliptic origin for the true and
mean barycentric ecliptic frames over the course of a year:


.. plot::
    :include-source:
    :context: reset

    import numpy as np
    import matplotlib.pyplot as plt
    from astropy.visualization import quantity_support
    quantity_support()

    from astropy import units as u
    from astropy.time import Time
    from astropy.coordinates import BarycentricMeanEcliptic, BarycentricTrueEcliptic, ICRS

    t = Time('J2018') + np.linspace(-1, 0, 1000)*u.year

    bme_origin = BarycentricMeanEcliptic([0]*len(t)*u.deg, [0]*len(t)*u.deg, equinox=t)
    bte_origin = BarycentricTrueEcliptic([0]*len(t)*u.deg, [0]*len(t)*u.deg, equinox=t)

    im = bme_origin.transform_to(ICRS())
    it = bte_origin.transform_to(ICRS())

    plt.plot(t.jyear, im.ra.wrap_at(180*u.deg), label='BarycentricMeanEcliptic')
    plt.plot(t.jyear, it.ra.wrap_at(180*u.deg), label='BarycentricTrueEcliptic')

    plt.xlabel('Julian year')
    plt.ylabel('ICRS R.A. of ecliptic origin [{}]'.format(im.ra.unit))
    plt.legend(loc=0)


Note that this change may break some usage of the previous ``*TrueEcliptic``
frames, as in the last few versions these had a behavior more akin to "mean"
ecliptic frames.  In many cases it will be sufficient to simply replace this
usage with the appropriate ``*MeanEcliptic`` frames.

.. _whatsnew-3.2-tt:

Default time scale for "J2000"-style strings changed to TT
==========================================================

In past versions of astropy, times specified as "equinox-style strings" - e.g.,
``Time('J2000')`` - defaulted to the UTC scale.  This includes default equinoxes
for FK4/FK5 coordinates. To be more consistent with commonly-accepted usage of
terms like "J2000", this strings now default to the TT time scale. This
difference is on the order of 60 seconds, which for e.g. equinox precession is
typically an extremely small differences (picoarcseconds).  However, if the
previous behavior is needed, the easiest work-around is to change any use of
e.g., ``'J2000'`` to ``Time('J2000', scale='utc')``.

.. _whatsnew-3.2-table-performance:

Table performance improvements and change in meta handling
==========================================================

A number of changes were made to the `~astropy.table.Table` implementation to
improve performance:

- Table row access speed is improved by a factor of 2 to 3.
- Table slicing speed is improved by a factor of 2.
- Getting the table length is now faster by a factor of 3 to 10.
- Writing a table with masked columns to ECSV is now faster (depending
  on how many masked columns there are).
- Manipulating tables and columns that have substantial meta-data stored in
  the ``meta`` attributes (e.g. some FITS tables) is now faster.  This was
  done by removing unnecessary deep copies of the meta-data and in some
  cases converting to a shallow copy.  See the change log for #8404 for details
  about the related API changes in table initialization and slicing.

.. _whatsnew-3.2-table-pandas:

Table I/O integration of pandas I/O functions for ASCII tables
==============================================================

Astropy `~astropy.table.Table` now supports the ability to read or write tables
using some of the
`I/O methods <https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html>`_
available within `pandas <http://pandas.pydata.org/>`_.  This interface provides
convenient wrappers for the `pandas <http://pandas.pydata.org/>`_ read/write
functions for the following formats: CSV, JSON, HTML, and fixed width.
For very large tables these may provide better performance than the built-in
astropy table ASCII read and write functions.  For details see :ref:`table_io_pandas`.

.. _whatsnew-3.2-asdf:

Support for ASDF readers/writers for Table class
================================================

If the `asdf <https://pypi.org/project/asdf/>`__ package is installed,
`~astropy.table.Table` can be read from and written to
`ASDF <https://asdf-standard.readthedocs.io/en/latest/>`__ files, using e.g.::

    from astropy.table import Table
    tab = Table.read('data.asdf')

and::

    tab.write('table.asdf')

.. _whatsnew-3.2-table-help:

Improved help on Table read() and write() methods
=================================================

Starting from astropy version 3.2 is now possible to get detailed help for
`~astropy.table.Table.read` and `~astropy.table.Table.write` which is
specific to a particular data format.  This includes information about
the format and method keywords that apply only for that format.  The
following examples illustrate the new syntax for getting help::

  >>> Table.read.help('ascii.latex')
  >>> Table.read.help('ascii')
  >>> Table.read.help('fits')
  >>> Table.write.help('hdf5')
  >>> Table.write.help('csv')
  >>> Table.read.help()  # Generic read help

Deprecated/Renamed/Removed functionality
========================================

The bundled version of the `six <https://pypi.org/project/six/>`_ package in
the ``astropy.extern.six`` sub-package is now deprecated. You should instead
make use of the `six`_ package directly.

Composition of model *classes* (as opposed to instances) is now deprecated
and will be removed in the v4.0 release.

The :class:`~astropy.timeseries.LombScargle` and
:class:`~astropy.timeseries.BoxLeastSquares` periodogram classes have now moved
from the :mod:`astropy.stats` to the :mod:`astropy.timeseries` module.

The previously deprecated ``astropy.tests.pytest_plugins`` module has been
removed. The variables ``PYTEST_HEADER_MODULES`` and ``TESTED_VERSIONS`` should
instead be imported from ``astropy.tests.plugins.display``, and the function
``enable_deprecations_as_exceptions`` should be imported from
``astropy.tests.helper``.

Full change log
===============

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

Contributors to the v3.2 release
================================

.. hlist::
  :columns: 4

  *    Adam Ginsburg
  *    Adrian Price-Whelan
  *    Alex Conley
  *    Alex Drlica-Wagner  *
  *    Antony Lee
  *    Benjamin Alan Weaver
  *    Benjamin Roulston  *
  *    Benjamin Winkel  *
  *    Brigitta Sipocz
  *    Bruno Oliveira
  *    Christoph Deil
  *    Clément Robert  *
  *    Dan Foreman-Mackey
  *    Dan Taranu  *
  *    Daniel D'Avella
  *    David Shupe
  *    David Stansby
  *    Devin Crichton
  *    Erik M. Bray
  *    Erik Tollerud
  *    Francesco Montanari  *
  *    Frédéric Chapoton  *
  *    Hans Moritz Günther
  *    Himanshu Pathak  *
  *    Jake VanderPlas
  *    James Davies
  *    James Noss
  *    Jane Rigby  *
  *    Jani Šumak
  *    Javier Pascual Granado  *
  *    John Parejko
  *    Johnny Greco
  *    Joseph Schlitz
  *    Juan Luis Cano Rodríguez
  *    Kris Stern  *
  *    Larry Bradley
  *    Lauren Glattly  *
  *    Leo Singer
  *    Lisa Martin  *
  *    Marten van Kerkwijk
  *    Matteo Bachetti
  *    Matthew Craig
  *    Michael Seifert
  *    Nabil Freij  *
  *    Nadia Dencheva
  *    Nicholas Saunders  *
  *    Noah Zuckman  *
  *    Ole Streicher
  *    Perry Greenfield
  *    Pey Lian Lim
  *    Rohit Kapoor  *
  *    Samuel Brice  *
  *    Simon Conseil
  *    Steve Crawford
  *    Stuart Mumford
  *    Sudheesh Singanamalla
  *    T. Carl Beery  *
  *    Thomas Robitaille
  *    Tim Jenness
  *    Tim Plummer  *
  *    Tito Dal Canton  *
  *    Tom Aldcroft
  *    Vishnunarayan K I
  *    Yannick Copin
  *    Yash Kumar  *
  *    disha  *
  *    shilpi_jc  *


Where a * indicates their first contribution to Astropy.
