Transfer documentation from JWST

docs/conf.py

@@ -43,6 +43,8 @@
         "https://spacetelescope-drizzle.readthedocs.io/en/latest/",
         None
     ),
+    "imagestats": ("https://stsciimagestats.readthedocs.io/en/latest/", None),
+    "spherical_geometry": ("https://spherical-geometry.readthedocs.io/en/latest/", None),
 }
 
 extensions = [
@@ -82,4 +84,7 @@
 nitpick_ignore = [
     ("py:class", "optional"),
     ("py:class", "np.ndarray"),
+    ("py:class", "stsci.imagestats.ImageStats"),  # intersphinx isn't working here
+    ("py:class", "spherical_geometry.polygon.SphericalPolygon"), # intersphinx isn't working here
 ]
+

docs/stcal/package_index.rst

@@ -10,3 +10,4 @@ Package Index
    tweakreg/index.rst
    outlier_detection/index.rst
    resample/index.rst
+   skymatch/index.rst

docs/stcal/skymatch/description.rst

@@ -0,0 +1,4 @@
+Description
+============
+
+This sub-package contains the functions and objects useful for skymatch.

docs/stcal/skymatch/index.rst

@@ -0,0 +1,14 @@
+.. _skymatch:
+
+=======================
+Skymatch
+=======================
+
+.. toctree::
+   :maxdepth: 2
+
+   description.rst
+
+.. automodapi:: stcal.skymatch.skystatistics
+.. automodapi:: stcal.skymatch.skyimage
+.. automodapi:: stcal.skymatch.skymatch

src/stcal/skymatch/skyimage.py

@@ -129,13 +129,13 @@ def __init__(self, image, wcs_fwd, wcs_inv, pix_area=1.0, convf=1.0,
 
         Parameters
         ----------
-        image : numpy.ndarray, NDArrayDataAccessor
+        image : numpy.ndarray, `NDArrayDataAccessor`
             A 2D array of image data or a `NDArrayDataAccessor`.
 
-        wcs_fwd : function
+        wcs_fwd : collections.abc.Callable
             "forward" pixel-to-world transformation function.
 
-        wcs_inv : function
+        wcs_inv : collections.abc.Callable
             "inverse" world-to-pixel transformation function.
 
         pix_area : float, optional
@@ -151,26 +151,26 @@ def __init__(self, image, wcs_fwd, wcs_inv, pix_area=1.0, convf=1.0,
               The functionality to support this conversion is not yet
               implemented and at this moment `convf` is ignored.
 
-        mask : numpy.ndarray, NDArrayDataAccessor
+        mask : numpy.ndarray, `NDArrayDataAccessor`
             A 2D array or `NDArrayDataAccessor` of a 2D array that indicates
             which pixels in the input `image` should be used for sky
             computations (``1``) and which pixels should **not** be used
             for sky computations (``0``).
 
-        sky_id : anything
+        sky_id : typing.Any
             The value of this parameter is simple stored within the `SkyImage`
             object. While it can be of any type, it is preferable that `id` be
             of a type with nice string representation.
 
-        skystat : callable, None, optional
+        skystat : collections.abc.Callable, None, optional
             A callable object that takes a either a 2D image (2D
             `numpy.ndarray`) or a list of pixel values (a Nx1 array) and
             returns a tuple of two values: some statistics (e.g., mean,
             median, etc.) and number of pixels/values from the input image
             used in computing that statistics.
 
             When `skystat` is not set, `SkyImage` will use
-            :py:class:`~jwst_pipeline.skymatch.skystatistics.SkyStats` object
+            :py:class:`~stcal.skymatch.skystatistics.SkyStats` object
             to perform sky statistics on image data.
 
         stepsize : int, None, optional
@@ -345,12 +345,12 @@ def intersection(self, skyimage):
 
         Parameters
         ----------
-        skyimage : SkyImage, SkyGroup, SphericalPolygon
+        skyimage : SkyImage, SkyGroup, spherical_geometry.polygon.SphericalPolygon
             Another object that should be intersected with this `SkyImage`.
 
         Returns
         -------
-        polygon : SphericalPolygon
+        polygon : `SphericalPolygon`
             A :py:class:`~spherical_geometry.polygon.SphericalPolygon` that is
             the intersection of this `SkyImage` and `skyimage`.
 
@@ -442,7 +442,7 @@ def set_builtin_skystat(self, skystat='median', lower=None, upper=None,
         Replace already set `skystat` with a "built-in" version of a
         statistics callable object used to measure sky background.
 
-        See :py:class:`~jwst_pipeline.skymatch.skystatistics.SkyStats` for the
+        See :py:class:`~stcal.skymatch.skystatistics.SkyStats` for the
         parameter description.
 
         """
@@ -462,10 +462,9 @@ def calc_sky(self, overlap=None, delta=True):
 
         Parameters
         ----------
-        overlap : SkyImage, SkyGroup, SphericalPolygon, list of tuples, \
-None, optional
+        overlap : SkyImage, SkyGroup, `SphericalPolygon`, list[tuple[typing.Any]], None, optional
             Another `SkyImage`, `SkyGroup`,
-            :py:class:`spherical_geometry.polygons.SphericalPolygon`, or
+            :py:class:`spherical_geometry.polygon.SphericalPolygon`, or
             a list of tuples of (RA, DEC) of vertices of a spherical
             polygon. This parameter is used to indicate that sky statistics
             should computed only in the region of intersection of *this*
@@ -688,12 +687,12 @@ def intersection(self, skyimage):
 
         Parameters
         ----------
-        skyimage : SkyImage, SkyGroup, SphericalPolygon
+        skyimage : SkyImage, SkyGroup, `SphericalPolygon`
             Another object that should be intersected with this `SkyImage`.
 
         Returns
         -------
-        intersect_poly : SphericalPolygon
+        intersect_poly : `SphericalPolygon`
             A :py:class:`~spherical_geometry.polygon.SphericalPolygon` that is
             the intersection of this `SkyImage` and `skyimage`.
 
@@ -768,10 +767,9 @@ def calc_sky(self, overlap=None, delta=True):
 
         Parameters
         ----------
-        overlap : SkyImage, SkyGroup, SphericalPolygon, list of tuples, \
-None, optional
+        overlap : SkyImage, SkyGroup, `SphericalPolygon`, list[tuple[typing.Any]], None, optional
             Another `SkyImage`, `SkyGroup`,
-            :py:class:`spherical_geometry.polygons.SphericalPolygon`, or
+            :py:class:`spherical_geometry.polygon.SphericalPolygon`, or
             a list of tuples of (RA, DEC) of vertices of a spherical
             polygon. This parameter is used to indicate that sky statistics
             should computed only in the region of intersection of *this*

src/stcal/skymatch/skymatch.py

@@ -34,10 +34,11 @@ def skymatch(images, skymethod='global+match', match_down=True, subtract=False):
     ----------
 
     images : list of SkyImage or SkyGroup
-        A list of of :py:class:`~jwst.skymatch.skyimage.SkyImage` or
-        :py:class:`~jwst.skymatch.skyimage.SkyGroup` objects.
+        A list of of :py:class:`~stcal.skymatch.skyimage.SkyImage` or
+        :py:class:`~stcal.skymatch.skyimage.SkyGroup` objects.
 
-    skymethod : {'local', 'global+match', 'global', 'match'}, optional
+    skymethod : str, optional
+        Available methods: {'local', 'global+match', 'global', 'match'}
         Select the algorithm for sky computation:
 
         * **'local'** : compute sky background values of each input image or
@@ -88,22 +89,23 @@ def skymatch(images, skymethod='global+match', match_down=True, subtract=False):
           This setting applies *only* when the `skymethod` parameter is
           either `'match'` or `'global+match'`.
 
-    subtract : bool (Default = False)
+    subtract : bool
         Subtract computed sky value from image data.
+        (Default: `False`).
 
     Raises
     ------
 
     TypeError
         The `images` argument must be a Python list of
-        :py:class:`~jwst.skymatch.skyimage.SkyImage` and/or
-        :py:class:`~jwst.skymatch.skyimage.SkyGroup` objects.
+        :py:class:`~stcal.skymatch.skyimage.SkyImage` and/or
+        :py:class:`~stcal.skymatch.skyimage.SkyGroup` objects.
 
 
     Notes
     -----
 
-    :py:func:`match` provides new algorithms for sky value computations
+    :py:func:`skymatch` provides new algorithms for sky value computations
     and enhances previously available algorithms used by, e.g.,
     `astrodrizzle <http://stsdas.stsci.edu/stsci_python_sphinxdocs_2.13/\
 drizzlepac/astrodrizzle.html>`_.
@@ -163,7 +165,7 @@ def skymatch(images, skymethod='global+match', match_down=True, subtract=False):
       baseline sky value (instead of 0 in ``'match'`` algorithm alone).
 
     **Remarks:**
-      * :py:func:`match` works directly on *geometrically distorted*
+      * :py:func:`skymatch` works directly on *geometrically distorted*
         flat-fielded images thus avoiding the need to perform distortion
         correction on the input images.
 
@@ -179,7 +181,7 @@ def skymatch(images, skymethod='global+match', match_down=True, subtract=False):
       Primary reason for introducing "sky match" algorithm was to try to
       equalize the sky in large mosaics in which computation of the
       "absolute" sky is difficult due to the presence of large diffuse
-      sources in the image. As discussed above, :py:func:`match`
+      sources in the image. As discussed above, :py:func:`skymatch`
       accomplishes this by comparing "sky values" in a pair of images in the
       overlap region (that is common to both images). Quite obviously the
       quality of sky "matching" will depend on how well these "sky values"
@@ -188,10 +190,10 @@ def skymatch(images, skymethod='global+match', match_down=True, subtract=False):
       measured sky may be the surface brightness of large galaxy, nebula, etc.
 
       In the discussion below we will refer to parameter names in
-      :py:class:`~jwst.skymatch.skystatistics.SkyStats` and these
+      :py:class:`~stcal.skymatch.skystatistics.SkyStats` and these
       parameter names may differ from the parameters of the actual `skystat`
       object passed to initializer of the
-      :py:class:`~jwst.skymatch.skyimage.SkyImage`.
+      :py:class:`~stcal.skymatch.skyimage.SkyImage`.
 
       Here is a brief list of possible limitations/factors that can affect
       the outcome of the matching (sky subtraction in general) algorithm:

src/stcal/skymatch/skystatistics.py

@@ -1,7 +1,7 @@
 """
 `skystatistics` module provides statistics computation class used by
-:py:func:`~jwst.skymatch.skymatch.skymatch`
-and :py:class:`~jwst.skymatch.skyimage.SkyImage`.
+:py:func:`~stcal.skymatch.skymatch.skymatch`
+and :py:class:`~stcal.skymatch.skyimage.SkyImage`.
 
 :Authors: Mihai Cara (contact: [email protected])
 
@@ -30,8 +30,9 @@ def __init__(self, skystat='mean', lower=None, upper=None,
 
         Parameters
         -----------
-        skystat : {'mode', 'median', 'mode', 'midpt'}, optional
-            Sets the statistics that will be returned by `~SkyStats.calc_sky`.
+        skystat : optional
+            possible values are'mode', 'median', 'mode', 'midpt".
+            Sets the statistics that will be returned by `~stcal.skymatch.skystatistics.SkyStats.calc_sky`.
             The following statistics are supported: 'mean', 'mode', 'midpt',
             and 'median'. First three statistics have the same meaning as in
             `stsdas.toolbox.imgtools.gstatistics <http://stsdas.stsci.edu/\