source: trunk/doc/cookbook.tex@ 965

Last change on this file since 965 was 953, checked in by Chris Phillips, 19 years ago

Initial Update for v2

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 59.4 KB
Line 
1\documentclass[11pt]{article}
2\usepackage{a4}
3\usepackage{calc}
4\usepackage[dvips]{graphicx}
5\usepackage{makeidx}
6
7% Adjust the page size
8\addtolength{\oddsidemargin}{-0.4in}
9\addtolength{\evensidemargin}{+0.4in}
10\addtolength{\textwidth}{+0.8in}
11
12\setlength{\parindent}{0mm}
13\setlength{\parskip}{1ex}
14
15\title{ATNF Spectral Analysis Package\\User Guide }
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\makeindex
27
28
29\begin{document}
30
31\maketitle
32
33\section{Introduction}
34
35ASAP is a single dish spectral line processing package currently being
36developed by the ATNF. It is intended to process data from all ATNF
37antennas, and can probably be used for other antennas if they can
38produce ``Single Dish FITS'' format. It is based on the AIPS++
39package.
40
41This useeguide is currently being updated for the ASAP 2.0 release
42which has a number of significant changes which affect the user
43interface. Please report any mistakes you find in this userguide.
44
45\section{Installation and Running}
46
47Currently there are installations running on Linux machines at
48
49\begin{itemize}
50\item Epping - use hosts {\tt draco} or {\tt hydra}
51\item Narrabri - use host {\tt kaputar}
52\item Parkes - use host {\tt bourbon}
53\item Mopra - use host {\tt minos}
54\end{itemize}
55
56\index{Running}To start asap log onto one of these Linux hosts and enter
57
58\begin{verbatim}
59 > cd /my/data/directory
60 > asap2
61\end{verbatim}
62
63This starts the ASAP. To quit, you need to type \verb+^+-d
64(control-d).
65
66\section{Interface}
67
68\index{Interface}ASAP is written in C++ and python. The user interface uses the
69``ipython'' interactive shell, which is a simple interactive interface
70to python. The user does not need to understand python to use this,
71but certain aspects python affect what the user can do. The current
72interface is object oriented. In the future, we will build a
73functional (non object oriented) shell on top of this to ease
74interactive use.
75
76\subsection {Integer Indices are 0-relative}
77
78Please note, all integer indices in ASAP and iPython are {\bf 0-relative}.
79
80\subsection{Objects}
81\index{objects}
82The ASAP interface is based around a number of ``objects'' which the
83user deals with. Objects range from the data which have been read from
84disk, to tools used for fitting functions to the data. The following
85main objects are used :
86
87\begin{itemize}
88 \item[\cmd{scantable}] The data container (actual spectra and header
89 information)
90 \item[\cmd{selector}] Allows the user to select a subsection of the
91 data, such as a specified or ramge of beam numbers, IFs, etc.
92 \item[\cmd{plotter}] A tool used to plot the spectral line data
93 \item[\cmd{fitter}] A tool used to fit functions to the spectral data
94 \item[\cmd{reader}] A tool which can be used to read data from disks
95 into a scantable object.
96\end{itemize}
97
98There can be many objects of the same type. Each object is referred to
99by a variable name made by the user. The name of this variable is not
100important and can be set to whatever the user prefers (i.e. ``s'' and
101``ParkesHOH-20052002'' are equivalent). However, having a simple and
102consistent naming convention will help you a lot.
103
104\subsection{Member Functions (functions)}
105
106\index{Functions!member}Following the object oriented approach,
107objects have associated ``member functions'' which can either be used
108to modify the data in some way or change global properties of the
109object. In this document member functions will be referred to simply
110as functions. From the command line, the user can execute these
111functions using the syntax:
112\begin{verbatim}
113 ASAP> out = object.function(arguments)
114\end{verbatim}
115
116Where \cmd{out} is the name of the returned variable (could be a new
117scantable object, or a vector of data, or a status return),
118\cmd{object} is the object variable name (set by the user),
119\cmd{function} is the name of the member function and \cmd{arguments}
120is a list of arguments to the function. The arguments can be provided
121either though position or \cmd{name=}. A mix of the two can be used.
122E.g.
123
124\begin{verbatim}
125 ASAP> av = scans.average_time(msk,weight='tsys')
126 ASAP> av = scans.average_time(mask=msk,weight='tsys')
127 ASAP> av = scans.average_time(msk,tsys)
128 ASAP> scans.polybaseline(mask=msk, order=0, insitu=True)
129 ASAP> scans.polybaseline(msk,0,True)
130 ASAP> scans.polybaseline(mask, insitu=True)
131\end{verbatim}
132
133\subsection{Global Functions}
134
135\index{Functions!global}It does not make sense to implement some functions as member
136functions, typically functions which operate on more than one
137scantable (e.g. time averaging of many scans). These functions will
138always be referred to as global functions.
139
140\subsection{Interactive environment}
141
142\index{ipython!environment}ipython has a number of useful interactive
143features and a few things to be aware of for the new user.
144
145\subsubsection{String completion}
146
147\index{ipython!string completion}Tab completion is enabled for all
148function names. If you type the first few letters of a function name,
149then type {\tt <TAB>} the function name will be auto completed if it
150is un-ambiguous, or a list of possibilities will be
151given. Auto-completion works for the user object names as well as
152function names. It does not work for filenames, nor for function
153arguments.
154
155Example
156\begin{verbatim}
157 ASAP> scans = scantable('MyData.rpf')
158 ASAP> scans.se<TAB>
159scans.set_cursor scans.set_freqframe scans.set_unit scans.setpol
160scans.set_doppler scans.set_instrument scans.setbeam
161scans.set_fluxunit scans.set_restfreqs scans.setif
162 ASAP> scans.set_in<TAB>
163 ASAP> scans.set_instrument()
164\end{verbatim}
165
166\subsubsection{Leading Spaces}
167
168\index{ipython!leading space}Python uses leading space to mark blocks
169of code. This means that it you start a command line with a space, the
170command generally will fail with an syntax error.
171
172\subsubsection{Variable Names}
173
174\index{ipython!variable names}During normal data processing, the user
175will have to create named variables to hold spectra etc. These must
176conform to the normal python syntax, specifically they cannot contain
177``special'' characters such as \@ \$ etc and cannot start with a
178number (but can contain numbers). Variable (and function) names are
179case sensitive.
180
181\subsubsection{Unix Interaction}
182
183\index{ipython!unix interaction}Basic unix shell commands (\cmd{pwd},
184\cmd{ls}, \cmd{cd} etc) can be issued from within ASAP. This allows
185the user to do things like look at files in the current directory. The
186shell command ``\cmd{cd}'' works within ASAP, allowing the user to
187change between data directories. Unix programs cannot be run this way,
188but the shell escape ``$!$'' can be used to run arbitrary
189programs. E.g.
190
191\begin{verbatim}
192 ASAP> pwd
193 ASAP> ls
194 ASAP> cd /my/data/directory
195 ASAP> ! mozilla&
196\end{verbatim}
197
198\subsection{Help}
199
200\index{Help}ASAP has built in help for all functions. To get a list of
201functions type:
202
203\begin{verbatim}
204 ASAP> commands()
205\end{verbatim}
206
207To get help on specific functions, the built in help needs to be given
208the object and function name. E.g.
209
210\begin{verbatim}
211 ASAP> help scantable.get_scan
212 ASAP> help scantable.stats
213 ASAP> help plotter.plot
214 ASAP> help fitter.plot
215
216 ASAP> scans = scantable('mydata.asap')
217 ASAP> help scans.get_scan # Same as above
218\end{verbatim}
219
220Global functions just need their name
221
222\begin{verbatim}
223 ASAP> help average_time
224\end{verbatim}
225
226Note that if you just type \cmd{help} the internal ipython help is
227invoked, which is probably {\em not} what you want. Type \verb+^+-d
228(control-d) to escape from this.
229
230\subsection{Customisation - .asaprc}
231
232\index{.asaprc}ASAP use an \cmd{.asaprc} file to control the user's
233preference of default values for various functions arguments. This
234includes the defaults for arguments such as \cmd{insitu}, scantable
235\cmd{freqframe} and the plotters \cmd{set\_mode} values. The help on
236individual functions says which arguments can be set default values
237from the \cmd{.asaprc} file. To get a sample contents for the
238\cmd{.asaprc} file use then command \cmd{list\_rcparameters}.
239
240Common values include:
241\begin{verbatim}
242 # apply operations on the input scantable or return new one
243 insitu : False
244
245 # default output format when saving scantable
246 scantable.save : ASAP
247
248 # default frequency frame to set when function
249 # scantable.set_freqframe is called
250 scantable.freqframe : LSRK
251
252 # auto averaging on read
253 scantable.autoaverage : True
254\end{verbatim}
255
256For a complete list of \cmd{.asaprc} values, see the Appendix.
257
258\section{Scantables}
259\index{Scantables}
260\subsection {Description}
261
262\subsubsection {Basic Structure}
263
264\index{Scantable!structure}ASAP data handling works on objects called
265scantables. A scantable holds your data, and also provides functions
266to operate upon it.
267
268{\bf [MALTE: Could you please reword this??]}
269
270The building block of a scantable is an integration, which is a single
271row of a scantable. Each row contains spectra for each beam, IF and
272polarisation. For example Parkes multibeam data would contain many
273beams, one IF and 2-4 polarisations, while the new Mopra 8-GHz
274filterbank will eventually produce one beam, many IFs, and 2-4
275polarisations.
276
277A collection of sequential integrations (rows) for one source is termed
278a scan (and each scan has a unique numeric identifier, the ScanID). A
279scantable is then a collection of one or more scans. If you have
280scan-averaged your data in time, then each scan would hold just one
281(averaged) integration.
282
283Many of the functions which work on scantables can either return a
284new scantable with modified data or change the scantable insitu. Which
285method is used depends on the users preference. The default can be
286changed via the {\tt .asaprc} resource file.
287
288\subsubsection {Contents}
289
290\index{Scantable!contents}A scantable has header information and data
291(a scantable is actually an AIPS++ Table and it is generally stored in
292memory when you are manipulating it with ASAP. You can save it to
293disk and then browse it with the AIPS++ Table browser if you know how
294to do that !).
295
296The data are stored in columns (the length of a column is the number of
297rows/integrations of course).
298
299{\bf [MALTE: Is this outdated??]}
300
301Two important columns are those that describe the frequency setup. We mention
302them explicitly here because you need to be able to understand the presentation
303of the frequency information and possibly how to manipulate it.
304
305These columns are called FreqID and RestFreqID. They contain indices, for
306each IF, pointing into tables with all of the frequency information for that
307integration. More on these below when we discuss the \cmd{summary} function
308in the next subsection.
309
310There are of course many other columns which contain the actual spectra,
311the flags, the Tsys, the source names and so on, but those are a little
312more transparently handled.
313
314There is also a function \cmd{summary} to list a summary of the scantable.
315You will find this very useful.
316
317Example:
318
319\begin{verbatim}
320 ASAP> scans = scantable('MyData.rpf')
321 ASAP> scans.summary() # Brief listing
322 ASAP> scans.summary(verbose=True) # Include frequency information
323
324 # Equivalent to brief summary function call
325 ASAP> print scan
326\end{verbatim}
327
328Most of what the \cmd{summary} function prints out is obvious. However,
329it also prints out the FreqIDs and RestFreqIDs to which we alluded above.
330These are the last column of the listing.
331
332The summary function gives you a scan-based summary. So it lists all of
333the FreqIDs and RestFreqIDs that it encountered for each scan. If you'd
334like to see what each FreqID actually means, then set the verbose
335argument to True and the frequency table will be listed at the end.
336FreqID of 3 say, refers to the fourth row of the frequency table (ASAP
337is 0-relative). The list of rest frequencies, to which the RestFreqIDs
338refer, is always listed.
339
340\subsection{Data Selection}
341\label{sec:selection}
342
343CHRIS TOFILL IN
344
345%You can copy one scantable to another with the \cmd{copy} function.
346
347%Example:
348
349%\begin{verbatim}
350% ASAP> scans = scantable('MyData.rpf')
351% ASAP> scan2 = scans.copy()
352%\end{verbatim}
353
354\subsection{State}
355
356\index{Scantable!state}Each scantable contains "state"; these are
357properties applying to all of the data in the scantable.
358
359Examples are the selection of beam, IF and polarisation, spectral unit
360(e.g. km/s), frequency reference frame (e.g. BARY) and velocity Doppler
361type (e.g. RADIO).
362
363\subsubsection{Units, Doppler and Frequency Reference Frame}
364
365The information describing the frequency setup for each integration
366is stored fundamentally in frequency in the reference frame
367of observation (E.g. TOPO).
368
369When required, this is converted to the desired reference frame
370(e.g. LSRK), Doppler (e.g. OPTICAL) and unit (e.g. km/s) on-the-fly.
371This is important, for example, when you are displaying the data or
372fitting to it.
373
374For units, the user has the choice of frequency, velocity or channel.
375The \cmd{set\_unit} function is used to set the current unit for a
376scantable. All functions will (where relevant) work with the selected
377unit until this changes. This is mainly important for fitting (the fits
378can be computed in any of these units), plotting and mask creation.
379
380The velocity definition can be changed with the \cmd{set\_doppler}
381function, and the frequency reference frame can be changed with the
382\cmd{set\_freqframe} function.
383
384Example usage:
385
386\begin{verbatim}
387 ASAP> scans = scantable('2004-11-23_1841-P484.rpf') # Read in the data
388 ASAP> scans.set_freqframe('LSRK') # Use the LSR velocity frame
389 ASAP> scans.set_unit('km/s') # Use velocity for plots etc from now on
390 ASAP> scans.set_doppler('OPTICAL') # Use the optical velocity convention
391 ASAP> scans.set_unit('MHz') # Use frequency in MHz from now on
392\end{verbatim}
393
394
395\subsubsection{Rest Frequency}
396
397\index{Scantable!rest frequency}ASAP reads the line rest frequency
398from the RPFITS file when reading the data. The values stored in the
399RPFITS file are not always correct and so there is a function
400\cmd{set\_restfreq} to set the rest frequencies for the currently
401selected data.
402
403For each integration, there is a rest-frequency per IF (the rest
404frequencies are just stored as a list with an index into them).
405There are a few ways to set the rest frequencies with this function.
406
407If you specify just one rest frequency, then it is set for all IF.
408
409\begin{verbatim}
410 # Set all IFs
411 ASAP> scans.set_restfreqs(freqs=1.667359e9)
412\end{verbatim}
413
414If set a rest frequency for each IF, specify a list of frequencies (of
415length the number of IFs). Regardless of the source, the rest
416frequency will be set for each IF to the corresponding value in the
417provided list.
418
419\begin{verbatim}
420 # Set rest frequency for all IFs
421 ASAP> scans.set_restfreqs(freqs=[1.6654018e9,1.667359e9,])
422
423\end{verbatim}
424
425{\em Currently this is not implemented}
426
427In both of the above modes, you can also specify the rest frequencies via
428names in a known list rather than by their values.
429
430Examples:
431
432\begin{verbatim}
433 ASAP> scans.set_restfreqs(freqs=['OH1665','OH1667'])
434\end{verbatim}
435
436
437\subsubsection{Masks}
438
439\index{Masks}\index{Scantable!masks}Many tasks (fitting, baseline
440subtraction, statistics etc) should only be run on range of
441channels. Depending on the current ``unit'' setting this range is set
442directly as channels, velocity or frequency ranges. Internally these
443are converted into a simple boolean mask for each channel of the
444abscissa. This means that if the unit setting is later changed,
445previously created mask are still valid. (This is not true for
446functions which change the shape or shift the frequency axis). You
447create masks with the function \cmd{create\_mask} and this specified
448the channels to be included in the selection.
449
450When setting the mask in velocity, the conversion from velocity
451to channels is based on the current cursor setting, selected row and
452selected frequency reference frame.
453
454Example :
455\begin{verbatim}
456
457 # Select channel range for baselining
458 ASAP> scans.set_unit('channels')
459 ASAP> msk = scans.create_mask([100,400],[600,800])
460
461 # Select velocity range for fitting
462 ASAP> scans.set_unit('km/s')
463 ASAP> msk = scans.create_mask([-30,-10])
464\end{verbatim}
465
466Sometimes it is more convenient to specify the channels to be
467excluded, rather included. You can do this with the ``invert''
468argument.
469
470Example :
471\begin{verbatim}
472 ASAP> scans.set_unit('channels')
473 ASAP> msk = scans.create_mask([0,100],[900-1023], invert=True)
474\end{verbatim}
475
476By default \cmd{create\_mask} uses the frequency setup of the first row
477to convert velocities into a channel mask. If the rows in the data
478cover different velocity ranges, the scantable row to use should be
479specified:
480
481\begin{verbatim}
482 ASAP> scans.set_unit('km/s')
483 ASAP> msk = q.create_mask([-30,-10], row=5)
484\end{verbatim}
485
486Because the mask is stored in a simple python variable, the users is
487able to combine masks using simple arithmetic. To create a mask
488excluding the edge channels, a strong maser feature and a birdie in
489the middle of the band:
490
491\begin{verbatim}
492 ASAP> scans.set_unit('channels')
493 ASAP> msk1 = q.create_mask([0,100],[511,511],[900,1023],invert=True)
494 ASAP> scans.set_unit('km/s')
495 ASAP> msk2 = q.create_mask([-20,-10],invert=True)
496
497 ASAP> mask = msk1 and msk2
498\end{verbatim}
499
500
501\subsection{Management}
502
503\index{Scantable!management}During processing it is possible to create
504a large number of scan tables. These all consume memory, so it is best
505to periodically remove unneeded scan tables. Use \cmd{list\_scans} to
506print a list of all scantables and \cmd{del} to remove unneeded ones.
507
508Example:
509
510\begin{verbatim}
511 ASAP> list_scans()
512 The user created scantables are:
513 ['s', 'scans', 'av', 's2', 'ss']
514
515 ASAP> del s2
516 ASAP> del ss
517\end{verbatim}
518
519\section{Data Input}
520
521\index{Reading data}Data can be loaded in one of two ways; using the reader object or via
522the scantable constructor. The scantable method is simpler but the
523reader allow the user more control on what is read.
524
525\subsection{Scantable constructor}
526
527\index{Scantable constructor}\index{Scantable!constructor}This loads
528all of the data from filename into the scantable object scans and
529averages all the data within a scan (i.e. the resulting scantable
530will have one row per scan). The recognised input file formats are
531RPFITS, SDFITS (singledish fits), ASAP's scantable format and aips++
532MeasurementSet2 format.
533
534Example usage:
535
536\begin{verbatim}
537 ASAP> scan = scantable('2004-11-23_1841-P484.rpf')
538
539 # Don't scan average the data
540 ASAP> scan = scantable('2004-11-23_1841-P484.rpf', average=False)
541\end{verbatim}
542
543
544\subsection{Reader object}
545
546\index{Reader object}\index{Scantable!reader object}For more control
547when reading data into ASAP, the reader object should be used. This
548has the option of only reading in a range of integrations, only a
549specified beam or IF and does not perform any scan averaging of the
550data, allowing analysis of the individual integrations. Note that due
551to limitation of the RPFITS library, only one reader object can be
552open at one time reading RPFITS files. To read multiple RPFITS files,
553the old reader must be destroyed before the new file is opened.
554However, multiple readers can be created and attached to SDFITS files.
555
556
557Example usage:
558
559\begin{verbatim}
560 ASAP> r = reader('2003-03-16_082048_t0002.rpf')
561 ASAP> r.summary()
562 ASAP> scan = r.read()
563 ASAP> s = r.read(range(100)) # To read in the first 100 integrations
564 ASAP> del r
565\end{verbatim}
566
567\section{Basic Processing}
568
569In the following section, a simple data reduction to form a quotient
570spectrum of a single source is followed. It has been assume that the
571\cmd{.asaprc} file has {\em not} been used to change the \cmd{insitu}
572default value from \cmd{True}.
573
574\subsection{Auto quotient}
575\index{Auto quotient}Quotients can be computed ``automatically''. This
576requires the data to have matching source/reference pairs or one
577reference for multiple sources. Auto quotient assumes reference scans
578have a trailing ``\_R'' in the source name for data from Parkes and
579Mopra, and a trailing ``e'' or ``w'' for data fro, Tidbinbilla.
580
581\begin{verbatim}
582 ASAP> q = s.auto_quotient()
583\end{verbatim}
584
585%If this is not sufficient the following alternative method can be used.
586%
587%\subsection{Separate reference and source observations}
588%
589%\index{Quotient spectra}Most data from ATNF observatories
590%distinguishes on and off source data using the file name. This makes
591%it easy to create two scantables with the source and reference
592%data. As long as there was exactly one reference observation for each
593%on source observation for following method will work.
594%
595%For Mopra and Parkes data:
596%\begin{verbatim}
597% ASAP> r = scans.get_scan('*_R')
598% ASAP> s = scans.get_scan('*_S')
599%\end{verbatim}
600%
601%For Tidbinbilla data
602%\begin{verbatim}
603% ASAP> r = scans.get_scan('*_[ew]')
604% ASAP> s = scans.get_scan('*_[^ew]')
605%\end{verbatim}
606%
607%\subsection{Make the quotient spectra}
608%
609%Use the quotient function
610%
611%\begin{verbatim}
612% ASAP> q = s.quotient(r)
613%\end{verbatim}
614%
615%This uses the rows in scantable \cmd{r} as reference spectra for the
616%rows in scantable \cmd{s}. Scantable \cmd{r} must have either 1 row
617%(which is applied to all rows in \cmd{s}) or both scantables must have
618%the same number of rows. By default the quotient spectra is calculated
619%to preserve continuum emission. If you wish to remove the continuum
620%contribution, use the \cmd{preserve} argument:
621%
622%\begin{verbatim}
623% ASAP> q = s.quotient(r, preserve=True)
624%\end{verbatim}
625
626\subsection{Time average separate scans}
627
628\index{Time average}If you have observed the source with multiple
629source/reference cycles you will want to scan-average the quotient
630spectra together.
631
632\begin{verbatim}
633 ASAP> av = q.average_time()
634\end{verbatim}
635
636If for some you want to average multiple sets of scantables together
637you can:
638
639\begin{verbatim}
640 ASAP> av = average_time(q1, q2, q3)
641\end{verbatim}
642
643The default is to use integration time weighting. The alternative is
644to use none, variance, Tsys weighting or Tsys \& integration time.
645
646\begin{verbatim}
647 ASAP> av = average_time(q, weight='tintsys')
648\end{verbatim}
649
650To use variance based weighting, you need to supply a mask saying which
651channel range you want it to calculate the variance from.
652
653\begin{verbatim}
654 ASAP> msk = scans.create_mask([200,400],[600,800])
655 ASAP> av = average_time(scans, mask=msk, weight='var')
656\end{verbatim}
657
658If you have not observed your data with Doppler tracking (or run
659\cmd{freq\_align} explicitally) you should align the data in frequency
660before averaging.
661
662\begin{verbatim}
663 ASAP> av = scans.average_time(align=True)
664\end{verbatim}
665
666Note that, if needed, you should run \cmd{gain\_el} and \cmd{opacity}
667before you average the data in time (\S \ref{sec:gainel} \&
668\ref{sec:freqalign}).
669
670\subsection{Baseline fitting}
671
672\index{Baseline fitting}To make a baseline fit, you must first create
673a mask of channels to use in the baseline fit.
674
675\begin{verbatim}
676 ASAP> msk = scans.create_mask([100,400],[600,900])
677 ASAP> scans.poly_baseline(msk, 1)
678\end{verbatim}
679
680This will fit a first order polynomial to the selected channels and subtract
681this polynomial from the full spectra.
682
683\subsubsection{Auto-baselining}
684
685\index{Auto-baseline}The function \cmd{auto\_poly\_baseline} can be used to automatically
686baseline your data without having to specify channel ranges for the
687line free data. It automatically figures out the line-free emission
688and fits a polynomial baseline to that data. The user can use masks to
689fix the range of channels or velocity range for the fit as well as
690mark the band edge as invalid.
691
692Simple example
693
694\begin{verbatim}
695 ASAP> scans.auto_poly_baseline(order=2,threshold=5)
696\end{verbatim}
697
698\cmd{order} is the polynomial order for the fit. \cmd{threshold} is
699the SNR threshold to use to deliminate line emission from
700signal. Generally the value of threshold is not too critical, however
701making this too large will compromise the fit (as it will include
702strong line features) and making it too small will mean it cannot find
703enough line free channels.
704
705
706Other examples:
707
708\begin{verbatim}
709 # Don't try and fit the edge of the bandpass which is noisier
710 ASAP> scans.auto_poly_baseline(edge=(500,450),order=3,threshold=3)
711
712 # Only fit a given region around the line
713 ASAP> scans.set_unit('km/s')
714 ASAP> msk = scans.create_mask((-60,-20))
715 ASAP> scans.auto_poly_baseline(mask=msk,order=3,threshold=3)
716
717\end{verbatim}
718
719\subsection{Average the polarisations}
720
721\index{average\_pol}If you are just interested in the highest SNR for total intensity you
722will want to average the parallel polarisations together.
723
724\begin{verbatim}
725 ASAP> scans.average_pol()
726\end{verbatim}
727
728\subsection{Calibration}
729
730\index{Calibration}For most uses, calibration happens transparently as the input data
731contains the Tsys measurements taken during observations. The nominal
732``Tsys'' values may be in Kelvin or Jansky. The user may wish to
733supply a Tsys correction or apply gain-elevation and opacity
734corrections.
735
736\subsubsection{Brightness Units}
737
738\index{Brightness Units}RPFITS files do not contain any information as
739to whether the telescope calibration was in units of Kelvin or
740Janskys. On reading the data a default value is set depending on the
741telescope and frequency of observation. If this default is incorrect
742(you can see it in the listing from the \cmd{summary} function) the
743user can either override this value on reading the data or later.
744E.g:
745
746\begin{verbatim}
747 ASAP> scans = scantable(('2004-11-23_1841-P484.rpf', unit='Jy')
748 # Or in two steps
749 ASAP> scans = scantable(('2004-11-23_1841-P484.rpf')
750 ASAP> scans.set_fluxunit('Jy)
751\end{verbatim}
752
753\subsubsection{Tsys scaling}
754
755\index{Tsys scaling}Sometime the nominal Tsys measurement at the
756telescope is wrong due to an incorrect noise diode calibration. This
757can easily be corrected for with the scale function. By default,
758\cmd{scale} only scans the spectra and not the corresponding Tsys.
759
760\begin{verbatim}
761 ASAP> scans.scale(1.05, tsys=True)
762\end{verbatim}
763
764\subsubsection{Unit Conversion}
765
766\index{Unit conversion}To convert measurements in Kelvin to Jy (and
767vice versa) the global function \cmd{convert\_flux} is needed. This
768converts and scales the data from K to Jy or vice-versa depending on
769what the current brightness unit is set to. The function knows the
770basic parameters for some frequencies and telescopes, but the user may
771need to supply the aperture efficiency, telescope diameter or the Jy/K
772factor.
773
774\begin{verbatim}
775 ASAP> scans.convert_flux() # If efficency known
776 ASAP> scans.convert_flux(eta=0.48) # If telescope diameter known
777 ASAP> scans.convert_flux(eta=0.48,d=35) # Unknown telescope
778 ASAP> scans.convert_flux(jypk=15) # Alternative
779\end{verbatim}
780
781\subsubsection{Gain-Elevation and Opacity Corrections}
782\label{sec:gainel}
783
784\index{Gain-elevation}As higher frequencies (particularly $>$20~GHz)
785it is important to make corrections for atmospheric opacity and
786gain-elevation effects.
787
788Note that currently the elevation is not written correctly into
789Tidbinbilla rpfits files. This means that gain-elevation and opacity
790corrections will not work unless these get recalculated.
791
792\begin{verbatim}
793 ASAP> scans.recalc_azel() # recalculate az/el based on pointing
794\end{verbatim}
795
796Gain-elevation curves for some telescopes and frequencies are known to
797ASAP (currently only for Tidbinbilla at 20~GHz). In these cases
798making gain-corrections is simple. If the gain curve for your data is
799not known, the user can supply either a gain polynomial or text file
800tabulating gain factors at a range of elevations (see \cmd{help
801scantable.gain\_el}).
802
803Examples:
804
805\begin{verbatim}
806 ASAP> scans.gain_el() # If gain table known
807 ASAP> scans.gain_el(poly=[3.58788e-1,2.87243e-2,-3.219093e-4])
808\end{verbatim}
809
810\index{Opacity}Opacity corrections can be made with the global
811function \cmd{opacity}. This should work on all telescopes as long as
812a measurement of the opacity factor was made during the observation.
813
814\begin{verbatim}
815 ASAP> scans.opacity(0.083)
816\end{verbatim}
817
818Note that at 3~mm Mopra uses a paddle wheel for Tsys calibration,
819which takes opacity effects into account (to first order). ASAP
820opacity corrections should not be used for Mopra 3-mm data.
821
822\subsection{Frequency Frame Alignment}
823\label{sec:freqalign}
824
825\index{Frequency alignment}\index{Velicity alignment}When time
826averaging a series of scans together, it is possible that the velocity
827scales are not exactly aligned. This may be for many reasons such as
828not Doppler tracking the observations, errors in the Doppler tracking
829etc. This mostly affects very long integrations or integrations
830averaged together from different days. Before averaging such data
831together, they should be frequency aligned using \cmd{freq\_align}.
832
833E.g.:
834
835\begin{verbatim}
836 ASAP> scans.freq_align()
837 ASAP> av = average_time(scans)
838\end{verbatim}
839
840{\em A Global freq\_align command will be made eventually}
841
842To average together data taken on different days, which are in
843different scantables, each scantable must aligned to a common
844reference time then the scantables averaged. The simplest way of
845doing this is to allow ASAP to choose the reference time for the first
846scantable then using this time for the subsequent scantables.
847
848\begin{verbatim}
849 ASAP> scans1.freq_align() # Copy the refeference Epoch from the output
850 ASAP> scans2.freq_align(reftime='2004/11/23/18:43:35')
851 ASAP> scans3.freq_align(reftime='2004/11/23/18:43:35')
852 ASAP> av = average_time(scans1, scans2, scans3)
853\end{verbatim}
854
855\section{Scantable manipulation}
856
857\index{Scantable!manipulation}While it is very useful to have many
858independent sources within one scantable, it is often inconvenient for
859data processing. The \cmd{get\_scan} function can be used to create a
860new scantable with a selection of scans from a scantable. The
861selection can either be on the source name, with simple wildcard
862matching or set of scan ids. Internally this uses the selector object,
863so for more complicated selection the selector should be used directly
864instead.
865
866For example:
867
868\begin{verbatim}
869 ASAP> ss = scans.get_scan(10) # Get the 11th scan (zero based)
870 ASAP> ss = scans.get_scan(range(10)) # Get the first 10 scans
871 ASAP> ss = scans.get_scan(range(10,20)) # Get the next 10 scans
872 ASAP> ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans
873
874 ASAP> ss = scans.get_scan('345p407') # Get a specific source
875 ASAP> ss = scans.get_scan('345*') # Get a few sources
876
877 ASAP> r = scans.get_scan('*_R') # Get all reference sources (Parkes/Mopra)
878 ASAP> s = scans.get_scan('*_S') # Get all program sources (Parkes/Mopra)
879 ASAP> r = scans.get_scan('*[ew]') # Get all reference sources (Tid)
880 ASAP> s = scans.get_scan('*[^ew]') # Get all program sources (Tid)
881
882\end{verbatim}
883
884To copy a scantable the following does not work:
885
886\begin{verbatim}
887 ASAP> ss = scans
888\end{verbatim}
889
890as this just creates a reference to the original scantable. Any
891changes made to \cmd{ss} are also seen in \cmd{scans}. To duplicate a
892scantable, use the copy function.
893
894\begin{verbatim}
895 ASAP> ss = scans.copy()
896\end{verbatim}
897
898\section{Data Output}
899
900\index{Scantable!save}\index{Saving data}ASAP can save scantables in a
901variety of formats, suitable for reading into other packages. The
902formats are:
903
904{\em Currently only raw ASAP output is available. Other formats will be added soon}
905
906\begin{itemize}
907\item[ASAP] This is the internal format used for ASAP. It is the only
908 format that allows the user to restore the data, fits etc. without
909 loosing any information. As mentioned before, the ASAP scantable is
910 an AIPS++ Table (a memory-based table). This function just converts
911 it to a disk-based Table. You can the access that Table with the
912 AIPS++ Table browser or any other AIPS++ tool.
913
914\item[SDFITS] The Single Dish FITS format. This format was designed to
915 for interchange between packages, but few packages actually can read
916 it.
917
918\item[FITS] This uses simple ``image'' fits to save the data, each row
919 being written to a separate fits file. This format is suitable for
920 importing the data into CLASS.
921
922\item[ASCII] A simple text based format suitable for the user to
923processing using Perl or, Python, gnuplot etc.
924
925\item[MS2] Saves the data in an aips++ MeasurementSet V2 format.
926You can also access this with the Table browser and other AIPS++
927tools.
928
929\end{itemize}
930
931The default output format can be set in the users {\tt .asaprc} file.
932Typical usages are:
933
934\begin{verbatim}
935 ASAP> scans.save('myscans') # Save in default format
936 ASAP> scans.save('myscans', 'FITS') # Save as FITS for exporting into CLASS
937
938 ASAP> scans.save('myscans', stokes=True) # Convert raw polarisations into Stokes
939 ASAP> scans.save('myscans', overwrite=True) # Overwrite an existing file
940\end{verbatim}
941
942
943\section{Plotter}
944
945\index{Plotter}Scantable spectra can be plotted at any time. An asapplotter object is
946used for plotting, meaning multiple plot windows can be active at the
947same time. On start up a default asapplotter object is created called
948``plotter''. This would normally be used for standard plotting.
949
950The plotter, optionally, will run in a multipanel mode and contain
951multiple plots per panel. The user must tell the plotter how they want
952the data distributed. This is done using the set\_mode function. The
953default can be set in the users {\tt .asaprc} file. The units (and frame
954etc) of the abscissa will be whatever has previously been set by
955\cmd{set\_unit}, \cmd{set\_freqframe} etc.
956
957Typical plotter usage would be:
958
959\begin{verbatim}
960 ASAP> scans.set_unit('km/s')
961 ASAP> plotter.set_mode(stacking='p',panelling='t')
962 ASAP> plotter.plot(scans)
963\end{verbatim}
964
965This will plot multiple polarisation within each plot panel and each
966scan row in a separate panel.
967
968Other possibilities include:
969
970\begin{verbatim}
971 # Plot multiple IFs per panel
972 ASAP> plotter.set_mode(stacking='i',panelling='t')
973
974 # Plot multiple beams per panel
975 ASAP> plotter.set_mode(stacking='b',panelling='t')
976
977 # Plot one IF per panel, time stacked
978 ASAP> plotter.set_mode('t', 'i')
979
980 # Plot each scan in a seperate panel
981 ASAP> plotter.set_mode('t', 's')
982
983\end{verbatim}
984
985\subsection{Plot Selection}
986\label{sec:plotter_cursor}
987
988\index{Plotter!selection}The plotter can plot up to 25 panels and
989stacked spectra per panel. If you have data larger than this (or for
990your own sanity) you need to select a subset of this data. This is
991particularly true for multibeam or multi IF data. The selector object
992should be used for this purpose. Selection can either be applide to
993the scantable or directly to the plotter, the end result is the same.
994
995Examples:
996
997\begin{verbatim}
998 ASAP> selection = selector()
999 # Select second IF
1000 ASAP> selection.set_if(1)
1001 ASAP> plotter.set_selection(selection)
1002
1003 # Select first 4 beams
1004 ASAP> selection.set_beam([0,1,2,3])
1005 ASAP> plotter.set_selection(selection)
1006
1007 # Select a few scans
1008 ASAP> selection.set_scans([2,4,6,10])
1009 ASAP> plotter.set_selection(selection)
1010
1011 # Multiple selection
1012 ASAP> selection.set_if(1)
1013 ASAP> selection.set_scans([2,4,6,10])
1014 ASAP> plotter.set_selection(selection)
1015
1016\end{verbatim}
1017
1018\subsection{Plot Control}
1019
1020\index{Plotter!control}The plotter window has a row of buttons on the
1021lower left. These can be used to control the plotter (mostly for
1022zooming the individual plots). From left to right:
1023
1024\begin{itemize}
1025
1026\item[Home] This will unzoom the plots to the original zoom factor
1027
1028\item[Plot history] (left and right arrow). The plotter keeps a
1029history of zoom settings. The left arrow sets the plot zoom to the
1030previous value. The right arrow returns back again. This allows you,
1031for example, to zoom in on one feature then return the plot to how it
1032was previously.
1033
1034\item[Pan] (The Cross) This sets the cursor to pan, or scroll mode
1035 allowing you to shift the plot within the window. Useful when
1036 zoomed in on a feature.
1037
1038\item[Zoom] (the letter with the magnifying glass) lets you draw a
1039 rectangle around a region of interest then zooms in on that
1040 region. Use the plot history to unzoom again.
1041
1042\item[Adjust] (rectangle with 4 arrows) adjust subplot paramaters
1043 (space at edge of plots)
1044
1045\item[Save] (floppy disk). Save the plot as a postscript or .png file
1046
1047You can also type ``g'' in the plot window to toggle on and off grid
1048lines. Typing 'l' turns on and off logarithmic Y-axis.
1049
1050\end{itemize}
1051
1052\subsection{Other control}
1053
1054The plotter has a number of functions to describe the layout of the
1055plot. These include \cmd{set\_legend}, \cmd{set\_layout} and \cmd{set\_title}.
1056
1057To set the exact velocity or channel range to be plotted use the
1058\cmd{set\_range} function. To reset to the default value, call
1059\cmd{set\_range} with no arguments. E.g.
1060
1061\begin{verbatim}
1062 ASAP> scans.set_unit('km/s')
1063 ASAP> plotter.plot(scans)
1064 ASAP> plotter.set_range(-150,-50)
1065 ASAP> plotter.set_range() # To reset
1066\end{verbatim}
1067
1068Both the range of the ``x'' and ``y'' axis can be set at once, if desired:
1069
1070\begin{verbatim}
1071 ASAP> plotter.set_range(-10,30,-1,6.6)
1072\end{verbatim}
1073
1074To save a hardcopy of the current plot, use the save function, e.g.
1075
1076\begin{verbatim}
1077 ASAP> plotter.save('myplot.ps')
1078\end{verbatim}
1079
1080\section{Fitting}
1081
1082\index{Fitting}Currently multicomponent Gaussian function is
1083available. This is done by creating a fitting object, setting up the
1084fit and actually fitting the data. Fitting can either be done on a
1085single scantable row/cursor selection or on an entire scantable using
1086the \cmd{auto\_fit} function.
1087
1088\begin{verbatim}
1089 ASAP> f = fitter()
1090 ASAP> f.set_function(gauss=2) # Fit two Gaussians
1091 ASAP> f.set_scan(scans)
1092 ASAP> scans.set_cursor(0,0,1) # Fit the second polarisation
1093 ASAP> scans.set_unit('km/s') # Make fit in velocity units
1094 ASAP> f.fit(1) # Run the fit on the second row in the table
1095 ASAP> f.plot() # Show fit in a plot window
1096 ASAP> f.get_parameters() # Return the fit paramaters
1097\end{verbatim}
1098
1099This auto-guesses the initial values of the fit and works well for data
1100without extra confusing features. Note that the fit is performed in
1101whatever unit the abscissa is set to.
1102
1103If you want to confine the fitting to a smaller range (e.g. to avoid
1104band edge effects or RFI you must set a mask.
1105
1106\begin{verbatim}
1107 ASAP> f = fitter()
1108 ASAP> f.set_function(gauss=2)
1109 ASAP> scans.set_unit('km/s') # Set the mask in channel units
1110 ASAP> msk = s.create_mask([1800,2200])
1111 ASAP> scans.set_unit('km/s') # Make fit in velocity units
1112 ASAP> f.set_scan(s,msk)
1113 ASAP> f.fit()
1114 ASAP> f.plot()
1115 ASAP> f.get_parameters()
1116\end{verbatim}
1117
1118If you wish, the initial parameter guesses can be specified and
1119specific parameters can be fixed:
1120
1121\begin{verbatim}
1122 ASAP> f = fitter()
1123 ASAP> f.set_function(gauss=2)
1124 ASAP> f.set_scan(s,msk)
1125 ASAP> f.fit() # Fit using auto-estimates
1126 # Set Peak, centre and fwhm for the second gaussian.
1127 # Force the centre to be fixed
1128 ASAP> f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
1129 ASAP> f.fit() # Re-run the fit
1130\end{verbatim}
1131
1132The fitter \cmd{plot} function has a number of options to either view
1133the fit residuals or the individual components (by default it plots
1134the sum of the model components).
1135
1136Examples:
1137
1138\begin{verbatim}
1139 # Plot the residual
1140 ASAP> f.plot(residual=True)
1141
1142 # Plot the first 2 componentsa
1143 ASAP> f.plot(components=[0,1])
1144
1145 # Plot the first and third component plus the model sum
1146 ASAP> f.plot(components=[-1,0,2]) # -1 means the compoment sum
1147\end{verbatim}
1148
1149\subsection{Fit saving}
1150
1151\index{Fitter!Fit saving}One you are happy with your fit, it is
1152possible to store it as part of the scantable.
1153
1154\begin{verbatim}
1155 ASAP> f.storefit()
1156\end{verbatim}
1157
1158This will be saved to disk with the data, if the ``ASAP'' file format
1159is selected. Multiple fits to the same data can be stored in the
1160scantable.
1161
1162The scantable function \cmd{get\_fit} can be used to retrieve the
1163stored fits. Currently the fit parameters are just printed to the
1164screen.
1165
1166\begin{verbatim}
1167 ASAP> scans.get_fit(4) # Print fits for row 4
1168\end{verbatim}
1169
1170\section{Polarisation}
1171
1172\index{Polarisation}Currently ASAP only supports polarmetric analysis
1173on linearly polarised feeds and the cross polarisation products
1174measured. Other cases will be added on an as needed basic.
1175
1176Conversions of linears to Stokes or Circular polarisations are done
1177``on-the-fly''. Leakage cannot be corrected for nor are these routines
1178able to calibrate position angle offsets.
1179
1180\subsection{Simple Calibration}
1181
1182\index{Polarisation!calibration}It is possible that there is a phase
1183offset between polarisation which will effect the phase of the cross
1184polarisation correlation, and so give rise to spurious
1185polarisation. \cmd{rotate\_xyphase} can be used to correct for this
1186error. At this point, the user must know how to determine the size of
1187the phase offset themselves.
1188
1189\begin{verbatim}
1190 ASAP> scans.rotate_xyphase(10.5) # Degrees
1191\end{verbatim}
1192
1193Note that if this function is run twice, the sum of the two values is
1194applied because it is done in-situ.
1195
1196A correction for the receiver parallactic angle may need to be made,
1197generally because of how it is mounted. Use \cmd{rotate\_linpolphase}
1198to correct the position angle. Running this function twice results in
1199the sum of the corrections being applied because it is applied
1200in-situ.
1201
1202\begin{verbatim}
1203 ASAP> scans.rotate_linpolphase(-45) # Degrees; correct for receiver mounting
1204\end{verbatim}
1205
1206If the sign of the complex correlation is wrong (this can happen
1207depending on the correlator configuration), use \cmd{invert\_phase} to
1208change take the complex conjugate of the complex correlation
1209term. This is always performed in-situ.
1210
1211\begin{verbatim}
1212 ASAP> scans.invert_phase()
1213\end{verbatim}
1214
1215Depending on how the correlator is configured, ``BA'' may be
1216correlated insead of ``AB''. Use \cmd{swap\_linears} to correct for
1217this problem:
1218
1219\begin{verbatim}
1220 ASAP> scans.swap_linears()
1221\end{verbatim}
1222
1223\subsection{Plotting}
1224\label{sec:polplot}
1225
1226\index{Polarisation!plotting}To plot Stokes values, a selector object
1227must be created and the set\_polarisation function used to select the
1228desired polarisation products.
1229
1230The values which can be plotted include a selection of [I,Q,U,V], [I,
1231Plinear, Pangle, V], [RR, LL] or [XX, YY, Real(XY),
1232Imaginary(XY)]. (Plinear and Pangle are the percentage and position
1233angle of linear polarisation). Conversion to circular polarisations
1234are currently not available.
1235
1236Example:
1237
1238\begin{verbatim}
1239 ASAP> selection = selector()
1240
1241 ASAP> selection.set_polarisations([``I'', ``Q'', ``U'', ``V''])
1242 ASAP plotter.set_selection(selection); # Select I, Q, U \& V
1243
1244 ASAP> selection.set_polarisations([``I'', ``Q'')
1245 ASAP plotter.set_selection(selection); # Select just I \& Q
1246
1247 ASAP> selection.set_polarisations([``RR'', ``LL'')
1248 ASAP plotter.set_selection(selection); # Select just RR \& LL
1249
1250 ASAP> selection.set_polarisations([``XX'', ``YY'')
1251 ASAP plotter.set_selection(selection); # Select linears
1252
1253 ASAP> selection.set_polarisations([``I'', ``Plinear'')
1254 ASAP plotter.set_selection(selection); # Select linears
1255
1256\end{verbatim}
1257
1258Scan, beam and IF selection are also available in the selector object as
1259describe in section~\ref{sec:selection}.
1260
1261\subsection{Saving}
1262
1263\index{Polarisation!saving}When saving data using the \cmd{save}
1264function, the \cmd{stokes} argument can be used to save the data as
1265Stoke values when saving in FITS format.
1266
1267Example:
1268
1269\begin{verbatim}
1270 ASAP> scans.save('myscan.sdfits', 'SDFITS', stokes=True)
1271\end{verbatim}
1272
1273
1274\section{Scantable Mathematics}
1275
1276\index{Scantable!maths}It is possible to to simple mathematics
1277directly on scantables from the command line using the \cmd{+, -, *,
1278/} operators as well as their cousins \cmd{+=, -= *=, /=}. This works
1279between two scantables or a scantable and a float. (Note that it does
1280not work for integers).
1281
1282\begin{verbatim}
1283 ASAP> sum = scan1+scan2
1284 ASAP> scan2 = scan1+2.0
1285 ASAP> scan *= 1.05
1286\end{verbatim}
1287
1288\section{Scripting}
1289
1290\index{Scripting}Because asap is based on python, it easy for the user
1291write their own scripts and functions to process data. This is highly
1292recommended as most processing of user data could then be done in a
1293couple of steps using a few simple user defined functions. A Python
1294primer is beyond the scope of this userguide. See the asap home pages
1295for a scripting tutorial or the main python website for comprehensive
1296documentation.
1297
1298\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
1299
1300\hspace{1cm} http://www.python.org/doc/Introduction.html
1301
1302\subsection{Running scripts}
1303
1304The asap global function \cmd{execfile} reads the named text file and
1305executes the contained python code. This file can either contain
1306function definitions which will be used in subsequent processing or
1307just a set of commands to process a specific dataset.
1308
1309\subsection{asapuserfuncs.py}
1310
1311The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
1312asap is started. The user can use this to define a set of user
1313functions which are automatically available each time asap is
1314used. The \cmd{execfile} function can be called from within this file.
1315
1316\section{Worked examples}
1317
1318In the following section a few examples of end-to-end processing of
1319some data in asap are given.
1320
1321\subsection{Mopra}
1322\index{Mopra}
1323
1324The following example is of some dual polarisation, position switched
1325data from Mopra. The source has been observed mulitple times split
1326into a number of seperate rpfits files. To make the processing easier,
1327the first step is to \cmd{cat} the seeprate rpfits files together and
1328load as a whole (future versions of asap will make this unnecessary).
1329
1330
1331\begin{verbatim}
1332# Concatenate the individual rpfits files together before loading
1333!cat 2005-06*.rpf > data.rpf
1334
1335# Load the data into a scantable
1336data = scantable('data.rpf')
1337print data
1338
1339# Form the quotient spectra
1340q = data.auto_quotient()
1341print q
1342
1343# Look at the spectra
1344plotter.plot(q)
1345
1346# Velocity align the data before averaging
1347q.set_unit('km/s')
1348q.set_freqframe('LSRK')
1349q.freq_align()
1350
1351# Average all scans in time
1352av = q.average_time()
1353plotter.plot(av)
1354
1355# Remove the baseline
1356msk = av.create_mask([100,130],[160,200])
1357av.poly_baseline(msk,2)
1358
1359# Average the two polarisations together
1360iav = av.average_pol()
1361print iav
1362plotter.plot(iav)
1363
1364# Set a sensible velocity range on the plot
1365plotter.set_range(85,200)
1366
1367# Smooth the data a little
1368av.smooth('gauss',4)
1369plotter.plot()
1370
1371# Fit a guassian to the emission
1372f = fitter()
1373f.set_function(gauss=1)
1374f.set_scan(av)
1375f.fit()
1376
1377# View the fit
1378f.plot()
1379
1380# Get the fit parameters
1381f.get_parameters()
1382
1383\end{verbatim}
1384
1385
1386\subsection{Parkes Polarimetry}
1387
1388\index{Parkes}\index{Polarisation}The following example is processing
1389of some Parkes polarmetric observations of OH masers at
13901.6~GHz. Because digital filters where used in the backend, the
1391baselines are stable enough not to require a quotient spectra. The
13924~MHz bandwidth is wide enough to observe both the 1665 and 1667~MHz
1393OH maser transitions. Each source was observed once for about 10
1394minutes. Tsys information was not written to the rpfits file (a
1395nominal 25K values was used), so the amplitudes need to be adjusted
1396based on a separate log file. A simple user function is used to
1397simplify this, contained in a file called mypol.py:
1398
1399\begin{verbatim}
1400def xyscale(data,xtsys=1.0,ytsys=1.0,nomtsys=25.0) :
1401
1402 data.set_cursor(pol=0)
1403 data.scale(xtsys/nomtsys,allaxes=False)
1404
1405 data.set_cursor(pol=1)
1406 data.scale(ytsys/nomtsys,allaxes=False)
1407
1408 data.set_cursor(pol=2)
1409 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
1410
1411 data.set_cursor(pol=3)
1412 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
1413\end{verbatim}
1414
1415The typical asap session would be
1416
1417\begin{verbatim}
1418
1419# Remind ourself the name of the rpfits files
1420ls
1421
1422# Load data from an rpfits file
1423d1665 = scantable('2005-10-27_0154-P484.rpf')
1424
1425# Check what we have just loaded
1426d1665.summary
1427
1428# View the data in velocity
1429d1665.set_unit('km/s')
1430d1665.set_freqframe('LSRK')
1431
1432# Correct for the known phase offset in the crosspol data
1433d1665.rotate_xyphase(-4)
1434
1435# Create a copy of the data and set the rest frequency to the 1667 MHz
1436# transition
1437d1667 = d1665.copy()
1438d1667.set_restfreqs(lines=['OH1667'])
1439d1667.summary
1440
1441# Copy out the scan we wish to process
1442g351_5 = d1665.get_scan('351p160')
1443g351_7 = d1667.get_scan('351p160')
1444
1445# Plot the data
1446plotter.plot(g351_5,g351_7) # Only shows one panel
1447
1448# Tell the plotter to stack polarisation and panel scans
1449plotter.set_mode('p','s')
1450
1451# Correct for the Tsys using our predefined function
1452execfile('mypol.py') # Read in the function
1453xyscale(g351_5,23.2,22.7) # Execute it on the data
1454xyscale(g351_7,23.2,22.7)
1455
1456# Only plot the velocity range of interest
1457plotter.set_range(-30,10)
1458
1459# Baseline the data
1460msk = g351_5.create_mask([-20,-15],[0,5])
1461g351_5.poly_baseline(msk,1)
1462msk = g351_7.create_mask([-20,-15],[0,5])
1463g351_7.poly_baseline(msk,1)
1464
1465# Update the plot with the baselined data
1466plotter.plot()
1467
1468# Look at the various polarisation products
1469plotter.set_cursor(pol='RR LL')
1470plotter.set_cursor(pol='I Plinear')
1471plotter.set_cursor(pol='I Q U V')
1472
1473# Save the plot as postscript
1474plotter.save('g361_stokes.ps')
1475
1476# Save the process spectra
1477g351_5.save('junk5.asap')
1478g351_7.save('junk7.asap')
1479
1480\end{verbatim}
1481
1482\subsection{Tidbinbilla}
1483
1484\index{Tidbinbilla}The following example is processing of some
1485Tidbinbilla observations of NH$_3$ at 12~mm. Tidbinbilla has (at the
1486time of observations) a single polarisation, but can process two IFs
1487simultaneously. In the example, the first half of the observation was
1488observing the (1,1) and (2,2) transitions simultaneously). The second
1489half observed only the (4,4) transition due to bandwidth
1490limitations. The data is position switched, observing first an
1491reference to the west, then the source twice and finally reference to
1492the east.
1493
1494\begin{verbatim}
1495
1496# Load the rpfits file and inspect
1497d = scantable('2003-03-16_082048_t0002.rpf')
1498print d
1499
1500# Make the quotient spectra
1501q = d.auto_quotient()
1502print q
1503
1504# Plot/select in velocity
1505q.set_freqframe('LSRK')
1506q.set_unit('km/s')
1507
1508# Seperate data from the (1,1)&(2,2) and (4,4) transitions
1509g1 = q.get_scan(range(6)) # Rows 0..5
1510g2 = q.get_scan(range(6,12)) # Rows 6..11
1511
1512# Align data in velocity
1513g1.freq_align(perif=True)
1514g2.freq_align(perif=True)
1515
1516# Average individual scans
1517a1 = g1.average_time()
1518a2 = g2.average_time()
1519
1520# Rpfits file only contrains a single rest frequency. Set both
1521a1.set_restfreqs(freqs= [23694.4700e6,23722.6336e6])
1522
1523plotter.plot(a1,a2)
1524plotter.set_mode('i','s')
1525
1526a1.auto_poly_baseline()
1527a2.auto_poly_baseline()
1528
1529plotter.plot()
1530
1531a1.smooth('gauss',5)
1532a2.smooth('gauss',5)
1533plotter.plot()
1534
1535\end{verbatim}
1536
1537\newpage
1538
1539\section{Appendix}
1540
1541\subsection{Function Summary}
1542
1543\index{Functions!summary}%
1544\begin{verbatim}
1545 [The scan container]
1546 scantable - a container for integrations/scans
1547 (can open asap/rpfits/sdfits and ms files)
1548 copy - returns a copy of a scan
1549 get_scan - gets a specific scan out of a scantable
1550 summary - print info about the scantable contents
1551 set_cursor - set a specific Beam/IF/Pol 'cursor' for
1552 further use
1553 get_cursor - print out the current cursor position
1554 stats - get specified statistic of the spectra in
1555 the scantable
1556 stddev - get the standard deviation of the spectra
1557 in the scantable
1558 get_tsys - get the TSys
1559 get_time - get the timestamps of the integrations
1560 get_azimuth - get the azimuth of the scans
1561 get_elevation - get the elevation of the scans
1562 get_parangle - get the parallactic angle of the scans
1563 get_unit - get the currnt unit
1564 set_unit - set the abcissa unit to be used from this
1565 point on
1566 get_abcissa - get the abcissa values and name for a given
1567 row (time)
1568 set_freqframe - set the frame info for the Spectral Axis
1569 (e.g. 'LSRK')
1570 set_doppler - set the doppler to be used from this point on
1571 set_instrument - set the instrument name
1572 get_fluxunit - get the brightness flux unit
1573 set_fluxunit - set the brightness flux unit
1574 create_mask - return an mask in the current unit
1575 for the given region. The specified regions
1576 are NOT masked
1577 get_restfreqs - get the current list of rest frequencies
1578 set_restfreqs - set a list of rest frequencies
1579 lines - print list of known spectral lines
1580 flag_spectrum - flag a whole Beam/IF/Pol
1581 save - save the scantable to disk as either 'ASAP'
1582 or 'SDFITS'
1583 nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
1584 history - print the history of the scantable
1585 get_fit - get a fit which has been stored witnh the data
1586 average_time - return the (weighted) time average of a scan
1587 or a list of scans
1588 average_pol - average the polarisations together.
1589 The dimension won't be reduced and
1590 all polarisations will contain the
1591 averaged spectrum.
1592 auto_quotient - return the on/off quotient with
1593 automatic detection of the on/off scans
1594 quotient - return the on/off quotient
1595 scale - return a scan scaled by a given factor
1596 add - return a scan with given value added
1597 bin - return a scan with binned channels
1598 resample - return a scan with resampled channels
1599 smooth - return the spectrally smoothed scan
1600 poly_baseline - fit a polynomial baseline to all Beams/IFs/Pols
1601 auto_poly_baseline - automatically fit a polynomial baseline
1602 recalc_azel - recalculate azimuth and elevation based on
1603 the pointing
1604 gain_el - apply gain-elevation correction
1605 opacity - apply opacity correction
1606 convert_flux - convert to and from Jy and Kelvin brightness
1607 units
1608 freq_align - align spectra in frequency frame
1609 rotate_xyphase - rotate XY phase of cross correlation
1610 rotate_linpolphase - rotate the phase of the complex
1611 polarization O=Q+iU correlation
1612 [Math] Mainly functions which operate on more than one scantable
1613
1614 average_time - return the (weighted) time average
1615 of a list of scans
1616 quotient - return the on/off quotient
1617 simple_math - simple mathematical operations on two scantables,
1618 'add', 'sub', 'mul', 'div'
1619 [Fitting]
1620 fitter
1621 auto_fit - return a scan where the function is
1622 applied to all Beams/IFs/Pols.
1623 commit - return a new scan where the fits have been
1624 commited.
1625 fit - execute the actual fitting process
1626 store_fit - store the fit paramaters in the data (scantable)
1627 get_chi2 - get the Chi^2
1628 set_scan - set the scantable to be fit
1629 set_function - set the fitting function
1630 set_parameters - set the parameters for the function(s), and
1631 set if they should be held fixed during fitting
1632 set_gauss_parameters - same as above but specialised for individual
1633 gaussian components
1634 get_parameters - get the fitted parameters
1635 plot - plot the resulting fit and/or components and
1636 residual
1637 [Plotter]
1638 asapplotter - a plotter for asap, default plotter is
1639 called 'plotter'
1640 plot - plot a (list of) scantable
1641 save - save the plot to a file ('png' ,'ps' or 'eps')
1642 set_mode - set the state of the plotter, i.e.
1643 what is to be plotted 'colour stacked'
1644 and what 'panelled'
1645 set_cursor - only plot a selected part of the data
1646 set_range - set a 'zoom' window
1647 set_legend - specify user labels for the legend indeces
1648 set_title - specify user labels for the panel indeces
1649 set_ordinate - specify a user label for the ordinate
1650 set_abcissa - specify a user label for the abcissa
1651 set_layout - specify the multi-panel layout (rows,cols)
1652
1653 [Reading files]
1654 reader - access rpfits/sdfits files
1655 read - read in integrations
1656 summary - list info about all integrations
1657
1658 [General]
1659 commands - this command
1660 print - print details about a variable
1661 list_scans - list all scantables created bt the user
1662 del - delete the given variable from memory
1663 range - create a list of values, e.g.
1664 range(3) = [0,1,2], range(2,5) = [2,3,4]
1665 help - print help for one of the listed functions
1666 execfile - execute an asap script, e.g. execfile('myscript')
1667 list_rcparameters - print out a list of possible values to be
1668 put into \$HOME/.asaprc
1669 mask_and,mask_or,
1670 mask_not - boolean operations on masks created with
1671 scantable.create_mask
1672
1673 Note:
1674 How to use this with help:
1675 # function 'summary'
1676 [xxx] is just a category
1677 Every 'sub-level' in this list should be replaces by a '.' Period when
1678 using help
1679 Example:
1680 ASAP> help scantable # to get info on ths scantable
1681 ASAP> help scantable.summary # to get help on the scantable's
1682 ASAP> help average_time
1683
1684\end{verbatim}
1685
1686\subsection{ASCII output format}
1687
1688\subsection{.asaprc settings}
1689\index{.asaprc}
1690\asaprc{verbose}{{\bf True}/False}{Print verbose output}
1691
1692\asaprc{insitu}{{\bf True}/False}{Apply operations on the input
1693scantable or return new one}
1694
1695% plotting
1696
1697\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
1698
1699\asaprc{plotter.gui}{{\bf True}/False}{Do we want a GUI or plot to a
1700file}
1701
1702\asaprc{plotter.stacking}{{\bf Pol} Beam IF Scan Time}{Default mode for
1703colour stacking}
1704
1705\asaprc{plotter.panelling}{Pol Beam IF {\bf Scan} Time}{Default mode
1706for panelling}
1707
1708\asaprc{plotter.ganged}{{\bf True}/False}{Push panels together, to
1709share axislabels}
1710
1711\asaprc{plotter.decimate}{True/{\bf False}}{Decimate the number of
1712points plotted by a factor of nchan/1024}
1713
1714% default colours/linestyles
1715%\asaprc{plotter.colours}{.}{.}
1716%\asaprc{plotter.linestyles{.}{.}
1717
1718% scantable
1719\asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
1720format when saving}
1721
1722\asaprc{scantable.autoaverage}{{\bf True}/False}{Auto averaging on
1723read}
1724
1725\asaprc{scantable.freqframe}{{\bf LSRK} TOPO BARY etc}{default
1726frequency frame to set when function scantable.set\_freqframe is
1727called}
1728
1729\asaprc{scantable.allaxes}{{\bf True}/False}{Apply action to all axes
1730not just the cursor location}
1731
1732\asaprc{scantable.plotter}{{\bf True}/False}{Use internal plotter}
1733
1734\asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level
1735of information printed by summary}
1736
1737\subsection{Installation}
1738
1739\index{Installation}ASAP depends on a number of third-party libraries which you must
1740have installed before attempting to build ASAP. These are:
1741
1742\begin{itemize}
1743\item AIPS++
1744\item Boost
1745\item Matplotlib
1746\item python/ipython
1747\end{itemize}
1748
1749Debian Linux is currently supported and we intend also
1750to support other popular Linux flavours, Solaris and Mac.
1751
1752Of the dependencies, AIPS++ is the most complex to install.
1753
1754\printindex
1755
1756\end{document}
1757
Note: See TracBrowser for help on using the repository browser.