source: branches/alma/doc/userguide.tex@ 1677

Last change on this file since 1677 was 1347, checked in by mar637, 18 years ago

move to use latex builder; doc updates for 2.2

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