source: branches/Release2.1.1/doc/userguide.tex@ 1867

Last change on this file since 1867 was 1276, checked in by mar637, 18 years ago

Fix for Ticket #80 - updated dcos to remove all FITS reference, removed FITS from known formats

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