DOC: Encourage local_bkg in ApertureStats

[pllim]

No reason not to use local_bkg, right? Should put best practice in example? xref:

• #1316

[pllim]

Hmm, local_bkg throws exception when aperture has multiple centers. Is this feature or bug? From the doc example:

>>> aper2
<CircularAperture([[150.,  25.],
                   [ 90.,  60.]], r=10.0)>
>>> median
5.408250014261292
>>> aperstats2 = ApertureStats(data, aper2, local_bkg=median)

.../photutils/aperture/stats.py in __init__(self, data, aperture, error, mask, wcs, sigma_clip, sum_method, subpixels, local_bkg)
    228                 raise ValueError('local_bkg must be a 1D array')
    229             if len(local_bkg) != self.n_apertures:
--> 230                 raise ValueError('local_bkg must have the same length as '
    231                                  'the aperture')
    232             if np.any(~np.isfinite(local_bkg)):

ValueError: local_bkg must have the same length as the aperture

[larrybradley]

Definitely a feature. It's a local background (i.e. around a particular position), not a global background.

[larrybradley]

From the docstring: " The local_bkg values correspond to the input aperture positions. local_bkg must have the same as the length of the input aperture."

[pllim]

Thanks for the hint. I fixed the doctest but I'll leave it up to you if the changes make sense.

[pllim]

@larrybradley , I updated the doc as you requested but not sure if I made it sound too confusing. What do you think?