.. _whatsnew-0.2:

=========================
What's New in Astropy 0.2
=========================

ASCII table I/O
---------------

The :ref:`astropy.io.ascii <io-ascii>` subpackage allows reading and writing of
table data in ASCII format.  A number of improvements have been made to this
package, some of which break compatibility with the original `asciitable
<https://asciitable.readthedocs.org/>`_ package.

The biggest change is full integration with the :ref:`Table <astropy-table>` class
so that table and column metadata (e.g. keywords, units, description,
formatting) are directly available in the output table object.  The CDS,
DAOphot, and IPAC format readers now provide this type of integrated metadata.
Missing value support is now provided using :ref:`masked tables <astropy-table>`
instead of NumPy masked arrays.

There is an important change in way that input data are parsed in the
:func:`~astropy.io.ascii.ui.write` function.  In version 0.1 of `astropy`, a
list of lists was interpreted to be a *list of data rows*, corresponding to the
behavior in `asciitable <https://asciitable.readthedocs.org/>`_.  Starting from
version 0.2, a list of lists is interpreted as a *list of data columns*.  This corresponds
to the behavior of the :class:`~astropy.table.table.Table` class.

Finally, a reader class to read SExtractor table outputs is now available.


Coordinates
-----------

The :ref:`astropy.coordinates <astropy-coordinates>` subpackage was added in Astropy 0.2, and
adds a framework for defining celestial and other astronomical coordinate
systems, as well as transformations between them. A few simple usage examples
include::

  >>> import astropy.coordinates as coord
  >>> c = coord.ICRSCoordinates(ra=10.68458, dec=41.26917, unit=(u.degree, u.degree))
  >>> c.ra
  <RA 10.68458 deg>
  >>> c.galactic
  <GalacticCoordinates l=121.17430 deg, b=-21.57280 deg>

Currently a limited set of standard coordinate systems are included, but more will be
added in the next release.  There is also an
:ref:`example of creating a custom coordinate system <sgr-example>`  in the documentation.

The package also includes a representation of angles (:class:`~astropy.coordinates.angles.Angle`)
that may be useful in other contexts. It also supports distances in
celestial coordinates, which allows a complete mapping to 3D coordinates::

  >>> c = coord.ICRSCoordinates('00h42m44.3s +41d16m9s', distance=Distance(770, u.kpc))
  >>> c.cartesian
  <CartesianPoints (568.712888217, 107.300935969, 507.889909249) kpc>

The package also supports a simple interface for retrieving coordinates for an object by
name using the `Sesame Name Resolver <http://cds.u-strasbg.fr/cgi-bin/Sesame>`_ . This works
on all subclasses of :class:`~astropy.coordinates.coordsystems.SphericalCoordinatesBase`::

  >>> c = coord.ICRSCoordinates.from_name("M42")
  >>> c.ra, c.dec
  (<RA 83.82208 deg>, <Dec -5.39111 deg>)
  >>> c = coord.GalacticCoordinates.from_name("M42")
  >>> c.l, c.b
  (<Angle -150.98622 deg>, <Angle -19.38162 deg>)

For more details about this feature, see
:func:`~astropy.coordinates.name_resolve.get_icrs_coordinates` and
:meth:`~astropy.coordinates.coordsystems.SphericalCoordinatesBase.from_name`.

Note that this subpackage is still under heavy development, and likely will
undergo significant changes in the next few versions.


Cosmology
---------

There have been several improvements to :ref:`astropy.cosmology
<astropy-cosmology>` subpackage, some of which required minor API
changes. Contributions to the energy density from photons and
neutrinos are now taken into account, and so cosmological quantities
should be accurate all the way up to z ~ 1100, corresponding to the
CMB surface of last scattering. There are also new classes to
represent flat cosmologies, optionally with a time-varying dark energy
parameter ``w`` using the popular parameterisations by `Linder 2003
<http://adsabs.harvard.edu/abs/2003PhRvL..90i1301L>`_.

