Changeset 1217 for trunk/doc


Ignore:
Timestamp:
08/30/06 13:29:25 (18 years ago)
Author:
mar637
Message:

Merge from Release2.1.0b tag

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/userguide.tex

    r1064 r1217  
    1313\setlength{\parskip}{1ex}
    1414
    15 \title{ATNF Spectral Analysis Package\\User Guide v2.0 }
     15\title{ATNF Spectral Analysis Package\\User Guide v2.1\\DRAFT }
    1616\author{Chris Phillips}
    1717
     
    2424}
    2525
     26\newcommand{\commanddef}[3]{
     27  \begin{minipage}[t]{27mm}\tt #1\end{minipage}\hspace{3mm}
     28  \begin{minipage}[t]{\textwidth-30mm}#2 \\ \tt #3\end{minipage}
     29}
     30
     31\newcommand{\bigcommanddef}[3]{
     32  \begin{minipage}[t]{45mm}\tt #1\end{minipage}\hspace{3mm}
     33  \begin{minipage}[t]{\textwidth-47mm}#2 \\ \tt #3\end{minipage}
     34}
     35
    2636\makeindex
    27 
    2837
    2938\begin{document}
     
    3948package.
    4049
    41 This userguide has been updated for the ASAP 2.0 release which has a
    42 number of significant changes which affect the user interface. Please
    43 report any mistakes you find.
     50This userguide is being updated for the ASAP 2.1. Please report any
     51mistakes you find.
    4452
    4553\section{Installation and Running}
     
    5361\item Mopra - use host {\tt minos}
    5462\end{itemize}
     63
     64Or use your own Linux desktop.
     65
     66{\em Note. ASAP2.1 only runs on ATNF Linux machines which have been
     67updated to Debian Sarge and are using the ``DEBIANsarge''
     68/usr/local. If your favourite machine has not been upgraded, send a
     69request your your friendly IT support.}
    5570
    5671\index{Running}To start asap log onto one of these Linux hosts and enter
     
    266281
    267282The building block of a scantable is an integration, which is a single
    268 row of a scantable. Each row contains just one spectrum for each beam, IF and
    269 polarisation. For example Parkes multibeam data would contain many
    270 beams, one IF and 2-4 polarisations, while the new Mopra 8-GHz
    271 filterbank will eventually produce one beam, many IFs, and 2-4
    272 polarisations. All of the combinations of Beams/IFs an Polarisations are
     283row of a scantable. Each row contains just one spectrum for each beam,
     284IF and polarisation. For example Parkes OH-multibeam data would
     285normally contain 13 beams, 1 IF and 2 polarisations, Parkes
     286methanol-multibeam data would contain 7 beams, 2 IFs and 2
     287polarisations while the Mopra 8-GHz MOPDS filterbank will produce one
     288beam, many IFs, and 2-4 polarisations.
     289
     290All of the combinations of Beams/IFs an Polarisations are
    273291contained in seperate rows. These rows are grouped in cycles (same time stamp).
    274292
    275 A collection of cycles for one source is termed
    276 a scan (and each scan has a unique numeric identifier, the SCANNO). A
    277 scantable is then a collection  of one or more scans. If you have
    278 scan-averaged your data in time, i.e. you have averegaed all cycles within
    279 a scan, then each scan would hold just one (averaged) integration.
    280 
    281 Many of the functions which work on scantables can either return a
    282 new scantable with modified data or change the scantable insitu. Which
     293A collection of cycles for one source is termed a scan (and each scan
     294has a unique numeric identifier, the SCANNO). A scantable is then a
     295collection of one or more scans. If you have scan-averaged your data
     296in time, i.e. you have averegaed all cycles within a scan, then each
     297scan would hold just one (averaged) integration.
     298
     299Many of the functions which work on scantables can either return a new
     300scantable with modified data or change the scantable insitu. Which
    283301method is used depends on the users preference. The default can be
    284302changed via the {\tt .asaprc} resource file.
     
    309327The data are stored in columns (the length of a column is the number of
    310328rows/spectra of course).
    311 
    312329
    313330Two important columns are those that describe the frequency setup.  We mention
     
    476493\end{verbatim}
    477494
    478 {\em Currently the following is not implemented}
     495{\em Currently the following is not implemented
    479496
    480497In both of the above modes, you can also specify the rest frequencies via
     
    486503  ASAP> scans.set_restfreqs(freqs=['OH1665','OH1667'])
    487504\end{verbatim}
    488 
     505}
    489506
    490507\subsubsection{Masks}
     
    649666\end{verbatim}
    650667
    651 %If this is not sufficient the following alternative method can be used.
    652 %
    653 %\subsection{Separate reference and source observations}
    654 %
    655 %\index{Quotient spectra}Most data from ATNF observatories
    656 %distinguishes on and off source data using the file name. This makes
    657 %it easy to create two scantables with the source and reference
    658 %data. As long as there was exactly one reference observation for each
    659 %on source observation for following method will work.
    660 %
    661 %For Mopra and Parkes data:
    662 %\begin{verbatim}
    663 %  ASAP> r = scans.get_scan('*_R')
    664 %  ASAP> s = scans.get_scan('*_S')
    665 %\end{verbatim}
    666 %
    667 %For Tidbinbilla data
    668 %\begin{verbatim}
    669 %  ASAP> r = scans.get_scan('*_[ew]')
    670 %  ASAP> s = scans.get_scan('*_[^ew]')
    671 %\end{verbatim}
    672 %
    673 %\subsection{Make the quotient spectra}
    674 %
    675 %Use the quotient function
    676 %
    677 %\begin{verbatim}
    678 %  ASAP> q = s.quotient(r)
    679 %\end{verbatim}
    680 %
    681 %This uses the rows in scantable \cmd{r} as reference spectra for the
    682 %rows in scantable \cmd{s}. Scantable \cmd{r} must have either 1 row
    683 %(which is applied to all rows in \cmd{s}) or both scantables must have
    684 %the same number of rows.
     668If this is not sufficient the following alternative method can be used.
     669
     670\subsection{Separate reference and source observations}
     671
     672\index{Quotient spectra}Most data from ATNF observatories
     673distinguishes on and off source data using the file name. This makes
     674it easy to create two scantables with the source and reference
     675data. As long as there was exactly one reference observation for each
     676on source observation for following method will work.
     677
     678For Mopra and Parkes data:
     679\begin{verbatim}
     680  ASAP> r = scans.get_scan('*_R')
     681  ASAP> s = scans.get_scan('*_S')
     682\end{verbatim}
     683
     684For Tidbinbilla data
     685\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
     692Use the quotient function
     693
     694\begin{verbatim}
     695  ASAP> q = s.quotient(r)
     696\end{verbatim}
     697
     698This uses the rows in scantable \cmd{r} as reference spectra for the
     699rows 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
     701the same number of rows.
    685702
    686703\subsection{Time average separate scans}
     
    702719
    703720The default is to use integration time weighting. The alternative is
    704 to use none, variance, Tsys weighting or Tsys \& integration time.
     721to use none, variance, Tsys weighting, Tsys \& integration time or
     722median averaging.
    705723
    706724\begin{verbatim}
     
    808826  # Or in two steps
    809827  ASAP> scans = scantable('2004-11-23_1841-P484.rpf')
    810   ASAP> scans.set_fluxunit('Jy)
     828  ASAP> scans.set_fluxunit('Jy')
     829\end{verbatim}
     830
     831\subsubsection{Feed Polarisation}
     832
     833\index{Brightness Units}The RPFITS files also do not contain any
     834information as to the feed polarisation. ASAP will set a default based
     835on the antenna, but this will often be wrong the data has been read,
     836the default can be changed using the \cmd{set\_feedtype} function with
     837an argument of \cmd{'linear'} or \cmd{'circular'}.
     838
     839E.g:
     840
     841\begin{verbatim}
     842  ASAP> scans = scantable('2004-11-23_1841-P484.rpf')
     843  ASAP> scans.set_feedtype('circular')
    811844\end{verbatim}
    812845
     
    9961029\end{verbatim}
    9971030
    998 
    9991031\section{Plotter}
    10001032
     
    11351167  ASAP> plotter.save('myplot.ps')
    11361168  ASAP> plotter.save('myplot.png', dpi=80)
     1169\end{verbatim}
     1170
     1171\subsection{Plotter Customisation}
     1172
     1173The plotter allows the user to change most properties such as text
     1174size and colour. The \cmd{commands} funcation and {\cmd help\
     1175asapplotter} list all the possible commands that can be used with the
     1176plotter.
     1177
     1178\commanddef{set\_colors}{Change the default colours used for line
     1179plotting. Colours can be given either by name, using the html standard
     1180(e.g. red, blue or hotpink), or hexadecimal code (e.g. for black
     1181\#000000). If less colours are specified than lines plotted , the
     1182plotter cycles through the colours. Example:} {ASAP>
     1183plotter.set\_colors('red blue green')\\ ASAP>
     1184plotter.set\_colors(`\#0000 blue \#FF00FF')\\ }
     1185
     1186\commanddef{set\_linestyles}{Change the line styles used for
     1187plots. Allowable values are 'line', 'dashed', 'dotted', 'dashdot',
     1188'dashdotdot' and 'dashdashdot. Example: }{
     1189  ASAP> plotter.set\_linestyles('line dash cotted datshot.)\\
     1190  ASAP> plotter.set\_font(size=10)\\
     1191}
     1192
     1193\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')\\
     1197}
     1198
     1199\commanddef{set\_layout}{Change the multi-panel layout, ie now many
     1200  rows and columns}{
     1201  ASAP> plotter.set\_layout(3,2)
     1202}
     1203
     1204\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
     1211}
     1212
     1213\commanddef{set\_title}{Set the plot title. If multiple panels are
     1214  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)\\
     1217}
     1218
     1219\subsection{Plotter Annotations}
     1220
     1221The plotter allows various annontations (lines, arrows, text and
     1222``spans'') to be added to the plot. These annotations are
     1223``temporary'', when the plotter is next refreshed
     1224(e.g. \cmd{plotter.plot} or \cmd{plotter.set\_range}) the annotations
     1225will be removed.
     1226
     1227\bigcommanddef{arrow(x,y,x+dx,y+dy)}{Draw an arrow from a specifed
     1228\cmd{(x,y)} position to \cmd{(x+dx, y+dy)}. The values are in world
     1229coordinates. \em {HOW TO SET ARROW HEAD??}}{
     1230  ASAP> plotter.arrow(-40,7,35,0)
     1231}
     1232
     1233\bigcommanddef{axhline(y, xmin, xmax)}{Draw a horizontal line at the
     1234specifed \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
     1236while 1.0 is the right side of the plot.}{
     1237 ASAP> plotter.axhline(6.0,0.2,0.8)
     1238}
     1239
     1240\bigcommanddef{avhline(x, ymin, ymax)}{Draw a vertical line at the
     1241specifed \cmd{x} position (in world coordinates) between \cmd{ymin}
     1242and \cmd{ymax} (in relative coordinates, ie 0.0 is the left hand edge
     1243of the plot while 1.0 is the right side of the plot).}{
     1244 ASAP> plotter.axvline(-50.0,0.1,1.0)
     1245}
     1246
     1247\bigcommanddef{axhspan(ymin, ymax, \\ \hspace*{20mm}xmin,
     1248 xmax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
     1249 \cmd{ymax} are given in world coordnates while \cmd{xmin} and
     1250 \cmd{xmax} are given in relative coordinates}{
     1251ASAP> plotter.axhspan(2,4,0.25,0.75)
     1252}
     1253
     1254\bigcommanddef{axvspan(xmin, xmax, \\ \hspace*{20mm} ymin,
     1255 ymax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
     1256 \cmd{ymax} are given in relative coordnates while \cmd{xmin} and
     1257 \cmd{xmax} are given in world coordinates}{
     1258ASAP> plotter.axvspan(-50,60,0.2,0.5)
     1259}
     1260
     1261\bigcommanddef{text(x, y, str)}{Place the string \cmd{str} at the
     1262 given \cmd{(x,y)} position in world coordinates.}{
     1263ASAP>plotter.text(-10,7,"CO")
     1264}
     1265
     1266
     1267
     1268These functions all take a set of \cmd{kwargs} commands. These can be
     1269used to set colour, linewidth fontsize etc. These are standard
     1270matplotlib settings. Common ones include:
     1271
     1272\begin{tabular}{ll}
     1273 \tt color  \\
     1274 \tt linewidth \\
     1275 \tt fontsize \\
     1276 \tt fontname & Sans, Helvetica, Courier, Times etc\\
     1277 \tt rotation & Text rotation (horizontal, vertical) \\
     1278 \tt alpha & The alpha transparency on 0-1 scale\\
     1279\end{tabular}
     1280
     1281Examples:
     1282\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)
    11371285\end{verbatim}
    11381286
     
    13471495\end{verbatim}
    13481496
     1497\section{Specialised Processing}
     1498
     1499\subsection{Multibeam MX mode}
     1500
     1501MX mode is a specific observing approach with a multibeam where a
     1502single source is observed cycling through each beam. The scans when
     1503the beam is off source is used as a reference for the onsource
     1504scan. The function \cmd{mx\_quotient} is used to make a quotient
     1505spectrum from an MX cycle. This works averaging the ``off-source''
     1506scans for each beam (either a median average or mean) and using this
     1507as a reference scan in a normal quotient (for each beam). The final
     1508spectrum for each beam is returned on a new scantable containing
     1509single scan (it the scan numbers are re-labelled to be the same). Note
     1510that the current version of \cmd{mx\_quotient} only handles a single
     1511MX cycle, ie if each beam has observed the source multiple times you
     1512will need to use the selector object multiple times to select a single
     1513MX cycle, run \cmd{mx\_quotient} for each cycle then merge the
     1514resulting scan tables back together.
     1515
     1516Example:
     1517
     1518\begin{verbatim}
     1519  ASAP> scans = scantable('mydata.rpf')
     1520  ASAP> q = scans.mx_quotient()
     1521  ASAP> plotter.plot(q)
     1522\end{verbatim}
     1523
     1524The function \cmd{average\_beam} averages multiple beam data
     1525together. This is need if MX mode has been used to make a long
     1526integration on a single source. E.g.
     1527
     1528\begin{verbatim}
     1529  ASAP> av = q.average_beam()
     1530\end{verbatim}
     1531
     1532\subsection{Frequency Switching}
     1533
     1534{\em FILL ME IN}
     1535
    13491536\section{Scantable Mathematics}
    13501537
     
    16391826\index{Functions!summary}%
    16401827\begin{verbatim}
    1641 ASAP> commands()
     1828
    16421829    [The scan container]
    16431830        scantable           - a container for integrations/scans
     
    16461833            get_scan        - gets a specific scan out of a scantable
    16471834                              (by name or number)
     1835            drop_scan       - drops a specific scan out of a scantable
     1836                              (by number)
    16481837            set_selection   - set a new subselection of the data
    16491838            get_selection   - get the current selection object
     
    16691858            set_dirframe    - set the frame for the direction on the sky
    16701859            set_instrument  - set the instrument name
     1860            set_feedtype    - set the feed type
    16711861            get_fluxunit    - get the brightness flux unit
    16721862            set_fluxunit    - set the brightness flux unit
     
    16761866            get_restfreqs   - get the current list of rest frequencies
    16771867            set_restfreqs   - set a list of rest frequencies
    1678             flag_spectrum   - flag data
    1679             save            - save the scantable to disk as either 'ASAP'
    1680                               or 'SDFITS'
     1868            flag            - flag selected channels in the data
     1869            lag_flag        - flag specified frequency in the data
     1870            save            - save the scantable to disk as either 'ASAP',
     1871                              'SDFITS' or 'ASCII'
    16811872            nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
    16821873            nscan           - the number of scans in the scantable
     
    16871878                              or a list of scans
    16881879            average_pol     - average the polarisations together.
    1689                               The dimension won't be reduced and
    1690                               all polarisations will contain the
    1691                               averaged spectrum.
     1880            average_beam    - average the beams together.
    16921881            convert_pol     - convert to a different polarisation type
    16931882            auto_quotient   - return the on/off quotient with
    1694                               automatic detection of the on/off scans
    1695                               (matched pairs and 1 off - n on)
    1696             scale           - return a scan scaled by a given factor
    1697             add             - return a scan with given value added
     1883                              automatic detection of the on/off scans (closest
     1884                              in time off is selected)
     1885            mx_quotient     - Form a quotient using MX data (off beams)
     1886            scale, *, /     - return a scan scaled by a given factor
     1887            add, +, -       - return a scan with given value added
    16981888            bin             - return a scan with binned channels
    16991889            resample        - return a scan with resampled channels
     
    17081898                              units
    17091899            freq_align      - align spectra in frequency frame
     1900            invert_phase    - Invert the phase of the cross-correlation
     1901            swap_linears    - Swap XX and YY
    17101902            rotate_xyphase  - rotate XY phase of cross correlation
    17111903            rotate_linpolphase - rotate the phase of the complex
     
    17161908            stddev          - Determine the standard deviation of the current
    17171909                              beam/if/pol
     1910     [Selection]
     1911         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
     1914            set_beams          - set (a list of) beamss by index
     1915            set_ifs            - set (a list of) ifs by index
     1916            set_polarisations  - set (a list of) polarisations by name
     1917                                 or by index
     1918            set_names          - set a selection by name (wildcards allowed)
     1919            set_tsys           - set a selection by tsys thresholds
     1920            reset              - unset all selections
     1921            +                  - merge to selections
    17181922
    17191923     [Math] Mainly functions which operate on more than one scantable
     
    17241928            simple_math     - simple mathematical operations on two scantables,
    17251929                              'add', 'sub', 'mul', 'div'
     1930            quotient        - build quotient of the given on and off scans
     1931                              (matched pairs and 1 off/n on are valid)
     1932            merge           - merge a list of scantables
     1933
     1934     [Line Catalog]
     1935        linecatalog              - a linecatalog wrapper, taking an ASCII or
     1936                                   internal format table
     1937            summary              - print a summary of the current selection
     1938            set_name             - select a subset by name pattern, e.g. '*OH*'
     1939            set_strength_limits  - select a subset by line strength limits
     1940            set_frequency_limits - select a subset by frequency limits
     1941            reset                - unset all selections
     1942            save                 - save the current subset to a table (internal
     1943                                   format)
     1944            get_row              - get the name and frequency from a specific
     1945                                   row in the table
    17261946     [Fitting]
    17271947        fitter
     
    17461966                              called 'plotter'
    17471967            plot            - plot a scantable
     1968            plot_lines      - plot a linecatalog overlay
    17481969            save            - save the plot to a file ('png' ,'ps' or 'eps')
    17491970            set_mode        - set the state of the plotter, i.e.
     
    17601981            set_linestyles  - specify a set of linestyles to use if only
    17611982                              using one color
     1983            set_font        - set general font properties, e.g. 'family'
     1984            set_histogram   - plot in historam style
    17621985            set_mask        - set a plotting mask for a specific polarization
     1986            text            - draw text annotations either in data or relative
     1987                              coordinates
     1988            arrow           - draw arrow annotations either in data or relative
     1989                              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
     2001            arrow           - draw arrow annotations either in data or relative
     2002                              coordinates
     2003            axhline,axvline - draw horizontal/vertical lines
     2004            axhspan,axvspan - draw horizontal/vertical regions
     2005
     2006        xyplotter           - matplotlib/pylab plotting functions
    17632007
    17642008    [Reading files]
     
    17802024        execfile            - execute an asap script, e.g. execfile('myscript')
    17812025        list_rcparameters   - print out a list of possible values to be
    1782                               put into $HOME/.asaprc
     2026                              put into .asaprc
     2027        rc                  - set rc parameters from within asap
    17832028        mask_and,mask_or,
    17842029        mask_not            - boolean operations on masks created with
    17852030                              scantable.create_mask
    1786 
    1787     Note:
    1788         How to use this with help:
    1789                                          # function 'summary'
    1790         [xxx] is just a category
    1791         Every 'sub-level' in this list should be replaces by a '.' Period when
    1792         using help
    1793         Example:
    1794             ASAP> help scantable # to get info on ths scantable
    1795             ASAP> help scantable.summary # to get help on the scantable's
    1796             ASAP> help average_time
    1797 
    1798 
    17992031\end{verbatim}
    18002032
     
    18082040scantable or return new one}
    18092041
    1810 % plotting
    1811 
    18122042\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
    18132043
     
    18272057points plotted by a factor of nchan/1024}
    18282058
    1829 % default colours/linestyles
    1830 %\asaprc{plotter.colours}{.}{.}
    1831 %\asaprc{plotter.linestyles{.}{.}
     2059\asaprc{plotter.histogram}{True/{\bf False}}{Plot spectrum using
     2060histogram rather than lines.}
     2061
     2062{\em MALTE TO FIX}
     2063
     2064\asaprc{plotter.colours}{}{Set default colours for plotting}
     2065
     2066\asaprc{plotter.colours}{}{Set default line styles}
     2067
     2068\asaprc{plotter.papersze}{{\bf A4}}{}
    18322069
    18332070% scantable
     
    18412078frequency frame to set when function scantable.set\_freqframe is
    18422079called or the data is imported}
     2080
     2081\asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level
     2082of information printed by summary}
     2083
     2084\asaprc{scantable.storage}{{\bf memory}/disk}{Storage of scantables in
     2085memory of via based disk tables}
    18432086
    18442087\subsection{Installation}
Note: See TracChangeset for help on using the changeset viewer.