Merge pull request #1982 from larrybradley/update-docs

Documentation updates

docs/reference/datasets_api.rst

@@ -1,7 +1,7 @@
 
-====================================
-Datasets (:mod:`photutils.datasets`)
-====================================
+===================================================
+Datasets and Simulation (:mod:`photutils.datasets`)
+===================================================
 
 .. automodapi:: photutils.datasets
     :no-heading:

docs/reference/detection_api.rst

@@ -1,7 +1,7 @@
 
-======================================
-Detection (:mod:`photutils.detection`)
-======================================
+========================================================
+Point-like Source Detection (:mod:`photutils.detection`)
+========================================================
 
 .. automodapi:: photutils.detection
     :no-heading:

docs/reference/geometry_api.rst

@@ -1,7 +1,7 @@
 
-====================================
-Geometry (:mod:`photutils.geometry`)
-====================================
+==============================================
+Geometry Functions (:mod:`photutils.geometry`)
+==============================================
 
 .. automodapi:: photutils.geometry
     :no-heading:

docs/reference/isophote_api.rst

@@ -1,7 +1,7 @@
 
-=======================================================
-Elliptical Isophote Fitting (:mod:`photutils.isophote`)
-=======================================================
+========================================================
+Elliptical Isophote Analysis (:mod:`photutils.isophote`)
+========================================================
 
 .. automodapi:: photutils.isophote
     :no-heading:

docs/reference/morphology_api.rst

@@ -1,7 +1,7 @@
 
-========================================
-Morphology (:mod:`photutils.morphology`)
-========================================
+======================================================
+Morphological Properties (:mod:`photutils.morphology`)
+======================================================
 
 .. automodapi:: photutils.morphology
     :no-heading:

docs/reference/utils_api.rst

@@ -1,7 +1,7 @@
 
-==================================
-Utilities (:mod:`photutils.utils`)
-==================================
+==========================================
+Utility Functions (:mod:`photutils.utils`)
+==========================================
 
 .. automodapi:: photutils.utils
     :no-heading:

docs/user_guide/centroids.rst

@@ -5,7 +5,9 @@ Introduction
 ------------
 
 `photutils.centroids` provides several functions to calculate the
-centroid of a single source:
+centroid of one or more sources.
+
+The following functions calculate the centroid of a single source:
 
 * :func:`~photutils.centroids.centroid_com`: Calculates the object
   "center of mass" from 2D image moments.

docs/user_guide/datasets.rst

@@ -1,33 +1,40 @@
 .. _datasets:
 
-Datasets (`photutils.datasets`)
-===============================
+Datasets and Simulation (`photutils.datasets`)
+==============================================
 
 Introduction
 ------------
 
-`photutils.datasets` gives easy access to load or make a few example
-datasets.  The datasets are mostly images, but they also include PSF
-models and a source catalog.
+`photutils.datasets` provides tools for loading datasets or making
+simulated data. These tools mostly involve astronomical images, but they
+also include PSF models and source catalogs.
 
-These datasets are useful for the Photutils documentation, tests, and
-benchmarks, but also for users that would like to try out or implement
-new methods for Photutils.
+These datasets are useful for the Photutils documentation examples,
+tests, and benchmarks. However, they can also be used for general data
+analysis or for users that would like to try out or implement new
+methods for Photutils.
 
-Functions that start with ``load_*`` load data files from disk.  Very
-small data files are bundled in the Photutils code repository and are
-guaranteed to be available.  Mid-sized data files are currently
-available from the `astropy-data`_ repository and loaded into the
-Astropy cache on the user's machine on first load.
+Functions that start with ``load_*`` load datasets, either from within
+the Photutils package or remotely from a GitHub repository. Very
+small data files are bundled with Photutils and are guaranteed to be
+available. Larger datasets are available from the `astropy-data`_
+repository. On first load, these larger datasets will be downloaded and
+placed into the Astropy cache on the user's machine.
 
