More docs

git-svn-id: http://svn.stsci.edu/svn/ssb/stsci_python/stsci_python/trunk/stwcs@10521 fe389314-cf27-0410-b35b-8c050e845b92

8 files changed, 102 insertions, 64 deletions

diff --git a/doc/source/hstwcs.rst b/doc/source/hstwcs.rst
index ec69944..dd858d5 100644
--- a/doc/source/hstwcs.rst
+++ b/doc/source/hstwcs.rst
@@ -6,9 +6,6 @@ HSTWCS API
     
 .. currentmodule:: stwcs.wcsutil.hstwcs
 
---------------------------
-HSTWCS
---------------------------
 .. autoclass:: HSTWCS
    :members:
    :undoc-members:
diff --git a/lib/__init__.py b/lib/__init__.py
index ebd45ef..0728a1c 100644
--- a/lib/__init__.py
+++ b/lib/__init__.py
@@ -1,3 +1,14 @@
+""" STWCS
+
+This package provides support for WCS based distortion models and coordinate 
+transformation. It relies on PyWCS (based on WCSLIB). It consists of two subpackages:
+updatewcs and wcsutil. Updatewcs performs corrections to the basic WCS and includes 
+other distortion infomation in the science files as header keywords or file extensions.
+Wcsutil provides an HSTWCS object which extends pywcs.WCS object and provides HST instrument
+specific information as well as methods for coordinate tarnsformaiton. Wcsutil also provides 
+functions for manipulating alternate WCS descriptions in the headers.
+
+"""
 from __future__ import division # confidence high
 
 #import all needed modules here to avoid relative imports
