Changeset 738 for trunk/doc

Timestamp:

11/24/05 14:57:27 (18 years ago)

Author:

mar637

Message:

added auto_quotient. updated commands to reflect version 1.2

File:

• trunk/doc/cookbook.tex (modified) (44 diffs)

trunk/doc/cookbook.tex

@@ -32 +32 @@
 %\section{Documentation Standards}
 
-%In most of the examples in this document, it has been assumed that the 
+%In most of the examples in this document, it has been assumed that the
 
 \section{Installation and Running}
 
-Currently there are installations running on Linux machines at 
+Currently there are installations running on Linux machines at
 
 \begin{itemize}
@@ -85 +85 @@
 \end{itemize}
 
-There can be many objects of the same type. Each object is referred to 
+There can be many objects of the same type. Each object is referred to
 by a variable name made by the user. The name of this variable is not
 important and can be set to whatever the user prefers (ie ``s'' and
@@ -145 +145 @@
   ASAP> scans.se<TAB>
 scans.set_cursor      scans.set_freqframe   scans.set_unit        scans.setpol
-scans.set_doppler     scans.set_instrument  scans.setbeam         
-scans.set_fluxunit    scans.set_restfreqs   scans.setif     
+scans.set_doppler     scans.set_instrument  scans.setbeam
+scans.set_fluxunit    scans.set_restfreqs   scans.setif
   ASAP> scans.set_in<TAB>
   ASAP> scans.set_instrument
@@ -196 +196 @@
 
 \begin{verbatim}
-  ASAP> help average_time 
+  ASAP> help average_time
 \end{verbatim}
 
@@ -203 +203 @@
 (control-d) to escape from this.
 
-\subsection{.asaprc}
+\subsection{Customisation - .asaprc}
 
 ASAP use an \cmd{.asaprc} file to control the user's preference of
@@ -218 +218 @@
   insitu                     : False
 
-  # default ouput format when saving scantable
+  # default output format when saving scantable
   scantable.save             : 'ASAP'
 
@@ -266 +266 @@
 
 The data are stored in columns (the length of a column is the number of
-rows/integrations of course).  
+rows/integrations of course).
 
 Two important columns are those that describe the frequency setup.  We mention
@@ -295 +295 @@
   ['s', 'scans', 'av', 's2', 'ss']
 
-  ASAP> del s2   
+  ASAP> del s2
   ASAP> del ss
 \end{verbatim}
@@ -310 +310 @@
 
   # Equivalent to brief summary function call
-  ASAP> print scan                     
+  ASAP> print scan
 \end{verbatim}
 
 Most of what the \cmd{summary} function  prints out is obvious. However,
-it also prints out the FreqIDs and RestFreqIDs to which we alluded above. 
+it also prints out the FreqIDs and RestFreqIDs to which we alluded above.
 These are the last column of the listing.
 
@@ -320 +320 @@
 the FreqIDs and RestFreqIDs that it encountered for each scan.  If you'd
 like to see what each FreqID actually means, then set the verbose
-argument to True and the frequency table will be listed at the end. 
+argument to True and the frequency table will be listed at the end.
 FreqID of 3 say, refers to the fourth row of the frequency table (ASAP
 is 0-relative). The list of rest frequencies, to which the RestFreqIDs
@@ -337 +337 @@
 
 Each scantable contains "state"; these are properties  applying to all
-of the data in the scantable.  
+of the data in the scantable.
 
 Examples are the selection of beam, IF and polarisation,  spectral unit
@@ -347 +347 @@
 The information describing the frequency setup for each integration
 is stored fundamentally in frequency in the reference frame
-of observation (E.g. TOPO).   
+of observation (E.g. TOPO).
 
 When required, this is converted to the desired reference frame
@@ -358 +358 @@
 scantable. All functions will (where relevant) work with the selected
 unit until this changes. This is mainly important for fitting (the fits
-can be computed in any of these units), plotting and mask creation. 
+can be computed in any of these units), plotting and mask creation.
 
 The velocity definition can be changed with the \cmd{set\_doppler}
@@ -390 +390 @@
 \begin{verbatim}
   # Select for specified source/IF
-  ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0)   
+  ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0)
 
   # Select for all sources and IFs
-  ASAP> scans.set_restfreqs(freqs=1.667359e9)                             
+  ASAP> scans.set_restfreqs(freqs=1.667359e9)
 \end{verbatim}
 
