Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/userguide.tex

    r1217 r1347  
    4848package.
    4949
    50 This userguide is being updated for the ASAP 2.1. Please report any
     50This userguide has been updated for the ASAP 2.1. Please report any
    5151mistakes you find.
    5252
    … …  
    6565
    6666{\em Note. ASAP2.1 only runs on ATNF Linux machines which have been
    67 updated to Debian Sarge and are using the ``DEBIANsarge''
     67updated to Debian Sarge and are using the ``DEBIANSarge''
    6868/usr/local. If your favourite machine has not been upgraded, send a
    69 request your your friendly IT support.}
     69request to your friendly IT support. At the time of writing asap 2.1
     70does not run on hydra, bourbon or kaputar.}
    7071
    7172\index{Running}To start asap log onto one of these Linux hosts and enter
    … …  
    7677\end{verbatim}
    7778
    78 This starts the ASAP. To quit, you need to type \verb+^+-d
    79 (control-d) or type \cmd{\%Exit}.
     79This starts ASAP. To quit, you need to type \verb+^+-d (control-d) or
     80type \cmd{\%Exit}.
    8081
    8182\section{Interface}
    … …  
    9899main objects are used :
    99100
    100 \begin{itemize}
    101   \item[\cmd{scantable}] The data container (actual spectra and header
    102     information)
    103   \item[\cmd{selector}] Allows the user to select a subsection of the
    104     data, such as a specified or range of beam numbers, IFs, etc.
    105   \item[\cmd{plotter}] A tool used to plot the spectral line data
    106   \item[\cmd{fitter}] A tool used to fit functions to the spectral data
    107   \item[\cmd{reader}] A tool which can be used to read data from disks
    108     into a scantable object (advanced use).
    109 \end{itemize}
     101\begin{tabular}{ll}
     102
     103\cmd{scantable} & \parbox[t]{0.7\textwidth}{The data container (actual
     104  spectra and header information)} \\
     105\cmd{selector} & \parbox[t]{0.80\textwidth}{Allows the user to select
     106  a subsection of the data, such as a specified or range of beam
     107  numbers, IFs, etc.} \\
     108\cmd{plotter} & A tool used to plot the spectral line data \\
     109\cmd{fitter} & A tool used to fit functions to the spectral data \\
     110\cmd{reader} & \parbox[t]{0.8\textwidth}{A tool which can be used to
     111    read data from disks into a scantable object (advanced use).}\\
     112\end{tabular}
    110113
    111114There can be many objects of the same type. Each object is referred to
    … …  
    124127functions using the syntax:
    125128\begin{verbatim}
    126   ASAP> out = object.function(arguments)
     129  ASAP>out = object.function(arguments)
    127130\end{verbatim}
    128131
    … …  
    136139
    137140\begin{verbatim}
    138   ASAP> av = scans.average_time(msk,weight='tsys')
    139   ASAP> av = scans.average_time(mask=msk,weight='tsys')
    140   ASAP> av = scans.average_time(msk,tsys)
    141   ASAP> scans.poly_baseline(mask=msk, order=0, insitu=True)
    142   ASAP> scans.poly_baseline(msk,0,True)
    143   ASAP> scans.poly_baseline(mask, insitu=True)
     141  ASAP>av = scans.average_time(msk,weight='tsys')
     142  ASAP>av = scans.average_time(mask=msk,weight='tsys')
     143  ASAP>av = scans.average_time(msk,tsys)
     144  ASAP>scans.poly_baseline(mask=msk, order=0, insitu=True)
     145  ASAP>scans.poly_baseline(msk,0,True)
     146  ASAP>scans.poly_baseline(mask, insitu=True)
    144147\end{verbatim}
    145148
    … …  
    168171Example
    169172\begin{verbatim}
    170   ASAP> scans = scantable('MyData.rpf')
    171   ASAP> scans.se<TAB>
    172   ASAP> scans.set_in<TAB>
     173  ASAP>scans = scantable('MyData.rpf')
     174  ASAP>scans.se<TAB>
     175  ASAP>scans.set_in<TAB>
    173176scans.set_cursor      scans.set_freqframe   scans.set_selection
    174177scans.set_doppler     scans.set_instrument  scans.set_unit
    175178scans.set_fluxunit    scans.set_restfreqs
    176179
    177   ASAP> scans.set_instrument()
     180  ASAP>scans.set_instrument()
    178181\end{verbatim}
    179182
    … …  
    204207
    205208\begin{verbatim}
    206   ASAP> pwd
    207   ASAP> ls
    208   ASAP> cd /my/data/directory
    209   ASAP> ! mozilla&
     209  ASAP>pwd
     210  ASAP>ls
     211  ASAP>cd /my/data/directory
     212  ASAP>! mozilla&
    210213\end{verbatim}
    211214
    … …  
    216219
    217220\begin{verbatim}
    218   ASAP> commands()
     221  ASAP>commands()
    219222\end{verbatim}
    220223
    … …  
    223226
    224227\begin{verbatim}
    225   ASAP> help scantable.get_scan # or help(scantable.get_scan)
    226   ASAP> help scantable.stats
    227   ASAP> help plotter.plot
    228   ASAP> help fitter.plot
    229 
    230   ASAP> scans = scantable('mydata.asap')
    231   ASAP> help scans.get_scan # Same as above
     228  ASAP>help scantable.get_scan # or help(scantable.get_scan)
     229  ASAP>help scantable.stats
     230  ASAP>help plotter.plot
     231  ASAP>help fitter.plot
     232
     233  ASAP>scans = scantable('mydata.asap')
     234  ASAP>help scans.get_scan # Same as above
    232235\end{verbatim}
    233236
    … …  
    235238
    236239\begin{verbatim}
    237   ASAP> help average_time
     240  ASAP>help average_time
    238241\end{verbatim}
    239242
    … …  
    285288normally contain 13 beams, 1 IF and 2 polarisations, Parkes
    286289methanol-multibeam data would contain 7 beams, 2 IFs and 2
    287 polarisations while the Mopra 8-GHz MOPDS filterbank will produce one
     290polarisations while the Mopra 8-GHz MOPS filterbank will produce one
    288291beam, many IFs, and 2-4 polarisations.
    289292
    290293All of the combinations of Beams/IFs an Polarisations are
    291 contained in seperate rows. These rows are grouped in cycles (same time stamp).
     294contained in separate rows. These rows are grouped in cycles (same time stamp).
    292295
    293296A collection of cycles for one source is termed a scan (and each scan
    294297has a unique numeric identifier, the SCANNO). A scantable is then a
    295298collection of one or more scans. If you have scan-averaged your data
    296 in time, i.e. you have averegaed all cycles within a scan, then each
     299in time, i.e. you have averaged all cycles within a scan, then each
    297300scan would hold just one (averaged) integration.
    298301
    … …  
    302305changed via the {\tt .asaprc} resource file.
    303306
    304 For example a Mopra scan with a  4s intergration time, two IFs and
     307For example a Mopra scan with a  4s integration time, two IFs and
    305308dual polarisations has two (2s) cycles.
    306309\begin{verbatim}
    … …  
    345348
    346349\begin{verbatim}
    347   ASAP> scans = scantable('MyData.rpf')
    348   ASAP> scans.summary()                # Brief listing
     350  ASAP>scans = scantable('MyData.rpf')
     351  ASAP>scans.summary()                # Brief listing
    349352
    350353  # Equivalent to brief summary function call
    351   ASAP> print scan
     354  ASAP>print scan
    352355\end{verbatim}
    353356
    … …  
    356359of summary is redirected into your current pager specified by the
    357360\$PAGER environment variable. If you find the screen is reset to the
    358 original state when summary is finished (ie the output from summary
     361original state when summary is finished (i.e. the output from summary
    359362disappears), you may need to set the \$LESS environment variable to
    360363include the \cmd{-X} option.
    … …  
    382385The common selection functions are:
    383386
    384 \begin{itemize}
    385 
    386 \item[\cmd{set\_beams}] Select beams by index number
    387 \item[\cmd{set\_ifs}] Select ifs by index number
    388 \item[\cmd{set\_name}] Select by source name. Can contain ``*'' as a
    389 wildcard, e.g. ``Orion*\_R''.
    390 \item[\cmd{set\_ifs}] Select IFs by index number
    391 \item[\cmd{set\_polarisation}] Select by polarisation index or
    392 name. If polarisation names are given, the data will be on-the-fly
    393 converted (for example from linears to Stokes).
    394 \item[\cmd{set\_query}] Set query directly. For power users only!
    395 \item[\cmd{set\_tsys}] Select data based on Tsys. Also example of user
    396 definable query.
    397 \item[\cmd{reset}] Reset the selection to include all spectra.
    398 
     387\begin{tabular}{ll}
     388
     389\cmd{set\_beams} & Select beams by index number \\
     390\cmd{set\_ifs} & Select ifs by index number \\
     391\cmd{set\_name} & Select by source name. Can contain ``*'' as a
     392wildcard, e.g. ``Orion*\_R''. \\
     393\cmd{set\_ifs} & Select IFs by index number \\
     394
     395\cmd{set\_polarisation} & \parbox[t]{0.73\textwidth}{Select by
     396polarisation index or name. If polarisation names are given, the data
     397will be on-the-fly onverted (for example from linears to Stokes). }\\
     398
     399\cmd{set\_query} & Set query directly. For power users only! \\
     400\cmd{set\_tsys} & Select data based on Tsys. Also example of user
     401definable query. \\
     402\cmd{reset} & Reset the selection to include all spectra. \\
     403
     404\end{tabular}
    399405
    400406Note that all indices are zero based.
    … …  
    403409
    404410\begin{verbatim}
    405   ASAP> selection = selector()         # Create selection object
    406   ASAP> selection.set_ifs(0)           # Just select the first IF
    407   ASAP> scans.set_selection(selection) # Apply the selection
    408   ASAP> print scans                    # Will just show the first IF
    409 
    410   ASAP> selection.set_ifs([0,1])       # Select the first two IFs
    411   ASAP> selection.set_beams([1,3,5])   # Also select three of the beams
    412   ASAP> scans.set_selection(selection) # Apply the selection
    413 
    414   ASAP> selection.set_name('G308*')     # Select by source name
    415 
    416   ASAP> selection.reset()              # Turn off selection
    417   ASAP> scans.set_selection(selection) # Apply the reset selection
    418 
    419 \end{verbatim}
    420 
    421 \end{itemize}
     411  ASAP>selection = selector()         # Create selection object
     412  ASAP>selection.set_ifs(0)           # Just select the first IF
     413  ASAP>scans.set_selection(selection) # Apply the selection
     414  ASAP>print scans                    # Will just show the first IF
     415
     416  ASAP>selection.set_ifs([0,1])       # Select the first two IFs
     417  ASAP>selection.set_beams([1,3,5])   # Also select three of the beams
     418  ASAP>scans.set_selection(selection) # Apply the selection
     419
     420  ASAP>selection.set_name('G308*')     # Select by source name
     421
     422  ASAP>selection.reset()              # Turn off selection
     423  ASAP>scans.set_selection(selection) # Apply the reset selection
     424
     425\end{verbatim}
    422426
    423427\subsection{State}
    … …  
    455459
    456460\begin{verbatim}
    457   ASAP> scans = scantable('2004-11-23_1841-P484.rpf') # Read in the data
    458   ASAP> scans.set_freqframe('LSRK')  # Use the LSR velocity frame
    459   ASAP> scans.set_unit('km/s')        # Use velocity for plots etc from now on
    460   ASAP> scans.set_doppler('OPTICAL')  # Use the optical velocity convention
    461   ASAP> scans.set_unit('MHz')         # Use frequency in MHz from now on
     461  ASAP>scans = scantable('2004-11-23_1841-P484.rpf') # Read in the data
     462  ASAP>scans.set_freqframe('LSRK')  # Use the LSR velocity frame
     463  ASAP>scans.set_unit('km/s')        # Use velocity for plots etc from now on
     464  ASAP>scans.set_doppler('OPTICAL')  # Use the optical velocity convention
     465  ASAP>scans.set_unit('MHz')         # Use frequency in MHz from now on
    462466\end{verbatim}
    463467
    … …  
    479483\begin{verbatim}
    480484  # Set all IFs
    481   ASAP> scans.set_restfreqs(freqs=1.667359e9)
     485  ASAP>scans.set_restfreqs(freqs=1.667359e9)
    482486\end{verbatim}
    483487
    … …  
    489493\begin{verbatim}
    490494  # Set rest frequency for all IFs
    491   ASAP> scans.set_restfreqs(freqs=[1.6654018e9,1.667359e9,])
    492 
    493 \end{verbatim}
    494 
    495 {\em Currently the following is not implemented
    496 
    497 In both of the above modes, you can also specify the rest frequencies via
    498 names in a known list rather than by their values.
    499 
    500 Examples:
    501 
    502 \begin{verbatim}
    503   ASAP> scans.set_restfreqs(freqs=['OH1665','OH1667'])
    504 \end{verbatim}
    505 }
     495  ASAP>scans.set_restfreqs(freqs=[1.6654018e9,1.667359e9,])
     496
     497\end{verbatim}
     498
     499A predetermined ``line catalog'' can be used to set the rest
     500frequency. See section \S \ref{sec:linecat}.
     501
    506502
    507503\subsubsection{Masks}
    … …  
    532528
    533529  # Select channel range for baselining
    534   ASAP> scans.set_unit('channels')
    535   ASAP> msk = scans.create_mask([100,400],[600,800])
     530  ASAP>scans.set_unit('channels')
     531  ASAP>msk = scans.create_mask([100,400],[600,800])
    536532
    537533  # Select velocity range for fitting
    538   ASAP> scans.set_unit('km/s')
    539   ASAP> msk = scans.create_mask([-30,-10])
     534  ASAP>scans.set_unit('km/s')
     535  ASAP>msk = scans.create_mask([-30,-10])
    540536\end{verbatim}
    541537
    … …  
    546542Example :
    547543\begin{verbatim}
    548   ASAP> scans.set_unit('channels')
    549   ASAP> msk = scans.create_mask([0,100],[900-1023], invert=True)
     544  ASAP>scans.set_unit('channels')
     545  ASAP>msk = scans.create_mask([0,100],[900-1023], invert=True)
    550546\end{verbatim}
    551547
    … …  
    556552
    557553\begin{verbatim}
    558   ASAP> scans.set_unit('km/s')
    559   ASAP> msk = q.create_mask([-30,-10], row=5)
     554  ASAP>scans.set_unit('km/s')
     555  ASAP>msk = q.create_mask([-30,-10], row=5)
    560556\end{verbatim}
    561557
    … …  
    566562
    567563\begin{verbatim}
    568   ASAP> scans.set_unit('channels')
    569   ASAP> msk1 = q.create_mask([0,100],[511,511],[900,1023],invert=True)
    570   ASAP> scans.set_unit('km/s')
    571   ASAP> msk2 = q.create_mask([-20,-10],invert=True)
    572 
    573   ASAP> mask = msk1 and msk2
     564  ASAP>scans.set_unit('channels')
     565  ASAP>msk1 = q.create_mask([0,100],[511,511],[900,1023],invert=True)
     566  ASAP>scans.set_unit('km/s')
     567  ASAP>msk2 = q.create_mask([-20,-10],invert=True)
     568
     569  ASAP>mask = msk1 and msk2
    574570\end{verbatim}
    575571
    … …  
    585581
    586582\begin{verbatim}
    587   ASAP> list_scans()
     583  ASAP>list_scans()
    588584  The user created scantables are:
    589585  ['s', 'scans', 'av', 's2', 'ss']
    590586
    591   ASAP> del s2
    592   ASAP> del ss
     587  ASAP>del s2
     588  ASAP>del ss
    593589\end{verbatim}
    594590
    … …  
    611607
    612608\begin{verbatim}
    613   ASAP> scan = scantable('2004-11-23_1841-P484.rpf')
     609  ASAP>scan = scantable('2004-11-23_1841-P484.rpf')
    614610
    615611  # Don't scan average the data
    616   ASAP> scan = scantable('2004-11-23_1841-P484.rpf', average=False)
     612  ASAP>scan = scantable('2004-11-23_1841-P484.rpf', average=False)
    617613\end{verbatim}
    618614
    … …  
    634630
    635631\begin{verbatim}
    636   ASAP> r = reader('2003-03-16_082048_t0002.rpf')
    637   ASAP> r.summary()
    638   ASAP> scan = r.read()
    639   ASAP> del r
     632  ASAP>r = reader('2003-03-16_082048_t0002.rpf')
     633  ASAP>r.summary()
     634  ASAP>scan = r.read()
     635  ASAP>del r
    640636\end{verbatim}
    641637
    … …  
    652648reference for multiple sources. Auto quotient assumes reference scans
    653649have a trailing ``\_R'' in the source name for data from Parkes and
    654 Mopra, and a trailing ``e'' or ``w'' for data fro, Tidbinbilla.
    655 
    656 \begin{verbatim}
    657   ASAP> q = s.auto_quotient()
     650Mopra, and a trailing ``e'' or ``w'' for data from Tidbinbilla.
     651This functions has two \cmd{mode}s. \cmd{paired} (the deafault), which assumes
     652matching adjacent pairs of source/reference scans and \cmd{time}, which finds
     653the closest reference scan in time.
     654
     655\begin{verbatim}
     656  ASAP>q = s.auto_quotient()
    658657\end{verbatim}
    659658
    … …  
    663662
    664663\begin{verbatim}
    665  ASAP> q = s.auto_quotient(preserve=True)
     664 ASAP>q = s.auto_quotient(preserve=True)
    666665\end{verbatim}
    667666
    … …  
    678677For Mopra and Parkes data:
    679678\begin{verbatim}
    680   ASAP> r = scans.get_scan('*_R')
    681   ASAP> s = scans.get_scan('*_S')
     679  ASAP>r = scans.get_scan('*_R')
     680  ASAP>s = scans.get_scan('*^_R')
    682681\end{verbatim}
    683682
    684683For Tidbinbilla data
    685684\begin{verbatim}
    686   ASAP> r = scans.get_scan('*_[ew]')
    687   ASAP> s = scans.get_scan('*_[^ew]')
    688 \end{verbatim}
    689 
    690 \subsection{Make the quotient spectra}
    691 
    692 Use the quotient function
    693 
    694 \begin{verbatim}
    695   ASAP> q = s.quotient(r)
    696 \end{verbatim}
    697 
    698 This uses the rows in scantable \cmd{r} as reference spectra for the
    699 rows in scantable \cmd{s}. Scantable \cmd{r} must have either 1 row
    700 (which is applied to all rows in \cmd{s}) or both scantables must have
    701 the same number of rows.
     685  ASAP>r = scans.get_scan('*_[ew]')
     686  ASAP>s = scans.get_scan('*_[^ew]')
     687\end{verbatim}
    702688
    703689\subsection{Time average separate scans}
    … …  
    708694
    709695\begin{verbatim}
    710  ASAP> av = q.average_time()
     696 ASAP>av = q.average_time()
    711697\end{verbatim}
    712698
    … …  
    715701
    716702\begin{verbatim}
    717  ASAP> av = average_time(q1, q2, q3)
     703 ASAP>av = average_time(q1, q2, q3)
    718704\end{verbatim}
    719705
    … …  
    723709
    724710\begin{verbatim}
    725  ASAP> av = average_time(q, weight='tintsys')
     711 ASAP>av = average_time(q, weight='tintsys')
    726712\end{verbatim}
    727713
    … …  
    730716
    731717\begin{verbatim}
    732  ASAP> msk = scans.create_mask([200,400],[600,800])
    733  ASAP> av = average_time(scans, mask=msk, weight='var')
     718 ASAP>msk = scans.create_mask([200,400],[600,800])
     719 ASAP>av = average_time(scans, mask=msk, weight='var')
    734720\end{verbatim}
    735721
    736722If you have not observed your data with Doppler tracking (or run
    737 \cmd{freq\_align} explicitally) you should align the data in frequency
     723\cmd{freq\_align} explicitly) you should align the data in frequency
    738724before averaging.
    739725
    740726\begin{verbatim}
    741  ASAP> av = scans.average_time(align=True)
     727 ASAP>av = scans.average_time(align=True)
    742728\end{verbatim}
    743729
    … …  
    752738
    753739\begin{verbatim}
    754  ASAP> msk = scans.create_mask([100,400],[600,900])
    755  ASAP> scans.poly_baseline(msk, order=1)
     740 ASAP>msk = scans.create_mask([100,400],[600,900])
     741 ASAP>scans.poly_baseline(msk, order=1)
    756742\end{verbatim}
    757743
    … …  
    771757
    772758\begin{verbatim}
    773   ASAP> scans.auto_poly_baseline(order=2,threshold=5)
     759  ASAP>scans.auto_poly_baseline(order=2,threshold=5)
    774760\end{verbatim}
    775761
    … …  
    786772\begin{verbatim}
    787773  # Don't try and fit the edge of the bandpass which is noisier
    788   ASAP> scans.auto_poly_baseline(edge=(500,450),order=3,threshold=3)
     774  ASAP>scans.auto_poly_baseline(edge=(500,450),order=3,threshold=3)
    789775
    790776  # Only fit a given region around the line
    791   ASAP> scans.set_unit('km/s')
    792   ASAP> msk = scans.create_mask([-60,-20])
    793   ASAP> scans.auto_poly_baseline(mask=msk,order=3,threshold=3)
     777  ASAP>scans.set_unit('km/s')
     778  ASAP>msk = scans.create_mask([-60,-20])
     779  ASAP>scans.auto_poly_baseline(mask=msk,order=3,threshold=3)
    794780
    795781\end{verbatim}
    … …  
    801787
    802788\begin{verbatim}
    803  ASAP> scans.average_pol()
     789 ASAP>scans.average_pol()
    804790\end{verbatim}
    805791
    … …  
    823809
    824810\begin{verbatim}
    825   ASAP> scans = scantable('2004-11-23_1841-P484.rpf', unit='Jy')
     811  ASAP>scans = scantable('2004-11-23_1841-P484.rpf', unit='Jy')
    826812  # Or in two steps
    827   ASAP> scans = scantable('2004-11-23_1841-P484.rpf')
    828   ASAP> scans.set_fluxunit('Jy')
     813  ASAP>scans = scantable('2004-11-23_1841-P484.rpf')
     814  ASAP>scans.set_fluxunit('Jy')
    829815\end{verbatim}
    830816
    … …  
    840826
    841827\begin{verbatim}
    842   ASAP> scans = scantable('2004-11-23_1841-P484.rpf')
    843   ASAP> scans.set_feedtype('circular')
     828  ASAP>scans = scantable('2004-11-23_1841-P484.rpf')
     829  ASAP>scans.set_feedtype('circular')
    844830\end{verbatim}
    845831
    … …  
    852838
    853839\begin{verbatim}
    854   ASAP> scans.scale(1.05, tsys=True)
     840  ASAP>scans.scale(1.05, tsys=True)
    855841\end{verbatim}
    856842
    … …  
    866852
    867853\begin{verbatim}
    868   ASAP> scans.convert_flux()               # If efficency known
    869   ASAP> scans.convert_flux(eta=0.48)       # If telescope diameter known
    870   ASAP> scans.convert_flux(eta=0.48,d=35)  # Unknown telescope
    871   ASAP> scans.convert_flux(jypk=15)        # Alternative
     854  ASAP>scans.convert_flux()               # If efficency known
     855  ASAP>scans.convert_flux(eta=0.48)       # If telescope diameter known
     856  ASAP>scans.convert_flux(eta=0.48,d=35)  # Unknown telescope
     857  ASAP>scans.convert_flux(jypk=15)        # Alternative
    872858\end{verbatim}
    873859
    … …  
    884870
    885871\begin{verbatim}
    886   ASAP> scans.recalc_azel()                # recalculate az/el based on pointing
     872  ASAP>scans.recalc_azel()                # recalculate az/el
     873                                                                  # based on pointing
    887874\end{verbatim}
    888875
    889876Gain-elevation curves for some telescopes and frequencies are known to
    890 ASAP (currently only for Tidbinbilla at 20~GHz).  In these cases
    891 making gain-corrections is simple.  If the gain curve for your data is
    892 not known, the user can supply either a gain polynomial or text file
     877ASAP (currently only for Tidbinbilla at 20~GHz and Parkes at K-band).
     878In these cases making gain-corrections is simple.  If the gain curve for your
     879data is not known, the user can supply either a gain polynomial or text file
    893880tabulating gain factors at a range of elevations (see \cmd{help
    894881scantable.gain\_el}).
    … …  
    897884
    898885\begin{verbatim}
    899   ASAP> scans.gain_el()   # If gain table known
    900   ASAP> scans.gain_el(poly=[3.58788e-1,2.87243e-2,-3.219093e-4])
     886  ASAP>scans.gain_el()   # If gain table known
     887  ASAP>scans.gain_el(poly=[3.58788e-1,2.87243e-2,-3.219093e-4])
    901888\end{verbatim}
    902889
    … …  
    906893
    907894\begin{verbatim}
    908   ASAP> scans.opacity(0.083)
     895  ASAP>scans.opacity(0.083)
    909896\end{verbatim}
    910897
    … …  
    916903\label{sec:freqalign}
    917904
    918 \index{Frequency alignment}\index{Velicity alignment}When time
     905\index{Frequency alignment}\index{Velocity alignment}When time
    919906averaging a series of scans together, it is possible that the velocity
    920907scales are not exactly aligned.  This may be for many reasons such as
    … …  
    927914
    928915\begin{verbatim}
    929   ASAP> scans.freq_align()
    930   ASAP> av = average_time(scans)
     916  ASAP>scans.freq_align()
     917  ASAP>av = average_time(scans)
    931918\end{verbatim}
    932919
    … …  
    940927
    941928\begin{verbatim}
    942   ASAP> scans1.freq_align() # Copy the refeference Epoch from the output
    943   ASAP> scans2.freq_align(reftime='2004/11/23/18:43:35')
    944   ASAP> scans3.freq_align(reftime='2004/11/23/18:43:35')
    945   ASAP> av = average_time(scans1, scans2, scans3)
     929  ASAP>scans1.freq_align() # Copy the refeference Epoch from the output
     930  ASAP>scans2.freq_align(reftime='2004/11/23/18:43:35')
     931  ASAP>scans3.freq_align(reftime='2004/11/23/18:43:35')
     932  ASAP>av = average_time(scans1, scans2, scans3)
    946933\end{verbatim}
    947934
    … …  
    960947
    961948\begin{verbatim}
    962   ASAP> ss = scans.get_scan(10) # Get the 11th scan (zero based)
    963   ASAP> ss = scans.get_scan(range(10)) # Get the first 10 scans
    964   ASAP> ss = scans.get_scan(range(10,20)) # Get the next 10 scans
    965   ASAP> ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans
    966 
    967   ASAP> ss = scans.get_scan('345p407') # Get a specific source
    968   ASAP> ss = scans.get_scan('345*')    # Get a few sources
    969 
    970   ASAP> r = scans.get_scan('*_R') # Get all reference sources (Parkes/Mopra)
    971   ASAP> s = scans.get_scan('*_S') # Get all program sources (Parkes/Mopra)
    972   ASAP> r = scans.get_scan('*[ew]')  # Get all reference sources (Tid)
    973   ASAP> s = scans.get_scan('*[^ew]') # Get all program sources (Tid)
     949  ASAP>ss = scans.get_scan(10) # Get the 11th scan (zero based)
     950  ASAP>ss = scans.get_scan(range(10)) # Get the first 10 scans
     951  ASAP>ss = scans.get_scan(range(10,20)) # Get the next 10 scans
     952  ASAP>ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans
     953
     954  ASAP>ss = scans.get_scan('345p407') # Get a specific source
     955  ASAP>ss = scans.get_scan('345*')    # Get a few sources
     956
     957  ASAP>r = scans.get_scan('*_R') # Get all reference sources (Parkes/Mopra)
     958  ASAP>s = scans.get_scan('*^_R') # Get all program sources (Parkes/Mopra)
     959  ASAP>r = scans.get_scan('*[ew]')  # Get all reference sources (Tid)
     960  ASAP>s = scans.get_scan('*[^ew]') # Get all program sources (Tid)
    974961
    975962\end{verbatim}
    … …  
    978965
    979966\begin{verbatim}
    980   ASAP> ss = scans
     967  ASAP>ss = scans
    981968\end{verbatim}
    982969
    … …  
    986973
    987974\begin{verbatim}
    988   ASAP> ss = scans.copy()
     975  ASAP>ss = scans.copy()
    989976\end{verbatim}
    990977
    … …  
    10241011
    10251012\begin{verbatim}
    1026   ASAP> scans.save('myscans') # Save in default format
    1027   ASAP> scans.save('myscans', 'FITS') # Save as FITS for exporting into CLASS
    1028   ASAP> scans.save('myscans', overwrite=True) # Overwrite an existing file
     1013  ASAP>scans.save('myscans') # Save in default format
     1014  ASAP>scans.save('myscans', overwrite=True) # Overwrite an existing file
    10291015\end{verbatim}
    10301016
    10311017\section{Plotter}
    10321018
    1033 \index{Plotter}Scantable spectra can be plotted at any time. An asapplotter object is
    1034 used for plotting, meaning multiple plot windows can be active at the
    1035 same time. On start up a default asapplotter object is created called
    1036 ``plotter''. This would normally be used for standard plotting.
    1037 
    1038 The plotter, optionally, will run in a multipanel mode and contain
     1019\index{Plotter}Scantable spectra can be plotted at any time. An
     1020asapplotter object is used for plotting, meaning multiple plot windows
     1021can be active at the same time. On start up a default asapplotter
     1022object is created called ``plotter''. This would normally be used for
     1023standard plotting.
     1024
     1025The plotter, optionally, will run in a multi-panel mode and contain
    10391026multiple plots per panel. The user must tell the plotter how they want
    10401027the data distributed. This is done using the set\_mode function. The
    … …  
    10461033
    10471034\begin{verbatim}
    1048   ASAP> scans.set_unit('km/s')
    1049   ASAP> plotter.set_mode(stacking='p',panelling='t')
    1050   ASAP> plotter.plot(scans)
     1035  ASAP>scans.set_unit('km/s')
     1036  ASAP>plotter.set_mode(stacking='p', panelling='t')
     1037  ASAP>plotter.plot(scans)
    10511038\end{verbatim}
    10521039
    … …  
    10581045\begin{verbatim}
    10591046  # Plot multiple IFs per panel
    1060   ASAP> plotter.set_mode(stacking='i',panelling='t')
     1047  ASAP>plotter.set_mode(stacking='i', panelling='t')
    10611048
    10621049  # Plot multiple beams per panel
    1063   ASAP> plotter.set_mode(stacking='b',panelling='t')
     1050  ASAP>plotter.set_mode(stacking='b', panelling='t')
    10641051
    10651052  # Plot one IF per panel, time stacked
    1066   ASAP> plotter.set_mode('t', 'i')
     1053  ASAP>plotter.set_mode('t', 'i')
    10671054
    10681055  # Plot each scan in a seperate panel
    1069   ASAP> plotter.set_mode('t', 's')
     1056  ASAP>plotter.set_mode('t', 's')
    10701057
    10711058\end{verbatim}
    … …  
    10801067should be used for this purpose. Selection can either be applied to
    10811068the scantable or directly to the plotter, the end result is the same.
    1082 You don't have to reset the scantable slection though, if you set
     1069You don't have to reset the scantable selection though, if you set
    10831070the selection on the plotter.
    10841071
    … …  
    10861073
    10871074\begin{verbatim}
    1088   ASAP> selection = selector()
     1075  ASAP>selection = selector()
    10891076  # Select second IF
    1090   ASAP> selection.set_ifs(1)
    1091   ASAP> plotter.set_selection(selection)
     1077  ASAP>selection.set_ifs(1)
     1078  ASAP>plotter.set_selection(selection)
    10921079
    10931080  # Select first 4 beams
    1094   ASAP> selection.set_beams([0,1,2,3])
    1095   ASAP> plotter.set_selection(selection)
     1081  ASAP>selection.set_beams([0,1,2,3])
     1082  ASAP>plotter.set_selection(selection)
    10961083
    10971084  # Select a few scans
    1098   ASAP> selection.set_scans([2,4,6,10])
    1099   ASAP> plotter.set_selection(selection)
     1085  ASAP>selection.set_scans([2,4,6,10])
     1086  ASAP>plotter.set_selection(selection)
    11001087
    11011088  # Multiple selection
    1102   ASAP> selection.set_ifs(1)
    1103   ASAP> selection.set_scans([2,4,6,10])
    1104   ASAP> plotter.set_selection(selection)
     1089  ASAP>selection.set_ifs(1)
     1090  ASAP>selection.set_scans([2,4,6,10])
     1091  ASAP>plotter.set_selection(selection)
    11051092
    11061093\end{verbatim}
    … …  
    11121099zooming the individual plots). From left to right:
    11131100
    1114 \begin{itemize}
    1115 
    1116 \item[Home] This will unzoom the plots to the original zoom factor
    1117 
    1118 \item[Plot history] (left and right arrow). The plotter keeps a
    1119 history of zoom settings. The left arrow sets the plot zoom to the
    1120 previous value. The right arrow returns back again. This allows you,
    1121 for example, to zoom in on one feature then return the plot to how it
    1122 was previously.
    1123 
    1124 \item[Pan] (The Cross) This sets the cursor to pan, or scroll mode
    1125   allowing you to shift the plot within the window. Useful when
    1126   zoomed in on a feature.
    1127 
    1128 \item[Zoom] (the letter with the magnifying glass) lets you draw a
    1129   rectangle around a region of interest then zooms in on that
    1130   region. Use the plot history to unzoom again.
    1131 
    1132 \item[Adjust] (rectangle with 4 arrows) adjust subplot paramaters
    1133   (space at edge of plots)
    1134 
    1135 \item[Save] (floppy disk). Save the plot as a postscript or .png file
     1101\begin{tabular}{ll}
     1102
     1103Home & This will unzoom the plots to the original zoom factor \\
     1104
     1105Plot history & \parbox[t]{0.8\textwidth}{(left and right arrow) The
     1106plotter keeps a history of zoom settings. The left arrow sets the plot
     1107zoom to the previous value. The right arrow returns back again. This
     1108allows you, for example, to zoom in on one feature then return the
     1109plot to how it was previously. }\\
     1110
     1111Pan & \parbox[t]{0.8\textwidth}{(The Cross) This sets the cursor to
     1112  pan, or scroll mode allowing you to shift the plot within the
     1113  window. Useful when zoomed in on a feature. }\\
     1114
     1115Zoom & \parbox[t]{0.8\textwidth}{(the letter with the magnifying
     1116  glass) lets you draw a rectangle around a region of interest then
     1117  zooms in on that region. Use the plot history to unzoom again.}\\
     1118
     1119Adjust & \parbox[t]{0.8\textwidth}{(rectangle with 4 arrows) adjust
     1120  subplot parameters (space at edge of plots)}\\
     1121
     1122Save & \parbox[t]{0.8\textwidth}{(floppy disk). Save the plot as a
     1123postscript or .png file}\\
     1124
     1125\end{tabular}
    11361126
    11371127You can also type ``g'' in the plot window to toggle on and off grid
    11381128lines. Typing 'l' turns on and off logarithmic Y-axis.
    1139 
    1140 \end{itemize}
    11411129
    11421130\subsection{Other control}
    … …  
    11501138
    11511139\begin{verbatim}
    1152   ASAP> scans.set_unit('km/s')
    1153   ASAP> plotter.plot(scans)
    1154   ASAP> plotter.set_range(-150,-50)
    1155   ASAP> plotter.set_range() # To reset
     1140  ASAP>scans.set_unit('km/s')
     1141  ASAP>plotter.plot(scans)
     1142  ASAP>plotter.set_range(-150,-50)
     1143  ASAP>plotter.set_range() # To reset
    11561144\end{verbatim}
    11571145
    … …  
    11591147
    11601148\begin{verbatim}
    1161   ASAP> plotter.set_range(-10,30,-1,6.6)
     1149  ASAP>plotter.set_range(-10,30,-1,6.6)
    11621150\end{verbatim}
    11631151
    … …  
    11651153
    11661154\begin{verbatim}
    1167   ASAP> plotter.save('myplot.ps')
    1168   ASAP> plotter.save('myplot.png', dpi=80)
     1155  ASAP>plotter.save('myplot.ps')
     1156  ASAP>plotter.save('myplot.png', dpi=80)
    11691157\end{verbatim}
    11701158
    … …  
    11721160
    11731161The plotter allows the user to change most properties such as text
    1174 size and colour. The \cmd{commands} funcation and {\cmd help\
     1162size and colour. The \cmd{commands} function and {\cmd help\
    11751163asapplotter} list all the possible commands that can be used with the
    11761164plotter.
    … …  
    11871175plots. Allowable values are 'line', 'dashed', 'dotted', 'dashdot',
    11881176'dashdotdot' and 'dashdashdot. Example: }{
    1189   ASAP> plotter.set\_linestyles('line dash cotted datshot.)\\
    1190   ASAP> plotter.set\_font(size=10)\\
     1177  ASAP>plotter.set\_linestyles('line dash cotted datshot.)\\
     1178  ASAP>plotter.set\_font(size=10)\\
    11911179}
    11921180
    11931181\commanddef{set\_font}{Change the font style and size. Example}{
    1194   ASAP> plotter.set\_font(weight='bold')\\
    1195   ASAP> plotter.set\_font(size=10)\\
    1196   ASAP> plotter.set\_font(style='italic')\\
     1182  ASAP>plotter.set\_font(weight='bold')\\
     1183  ASAP>plotter.set\_font(size=10)\\
     1184  ASAP>plotter.set\_font(style='italic')\\
    11971185}
    11981186
    1199 \commanddef{set\_layout}{Change the multi-panel layout, ie now many
     1187\commanddef{set\_layout}{Change the multi-panel layout, i.e. now many
    12001188  rows and columns}{
    1201   ASAP> plotter.set\_layout(3,2)
     1189  ASAP>plotter.set\_layout(3,2)
    12021190}
    12031191
    12041192\commanddef{set\_legend}{Set the position, size and optional value of the legend}{
    1205   ASAP> plotter.set\_legend(fontsize=16)\\
    1206   ASAP> plotter.set\_legend(mode=0)  \# ASAP chooses where to put the legend\\
    1207   ASAP> plotter.set\_legend(mode=4)  \# Put legend on lower right\\
    1208   ASAP> plotter.set\_legend(mode=-1) \# No legend\\
    1209   ASAP> plotter.set\_legend(mp=['RR','LL']) \# Specify legend labels\\
    1210   ASAP> plotter.set\_legend(mp=[r'\$\^\{12\}CO\$',r'\$\^\{13\}CO\$']) \# Latex labels
     1193  ASAP>plotter.set\_legend(fontsize=16)\\
     1194  ASAP>plotter.set\_legend(mode=0)  \# ASAP chooses where to put the legend\\
     1195  ASAP>plotter.set\_legend(mode=4)  \# Put legend on lower right\\
     1196  ASAP>plotter.set\_legend(mode=-1) \# No legend\\
     1197  ASAP>plotter.set\_legend(mp=['RR','LL']) \# Specify legend labels\\
     1198  ASAP>plotter.set\_legend(mp=[r'\$\^\{12\}CO\$',r'\$\^\{13\}CO\$']) \# Latex labels
    12111199}
    12121200
    12131201\commanddef{set\_title}{Set the plot title. If multiple panels are
    12141202  plotted, multiple titles have to be specified}{
    1215   ASAP> plotter.set\_title(`G323.12$-$1.79`)\\
    1216   ASAP> plotter.set\_title([`SiO`, 'Methanol'], fontsize=18)\\
     1203  ASAP>plotter.set\_title(`G323.12$-$1.79`)\\
     1204  ASAP>plotter.set\_title([`SiO`, 'Methanol'], fontsize=18)\\
    12171205}
    12181206
    12191207\subsection{Plotter Annotations}
    12201208
    1221 The plotter allows various annontations (lines, arrows, text and
     1209The plotter allows various annotations (lines, arrows, text and
    12221210``spans'') to be added to the plot. These annotations are
    12231211``temporary'', when the plotter is next refreshed
    … …  
    12251213will be removed.
    12261214
    1227 \bigcommanddef{arrow(x,y,x+dx,y+dy)}{Draw an arrow from a specifed
     1215\bigcommanddef{arrow(x,y,x+dx,y+dy)}{Draw an arrow from a specified
    12281216\cmd{(x,y)} position to \cmd{(x+dx, y+dy)}. The values are in world
    1229 coordinates. \em {HOW TO SET ARROW HEAD??}}{
    1230   ASAP> plotter.arrow(-40,7,35,0)
     1217coordinates. Addition arguments which must be passed are {\cmd head\_width} and \cmd{head\_length}}{
     1218  ASAP>plotter.arrow(-40,7,35,0,head\_width=0.2, head\_length=10)
    12311219}
    12321220
    12331221\bigcommanddef{axhline(y, xmin, xmax)}{Draw a horizontal line at the
    1234 specifed \cmd{y} position (in world coordinates) between xmin and xmax
    1235 (in relative coordinates, ie 0.0 is the left hand edge of the plot
    1236 while 1.0 is the right side of the plot.}{
    1237  ASAP> plotter.axhline(6.0,0.2,0.8)
     1222specified \cmd{y} position (in world coordinates) between xmin and xmax
     1223(in relative coordinates, i.e. 0.0 is the left hand edge of the plot
     1224while 1.0 is the right side of the plot).}{
     1225 ASAP>plotter.axhline(6.0,0.2,0.8)
    12381226}
    12391227
    12401228\bigcommanddef{avhline(x, ymin, ymax)}{Draw a vertical line at the
    1241 specifed \cmd{x} position (in world coordinates) between \cmd{ymin}
    1242 and \cmd{ymax} (in relative coordinates, ie 0.0 is the left hand edge
     1229specified \cmd{x} position (in world coordinates) between \cmd{ymin}
     1230and \cmd{ymax} (in relative coordinates, i.e. 0.0 is the left hand edge
    12431231of the plot while 1.0 is the right side of the plot).}{
    1244  ASAP> plotter.axvline(-50.0,0.1,1.0)
     1232 ASAP>plotter.axvline(-50.0,0.1,1.0)
    12451233}
    12461234
    12471235\bigcommanddef{axhspan(ymin, ymax, \\ \hspace*{20mm}xmin,
    12481236 xmax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
    1249  \cmd{ymax} are given in world coordnates while \cmd{xmin} and
     1237 \cmd{ymax} are given in world coordinates while \cmd{xmin} and
    12501238 \cmd{xmax} are given in relative coordinates}{
    1251 ASAP> plotter.axhspan(2,4,0.25,0.75)
     1239ASAP>plotter.axhspan(2,4,0.25,0.75)
    12521240}
    12531241
    12541242\bigcommanddef{axvspan(xmin, xmax, \\ \hspace*{20mm} ymin,
    12551243 ymax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
    1256  \cmd{ymax} are given in relative coordnates while \cmd{xmin} and
     1244 \cmd{ymax} are given in relative coordinates while \cmd{xmin} and
    12571245 \cmd{xmax} are given in world coordinates}{
    1258 ASAP> plotter.axvspan(-50,60,0.2,0.5)
     1246ASAP>plotter.axvspan(-50,60,0.2,0.5)
    12591247}
    12601248
    … …  
    12641252}
    12651253
    1266 
    1267 
    12681254These functions all take a set of \cmd{kwargs} commands. These can be
    12691255used to set colour, linewidth fontsize etc. These are standard
    … …  
    12711257
    12721258\begin{tabular}{ll}
    1273  \tt color  \\
    1274  \tt linewidth \\
     1259 \tt color, facecolor, edgecolor \\
     1260 \tt width, linewidth \\
    12751261 \tt fontsize \\
    12761262 \tt fontname & Sans, Helvetica, Courier, Times etc\\
    … …  
    12811267Examples:
    12821268\begin{verbatim}
    1283   ASAP> plotter.axhline(6.0,0.2,0.8, color='red', linewidth=3)
    1284   ASAP> plotter.text(-10,7,"CO", fontsize=20)
    1285 \end{verbatim}
     1269  ASAP>plotter.axhline(6.0,0.2,0.8, color='red', linewidth=3)
     1270  ASAP>plotter.text(-10,7,"CO", fontsize=20)
     1271\end{verbatim}
     1272
     1273\section{Line Catalog}
     1274\label{sec:linecat}
     1275\index{Linecatalog}ASAP can load and manipulate line catlogs to
     1276retrieve rest frequencies for \cmd{set\_restfreqs} and for line
     1277identification in the plotter. All line catalogs are loaded into a ``linecatalog'' object.
     1278
     1279No line catalogs are built into ASAP, the user must load a ASCII based
     1280table (which can optionally be saved in an internal format) either of
     1281the users own creation or a standard line catalog such as the JPL line
     1282catalog or Lovas. The ATNF asap ftp area as copies of the JPL and
     1283Lovas catalog in the appropriate format:
     1284
     1285\hspace{1cm}\cmd{ftp://ftp.atnf.csiro.au/pub/software/asap/data}
     1286 
     1287
     1288\subsection{Loading a Line Catalog}
     1289
     1290\index{Linecatalog!loading}The ASCII text line catalog must have at
     1291least 4 columns. The first four columns must contain (in order):
     1292Molecule name, frequency in MHz, frequency error and ``intensity''
     1293(any units). If the molecule name contains any spaces, they must be
     1294wrapped in quotes \verb+""+.
     1295
     1296A sample from the JPL line catalog:
     1297
     1298\begin{verbatim}
     1299     H2D+    3955.2551 228.8818  -7.1941 
     1300     H2D+   12104.7712 177.1558  -6.0769 
     1301     H2D+   45809.2731 118.3223  -3.9494 
     1302     CH       701.6811    .0441  -7.1641 
     1303     CH       724.7709    .0456  -7.3912 
     1304     CH      3263.7940    .1000  -6.3501 
     1305     CH      3335.4810    .1000  -6.0304 
     1306\end{verbatim}
     1307
     1308To load a line catalog then save it in the internal format:
     1309
     1310\begin{verbatim}
     1311  ASAP>jpl = linecatalog('jpl_pruned.txt')
     1312  ASAP>jpl.save('jpl.tbl')
     1313\end{verbatim}
     1314
     1315Later the saved line catalog can reloaded:
     1316
     1317\begin{verbatim}
     1318  ASAP>jpl = linecatalog('jpl.tbl')
     1319\end{verbatim}
     1320
     1321{\em NOTE:} Due to a bug in ipython, if you do not \cmd{del} the
     1322linecatalog table before quiting asap, you will be left with temporary
     1323files. It is safe to delete these once asap has finished.
     1324
     1325\subsection{Line selection}
     1326
     1327\index{Linecatalog!line selection}The linecatalog has a number of
     1328selection functions to select a range of lines from a larger catalog
     1329(the JPL catalog has $>$180000 lines for
     1330example). \cmd{set\_frequency\_limits} selects on frequency range,
     1331\cmd{set\_strength\_limits} selects on intensity while \cmd{set\_name}
     1332selects on molecule name (wild cards allowed). The \cmd{summary}
     1333function lists the currently selected lines.
     1334
     1335\begin{verbatim}
     1336  ASAP>jpl = linecatalog('jpl.tbl')
     1337  ASAP>jpl.set_frequency_limits(80,115,'GHz') # Lines for 3mm receiver
     1338  ASAP>jpl.set_name('*OH')                    # Select all alcohols
     1339  ASAP>jpl.set_name('OH')                     # Select only OH molecules
     1340  ASAP>jpl.summary()
     1341
     1342  ASAP>jpl.reset()                            # Selections are accumulative
     1343  ASAP>jpl.set_frequency_limits(80,115,'GHz')
     1344  ASAP>jpl.set_strength_limits(-2,10)         # Select brightest lines
     1345  ASAP>jpl.summary()
     1346\end{verbatim}
     1347
     1348\subsection{Using Linecatalog}
     1349
     1350The line catalogs can be used for line overlays on the plotter or with
     1351\cmd{set\_restfreq}.
     1352
     1353\subsubsection{Plotting linecatalog}
     1354
     1355\index{Linecatalog!plotting}
     1356
     1357The plotter \cmd{plot\_lines} function takes a line catalog as an
     1358argument and overlays the lines on the spectrum. {\em Currently this
     1359only works when plotting in units of frequency (Hz, GHz etc).} If a
     1360large line catalog has been loaded (e.g. JPL) it is highly recommended
     1361that you use the selection functions to narrow down the number of
     1362lines.  By default the line catalog overlay is plotted assuming a line
     1363velocity of 0.0. This can be set using the \cmd{doppler} argument (in
     1364km/s). Each time \cmd{plot\_lines} is called the new lines are added
     1365to any existing line catalog annotations. These are all removed after
     1366the next call to \cmd{plotter.plot()}.
     1367
     1368\begin{verbatim}
     1369  ASAP>jpl = linecatalog('jpl.tbl')
     1370  ASAP>jpl.set_frequency_limits(23,24,'GHz')
     1371  ASAP>data.set_unit('GHz')            # Only works with freq axis currently
     1372  ASAP>plotter.plot(data)
     1373  ASAP>plotter.plot_lines(jpl)
     1374
     1375  ASAP>plotter.plot()                  # Reset plotter
     1376  ASAP>plotter.plot_lines(jpl,doppler=-10,location='Top')
     1377                             # On top with -10 km/s velocity
     1378\end{verbatim}
     1379
     1380\subsubsection{Setting Rest Frequencies}
     1381
     1382\index{Linecatalog!set\_restfreq}A linecatalog can be used as an
     1383argument for \cmd{set\_restfreqs}. If a personal line catalog has been
     1384used (which has the same size as the number of number of IFs) or
     1385linecatalog selection has been used to reduce the number of entries,
     1386the line catalog can be used directly as an argument to
     1387\cmd{set\_restfreqs}, e.g.:
     1388\begin{verbatim}
     1389  ASAP>jpl = linecatalog('jpl.tbl')
     1390  ASAP>jpl.set_frequency_limits(23.66,23.75,'GHz')
     1391  ASAP>data = scantable('data.rpf')
     1392  ASAP>data.set_restfreqs(jpl)
     1393\end{verbatim}
     1394
     1395If a larger linecatalog is used, individual elements can be used. Use
     1396the \cmd{summary} to get the index number of the rest frequency you
     1397wish to use. E.g.:
     1398
     1399\begin{verbatim}
     1400  ASAP>jpl.summary()
     1401  ASAP>data.set_restfreqs([jpl[11],[jpl[21]])
     1402\end{verbatim}
     1403
     1404For data with many IFs, such as from MOPS, the user it is recommended
     1405that the user creates their own line cstalog for the data and use this
     1406to set the rest frequency for each IF.
    12861407
    12871408\section{Fitting}
    … …  
    12961417
    12971418\begin{verbatim}
    1298  ASAP> f = fitter()
    1299  ASAP> f.set_function(gauss=2) # Fit two Gaussians
    1300  ASAP> f.set_scan(scans)
    1301  ASAP> selection = selector()
    1302  ASAP> selection.set_polarisations(1) # Fit the second polarisation
    1303  ASAP> scans.set_selection(selection)
    1304  ASAP> scans.set_unit('km/s')  # Make fit in velocity units
    1305  ASAP> f.fit(1)                # Run the fit on the second row in the table
    1306  ASAP> f.plot()                # Show fit in a plot window
    1307  ASAP> f.get_parameters()      # Return the fit paramaters
     1419 ASAP>f = fitter()
     1420 ASAP>f.set_function(gauss=2) # Fit two Gaussians
     1421 ASAP>f.set_scan(scans)
     1422 ASAP>selection = selector()
     1423 ASAP>selection.set_polarisations(1) # Fit the second polarisation
     1424 ASAP>scans.set_selection(selection)
     1425 ASAP>scans.set_unit('km/s')  # Make fit in velocity units
     1426 ASAP>f.fit(1)                # Run the fit on the second row in the table
     1427 ASAP>f.plot()                # Show fit in a plot window
     1428 ASAP>f.get_parameters()      # Return the fit paramaters
    13081429\end{verbatim}
    13091430
    … …  
    13161437
    13171438\begin{verbatim}
    1318   ASAP> f = fitter()
    1319   ASAP> f.set_function(gauss=2)
    1320   ASAP> scans.set_unit('km/s')  # Set the mask in channel units
    1321   ASAP> msk = s.create_mask([1800,2200])
    1322   ASAP> scans.set_unit('km/s')  # Make fit in velocity units
    1323   ASAP> f.set_scan(s,msk)
    1324   ASAP> f.fit()
    1325   ASAP> f.plot()
    1326   ASAP> f.get_parameters()
     1439  ASAP>f = fitter()
     1440  ASAP>f.set_function(gauss=2)
     1441  ASAP>scans.set_unit('km/s')  # Set the mask in channel units
     1442  ASAP>msk = s.create_mask([1800,2200])
     1443  ASAP>scans.set_unit('km/s')  # Make fit in velocity units
     1444  ASAP>f.set_scan(s,msk)
     1445  ASAP>f.fit()
     1446  ASAP>f.plot()
     1447  ASAP>f.get_parameters()
    13271448\end{verbatim}
    13281449
    … …  
    13311452
    13321453\begin{verbatim}
    1333   ASAP> f = fitter()
    1334   ASAP> f.set_function(gauss=2)
    1335   ASAP> f.set_scan(s,msk)
    1336   ASAP> f.fit() # Fit using auto-estimates
     1454  ASAP>f = fitter()
     1455  ASAP>f.set_function(gauss=2)
     1456  ASAP>f.set_scan(s,msk)
     1457  ASAP>f.fit() # Fit using auto-estimates
    13371458  # Set Peak, centre and fwhm for the second gaussian.
    13381459  # Force the centre to be fixed
    1339   ASAP> f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
    1340   ASAP> f.fit() # Re-run the fit
     1460  ASAP>f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
     1461  ASAP>f.fit() # Re-run the fit
    13411462\end{verbatim}
    13421463
    … …  
    13491470\begin{verbatim}
    13501471  # Plot the residual
    1351   ASAP> f.plot(residual=True)
     1472  ASAP>f.plot(residual=True)
    13521473
    13531474  # Plot the first 2 componentsa
    1354   ASAP> f.plot(components=[0,1])
     1475  ASAP>f.plot(components=[0,1])
    13551476
    13561477  # Plot the first and third component plus the model sum
    1357   ASAP> f.plot(components=[-1,0,2])  # -1 means the compoment sum
     1478  ASAP>f.plot(components=[-1,0,2])  # -1 means the compoment sum
    13581479\end{verbatim}
    13591480
    … …  
    13641485
    13651486\begin{verbatim}
    1366   ASAP> f.storefit()
     1487  ASAP>f.store_fit()
    13671488\end{verbatim}
    13681489
    … …  
    13761497
    13771498\begin{verbatim}
    1378   ASAP> scans.get_fit(4) # Print fits for row 4
     1499  ASAP>scans.get_fit(4) # Print fits for row 4
     1500\end{verbatim}
     1501
     1502A fit can also be exported to an ASCII file using the \cmd{store\_fit}
     1503function. Simply give the name of the output file requires as an
     1504argument.
     1505
     1506\begin{verbatim}
     1507  ASAP>f.store_fit('myfit.txt')
    13791508\end{verbatim}
    13801509
    … …  
    13991528
    14001529\begin{verbatim}
    1401   ASAP> scans.rotate_xyphase(10.5)            # Degrees
     1530  ASAP>scans.rotate_xyphase(10.5)            # Degrees
    14021531\end{verbatim}
    14031532
    … …  
    14121541
    14131542\begin{verbatim}
    1414   ASAP> scans.rotate_linpolphase(-45) # Degrees; correct for receiver mounting
     1543  ASAP>scans.rotate_linpolphase(-45) # Degrees; correct for receiver mounting
    14151544\end{verbatim}
    14161545
    … …  
    14211550
    14221551\begin{verbatim}
    1423   ASAP> scans.invert_phase()
     1552  ASAP>scans.invert_phase()
    14241553\end{verbatim}
    14251554
    14261555Depending on how the correlator is configured, ``BA'' may be
    1427 correlated insead of ``AB''. Use \cmd{swap\_linears} to correct for
     1556correlated instead of ``AB''. Use \cmd{swap\_linears} to correct for
    14281557this problem:
    14291558
    14301559\begin{verbatim}
    1431   ASAP> scans.swap_linears()
     1560  ASAP>scans.swap_linears()
    14321561\end{verbatim}
    14331562
    … …  
    14391568
    14401569\begin{verbatim}
    1441   ASAP> stokescans = linearscans.convert_pol("stokes")
     1570  ASAP>stokescans = linearscans.convert_pol("stokes")
    14421571\end{verbatim}
    14431572
    … …  
    14581587
    14591588\begin{verbatim}
    1460   ASAP> selection = selector()
    1461 
    1462   ASAP> selection.set_polarisations(``I Q U V'')
     1589  ASAP>selection = selector()
     1590
     1591  ASAP>selection.set_polarisations(``I Q U V'')
    14631592  ASAP  plotter.set_selection(selection);              # Select I, Q, U \& V
    14641593
    1465   ASAP> selection.set_polarisations(``I Q'')
     1594  ASAP>selection.set_polarisations(``I Q'')
    14661595  ASAP  plotter.set_selection(selection);              # Select just I \& Q
    14671596
    1468   ASAP> selection.set_polarisations(``RR LL'')
     1597  ASAP>selection.set_polarisations(``RR LL'')
    14691598  ASAP  plotter.set_selection(selection);              # Select just RR \& LL
    14701599
    1471   ASAP> selection.set_polarisations(``XX YY'')
     1600  ASAP>selection.set_polarisations(``XX YY'')
    14721601  ASAP  plotter.set_selection(selection);              # Select linears
    14731602
    1474   ASAP> selection.set_polarisations(``I Plinear'')
     1603  ASAP>selection.set_polarisations(``I Plinear'')
    14751604  ASAP  plotter.set_selection(selection);              # Fractional linear
    14761605
    1477   ASAP> selection.set_polarisations(``Pangle'')
     1606  ASAP>selection.set_polarisations(``Pangle'')
    14781607  ASAP  plotter.set_selection(selection);              # Position angle
    14791608
    … …  
    14831612describe in section~\ref{sec:selection}.
    14841613
    1485 \subsection{Saving}
    1486 
    1487 \index{Polarisation!saving}When saving data using the \cmd{save}
    1488 function, the \cmd{stokes} argument can be used to save the data as
    1489 Stoke values when saving in FITS format.
    1490 
    1491 Example:
    1492 
    1493 \begin{verbatim}
    1494   ASAP> scans.save('myscan.sdfits', 'SDFITS', stokes=True)
    1495 \end{verbatim}
    1496 
    14971614\section{Specialised Processing}
    14981615
    … …  
    15011618MX mode is a specific observing approach with a multibeam where a
    15021619single source is observed cycling through each beam. The scans when
    1503 the beam is off source is used as a reference for the onsource
     1620the beam is off source is used as a reference for the on-source
    15041621scan. The function \cmd{mx\_quotient} is used to make a quotient
    15051622spectrum from an MX cycle. This works averaging the ``off-source''
    … …  
    15091626single scan (it the scan numbers are re-labelled to be the same). Note
    15101627that the current version of \cmd{mx\_quotient} only handles a single
    1511 MX cycle, ie if each beam has observed the source multiple times you
     1628MX cycle, i.e. if each beam has observed the source multiple times you
    15121629will need to use the selector object multiple times to select a single
    15131630MX cycle, run \cmd{mx\_quotient} for each cycle then merge the
    … …  
    15171634
    15181635\begin{verbatim}
    1519   ASAP> scans = scantable('mydata.rpf')
    1520   ASAP> q = scans.mx_quotient()
    1521   ASAP> plotter.plot(q)
     1636  ASAP>scans = scantable('mydata.rpf')
     1637  ASAP>q = scans.mx_quotient()
     1638  ASAP>plotter.plot(q)
    15221639\end{verbatim}
    15231640
    … …  
    15271644
    15281645\begin{verbatim}
    1529   ASAP> av = q.average_beam()
     1646  ASAP>av = q.average_beam()
    15301647\end{verbatim}
    15311648
    … …  
    15331650
    15341651{\em FILL ME IN}
     1652
     1653\subsection{Disk Based Processing}
     1654\index{Scantable!disk based}
     1655
     1656Normally scantables exist entirely in memory during an ASAP
     1657session. This has the advantage of speed, but causes limits on the
     1658size of the dataset which can be loaded. ASAP can use ``disk based''
     1659scan tables which cache the bulk of the scantable on disk and require
     1660significantly less memory usage.
     1661
     1662To use disk based tables you either need to change the default in your
     1663\cmd{.asaprc} file, e.g.
     1664\begin{verbatim}
     1665   scantable.storage          : disk
     1666\end{verbatim}
     1667
     1668or use set the ``\cmd{rc}'' value while running asap to change this
     1669on-the-fly. E.g.
     1670\begin{verbatim}
     1671  ASAP>rc('scantable',storage='disk')
     1672  ASAP>data = scantable('data.rpf')     # Loaded using disk based table
     1673  ASAP>rc('scantable',storage='memory') # Memory tables will be used now
     1674\end{verbatim}
     1675
     1676Changing the ``\cmd{rc}'' value affects the next time the
     1677\cmd{scantable} constructor is called.
     1678
     1679{\bf NOTE: } Currently a bug in ipython means temporary files are not
     1680cleaned up properly when you exit ASAP. If you use disk based scan
     1681tables your directory will be left with 'tabXXXXX\_X' directories. These can
     1682be safely removed if ASAP is not running.
    15351683
    15361684\section{Scantable Mathematics}
    … …  
    15441692{\em Currently mathematics between two scantables is not available }
    15451693
    1546 %  ASAP> sum = scan1+scan2
    1547 \begin{verbatim}
    1548   ASAP> scan2 = scan1+2.0
    1549   ASAP> scan *= 1.05
     1694%  ASAP>sum = scan1+scan2
     1695\begin{verbatim}
     1696  ASAP>scan2 = scan1+2.0
     1697  ASAP>scan *= 1.05
    15501698\end{verbatim}
    15511699
    15521700\section{Scripting}
    15531701
    1554 \index{Scripting}Because asap is based on python, it easy for the user
     1702\index{Scripting}Because ASAP is based on python, it easy for the user
    15551703write their own scripts and functions to process data. This is highly
    15561704recommended as most processing of user data could then be done in a
    15571705couple of steps using a few simple user defined functions. A Python
    1558 primer is beyond the scope of this userguide. See the asap home pages
     1706primer is beyond the scope of this userguide. See the ASAP home pages
    15591707for a scripting tutorial or the main python website for comprehensive
    15601708documentation.
    … …  
    15621710\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
    15631711
     1712\hspace{1cm} http://svn.atnf.csiro.au/trac/asap/wiki
     1713
    15641714\hspace{1cm} http://www.python.org/doc/Introduction.html
    15651715
    15661716\subsection{Running scripts}
    15671717
    1568 The asap global function \cmd{execfile} reads the named text file and
     1718The ASAP global function \cmd{execfile} reads the named text file and
    15691719executes the contained python code. This file can either contain
    15701720function definitions which will be used in subsequent processing or
    15711721just a set of commands to process a specific dataset.
    15721722
     1723As an alternative to run scripts without entering ASAP, create a script which
     1724starts with.
     1725
     1726\begin{verbatim}
     1727from asap import *
     1728
     1729<your code>
     1730\end{verbatim}
     1731
     1732And run it with \cmd{python scriptname}.
     1733
    15731734\subsection{asapuserfuncs.py}
    15741735
    15751736The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
    1576 asap is started. The user can use this to define a set of user
    1577 functions which are automatically available each time asap is
     1737ASAP is started. The user can use this to define a set of user
     1738functions which are automatically available each time ASAP is
    15781739used. The \cmd{execfile} function can be called from within this file.
    15791740
    … …  
    15811742
    15821743In the following section a few examples of end-to-end processing of
    1583 some data in asap are given.
     1744some data in ASAP are given.
    15841745
    15851746\subsection{Mopra}
    … …  
    15871748
    15881749The following example is of some dual polarisation, position switched
    1589 data from Mopra. The source has been observed mulitple times split
    1590 into a number of seperate rpfits files. To make the processing easier,
    1591 the first step is to \cmd{cat} the seeprate rpfits files together and
    1592 load as a whole (future versions of asap will make this unnecessary).
     1750data from Mopra. The source has been observed multiple times split
     1751into a number of separate RPFITS files. To make the processing easier,
     1752the first step is to \cmd{cat} the separate RPFITS files together and
     1753load as a whole (future versions of ASAP will make this unnecessary).
    15931754
    15941755
    … …  
    16501811
    16511812\index{Parkes}\index{Polarisation}The following example is processing
    1652 of some Parkes polarmetric observations of OH masers at
     1813of some Parkes polarimetric observations of OH masers at
    165318141.6~GHz. Because digital filters where used in the backend, the
    16541815baselines are stable enough not to require a quotient spectra. The
    165518164~MHz bandwidth is wide enough to observe both the 1665 and 1667~MHz
    16561817OH maser transitions. Each source was observed once for about 10
    1657 minutes. Tsys information was not written to the rpfits file (a
     1818minutes. Tsys information was not written to the RPFITS file (a
    16581819nominal 25K values was used), so the amplitudes need to be adjusted
    16591820based on a separate log file. A simple user function is used to
    … …  
    16811842\end{verbatim}
    16821843
    1683 The typical asap session would be
     1844The typical ASAP session would be
    16841845
    16851846\begin{verbatim}
    … …  
    17661927limitations. The data is position switched, observing first an
    17671928reference to the west, then the source twice and finally reference to
    1768 the east.
     1929the east. Important to note, that \cmd{auto\_quotient} should be executed
     1930using the \cmd{mode} `time'.
    17691931
    17701932\begin{verbatim}
    … …  
    17751937
    17761938# Make the quotient spectra
    1777 q = d.auto_quotient()
     1939q = d.auto_quotient(mode='time')
    17781940print q
    17791941
    … …  
    18261988\index{Functions!summary}%
    18271989\begin{verbatim}
    1828 
    1829     [The scan container]
     1990   [The scan container]
    18301991        scantable           - a container for integrations/scans
    18311992                              (can open asap/rpfits/sdfits and ms files)
    … …  
    18532014            get_abcissa     - get the abcissa values and name for a given
    18542015                              row (time)
     2016            get_column_names - get the names of the columns in the scantable
     2017                               for use with selector.set_query
    18552018            set_freqframe   - set the frame info for the Spectral Axis
    18562019                              (e.g. 'LSRK')
    … …  
    18672030            set_restfreqs   - set a list of rest frequencies
    18682031            flag            - flag selected channels in the data
    1869             lag_flag        - flag specified frequency in the data
    18702032            save            - save the scantable to disk as either 'ASAP',
    18712033                              'SDFITS' or 'ASCII'
    … …  
    19102072     [Selection]
    19112073         selector              - a selection object to set a subset of a scantable
    1912             set_scans          - set (a list of) scans by index
    1913             set_cycles         - set (a list of) cycles by index
     2074           set_cycles         - set (a list of) cycles by index
    19142075            set_beams          - set (a list of) beamss by index
    19152076            set_ifs            - set (a list of) ifs by index
    … …  
    19182079            set_names          - set a selection by name (wildcards allowed)
    19192080            set_tsys           - set a selection by tsys thresholds
     2081            set_query          - set a selection by SQL-like query, e.g. BEAMNO==1
    19202082            reset              - unset all selections
    19212083            +                  - merge to selections
    … …  
    19882150            arrow           - draw arrow annotations either in data or relative
    19892151                              coordinates
    1990             set_abcissa     - specify a user label for the abcissa
    1991             set_ordinate    - specify a user label for the ordinate
    1992             set_layout      - specify the multi-panel layout (rows,cols)
    1993             set_colors      - specify a set of colours to use
    1994             set_linestyles  - specify a set of linestyles to use if only
    1995                               using one color
    1996             set_font        - set general font properties, e.g. 'family'
    1997             set_histogram   - plot in historam style
    1998             set_mask        - set a plotting mask for a specific polarization
    1999             text            - draw text annotations either in data or relative
    2000                               coordinates
     2152            axhline,axvline - draw horizontal/vertical lines
     2153            axhspan,axvspan - draw horizontal/vertical regions
     2154
     2155        xyplotter           - matplotlib/pylab plotting functions
     2156
     2157    [Reading files]
     2158        reader              - access rpfits/sdfits files
    20012159            arrow           - draw arrow annotations either in data or relative
    20022160                              coordinates
    … …  
    20602218histogram rather than lines.}
    20612219
    2062 {\em MALTE TO FIX}
    2063 
    20642220\asaprc{plotter.colours}{}{Set default colours for plotting}
    20652221
    … …  
    20692225
    20702226% scantable
    2071 \asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
     2227\asaprc{scantable.save}{{\bf ASAP} SDFITS ASCII MS2}{Default output
    20722228format when saving}
    20732229
    … …  
    20872243\subsection{Installation}
    20882244
    2089 \index{Installation}ASAP depends on a number of third-party libraries which you must
    2090 have installed before attempting to build ASAP. These are:
    2091 
    2092 \begin{itemize}
    2093 \item AIPS++
    2094 \item Boost
    2095 \item Matplotlib
    2096 \item python/ipython
    2097 \end{itemize}
    2098 
    2099 Debian Linux is currently supported and we intend also
    2100 to support other popular Linux flavours, Solaris and Mac.
    2101 
    2102 Of the dependencies, AIPS++ is the most complex to install.
     2245\index{Installation}
     2246
     2247Please refer to the asap wiki for instructions on downloading and/or
     2248building asap from source.
     2249
     2250\hspace{1cm}\cmd{http://www.atnf.csiro.au/computing/software/asap/}
    21032251
    21042252\printindex
Note: See TracChangeset for help on using the changeset viewer.