-Functions that start with ``make_*`` generate simple simulated data
-(e.g., Gaussian sources on a flat background with Poisson or Gaussian
-noise).  Note that there are other tools like `skymaker`_ that can
-simulate much more realistic astronomical images.
+Functions that start with ``make_*`` generate simulated data.
+Typically one would need to use a combination of these functions
+to create a simulated image. For example, one might use
+:func:`~photutils.datasets.make_model_params` to create a table of
+source parameters, then use :func:`~photutils.datasets.make_model_image`
+to create an image of the sources, add noise using
+:func:`~photutils.datasets.make_noise_image`, and finally create a world
+coordinate system (WCS) using :func:`~photutils.datasets.make_wcs`. An
+example of this process is shown below.
 
 
-Getting Started
----------------
+Loading Datasets
+----------------
 
 Let's load an example image of M67 with
 :func:`~photutils.datasets.load_star_image`::
@@ -49,9 +56,95 @@ Let's plot the image:
     from photutils.datasets import load_star_image
 
     hdu = load_star_image()
-    plt.imshow(hdu.data, origin='lower', interpolation='nearest')
-    plt.tight_layout()
-    plt.show()
+    fig, ax = plt.subplots()
+    ax.imshow(hdu.data, origin='lower', interpolation='nearest')
+
+
+Simulating Images
+-----------------
+
+For this example, let's simulate an image of 2D Gaussian sources on a
+constant background with Gaussian noise.
+
+First, we'll create a table of 2D Gaussian source
+parameters with random positions, fluxes, and shapes using
+:func:`~photutils.datasets.make_model_params`::
+
+    >>> from photutils.datasets import make_model_params
+    >>> from photutils.psf import GaussianPSF
+    >>> model = GaussianPSF()
+    >>> shape = (500, 500)
+    >>> n_sources = 500
+    >>> params = make_model_params(shape, n_sources, x_name='x_0',
+    ...                            y_name='y_0', min_separation=5,
+    ...                            flux=(100, 500), x_fwhm=(1, 3),
+    ...                            y_fwhm=(1, 3), theta=(0, 90), seed=123)
+
+Next, we'll create a simulated image of the sources using the table of
+model parameters using :func:`~photutils.datasets.make_model_image`::
+
+    >>> from photutils.datasets import make_model_image
+    >>> model_shape = (25, 25)
+    >>> data = make_model_image(shape, model, params, model_shape=model_shape,
+    ...                         x_name='x_0', y_name='y_0')
+
+Next, let's add a constant background (``mean = 5``) and Gaussian noise
+(``stddev = 2``) to the image::
+
+    >>> from photutils.datasets import make_noise_image
+    >>> noise = make_noise_image(shape, distribution='gaussian', mean=5,
+    ...                          stddev=2, seed=123)
+    >>> data += noise
+
+Finally, let's plot the simulated image:
+
+.. plot::
+    :include-source:
+
+    import matplotlib.pyplot as plt
+    from astropy.visualization import simple_norm
+    from photutils.datasets import (make_model_image, make_model_params,
+                                    make_noise_image)
+    from photutils.psf import GaussianPSF
+
+    model = GaussianPSF()
+    shape = (500, 500)
+    n_sources = 500
+    params = make_model_params(shape, n_sources, x_name='x_0',
+                               y_name='y_0', min_separation=5,
+                               flux=(100, 500), x_fwhm=(1, 3),
+                               y_fwhm=(1, 3), theta=(0, 90), seed=123)
+    model_shape = (25, 25)
+    data = make_model_image(shape, model, params, model_shape=model_shape,
+                            x_name='x_0', y_name='y_0')
+
+    noise = make_noise_image(shape, distribution='gaussian', mean=5,
+                             stddev=2, seed=123)
+    data += noise
+
+    fig, ax = plt.subplots()
+    norm = simple_norm(data, 'sqrt', percent=99)
+    ax.imshow(data, norm=norm, origin='lower')
+    ax.set_title('Simulated image')
+
+We can also create a simulated world coordinate system (WCS) for the
+image using :func:`~photutils.datasets.make_wcs`::
+
+    >>> from photutils.datasets import make_wcs
+    >>> wcs = make_wcs(shape)
+    >>> wcs.pixel_to_world(0, 0)
+    <SkyCoord (ICRS): (ra, dec) in deg
+    (197.8899676, -1.3750039)>
+
+or a generalized WCS using :func:`~photutils.datasets.make_gwcs`:
+
+.. doctest-requires:: gwcs
+
+    >>> from photutils.datasets import make_gwcs
+    >>> gwcs = make_gwcs(shape)
+    >>> gwcs.pixel_to_world(0, 0)
+    <SkyCoord (ICRS): (ra, dec) in deg
+    (197.8899676, -1.3750039)>
 
 
 API Reference

