astrofrog/astropy-api — pull request #2 by astrofrog (2012-11-05 17:37:34+00:00)
Title: Photometry API proposal

This is an initial version of the Photometry API document, based on the discussion in

https://github.com/astropy/photutils/wiki/Proposed-photutils-API

Note that for now, I have left out object detection and regions. I believe that for now we should go ahead with the idea of having aperture objects that have no specific center, because we want to be able to efficiently do photometry on tens of thousands of sources or more, and tens of thousands of instances of aperture objects is not efficient. The ``Region`` stuff could be developed separately, and just rely on the same cython routines under the hood. But I think for now we should focus on the photometry API without worrying about the regions (sorry for bringing it up in the first place!).

Note also that the standalone photometry routines can work directly with Numpy arrays as @kylebarbary was asking. They also work with NDData objects, but that doesn't prevent using simply Numpy arrays. The only place where I think we should stick with an astropy object is the Table object for the output. It really is just a structured array, so should be familiar to users, but just has a lot of nice extras.

I also tried to re-think how we deal with multiple apertures per source and different apertures for each sources, trying to make it as intuitive as possible - I'd be interested to hear what you think.

I tried to re-think the API to ensure consistency between the aperture and PSF photometry. Note that in fact, we could even consider having a high-level ``photometry`` function that could do:

```
results = photometry(image, (x, y), [ap1, ap2, psf1, psf2])
```

This would be awesome, because it would provide a way to do simultaneous aperture and PSF photometry. But that's not in the API document yet.

Things that still need to be added to this API document:

* How to pass uncertainties when the data is passed just as a Numpy array

* Source detection

I will work on these, but let's first see if there is agreement about what's already there.

I will not add anything about the *internal* API, as that is a separate matter.

Once you agree with this document, I will add you as an author, and once we've converged, I'll open a PR on the main astropy-api repository!

cc @bretonr @kbarbary @stargaser