Changeset 14118 for fact/tools/pyscripts/pyfact/pyfact.py

Timestamp:

06/08/12 15:31:05 (12 years ago)

Author:

neise

Message:

added a lot of docu

File:

• fact/tools/pyscripts/pyfact/pyfact.py (modified) (21 diffs)

fact/tools/pyscripts/pyfact/pyfact.py

@@ -29 +29 @@
             the second should be an amplitude calibration file(\*.drs.fits.gz)
         """
+        
+        self.__module__ = 'pyfact'
+        
         # sanity check for input
         if type(filelist) != type(list()):
@@ -72 +75 @@
     """ raw data access and calibration
     
+    class is **iterable**
+    
     - open raw data file and drs calibration file
     - performs amplitude calibration
@@ -83 +88 @@
 
     def __init__(self, data_file_name, calib_file_name, 
-                user_action_calib=lambda acal_data, data, blm, tom, gm, scells, nroi: None,
                 baseline_file_name='',
                 return_dict = True,
+                use_CalFactFits = True,
                 do_calibration = True,
-                use_CalFactFits = True):
-        """ initialize object
-        
-        open data file and calibration data file
-        get basic information about the data in data_file_name
-        allocate buffers for data access
-
-        data_file_name   : fits or fits.gz file of the data including the path
-        calib_file_name : fits or fits.gz file containing DRS calibration data
-        baseline_file_name : npy file containing the baseline values
+                user_action_calib=lambda acal_data, data, blm, tom, gm, scells, nroi: None):
+        """ -constructor-
+        
+        - open data file and calibration data file
+        - get basic information about the data in data_file_name
+        - allocate buffers for data access
+
+        *data_file_name*   : fits or fits.gz file of the data including the path
+        
+        *calib_file_name* : fits or fits.gz file containing DRS calibration data
+        
+        *baseline_file_name* : npy file containing the baseline values
+        
+        *return_dict* : this option will be removed in future releases.
+            formerly the next() method returned only a subset of (important) event information, 
+            and it was not transparent how to retrieve the other (less important) information.
+            Nowadays next() returns self.__dict__ which contains everything we were able to find in the fits file.
+            
+        *use_CalFactFits* : formerly the DRS amplitude calibration was 
+        implemented in python. But for performance reasons this was now moved into 
+        a C++ class called CalFactFits. For test purposes, this option can be set to 
+        False, but this is not really maintained anymore. If DRS the DRS calibration algorithm is 
+        beeing updated in C++ it may not be updated in the python implementation.
+        
+        *do_calibration* : In case *use_CalFactFits* is False, one may choose
+        not to calibrate the data at all, thus safe quite some time.
+        This is imho only needed in case one is interesting in learning something about the 
+        calibration algorithm itself.
+        
+        *user_action_calib* : callback function, intended for tests of the DRS calibration algorithm.
+        but since this is not done in the Python regime anymore, this function is never called.
+        (depending on *use_CalFactFits* of course)
         """
         self.__module__='pyfact'
@@ -122 +149 @@
             self.correct_baseline = True
         
+        
         # access data file
         if use_CalFactFits:
@@ -129 +157 @@
                 print 'problem accessing data file: ', data_file_name
                 raise  # stop ! no data
-                
+            
+            #: either CalFactFits object or FactFits object, depending on *use_CalFactFits*
             self.data_file = data_file
+            #: 1440x300 nparray containing the event data. pixel sorted according to CHID
             self.data      = np.empty( data_file.npix * data_file.nroi, np.float64)
             data_file.SetNpcaldataPtr(self.data)
-            self.data      = self.data.reshape( data_file.npix, data_file.nroi ) 
+            self.data      = self.data.reshape( data_file.npix, data_file.nroi )
+            #: copy of data. here for historical reasons
             self.acal_data = self.data
-
+            #: region of interest. (number of DRS slices read). 
+            # for FACT data mostly 300. for special runs sometimes 1024.
             self.nroi    = data_file.nroi
+            #: number of Pixel in FACT. should be 1440
             self.npix    = data_file.npix
+            #: the total number of events in the data_file
             self.nevents = data_file.nevents
             
             # Data per event
+            #:  starting at 1
             self.event_id     = None
+            #: data=4 ; the rest I don't know by heart .. should be documented here :-)
             self.trigger_type = None
             #self.start_cells  = None
             #self.board_times  = None
+            #: slice where drs readout started for all DRS chips (160) .. but enlarged to the size of 1440 pixel. thus there are always 9 equal numbers inside.
             self.start_cells = np.zeros( self.npix, np.int16 )
+            #: each FAD has an onboard clock running from startup time. Currently I don't know the time unit. However this is an array of 40 times, since we have 40 boards. 
             self.board_times = np.zeros( 40, np.int32 )
 
@@ -164 +202 @@
             
             # get basic information about the data file
-            #: region of interest (number of DRS slices read)
             self.nroi    = data_file.GetUInt('NROI')
-            #: number of pixels (should be 1440)
             self.npix    = data_file.GetUInt('NPIX')
-            #: number of events in the data run
             self.nevents = data_file.GetNumRows()
             
@@ -174 +209 @@
             self.event_id = c_ulong()
             self.trigger_type = c_ushort()
-            #: 1D array with raw data
             self.data  = np.zeros( self.npix * self.nroi, np.int16 ).reshape(self.npix ,self.nroi)
-            #: slice where drs readout started
             self.start_cells = np.zeros( self.npix, np.int16 )
-            #: time when the FAD was triggered, in some strange units...
             self.board_times = np.zeros( 40, np.int32 )
 
@@ -226 +258 @@
 
     def next(self):
-        """ used by __iter__ """
+        """ used by __iter__ 
+        
+            returns self.__dict__
+        """
         if self.use_CalFactFits:
             if self.data_file.GetCalEvent() == False:
@@ -250 +285 @@
 
     def next_event(self):
-        """ load the next event from disk and calibrate it
+        """ ---- DEPRICATED ----
+        
+            load the next event from disk and calibrate it
         """
         if self.use_CalFactFits:
