Improved documentation

Working on #24
avigan · Aug 30, 2017 · 949282f · 949282f
1 parent fd5eb03
commit 949282f
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 53 deletions.
diff --git a/examples/standard_irdis_reduction.py b/examples/standard_irdis_reduction.py
@@ -10,7 +10,7 @@
 # red.full_reduction()
 
 # standard manual reduction
-# red.init_reduction()
+red.init_reduction()
 # red.create_static_calibrations()
 # red.preprocess_science()
 # red.process_science()

diff --git a/pysphere/IFS.py b/pysphere/IFS.py
@@ -458,7 +458,7 @@ def init_reduction(self):
 
     def create_static_calibrations(self):
         '''
-        Create all static calibrations, mainly with esorex
+        Create static calibrations, mainly with esorex
         '''
 
         self.sph_ifs_cal_dark()
@@ -514,7 +514,7 @@ def full_reduction(self):
 
     def read_info(self):
         '''
-        Read the files, calibs and frames information
+        Read the files, calibs and frames information from disk
 
         files_info : dataframe
             The data frame with all the information on files
@@ -697,18 +697,9 @@ def sort_files(self):
 
     def sort_frames(self):
         '''
-        Extract the frames information from the science files
+        Extract the frames information from the science files and save
+        result in a data frame
 
-        Parameters
-        ----------
-        root_path : str
-            Path to the dataset
-
-        files_info : dataframe
-            The data frame with all the information on files
-
-        Returns
-        -------
         calibs : dataframe
             A data frame with the information on all frames
         '''
@@ -757,6 +748,9 @@ def sort_frames(self):
     def check_files_association(self):
         '''
         Performs the calibration files association as a sanity check
+
+        Warnings and errors are reported at the end. Execution is
+        interupted in case of error.
         '''
 
         # check if recipe can be executed
@@ -895,7 +889,7 @@ def sph_ifs_cal_dark(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1000,7 +994,7 @@ def sph_ifs_cal_detector_flat(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1091,7 +1085,7 @@ def sph_ifs_cal_specpos(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1178,7 +1172,7 @@ def sph_ifs_cal_wave(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1280,7 +1274,7 @@ def sph_ifs_cal_ifu_flat(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1403,8 +1397,7 @@ def sph_ifs_preprocess_science(self,
                                    subtract_background=True, fix_badpix=True, correct_xtalk=True,
                                    collapse_science=False, collapse_type='mean', coadd_value=2,
                                    collapse_psf=True, collapse_center=True):
-        '''
-        Pre-processes the science frames.
+        '''Pre-processes the science frames.
 
         This function can perform multiple steps:
           - collapse of the frames according to different schemes
@@ -1421,6 +1414,10 @@ def sph_ifs_preprocess_science(self,
         For the PSFs and star center frames, there is either no collapse
         or a mean collapse.
 
+        The pre-processed frames are saved in the preproc
+        sub-directory and will be combined after the (x,y,lambda) cube
+        will be created with esorex.
+
         Parameters
         ----------
         subtract_background : bool
@@ -1449,7 +1446,8 @@ def sph_ifs_preprocess_science(self,
 
         collapse_center :  bool
             Collapse data for OBJECT,CENTER cubes. Default is True. Note
-            that the collapse type is mean and cannot be changed.    
+            that the collapse type is mean and cannot be changed.
+
         '''
 
         # check if recipe can be executed
