Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WIP: PSF Photometry API documentation for established functionality #721

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

WIP: PSF Photometry API documentation for established functionality #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
31d67b5
Minor typo fixes. Added specification description for pre-existing PS…
Onoddil Sep 21, 2018
b57cacb
Minor changes to the wording of the description of some PSF specifica…
Onoddil Sep 24, 2018
0c8ecdb
Expanded discussion of block APIs
Onoddil Oct 22, 2018
8a80201
Minor revisions to wording and formatting for API block documentation
Onoddil Oct 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
35 changes: 21 additions & 14 deletions docs/psf_spec/background_estimator.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,35 @@
BackgroundEstimator
===================

EJT: Existing code documented at
https://photutils.readthedocs.io/en/stable/api/photutils.background.BackgroundBase.html
- while the ``__call__`` function has no docstring, the ``calc_background``
function is the actual block API. I'm providing this as an *example* block
because it is heavily used in other parts of `photutils` and therefore probably
should not be changed much unless absolutely necessary.
Existing code documented `here
<https://photutils.readthedocs.io/en/stable/api/photutils.background.BackgroundBase.html>`_
-- while the ``__call__`` function has no docstring, the ``calc_background``
function is the actual block API. This function is used significantly through `photutils`
and is heavily used within the PSF fitting process, so the documentation is summarized
again here.

A single sentence summarizing this block.

A longer descrption. Can be multiple paragraphs. You can link to other things
like `photutils.background`.
Routine to estimate the background level of images and provide background subtraction.
Can either be applied across an entire image or applied in a two-dimensional grid, at
which point background estimation is applied at each grid location locally.

Base class from which all background estimators are defined. Further parameters may be
specified by subclass estimators, such as the ``ModeEstimatorBackground`` in ``photutils``
which takes ``median_factor`` and ``mean_factor`` as additional variables.

Parameters
----------

sigma_clip : `~astropy.stats.SigmaClip` object or None
The object which defines the level of sigma clipping applied to the data. If `None`
then no clipping is performed. Passed when creating the class in ``__init__``.

data : array_like or `~numpy.ma.MaskedArray`
The array for which to calculate the background value.
The array for which to calculate the background value. Passed to the ``__call__``
function.

axis : int or `None`, optional
The array axis along which the background is calculated. If
`None`, then the entire array is used.
`None`, then the entire array is used. Passed to the ``__call__`` function.

Returns
-------
Expand All @@ -36,14 +43,14 @@ result : float or `~numpy.ma.MaskedArray`
Methods
-------

This block requires no methods beyond ``__call__()``.
This block requires no methods beyond first initialisation, and ``__call__()``.


Example Usage
-------------

A variety of implementations of this block already exist in ``photutils``. A
canononical example is the mode estimation algorithm ``3 * median - 2 * mean``.
canonical example is the mode estimation algorithm ``3 * median - 2 * mean``.
This can be done on an array called ``image_data`` by using the block like so::

from photutils.background import ModeEstimatorBackground
Expand Down
81 changes: 28 additions & 53 deletions docs/psf_spec/finder.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,46 @@
ObjectFinder
============

EJT: Existing code documented at
https://photutils.readthedocs.io/en/stable/api/photutils.detection.StarFinderBase.html
- see the ``find_stars`` function for the basic API.

A single sentence summarizing this block.

A longer descrption. Can be multiple paragraphs. You can link to other things
like `photutils.background`.
Existing code documented `here
<https://photutils.readthedocs.io/en/stable/api/photutils.detection.StarFinderBase.html>`_
-- see the ``find_stars`` function for the basic API. ``Finder`` is a relatively
independent routine in the PSF fitting process, and as such it is documented within its
own documentation blocks, based on ``StarFinderBase``; it is documented here for
completeness.

The object which defines the detection of objects in an image. Subclass finders
may require additional parameters -- see below for the example of ``DAOStarFinder``. The
class is defined entirely by its ``find_stars`` function, with some initialization,
depending on the individual subclass.

``find_stars`` accepts ``data``, the two-dimensional image in which sources should be
found, and returns ``table``, an `~astropy.table.Table` list of sources which passed
the given detection criteria. For example, in `~photutils.detection.DAOStarFinder`
a source must have given ``sharpness`` and ``roundness`` within specified ranges for
acceptance as a detected source.

