.. doctest-skip-all

****************************
What's New in Photutils 1.1?
****************************

Overview
========
Photutils 1.1 is a major release that adds new functionality since the
1.0 release. Here we highlight some of the major changes. Please see the
:ref:`changelog` for the complete list of changes.


New SourceCatalog class
=======================
A new, significantly faster, `~photutils.segmentation.SourceCatalog`
class was implemented. This new class simplifies the API and takes the
place of the ``source_properties`` function and the ``SourceProperties``
``LegacySourceCatalog`` classes. The ``source_properties`` function
and ``SourceProperties`` class are now deprecated and will eventually
be removed. The ``source_properties`` function now returns
``LegacySourceCatalog`` class (deprecated) to distinguish it from the
new `~photutils.segmentation.SourceCatalog`.

Optional keyword arguments in `~photutils.segmentation.SourceCatalog`
can not be input as positional arguments. Please see the
`~photutils.segmentation.SourceCatalog` documentation for the keywords
inputs and their allowed values.

Renamed properties
------------------
Note that many of the source properties have been slightly renamed
in the new `~photutils.segmentation.SourceCatalog` class, e.g.,

    * 'id' -> 'label'
    * 'background_at_centroid' -> 'background_centroid'
    * 'background_cutout' -> 'background'
    * 'background_cutout_ma' -> 'background_ma'
    * 'data_cutout' -> 'data'
    * 'data_cutout_ma' -> 'data_ma'
    * 'error_cutout' -> 'error'
    * 'error_cutout_ma' -> 'error_ma'
    * 'filtered_data_cutout_ma' -> 'convdata_ma'
    * 'minval_pos' -> 'minval_index'
    * 'minval_xpos' -> 'minval_xindex'
    * 'minval_ypos' -> 'minval_yindex'
    * 'maxval_pos' -> 'maxval_index'
    * 'maxval_xpos' -> 'maxval_xindex'
    * 'maxval_ypos' -> 'maxval_yindex'
    * 'semimajor_axis_sigma' -> 'semimajor_sigma'
    * 'semiminor_axis_sigma' -> 'semiminor_sigma'
    * 'source_sum' -> 'segment_flux'
    * 'source_sum_err' -> 'segment_fluxerr'

Also, the 'centroid' and 'cutout_centroid' properties now return
centroids in (x, y) order to be consistent with the tools in
``photutils.centroid``.

New methods and attributes
--------------------------
The new `~photutils.segmentation.SourceCatalog` class has the following
new methods:

    * :meth:`~photutils.segmentation.SourceCatalog.circular_photometry`
    * :meth:`~photutils.segmentation.SourceCatalog.fluxfrac_radius`
    * :meth:`~photutils.segmentation.SourceCatalog.get_label`
    * :meth:`~photutils.segmentation.SourceCatalog.get_labels`

and new attributes:

    * :attr:`~photutils.segmentation.SourceCatalog.fwhm`
    * :attr:`~photutils.segmentation.SourceCatalog.segment`
    * :attr:`~photutils.segmentation.SourceCatalog.segment_ma`
