Changeset 770 for trunk/doc


Ignore:
Timestamp:
12/05/05 11:30:12 (19 years ago)
Author:
mar637
Message:

merge from Release12

Location:
trunk/doc
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/README

    r732 r770  
    1515=======
    1616
    17 To install simply run
    18   ./install.sh
     17To install simply run (as root or 'sudo')
     18  ./bin/install.sh
    1919which will install asap into /usr/local
    2020
  • trunk/doc/cookbook.tex

    r738 r770  
    11\documentclass[11pt]{article}
    22\usepackage{a4}
     3\usepackage{calc}
    34\usepackage[dvips]{graphicx}
    45
     
    1112\setlength{\parskip}{1ex}
    1213
    13 
    14 \title{ATNF Spectral Analysis Package\\Cookbook }
     14\title{ATNF Spectral Analysis Package\\User Guide }
    1515\author{Chris Phillips}
    1616
    17 
    1817\newcommand{\cmd}[1]{{\tt #1}}
     18
     19\newcommand{\asaprc}[3]{
     20  \begin{minipage}[t]{45mm}#1\end{minipage}
     21  \begin{minipage}[t]{30mm}\raggedright #2\end{minipage}\hspace{3mm}
     22  \begin{minipage}[t]{\textwidth-75mm}#3\end{minipage}
     23}
    1924
    2025\begin{document}
     
    2631ASAP is a single dish spectral line processing package currently being
    2732developed by the ATNF. It is intended to process data from all ATNF
    28 antennas, and can probably be used for other antnnas if they can
     33antennas, and can probably be used for other antennas if they can
    2934produce ``Single Dish FITS'' format. It is based on the AIPS++
    3035package.
     
    4550\end{itemize}
    4651
    47 To start asap log onto one of these Linux hosts and  enter
     52To start asap log onto one of these Linux hosts and enter
    4853
    4954\begin{verbatim}
     
    8792There can be many objects of the same type. Each object is referred to
    8893by a variable name made by the user. The name of this variable is not
    89 important and can be set to whatever the user prefers (ie ``s'' and
     94important and can be set to whatever the user prefers (i.e. ``s'' and
    9095``ParkesHOH-20052002'' are equivalent).  However, having a simple and
    9196consistent naming convention will help you a lot.
     
    113118  ASAP> av = scans(msk,weight='tsys')
    114119  ASAP> av = scans(mask=msk,weight='tsys')
    115   ASAP> av = scans(msk,True)
     120  ASAP> av = scans(msk,tsys)
    116121  ASAP> scans.polybaseline(mask=msk, order=0, insitu=True)
    117122  ASAP> scans.polybaseline(msk,0,True)
     
    128133\subsection{Interactive environment}
    129134
    130 ipython has a number of useful interactive features and a few things to be aware
    131 of for the new user.
     135ipython has a number of useful interactive features and a few things
     136to be aware of for the new user.
    132137
    133138\subsubsection{String completion}
     
    157162fail with an syntax error.
    158163
     164\subsubsection{Variable Names}
     165
     166During normal data processing, the user will have to create named
     167variables to hold spectra etc. These must conform to the normal python
     168syntax, specifically they cannot contain ``special'' characters such
     169as \@ \$ etc and cannot start with a number (but can contain numbers).
     170Variable (and function) names are case sensitive.
     171
    159172\subsubsection{Unix Interaction}
    160173
     
    221234  scantable.save             : 'ASAP'
    222235
    223 
    224236  # default frequency frame to set when function
    225237  # scantable.set_freqframe is called
     
    229241  scantable.autoaverage      : True
    230242\end{verbatim}
     243
     244For a complete list of \cmd{.asaprc} values, see the appendix.
    231245
    232246\section{Scantables}
     
    340354
    341355Examples are the selection of beam, IF and polarisation,  spectral unit
    342 (e.g. km/s) frequency reference frame (e.g. BARY) and velocity Doppler
     356(e.g. km/s), frequency reference frame (e.g. BARY) and velocity Doppler
    343357type (e.g. RADIO).
    344358
     
    405419
    406420\begin{verbatim}
    407   # Select for specified source/IF
    408   ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0)
    409 
    410   # Select for all sources and IFs
    411   ASAP> scans.set_restfreqs(freqs=1.667359e9)
    412 \end{verbatim}
    413 
     421  # Set rest frequency for all IFs
     422  ASAP> scans.set_restfreqs(freqs=[1.6654018e9,1.667359e9,])
     423
     424\end{verbatim}
    414425
    415426In both of the above modes, you can also specify the rest frequencies via
     
    422433  ASAP> scans.set_restfreqs(lines=['OH1665','OH1667'])
    423434\end{verbatim}
    424 
    425435
    426436
     
    581591%How and when?
    582592\subsection{Auto quotient}
    583 Quotients can becomputed ``automatically''. This requires the data to have matching source/reference pairs or one refrence for multiple sources.
     593Quotients can be computed ``automatically''. This requires the data to
     594have matching source/reference pairs or one reference for multiple
     595sources. Auto quotient assumes reference scans have a trailing ``\_R''
     596in the source name for data from Parkes and Mopra, and a trailing
     597``e'' or ``w'' for data fro, Tidbinbilla.
    584598
    585599\begin{verbatim}
     
    645659
    646660The default is to use integration time weighting. The alternative is
    647 to use none, variance , Tsys weighting or Tsys \& integration time.
     661to use none, variance, Tsys weighting or Tsys \& integration time.
    648662
    649663\begin{verbatim}
     
    675689
    676690The function \cmd{auto\_poly\_baseline} can be used to automatically
    677 baseline your data with out having to specify channel ranges for
    678 the line free data. It automatically figures out the line-free
    679 emission and fits a polynomial baseline to that data. The user can use
    680 masks to fix the range of channels or velocity range for the fit as
    681 well as mark the band edge as invalid.
     691baseline your data without having to specify channel ranges for the
     692line free data. It automatically figures out the line-free emission
     693and fits a polynomial baseline to that data. The user can use masks to
     694fix the range of channels or velocity range for the fit as well as
     695mark the band edge as invalid.
    682696
    683697Simple example
     
    727741\subsubsection{Brightness Units}
    728742
    729 RPFITS files to not contain any information as to whether the telescope
     743RPFITS files do not contain any information as to whether the telescope
    730744calibration was in units of Kelvin or Janskys.  On reading the data a
    731745default value is set depending on the telescope and frequency of
     
    772786As higher frequencies (particularly $>$20~GHz) it is important to make
    773787corrections for atmospheric opacity and gain-elevation effects.
     788
     789{\em Note that currently the elevation is not written correctly into
     790Tidbinbilla rpfits files. This means that gain-elevation and opacity
     791corrections will not work until a work around is implemented.}
    774792
    775793Gain-elevation curves for some telescopes and frequencies are known to
     
    819837\cmd{perif} argument. By default it will align each source and freqid
    820838separately. This is needed for scan tables containing multiple
    821 sources. However if scan-based Doppler tracking has been made at the observatory,
    822 each row will have a different freqid. In these cases run with
    823 \cmd{perif=True} and all rows of a source will be aligned to the same
    824 frame. In general \cmd{perif=True} will be needed for most
     839sources. However if scan-based Doppler tracking has been made at the
     840observatory, each row will have a different freqid. In these cases run
     841with \cmd{perif=True} and all rows of a source will be aligned to the
     842same frame. In general \cmd{perif=True} will be needed for most
    825843observations as Doppler tracking of some form is made at Parkes, Tid
    826844and Mopra.
     
    927945\section{Plotter}
    928946
    929 Scantable spectra can be plotter at any time. An asapplotter object is
     947Scantable spectra can be plotted at any time. An asapplotter object is
    930948used for plotting, meaning multiple plot windows can be active at the
    931949same time. On start up a default asapplotter object is created called
     
    11551173\subsection{Simple Calibration}
    11561174
    1157 {\em Currently the receiver position angle is not stored in the RPFITS
    1158 file. This severely hampers correct handling of polarimetry. In the future
    1159 we aim to define a general framework and populate the RPFITS files
    1160 with the data required for transparent polarimetric calibration.}
     1175{\em Currently the receiver position angle is not read from the RPFITS
     1176file and a position angle of zero is assumed. This severely hampers
     1177correct handling of polarimetry. In the future we aim to define a
     1178general framework and populate the RPFITS files with the data required
     1179for transparent polarimetric calibration.}
    11611180
    11621181It is possible that there is a phase offset between polarisation which
     
    11991218
    12001219\begin{verbatim}
    1201   ASAP> plotter.set_cursor(pol=[``I'',''Q'']
    1202   ASAP> plotter.set_cursor(pol=[``RR'',''LL'']
    1203   ASAP> plotter.set_cursor(pol=[``XX'',''YY'']
    1204   ASAP> plotter.set_cursor(pol=[``I'',''Plinear'']
     1220  ASAP> plotter.set_cursor(pol=``I Q'')
     1221  ASAP> plotter.set_cursor(pol=``RR LL'')
     1222  ASAP> plotter.set_cursor(pol=``XX YY'')
     1223  ASAP> plotter.set_cursor(pol=``I Plinear'')
    12051224\end{verbatim}
    12061225
     
    12201239\end{verbatim}
    12211240
    1222 \section{Function Summary}
     1241
     1242\section{Scantable Mathematics}
     1243
     1244It is possible to to simple mathematics directly on scantables from
     1245the command line using the \cmd{+, -, *, /} operators as well as their
     1246cousins \cmd{+=, -= *=, /=}. This works between two scantables or a
     1247scantable and a float. (Note that it does not work for integers).
     1248
     1249\begin{verbatim}
     1250  ASAP> sum = scan1+scan2
     1251  ASAP> scan2 = scan1+2.0
     1252  ASAP> scan *= 1.05
     1253\end{verbatim}
     1254
     1255\section{Scripting}
     1256
     1257Because asap is based on python, it easy for the user write their own
     1258scripts and functions to process data. This is highly recommended as
     1259most processing of user data could then be done in a couple of steps
     1260using a few simple user defined functions. A Python primer is beyond
     1261the scope of this userguide. See the asap home pages for a scripting
     1262tutorial or the main python website for comprehensive documentation.
     1263
     1264\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
     1265\hspace{1cm} http://www.python.org/doc/Introduction.html
     1266
     1267\subsection{Running scripts}
     1268
     1269The asap global function \cmd{execfile} reads the named text file and
     1270executes the contained python code. This file can either contain
     1271function definitions which will be used in subsequent processing or
     1272just a set of commands to process a specific dataset.
     1273
     1274\subsection{asapuserfuncs.py}
     1275
     1276The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
     1277asap is started. The user can use this to define a set of user
     1278functions which are automatically available each time asap is
     1279used. The \cmd{execfile} function can be called from within this file.
     1280
     1281\section{Worked examples}
     1282
     1283In the following section a few examples of end-to-end processing of
     1284some data in asap are given.
     1285
     1286\subsection{Mopra}
     1287
     1288\subsection{Parkes Polarimetry}
     1289
     1290The following example is processing of some Parkes polarmetric
     1291observations of OH masers at 1.6~GHz. Because digital filters where
     1292used in the backend, the baselines are stable enough not to require a
     1293quotient spectra. The 4~MHz bandwidth is wide enough to observe both
     1294the 1665 and 1667~MHz OH maser transitions. Each source was observed
     1295once for about 10 minutes. Tsys information was not written to the
     1296rpfits file (a nominal 25K values was used), so the amplitudes need
     1297to be adjusted based on a separate log file. A simple user function is
     1298used to simplify this, contained in a file called mypol.py:
     1299
     1300\begin{verbatim}
     1301def xyscale(data,xtsys=1.0,ytsys=1.0,nomtsys=25.0) :
     1302
     1303 data.set_cursor(pol=0)
     1304 data.scale(xtsys/nomtsys,allaxes=False)
     1305
     1306 data.set_cursor(pol=1)
     1307 data.scale(ytsys/nomtsys,allaxes=False)
     1308
     1309 data.set_cursor(pol=2)
     1310 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
     1311
     1312 data.set_cursor(pol=3)
     1313 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
     1314\end{verbatim}
     1315
     1316The typical asap session would be
     1317
     1318\begin{verbatim}
     1319 
     1320# Remind ourself the name of the rpfits files
     1321ls
     1322
     1323# Load data from an rpfits file
     1324d1665 = scantable('2005-10-27_0154-P484.rpf')
     1325
     1326# Check what we have just loaded
     1327d1665.summary
     1328
     1329# View the data in velocity
     1330d1665.set_unit('km/s')
     1331d1665.set_freqframe('LSRK')
     1332
     1333# Correct for the known phase offset in the crosspol data
     1334d1665.rotate_xyphase(-4)
     1335
     1336# Create a copy of the data and set the rest frequency to the 1667 MHz
     1337# transition
     1338d1667 = d1665.copy()
     1339d1667.set_restfreqs(lines=['OH1667'])
     1340d1667.summary
     1341
     1342# Copy out the scan we wish to process
     1343g351_5 = d1665.get_scan('351p160')
     1344g351_7 = d1667.get_scan('351p160')
     1345
     1346# Plot the data
     1347plotter.plot(g351_5,g351_7) # Only shows one panel
     1348
     1349# Tell the plotter to stack polarisation and panel scans
     1350plotter.set_mode('p','s')
     1351
     1352# Correct for the Tsys using our predefined function
     1353execfile('mypol.py') # Read in the function
     1354xyscale(g351_5,23.2,22.7) # Execute it on the data
     1355xyscale(g351_7,23.2,22.7)
     1356
     1357# Only plot the velocity range of interest
     1358plotter.set_range(-30,10)
     1359
     1360# Baseline the data
     1361msk = g351_5.create_mask([-20,-15],[0,5])
     1362g351_5.poly_baseline(msk,1)
     1363msk = g351_7.create_mask([-20,-15],[0,5])
     1364g351_7.poly_baseline(msk,1)
     1365
     1366# Update the plot with the baselined data
     1367plotter.plot()
     1368
     1369# Look at the various polarisation products
     1370plotter.set_cursor(pol='RR LL')
     1371plotter.set_cursor(pol='I Plinear')
     1372plotter.set_cursor(pol='I Q U V')
     1373
     1374# Save the plot as postscript
     1375plotter.save('g361_stokes.ps')
     1376
     1377# Save the process spectra
     1378g351_5.save('junk5.asap')
     1379g351_7.save('junk7.asap')
     1380
     1381\end{verbatim}
     1382
     1383\subsection{Tidbinbilla}
     1384
     1385The following example is processing of some Tidbinbilla observations
     1386of NH$_3$ at 12~mm. Tidbinbilla has (at the time of observations) a
     1387single polarisation, but can process two IFs simultaneously. In the
     1388example, the first half of the observation was observing the (1,1) and
     1389(2,2) transitions simultaneously). The second half observed only the
     1390(4,4) transition due to bandwidth limitations. The data is position
     1391switched, observing first an reference to the west, then the source
     1392twice and finally reference to the east.
     1393
     1394\begin{verbatim}
     1395
     1396# Load the rpfits file and inspect
     1397d = scantable('2003-03-16_082048_t0002.rpf')
     1398print d
     1399
     1400# Make the quotient spectra
     1401q = d.auto_quotient()
     1402print q
     1403
     1404# Plot/select in velocity
     1405q.set_freqframe('LSRK')
     1406q.set_unit('km/s')
     1407
     1408# Seperate data from the (1,1)&(2,2) and (4,4) transitions
     1409g1 = q.get_scan(range(6))     # Rows 0..5
     1410g2 = q.get_scan(range(6,12))  # Rows 6..11
     1411
     1412# Align data in velocity
     1413g1.freq_align(perif=True)
     1414g2.freq_align(perif=True)
     1415
     1416# Average individual scans
     1417a1 = g1.average_time()
     1418a2 = g2.average_time()
     1419
     1420# Rpfits file only contrains a single rest frequency. Set both
     1421a1.set_restfreqs(freqs= [23694.4700e6,23722.6336e6])
     1422
     1423plotter.plot(a1,a2)
     1424plotter.set_mode('i','s')
     1425x = raw_input()
     1426
     1427a1.auto_poly_baseline()
     1428a2.auto_poly_baseline()
     1429
     1430plotter.plot()
     1431
     1432a1.smooth('gauss',5)
     1433a2.smooth('gauss',5)
     1434plotter.plot()
     1435
     1436\end{verbatim}
     1437
     1438\newpage
     1439
     1440\section{Appendix}
     1441
     1442\subsection{Function Summary}
    12231443
    12241444\begin{verbatim}
     
    13411561        execfile            - execute an asap script, e.g. execfile('myscript')
    13421562        list_rcparameters   - print out a list of possible values to be
    1343                               put into $HOME/.asaprc
     1563                              put into \$HOME/.asaprc
    13441564        mask_and,mask_or,
    13451565        mask_not            - boolean operations on masks created with
     
    13591579\end{verbatim}
    13601580
    1361 \section{Scantable Mathematics}
    1362 
    1363 It is possible to to simple mathematics directly on scantables from
    1364 the command line using the \cmd{+, -, *, /} operators as well as their
    1365 cousins \cmd{+=, -= *=, /=}. This works between two scantables or a
    1366 scantable and a float. (Note that it does not work for integers).
    1367 
    1368 \begin{verbatim}
    1369   ASAP> sum = scan1+scan2
    1370   ASAP> scan2 = scan1+2.0
    1371   ASAP> scan *= 1.05
    1372 \end{verbatim}
    1373 
    1374 %\section{Scripting}
    1375 
    1376 %Malte to add something
    1377 
    1378 \section{Appendix}
    1379 
    13801581\subsection{Installation}
    13811582
     
    13991600\subsection{.asaprc settings}
    14001601
     1602\asaprc{verbose}{{\bf True}/False}{Print verbose output}
     1603
     1604\asaprc{insitu}{{\bf True}/False}{Apply operations on the input
     1605scantable or return new one}
     1606
     1607% plotting
     1608
     1609\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
     1610
     1611\asaprc{plotter.gui}{{\bf True}/False}{Do we want a GUI or plot to a
     1612file}
     1613
     1614\asaprc{plotter.stacking}{{\bf Pol} Beam IF Scan Time}{Default mode for
     1615colour stacking}
     1616
     1617\asaprc{plotter.panelling}{Pol Beam IF {\bf Scan} Time}{Default mode
     1618for panelling}
     1619
     1620\asaprc{plotter.ganged}{{\bf True}/False}{Push panels together, to
     1621share axislabels}
     1622
     1623\asaprc{plotter.decimate}{True/{\bf False}}{Decimate the number of
     1624points plotted by a factor of nchan/1024}
     1625
     1626% default colours/linestyles
     1627%\asaprc{plotter.colours}{.}{.}
     1628%\asaprc{plotter.linestyles{.}{.}
     1629
     1630% scantable
     1631\asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
     1632format when saving}
     1633
     1634\asaprc{scantable.autoaverage}{{\bf True}/False}{Auto averaging on
     1635read}
     1636
     1637\asaprc{scantable.freqframe}{{\bf LSRK} TOPO BARY etc}{default
     1638frequency frame to set when function scantable.set\_freqframe is
     1639called}
     1640
     1641\asaprc{scantable.allaxes}{{\bf True}/False}{Apply action to all axes
     1642not just the cursor location}
     1643
     1644\asaprc{scantable.plotter}{{\bf True}/False}{Use internal plotter}
     1645
     1646\asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level
     1647of information printed by summary}
     1648
    14011649\end{document}
     1650
Note: See TracChangeset for help on using the changeset viewer.