WIP: Single Object Model and Scene Maker Future PSF Photometry API

[Onoddil]

This pull request is set up for the discussion of the forward-looking additions to PSF photometry and should not be merged until after the discussion is finished. In this case the issue is the 'single object model' and 'scene maker' aspects of the block diagram -- although 'scene maker' is not currently implemented within the block diagram it is heavily linked to the 'single object model' and included here for discussion accordingly. This API documentation complements that in #721 where the documentation for those blocks implemented, with solid APIs unlikely to change in future releases. Please see #766 for an overview of the fitting process and a revised block diagram.

The structure of the blocks input and output parameters is described in detail in the documentation, but the main issues are summarised below:

• SingleObjectModel

  • Formatting
  • Wording
  • Internal model parameters
  • star variable renaming
  • Verification of internal consistency between object_type list available to both SingleObjectModel and SceneMaker
  • API workflow: requires psf_model (~astropy.modeling.Fittable2DModel) and object_type (string) and returns convolve_psf_model (~astropy.modeling.Fittable2DModel)

• SceneMaker

  • Appropriate level of description of non-implemented API block
  • Wording
  • Formatting
  • Formalism for keeping track of merged sources

In particular discussion on

• How to determine the 'internal' parameters of an extended source -- galaxy distance, time since supernova maximum, etc. -- within the framework of a Fitter instance. While point sources can be naively fit for flux and position with no knowledge of the underlying physics of the source (age, spectral type, etc.), the creation of an underlying intrinsic "image" of extended sources requires fitting for physical parameters.
• Whether it is necessary to rename the catalogue created during the PSF fitting process, currently called star. Is it better to keep backwards consistency and keep all sources, extended or not, under a variable called 'star', or is it better to have a physically motivated name for the variable?
• What methods would be most effective in ensuring that SingleObjectModel and SceneMaker have the same accepted object_type list (such that SceneMaker cannot assign a source as being, e.g., a Quasar, which is not an accepted object type in SingleObjectModel) -- or whether there is a more effective way to handle such non-point source determination than the list of accepted strings of object_type variables.
• How best to keep track of the merging of point sources into fitting simultaneously as an extended source. For example, "stars" 1, 2, and 5 might be determined by SceneMaker to be "galaxy 1" while stars 3 and 6 are now "galaxy 2" with star 4 a point source still; what framework within the star ~astropy.table.Table structure will most efficiently and obviously indicate such mergings?

is appreciated to finalise the API call.

Please provide any feedback on the API for this PSF photometry fitting routine block you may have, such that the implementation meets all of the requirements of all users and is as clear as possible going forward. A simple example for this block, maintaining "do nothing" backwards-compatibility can be found in IterativelySubtractedPSFPhotometry, with changes to get_grouped_psf_model necessary for creating a composite PSF given here and the example SingleObjectModel class shown here. Note that the example shown is very basic, with no implementation of any convolution with intrinsic sources, and does not attempt to implement SceneMaker at all. Please also provide simpler formatting or grammatical changes to improve the readability and professional look of the document. The function's primary goal is to allow for the extension of PSF fitting to include non-point sources, fitting for more complex extended sources as well as the eventual acceptance the mergers between multiple sources into an extended source in a manner analagous to source grouping.