@@ -406 +406 @@
 \begin{verbatim}
   # Select for specified source/IF
-  ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0)   
+  ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0)
 
   # Select for all sources and IFs
-  ASAP> scans.set_restfreqs(freqs=1.667359e9)                             
+  ASAP> scans.set_restfreqs(freqs=1.667359e9)
 \end{verbatim}
 
@@ -423 +423 @@
 \end{verbatim}
 
-  
+
 
 \subsection{Data Selection}
 
 Data selection is currently fairly limited. This will be improved in
-the future. 
+the future.
 
 
@@ -482 +482 @@
   ASAP> scans.set_unit('channels')
   ASAP> msk = scans.create_mask([100,400],[600,800])
- 
+
   # Select velocity range for fitting
   ASAP> scans.set_unit('km/s')
@@ -495 +495 @@
 \begin{verbatim}
   ASAP> scans.set_unit('channels')
-  ASAP> msk = scans.create_mask([0,100],[900-1023], invert=True)   
+  ASAP> msk = scans.create_mask([0,100],[900-1023], invert=True)
 \end{verbatim}
 
@@ -535 +535 @@
 will have one row per scan).  The recognised input file formats are
 RPFITS, SDFITS (singledish fits), ASAP's scantable format and aips++
-MeasurementSet2 format. 
+MeasurementSet2 format.
 
 
@@ -557 +557 @@
 RPFITS files.  To read multiple RPFITS files, the old reader must be
 destroyed before the new file is opened.  However, multiple readers can
-be created and attached to SDFITS files. 
+be created and attached to SDFITS files.
 
 
@@ -564 +564 @@
 \begin{verbatim}
   ASAP> r = reader('2003-03-16_082048_t0002.rpf')
-  ASAP> r.summary 
+  ASAP> r.summary
   ASAP> scan = r.read()
   ASAP> s = r.read(range(100)) # To read in the first 100 integrations
@@ -580 +580 @@
 
 %How and when?
+\subsection{Auto quotient}
+Quotients can becomputed ``automatically''. This requires the data to have matching source/reference pairs or one refrence for multiple sources.
+
+\begin{verbatim}
+  ASAP> q = s.auto_quotient()
+\end{verbatim}
+
+If this is not sufficient the following alternative method can be used.
 
 \subsection{Separate reference and source observations}
@@ -654 +662 @@
 
 To make a baseline fit, you must first create a mask of channels to
-use in the baseline fit. 
+use in the baseline fit.
 
 \begin{verbatim}
  ASAP> msk = scans.create_mask([100,400],[600,900])
- ASAP> scans.poly_baseline(msk, 1) 
+ ASAP> scans.poly_baseline(msk, 1)
 \end{verbatim}
 
@@ -671 +679 @@
 emission and fits a polynomial baseline to that data. The user can use
 masks to fix the range of channels or velocity range for the fit as
-well as mark the band edge as invalid. 
+well as mark the band edge as invalid.
 
 Simple example
@@ -741 +749 @@
 
 \begin{verbatim}
-  ASAP> scans.scale(1.05, tsys=True) 
+  ASAP> scans.scale(1.05, tsys=True)
 \end{verbatim}
 
@@ -763 +771 @@
 
 As higher frequencies (particularly $>$20~GHz) it is important to make
-corrections for atmospheric opacity and gain-elevation effects. 
+corrections for atmospheric opacity and gain-elevation effects.
 
 Gain-elevation curves for some telescopes and frequencies are known to
@@ -826 +834 @@
 reference time then the scantables averaged. The simplest way of
 doing this is to allow ASAP to choose the reference time for the first
-scantable then using this time for the subsequent scantables. 
+scantable then using this time for the subsequent scantables.
 
 \begin{verbatim}
@@ -905 +913 @@
 \end{itemize}
 
-The default output format can be set in the users {\tt .asaprc} file. 
+The default output format can be set in the users {\tt .asaprc} file.
 Typical usages are:
 
@@ -1012 +1020 @@
 \item[Zoom] (the letter with the magnifying glass) lets you draw a
        rectangle around a region of interest then zooms in on that
-       region. Use the plot history to unzoom again.  
+       region. Use the plot history to unzoom again.
 
 \item[Save] (floppy disk). Save the plot as a postscript or .png file