@@ -1704,7 +1702,7 @@ def sph_ifs_science_cubes(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -1830,8 +1828,8 @@ def sph_ifs_science_cubes(self, silent=True):
 
 
     def sph_ifs_wavelength_recalibration(self, high_pass=False, display=False, save=True):
-        '''
-        Performs a recalibration of the wavelength, is star center frames are available
+        '''Performs a recalibration of the wavelength, is star center frames
+        are available
 
         See Vigan et al. (2015, MNRAS, 454, 129) for details of the
         wavelength recalibration:
@@ -1849,6 +1847,7 @@ def sph_ifs_wavelength_recalibration(self, high_pass=False, display=False, save=
         save : bool
             Save the fit of the sattelite spot for quality check. Default is True,
             although it is a bit slow.
+
         '''
 
         # check if recipe can be executed
@@ -2034,8 +2033,8 @@ def sph_ifs_wavelength_recalibration(self, high_pass=False, display=False, save=
 
 
     def sph_ifs_star_center(self, high_pass=False, display=False, save=True):
-        '''
-        Determines the star center for all frames
+        '''Determines the star center for all frames where a center can be
+        determined (OBJECT,CENTER and OBJECT,FLUX)
 
         Parameters
         ----------
@@ -2048,6 +2047,7 @@ def sph_ifs_star_center(self, high_pass=False, display=False, save=True):
         save : bool
             Save the fit of the sattelite spot for quality check. Default is True,
             although it is a bit slow.
+
         '''
 
         # check if recipe can be executed

diff --git a/pysphere/IRDIS.py b/pysphere/IRDIS.py
@@ -25,8 +25,9 @@
 
 
 class ImagingReduction(object):
-    '''
-    SPHERE/IRDIS imaging reduction object
+    '''SPHERE/IRDIS imaging reduction object. It handles the dual-band
+    imaging (DBI) and classifcal imaging (CI) observing modes.
+
     '''
 
     ##################################################
@@ -50,13 +51,13 @@ class ImagingReduction(object):
     ##################################################
 
     def __init__(self, path):
-        '''
-        Initialization of the ImagingReduction
+        '''Initialization of the ImagingReduction instances
 
         Parameters
         ----------
         path : str
             Path to the directory containing the raw data
+
         '''
 
         # init path and name
@@ -142,7 +143,7 @@ def init_reduction(self):
 
     def create_static_calibrations(self):
         '''
-        Create all static calibrations with esorex
+        Create static calibrations with esorex
         '''
 
         self.sph_ird_cal_dark()
@@ -151,7 +152,7 @@ def create_static_calibrations(self):
 
     def preprocess_science(self):
         '''
-        Extract images in data cubes, clean and collapse
+        Clean and collapse images
         '''
 
         self.sph_ird_preprocess_science()
@@ -193,7 +194,7 @@ def full_reduction(self):
 
     def read_info(self):
         '''
-        Read the files, calibs and frames information
+        Read the files, calibs and frames information from disk
 
         files_info : dataframe
             The data frame with all the information on files
@@ -354,18 +355,9 @@ def sort_files(self):
 
     def sort_frames(self):
         '''
-        Extract the frames information from the science files
+        Extract the frames information from the science files and save
+        result in a data frame
 
-        Parameters
-        ----------
-        root_path : str
-            Path to the dataset
-
-        files_info : dataframe
-            The data frame with all the information on files
-
-        Returns
-        -------
         calibs : dataframe
             A data frame with the information on all frames
         '''
@@ -413,7 +405,10 @@ def sort_frames(self):
 
     def check_files_association(self):
         '''
-        Performs the calibration files association as a sanity check
+        Performs the calibration files association as a sanity check.
+
+        Warnings and errors are reported at the end. Execution is
+        interupted in case of error.
         '''
 
         # check if recipe can be executed
@@ -496,7 +491,7 @@ def sph_ird_cal_dark(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -613,7 +608,7 @@ def sph_ird_cal_detector_flat(self, silent=True):
         Parameters
         ----------
         silent : bool
-            Suppress esorex output. Optional, default is True
+            Suppress esorex output. Default is True
         '''
 
         # check if recipe can be executed
@@ -704,8 +699,7 @@ def sph_ird_preprocess_science(self,
                                    subtract_background=True, fix_badpix=True,
                                    collapse_science=False, collapse_type='mean', coadd_value=2,
                                    collapse_psf=True, collapse_center=True):
-        '''
-        Pre-processes the science frames.
+        '''Pre-processes the science frames.
 
         This function can perform multiple steps:
           - collapse of the frames according to different schemes
@@ -722,6 +716,9 @@ def sph_ird_preprocess_science(self,
         For the PSFs and star center frames, there is either no collapse
         or a mean collapse.
 
+        The pre-processed frames are saved in the preproc
+        sub-directory and will be combined later.
+        
         Parameters
         ----------
         subtract_background : bool
@@ -747,7 +744,8 @@ def sph_ird_preprocess_science(self,
 
         collapse_center :  bool
             Collapse data for OBJECT,CENTER cubes. Default is True. Note
-            that the collapse type is mean and cannot be changed.    
+            that the collapse type is mean and cannot be changed.
+
         '''
 
         # check if recipe can be executed
@@ -956,8 +954,8 @@ def sph_ird_preprocess_science(self,
 
 
     def sph_ird_star_center(self, high_pass=False, display=False, save=True):
-        '''
-        Determines the star center for all frames
+        '''Determines the star center for all frames where a center can be
+        determined (OBJECT,CENTER and OBJECT,FLUX)
 
         Parameters
         ----------
@@ -970,6 +968,7 @@ def sph_ird_star_center(self, high_pass=False, display=False, save=True):
         save : bool
             Save the fit of the sattelite spot for quality check. Default is True,
             although it is a bit slow.
+
         '''
 
         # check if recipe can be executed