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

docs/psf_spec/scene_maker.rst

@@ -1,72 +1,24 @@
 SceneMaker
 ==========
 
-EJT: This object is not currently in the block diagram, as it represents a step
-beyond the "baseline" PSF fitting machinery. It should be developed in parallel
-with the ``SingleObjectModel``, which really doesn't have reason to exist without
-the scene maker.
-
-A single sentence summarizing this block.
-
-A longer descrption.  Can be multiple paragraphs.  You can link to other things
-like `photutils.background`.
-
-Parameters
-----------
-
-first_parameter_name : `~astropy.table.Table`
-    Description of first input
-
-second_parameter_name : SomeOtherType
-    Description of second input (if any)
-
-Returns
--------
-
-first_return : `~astropy.table.Table`
-    Description of the first thing this block outputs.
-
-second_return
-    Many blocks will only return one object, but if more things are returned
-    they can be described here (e.g., in python this is
-    ``first, second = some_function(...)``)
-
-
-Methods
--------
-
-Not all blocks will have these, but if desired some blocks can have methods that
-let you do something other than just running the block.  E.g::
-
-    some_block = BlockClassName()
-    output = some_block(input1, input2, ...)  # this is what is documented above
-    result = some_block.method_name(...)  #this is documented here
-
-method_name
-^^^^^^^^^^^
-
-Description of method
-
-Parameters
-""""""""""
-
-first_parameter : type
-    Description ...
-
-second_parameter : type
-    Description ...
-
-Returns
-"""""""
-
-first_return : type
-    Description ...
-
-
-Example Usage
--------------
-
-An example of *using* the block should be provided.  This needs to be after a
-``::`` in the rst and indented::
-
-    print("This is example code")
+SceneMaker does not yet exist in the framework of PSF Photometry. This API
+is therefore a work in progress and should be considered as such.
+
+However, the block will likely involve an additional column or variable attributed
+to each source in the input `~astropy.table.Table` indicating whether sources are
+stars or more extended objects. This column will be used in conjunction with
+``SingleObjectModel``, which already has the framework to accept ``object_type`` which
+allows for individual extended sources to be handled, depending on the specific
+class used for the specific purpose. The given list of single object models allowed
+by, and available to, ``SingleObjectModel`` must be the same list of physical
+source classes (stars, galaxies, etc.) as ``SceneMaker`` uses to group and merge
+detected sources into point sources or extended objects. The block must also handle
+the possibility of merging several point sources into an extended object and vice
+versa.
+
+SceneMaker should be considered an extension of GroupMaker, and will likely accept
+outputs from that block. Sources grouped together by GroupMaker will subsequently
+be assigned as multiple single sources or one larger, extended source erroneously split
+up by the Finder, or some combination of the two. This information will then be used by
+SingleObjectModel to fit the grouped sources as either individual point sources or
+extended sources, based on ``object_type``.

docs/psf_spec/single_object_model.rst

@@ -1,76 +1,73 @@
 SingleObjectModel
 =================
 
-EJT: This does not exist in the current `photutils.psf` model, because there is not
-an explicit separate single object model.  Instead the psf_model is used
-directly, as the "single object model" is implicitly a delta function.  To
-maintain backwards-compatibility, the new ``SingleObjectModel`` will need to
-default to the "point source" object model, and behave the same as the current
-behavior of a model with shape parameters is provided as the "psf model".  But
-arguable that is *not* the desired behavior in the "new" paradigm that combines
-the ``SceneMaker``and the ``SingleObjectModel``.
-
-A single sentence summarizing this block.
-
-A longer descrption.  Can be multiple paragraphs.  You can link to other things
-like `photutils.background`.
+SingleObjectModel handles the creation of the model image of an
+astrophysical object, combining physical on-sky flux distributions with the
+effects of the PSF, extending the ``psf_model`` block of the PSF
+fitting routine to include non-point sources. This method may be subject
+to API changes in future versions and should not be considered final.
+
+This block is an additional step between the PSF (or PRF)
+`~astropy.modeling.Fittable2DModel` and the
+`~astropy.modeling.fitting.Fitter` instance, to allow for cases
+where the images being fit contain sources other than point sources. In
+these instances a combined PRF, combining the PSF resulting from
+telescope optics, CCD, etc. with that of the intrinsic source as it would
+appear with infinite resolution is required. If the source is a simple
+point source, then the block simply returns the given PSF, avoiding the
+lengthy computational time of image convolution.
+
+The single object model -- the model determining what type of object
+(single star, binary star, galaxy, supernova, etc.) this source is assumed
+to be -- is described by an additional column of the ``star`` source list
+created during the PSF fitting routine. For a given fit the object is
+determined by ``star['object_type']`` which is accepted as the ``string``
+argument ``object_type`` by ``SingleObjectModel``. Additionally,
+``psf_model``, the `~astropy.modeling.Fittable2DModel` describing the PSF,
+accounting for quantized detector pixels, is required. The block then returns
+``convolve_psf_model``, the convolution of ``psf_model`` with the flux
+distribution intrinsic to the source with given internal parameters
+(such as galaxy distance to correct for apparent size, time since
+supernova explosion to produce the correct lightcurve, etc.). The class must
+be a subclass of ``SingleObjectModelBase``, with the individual class provided
+to the PSF fitting routine accepting a specific set of sources to be passed
+in ``object_type``, with each object being handled on a case-by-case basis.
+
+This block is also related to ``SceneMaker``, the future extension to the
+standard "source grouping" aspect of the PSF fitting process, which additionally
+allows for the grouping of several objects, otherwise assumed to be single point
+sources, into a composite extended source, and vice versa. It is
+``SceneMaker`` which therefore dictates the ``object_type`` of a given source
+in the created ``star`` catalogue. ``SceneMaker`` must be set up such that it
+will group and merge ``star`` sources into groups such that all object types
+determined are accepted by ``SingleObjectModel`` -- the two blocks must therefore
+work closely in parallel with one another.
 
 Parameters
 ----------
 
-first_parameter_name : `~astropy.table.Table`
-    Description of first input
-
-second_parameter_name : SomeOtherType
-    Description of second input (if any)
+psf_model : `~astropy.modeling.Fittable2DModel` instance
+    The model describing the PSF/PRF of the image, used to fit individual point
+    source objects.
+object_type : string
+    The extended source type used to determine the innate
+    light distribution of the source.
 
 Returns
 -------
 
-first_return : `~astropy.table.Table`
-    Description of the first thing this block outputs.
-
-second_return
-    Many blocks will only return one object, but if more things are returned
-    they can be described here (e.g., in python this is
-    ``first, second = some_function(...)``)
-
-
-Methods
--------
-
-Not all blocks will have these, but if desired some blocks can have methods that
-let you do something other than just running the block.  E.g::
-
-    some_block = BlockClassName()
-    output = some_block(input1, input2, ...)  # this is what is documented above
-    result = some_block.method_name(...)  #this is documented here
-
-method_name
-^^^^^^^^^^^
-
-Description of method
-
-Parameters
-""""""""""
-
-first_parameter : type
-    Description ...
-
-second_parameter : type
-    Description ...
-
-Returns
-"""""""
-
-first_return : type
-    Description ...
+convolve_psf_model : `~astropy.modeling.Fittable2DModel` instance
+    The new, combined PRF of the extended source, combining the
+    intrinsic light distribution and PSF effects.
 
 
 Example Usage
 -------------
 
-An example of *using* the block should be provided.  This needs to be after a
-``::`` in the rst and indented::
+This class simply takes the `~astropy.modeling.Fittable2DModel` instance and 
+convolves it with the appropriate model describing the, e.g., galaxy light
+distribution::
 
-    print("This is example code")
+    from photutils.psf import SingleObjectModel
+    single_object_model = SingleObjectModel()
+    new_composite_psf = single_object_model(psf_to_add, star['object_type'])