Add aperture masks

[larrybradley]

This PR is a significant refactoring of the aperture subpackage to add the ability to get aperture masks. It a continuation of the initial work in #446.

While there are many new features, there are only a few user-facing API changes:

• the source_id keyword was renamed to indices in the aperture plot() method (because apertures are independent of sources or data).
• the old aperture masking methods (e.g. get_fractions()) were removed.

Here are the highlights of the other changes:

• Apertures no longer require a do_photometry() method. do_photometry() is now defined only once, in the PixelAperture class.
• Apertures now require a to_mask() method. This method is provided by new Mixin classes for each of the PixelAperture shapes.
• The to_mask() method returns a new ApertureMask object.
• Added new `mask_area()`` method.
• The do_photometry() method now has mask and unit keywords.
• The aperture extents (bounding boxes) are now defined in _slices and _geom_slices properties.

Example usage:

from photutils import CircularAperture
aper = CircularAperture([(40, 40), (50, 50)], r=3)

masks = aper.to_mask(method='exact')    # list of ApertureMask objects (one for each position)
m0 = masks[0]    # an ApertureMask object
m0.data    # ndarray

# mask in an image of given shape
m0.to_image((300, 300))    # ndarray

# apply mask to data
data = np.ones((100, 100)
cutout_data = m0.apply(data)   # ndarray

[tnorth2]

@larrybradley hi, how exactly can I now use this method to perform the procedure described in #8 ? Despite many functions documented here, and an attempted implementation of the method described above I am unable to perform (what should be straightforward) Median background subtraction through an annulus.

It may be a lack of understanding of what exactly the ApertureMask object is returning on my half, as 'm0.shape' is returning a 2d array of mostly zeros (despite the fact the pixels inside the annulus certainly are not zero). Any direct answers to #8 ? Cheers

[larrybradley]

@tnorth2 Thanks for your question and reminding me that I need to expand the aperture mask documentation.

ApertureMask is an object that contains a 2D numpy array of the aperture mask pixel weights (stored in .data) and a bounding box object that defines the bounding box of the mask.

Here's a quick example:

from photutils.datasets import make_100gaussians_image
from photutils import CircularAnnulus

data = make_100gaussians_image()
xypos = (291, 113.5)
ann = CircularAnnulus(xypos, r_in=10, r_out=15)
method = 'exact'
ann_mask = ann.to_mask(method=method)[0]    # only one xypos
plt.imshow(ann_mask.data)

Here's what the annulus mask looks like:

Note that with method='exact' (the default), the aperture mask contains partial-pixel weights, thus we need to compute weighted statistics. numpy.average can do this for mean, but unfortunately there is not an analogous weighted-median function. It's on my to-do list to add a weighted median to astropy.stats, but in the meantime there are python packages that provide such functionality.

Weighted mean:

weighted_data = ann_mask.apply(data)
np.average(weighted_data, weights=ann_mask)
4.6969601309256248

If you want to simply use numpy.median, you can set the method='center' to turn-off partial-pixel weighting and then take the median of the non-zero pixels in the weighted data. Full example:

from photutils.datasets import make_100gaussians_image
from photutils import CircularAnnulus

data = make_100gaussians_image()
xypos = (291, 113.5)
ann = CircularAnnulus(xypos, r_in=10, r_out=15)
method = 'center'
ann_mask = ann.to_mask(method=method)[0]    # only one xypos
weighted_data = ann_mask.apply(data)
np.median(weighted_data[weighted_data != 0])
5.0622323212147089

EDIT: I should also note that the .apply() method has been renamed to .multiply() in the development version.