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

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

Removed 'FITS' export example

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