source: branches/Release2.1/doc/userguide.tex@ 1604

Last change on this file since 1604 was 1275, checked in by phi196, 18 years ago

Removed 'FITS' export example

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 79.4 KB
RevLine 
[534]1\documentclass[11pt]{article}
2\usepackage{a4}
[770]3\usepackage{calc}
[534]4\usepackage[dvips]{graphicx}
[794]5\usepackage{makeidx}
[534]6
7% Adjust the page size
8\addtolength{\oddsidemargin}{-0.4in}
9\addtolength{\evensidemargin}{+0.4in}
10\addtolength{\textwidth}{+0.8in}
11
12\setlength{\parindent}{0mm}
13\setlength{\parskip}{1ex}
14
[1215]15\title{ATNF Spectral Analysis Package\\User Guide v2.1\\DRAFT }
[534]16\author{Chris Phillips}
17
18\newcommand{\cmd}[1]{{\tt #1}}
19
[770]20\newcommand{\asaprc}[3]{
21 \begin{minipage}[t]{45mm}#1\end{minipage}
22 \begin{minipage}[t]{30mm}\raggedright #2\end{minipage}\hspace{3mm}
23 \begin{minipage}[t]{\textwidth-75mm}#3\end{minipage}
24}
25
[1215]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
[794]36\makeindex
37
[534]38\begin{document}
39
40\maketitle
41
42\section{Introduction}
43
[544]44ASAP is a single dish spectral line processing package currently being
45developed by the ATNF. It is intended to process data from all ATNF
[770]46antennas, and can probably be used for other antennas if they can
[544]47produce ``Single Dish FITS'' format. It is based on the AIPS++
48package.
49
[1266]50This userguide has been updated for the ASAP 2.1. Please report any
[1215]51mistakes you find.
[534]52
[544]53\section{Installation and Running}
[534]54
[738]55Currently there are installations running on Linux machines at
[534]56
57\begin{itemize}
58\item Epping - use hosts {\tt draco} or {\tt hydra}
59\item Narrabri - use host {\tt kaputar}
[537]60\item Parkes - use host {\tt bourbon}
[534]61\item Mopra - use host {\tt minos}
62\end{itemize}
63
[1215]64Or use your own Linux desktop.
65
66{\em Note. ASAP2.1 only runs on ATNF Linux machines which have been
[1266]67updated to Debian Sarge and are using the ``DEBIANSarge''
[1215]68/usr/local. If your favourite machine has not been upgraded, send a
[1266]69request to your friendly IT support. At the time of writing asap 2.1
[1265]70does not run on hydra, bourbon or kaputar.}
[1215]71
[794]72\index{Running}To start asap log onto one of these Linux hosts and enter
[534]73
74\begin{verbatim}
75 > cd /my/data/directory
[966]76 > asap
[534]77\end{verbatim}
78
[1266]79This starts ASAP. To quit, you need to type \verb+^+-d (control-d) or
80type \cmd{\%Exit}.
[534]81
82\section{Interface}
83
[1064]84\index{Interface}ASAP is written in C++ and python. The user interface
85uses the ``ipython'' interactive shell, which is a simple interactive
86interface to python. The user does not need to understand python to
87use this, but certain aspects python affect what the user can do. The
88current interface is object oriented.
[534]89
90\subsection {Integer Indices are 0-relative}
91
92Please note, all integer indices in ASAP and iPython are {\bf 0-relative}.
93
94\subsection{Objects}
[794]95\index{objects}
[534]96The ASAP interface is based around a number of ``objects'' which the
97user deals with. Objects range from the data which have been read from
98disk, to tools used for fitting functions to the data. The following
99main objects are used :
100
[1266]101\begin{tabular}{ll}
[534]102
[1266]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}
113
[738]114There can be many objects of the same type. Each object is referred to
[534]115by a variable name made by the user. The name of this variable is not
[770]116important and can be set to whatever the user prefers (i.e. ``s'' and
[534]117``ParkesHOH-20052002'' are equivalent). However, having a simple and
118consistent naming convention will help you a lot.
119
[544]120\subsection{Member Functions (functions)}
[534]121
[794]122\index{Functions!member}Following the object oriented approach,
123objects have associated ``member functions'' which can either be used
124to modify the data in some way or change global properties of the
125object. In this document member functions will be referred to simply
126as functions. From the command line, the user can execute these
127functions using the syntax:
[534]128\begin{verbatim}
[1243]129 ASAP>out = object.function(arguments)
[534]130\end{verbatim}
131
132Where \cmd{out} is the name of the returned variable (could be a new
[544]133scantable object, or a vector of data, or a status return),
134\cmd{object} is the object variable name (set by the user),
135\cmd{function} is the name of the member function and \cmd{arguments}
136is a list of arguments to the function. The arguments can be provided
137either though position or \cmd{name=}. A mix of the two can be used.
138E.g.
[534]139
140\begin{verbatim}
[1243]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)
[534]147\end{verbatim}
148
149\subsection{Global Functions}
150
[794]151\index{Functions!global}It does not make sense to implement some functions as member
[544]152functions, typically functions which operate on more than one
153scantable (e.g. time averaging of many scans). These functions will
154always be referred to as global functions.
[534]155
[538]156\subsection{Interactive environment}
[534]157
[794]158\index{ipython!environment}ipython has a number of useful interactive
159features and a few things to be aware of for the new user.
[534]160
161\subsubsection{String completion}
162
[794]163\index{ipython!string completion}Tab completion is enabled for all
164function names. If you type the first few letters of a function name,
165then type {\tt <TAB>} the function name will be auto completed if it
166is un-ambiguous, or a list of possibilities will be
167given. Auto-completion works for the user object names as well as
168function names. It does not work for filenames, nor for function
169arguments.
[534]170
171Example
172\begin{verbatim}
[1243]173 ASAP>scans = scantable('MyData.rpf')
174 ASAP>scans.se<TAB>
175 ASAP>scans.set_in<TAB>
[971]176scans.set_cursor scans.set_freqframe scans.set_selection
177scans.set_doppler scans.set_instrument scans.set_unit
178scans.set_fluxunit scans.set_restfreqs
179
[1243]180 ASAP>scans.set_instrument()
[534]181\end{verbatim}
182
[544]183\subsubsection{Leading Spaces}
184
[794]185\index{ipython!leading space}Python uses leading space to mark blocks
186of code. This means that it you start a command line with a space, the
187command generally will fail with an syntax error.
[544]188
[770]189\subsubsection{Variable Names}
190
[794]191\index{ipython!variable names}During normal data processing, the user
192will have to create named variables to hold spectra etc. These must
193conform to the normal python syntax, specifically they cannot contain
194``special'' characters such as \@ \$ etc and cannot start with a
195number (but can contain numbers). Variable (and function) names are
196case sensitive.
[770]197
[534]198\subsubsection{Unix Interaction}
199
[794]200\index{ipython!unix interaction}Basic unix shell commands (\cmd{pwd},
201\cmd{ls}, \cmd{cd} etc) can be issued from within ASAP. This allows
202the user to do things like look at files in the current directory. The
203shell command ``\cmd{cd}'' works within ASAP, allowing the user to
204change between data directories. Unix programs cannot be run this way,
205but the shell escape ``$!$'' can be used to run arbitrary
206programs. E.g.
[534]207
208\begin{verbatim}
[1243]209 ASAP>pwd
210 ASAP>ls
211 ASAP>cd /my/data/directory
212 ASAP>! mozilla&
[534]213\end{verbatim}
214
215\subsection{Help}
216
[794]217\index{Help}ASAP has built in help for all functions. To get a list of
218functions type:
[534]219
[538]220\begin{verbatim}
[1243]221 ASAP>commands()
[538]222\end{verbatim}
223
224To get help on specific functions, the built in help needs to be given
225the object and function name. E.g.
226
227\begin{verbatim}
[1243]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
[538]232
[1243]233 ASAP>scans = scantable('mydata.asap')
234 ASAP>help scans.get_scan # Same as above
[544]235\end{verbatim}
[538]236
[544]237Global functions just need their name
[538]238
[544]239\begin{verbatim}
[1243]240 ASAP>help average_time
[538]241\end{verbatim}
242
243Note that if you just type \cmd{help} the internal ipython help is
244invoked, which is probably {\em not} what you want. Type \verb+^+-d
245(control-d) to escape from this.
246
[738]247\subsection{Customisation - .asaprc}
[534]248
[794]249\index{.asaprc}ASAP use an \cmd{.asaprc} file to control the user's
250preference of default values for various functions arguments. This
251includes the defaults for arguments such as \cmd{insitu}, scantable
252\cmd{freqframe} and the plotters \cmd{set\_mode} values. The help on
253individual functions says which arguments can be set default values
254from the \cmd{.asaprc} file. To get a sample contents for the
[1064]255\cmd{.asaprc} file use the command \cmd{list\_rcparameters}.
[534]256
[538]257Common values include:
258\begin{verbatim}
259 # apply operations on the input scantable or return new one
260 insitu : False
261
[738]262 # default output format when saving scantable
[953]263 scantable.save : ASAP
[538]264
265 # default frequency frame to set when function
266 # scantable.set_freqframe is called
[953]267 scantable.freqframe : LSRK
[538]268
269 # auto averaging on read
270 scantable.autoaverage : True
271\end{verbatim}
272
[953]273For a complete list of \cmd{.asaprc} values, see the Appendix.
[770]274
[534]275\section{Scantables}
[794]276\index{Scantables}
[534]277\subsection {Description}
278
279\subsubsection {Basic Structure}
280
[794]281\index{Scantable!structure}ASAP data handling works on objects called
282scantables. A scantable holds your data, and also provides functions
283to operate upon it.
[534]284
285The building block of a scantable is an integration, which is a single
[1215]286row of a scantable. Each row contains just one spectrum for each beam,
287IF and polarisation. For example Parkes OH-multibeam data would
288normally contain 13 beams, 1 IF and 2 polarisations, Parkes
289methanol-multibeam data would contain 7 beams, 2 IFs and 2
[1243]290polarisations while the Mopra 8-GHz MOPS filterbank will produce one
[1215]291beam, many IFs, and 2-4 polarisations.
292
293All of the combinations of Beams/IFs an Polarisations are
[1243]294contained in separate rows. These rows are grouped in cycles (same time stamp).
[534]295
[1215]296A collection of cycles for one source is termed a scan (and each scan
297has a unique numeric identifier, the SCANNO). A scantable is then a
298collection of one or more scans. If you have scan-averaged your data
[1243]299in time, i.e. you have averaged all cycles within a scan, then each
[1215]300scan would hold just one (averaged) integration.
[534]301
[1215]302Many of the functions which work on scantables can either return a new
303scantable with modified data or change the scantable insitu. Which
[534]304method is used depends on the users preference. The default can be
305changed via the {\tt .asaprc} resource file.
306
[1243]307For example a Mopra scan with a 4s integration time, two IFs and
[1011]308dual polarisations has two (2s) cycles.
309\begin{verbatim}
[1064]310 SCANNO CYCLENO BEAMNO IFNO POLNO
311 0 0 0 0 0
312 0 0 0 0 1
313 0 0 0 1 0
314 0 0 0 1 1
315 0 1 0 0 0
316 0 1 0 0 1
317 0 1 0 1 0
318 0 1 0 1 1
[1011]319\end{verbatim}
320
321
[534]322\subsubsection {Contents}
323
[794]324\index{Scantable!contents}A scantable has header information and data
[953]325(a scantable is actually an AIPS++ Table and it is generally stored in
326memory when you are manipulating it with ASAP. You can save it to
327disk and then browse it with the AIPS++ Table browser if you know how
328to do that !).
[534]329
330The data are stored in columns (the length of a column is the number of
[1011]331rows/spectra of course).
[534]332
333Two important columns are those that describe the frequency setup. We mention
[538]334them explicitly here because you need to be able to understand the presentation
[534]335of the frequency information and possibly how to manipulate it.
336
[1011]337These columns are called FREQ\_ID and MOLECULE\_ID. They contain indices, for
[971]338each IF, pointing into tables with all of the frequency and rest-frequency
[1054]339information for that integration.
[534]340
341There are of course many other columns which contain the actual spectra,
[971]342the flags, the Tsys, the source names and so on.
[534]343
344There is also a function \cmd{summary} to list a summary of the scantable.
345You will find this very useful.
346
347Example:
348
349\begin{verbatim}
[1243]350 ASAP>scans = scantable('MyData.rpf')
351 ASAP>scans.summary() # Brief listing
[544]352
353 # Equivalent to brief summary function call
[1243]354 ASAP>print scan
[534]355\end{verbatim}
356
[971]357The summary function gives you a scan-based summary, presenting the
[1054]358scantable as a cascading view of Beams and IFs. Note that the output
359of summary is redirected into your current pager specified by the
360\$PAGER environment variable. If you find the screen is reset to the
[1243]361original state when summary is finished (i.e. the output from summary
[1054]362disappears), you may need to set the \$LESS environment variable to
363include the \cmd{-X} option.
[534]364
[953]365\subsection{Data Selection}
366\label{sec:selection}
367
[966]368ASAP contains flexible data selection. Data can be selected based on
369IF, beam, polarisation, scan number as well as values such as
370Tsys. Advanced users can also make use of the AIPS++ TAQL language to
[971]371create selections based on almost any of the values recorded.
[953]372
[966]373Selection is based on a \cmd{selector} object. This object is created
374and various selection functions applied to it (\cmd{set\_ifs},
375\cmd{set\_beams} etc). The selection object then must be applied to a
376scantable using the \cmd{set\_selection} function. A single selection
377object can be created and setup then applied to multiple scantables.
[534]378
[966]379Once a selection has been applied, all following functions will only
380``see'' the selected spectra (including functions such as
381\cmd{summary}). The selection can then be reset and all spectra are
382visible. Note that if functions such as \cmd{copy} are run on a
383scantable with active selection, only the selected spectra are copied.
[534]384
[966]385The common selection functions are:
[534]386
[1266]387\begin{tabular}{ll}
[966]388
[1266]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 \\
[966]394
[1266]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). }\\
[966]398
[1266]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}
405
[966]406Note that all indices are zero based.
407
408Examples:
409
410\begin{verbatim}
[1243]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
[966]415
[1243]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
[966]419
[1243]420 ASAP>selection.set_name('G308*') # Select by source name
[966]421
[1243]422 ASAP>selection.reset() # Turn off selection
423 ASAP>scans.set_selection(selection) # Apply the reset selection
[966]424
[970]425\end{verbatim}
426
[534]427\subsection{State}
428
[794]429\index{Scantable!state}Each scantable contains "state"; these are
430properties applying to all of the data in the scantable.
[534]431
432Examples are the selection of beam, IF and polarisation, spectral unit
[770]433(e.g. km/s), frequency reference frame (e.g. BARY) and velocity Doppler
[534]434type (e.g. RADIO).
435
436\subsubsection{Units, Doppler and Frequency Reference Frame}
437
438The information describing the frequency setup for each integration
439is stored fundamentally in frequency in the reference frame
[738]440of observation (E.g. TOPO).
[534]441
[544]442When required, this is converted to the desired reference frame
443(e.g. LSRK), Doppler (e.g. OPTICAL) and unit (e.g. km/s) on-the-fly.
444This is important, for example, when you are displaying the data or
[971]445fitting to it. The reference frame is set on file read to the value
446set in the user \cmd{.asaprc} file.
[534]447
448For units, the user has the choice of frequency, velocity or channel.
449The \cmd{set\_unit} function is used to set the current unit for a
450scantable. All functions will (where relevant) work with the selected
451unit until this changes. This is mainly important for fitting (the fits
[738]452can be computed in any of these units), plotting and mask creation.
[534]453
[544]454The velocity definition can be changed with the \cmd{set\_doppler}
455function, and the frequency reference frame can be changed with the
[534]456\cmd{set\_freqframe} function.
457
458Example usage:
459
460\begin{verbatim}
[1243]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
[534]466\end{verbatim}
467
468
469\subsubsection{Rest Frequency}
470
[794]471\index{Scantable!rest frequency}ASAP reads the line rest frequency
472from the RPFITS file when reading the data. The values stored in the
473RPFITS file are not always correct and so there is a function
[953]474\cmd{set\_restfreq} to set the rest frequencies for the currently
475selected data.
[534]476
477For each integration, there is a rest-frequency per IF (the rest
478frequencies are just stored as a list with an index into them).
479There are a few ways to set the rest frequencies with this function.
480
[953]481If you specify just one rest frequency, then it is set for all IF.
[534]482
483\begin{verbatim}
[953]484 # Set all IFs
[1243]485 ASAP>scans.set_restfreqs(freqs=1.667359e9)
[534]486\end{verbatim}
487
[953]488If set a rest frequency for each IF, specify a list of frequencies (of
489length the number of IFs). Regardless of the source, the rest
490frequency will be set for each IF to the corresponding value in the
[970]491provided list.
[534]492
493\begin{verbatim}
[770]494 # Set rest frequency for all IFs
[1243]495 ASAP>scans.set_restfreqs(freqs=[1.6654018e9,1.667359e9,])
[538]496
[534]497\end{verbatim}
498
[1266]499A predetermined ``line catalog'' can be used to set the rest
500frequency. See section \S \ref{sec:linecat}.
[953]501
[534]502
503\subsubsection{Masks}
504
[970]505\index{Masks}\index{Scantable!masks}
[534]506
[966]507Many tasks (fitting, baseline subtraction, statistics etc) should only
508be run on range of channels. Depending on the current ``unit'' setting
509this range is set directly as channels, velocity or frequency
510ranges. Internally these are converted into a simple boolean mask for
511each channel of the abscissa. This means that if the unit setting is
512later changed, previously created mask are still valid. (This is not
513true for functions which change the shape or shift the frequency
514axis). You create masks with the function \cmd{create\_mask} and this
515specified the channels to be included in the selection. When setting
516the mask in velocity, the conversion from velocity to channels is
[1064]517based on the current selection, specified row and selected frequency
518reference frame.
[534]519
[966]520
521Note that for multi IF data with different number of channels per IF a
522single mask cannot be applied to different IFs. To use a mask on such
523data the selector should be applied to select all IFs with the same
524number of channels.
525
[534]526Example :
527\begin{verbatim}
528
529 # Select channel range for baselining
[1243]530 ASAP>scans.set_unit('channels')
531 ASAP>msk = scans.create_mask([100,400],[600,800])
[738]532
[534]533 # Select velocity range for fitting
[1243]534 ASAP>scans.set_unit('km/s')
535 ASAP>msk = scans.create_mask([-30,-10])
[534]536\end{verbatim}
537
[544]538Sometimes it is more convenient to specify the channels to be
539excluded, rather included. You can do this with the ``invert''
540argument.
[534]541
542Example :
543\begin{verbatim}
[1243]544 ASAP>scans.set_unit('channels')
545 ASAP>msk = scans.create_mask([0,100],[900-1023], invert=True)
[534]546\end{verbatim}
547
[544]548By default \cmd{create\_mask} uses the frequency setup of the first row
549to convert velocities into a channel mask. If the rows in the data
550cover different velocity ranges, the scantable row to use should be
551specified:
552
553\begin{verbatim}
[1243]554 ASAP>scans.set_unit('km/s')
555 ASAP>msk = q.create_mask([-30,-10], row=5)
[544]556\end{verbatim}
557
[534]558Because the mask is stored in a simple python variable, the users is
559able to combine masks using simple arithmetic. To create a mask
560excluding the edge channels, a strong maser feature and a birdie in
561the middle of the band:
562
563\begin{verbatim}
[1243]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)
[534]568
[1243]569 ASAP>mask = msk1 and msk2
[534]570\end{verbatim}
571
572
[953]573\subsection{Management}
574
575\index{Scantable!management}During processing it is possible to create
576a large number of scan tables. These all consume memory, so it is best
577to periodically remove unneeded scan tables. Use \cmd{list\_scans} to
578print a list of all scantables and \cmd{del} to remove unneeded ones.
579
580Example:
581
582\begin{verbatim}
[1243]583 ASAP>list_scans()
[953]584 The user created scantables are:
585 ['s', 'scans', 'av', 's2', 'ss']
586
[1243]587 ASAP>del s2
588 ASAP>del ss
[953]589\end{verbatim}
590
[534]591\section{Data Input}
592
[971]593\index{Reading data}Data can be loaded in one of two ways; using the
594reader object or via the scantable constructor. The scantable method
595is simpler but the reader allows the user more control on what is read.
[534]596
597\subsection{Scantable constructor}
598
[794]599\index{Scantable constructor}\index{Scantable!constructor}This loads
600all of the data from filename into the scantable object scans and
601averages all the data within a scan (i.e. the resulting scantable
[534]602will have one row per scan). The recognised input file formats are
603RPFITS, SDFITS (singledish fits), ASAP's scantable format and aips++
[738]604MeasurementSet2 format.
[534]605
606Example usage:
607
608\begin{verbatim}
[1243]609 ASAP>scan = scantable('2004-11-23_1841-P484.rpf')
[544]610
611 # Don't scan average the data
[1243]612 ASAP>scan = scantable('2004-11-23_1841-P484.rpf', average=False)
[534]613\end{verbatim}
614
615
616\subsection{Reader object}
617
[794]618\index{Reader object}\index{Scantable!reader object}For more control
619when reading data into ASAP, the reader object should be used. This
[953]620has the option of only reading in a range of integrations, only a
621specified beam or IF and does not perform any scan averaging of the
622data, allowing analysis of the individual integrations. Note that due
623to limitation of the RPFITS library, only one reader object can be
624open at one time reading RPFITS files. To read multiple RPFITS files,
625the old reader must be destroyed before the new file is opened.
626However, multiple readers can be created and attached to SDFITS files.
[534]627
628
629Example usage:
630
631\begin{verbatim}
[1243]632 ASAP>r = reader('2003-03-16_082048_t0002.rpf')
633 ASAP>r.summary()
634 ASAP>scan = r.read()
635 ASAP>del r
[534]636\end{verbatim}
637
638\section{Basic Processing}
639
640In the following section, a simple data reduction to form a quotient
[544]641spectrum of a single source is followed. It has been assume that the
642\cmd{.asaprc} file has {\em not} been used to change the \cmd{insitu}
643default value from \cmd{True}.
[534]644
[738]645\subsection{Auto quotient}
[794]646\index{Auto quotient}Quotients can be computed ``automatically''. This
647requires the data to have matching source/reference pairs or one
648reference for multiple sources. Auto quotient assumes reference scans
649have a trailing ``\_R'' in the source name for data from Parkes and
650Mopra, and a trailing ``e'' or ``w'' for data fro, Tidbinbilla.
[534]651
[738]652\begin{verbatim}
[1243]653 ASAP>q = s.auto_quotient()
[738]654\end{verbatim}
655
[971]656By default the quotient spectra is calculated
657to preserve continuum emission. If you wish to remove the continuum
658contribution, use the \cmd{preserve} argument:
659
660\begin{verbatim}
[1243]661 ASAP>q = s.auto_quotient(preserve=True)
[971]662\end{verbatim}
663
[1215]664If this is not sufficient the following alternative method can be used.
[738]665
[1215]666\subsection{Separate reference and source observations}
667
668\index{Quotient spectra}Most data from ATNF observatories
669distinguishes on and off source data using the file name. This makes
670it easy to create two scantables with the source and reference
671data. As long as there was exactly one reference observation for each
672on source observation for following method will work.
673
674For Mopra and Parkes data:
675\begin{verbatim}
[1243]676 ASAP>r = scans.get_scan('*_R')
677 ASAP>s = scans.get_scan('*_S')
[1215]678\end{verbatim}
679
680For Tidbinbilla data
681\begin{verbatim}
[1243]682 ASAP>r = scans.get_scan('*_[ew]')
683 ASAP>s = scans.get_scan('*_[^ew]')
[1215]684\end{verbatim}
685
686\subsection{Make the quotient spectra}
687
688Use the quotient function
689
690\begin{verbatim}
[1243]691 ASAP>q = s.quotient(r)
[1215]692\end{verbatim}
693
694This uses the rows in scantable \cmd{r} as reference spectra for the
695rows in scantable \cmd{s}. Scantable \cmd{r} must have either 1 row
696(which is applied to all rows in \cmd{s}) or both scantables must have
697the same number of rows.
698
[534]699\subsection{Time average separate scans}
700
[794]701\index{Time average}If you have observed the source with multiple
702source/reference cycles you will want to scan-average the quotient
703spectra together.
[534]704
705\begin{verbatim}
[1243]706 ASAP>av = q.average_time()
[534]707\end{verbatim}
708
[544]709If for some you want to average multiple sets of scantables together
710you can:
[534]711
712\begin{verbatim}
[1243]713 ASAP>av = average_time(q1, q2, q3)
[534]714\end{verbatim}
715
[544]716The default is to use integration time weighting. The alternative is
[1215]717to use none, variance, Tsys weighting, Tsys \& integration time or
718median averaging.
[534]719
[544]720\begin{verbatim}
[1243]721 ASAP>av = average_time(q, weight='tintsys')
[544]722\end{verbatim}
723
[534]724To use variance based weighting, you need to supply a mask saying which
725channel range you want it to calculate the variance from.
726
727\begin{verbatim}
[1243]728 ASAP>msk = scans.create_mask([200,400],[600,800])
729 ASAP>av = average_time(scans, mask=msk, weight='var')
[534]730\end{verbatim}
731
[953]732If you have not observed your data with Doppler tracking (or run
[1243]733\cmd{freq\_align} explicitly) you should align the data in frequency
[953]734before averaging.
[794]735
[953]736\begin{verbatim}
[1243]737 ASAP>av = scans.average_time(align=True)
[953]738\end{verbatim}
739
740Note that, if needed, you should run \cmd{gain\_el} and \cmd{opacity}
741before you average the data in time (\S \ref{sec:gainel} \&
742\ref{sec:freqalign}).
743
[534]744\subsection{Baseline fitting}
745
[794]746\index{Baseline fitting}To make a baseline fit, you must first create
747a mask of channels to use in the baseline fit.
[534]748
749\begin{verbatim}
[1243]750 ASAP>msk = scans.create_mask([100,400],[600,900])
751 ASAP>scans.poly_baseline(msk, order=1)
[534]752\end{verbatim}
753
754This will fit a first order polynomial to the selected channels and subtract
755this polynomial from the full spectra.
756
757\subsubsection{Auto-baselining}
758
[794]759\index{Auto-baseline}The function \cmd{auto\_poly\_baseline} can be used to automatically
[770]760baseline your data without having to specify channel ranges for the
761line free data. It automatically figures out the line-free emission
762and fits a polynomial baseline to that data. The user can use masks to
763fix the range of channels or velocity range for the fit as well as
764mark the band edge as invalid.
[534]765
766Simple example
767
768\begin{verbatim}
[1243]769 ASAP>scans.auto_poly_baseline(order=2,threshold=5)
[534]770\end{verbatim}
771
772\cmd{order} is the polynomial order for the fit. \cmd{threshold} is
773the SNR threshold to use to deliminate line emission from
[548]774signal. Generally the value of threshold is not too critical, however
775making this too large will compromise the fit (as it will include
776strong line features) and making it too small will mean it cannot find
777enough line free channels.
[534]778
[548]779
[534]780Other examples:
781
782\begin{verbatim}
783 # Don't try and fit the edge of the bandpass which is noisier
[1243]784 ASAP>scans.auto_poly_baseline(edge=(500,450),order=3,threshold=3)
[534]785
786 # Only fit a given region around the line
[1243]787 ASAP>scans.set_unit('km/s')
788 ASAP>msk = scans.create_mask([-60,-20])
789 ASAP>scans.auto_poly_baseline(mask=msk,order=3,threshold=3)
[534]790
791\end{verbatim}
792
793\subsection{Average the polarisations}
794
[794]795\index{average\_pol}If you are just interested in the highest SNR for total intensity you
[534]796will want to average the parallel polarisations together.
797
798\begin{verbatim}
[1243]799 ASAP>scans.average_pol()
[534]800\end{verbatim}
801
802\subsection{Calibration}
803
[794]804\index{Calibration}For most uses, calibration happens transparently as the input data
[534]805contains the Tsys measurements taken during observations. The nominal
806``Tsys'' values may be in Kelvin or Jansky. The user may wish to
807supply a Tsys correction or apply gain-elevation and opacity
808corrections.
809
810\subsubsection{Brightness Units}
811
[794]812\index{Brightness Units}RPFITS files do not contain any information as
813to whether the telescope calibration was in units of Kelvin or
814Janskys. On reading the data a default value is set depending on the
815telescope and frequency of observation. If this default is incorrect
816(you can see it in the listing from the \cmd{summary} function) the
817user can either override this value on reading the data or later.
818E.g:
[534]819
820\begin{verbatim}
[1243]821 ASAP>scans = scantable('2004-11-23_1841-P484.rpf', unit='Jy')
[534]822 # Or in two steps
[1243]823 ASAP>scans = scantable('2004-11-23_1841-P484.rpf')
824 ASAP>scans.set_fluxunit('Jy')
[534]825\end{verbatim}
826
[1215]827\subsubsection{Feed Polarisation}
828
829\index{Brightness Units}The RPFITS files also do not contain any
830information as to the feed polarisation. ASAP will set a default based
831on the antenna, but this will often be wrong the data has been read,
832the default can be changed using the \cmd{set\_feedtype} function with
833an argument of \cmd{'linear'} or \cmd{'circular'}.
834
835E.g:
836
837\begin{verbatim}
[1243]838 ASAP>scans = scantable('2004-11-23_1841-P484.rpf')
839 ASAP>scans.set_feedtype('circular')
[1215]840\end{verbatim}
841
[534]842\subsubsection{Tsys scaling}
843
[794]844\index{Tsys scaling}Sometime the nominal Tsys measurement at the
845telescope is wrong due to an incorrect noise diode calibration. This
846can easily be corrected for with the scale function. By default,
847\cmd{scale} only scans the spectra and not the corresponding Tsys.
[534]848
849\begin{verbatim}
[1243]850 ASAP>scans.scale(1.05, tsys=True)
[534]851\end{verbatim}
852
853\subsubsection{Unit Conversion}
854
[794]855\index{Unit conversion}To convert measurements in Kelvin to Jy (and
856vice versa) the global function \cmd{convert\_flux} is needed. This
857converts and scales the data from K to Jy or vice-versa depending on
858what the current brightness unit is set to. The function knows the
859basic parameters for some frequencies and telescopes, but the user may
860need to supply the aperture efficiency, telescope diameter or the Jy/K
861factor.
[534]862
863\begin{verbatim}
[1243]864 ASAP>scans.convert_flux() # If efficency known
865 ASAP>scans.convert_flux(eta=0.48) # If telescope diameter known
866 ASAP>scans.convert_flux(eta=0.48,d=35) # Unknown telescope
867 ASAP>scans.convert_flux(jypk=15) # Alternative
[534]868\end{verbatim}
869
870\subsubsection{Gain-Elevation and Opacity Corrections}
[794]871\label{sec:gainel}
[534]872
[794]873\index{Gain-elevation}As higher frequencies (particularly $>$20~GHz)
874it is important to make corrections for atmospheric opacity and
875gain-elevation effects.
[534]876
[794]877Note that currently the elevation is not written correctly into
[770]878Tidbinbilla rpfits files. This means that gain-elevation and opacity
[794]879corrections will not work unless these get recalculated.
[770]880
[794]881\begin{verbatim}
[1243]882 ASAP>scans.recalc_azel() # recalculate az/el based on pointing
[794]883\end{verbatim}
884
[544]885Gain-elevation curves for some telescopes and frequencies are known to
[794]886ASAP (currently only for Tidbinbilla at 20~GHz). In these cases
887making gain-corrections is simple. If the gain curve for your data is
888not known, the user can supply either a gain polynomial or text file
[534]889tabulating gain factors at a range of elevations (see \cmd{help
[544]890scantable.gain\_el}).
[534]891
892Examples:
893
894\begin{verbatim}
[1243]895 ASAP>scans.gain_el() # If gain table known
896 ASAP>scans.gain_el(poly=[3.58788e-1,2.87243e-2,-3.219093e-4])
[534]897\end{verbatim}
898
[794]899\index{Opacity}Opacity corrections can be made with the global
900function \cmd{opacity}. This should work on all telescopes as long as
901a measurement of the opacity factor was made during the observation.
[534]902
903\begin{verbatim}
[1243]904 ASAP>scans.opacity(0.083)
[534]905\end{verbatim}
906
907Note that at 3~mm Mopra uses a paddle wheel for Tsys calibration,
908which takes opacity effects into account (to first order). ASAP
[544]909opacity corrections should not be used for Mopra 3-mm data.
[534]910
911\subsection{Frequency Frame Alignment}
[794]912\label{sec:freqalign}
[534]913
[1243]914\index{Frequency alignment}\index{Velocity alignment}When time
[794]915averaging a series of scans together, it is possible that the velocity
916scales are not exactly aligned. This may be for many reasons such as
917not Doppler tracking the observations, errors in the Doppler tracking
918etc. This mostly affects very long integrations or integrations
919averaged together from different days. Before averaging such data
920together, they should be frequency aligned using \cmd{freq\_align}.
[534]921
922E.g.:
923
924\begin{verbatim}
[1243]925 ASAP>scans.freq_align()
926 ASAP>av = average_time(scans)
[534]927\end{verbatim}
928
[953]929{\em A Global freq\_align command will be made eventually}
[534]930
931To average together data taken on different days, which are in
932different scantables, each scantable must aligned to a common
933reference time then the scantables averaged. The simplest way of
934doing this is to allow ASAP to choose the reference time for the first
[738]935scantable then using this time for the subsequent scantables.
[534]936
937\begin{verbatim}
[1243]938 ASAP>scans1.freq_align() # Copy the refeference Epoch from the output
939 ASAP>scans2.freq_align(reftime='2004/11/23/18:43:35')
940 ASAP>scans3.freq_align(reftime='2004/11/23/18:43:35')
941 ASAP>av = average_time(scans1, scans2, scans3)
[534]942\end{verbatim}
943
944\section{Scantable manipulation}
945
[794]946\index{Scantable!manipulation}While it is very useful to have many
947independent sources within one scantable, it is often inconvenient for
948data processing. The \cmd{get\_scan} function can be used to create a
949new scantable with a selection of scans from a scantable. The
950selection can either be on the source name, with simple wildcard
[953]951matching or set of scan ids. Internally this uses the selector object,
952so for more complicated selection the selector should be used directly
953instead.
[534]954
955For example:
956
957\begin{verbatim}
[1243]958 ASAP>ss = scans.get_scan(10) # Get the 11th scan (zero based)
959 ASAP>ss = scans.get_scan(range(10)) # Get the first 10 scans
960 ASAP>ss = scans.get_scan(range(10,20)) # Get the next 10 scans
961 ASAP>ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans
[534]962
[1243]963 ASAP>ss = scans.get_scan('345p407') # Get a specific source
964 ASAP>ss = scans.get_scan('345*') # Get a few sources
[534]965
[1243]966 ASAP>r = scans.get_scan('*_R') # Get all reference sources (Parkes/Mopra)
967 ASAP>s = scans.get_scan('*_S') # Get all program sources (Parkes/Mopra)
968 ASAP>r = scans.get_scan('*[ew]') # Get all reference sources (Tid)
969 ASAP>s = scans.get_scan('*[^ew]') # Get all program sources (Tid)
[534]970
971\end{verbatim}
972
973To copy a scantable the following does not work:
974
975\begin{verbatim}
[1243]976 ASAP>ss = scans
[534]977\end{verbatim}
978
[544]979as this just creates a reference to the original scantable. Any
980changes made to \cmd{ss} are also seen in \cmd{scans}. To duplicate a
[534]981scantable, use the copy function.
982
983\begin{verbatim}
[1243]984 ASAP>ss = scans.copy()
[534]985\end{verbatim}
986
987\section{Data Output}
988
[794]989\index{Scantable!save}\index{Saving data}ASAP can save scantables in a
990variety of formats, suitable for reading into other packages. The
991formats are:
[534]992
993\begin{itemize}
994\item[ASAP] This is the internal format used for ASAP. It is the only
[544]995 format that allows the user to restore the data, fits etc. without
996 loosing any information. As mentioned before, the ASAP scantable is
997 an AIPS++ Table (a memory-based table). This function just converts
998 it to a disk-based Table. You can the access that Table with the
999 AIPS++ Table browser or any other AIPS++ tool.
[534]1000
[544]1001\item[SDFITS] The Single Dish FITS format. This format was designed to
1002 for interchange between packages, but few packages actually can read
1003 it.
[534]1004
[1064]1005%\item[FITS] This uses simple ``image'' fits to save the data, each row
1006% being written to a separate fits file. This format is suitable for
1007% importing the data into CLASS.
[534]1008
1009\item[ASCII] A simple text based format suitable for the user to
1010processing using Perl or, Python, gnuplot etc.
1011
1012\item[MS2] Saves the data in an aips++ MeasurementSet V2 format.
1013You can also access this with the Table browser and other AIPS++
1014tools.
1015
1016\end{itemize}
1017
[738]1018The default output format can be set in the users {\tt .asaprc} file.
[534]1019Typical usages are:
1020
1021\begin{verbatim}
[1243]1022 ASAP>scans.save('myscans') # Save in default format
[1275]1023 ASAP>scans.save('myscans', 'SDFITS') # Save as SDFITS for export
[1243]1024 ASAP>scans.save('myscans', overwrite=True) # Overwrite an existing file
[534]1025\end{verbatim}
1026
1027\section{Plotter}
1028
[1243]1029\index{Plotter}Scantable spectra can be plotted at any time. An
1030asapplotter object is used for plotting, meaning multiple plot windows
1031can be active at the same time. On start up a default asapplotter
1032object is created called ``plotter''. This would normally be used for
1033standard plotting.
[534]1034
[1243]1035The plotter, optionally, will run in a multi-panel mode and contain
[534]1036multiple plots per panel. The user must tell the plotter how they want
1037the data distributed. This is done using the set\_mode function. The
1038default can be set in the users {\tt .asaprc} file. The units (and frame
[538]1039etc) of the abscissa will be whatever has previously been set by
1040\cmd{set\_unit}, \cmd{set\_freqframe} etc.
[534]1041
1042Typical plotter usage would be:
1043
1044\begin{verbatim}
[1243]1045 ASAP>scans.set_unit('km/s')
1046 ASAP>plotter.set_mode(stacking='p',panelling='t')
1047 ASAP>plotter.plot(scans)
[534]1048\end{verbatim}
1049
1050This will plot multiple polarisation within each plot panel and each
[544]1051scan row in a separate panel.
[534]1052
[538]1053Other possibilities include:
[534]1054
1055\begin{verbatim}
1056 # Plot multiple IFs per panel
[1243]1057 ASAP>plotter.set_mode(stacking='i',panelling='t')
[538]1058
1059 # Plot multiple beams per panel
[1243]1060 ASAP>plotter.set_mode(stacking='b',panelling='t')
[538]1061
1062 # Plot one IF per panel, time stacked
[1243]1063 ASAP>plotter.set_mode('t', 'i')
[538]1064
1065 # Plot each scan in a seperate panel
[1243]1066 ASAP>plotter.set_mode('t', 's')
[538]1067
[534]1068\end{verbatim}
1069
[538]1070\subsection{Plot Selection}
1071\label{sec:plotter_cursor}
1072
[794]1073\index{Plotter!selection}The plotter can plot up to 25 panels and
1074stacked spectra per panel. If you have data larger than this (or for
1075your own sanity) you need to select a subset of this data. This is
[953]1076particularly true for multibeam or multi IF data. The selector object
[971]1077should be used for this purpose. Selection can either be applied to
[953]1078the scantable or directly to the plotter, the end result is the same.
[1243]1079You don't have to reset the scantable selection though, if you set
[971]1080the selection on the plotter.
[538]1081
1082Examples:
1083
1084\begin{verbatim}
[1243]1085 ASAP>selection = selector()
[538]1086 # Select second IF
[1243]1087 ASAP>selection.set_ifs(1)
1088 ASAP>plotter.set_selection(selection)
[538]1089
1090 # Select first 4 beams
[1243]1091 ASAP>selection.set_beams([0,1,2,3])
1092 ASAP>plotter.set_selection(selection)
[538]1093
[953]1094 # Select a few scans
[1243]1095 ASAP>selection.set_scans([2,4,6,10])
1096 ASAP>plotter.set_selection(selection)
[538]1097
1098 # Multiple selection
[1243]1099 ASAP>selection.set_ifs(1)
1100 ASAP>selection.set_scans([2,4,6,10])
1101 ASAP>plotter.set_selection(selection)
[953]1102
[538]1103\end{verbatim}
1104
[544]1105\subsection{Plot Control}
1106
[794]1107\index{Plotter!control}The plotter window has a row of buttons on the
1108lower left. These can be used to control the plotter (mostly for
1109zooming the individual plots). From left to right:
[534]1110
[1266]1111\begin{tabular}{ll}
[534]1112
[1266]1113Home & This will unzoom the plots to the original zoom factor \\
[534]1114
[1266]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. }\\
[534]1120
[1266]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. }\\
[534]1124
[1266]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.}\\
[534]1128
[1266]1129Adjust & \parbox[t]{0.8\textwidth}{(rectangle with 4 arrows) adjust
1130 subplot parameters (space at edge of plots)}\\
[953]1131
[1266]1132Save & \parbox[t]{0.8\textwidth}{(floppy disk). Save the plot as a
1133postscript or .png file}\\
[534]1134
[1266]1135\end{tabular}
1136
[794]1137You can also type ``g'' in the plot window to toggle on and off grid
1138lines. Typing 'l' turns on and off logarithmic Y-axis.
1139
[534]1140\subsection{Other control}
1141
1142The plotter has a number of functions to describe the layout of the
1143plot. These include \cmd{set\_legend}, \cmd{set\_layout} and \cmd{set\_title}.
1144
1145To set the exact velocity or channel range to be plotted use the
1146\cmd{set\_range} function. To reset to the default value, call
1147\cmd{set\_range} with no arguments. E.g.
1148
1149\begin{verbatim}
[1243]1150 ASAP>scans.set_unit('km/s')
1151 ASAP>plotter.plot(scans)
1152 ASAP>plotter.set_range(-150,-50)
1153 ASAP>plotter.set_range() # To reset
[534]1154\end{verbatim}
1155
[544]1156Both the range of the ``x'' and ``y'' axis can be set at once, if desired:
1157
1158\begin{verbatim}
[1243]1159 ASAP>plotter.set_range(-10,30,-1,6.6)
[544]1160\end{verbatim}
1161
[738]1162To save a hardcopy of the current plot, use the save function, e.g.
[534]1163
1164\begin{verbatim}
[1243]1165 ASAP>plotter.save('myplot.ps')
1166 ASAP>plotter.save('myplot.png', dpi=80)
[534]1167\end{verbatim}
1168
[1215]1169\subsection{Plotter Customisation}
1170
1171The plotter allows the user to change most properties such as text
[1243]1172size and colour. The \cmd{commands} function and {\cmd help\
[1215]1173asapplotter} list all the possible commands that can be used with the
1174plotter.
1175
1176\commanddef{set\_colors}{Change the default colours used for line
1177plotting. Colours can be given either by name, using the html standard
1178(e.g. red, blue or hotpink), or hexadecimal code (e.g. for black
1179\#000000). If less colours are specified than lines plotted , the
1180plotter cycles through the colours. Example:} {ASAP>
1181plotter.set\_colors('red blue green')\\ ASAP>
1182plotter.set\_colors(`\#0000 blue \#FF00FF')\\ }
1183
1184\commanddef{set\_linestyles}{Change the line styles used for
1185plots. Allowable values are 'line', 'dashed', 'dotted', 'dashdot',
1186'dashdotdot' and 'dashdashdot. Example: }{
[1243]1187 ASAP>plotter.set\_linestyles('line dash cotted datshot.)\\
1188 ASAP>plotter.set\_font(size=10)\\
[1215]1189}
1190
1191\commanddef{set\_font}{Change the font style and size. Example}{
[1243]1192 ASAP>plotter.set\_font(weight='bold')\\
1193 ASAP>plotter.set\_font(size=10)\\
1194 ASAP>plotter.set\_font(style='italic')\\
[1215]1195}
1196
[1243]1197\commanddef{set\_layout}{Change the multi-panel layout, i.e. now many
[1215]1198 rows and columns}{
[1243]1199 ASAP>plotter.set\_layout(3,2)
[1215]1200}
1201
1202\commanddef{set\_legend}{Set the position, size and optional value of the legend}{
[1243]1203 ASAP>plotter.set\_legend(fontsize=16)\\
1204 ASAP>plotter.set\_legend(mode=0) \# ASAP chooses where to put the legend\\
1205 ASAP>plotter.set\_legend(mode=4) \# Put legend on lower right\\
1206 ASAP>plotter.set\_legend(mode=-1) \# No legend\\
1207 ASAP>plotter.set\_legend(mp=['RR','LL']) \# Specify legend labels\\
1208 ASAP>plotter.set\_legend(mp=[r'\$\^\{12\}CO\$',r'\$\^\{13\}CO\$']) \# Latex labels
[1215]1209}
1210
1211\commanddef{set\_title}{Set the plot title. If multiple panels are
1212 plotted, multiple titles have to be specified}{
[1243]1213 ASAP>plotter.set\_title(`G323.12$-$1.79`)\\
1214 ASAP>plotter.set\_title([`SiO`, 'Methanol'], fontsize=18)\\
[1215]1215}
1216
1217\subsection{Plotter Annotations}
1218
[1243]1219The plotter allows various annotations (lines, arrows, text and
[1215]1220``spans'') to be added to the plot. These annotations are
1221``temporary'', when the plotter is next refreshed
1222(e.g. \cmd{plotter.plot} or \cmd{plotter.set\_range}) the annotations
1223will be removed.
1224
[1243]1225\bigcommanddef{arrow(x,y,x+dx,y+dy)}{Draw an arrow from a specified
[1215]1226\cmd{(x,y)} position to \cmd{(x+dx, y+dy)}. The values are in world
[1266]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)
[1215]1229}
1230
1231\bigcommanddef{axhline(y, xmin, xmax)}{Draw a horizontal line at the
[1243]1232specified \cmd{y} position (in world coordinates) between xmin and xmax
1233(in relative coordinates, i.e. 0.0 is the left hand edge of the plot
[1266]1234while 1.0 is the right side of the plot).}{
[1243]1235 ASAP>plotter.axhline(6.0,0.2,0.8)
[1215]1236}
1237
1238\bigcommanddef{avhline(x, ymin, ymax)}{Draw a vertical line at the
[1243]1239specified \cmd{x} position (in world coordinates) between \cmd{ymin}
1240and \cmd{ymax} (in relative coordinates, i.e. 0.0 is the left hand edge
[1215]1241of the plot while 1.0 is the right side of the plot).}{
[1243]1242 ASAP>plotter.axvline(-50.0,0.1,1.0)
[1215]1243}
1244
1245\bigcommanddef{axhspan(ymin, ymax, \\ \hspace*{20mm}xmin,
1246 xmax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
[1243]1247 \cmd{ymax} are given in world coordinates while \cmd{xmin} and
[1215]1248 \cmd{xmax} are given in relative coordinates}{
[1243]1249ASAP>plotter.axhspan(2,4,0.25,0.75)
[1215]1250}
1251
1252\bigcommanddef{axvspan(xmin, xmax, \\ \hspace*{20mm} ymin,
1253 ymax)}{Overlay a transparent colour rectangle. \cmd{ymin} and
[1243]1254 \cmd{ymax} are given in relative coordinates while \cmd{xmin} and
[1215]1255 \cmd{xmax} are given in world coordinates}{
[1243]1256ASAP>plotter.axvspan(-50,60,0.2,0.5)
[1215]1257}
1258
1259\bigcommanddef{text(x, y, str)}{Place the string \cmd{str} at the
1260 given \cmd{(x,y)} position in world coordinates.}{
1261ASAP>plotter.text(-10,7,"CO")
1262}
1263
1264These functions all take a set of \cmd{kwargs} commands. These can be
1265used to set colour, linewidth fontsize etc. These are standard
1266matplotlib settings. Common ones include:
1267
1268\begin{tabular}{ll}
[1266]1269 \tt color, facecolor, edgecolor \\
1270 \tt width, linewidth \\
[1215]1271 \tt fontsize \\
1272 \tt fontname & Sans, Helvetica, Courier, Times etc\\
1273 \tt rotation & Text rotation (horizontal, vertical) \\
1274 \tt alpha & The alpha transparency on 0-1 scale\\
1275\end{tabular}
1276
1277Examples:
1278\begin{verbatim}
[1243]1279 ASAP>plotter.axhline(6.0,0.2,0.8, color='red', linewidth=3)
1280 ASAP>plotter.text(-10,7,"CO", fontsize=20)
[1215]1281\end{verbatim}
1282
[1243]1283\section{Line Catalog}
[1266]1284\label{sec:linecat}
[1264]1285\index{Linecatalog}ASAP can load and manipulate line catlogs to
1286retrieve rest frequencies for \cmd{set\_restfreqs} and for line
[1265]1287identification in the plotter. All line catalogs are loaded into a ``linecatalog'' object.
[1243]1288
[1265]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
[1266]1293Lovas catalog in the appropriate format:
[1265]1294
[1266]1295\hspace{1cm}\cmd{ftp://ftp.atnf.csiro.au/pub/software/asap/data}
1296
1297
[1243]1298\subsection{Loading a Line Catalog}
1299
[1265]1300\index{Linecatalog!loading}The ASCII text line catalog must have at
[1243]1301least 4 columns. The first four columns must contain (in order):
1302Molecule name, frequency in MHz, frequency error and ``intensity''
1303(any units). If the molecule name contains any spaces, they must be
1304wrapped in quotes \verb+""+.
1305
1306A sample from the JPL line catalog:
1307
1308\begin{verbatim}
1309 H2D+ 3955.2551 228.8818 -7.1941
1310 H2D+ 12104.7712 177.1558 -6.0769
1311 H2D+ 45809.2731 118.3223 -3.9494
1312 CH 701.6811 .0441 -7.1641
1313 CH 724.7709 .0456 -7.3912
1314 CH 3263.7940 .1000 -6.3501
1315 CH 3335.4810 .1000 -6.0304
1316\end{verbatim}
1317
1318To load a line catalog then save it in the internal format:
1319
1320\begin{verbatim}
1321 ASAP>jpl = linecatalog('jpl_pruned.txt')
1322 ASAP>jpl.save('jpl.tbl')
1323\end{verbatim}
1324
1325Later the saved line catalog can reloaded:
1326
1327\begin{verbatim}
1328 ASAP>jpl = linecatalog('jpl.tbl')
1329\end{verbatim}
1330
[1265]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
[1243]1335\subsection{Line selection}
1336
[1265]1337\index{Linecatalog!line selection}The linecatalog has a number of
[1243]1338selection functions to select a range of lines from a larger catalog
1339(the JPL catalog has $>$180000 lines for
1340example). \cmd{set\_frequency\_limits} selects on frequency range,
1341\cmd{set\_strength\_limits} selects on intensity while \cmd{set\_name}
[1266]1342selects on molecule name (wild cards allowed). The \cmd{summary}
1343function lists the currently selected lines.
[1243]1344
1345\begin{verbatim}
1346 ASAP>jpl = linecatalog('jpl.tbl')
1347 ASAP>jpl.set_frequency_limits(80,115,'GHz') # Lines for 3mm receiver
1348 ASAP>jpl.set_name('*OH') # Select all alcohols
1349 ASAP>jpl.set_name('OH') # Select only OH molecules
1350 ASAP>jpl.summary()
1351
1352 ASAP>jpl.reset() # Selections are accumulative
1353 ASAP>jpl.set_frequency_limits(80,115,'GHz')
1354 ASAP>jpl.set_strength_limits(-2,10) # Select brightest lines
1355 ASAP>jpl.summary()
1356\end{verbatim}
1357
1358\subsection{Using Linecatalog}
1359
1360The line catalogs can be used for line overlays on the plotter or with
1361\cmd{set\_restfreq}.
1362
1363\subsubsection{Plotting linecatalog}
1364
[1265]1365\index{Linecatalog!plotting}
[1243]1366
1367The plotter \cmd{plot\_lines} function takes a line catalog as an
1368argument and overlays the lines on the spectrum. {\em Currently this
1369only works when plotting in units of frequency (Hz, GHz etc).} If a
1370large line catalog has been loaded (e.g. JPL) it is highly recommended
1371that you use the selection functions to narrow down the number of
1372lines. By default the line catalog overlay is plotted assuming a line
1373velocity of 0.0. This can be set using the \cmd{doppler} argument (in
1374km/s). Each time \cmd{plot\_lines} is called the new lines are added
1375to any existing line catalog annotations. These are all removed after
1376the next call to \cmd{plotter.plot()}.
1377
1378\begin{verbatim}
1379 ASAP>jpl = linecatalog('jpl.tbl')
1380 ASAP>jpl.set_frequency_limits(23,24,'GHz')
1381 ASAP>data.set_unit('GHz') # Only works with freq axis currently
1382 ASAP>plotter.plot(data)
1383 ASAP>plotter.plot_lines(jpl)
1384
1385 ASAP>plotter.plot() # Reset plotter
[1266]1386 ASAP>plotter.plot_lines(jpl,doppler=-10,location='Top')
1387 # On top with -10 km/s velocity
[1243]1388\end{verbatim}
1389
1390\subsubsection{Setting Rest Frequencies}
1391
[1265]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}
[1243]1404
[1265]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
[1266]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.
[1265]1417
[534]1418\section{Fitting}
1419
[794]1420\index{Fitting}Currently multicomponent Gaussian function is
1421available. This is done by creating a fitting object, setting up the
1422fit and actually fitting the data. Fitting can either be done on a
[966]1423single scantable selection or on an entire scantable using the
1424\cmd{auto\_fit} function. If single value fitting is used, and the
1425current selection includes multiple spectra (beams, IFs, scans etc)
[971]1426then the first spectrum in the scantable will be used for fitting.
[534]1427
1428\begin{verbatim}
[1243]1429 ASAP>f = fitter()
1430 ASAP>f.set_function(gauss=2) # Fit two Gaussians
1431 ASAP>f.set_scan(scans)
1432 ASAP>selection = selector()
1433 ASAP>selection.set_polarisations(1) # Fit the second polarisation
1434 ASAP>scans.set_selection(selection)
1435 ASAP>scans.set_unit('km/s') # Make fit in velocity units
1436 ASAP>f.fit(1) # Run the fit on the second row in the table
1437 ASAP>f.plot() # Show fit in a plot window
1438 ASAP>f.get_parameters() # Return the fit paramaters
[534]1439\end{verbatim}
1440
1441This auto-guesses the initial values of the fit and works well for data
1442without extra confusing features. Note that the fit is performed in
1443whatever unit the abscissa is set to.
1444
1445If you want to confine the fitting to a smaller range (e.g. to avoid
1446band edge effects or RFI you must set a mask.
1447
1448\begin{verbatim}
[1243]1449 ASAP>f = fitter()
1450 ASAP>f.set_function(gauss=2)
1451 ASAP>scans.set_unit('km/s') # Set the mask in channel units
1452 ASAP>msk = s.create_mask([1800,2200])
1453 ASAP>scans.set_unit('km/s') # Make fit in velocity units
1454 ASAP>f.set_scan(s,msk)
1455 ASAP>f.fit()
1456 ASAP>f.plot()
1457 ASAP>f.get_parameters()
[534]1458\end{verbatim}
1459
[544]1460If you wish, the initial parameter guesses can be specified and
1461specific parameters can be fixed:
[534]1462
1463\begin{verbatim}
[1243]1464 ASAP>f = fitter()
1465 ASAP>f.set_function(gauss=2)
1466 ASAP>f.set_scan(s,msk)
1467 ASAP>f.fit() # Fit using auto-estimates
[738]1468 # Set Peak, centre and fwhm for the second gaussian.
[534]1469 # Force the centre to be fixed
[1243]1470 ASAP>f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
1471 ASAP>f.fit() # Re-run the fit
[534]1472\end{verbatim}
1473
1474The fitter \cmd{plot} function has a number of options to either view
1475the fit residuals or the individual components (by default it plots
1476the sum of the model components).
1477
1478Examples:
1479
1480\begin{verbatim}
1481 # Plot the residual
[1243]1482 ASAP>f.plot(residual=True)
[534]1483
1484 # Plot the first 2 componentsa
[1243]1485 ASAP>f.plot(components=[0,1])
[534]1486
1487 # Plot the first and third component plus the model sum
[1243]1488 ASAP>f.plot(components=[-1,0,2]) # -1 means the compoment sum
[534]1489\end{verbatim}
1490
[544]1491\subsection{Fit saving}
1492
[794]1493\index{Fitter!Fit saving}One you are happy with your fit, it is
1494possible to store it as part of the scantable.
[544]1495
1496\begin{verbatim}
[1243]1497 ASAP>f.store_fit()
[544]1498\end{verbatim}
1499
1500This will be saved to disk with the data, if the ``ASAP'' file format
1501is selected. Multiple fits to the same data can be stored in the
[738]1502scantable.
[544]1503
1504The scantable function \cmd{get\_fit} can be used to retrieve the
1505stored fits. Currently the fit parameters are just printed to the
1506screen.
1507
1508\begin{verbatim}
[1243]1509 ASAP>scans.get_fit(4) # Print fits for row 4
[544]1510\end{verbatim}
1511
[1243]1512A fit can also be exported to an ASCII file using the \cmd{store\_fit}
1513function. Simply give the name of the output file requires as an
1514argument.
1515
1516\begin{verbatim}
1517 ASAP>f.store_fit('myfit.txt')
1518\end{verbatim}
1519
[534]1520\section{Polarisation}
1521
[794]1522\index{Polarisation}Currently ASAP only supports polarmetric analysis
1523on linearly polarised feeds and the cross polarisation products
[971]1524measured. Other cases will be added on an as needed basis.
[534]1525
[538]1526Conversions of linears to Stokes or Circular polarisations are done
[966]1527``on-the-fly''. Leakage cannot be corrected for nor are there routines
1528to calibrate position angle offsets.
[534]1529
[538]1530\subsection{Simple Calibration}
1531
[794]1532\index{Polarisation!calibration}It is possible that there is a phase
1533offset between polarisation which will effect the phase of the cross
1534polarisation correlation, and so give rise to spurious
1535polarisation. \cmd{rotate\_xyphase} can be used to correct for this
1536error. At this point, the user must know how to determine the size of
1537the phase offset themselves.
[538]1538
1539\begin{verbatim}
[1243]1540 ASAP>scans.rotate_xyphase(10.5) # Degrees
[538]1541\end{verbatim}
1542
1543Note that if this function is run twice, the sum of the two values is
[546]1544applied because it is done in-situ.
[538]1545
[546]1546A correction for the receiver parallactic angle may need to be made,
[953]1547generally because of how it is mounted. Use \cmd{rotate\_linpolphase}
1548to correct the position angle. Running this function twice results in
1549the sum of the corrections being applied because it is applied
1550in-situ.
[538]1551
1552\begin{verbatim}
[1243]1553 ASAP>scans.rotate_linpolphase(-45) # Degrees; correct for receiver mounting
[953]1554\end{verbatim}
[538]1555
[953]1556If the sign of the complex correlation is wrong (this can happen
1557depending on the correlator configuration), use \cmd{invert\_phase} to
1558change take the complex conjugate of the complex correlation
1559term. This is always performed in-situ.
1560
1561\begin{verbatim}
[1243]1562 ASAP>scans.invert_phase()
[538]1563\end{verbatim}
1564
[953]1565Depending on how the correlator is configured, ``BA'' may be
[1243]1566correlated instead of ``AB''. Use \cmd{swap\_linears} to correct for
[953]1567this problem:
1568
1569\begin{verbatim}
[1243]1570 ASAP>scans.swap_linears()
[953]1571\end{verbatim}
1572
[1011]1573\subsection{Conversion}
1574\label{sec:polconv}
1575
[1064]1576Data can be permanently converted between linear and circular
1577polarisations and stokes.
1578
[1011]1579\begin{verbatim}
[1243]1580 ASAP>stokescans = linearscans.convert_pol("stokes")
[1011]1581\end{verbatim}
1582
1583
[538]1584\subsection{Plotting}
1585\label{sec:polplot}
1586
[953]1587\index{Polarisation!plotting}To plot Stokes values, a selector object
1588must be created and the set\_polarisation function used to select the
1589desired polarisation products.
1590
1591The values which can be plotted include a selection of [I,Q,U,V], [I,
1592Plinear, Pangle, V], [RR, LL] or [XX, YY, Real(XY),
[794]1593Imaginary(XY)]. (Plinear and Pangle are the percentage and position
[1011]1594angle of linear polarisation).
[538]1595
1596Example:
1597
1598\begin{verbatim}
[1243]1599 ASAP>selection = selector()
[970]1600
[1243]1601 ASAP>selection.set_polarisations(``I Q U V'')
[953]1602 ASAP plotter.set_selection(selection); # Select I, Q, U \& V
1603
[1243]1604 ASAP>selection.set_polarisations(``I Q'')
[953]1605 ASAP plotter.set_selection(selection); # Select just I \& Q
1606
[1243]1607 ASAP>selection.set_polarisations(``RR LL'')
[953]1608 ASAP plotter.set_selection(selection); # Select just RR \& LL
1609
[1243]1610 ASAP>selection.set_polarisations(``XX YY'')
[953]1611 ASAP plotter.set_selection(selection); # Select linears
1612
[1243]1613 ASAP>selection.set_polarisations(``I Plinear'')
[966]1614 ASAP plotter.set_selection(selection); # Fractional linear
[953]1615
[1243]1616 ASAP>selection.set_polarisations(``Pangle'')
[966]1617 ASAP plotter.set_selection(selection); # Position angle
1618
[538]1619\end{verbatim}
1620
[970]1621Scan, beam and IF selection are also available in the selector object as
[953]1622describe in section~\ref{sec:selection}.
[538]1623
1624\subsection{Saving}
1625
[794]1626\index{Polarisation!saving}When saving data using the \cmd{save}
1627function, the \cmd{stokes} argument can be used to save the data as
1628Stoke values when saving in FITS format.
[538]1629
1630Example:
1631
1632\begin{verbatim}
[1243]1633 ASAP>scans.save('myscan.sdfits', 'SDFITS', stokes=True)
[538]1634\end{verbatim}
1635
[1215]1636\section{Specialised Processing}
1637
1638\subsection{Multibeam MX mode}
1639
1640MX mode is a specific observing approach with a multibeam where a
1641single source is observed cycling through each beam. The scans when
[1243]1642the beam is off source is used as a reference for the on-source
[1215]1643scan. The function \cmd{mx\_quotient} is used to make a quotient
1644spectrum from an MX cycle. This works averaging the ``off-source''
1645scans for each beam (either a median average or mean) and using this
1646as a reference scan in a normal quotient (for each beam). The final
1647spectrum for each beam is returned on a new scantable containing
1648single scan (it the scan numbers are re-labelled to be the same). Note
1649that the current version of \cmd{mx\_quotient} only handles a single
[1243]1650MX cycle, i.e. if each beam has observed the source multiple times you
[1215]1651will need to use the selector object multiple times to select a single
1652MX cycle, run \cmd{mx\_quotient} for each cycle then merge the
1653resulting scan tables back together.
1654
1655Example:
1656
1657\begin{verbatim}
[1243]1658 ASAP>scans = scantable('mydata.rpf')
1659 ASAP>q = scans.mx_quotient()
1660 ASAP>plotter.plot(q)
[1215]1661\end{verbatim}
1662
1663The function \cmd{average\_beam} averages multiple beam data
1664together. This is need if MX mode has been used to make a long
1665integration on a single source. E.g.
1666
1667\begin{verbatim}
[1243]1668 ASAP>av = q.average_beam()
[1215]1669\end{verbatim}
1670
1671\subsection{Frequency Switching}
1672
1673{\em FILL ME IN}
1674
[1243]1675\subsection{Disk Based Processing}
[1265]1676\index{Scantable!disk based}
[1243]1677
[1265]1678Normally scantables exist entirely in memory during an ASAP
1679session. This has the advantage of speed, but causes limits on the
[1243]1680size of the dataset which can be loaded. ASAP can use ``disk based''
[1264]1681scan tables which cache the bulk of the scantable on disk and require
[1265]1682significantly less memory usage.
[1243]1683
[1264]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.
1700
[1243]1701{\bf NOTE: } Currently a bug in ipython means temporary files are not
1702cleaned up properly when you exit ASAP. If you use disk based scan
[1265]1703tables your directory will be left with 'tabXXXXX\_X' directories. These can
[1243]1704be safely removed if ASAP is not running.
1705
[770]1706\section{Scantable Mathematics}
1707
[794]1708\index{Scantable!maths}It is possible to to simple mathematics
1709directly on scantables from the command line using the \cmd{+, -, *,
1710/} operators as well as their cousins \cmd{+=, -= *=, /=}. This works
[971]1711between a scantable and a float. (Note that it does
[794]1712not work for integers).
[770]1713
[971]1714{\em Currently mathematics between two scantables is not available }
[966]1715
[1243]1716% ASAP>sum = scan1+scan2
[534]1717\begin{verbatim}
[1243]1718 ASAP>scan2 = scan1+2.0
1719 ASAP>scan *= 1.05
[770]1720\end{verbatim}
1721
1722\section{Scripting}
1723
[1243]1724\index{Scripting}Because ASAP is based on python, it easy for the user
[794]1725write their own scripts and functions to process data. This is highly
1726recommended as most processing of user data could then be done in a
1727couple of steps using a few simple user defined functions. A Python
[1243]1728primer is beyond the scope of this userguide. See the ASAP home pages
[794]1729for a scripting tutorial or the main python website for comprehensive
1730documentation.
[770]1731
1732\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
[953]1733
[770]1734\hspace{1cm} http://www.python.org/doc/Introduction.html
1735
1736\subsection{Running scripts}
1737
[1243]1738The ASAP global function \cmd{execfile} reads the named text file and
[770]1739executes the contained python code. This file can either contain
1740function definitions which will be used in subsequent processing or
1741just a set of commands to process a specific dataset.
1742
1743\subsection{asapuserfuncs.py}
1744
1745The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
[1243]1746ASAP is started. The user can use this to define a set of user
1747functions which are automatically available each time ASAP is
[770]1748used. The \cmd{execfile} function can be called from within this file.
1749
1750\section{Worked examples}
1751
1752In the following section a few examples of end-to-end processing of
[1243]1753some data in ASAP are given.
[770]1754
1755\subsection{Mopra}
[794]1756\index{Mopra}
[770]1757
[794]1758The following example is of some dual polarisation, position switched
[1243]1759data from Mopra. The source has been observed multiple times split
1760into a number of separate RPFITS files. To make the processing easier,
1761the first step is to \cmd{cat} the separate RPFITS files together and
1762load as a whole (future versions of ASAP will make this unnecessary).
[794]1763
1764
1765\begin{verbatim}
[1011]1766# get a list of the individual rpfits files in the current directory
1767myfiles = list_files()
[794]1768
1769# Load the data into a scantable
[1011]1770data = scantable(myfiles)
[794]1771print data
1772
1773# Form the quotient spectra
1774q = data.auto_quotient()
1775print q
1776
1777# Look at the spectra
1778plotter.plot(q)
1779
[1011]1780# Set unit and reference frame
[794]1781q.set_unit('km/s')
1782q.set_freqframe('LSRK')
1783
[966]1784# Average all scans in time, aligning in velocity
1785av = q.average_time(align=True)
[794]1786plotter.plot(av)
1787
1788# Remove the baseline
1789msk = av.create_mask([100,130],[160,200])
1790av.poly_baseline(msk,2)
1791
1792# Average the two polarisations together
1793iav = av.average_pol()
1794print iav
1795plotter.plot(iav)
1796
1797# Set a sensible velocity range on the plot
1798plotter.set_range(85,200)
1799
1800# Smooth the data a little
1801av.smooth('gauss',4)
1802plotter.plot()
1803
1804# Fit a guassian to the emission
1805f = fitter()
1806f.set_function(gauss=1)
1807f.set_scan(av)
1808f.fit()
1809
1810# View the fit
1811f.plot()
1812
1813# Get the fit parameters
1814f.get_parameters()
1815
1816\end{verbatim}
1817
1818
[770]1819\subsection{Parkes Polarimetry}
1820
[794]1821\index{Parkes}\index{Polarisation}The following example is processing
[1265]1822of some Parkes polarimetric observations of OH masers at
[794]18231.6~GHz. Because digital filters where used in the backend, the
1824baselines are stable enough not to require a quotient spectra. The
18254~MHz bandwidth is wide enough to observe both the 1665 and 1667~MHz
1826OH maser transitions. Each source was observed once for about 10
[1243]1827minutes. Tsys information was not written to the RPFITS file (a
[794]1828nominal 25K values was used), so the amplitudes need to be adjusted
1829based on a separate log file. A simple user function is used to
1830simplify this, contained in a file called mypol.py:
[770]1831
1832\begin{verbatim}
1833def xyscale(data,xtsys=1.0,ytsys=1.0,nomtsys=25.0) :
1834
[966]1835 selection = selector()
[971]1836 selection.set_polarisations(0)
[966]1837 data.set_selection(selection)
1838 data.scale(xtsys/nomtsys)
[770]1839
[971]1840 selection.set_polarisations(1)
[966]1841 data.set_selection(selection)
1842 data.scale(ytsys/nomtsys)
[770]1843
[971]1844 selection.set_polarisations(0)
[966]1845 data.set_selection(selection)
1846 data.scale((xtsys+ytsys)/(2*nomtsys))
[770]1847
[971]1848 selection.set_polarisations(0)
[966]1849 data.set_selection(selection)
1850 data.scale((xtsys+ytsys)/(2*nomtsys))
[770]1851\end{verbatim}
1852
[1243]1853The typical ASAP session would be
[770]1854
1855\begin{verbatim}
[794]1856
[770]1857# Remind ourself the name of the rpfits files
[794]1858ls
[770]1859
1860# Load data from an rpfits file
1861d1665 = scantable('2005-10-27_0154-P484.rpf')
1862
1863# Check what we have just loaded
[1011]1864d1665.summary()
[770]1865
1866# View the data in velocity
1867d1665.set_unit('km/s')
1868d1665.set_freqframe('LSRK')
1869
1870# Correct for the known phase offset in the crosspol data
1871d1665.rotate_xyphase(-4)
1872
[794]1873# Create a copy of the data and set the rest frequency to the 1667 MHz
[770]1874# transition
1875d1667 = d1665.copy()
[966]1876d1667.set_restfreqs([1667.3590], 'MHz')
1877d1667.summary()
[770]1878
1879# Copy out the scan we wish to process
1880g351_5 = d1665.get_scan('351p160')
1881g351_7 = d1667.get_scan('351p160')
1882
[966]1883# Baseline both
1884msk = g351_5.create_mask([-30,-25],[-5,0])
1885g351_5.poly_baseline(msk,order=1)
1886msk = g351_7.create_mask([-30,-25],[-5,0])
1887g351_7.poly_baseline(msk,order=1)
[770]1888
[966]1889
1890# Plot the data. The plotter can only plot a single scantable
1891# So we must merge the two tables first
1892
1893plotscans = merge(g351_5, g351_7)
1894
1895plotter.plot(plotscans) # Only shows one panel
1896
[770]1897# Tell the plotter to stack polarisation and panel scans
1898plotter.set_mode('p','s')
1899
1900# Correct for the Tsys using our predefined function
[971]1901execfile('mypol.py') # Read in the function xyscale
[770]1902xyscale(g351_5,23.2,22.7) # Execute it on the data
1903xyscale(g351_7,23.2,22.7)
1904
1905# Only plot the velocity range of interest
1906plotter.set_range(-30,10)
1907
1908# Update the plot with the baselined data
1909plotter.plot()
1910
1911# Look at the various polarisation products
[966]1912selection = selector()
1913selection.set_polarisations(``RR LL'')
1914plotter.set_selection(selection)
1915selection.set_polarisations(``I Plinear'')
1916plotter.set_selection(selection)
1917selection.set_polarisations(``I Q U V'')
1918plotter.set_selection(selection)
[770]1919
1920# Save the plot as postscript
[966]1921plotter.save('g351_stokes.ps')
[770]1922
1923# Save the process spectra
[966]1924plotscans.save('g351.asap')
[770]1925
1926\end{verbatim}
1927
1928\subsection{Tidbinbilla}
1929
[794]1930\index{Tidbinbilla}The following example is processing of some
1931Tidbinbilla observations of NH$_3$ at 12~mm. Tidbinbilla has (at the
1932time of observations) a single polarisation, but can process two IFs
1933simultaneously. In the example, the first half of the observation was
1934observing the (1,1) and (2,2) transitions simultaneously). The second
1935half observed only the (4,4) transition due to bandwidth
1936limitations. The data is position switched, observing first an
1937reference to the west, then the source twice and finally reference to
1938the east.
[770]1939
1940\begin{verbatim}
1941
1942# Load the rpfits file and inspect
1943d = scantable('2003-03-16_082048_t0002.rpf')
1944print d
1945
1946# Make the quotient spectra
1947q = d.auto_quotient()
1948print q
1949
[966]1950del d
1951
[770]1952# Plot/select in velocity
1953q.set_freqframe('LSRK')
1954q.set_unit('km/s')
1955
[966]1956# Correct for gain/el effects
1957
1958q.recalc_azel() # Tid does not write the elevation
1959q.gain_el()
1960q.opacity(0.05)
1961
[770]1962# Seperate data from the (1,1)&(2,2) and (4,4) transitions
[971]1963g1 = q.get_scan(range(6)) # scans 0..5
1964g2 = q.get_scan(range(6,12)) # scans 6..11
[770]1965
[794]1966# Align data in velocity
[966]1967g1.freq_align()
1968g2.freq_align()
[770]1969
1970# Average individual scans
1971a1 = g1.average_time()
1972a2 = g2.average_time()
1973
[1011]1974# Rpfits file only contains a single rest frequency. Set both
[966]1975a1.set_restfreqs([23694.4700e6,23722.6336e6])
[770]1976
[966]1977plotter.plot(a1)
[1011]1978plotter.set_mode('i','t')
[770]1979
1980a1.auto_poly_baseline()
1981
1982plotter.plot()
1983
1984a1.smooth('gauss',5)
1985plotter.plot()
1986
[966]1987
[770]1988\end{verbatim}
1989
1990\newpage
1991
1992\section{Appendix}
1993
1994\subsection{Function Summary}
1995
[794]1996\index{Functions!summary}%
[770]1997\begin{verbatim}
[1265]1998 [The scan container]
[534]1999 scantable - a container for integrations/scans
2000 (can open asap/rpfits/sdfits and ms files)
2001 copy - returns a copy of a scan
2002 get_scan - gets a specific scan out of a scantable
[1011]2003 (by name or number)
[1215]2004 drop_scan - drops a specific scan out of a scantable
2005 (by number)
[1011]2006 set_selection - set a new subselection of the data
2007 get_selection - get the current selection object
[534]2008 summary - print info about the scantable contents
2009 stats - get specified statistic of the spectra in
2010 the scantable
2011 stddev - get the standard deviation of the spectra
2012 in the scantable
2013 get_tsys - get the TSys
2014 get_time - get the timestamps of the integrations
[1011]2015 get_sourcename - get the source names of the scans
[794]2016 get_azimuth - get the azimuth of the scans
2017 get_elevation - get the elevation of the scans
2018 get_parangle - get the parallactic angle of the scans
[1011]2019 get_unit - get the current unit
[534]2020 set_unit - set the abcissa unit to be used from this
2021 point on
2022 get_abcissa - get the abcissa values and name for a given
2023 row (time)
[1265]2024 get_column_names - get the names of the columns in the scantable
2025 for use with selector.set_query
[534]2026 set_freqframe - set the frame info for the Spectral Axis
2027 (e.g. 'LSRK')
2028 set_doppler - set the doppler to be used from this point on
[1011]2029 set_dirframe - set the frame for the direction on the sky
[534]2030 set_instrument - set the instrument name
[1215]2031 set_feedtype - set the feed type
[534]2032 get_fluxunit - get the brightness flux unit
2033 set_fluxunit - set the brightness flux unit
2034 create_mask - return an mask in the current unit
2035 for the given region. The specified regions
2036 are NOT masked
2037 get_restfreqs - get the current list of rest frequencies
2038 set_restfreqs - set a list of rest frequencies
[1215]2039 flag - flag selected channels in the data
2040 save - save the scantable to disk as either 'ASAP',
2041 'SDFITS' or 'ASCII'
[534]2042 nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
[1011]2043 nscan - the number of scans in the scantable
2044 nrow - te number of spectra in the scantable
[534]2045 history - print the history of the scantable
[544]2046 get_fit - get a fit which has been stored witnh the data
[738]2047 average_time - return the (weighted) time average of a scan
[534]2048 or a list of scans
2049 average_pol - average the polarisations together.
[1215]2050 average_beam - average the beams together.
[1011]2051 convert_pol - convert to a different polarisation type
[738]2052 auto_quotient - return the on/off quotient with
[1215]2053 automatic detection of the on/off scans (closest
2054 in time off is selected)
2055 mx_quotient - Form a quotient using MX data (off beams)
2056 scale, *, / - return a scan scaled by a given factor
2057 add, +, - - return a scan with given value added
[534]2058 bin - return a scan with binned channels
2059 resample - return a scan with resampled channels
2060 smooth - return the spectrally smoothed scan
2061 poly_baseline - fit a polynomial baseline to all Beams/IFs/Pols
[738]2062 auto_poly_baseline - automatically fit a polynomial baseline
[794]2063 recalc_azel - recalculate azimuth and elevation based on
2064 the pointing
[534]2065 gain_el - apply gain-elevation correction
2066 opacity - apply opacity correction
2067 convert_flux - convert to and from Jy and Kelvin brightness
2068 units
2069 freq_align - align spectra in frequency frame
[1215]2070 invert_phase - Invert the phase of the cross-correlation
2071 swap_linears - Swap XX and YY
[534]2072 rotate_xyphase - rotate XY phase of cross correlation
2073 rotate_linpolphase - rotate the phase of the complex
2074 polarization O=Q+iU correlation
[1011]2075 freq_switch - perform frequency switching on the data
2076 stats - Determine the specified statistic, e.g. 'min'
2077 'max', 'rms' etc.
2078 stddev - Determine the standard deviation of the current
2079 beam/if/pol
[1215]2080 [Selection]
2081 selector - a selection object to set a subset of a scantable
[1265]2082 set_cycles - set (a list of) cycles by index
[1215]2083 set_beams - set (a list of) beamss by index
2084 set_ifs - set (a list of) ifs by index
2085 set_polarisations - set (a list of) polarisations by name
2086 or by index
2087 set_names - set a selection by name (wildcards allowed)
2088 set_tsys - set a selection by tsys thresholds
[1265]2089 set_query - set a selection by SQL-like query, e.g. BEAMNO==1
[1215]2090 reset - unset all selections
2091 + - merge to selections
[1011]2092
[534]2093 [Math] Mainly functions which operate on more than one scantable
2094
[738]2095 average_time - return the (weighted) time average
[534]2096 of a list of scans
2097 quotient - return the on/off quotient
[544]2098 simple_math - simple mathematical operations on two scantables,
2099 'add', 'sub', 'mul', 'div'
[1215]2100 quotient - build quotient of the given on and off scans
2101 (matched pairs and 1 off/n on are valid)
2102 merge - merge a list of scantables
2103
2104 [Line Catalog]
2105 linecatalog - a linecatalog wrapper, taking an ASCII or
2106 internal format table
2107 summary - print a summary of the current selection
2108 set_name - select a subset by name pattern, e.g. '*OH*'
2109 set_strength_limits - select a subset by line strength limits
2110 set_frequency_limits - select a subset by frequency limits
2111 reset - unset all selections
2112 save - save the current subset to a table (internal
2113 format)
2114 get_row - get the name and frequency from a specific
2115 row in the table
[534]2116 [Fitting]
2117 fitter
2118 auto_fit - return a scan where the function is
2119 applied to all Beams/IFs/Pols.
2120 commit - return a new scan where the fits have been
2121 commited.
2122 fit - execute the actual fitting process
[1011]2123 store_fit - store the fit parameters in the data (scantable)
[534]2124 get_chi2 - get the Chi^2
2125 set_scan - set the scantable to be fit
2126 set_function - set the fitting function
2127 set_parameters - set the parameters for the function(s), and
2128 set if they should be held fixed during fitting
[544]2129 set_gauss_parameters - same as above but specialised for individual
2130 gaussian components
[534]2131 get_parameters - get the fitted parameters
2132 plot - plot the resulting fit and/or components and
2133 residual
2134 [Plotter]
2135 asapplotter - a plotter for asap, default plotter is
2136 called 'plotter'
[1011]2137 plot - plot a scantable
[1215]2138 plot_lines - plot a linecatalog overlay
[534]2139 save - save the plot to a file ('png' ,'ps' or 'eps')
2140 set_mode - set the state of the plotter, i.e.
2141 what is to be plotted 'colour stacked'
2142 and what 'panelled'
[1011]2143 set_selection - only plot a selected part of the data
2144 set_range - set a 'zoom' window [xmin,xmax,ymin,ymax]
[534]2145 set_legend - specify user labels for the legend indeces
2146 set_title - specify user labels for the panel indeces
[1011]2147 set_abcissa - specify a user label for the abcissa
[534]2148 set_ordinate - specify a user label for the ordinate
2149 set_layout - specify the multi-panel layout (rows,cols)
[1011]2150 set_colors - specify a set of colours to use
2151 set_linestyles - specify a set of linestyles to use if only
2152 using one color
[1215]2153 set_font - set general font properties, e.g. 'family'
2154 set_histogram - plot in historam style
[1011]2155 set_mask - set a plotting mask for a specific polarization
[1215]2156 text - draw text annotations either in data or relative
2157 coordinates
2158 arrow - draw arrow annotations either in data or relative
2159 coordinates
[1265]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
[1215]2167 arrow - draw arrow annotations either in data or relative
2168 coordinates
2169 axhline,axvline - draw horizontal/vertical lines
2170 axhspan,axvspan - draw horizontal/vertical regions
[738]2171
[1215]2172 xyplotter - matplotlib/pylab plotting functions
2173
[534]2174 [Reading files]
2175 reader - access rpfits/sdfits files
[1011]2176 open - attach reader to a file
2177 close - detach reader from file
[534]2178 read - read in integrations
2179 summary - list info about all integrations
2180
2181 [General]
2182 commands - this command
2183 print - print details about a variable
2184 list_scans - list all scantables created bt the user
[1011]2185 list_files - list all files readable by asap (default rpf)
[534]2186 del - delete the given variable from memory
2187 range - create a list of values, e.g.
2188 range(3) = [0,1,2], range(2,5) = [2,3,4]
2189 help - print help for one of the listed functions
[538]2190 execfile - execute an asap script, e.g. execfile('myscript')
[544]2191 list_rcparameters - print out a list of possible values to be
[1215]2192 put into .asaprc
2193 rc - set rc parameters from within asap
[534]2194 mask_and,mask_or,
2195 mask_not - boolean operations on masks created with
2196 scantable.create_mask
2197\end{verbatim}
2198
2199\subsection{ASCII output format}
2200
2201\subsection{.asaprc settings}
[794]2202\index{.asaprc}
[971]2203\asaprc{verbose}{{\bf True}/False}{Print verbose output, good to disable in scripts}
[770]2204
2205\asaprc{insitu}{{\bf True}/False}{Apply operations on the input
2206scantable or return new one}
2207
2208\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
2209
2210\asaprc{plotter.gui}{{\bf True}/False}{Do we want a GUI or plot to a
2211file}
2212
2213\asaprc{plotter.stacking}{{\bf Pol} Beam IF Scan Time}{Default mode for
2214colour stacking}
2215
2216\asaprc{plotter.panelling}{Pol Beam IF {\bf Scan} Time}{Default mode
2217for panelling}
2218
2219\asaprc{plotter.ganged}{{\bf True}/False}{Push panels together, to
2220share axislabels}
2221
2222\asaprc{plotter.decimate}{True/{\bf False}}{Decimate the number of
2223points plotted by a factor of nchan/1024}
2224
[1215]2225\asaprc{plotter.histogram}{True/{\bf False}}{Plot spectrum using
2226histogram rather than lines.}
[770]2227
[1215]2228\asaprc{plotter.colours}{}{Set default colours for plotting}
2229
2230\asaprc{plotter.colours}{}{Set default line styles}
2231
2232\asaprc{plotter.papersze}{{\bf A4}}{}
2233
[770]2234% scantable
2235\asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
[794]2236format when saving}
[770]2237
2238\asaprc{scantable.autoaverage}{{\bf True}/False}{Auto averaging on
2239read}
2240
2241\asaprc{scantable.freqframe}{{\bf LSRK} TOPO BARY etc}{default
2242frequency frame to set when function scantable.set\_freqframe is
[971]2243called or the data is imported}
[770]2244
[1215]2245\asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level
2246of information printed by summary}
2247
2248\asaprc{scantable.storage}{{\bf memory}/disk}{Storage of scantables in
2249memory of via based disk tables}
2250
[953]2251\subsection{Installation}
2252
[1266]2253\index{Installation}
[953]2254
[1266]2255Please refer to the asap wiki for instructions on downloading and/or
2256building asap from source.
[953]2257
[1266]2258\hspace{1cm}\cmd{http://www.atnf.csiro.au/computing/software/asap/}
[953]2259
[794]2260\printindex
2261
[534]2262\end{document}
[770]2263
Note: See TracBrowser for help on using the repository browser.