source: branches/newfiller/doc/userguide.tex@ 2603

Last change on this file since 2603 was 1757, checked in by Kana Sugimoto, 14 years ago

New Development: Yes

JIRA Issue: Yes (CAS-2211)

Ready for Test: Yes

Interface Changes: Yes

What Interface Changed: ASAP 3.0.0 interface changes

Test Programs:

Put in Release Notes: Yes

Module(s): all the CASA sd tools and tasks are affected.

Description: Merged ATNF-ASAP 3.0.0 developments to CASA (alma) branch.

Note you also need to update casa/code/atnf.


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