@@ -1040 +1048 @@
 \end{verbatim}
 
-To save a hardcopy of the current plot, use the save function, e.g. 
+To save a hardcopy of the current plot, use the save function, e.g.
 
 \begin{verbatim}
@@ -1091 +1099 @@
   ASAP> f.set_scan(s,msk)
   ASAP> f.fit() # Fit using auto-estimates
-  # Set Peak, centre and fwhm for the second gaussian. 
+  # Set Peak, centre and fwhm for the second gaussian.
   # Force the centre to be fixed
   ASAP> f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
@@ -1105 +1113 @@
 \begin{verbatim}
   # Plot the residual
-  ASAP> f.plot(residual=True) 
+  ASAP> f.plot(residual=True)
 
   # Plot the first 2 componentsa
-  ASAP> f.plot(components=[0,1]) 
+  ASAP> f.plot(components=[0,1])
 
   # Plot the first and third component plus the model sum
@@ -1125 +1133 @@
 This will be saved to disk with the data, if the ``ASAP'' file format
 is selected. Multiple fits to the same data can be stored in the
-scantable. 
+scantable.
 
 The scantable function \cmd{get\_fit} can be used to retrieve the
@@ -1143 +1151 @@
 Conversions of linears to Stokes or Circular polarisations are done
 ``on-the-fly''. Leakage cannot be corrected for nor are these routines
-able to calibrate position angle offsets. 
+able to calibrate position angle offsets.
 
 \subsection{Simple Calibration}
@@ -1175 +1183 @@
 
   # Receiver was tracking 90 degrees rather than 0
-  ASAP> scans.rotate_linpolphase(90)  
+  ASAP> scans.rotate_linpolphase(90)
 \end{verbatim}
 
@@ -1215 +1223 @@
 
 \begin{verbatim}
+    [The scan container]
         scantable           - a container for integrations/scans
                               (can open asap/rpfits/sdfits and ms files)
@@ -1252 +1261 @@
             history         - print the history of the scantable
             get_fit         - get a fit which has been stored witnh the data
-            average_time    - return the (weighted) time average of a scan 
+            average_time    - return the (weighted) time average of a scan
                               or a list of scans
             average_pol     - average the polarisations together.
@@ -1258 +1267 @@
                               all polarisations will contain the
                               averaged spectrum.
+            auto_quotient   - return the on/off quotient with
+                              automatic detection of the on/off scans
             quotient        - return the on/off quotient
             scale           - return a scan scaled by a given factor
-            add             - return a scan with given value added 
+            add             - return a scan with given value added
             bin             - return a scan with binned channels
             resample        - return a scan with resampled channels
             smooth          - return the spectrally smoothed scan
             poly_baseline   - fit a polynomial baseline to all Beams/IFs/Pols
-            auto_poly_baseline - automatically fit a polynomial baseline 
+            auto_poly_baseline - automatically fit a polynomial baseline
             gain_el         - apply gain-elevation correction
             opacity         - apply opacity correction
@@ -1276 +1287 @@
      [Math] Mainly functions which operate on more than one scantable
 
-            average_time    - return the (weighted) time average 
+            average_time    - return the (weighted) time average
                               of a list of scans
             quotient        - return the on/off quotient
@@ -1314 +1325 @@
             set_abcissa     - specify a user label for the abcissa
             set_layout      - specify the multi-panel layout (rows,cols)
-            
+
     [Reading files]
         reader              - access rpfits/sdfits files
@@ -1330 +1341 @@
         execfile            - execute an asap script, e.g. execfile('myscript')
         list_rcparameters   - print out a list of possible values to be
-                              put into .asaprc file
+                              put into $HOME/.asaprc
         mask_and,mask_or,
         mask_not            - boolean operations on masks created with
                               scantable.create_mask
-        
+
     Note:
         How to use this with help:
@@ -1340 +1351 @@
         [xxx] is just a category
         Every 'sub-level' in this list should be replaces by a '.' Period when
-        using help 
+        using help
         Example:
             ASAP> help scantable # to get info on ths scantable
@@ -1376 +1387 @@
 \item Boost
 \item Matplotlib
-\item ipython/python
+\item python/ipython
 \end{itemize}
 
@@ -1389 +1400 @@
 
 \end{document}
-
-