@@ -259 +296 @@
 
     def calibrate_drs_amplitude(self):
-        """ perform the drs amplitude calibration of the event data
-        
+        """ --- DEPRICATED ---
+            
+            since the DRS calibration is done by the C++  class CalFactFits
+            
+            perform the drs amplitude calibration of the event data
         """
         # shortcuts
@@ -295 +335 @@
     def baseline_read_values(self, file, bsl_hist='bsl_sum/hplt_mean'):
         """
-        
         open ROOT file with baseline histogram and read baseline values
-        file       name of the root file
-        bsl_hist   path to the histogram containing the basline values
-
+        
+        *file* : name of the root file
+        
+        *bsl_hist* : path to the histogram containing the basline values
         """
 
@@ -317 +357 @@
     def baseline_correct(self):
         """ subtract baseline from the data
-
+        
+            DN 08.06.2011: I didn't use this function at all so far... don't know how well it works.
         """
         
@@ -325 +366 @@
     def info(self):
         """ print run information
-        
+            
+            not very well implemented ... we need more info here.
         """
         print 'data file:  ', self.data_file_name
@@ -334 +376 @@
 class RawDataFake( object ):
     """ raw data FAKE access similar to real RawData access
+    
+        DO NOT USE ... its not working
     """
 
@@ -419 +463 @@
 class SlowData( FactFits ):
     """ -Fact SlowData File-
-        A Python wrapper for the fits-class implemented in pyfits.h
+
+        A Python wrapper for the fits-class implemented in factfits.h
         provides easy access to the fits file meta data.
+
         * dictionary of file metadata - self.meta
         * dict of table metadata - self.columns
@@ -429 +475 @@
         """
         self.path = path
+        self.__module__ = 'pyfact'
         try:
             FactFits.__init__(self,path)
@@ -438 +485 @@
         self.columns = self._make_columns_dict()
         
-        self.treat_meta_dict()
+        self._treat_meta_dict()
         
         
@@ -533 +580 @@
 #                raise TypeError("I don't know how to stack "+col+". It is of type: "+str(type(self.dict[col])))
     
-    def register(self, input_str):
+    def register(self, col_name):
+        """ register for a column in the fits file
+        
+            after the call, this SlowData object will have a new member variable
+            self.col_name, if col_name is a key in self.colums
+            
+            the value will be updated after each call of next(), or while iterating over self.
+            NB: the initial value is zero(s)
+        
+            *col_name* : name of a key in self.columns, or 'all' to choose all.
+        """
         columns = self.columns
-        if input_str.lower() == 'all':
+        if col_name.lower() == 'all':
             for col in columns:
                 self._register(col)
         else:
             #check if colname is in columns:
-            if input_str not in columns:
+            if col_name not in columns:
                 error_msg = 'colname:'+ input_str +' is not a column in the binary table.\n'
                 error_msg+= 'possible colnames are\n'
@@ -630 +687 @@
         
     
-    def treat_meta_dict(self):
+    def _treat_meta_dict(self):
         """make 'interesting' meta information available like normal members.
             non interesting are:
@@ -699 +756 @@
 
     def next(self):
-        """ used by __iter__ """
+        """ use to iterate over the file
+        
+            do not forget to call register() before iterating over the file
+            call show() in order to find out, what parameters register() accepts.
+            or just call register('all') in case you are unsure.
+            
+            returns self
+        """
         # Here one might check, if looping makes any sense, and if not
         # one could stop looping or so...
@@ -725 +789 @@
 
     def show(self):
+        """
+        """
         pprint.pprint(self.dict)