.. doctest-skip-all

.. _whatsnew-3.2:

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

Overview
========

Astropy 3.2 is a major release that ...  since
the 3.1.x series of releases.

In particular, this release includes:

* :ref:`whatsnew-3.2-timeseries`
* :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:

* xxx issues have been closed since v3.1
* xxx pull requests have been merged since v3.1
* xxx distinct people have contributed code

.. _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-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.

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`.