diff --git a/updatewcs/apply_corrections.py b/updatewcs/apply_corrections.py
index 0c49923..b00b7ef 100644
--- a/updatewcs/apply_corrections.py
+++ b/updatewcs/apply_corrections.py
@@ -31,9 +31,7 @@ cnames = {'DET2IMCorr': 'Detector to Image Correction',
                             
 def setCorrections(fname, vacorr=True, tddcorr=True, dgeocorr=True, d2imcorr=True):
     """
-    Purpose
-    =======
-    Creates a list of corrections to be applied to a file.
+    Creates a list of corrections to be applied to a file
     based on user input paramters and allowed corrections
     for the instrument.
     """
@@ -111,8 +109,6 @@ def applyTDDCorr(fname, utddcorr):
 
 def applyDgeoCorr(fname, udgeocorr):
     """
-    Purpose
-    =======
     Determines whether non-polynomial distortion lookup tables should be added 
     as extensions to the science file based on the 'NPOLFILE' keyword in the 
     primary header and NPOLEXT kw in the first extension.
diff --git a/updatewcs/corrections.py b/updatewcs/corrections.py
index ee73d61..2e06656 100644
--- a/updatewcs/corrections.py
+++ b/updatewcs/corrections.py
@@ -13,7 +13,7 @@ DGEOCorr = dgeo.DGEOCorr
 class TDDCorr(object):
     """
     Apply time dependent distortion correction to distortion coefficients and basic
-    WCS keywords. This applies only to ACS/WFC data.
+    WCS keywords. This correction **must** be done before any other WCS correction.
         
     Parameters
     ----------
@@ -21,17 +21,34 @@ class TDDCorr(object):
              An HSTWCS object to be modified
     ref_wcs: HSTWCS object
              A reference HSTWCS object
-            
+             
     Notes
     -----
-    Compute the ACS/WFC time dependent distortion terms
-    as described in [1]_.
+    Compute the ACS/WFC time dependent distortion terms as described 
+    in [1]_ and apply the correction to the WCS of the observation.
+    
+    The model coefficients are stored in the primary header of the IDCTAB.
+    :math:`D_{ref}` is the reference date. The computed corrections are saved 
+    in the science extension header as TDDALPHA and TDDBETA keywords.
+    
+    .. math:: TDDALPHA = A_{0} + {A_{1}*(obsdate - D_{ref})}
+    
+    .. math:: TDDBETA =  B_{0} + B_{1}*(obsdate - D_{ref})
+    
+       
+    The time dependent distortion affects the IDCTAB coefficients, and the
+    relative location of the two chips. Because the linear order IDCTAB 
+    coefficients ar eused in the computatuion of the NPOL extensions,
+    the TDD correction affects all components of the distortion model.
     
-    The zero-point terms account for the skew accumulated between
-    2002.0 and 2004.5, when the latest IDCTAB was delivered.
-    alpha = 0.095 + 0.090*(rday-dday)/2.5
-    beta = -0.029 - 0.030*(rday-dday)/2.5
+    Application of TDD to the IDCTAB polynomial coefficients:
+    The TDD model is computed in Jay's frame, while the IDCTAB coefficients 
+    are in the HST V2/V3 frame. The coefficients are transformed to Jay's frame, 
+    TDD is applied and they are transformed back to the V2/V3 frame. This 
+    correction is performed in this class. 
     
+    Application of TDD to the relative location of the two chips is 
+    done in `makewcs`.
     
     References
     ----------
@@ -162,10 +179,18 @@ class VACorr(object):
         
 class CompSIP(object):
     """
-    Compute SIP coefficients from IDC table coefficients.
+    Compute Simple Imaging Polynomial (SIP) coefficients as defined in [2]_
+    from IDC table coefficients.
     
-    Notes
-    -----
+    This class transforms the TDD corrected IDCTAB coefficients into SIP format.
+    It also applies a binning factor to the coefficients if the observation was 
+    binned.
+    
+    References
+    ----------
+    .. [2] David Shupe, et al, "The SIP Convention of representing Distortion
+       in FITS Image headers",  Astronomical Data Analysis Software And Systems, ASP
+       Conference Series, Vol. 347, 2005
     
     """
     
diff --git a/updatewcs/det2im.py b/updatewcs/det2im.py
index 993ec52..6eb7fa7 100644
--- a/updatewcs/det2im.py
+++ b/updatewcs/det2im.py
@@ -5,6 +5,32 @@ from pytools import fileutil
 import utils
 
 class DET2IMCorr(object):
+    """
+    Stores a small correction to the detector coordinates as a d2imarr 
+    extension in the science file.
+    
+    Notes
+    -----
+    For the case of ACS/WFC every 68th column is wider than the rest.
+    To compensate for this a small correction needs to be applied to the 
+    detector coordinates. We call this a detector to image transformation. 
+    The so obtained image coordinates are the input to all other distortion 
+    corrections. The correction is originally stored in an external 
+    reference file pointed to by 'D2IMFILE' keyword in the primary header. 
+    This class attaches the correction array as an extension to the science 
+    file with extname = `d2imarr`. 
+    
+    Other keywords used in this correction are:
+
+    `AXISCORR`: integer (1 or 2) - axis to which the detector to image 
+                correction is applied
+                
+    `D2IMEXT`:  string = name of reference file which was used to create
+                the lookup table extension
+                
+    `D2IMERR`:  float, optional - maximum value of the correction
+    
+    """
     def updateWCS(cls, fobj):
         """
         Parameters
diff --git a/updatewcs/dgeo.py b/updatewcs/dgeo.py
index 7c6ec45..44d495e 100644
--- a/updatewcs/dgeo.py
+++ b/updatewcs/dgeo.py
@@ -8,19 +8,21 @@ import numpy as np
 class DGEOCorr(object):
     """
     Defines a Lookup table prior distortion correction as per WCS paper IV.
-    It uses a reference file defined by the NPOLFILE (suffix 'NPL') keyword in the primary header.
+    It uses a reference file defined by the NPOLFILE (suffix 'NPL') keyword 
+    in the primary header.
     
     Notes
     -----
-    - Using extensions in the reference file create a WCSDVARR extension 
-      and add it to the file object.
-    - Add record-valued keywords which describe the lookup tables to the 
-      science extension header
-    - Add a keyword 'NPOLEXT' to the science extension header, whose
-      value is the reference file used to create the WCSDVARR extension
+    - Using extensions in the reference file create a WCSDVARR extensions 
+      and add them to the science file.
+    - Add record-valued keywords to the science extension header to describe 
+      the lookup tables.
+    - Add a keyword 'NPOLEXT' to the science extension header to store
+      the name of the reference file used to create the WCSDVARR extensions.
     
-    If WCSDVARR extensions exist, subsequent updates will overwrite them. 
-    If not, they will be added to the file object.
+    If WCSDVARR extensions exist and `NPOLFILE` is different from `NPOLEXT`, 
+    a subsequent update will overwrite the existing extensions. 
+    If WCSDVARR extensions were not found in the science file, they will be added.
     
     It is assumed that the NPL reference files were created to work with IDC tables
     but will be applied with SIP coefficients. A transformation is applied to correct 
@@ -30,8 +32,9 @@ class DGEOCorr(object):
     
     def updateWCS(cls, fobj):
         """
-        :Parameters:
-        `fobj`: pyfits object
+        Parameters
+        ----------
+        fobj: pyfits object
                 Science file, for which a distortion correction in a NPOLFILE is available
                 
         """
diff --git a/updatewcs/makewcs.py b/updatewcs/makewcs.py
index 6e9b7a5..4210fd3 100644
--- a/updatewcs/makewcs.py
+++ b/updatewcs/makewcs.py
@@ -8,20 +8,18 @@ from pytools import fileutil
 
 class MakeWCS(object):
     """
-    Purpose
-    =======
     Recompute basic WCS keywords based on PA_V3 and distortion model.
     
-    Algorithm
-    =========
-    - update reference chip wcs
-        
-        -- CRVAL: reference chip model zero point (XREF/YREF) on the sky
+    Notes
+    -----
+    - Compute the reference chip WCS:
+    
+        -- CRVAL: transform the model XREF/YREF to the sky
         -- PA_V3 is calculated at the target position and adjusted 
            for each chip orientation
         -- CD: PA_V3 and the model scale are used to cnstruct a CD matrix
         
-    - update extension wcs
+    - Compute the second chip WCS:
 
         -- CRVAL: - the distance between the zero points of the two 
                   chip models on the sky
@@ -30,6 +28,8 @@ class MakeWCS(object):
             between CRVAL and these vectors is the new CD matrix for each chip.
         -- CRPIX: chip's model zero point in pixel space (XREF/YREF)
     
+    - Time dependent distortion correction is applied to both chips' V2/V3 values.
+    
     """
     tdd_xyref = {1: [2048, 3072], 2:[2048, 1024]}
     def updateWCS(cls, ext_wcs, ref_wcs):    
@@ -213,11 +213,11 @@ class MakeWCS(object):
 
 def troll(roll, dec, v2, v3):
     """ Computes the roll angle at the target position based on:
-            the roll angle at the V1 axis(roll),
-            the dec of the target(dec), and
-            the V2/V3 position of the aperture (v2,v3) in arcseconds.
+        the roll angle at the V1 axis(roll),
+        the dec of the target(dec), and
+        the V2/V3 position of the aperture (v2,v3) in arcseconds.
 
-        Based on the algorithm provided by Colin Cox that is used in
+        Based on algorithm provided by Colin Cox and used in
         Generic Conversion at STScI.
     """
     # Convert all angles to radians
diff --git a/wcsutil/altwcs.py b/wcsutil/altwcs.py
index 76bfc76..4c41d2a 100644
--- a/wcsutil/altwcs.py
+++ b/wcsutil/altwcs.py
@@ -5,17 +5,6 @@ import pywcs
 import numpy as np
 import pyfits
 
-"""
-    WCS keywords:
-    'CD1_1', 'CD1_2', 'CD2_1', 'CD2_2', 
-    'CRVAL*',
-    'CTYPE*',
-    'CRPIX*', 
-    'CDELT*',
-    'CUNIT*',
-    'ORIENTAT' 
-    'TDDALPHA', 'TDDBETA' 
-"""
 
 # file operations
 def archiveWCS(fname, ext, wcskey=" ", wcsname=" ", clobber=False):
@@ -369,6 +358,7 @@ def pc2cd(hdr, key=' '):
     Parameters
     ----------
     hdr: pyfits.Header
+    
     """
     for c in ['1_1', '1_2', '2_1', '2_2']:
         try:
@@ -426,17 +416,7 @@ def parpasscheck(fobj, ext, wcskey, wcsname, clobber=True):
                 print 'Use "wcsutil.next_wcskey" to obtain a valid wcskey'
                 print 'or use "clobber=True" to overwrite the values.'
                 return False
-        """
-            else:
-                # reuse the value for WCSNAME
-                if wcsname == " ": 
-                    wcsname = f[1].header["WCSNAME"+wcskey]
-                else:
-                    wkey = wcskey
-                    wname = wcsname
-        wkey = wcskey 
-        wname = wcsname
-        """
+
 
     return True