source: branches/Release12/doc/cookbook.tex@ 769

Last change on this file since 769 was 767, checked in by phi196, 19 years ago

Small typos and Tid example

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