Separate high-level and low-level API?

[cdeil]

Currently the photutils API contains high-level functions like aperture_photometry as well as low-level functions like centroid_1dg.

I think there is agreement that more low-level functions and classes should be exposed in the photutils API (see #8 and #31) so that it becomes a toolbox (e.g. I'd like to use these low-level functions in gammapy to implement gamma-ray specific detection methods).

The drawback is that it gets harder for end-users to find the main common high-level functions and classes (see current version of the photutils docs on what the status is).

As discussed previously, the solution to this problem is separate namespaces and docs sections for the high-level (end-user) and low-level (toolbox for reuse) functionality.

I see the following two options where to put the high-level API:

1. A namespace photutils.ui ("ui" for user interface) or photutils.api ("api" for application programming interface". E.g. Sherpa uses sherpa.ui, Skyfield uses skyfield.api and Statsmodels uses statsmodels.api
2. Use the top-level photutils namespace (this is what we have now).

@astrofrog @eteq @bsipocz @larrybradley @kbarbary Agreed that having the high-level API in a separate namespace is a good idea? Any preference for using photutils or photutils.api or photutils.ui?

[eteq]

I agree separating these makes a lot of sense.

I think photutils is the best place for the high-level API, because that lowers the bar the most for the novice user who just want to use it to do high-level tasks. Anyone who wants it for "toolbox" purposes isn't going to mind accessing photutils.tools or the like, but the converse may not be true.

[cdeil]

@bsipocz I'm assigning this issue to you ... whatever we decide the majority of the work is re-structuring and extending the docs.

[larrybradley]

I like @eteq's suggestion of photutils and photutils.tools.

[cdeil]

We discussed this in today's photutils hangout and the conclusion was this:

• The high-level API will be imported into the top-level photutils namespace ... any decision what should be included there is irrespective of which folder / file things are located.
• The lower-level functions and classes will be distributed across sub-modules or sub-packages (e.g. photutils.detection or photutils.aperture or photutils.psf ... whatever makes sense)
• Over the coming weeks @bsipocz will explain "photutils has end-user functions to do common things but is also a toolbox you can use to implement your own algorithms in scripts or other package" in the docs and re-structure them.

@eteq, @larrybradley, everyone: Would that be OK with you? I'm not sure if you suggested above to move everything in sub-packages of photutils.tools, i.e. create photutils.tools.utils, photutils.tools.detection, photutils.tools.aperture, photutils.tools.psf or did you mean photutils.tools only as an example?

[bsipocz]

@cdeil - you might have closed by mistake when merged the package-template?

[cdeil]

@bsipocz Yes, I didn't want to close this ... thanks!

[larrybradley]

@cdeil :+1: I was not suggesting subpackages of photutils.tools, e.g. photutils.tools.detection (that's unnecessary IMHO). The submodule structure photutils.detection, etc. looks good to me. Basically anything not in the top level namespace is a "tool".

[eteq]

@cdeil - I indeed meant photutils.tools.detection et al., but I like your suggestion here even better.

The one concern is that in this scheme, photutils might get to be a pretty busy namespace... What I was suggesting before was that e.g. photutils.psf would have the high-level psf stuff, while photuitls.tools.psf would have the lower-level stuff. But I'm fine with the high-level stuff all being in photutils as long as that doesn't end up being a ton of functions or something.

[cdeil]

@eteq @larrybradley Thanks for clarifying what you like best.

I guess the general direction is clear and we can decide on a case-by-case basis what is general enough to go in the top-level namespace in the coming weeks ... let's keep this issue open for now as a reminder.

[cdeil]

I think this is done:

• The photutils namespace contains high-level functionality
• Lower-level and less used functions / classes are in sub-namespaces, e.g. photutils.morphology or photutils.datasets.