source: trunk/doc/userguide.tex@ 1266

Last change on this file since 1266 was 1259, checked in by mar637, 18 years ago

Merge from Release2.1.0b tag

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