There are two API changes:

  * Previously the ``Om``, ``Ol`` and ``Ok`` attributes of a
    `Cosmology` class referred to densities at z = 0. These have been
    renamed to ``Om0``, ``Ol0``, and ``Ok0``. ``Om``, ``Ol`` and
    ``Ok`` are now methods that give the relevant density as a
    function of redshift. This change makes their behaviour consistent
    with that of the Hubble parameter attribute and method (``H0`` and
    ``H``).

  * The `FLRWCosmology` class has been renamed to
    :class:`~astropy.cosmology.core.FLRW`.

So while in version 0.1 you could define a flat cosmology in following way::

  >>> from astropy.cosmology import FLRWCosmology
  >>> cosmo = FLRWCosmology(H0=70, Om=0.3, Ol=0.7)

Now you would do the same thing using::

  >>> from astropy.cosmology import FlatLambdaCDM
  >>> cosmo = FlatLambdaCDM(H0=70, Om0=0.3)

The convenience functions
:func:`~astropy.cosmology.funcs.kpc_proper_per_arcmin`,
:func:`~astropy.cosmology.funcs.kpc_comoving_per_arcmin`,
:func:`~astropy.cosmology.funcs.arcsec_per_kpc_proper` and
:func:`~astropy.cosmology.funcs.arcsec_per_kpc_comoving` are now all
available as methods of the :class:`~astropy.cosmology.Cosmology`
object.

Finally, a new set of cosmological parameters from the 9 year WMAP
results (`astropy.cosmology.WMAP9`) has been added from the recently
submitted paper by `Hinshaw et
al. <http://arxiv.org/abs/1212.5226>`_. Since this paper has not yet
been refereed, convenience functions still use the 7 year WMAP results
if you don't explicitly specify a cosmology.


Data Tables
-----------

The :ref:`astropy.table <astropy-table>` subpackage was first introduced for
preview in Astropy 0.1 and provides functionality for storing and manipulating
heterogeneous tables of data in a way that is familiar to numpy users.  Some key
features include:

* Modify a table by adding or removing columns, changing column names,
  or adding new rows of data.
* Include table and column metadata as flexible data structures.
* Specify a description, units and output formatting for columns.
* Interactively scroll through long tables similar to using ``more``.

Astropy 0.2 brings the addition of integrated support for missing values via
the Numpy `masked array
<http://docs.scipy.org/doc/numpy/reference/maskedarray.html>`_ class.  This
feature requires Numpy version 1.5 or greater because of issues
with masked arrays in previous versions.

The :class:`~astropy.table.table.Table` class now connects to the new `I/O
framework`_ read and write methods.  For example, assume you have a table
of magnitudes called ``mags`` with columns ``B`` and ``V``.  You can add a new
column ``B-V`` and write out to an ASCII table with::

  >>> BV = Column(data=mags['B'] - mags['V'], name='B-V')
  >>> mags.add_column(BV)
  >>> mags.write('mags_BV.dat', format='ascii')



I/O framework
-------------

This version sees the introduction of a framework that makes it easy to read
in or write out data objects. This can be used for
:class:`~astropy.table.table.Table` and :class:`~astropy.nddata.nddata.NDData`
objects, by doing e.g.::

    >>> from astropy.table import Table
    >>> t = Table.read('my_table.xml', format='vo')
    >>> t.write('my_table.hdf5')

At this time, this framework supports ASCII tables, HDF5 tables, and VO
tables, and will be extended to support FITS tables and datasets in the next
version. Users can also register their own file formats directly, in case
these are not present in Astropy. More information about how to read/write
:class:`~astropy.table.table.Table` objects using the built-in formats is
available in :ref:`table_io`, and more information about the I/O framework and
how to register new file formats can be found in :ref:`io_registry`.



Time
-----

The :ref:`astropy.time <astropy-time>` package is new in Astropy 0.2 and
provides functionality for manipulating times and dates.  Specific emphasis is
placed on supporting time scales (e.g. UTC, TAI, UT1) and time representations
(e.g. JD, MJD, ISO 8601) that are used in astronomy.  The underlying
computations are mostly done with the C language `SOFA`_ time and calendar
routines.  A simple example follows::

  >>> from astropy.time import Time
  >>> times = ['1999-01-01 00:00:00.123456789', '2010-01-01 00:00:00']
  >>> t = Time(times, format='iso', scale='utc')