Parameters
----------

first_parameter_name : `~astropy.table.Table`
Description of first input
data : array_like
The 2D image array in which the finder should detection sources.

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 ...
table : `~astropy.table.Table`
The table of detected sources.


Example Usage
-------------

An example of *using* the block should be provided. This needs to be after a
``::`` in the rst and indented::
StarFinder currently implements two methods: DAOFind and IRAFFind. For example, daofind
can be run to find objects with FWHM of approximately 3 pixels with a peak 5-sigma above
the background::

print("This is example code")
from photutils import DAOStarFinder
daofind = DAOStarFinder(fwhm=3.0, threshold=5.*std)
sources = daofind(data)

82 changes: 41 additions & 41 deletions docs/psf_spec/group_maker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,73 @@
GroupMaker
==========

EJT: Documented as the ``__call__`` method of ``GroupStarsBase`` - see
https://photutils.readthedocs.io/en/stable/api/photutils.psf.groupstars.GroupStarsBase.html
It'll be substantial work to re-design the photometry loops if this is changed
in a backwards-incompatible manner, but of course that's possible if there's a
good reason for it.

A single sentence summarizing this block.

A longer descrption. Can be multiple paragraphs. You can link to other things
like `photutils.background`.
Documented as the ``__call__`` method of ``GroupStarsBase`` -- see `here
<https://photutils.readthedocs.io/en/stable/api/photutils.psf.groupstars.GroupStarsBase.html>`_
for more information. The API for the group maker may be subject to change if ``group_stars``
requires changes to accommodate future revisions to the PSF fitting process -- primarily it
would require updates if the PSF fitting is extended to include non-point sources and
"scene maker" functionality. These large changes would subsequently require significant
changes to the PSF fitting routines (e.g., `~photutils.psf.IterativelySubtractedPSFPhotometry`)
as a whole.

A function which groups stars within some critical separation, returning potentially
overlapping sources with an additonal column indicating their common group members.
Subclasses of ``GroupStarsBase`` may require further input parameters, such as
``crit_separation`` required for ``DAOGroup``.

The main functionality of this routine is within ``group_stars``, which accepts
``starlist``, a `~astropy.table.Table` of sources with centroid positions, and returns
``group_starlist``, the same `~astropy.table.Table` passed to the routine but with an
additional column indicating the group number of the sources. These sources are grouped
by the individual criteria specified within the ``group_stars`` function defined by the
``GroupStarsBase`` subclass in question.

Parameters
----------

first_parameter_name : `~astropy.table.Table`
Description of first input

second_parameter_name : SomeOtherType
Description of second input (if any)
starlist : `~astropy.table.Table`
List of star positions; ``x_0`` and ``y_0``, the centroids of the sources, must be
provided.

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(...)``)
group_starlist : `~astropy.table.Table`
``starlist`` with an additional column appended -- ``group_id`` gives unique
group number of mutually overlapping sources.


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
find_group
^^^^^^^^^^^

Description of method
Convenience function provided by ``DAOGroup`` returning all objects within
``crit_separation`` from a given star from ``starlist``.

Parameters
""""""""""

first_parameter : type
Description ...

second_parameter : type
Description ...
star : `~astropy.table.Row`
Single star from ``starlist`` whose mutual group members are required.
starlist : `~astropy.table.Table`
List of star positions; ``x_0`` and ``y_0``, the centroids of the sources, must be
provided.

Returns
"""""""

first_return : type
Description ...
`~numpy.array` with the IDs of all stars with distance less than ``crit_separation`` to ``star``.


Example Usage
-------------

An example of *using* the block should be provided. This needs to be after a
``::`` in the rst and indented::
Here we create a ``DAOGroup`` list of overlapping sources, then find all sources within 3 pixels
of the first source in the list. ::

print("This is example code")
from photutils.psf.groupstars import DAOGroup
group = DAOGroup(starlist, crit_separation=3)
stargroups = group.group_stars(starlist)
id_overlap = group.find_stars(starlist[0], starlist)
2 changes: 2 additions & 0 deletions docs/psf_spec/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Blocks
.. toctree::
:maxdepth: 1

block_template
background_estimator
block_template
culler_and_ender
Expand All @@ -24,3 +25,4 @@ Blocks
psf_model
scene_maker
single_object_model