Changeset 1267 for trunk/doc


Ignore:
Timestamp:
09/13/06 10:17:00 (18 years ago)
Author:
mar637
Message:

Merge from Release2.1 branch

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/userguide.tex

    r1259 r1267  
    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
     
    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.
     
    418424
    419425\end{verbatim}
    420 
    421 \end{itemize}
    422426
    423427\subsection{State}
     
    493497\end{verbatim}
    494498
    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 }
     499A predetermined ``line catalog'' can be used to set the rest
     500frequency. See section \S \ref{sec:linecat}.
     501
    506502
    507503\subsubsection{Masks}
     
    11131109zooming the individual plots). From left to right:
    11141110
    1115 \begin{itemize}
    1116 
    1117 \item[Home] This will unzoom the plots to the original zoom factor
    1118 
    1119 \item[Plot history] (left and right arrow). The plotter keeps a
    1120 history of zoom settings. The left arrow sets the plot zoom to the
    1121 previous value. The right arrow returns back again. This allows you,
    1122 for example, to zoom in on one feature then return the plot to how it
    1123 was previously.
    1124 
    1125 \item[Pan] (The Cross) This sets the cursor to pan, or scroll mode
    1126   allowing you to shift the plot within the window. Useful when
    1127   zoomed in on a feature.
    1128 
    1129 \item[Zoom] (the letter with the magnifying glass) lets you draw a
    1130   rectangle around a region of interest then zooms in on that
    1131   region. Use the plot history to unzoom again.
    1132 
    1133 \item[Adjust] (rectangle with 4 arrows) adjust subplot parameters
    1134   (space at edge of plots)
    1135 
    1136 \item[Save] (floppy disk). Save the plot as a postscript or .png file
     1111\begin{tabular}{ll}
     1112
     1113Home & This will unzoom the plots to the original zoom factor \\
     1114
     1115Plot history & \parbox[t]{0.8\textwidth}{(left and right arrow) The
     1116plotter keeps a history of zoom settings. The left arrow sets the plot
     1117zoom to the previous value. The right arrow returns back again. This
     1118allows you, for example, to zoom in on one feature then return the
     1119plot to how it was previously. }\\
     1120
     1121Pan & \parbox[t]{0.8\textwidth}{(The Cross) This sets the cursor to
     1122  pan, or scroll mode allowing you to shift the plot within the
     1123  window. Useful when zoomed in on a feature. }\\
     1124
     1125Zoom & \parbox[t]{0.8\textwidth}{(the letter with the magnifying
     1126  glass) lets you draw a rectangle around a region of interest then
     1127  zooms in on that region. Use the plot history to unzoom again.}\\
     1128
     1129Adjust & \parbox[t]{0.8\textwidth}{(rectangle with 4 arrows) adjust
     1130  subplot parameters (space at edge of plots)}\\
     1131
     1132Save & \parbox[t]{0.8\textwidth}{(floppy disk). Save the plot as a
     1133postscript or .png file}\\
     1134
     1135\end{tabular}
    11371136
    11381137You can also type ``g'' in the plot window to toggle on and off grid
    11391138lines. Typing 'l' turns on and off logarithmic Y-axis.
    1140 
    1141 \end{itemize}
    11421139
    11431140\subsection{Other control}
     
    12281225\bigcommanddef{arrow(x,y,x+dx,y+dy)}{Draw an arrow from a specified
    12291226\cmd{(x,y)} position to \cmd{(x+dx, y+dy)}. The values are in world
    1230 coordinates. \em {HOW TO SET ARROW HEAD??}}{
    1231   ASAP>plotter.arrow(-40,7,35,0)
     1227coordinates. Addition arguments which must be passed are {\cmd head\_width} and \cmd{head\_length}}{
     1228  ASAP>plotter.arrow(-40,7,35,0,head\_width=0.2, head\_length=10)
    12321229}
    12331230
     
    12351232specified \cmd{y} position (in world coordinates) between xmin and xmax
    12361233(in relative coordinates, i.e. 0.0 is the left hand edge of the plot
    1237 while 1.0 is the right side of the plot.}{
     1234while 1.0 is the right side of the plot).}{
    12381235 ASAP>plotter.axhline(6.0,0.2,0.8)
    12391236}
     
    12651262}
    12661263
    1267 
    1268 
    12691264These functions all take a set of \cmd{kwargs} commands. These can be
    12701265used to set colour, linewidth fontsize etc. These are standard
     
    12721267
    12731268\begin{tabular}{ll}
    1274  \tt color  \\
    1275  \tt linewidth \\
     1269 \tt color, facecolor, edgecolor \\
     1270 \tt width, linewidth \\
    12761271 \tt fontsize \\
    12771272 \tt fontname & Sans, Helvetica, Courier, Times etc\\
     
    12871282
    12881283\section{Line Catalog}
    1289 
    1290 \index{Linecatalog}ASAP can load and manipulate line catlogs to retrieve rest frequencies
    1291 for \cmd{set\_restfreqs} and for line identification in the
    1292 plotter. No line catalogs are built into ASAP, the user must load a
    1293 ASCII based table (which can optionally be saved in an internal
    1294 format) either of the users own creation or a standard line catalog
    1295 such as the JPL line catalog or Lovas. The ATNF asap ftp area as
    1296 copies of the JPL and Lovas catalog in the appropriate format. All
    1297 line catalogs are loaded into a ``linecatalog'' object.
     1284\label{sec:linecat}
     1285\index{Linecatalog}ASAP can load and manipulate line catlogs to
     1286retrieve rest frequencies for \cmd{set\_restfreqs} and for line
     1287identification in the plotter. All line catalogs are loaded into a ``linecatalog'' object.
     1288
     1289No line catalogs are built into ASAP, the user must load a ASCII based
     1290table (which can optionally be saved in an internal format) either of
     1291the users own creation or a standard line catalog such as the JPL line
     1292catalog or Lovas. The ATNF asap ftp area as copies of the JPL and
     1293Lovas catalog in the appropriate format:
     1294
     1295\hspace{1cm}\cmd{ftp://ftp.atnf.csiro.au/pub/software/asap/data}
     1296 
    12981297
    12991298\subsection{Loading a Line Catalog}
    13001299
    1301 \index{Linecatalog|loading}The ASCII text line catalog must have at
     1300\index{Linecatalog!loading}The ASCII text line catalog must have at
    13021301least 4 columns. The first four columns must contain (in order):
    13031302Molecule name, frequency in MHz, frequency error and ``intensity''
     
    13301329\end{verbatim}
    13311330
     1331{\em NOTE:} Due to a bug in ipython, if you do not \cmd{del} the
     1332linecatalog table before quiting asap, you will be left with temporary
     1333files. It is safe to delete these once asap has finished.
     1334
    13321335\subsection{Line selection}
    13331336
    1334 \index{Linecatalog|line selection}The linecatalog has a number of
     1337\index{Linecatalog!line selection}The linecatalog has a number of
    13351338selection functions to select a range of lines from a larger catalog
    13361339(the JPL catalog has $>$180000 lines for
    13371340example). \cmd{set\_frequency\_limits} selects on frequency range,
    13381341\cmd{set\_strength\_limits} selects on intensity while \cmd{set\_name}
    1339 selects on molecule name (wild cards allowed).
     1342selects on molecule name (wild cards allowed). The \cmd{summary}
     1343function lists the currently selected lines.
    13401344
    13411345\begin{verbatim}
     
    13591363\subsubsection{Plotting linecatalog}
    13601364
    1361 \index{Linecatalog|plotting}
     1365\index{Linecatalog!plotting}
    13621366
    13631367The plotter \cmd{plot\_lines} function takes a line catalog as an
     
    13801384
    13811385  ASAP>plotter.plot()                  # Reset plotter
    1382   ASAP>plotter.plot_lines(jpl,doppler=-10,location='Top') # On top with -10 km/s velocity
     1386  ASAP>plotter.plot_lines(jpl,doppler=-10,location='Top')
     1387                             # On top with -10 km/s velocity
    13831388\end{verbatim}
    13841389
    13851390\subsubsection{Setting Rest Frequencies}
    13861391
    1387 \index{Linecatalog|set_restfreq}
     1392\index{Linecatalog!set\_restfreq}A linecatalog can be used as an
     1393argument for \cmd{set\_restfreqs}. If a personal line catalog has been
     1394used (which has the same size as the number of number of IFs) or
     1395linecatalog selection has been used to reduce the number of entries,
     1396the line catalog can be used directly as an argument to
     1397\cmd{set\_restfreqs}, e.g.:
     1398\begin{verbatim}
     1399  ASAP>jpl = linecatalog('jpl.tbl')
     1400  ASAP>jpl.set_frequency_limits(23.66,23.75,'GHz')
     1401  ASAP>data = scantable('data.rpf')
     1402  ASAP>data.set_restfreqs(jpl)
     1403\end{verbatim}
     1404
     1405If a larger linecatalog is used, individual elements can be used. Use
     1406the \cmd{summary} to get the index number of the rest frequency you
     1407wish to use. E.g.:
     1408
     1409\begin{verbatim}
     1410  ASAP>jpl.summary()
     1411  ASAP>data.set_restfreqs([jpl[11],[jpl[21]])
     1412\end{verbatim}
     1413
     1414For data with many IFs, such as from MOPS, the user it is recommended
     1415that the user creates their own line cstalog for the data and use this
     1416to set the rest frequency for each IF.
    13881417
    13891418\section{Fitting}
     
    16451674
    16461675\subsection{Disk Based Processing}
    1647 \index{Scantable|disk based}
    1648 
    1649 Normally scantables exisit entirely in memory during an ASAP
    1650 session. This has the adtantage of speed, but causes limits on the
     1676\index{Scantable!disk based}
     1677
     1678Normally scantables exist entirely in memory during an ASAP
     1679session. This has the advantage of speed, but causes limits on the
    16511680size of the dataset which can be loaded. ASAP can use ``disk based''
    1652 scan tables which
     1681scan tables which cache the bulk of the scantable on disk and require
     1682significantly less memory usage.
     1683
     1684To use disk based tables you either need to change the default in your
     1685\cmd{.asapr} file, e.g.
     1686\begin{verbatim}
     1687   scantable.storage          : disk
     1688\end{verbatim}
     1689
     1690or use set the ``\cmd{rc}'' value while running asap to change this
     1691on-the-fly. E.g.
     1692\begin{verbatim}
     1693  ASAP>rc('scantable',storage='disk')
     1694  ASAP>data = scantable('data.rpf')     # Loaded using disk based table
     1695  ASAP>rc('scantable',storage='memory') # Memory tables will be used now
     1696\end{verbatim}
     1697
     1698Changing the ``\cmd{rc}'' value affects the next time the
     1699\cmd{scantable} constructor is called.
    16531700
    16541701{\bf NOTE: } Currently a bug in ipython means temporary files are not
    16551702cleaned up properly when you exit ASAP. If you use disk based scan
    1656 tables your directory will be left with 'tmp*' directories. These can
     1703tables your directory will be left with 'tabXXXXX\_X' directories. These can
    16571704be safely removed if ASAP is not running.
    16581705
     
    17731820
    17741821\index{Parkes}\index{Polarisation}The following example is processing
    1775 of some Parkes polarmetric observations of OH masers at
     1822of some Parkes polarimetric observations of OH masers at
    177618231.6~GHz. Because digital filters where used in the backend, the
    17771824baselines are stable enough not to require a quotient spectra. The
     
    19491996\index{Functions!summary}%
    19501997\begin{verbatim}
    1951 
    1952     [The scan container]
     1998   [The scan container]
    19531999        scantable           - a container for integrations/scans
    19542000                              (can open asap/rpfits/sdfits and ms files)
     
    19762022            get_abcissa     - get the abcissa values and name for a given
    19772023                              row (time)
     2024            get_column_names - get the names of the columns in the scantable
     2025                               for use with selector.set_query
    19782026            set_freqframe   - set the frame info for the Spectral Axis
    19792027                              (e.g. 'LSRK')
     
    19902038            set_restfreqs   - set a list of rest frequencies
    19912039            flag            - flag selected channels in the data
    1992             lag_flag        - flag specified frequency in the data
    19932040            save            - save the scantable to disk as either 'ASAP',
    19942041                              'SDFITS' or 'ASCII'
     
    20332080     [Selection]
    20342081         selector              - a selection object to set a subset of a scantable
    2035             set_scans          - set (a list of) scans by index
    2036             set_cycles         - set (a list of) cycles by index
     2082           set_cycles         - set (a list of) cycles by index
    20372083            set_beams          - set (a list of) beamss by index
    20382084            set_ifs            - set (a list of) ifs by index
     
    20412087            set_names          - set a selection by name (wildcards allowed)
    20422088            set_tsys           - set a selection by tsys thresholds
     2089            set_query          - set a selection by SQL-like query, e.g. BEAMNO==1
    20432090            reset              - unset all selections
    20442091            +                  - merge to selections
     
    21112158            arrow           - draw arrow annotations either in data or relative
    21122159                              coordinates
    2113             set_abcissa     - specify a user label for the abcissa
    2114             set_ordinate    - specify a user label for the ordinate
    2115             set_layout      - specify the multi-panel layout (rows,cols)
    2116             set_colors      - specify a set of colours to use
    2117             set_linestyles  - specify a set of linestyles to use if only
    2118                               using one color
    2119             set_font        - set general font properties, e.g. 'family'
    2120             set_histogram   - plot in historam style
    2121             set_mask        - set a plotting mask for a specific polarization
    2122             text            - draw text annotations either in data or relative
    2123                               coordinates
     2160            axhline,axvline - draw horizontal/vertical lines
     2161            axhspan,axvspan - draw horizontal/vertical regions
     2162
     2163        xyplotter           - matplotlib/pylab plotting functions
     2164
     2165    [Reading files]
     2166        reader              - access rpfits/sdfits files
    21242167            arrow           - draw arrow annotations either in data or relative
    21252168                              coordinates
     
    21832226histogram rather than lines.}
    21842227
    2185 {\em MALTE TO FIX}
    2186 
    21872228\asaprc{plotter.colours}{}{Set default colours for plotting}
    21882229
     
    22102251\subsection{Installation}
    22112252
    2212 \index{Installation}ASAP depends on a number of third-party libraries which you must
    2213 have installed before attempting to build ASAP. These are:
    2214 
    2215 \begin{itemize}
    2216 \item AIPS++
    2217 \item Boost
    2218 \item Matplotlib
    2219 \item python/ipython
    2220 \end{itemize}
    2221 
    2222 Debian Linux is currently supported and we intend also
    2223 to support other popular Linux flavours, Solaris and Mac.
    2224 
    2225 Of the dependencies, AIPS++ is the most complex to install.
     2253\index{Installation}
     2254
     2255Please refer to the asap wiki for instructions on downloading and/or
     2256building asap from source.
     2257
     2258\hspace{1cm}\cmd{http://www.atnf.csiro.au/computing/software/asap/}
    22262259
    22272260\printindex
Note: See TracChangeset for help on using the changeset viewer.