The ``format`` argument specifies how to interpret :ref:`time-format` of the
input values, e.g. ISO or JD or Unix time.  The ``scale`` argument specifies
the :ref:`time-scale` for the values, e.g. UTC or TT or UT1.  Converting to
another time ``format`` or time ``scale`` is a snap::

  >>> t.jd  # Get an array of JD times
  array([ 2451179.50000143,  2455197.5       ])
  >>> t.tt  # Get a new Time object with values in the TT time scale
  <Time object: scale='tt' format='iso' vals=['1999-01-01 00:01:04.307' '2010-01-01 00:01:06.184']>

.. _SOFA: http://www.iausofa.org/index.html


Units and quantities
--------------------

:ref:`astropy-units` handles defining and converting between physical
units, and performing arithmetic with physical quantities (numbers
with associated units).

Units can be converted to one another:

  >>> from astropy import units as u
  >>> # Convert from parsec to meter
  >>> u.pc.to(u.m)
  3.0856776e+16

It also handles equivalencies that hold true in certain contexts, such
as that between wavelength and frequency::

  # Wavelength to frequency doesn't normally work
  >>> u.nm.to(u.Hz, [1000, 2000])
  UnitError: 'nm' (length) and 'Hz' (frequency) are not convertible
  # ...but by passing an equivalency unit (spectral()), it does...
  >>> u.nm.to(u.Hz, [1000, 2000], equivalencies=u.spectral())
  array([  2.99792458e+14,   1.49896229e+14])

Also included in the `astropy.units` package is the
`~astropy.units.quantity.Quantity` object, which represents a
numerical value with an associated unit. These objects support
arithmetic with other numbers and `~astropy.units.quantity.Quantity`
objects and preserve units::

  >>> from astropy import units as u
  >>> 15.1*u.meter / (32.0*u.second)
  <Quantity 0.471875 m / (s)>
  >>> 3.0*u.kilometer / (130.51*u.meter/u.second)
  <Quantity 0.0229867443108 km s / (m)>
  >>> (3.0*u.kilometer / (130.51*u.meter/u.second)).simplify_units()
  <Quantity 22.9867443108 s>


VOTable XML support
-------------------

The name of the VOTable XML handling package has changed from
`astropy.io.vo` to `astropy.io.votable`.

The `unit` attribute is now an `astropy.units.Unit` object, so unit
conversions can easily be supported.  The CDS unit format used by
VOTable XML is now fully supported as a result.

Masked values are now handled by a single array, rather than a pair of
arrays.

The `precision` and `width` attributes of each field are now handled
correctly as per the VOTable XML specification.  This may result in
the output changing.

Each `TABLE` section of a `VOTable` XML file can be converted to/from
an `astropy.table.Table` object, which allows much easier editing of
the columns than a regular Numpy structured array.

A standalone `volint` script is available to validate the contents of
VOTable XML files.

The default setting for `pedantic` mode can be set using a
configuration parameter (`astropy.io.vo.PEDANTIC`).


WCS
---

When reading FITS headers, the default value of `relax` is `True`, in
order to accept all non-standard keywords that `wcslib` understands.
This should make `astropy.wcs` handle more FITS files by default, but
may introduce a change in behavior in some edge cases.  Likewise for
writing FITS headers, the default value of `relax` is `WCSHDO_safe`,
meaning it will write all non-standard exceptions that are considered
safe and unambiguous.  This should make the FITS files produced by
`astropy.wcs` supported by a larger range of third-party tools, but
may introduce changes in behavior in some edge cases.

The WCS transformation functions, when provided for a separate array
for each input axis, will now broadcast the arrays correctly and
return the output in the broadcasted shape.  This makes using a
constant for one of the axes possible.

The units in a WCS object (`CUNITij`) are now `astropy.units.Unit`
objects, so operations on those units may be performed.

The included version of `wcslib` has been upgraded to version 4.16.
