Changeset 544 for trunk/doc


Ignore:
Timestamp:
03/08/05 15:48:43 (20 years ago)
Author:
phi196
Message:

more updates

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/cookbook.tex

    r538 r544  
    1 %% TODO
    2 %% Intro
    3 %% Fit saving
    4 
    51\documentclass[11pt]{article}
    62\usepackage{a4}
    … …  
    2824\section{Introduction}
    2925
     26ASAP is a single dish spectral line processing package currently being
     27developed by the ATNF. It is intended to process data from all ATNF
     28antennas, and can probably be used for other antnnas if they can
     29produce ``Single Dish FITS'' format. It is based on the AIPS++
     30package.
     31
    3032%\section{Documentation Standards}
    3133
    3234%In most of the examples in this document, it has been assumed that the
    3335
    34 \section{Installation and running}
     36\section{Installation and Running}
    3537
    3638Currently there are installations running on Linux machines at
    … …  
    4749\begin{verbatim}
    4850  > cd /my/data/directory
    49   > source /nfs/aips++/daily/aipsinit.csh  # Temporary measure
    5051  > asap
    5152\end{verbatim}
    5253
    53 This starts the asap. To quit, you need to type \verb+^+-d (control-d).
     54This starts the ASAP. To quit, you need to type \verb+^+-d
     55(control-d).
    5456
    5557\section{Interface}
    … …  
    7577
    7678\begin{itemize}
    77   \item[scantable] The data container (actual spectra and header information)
    78   \item[fitter] A tool used to fit functions to the spectral data
    79   \item[plotter] A tool used to plot the spectral line data
    80   \item[reader] A tool which can be used to read data from disks
     79  \item[\cmd{scantable}] The data container (actual spectra and header
     80    information)
     81  \item[\cmd{fitter}] A tool used to fit functions to the spectral data
     82  \item[\cmd{plotter}] A tool used to plot the spectral line data
     83  \item[\cmd{reader}] A tool which can be used to read data from disks
    8184    into a scantable object.
    8285\end{itemize}
    83 
    84 These are all described below.
    8586
    8687There can be many objects of the same type. Each object is referred to
    … …  
    9091consistent naming convention will help you a lot.
    9192
    92 \subsection{Member functions(functions)}
     93\subsection{Member Functions (functions)}
    9394
    9495Following the object oriented approach, objects have associated
    … …  
    102103
    103104Where \cmd{out} is the name of the returned variable (could be a new
    104 scantable object, or a vector of data, or a status return),  \cmd{object} is the
    105 object variable name (set by the user), \cmd{function} is the name of
    106 the member function and \cmd{arguments} is a list of arguments to the
    107 function. The arguments can be provided either though position or names.
    108 A mix of the two can be used.  E.g.
     105scantable object, or a vector of data, or a status return),
     106\cmd{object} is the object variable name (set by the user),
     107\cmd{function} is the name of the member function and \cmd{arguments}
     108is a list of arguments to the function. The arguments can be provided
     109either though position or \cmd{name=}.  A mix of the two can be used.
     110E.g.
    109111
    110112\begin{verbatim}
    … …  
    112114  ASAP> av = scans(mask=msk,weight='tsys')
    113115  ASAP> av = scans(msk,True)
    114   ASAP> scans.polybaseline(mask=msk, order=0, insitue=True)
     116  ASAP> scans.polybaseline(mask=msk, order=0, insitu=True)
    115117  ASAP> scans.polybaseline(msk,0,True)
    116118  ASAP> scans.polybaseline(mask, insitu=True)
    … …  
    119121\subsection{Global Functions}
    120122
    121 Some functions do not make sense to be implemented as member
    122 functions, typically functions which operate on more than one scantable
    123 (e.g. time averaging of many scans). These functions will always be
    124 referred to as global functions.
     123It does not make sense to implement some functions as member
     124functions, typically functions which operate on more than one
     125scantable (e.g. time averaging of many scans). These functions will
     126always be referred to as global functions.
    125127
    126128\subsection{Interactive environment}
    … …  
    132134
    133135Tab completion is enabled for all function names. If you type the
    134 first few letters of a function name, then type <TAB> the function
    135 name will be auto completed if it is un-ambiguous, or a list of
    136 possibilities will be given. Auto-completion works for the user
    137 object names as well as function names. It does not work for filenames,
    138 nor for function arguments.
     136first few letters of a function name, then type {\tt <TAB>} the
     137function name will be auto completed if it is un-ambiguous, or a list
     138of possibilities will be given. Auto-completion works for the user
     139object names as well as function names. It does not work for
     140filenames, nor for function arguments.
    139141
    140142Example
    … …  
    149151\end{verbatim}
    150152
     153\subsubsection{Leading Spaces}
     154
     155Python uses leading space to mark blocks of code. This means that it
     156you start a command line with a space, the command generally will
     157fail with an syntax error.
     158
    151159\subsubsection{Unix Interaction}
    152160
    153 Basic unix shell commands (pwd, ls, cd etc) can be issued from within
    154 ASAP. This allows the user to do things list look at files in the
    155 current directory. The shell command ``cd'' does work within ASAP
    156 allowing the user to change between data directories. Unix programs
    157 cannot be run this way, but the shell escape ``$!$'' can be used to run
    158 arbitrary programs. E.g.
     161Basic unix shell commands (\cmd{pwd}, \cmd{ls}, \cmd{cd} etc) can be
     162issued from within ASAP. This allows the user to do things like look
     163at files in the current directory. The shell command ``\cmd{cd}''
     164works within ASAP, allowing the user to change between data
     165directories. Unix programs cannot be run this way, but the shell
     166escape ``$!$'' can be used to run arbitrary programs. E.g.
    159167
    160168\begin{verbatim}
    … …  
    183191  ASAP> scans = scantable('mydata.asap')
    184192  ASAP> help scans.get_scan # Same as above
    185 
    186   ASAP> help average_time # Global functions just need their name
    187 
     193\end{verbatim}
     194
     195Global functions just need their name
     196
     197\begin{verbatim}
     198  ASAP> help average_time
    188199\end{verbatim}
    189200
    … …  
    194205\subsection{.asaprc}
    195206
    196 ASAP use a \cmd{.asaprc} file to control the users preferences of
     207ASAP use an \cmd{.asaprc} file to control the user's preference of
    197208default values for various functions arguments. This includes the
    198 defaults for aguments such as \cmd{insitu}, scantable \cmd{freqframe}
     209defaults for arguments such as \cmd{insitu}, scantable \cmd{freqframe}
    199210and the plotters \cmd{set\_mode} values. The help on individual
    200 functons says which agruments can be set default values from the
     211functions says which arguments can be set default values from the
    201212\cmd{.asaprc} file. To get a sample contents for the \cmd{.asaprc}
    202213file use then command \cmd{list\_rcparameters}.
    … …  
    297308  ASAP> scans.summary()                # Brief listing
    298309  ASAP> scans.summary(verbose=True)    # Include frequency information
    299   ASAP> print scan                     # Equivalent to brief summary function call
     310
     311  # Equivalent to brief summary function call
     312  ASAP> print scan                     
    300313\end{verbatim}
    301314
    … …  
    312325refer, is always listed.
    313326
    314 You can copy one scantable to another with the \cmd{copy} function.
    315 
    316 Example:
    317 
    318 \begin{verbatim}
    319   ASAP> scans = scantable('MyData.rpf')
    320   ASAP> scan2 = scans.copy()
    321 \end{verbatim}
     327%You can copy one scantable to another with the \cmd{copy} function.
     328
     329%Example:
     330
     331%\begin{verbatim}
     332%  ASAP> scans = scantable('MyData.rpf')
     333%  ASAP> scan2 = scans.copy()
     334%\end{verbatim}
    322335
    323336\subsection{State}
    … …  
    327340
    328341Examples are the selection of beam, IF and polarisation,  spectral unit
    329 (e.g. $km/s$) frequency reference frame (e.g. BARY) and velocity Doppler
     342(e.g. km/s) frequency reference frame (e.g. BARY) and velocity Doppler
    330343type (e.g. RADIO).
    331344
    … …  
    336349of observation (E.g. TOPO).   
    337350
    338 When required, this is converted to the desired reference frame (e.g. LSRK),
    339 Doppler (e.g. OPTICAL) and unit (e.g. $km/s$) on-the-fly.  For example,
    340 this is important when you are displaying the data or fitting to it.
     351When required, this is converted to the desired reference frame
     352(e.g. LSRK), Doppler (e.g. OPTICAL) and unit (e.g. km/s) on-the-fly.
     353This is important, for example, when you are displaying the data or
     354fitting to it.
    341355
    342356For units, the user has the choice of frequency, velocity or channel.
    … …  
    346360can be computed in any of these units), plotting and mask creation.
    347361
    348 The velocity Doppler can be changed with the \cmd{set\_doppler}
    349 function, and the frequency reference frame can be changed with the 
     362The velocity definition can be changed with the \cmd{set\_doppler}
     363function, and the frequency reference frame can be changed with the
    350364\cmd{set\_freqframe} function.
    351365
    … …  
    460474When setting the mask in velocity, the conversion from velocity
    461475to channels is based on the current cursor setting, selected row and
    462 selected frequency reference frame (**Currently first row only**)
    463 
     476selected frequency reference frame.
    464477
    465478Example :
    … …  
    468481  # Select channel range for baselining
    469482  ASAP> scans.set_unit('channels')
    470   ASAP> msk = q.create_mask([100,400],[600,800])
     483  ASAP> msk = scans.create_mask([100,400],[600,800])
    471484 
    472485  # Select velocity range for fitting
    473486  ASAP> scans.set_unit('km/s')
    474   ASAP> msk = q.create_mask([-30,-10])
    475 \end{verbatim}
    476 
    477 
    478 Sometimes it is more convenient to specify the channels to be
    479 excluded, rather included.  You can do this with the ``invert'' argument.
     487  ASAP> msk = scans.create_mask([-30,-10])
     488\end{verbatim}
     489
     490Sometimes it is more convenient to specify the channels to be
     491excluded, rather included.  You can do this with the ``invert''
     492argument.
    480493
    481494Example :
    482495\begin{verbatim}
    483496  ASAP> scans.set_unit('channels')
    484   ASAP> msk = q.create_mask([0,100],[900-1023], invert=True)   # Excludes specified channels
     497  ASAP> msk = scans.create_mask([0,100],[900-1023], invert=True)   
     498\end{verbatim}
     499
     500By default \cmd{create\_mask} uses the frequency setup of the first row
     501to convert velocities into a channel mask. If the rows in the data
     502cover different velocity ranges, the scantable row to use should be
     503specified:
     504
     505\begin{verbatim}
     506  ASAP> scans.set_unit('km/s')
     507  ASAP> msk = q.create_mask([-30,-10], row=5)
    485508\end{verbatim}
    486509
    … …  
    519542\begin{verbatim}
    520543  ASAP> scan = scantable('2004-11-23_1841-P484.rpf')
     544
     545  # Don't scan average the data
     546  ASAP> scan = scantable('2004-11-23_1841-P484.rpf', average=False)
    521547\end{verbatim}
    522548
    … …  
    547573
    548574In the following section, a simple data reduction to form a quotient
    549 spectrum of a single source is followed. In the following it has been
    550 assume that the \cmd{.asaprc} file has been used to set \cmd{insitu}
    551 to a default value or \cmd{True}.
     575spectrum of a single source is followed.  It has been assume that the
     576\cmd{.asaprc} file has {\em not} been used to change the \cmd{insitu}
     577default value from \cmd{True}.
    552578
    553579%\subsection{Editing}
    … …  
    587613(which is applied to all rows in \cmd{s}) or both scantables must have
    588614the same number of rows. By default the quotient spectra is calculated
    589 to preserve continuum emission. If you wish to remove continuum
     615to preserve continuum emission. If you wish to remove the continuum
    590616contribution, use the \cmd{preserve} argument:
    591617
    … …  
    603629\end{verbatim}
    604630
    605 If for some you want to average multiple sets of scan tables together you can:
     631If for some you want to average multiple sets of scantables together
     632you can:
    606633
    607634\begin{verbatim}
    … …  
    609636\end{verbatim}
    610637
    611 The default is not to use any weighting, which probably is not what
    612 you want. The alternative is to use variance or Tsys weighting.
     638The default is to use integration time weighting. The alternative is
     639to use none, variance , Tsys weighting or Tsys \& integration time.
     640
     641\begin{verbatim}
     642 ASAP> av = average_time(q, weight='tintsys')
     643\end{verbatim}
    613644
    614645To use variance based weighting, you need to supply a mask saying which
    … …  
    616647
    617648\begin{verbatim}
    618  ASAP> av = average_time(q, weight='tsys')
    619 
    620  ASAP> msk = q.create_mask([200,400],[600,800])
    621  ASAP> av = average_time(q, mask=msk, weight='var')
     649 ASAP> msk = scans.create_mask([200,400],[600,800])
     650 ASAP> av = average_time(scans, mask=msk, weight='var')
    622651\end{verbatim}
    623652
    … …  
    733762corrections for atmospheric opacity and gain-elevation effects.
    734763
    735 Gain-elevation curves for some telescopes and frequencies and known to
    736 ASAP (currently only for Tid at 20~GHz).  In these cases making
     764Gain-elevation curves for some telescopes and frequencies are known to
     765ASAP (currently only for Tidbinbilla at 20~GHz).  In these cases making
    737766gain-corrections is simple.  If the gain curve for your data is not
    738 known the user can supply either a gain polynomial or text file
     767known, the user can supply either a gain polynomial or text file
    739768tabulating gain factors at a range of elevations (see \cmd{help
    740 gain\_el}).
     769scantable.gain\_el}).
    741770
    742771Examples:
    … …  
    749778Opacity corrections can be made with the global function
    750779\cmd{opacity}. This should work on all telescopes as long as a
    751 measurement of the opacity factor, was made during the
    752 observation.
     780measurement of the opacity factor was made during the observation.
    753781
    754782\begin{verbatim}
    … …  
    758786Note that at 3~mm Mopra uses a paddle wheel for Tsys calibration,
    759787which takes opacity effects into account (to first order). ASAP
    760 opacity corrections should not then be used for Mopra 3-mm data.
     788opacity corrections should not be used for Mopra 3-mm data.
    761789
    762790\subsection{Frequency Frame Alignment}
    763791
    764 When time averaging a series of scans together, it is possible that the
    765 velocity scales are not exactly aligned.  This may be for many reasons
    766 such as not Doppler tracking the observations, errors in the Doppler
    767 tracking etc.  This mostly affects very long integrations or
    768 integrations averaged together from different days data.  Before
    769 averaging such data together, they should be frequency aligned using
    770 \cmd{freq\_align}. 
     792When time averaging a series of scans together, it is possible that
     793the velocity scales are not exactly aligned.  This may be for many
     794reasons such as not Doppler tracking the observations, errors in the
     795Doppler tracking etc.  This mostly affects very long integrations or
     796integrations averaged together from different days.  Before averaging
     797such data together, they should be frequency aligned using
     798\cmd{freq\_align}.
    771799
    772800E.g.:
    … …  
    836864\end{verbatim}
    837865
    838 as this just creates a reference to the original scantable. Any changes
    839 made to \cmd{ss} and also seen in \cmd{scans}. To duplicate a
     866as this just creates a reference to the original scantable. Any
     867changes made to \cmd{ss} are also seen in \cmd{scans}. To duplicate a
    840868scantable, use the copy function.
    841869
    … …  
    851879\begin{itemize}
    852880\item[ASAP] This is the internal format used for ASAP. It is the only
    853 format that allows the user to restore the data, fits etc. without
    854 loosing any information.   As mentioned before, the ASAP scantable
    855 is just an AIPS++ Table (a memory-based table).
    856 This function just converts it to a  disk-based
    857 Table.  You can the access that Table with the AIPS++ Table browser
    858 or any other AIPS++ tool.
    859 
    860 \item[SDFITS] The Single Dish FITS format. This format was
    861 designed to for interchange between packages, but few packages
    862 actually can read it.
     881  format that allows the user to restore the data, fits etc. without
     882  loosing any information.  As mentioned before, the ASAP scantable is
     883  an AIPS++ Table (a memory-based table).  This function just converts
     884  it to a disk-based Table.  You can the access that Table with the
     885  AIPS++ Table browser or any other AIPS++ tool.
     886
     887\item[SDFITS] The Single Dish FITS format. This format was designed to
     888  for interchange between packages, but few packages actually can read
     889  it.
    863890
    864891\item[FITS] This uses simple ``image'' fits to save the data, each row
    865 being written to a separate fits file. This format is suitable for
    866 importing the data into CLASS.
     892  being written to a separate fits file. This format is suitable for
     893  importing the data into CLASS.
    867894
    868895\item[ASCII] A simple text based format suitable for the user to
    … …  
    910937
    911938This will plot multiple polarisation within each plot panel and each
    912 scanrow in a separate panel.
     939scan row in a separate panel.
    913940
    914941Other possibilities include:
    … …  
    937964multibeam or multi IF data. The plotter \cmd{set\_cursor} function is
    938965used to select a subset of the data. The arguments \cmd{row},
    939 \cmd{beam} and \cmd{IF} all accept a vector if indices corresponding
    940 to tow, beam or IF selection. Only the selected data will be plotted.
    941 So select on polarisation, see section~\ref{sec:polplot}.
     966\cmd{beam} and \cmd{IF} all accept a vector of indices corresponding
     967to row, beam or IF selection. Only the selected data will be plotted.
     968To select on polarisation, see section~\ref{sec:polplot}.
    942969
    943970Examples:
    … …  
    957984\end{verbatim}
    958985
    959 \subsection{Plot control}
     986Note that the plotter cursor selection is independent of the scantable
     987cursor.
     988
     989\subsection{Plot Control}
    960990
    961991The plotter window has a row of buttons on the lower left. These can
    … …  
    9851015\end{itemize}
    9861016
    987 \subsection{Plot selection}
    988 
    9891017\subsection{Other control}
    9901018
    … …  
    10001028  ASAP> plotter.plot(scans)
    10011029  ASAP> plotter.set_range(-150,-50)
    1002   ASAP> plotter.set_range()
     1030  ASAP> plotter.set_range() # To reset
     1031\end{verbatim}
     1032
     1033Both the range of the ``x'' and ``y'' axis can be set at once, if desired:
     1034
     1035\begin{verbatim}
     1036  ASAP> plotter.set_range(-10,30,-1,6.6)
    10031037\end{verbatim}
    10041038
    … …  
    10461080\end{verbatim}
    10471081
    1048 If you wish, the initial parameter guesses can be specified specific
    1049 parameters can be fixed:
     1082If you wish, the initial parameter guesses can be specified and
     1083specific parameters can be fixed:
    10501084
    10511085\begin{verbatim}
    … …  
    10771111\end{verbatim}
    10781112
     1113\subsection{Fit saving}
     1114
     1115One you are happy with your fit, it is possible to store it as part of
     1116the scantable.
     1117
     1118\begin{verbatim}
     1119  ASAP> f.storefit()
     1120\end{verbatim}
     1121
     1122This will be saved to disk with the data, if the ``ASAP'' file format
     1123is selected. Multiple fits to the same data can be stored in the
     1124scantable.
     1125
     1126The scantable function \cmd{get\_fit} can be used to retrieve the
     1127stored fits. Currently the fit parameters are just printed to the
     1128screen.
     1129
     1130\begin{verbatim}
     1131  ASAP> scans.get_fit(4) # Print fits for row 4
     1132\end{verbatim}
     1133
    10791134\section{Polarisation}
    10801135
    … …  
    10841139
    10851140Conversions of linears to Stokes or Circular polarisations are done
    1086 ``on-the-fly''. Leakage cannot be corrected for nor are there routines
     1141``on-the-fly''. Leakage cannot be corrected for nor are these routines
    10871142able to calibrate position angle offsets.
    10881143
    … …  
    10931148
    10941149It is possible that there is a phase offset between polarisation which
    1095 will effect the phase of the cross polarisation
    1096 correlation. \cmd{rotate\_xyphase} can be used to correct for this
    1097 error. The user must know how to determine the size of the phase
    1098 offset.
     1150will effect the phase of the cross polarisation correlation, and so
     1151give rise to spurious polarisation. \cmd{rotate\_xyphase} can be used
     1152to correct for this error. The user must know how to determine the
     1153size of the phase offset themselves.
    10991154
    11001155\begin{verbatim}
    … …  
    11541209
    11551210\begin{verbatim}
    1156 
    1157     [The scan container]
    11581211        scantable           - a container for integrations/scans
    11591212                              (can open asap/rpfits/sdfits and ms files)
    … …  
    11921245            nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
    11931246            history         - print the history of the scantable
    1194 
    1195             average_time    - return the (weighted) time average of a scan
     1247            get_fit         - get a fit which has been stored witnh the data
     1248            average_time    - return the (weighted) time average of a scan 
    11961249                              or a list of scans
    11971250            average_pol     - average the polarisations together.
    … …  
    12011254            quotient        - return the on/off quotient
    12021255            scale           - return a scan scaled by a given factor
    1203             add             - return a scan with given value added
     1256            add             - return a scan with given value added 
    12041257            bin             - return a scan with binned channels
    12051258            resample        - return a scan with resampled channels
    … …  
    12161269     [Math] Mainly functions which operate on more than one scantable
    12171270
    1218             average_time    - return the (weighted) time average
     1271            average_time    - return the (weighted) time average 
    12191272                              of a list of scans
    12201273            quotient        - return the on/off quotient
    1221             simple_math     - simple mathematical operations on two scantables,                              'add', 'sub', 'mul', 'div'
     1274            simple_math     - simple mathematical operations on two scantables,
     1275                              'add', 'sub', 'mul', 'div'
    12221276     [Fitting]
    12231277        fitter
    … …  
    12271281                              commited.
    12281282            fit             - execute the actual fitting process
     1283            store_fit       - store the fit paramaters in the data (scantable)
    12291284            get_chi2        - get the Chi^2
    12301285            set_scan        - set the scantable to be fit
    … …  
    12321287            set_parameters  - set the parameters for the function(s), and
    12331288                              set if they should be held fixed during fitting
    1234             set_gauss_parameters - same as above but specialised for individual                                   gaussian components
     1289            set_gauss_parameters - same as above but specialised for individual
     1290                                   gaussian components
    12351291            get_parameters  - get the fitted parameters
    12361292            plot            - plot the resulting fit and/or components and
    … …  
    12441300                              what is to be plotted 'colour stacked'
    12451301                              and what 'panelled'
    1246             set_range       - set the abcissa 'zoom' range
     1302            set_cursor      - only plot a selected part of the data
     1303            set_range       - set a 'zoom' window
    12471304            set_legend      - specify user labels for the legend indeces
    12481305            set_title       - specify user labels for the panel indeces
    … …  
    12501307            set_abcissa     - specify a user label for the abcissa
    12511308            set_layout      - specify the multi-panel layout (rows,cols)
    1252 
     1309           
    12531310    [Reading files]
    12541311        reader              - access rpfits/sdfits files
    … …  
    12651322        help                - print help for one of the listed functions
    12661323        execfile            - execute an asap script, e.g. execfile('myscript')
    1267         list_rcparameters   - print out a list of possible values to be
    1268                               put into \$HOME/.asaprc
     1324        list_rcparameters   - print out a list of possible values to be
     1325                              put into .asaprc file
    12691326        mask_and,mask_or,
    12701327        mask_not            - boolean operations on masks created with
    12711328                              scantable.create_mask
    1272 
     1329       
    12731330    Note:
    12741331        How to use this with help:
    12751332                                         # function 'summary'
    12761333        [xxx] is just a category
    1277         Every 'sub-level' in this list should be replaces by a '.' Period when        using help
     1334        Every 'sub-level' in this list should be replaces by a '.' Period when
     1335        using help
    12781336        Example:
    12791337            ASAP> help scantable # to get info on ths scantable
    12801338            ASAP> help scantable.summary # to get help on the scantable's
    12811339            ASAP> help average_time
     1340
     1341\end{verbatim}
     1342
     1343\section{Scantable Mathematics}
     1344
     1345It is possible to to simple mathematics directly on scantables from
     1346the command line using the \cmd{+, -, *, /} operators as well as their
     1347cousins \cmd{+=, -= *=, /=}. This works between two scantables or a
     1348scantable and a float. (Note that it does not work for integers).
     1349
     1350\begin{verbatim}
     1351  ASAP> sum = scan1+scan2
     1352  ASAP> scan2 = scan1+2.0
     1353  ASAP> scan *= 1.05
    12821354\end{verbatim}
    12831355
Note: See TracChangeset for help on using the changeset viewer.