docs/user_guide/detection.rst

@@ -1,17 +1,16 @@
 .. _source_detection:
 
-Source Detection (`photutils.detection`)
-========================================
+Point-like Source Detection (`photutils.detection`)
+===================================================
 
 Introduction
 ------------
 
-One generally needs to identify astronomical sources in their data
-before they can perform photometry or morphological measurements.
-Photutils provides several tools designed specifically to detect
-point-like (stellar) sources in an astronomical image. Photutils also
-provides a function to identify local peaks in an image that are above a
-specified threshold value.
+One generally needs to identify astronomical sources in the data before
+performing photometry or other measurements. The `photutils.detection`
+subpackage provides tools to detect point-like (stellar) sources in an
+image. This subpackage also provides tools to find local peaks in an
+image that are above a specified threshold value.
 
 For general-use source detection and extraction of both point-like
 and extended sources, please see :ref:`Image Segmentation

docs/user_guide/geometry.rst

@@ -5,7 +5,9 @@ Introduction
 ------------
 
 The `photutils.geometry` package contains low-level geometry functions
-used mainly by `~photutils.aperture.aperture_photometry`.
+used by aperture photometry to calculate the overlap of aperture shapes
+with a pixel grid. These functions are not intended to be used directly
+by users, but are used by the higher-level `photutils.aperture` tools.
 
 
 API Reference

docs/user_guide/grouping.rst

@@ -6,12 +6,16 @@ Source Grouping Algorithms
 Introduction
 ------------
 
-In Point Spread Function (PSF) photometry, a grouping algorithm can be
-used to combine stars into groups that can be fit simultaneously. The
-goal is to separate the stars into groups such that the profile of each
-star does not extend into the fitting region of any other star. This
-reduces the number of stars that need to be fit simultaneously, which
-can be computationally expensive.
+In Point Spread Function (PSF) photometry, the PSF model fit for a given
+star can be affected by the presence of the profile of neighboring
+stars. In this case, a grouping algorithm can be used to combine
+neighboring stars into groups that can be fit simultaneously. The goal
+is to separate the stars into groups such that the profile of each
+star in the group does not extend into the fitting region of a star
+in another group. Creating groups reduces the number of stars that
+need to be fit simultaneously, which can be computationally expensive.
+Simultaneous fitting of all stars in an image is generally not feasible,
+especially for crowded fields.
 
 Stetson (`1987, PASP 99, 191
 <https://ui.adsabs.harvard.edu/abs/1987PASP...99..191S/abstract>`_),
@@ -31,6 +35,12 @@ class to group stars. The groups are formed using hierarchical
 agglomerative clustering with a distance criterion, calling the
 `scipy.cluster.hierarchy.fclusterdata` function.
 
+To group stars during PSF fitting, typically one would simply pass an
+instance of the :class:`~photutils.psf.SourceGrouper` class with a
+defined minimum separation to the PSF photometry classes. Here, we will
+demonstrate how to use the :class:`~photutils.psf.SourceGrouper` class
+separately to group stars in a simulated image.
+
 First, let's create a simulated image containing 2D Gaussian sources
 using `~photutils.psf.make_psf_model_image`::
 
@@ -105,19 +115,24 @@ The ``groups`` output is an array of integers (ordered the same as the
 ``(x, y)`` inputs) containing the group indices. Stars with the same
 group index are in the same group.
 
-For example, to find all the stars in group 3::
-
-   >>> mask = groups == 3
-   >>> x[mask], y[mask]
-   (array([60.32708921, 58.73063714]), array([147.24184586, 158.0612346 ]))
-
 The grouping algorithm separated the 100 stars into 65 distinct groups:
 
 .. doctest-skip::
 
     >>> print(max(groups))
     65
 
+For example, to find the positions of the stars in group 3::
+
+   >>> mask = groups == 3
+   >>> x[mask], y[mask]
+   (array([60.32708921, 58.73063714]), array([147.24184586, 158.0612346 ]))
+
+When performing PSF photometry, the group indices can be included in the
+``init_params`` table when calling the PSF photometry classes. These
+group indices would override the input `~photutils.psf.SourceGrouper`
+instance.
+
 Finally, let's plot a circular aperture around each star, where stars in
 the same group have the same aperture color: