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

Last change on this file since 780 was 774, checked in by mar637, 19 years ago

added recalc_azel. fixed missing ()

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 56.7 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
789Note that currently the elevation is not written correctly into
790Tidbinbilla rpfits files. This means that gain-elevation and opacity
791corrections will not work unless these get recalculated.
792
793\begin{verbatim}
794 ASAP> scans.recalc_azel() # recalculate az/el based on pointing
795\end{verbatim}
796
797
798Gain-elevation curves for some telescopes and frequencies are known to
799ASAP (currently only for Tidbinbilla at 20~GHz). In these cases making
800gain-corrections is simple. If the gain curve for your data is not
801known, the user can supply either a gain polynomial or text file
802tabulating gain factors at a range of elevations (see \cmd{help
803scantable.gain\_el}).
804
805Examples:
806
807\begin{verbatim}
808 ASAP> scans.gain_el() # If gain table known
809 ASAP> scans.gain_el(poly=[3.58788e-1,2.87243e-2,-3.219093e-4])
810\end{verbatim}
811
812Opacity corrections can be made with the global function
813\cmd{opacity}. This should work on all telescopes as long as a
814measurement of the opacity factor was made during the observation.
815
816\begin{verbatim}
817 ASAP> scans.opacity(0.083)
818\end{verbatim}
819
820Note that at 3~mm Mopra uses a paddle wheel for Tsys calibration,
821which takes opacity effects into account (to first order). ASAP
822opacity corrections should not be used for Mopra 3-mm data.
823
824\subsection{Frequency Frame Alignment}
825
826When time averaging a series of scans together, it is possible that
827the velocity scales are not exactly aligned. This may be for many
828reasons such as not Doppler tracking the observations, errors in the
829Doppler tracking etc. This mostly affects very long integrations or
830integrations averaged together from different days. Before averaging
831such data together, they should be frequency aligned using
832\cmd{freq\_align}.
833
834E.g.:
835
836\begin{verbatim}
837 ASAP> scans.freq_align()
838 ASAP> av = average_time(scans)
839\end{verbatim}
840
841\cmd{freq\_align} has two modes of operations controlled by the
842\cmd{perif} argument. By default it will align each source and freqid
843separately. This is needed for scan tables containing multiple
844sources. However if scan-based Doppler tracking has been made at the
845observatory, each row will have a different freqid. In these cases run
846with \cmd{perif=True} and all rows of a source will be aligned to the
847same frame. In general \cmd{perif=True} will be needed for most
848observations as Doppler tracking of some form is made at Parkes, Tid
849and Mopra.
850
851\begin{verbatim}
852 ASAP> scans.freq_align(perif=True)
853\end{verbatim}
854
855To average together data taken on different days, which are in
856different scantables, each scantable must aligned to a common
857reference time then the scantables averaged. The simplest way of
858doing this is to allow ASAP to choose the reference time for the first
859scantable then using this time for the subsequent scantables.
860
861\begin{verbatim}
862 ASAP> scans1.freq_align() # Copy the refeference Epoch from the output
863 ASAP> scans2.freq_align(reftime='2004/11/23/18:43:35')
864 ASAP> scans3.freq_align(reftime='2004/11/23/18:43:35')
865 ASAP> av = average_time(scans1, scans2, scans3)
866\end{verbatim}
867
868\section{Scantable manipulation}
869
870While it is very useful to have many independent sources within one
871scantable, it is often inconvenient for data processing. The
872\cmd{get\_scan} function can be used to create a new scantable with a
873selection of scans from a scantable. The selection can either be on
874the source name, with simple wildcard matching or set of scan ids.
875
876For example:
877
878\begin{verbatim}
879 ASAP> ss = scans.get_scan(10) # Get the 11th scan (zero based)
880 ASAP> ss = scans.get_scan(range(10)) # Get the first 10 scans
881 ASAP> ss = scans.get_scan(range(10,20)) # Get the next 10 scans
882 ASAP> ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans
883
884 ASAP> ss = scans.get_scan('345p407') # Get a specific source
885 ASAP> ss = scans.get_scan('345*') # Get a few sources
886
887 ASAP> r = scans.get_scan('*_R') # Get all reference sources (Parkes/Mopra)
888 ASAP> s = scans.get_scan('*_S') # Get all program sources (Parkes/Mopra)
889 ASAP> r = scans.get_scan('*_[ew]') # Get all reference sources (Tid)
890 ASAP> s = scans.get_scan('*_[^ew]') # Get all program sources (Tid)
891
892\end{verbatim}
893
894To copy a scantable the following does not work:
895
896\begin{verbatim}
897 ASAP> ss = scans
898\end{verbatim}
899
900as this just creates a reference to the original scantable. Any
901changes made to \cmd{ss} are also seen in \cmd{scans}. To duplicate a
902scantable, use the copy function.
903
904\begin{verbatim}
905 ASAP> ss = scans.copy()
906\end{verbatim}
907
908\section{Data Output}
909
910ASAP can save scantables in a variety of formats, suitable for reading
911into other packages. The formats are:
912
913\begin{itemize}
914\item[ASAP] This is the internal format used for ASAP. It is the only
915 format that allows the user to restore the data, fits etc. without
916 loosing any information. As mentioned before, the ASAP scantable is
917 an AIPS++ Table (a memory-based table). This function just converts
918 it to a disk-based Table. You can the access that Table with the
919 AIPS++ Table browser or any other AIPS++ tool.
920
921\item[SDFITS] The Single Dish FITS format. This format was designed to
922 for interchange between packages, but few packages actually can read
923 it.
924
925\item[FITS] This uses simple ``image'' fits to save the data, each row
926 being written to a separate fits file. This format is suitable for
927 importing the data into CLASS.
928
929\item[ASCII] A simple text based format suitable for the user to
930processing using Perl or, Python, gnuplot etc.
931
932\item[MS2] Saves the data in an aips++ MeasurementSet V2 format.
933You can also access this with the Table browser and other AIPS++
934tools.
935
936\end{itemize}
937
938The default output format can be set in the users {\tt .asaprc} file.
939Typical usages are:
940
941\begin{verbatim}
942 ASAP> scans.save('myscans') # Save in default format
943 ASAP> scans.save('myscans', 'FITS') # Save as FITS for exporting into CLASS
944
945 ASAP> scans.save('myscans', stokes=True) # Convert raw polarisations into Stokes
946 ASAP> scans.save('myscans', overwrite=True) # Overwrite an existing file
947\end{verbatim}
948
949
950\section{Plotter}
951
952Scantable spectra can be plotted at any time. An asapplotter object is
953used for plotting, meaning multiple plot windows can be active at the
954same time. On start up a default asapplotter object is created called
955``plotter''. This would normally be used for standard plotting.
956
957The plotter, optionally, will run in a multipanel mode and contain
958multiple plots per panel. The user must tell the plotter how they want
959the data distributed. This is done using the set\_mode function. The
960default can be set in the users {\tt .asaprc} file. The units (and frame
961etc) of the abscissa will be whatever has previously been set by
962\cmd{set\_unit}, \cmd{set\_freqframe} etc.
963
964Typical plotter usage would be:
965
966\begin{verbatim}
967 ASAP> scans.set_unit('km/s')
968 ASAP> plotter.set_mode(stacking='p',panelling='t')
969 ASAP> plotter.plot(scans)
970\end{verbatim}
971
972This will plot multiple polarisation within each plot panel and each
973scan row in a separate panel.
974
975Other possibilities include:
976
977\begin{verbatim}
978 # Plot multiple IFs per panel
979 ASAP> plotter.set_mode(stacking='i',panelling='t')
980
981 # Plot multiple beams per panel
982 ASAP> plotter.set_mode(stacking='b',panelling='t')
983
984 # Plot one IF per panel, time stacked
985 ASAP> plotter.set_mode('t', 'i')
986
987 # Plot each scan in a seperate panel
988 ASAP> plotter.set_mode('t', 's')
989
990\end{verbatim}
991
992\subsection{Plot Selection}
993\label{sec:plotter_cursor}
994
995The plotter can plot up to 25 panels and stacked spectra per
996panel. If you have data larger than this (or for your own sanity) you
997need to select a subset of this data. This is particularly true for
998multibeam or multi IF data. The plotter \cmd{set\_cursor} function is
999used to select a subset of the data. The arguments \cmd{row},
1000\cmd{beam} and \cmd{IF} all accept a vector of indices corresponding
1001to row, beam or IF selection. Only the selected data will be plotted.
1002To select on polarisation, see section~\ref{sec:polplot}.
1003
1004Examples:
1005
1006\begin{verbatim}
1007 # Select second IF
1008 ASAP> plotter.set_cursor(IF=[1])
1009
1010 # Select first 4 beams
1011 ASAP> plotter.set_cursor(beam=[0,1,2,3])
1012
1013 # Select a few rows
1014 ASAP> plotter.set_cursor(row=[2,4,6,10])
1015
1016 # Multiple selection
1017 ASAP> plotter.set_cursor(IF=[1], beam=[0,2], row=range(10))
1018\end{verbatim}
1019
1020Note that the plotter cursor selection is independent of the scantable
1021cursor.
1022
1023\subsection{Plot Control}
1024
1025The plotter window has a row of buttons on the lower left. These can
1026be used to control the plotter (mostly for zooming the individual
1027plots). From left to right:
1028
1029\begin{itemize}
1030
1031\item[Home] This will unzoom the plots to the original zoom factor
1032
1033\item[Plot history] (left and right arrow). The plotter keeps a
1034history of zoom settings. The left arrow sets the plot zoom to the
1035previous value. The right arrow returns back again. This allows you,
1036for example, to zoom in on one feature then return the plot to how it
1037was previously.
1038
1039\item[Pan] (The Cross) This sets the cursor to pan, or scroll mode
1040 allowing you to shift the plot within the window. Useful when
1041 zoomed in on a feature.
1042
1043\item[Zoom] (the letter with the magnifying glass) lets you draw a
1044 rectangle around a region of interest then zooms in on that
1045 region. Use the plot history to unzoom again.
1046
1047\item[Save] (floppy disk). Save the plot as a postscript or .png file
1048
1049\end{itemize}
1050
1051\subsection{Other control}
1052
1053The plotter has a number of functions to describe the layout of the
1054plot. These include \cmd{set\_legend}, \cmd{set\_layout} and \cmd{set\_title}.
1055
1056To set the exact velocity or channel range to be plotted use the
1057\cmd{set\_range} function. To reset to the default value, call
1058\cmd{set\_range} with no arguments. E.g.
1059
1060\begin{verbatim}
1061 ASAP> scans.set_unit('km/s')
1062 ASAP> plotter.plot(scans)
1063 ASAP> plotter.set_range(-150,-50)
1064 ASAP> plotter.set_range() # To reset
1065\end{verbatim}
1066
1067Both the range of the ``x'' and ``y'' axis can be set at once, if desired:
1068
1069\begin{verbatim}
1070 ASAP> plotter.set_range(-10,30,-1,6.6)
1071\end{verbatim}
1072
1073To save a hardcopy of the current plot, use the save function, e.g.
1074
1075\begin{verbatim}
1076 ASAP> plotter.save('myplot.ps')
1077\end{verbatim}
1078
1079\section{Fitting}
1080
1081Currently multicomponent Gaussian function is available. This is done
1082by creating a fitting object, setting up the fit and actually fitting
1083the data. Fitting can either be done on a single scantable row/cursor
1084selection or on an entire scantable using the \cmd{auto\_fit} function.
1085
1086\begin{verbatim}
1087 ASAP> f = fitter()
1088 ASAP> f.set_function(gauss=2) # Fit two Gaussians
1089 ASAP> f.set_scan(scans)
1090 ASAP> scans.set_cursor(0,0,1) # Fit the second polarisation
1091 ASAP> scans.set_unit('km/s') # Make fit in velocity units
1092 ASAP> f.fit(1) # Run the fit on the second row in the table
1093 ASAP> f.plot() # Show fit in a plot window
1094 ASAP> f.get_parameters() # Return the fit paramaters
1095\end{verbatim}
1096
1097This auto-guesses the initial values of the fit and works well for data
1098without extra confusing features. Note that the fit is performed in
1099whatever unit the abscissa is set to.
1100
1101If you want to confine the fitting to a smaller range (e.g. to avoid
1102band edge effects or RFI you must set a mask.
1103
1104\begin{verbatim}
1105 ASAP> f = fitter()
1106 ASAP> f.set_function(gauss=2)
1107 ASAP> scans.set_unit('km/s') # Set the mask in channel units
1108 ASAP> msk = s.create_mask([1800,2200])
1109 ASAP> scans.set_unit('km/s') # Make fit in velocity units
1110 ASAP> f.set_scan(s,msk)
1111 ASAP> f.fit()
1112 ASAP> f.plot()
1113 ASAP> f.get_parameters()
1114\end{verbatim}
1115
1116If you wish, the initial parameter guesses can be specified and
1117specific parameters can be fixed:
1118
1119\begin{verbatim}
1120 ASAP> f = fitter()
1121 ASAP> f.set_function(gauss=2)
1122 ASAP> f.set_scan(s,msk)
1123 ASAP> f.fit() # Fit using auto-estimates
1124 # Set Peak, centre and fwhm for the second gaussian.
1125 # Force the centre to be fixed
1126 ASAP> f.set_gauss_parameters(0.4,450,150,0,1,0,component=1)
1127 ASAP> f.fit() # Re-run the fit
1128\end{verbatim}
1129
1130The fitter \cmd{plot} function has a number of options to either view
1131the fit residuals or the individual components (by default it plots
1132the sum of the model components).
1133
1134Examples:
1135
1136\begin{verbatim}
1137 # Plot the residual
1138 ASAP> f.plot(residual=True)
1139
1140 # Plot the first 2 componentsa
1141 ASAP> f.plot(components=[0,1])
1142
1143 # Plot the first and third component plus the model sum
1144 ASAP> f.plot(components=[-1,0,2]) # -1 means the compoment sum
1145\end{verbatim}
1146
1147\subsection{Fit saving}
1148
1149One you are happy with your fit, it is possible to store it as part of
1150the scantable.
1151
1152\begin{verbatim}
1153 ASAP> f.storefit()
1154\end{verbatim}
1155
1156This will be saved to disk with the data, if the ``ASAP'' file format
1157is selected. Multiple fits to the same data can be stored in the
1158scantable.
1159
1160The scantable function \cmd{get\_fit} can be used to retrieve the
1161stored fits. Currently the fit parameters are just printed to the
1162screen.
1163
1164\begin{verbatim}
1165 ASAP> scans.get_fit(4) # Print fits for row 4
1166\end{verbatim}
1167
1168\section{Polarisation}
1169
1170Currently ASAP only supports polarmetric analysis on linearly
1171polarised feeds and the cross polarisation products measured. Other
1172cases will be added on an as needed basic.
1173
1174Conversions of linears to Stokes or Circular polarisations are done
1175``on-the-fly''. Leakage cannot be corrected for nor are these routines
1176able to calibrate position angle offsets.
1177
1178\subsection{Simple Calibration}
1179
1180{\em Currently the receiver position angle is not read from the RPFITS
1181file and a position angle of zero is assumed. This severely hampers
1182correct handling of polarimetry. In the future we aim to define a
1183general framework and populate the RPFITS files with the data required
1184for transparent polarimetric calibration.}
1185
1186It is possible that there is a phase offset between polarisation which
1187will effect the phase of the cross polarisation correlation, and so give
1188rise to spurious polarisation. \cmd{rotate\_xyphase} can be used to
1189correct for this error. At this point, the user must know how to
1190determine the size of the phase offset themselves.
1191
1192\begin{verbatim}
1193 ASAP> scans.rotate_xyphase(10.5) # Degrees
1194\end{verbatim}
1195
1196Note that if this function is run twice, the sum of the two values is
1197applied because it is done in-situ.
1198
1199A correction for the receiver parallactic angle may need to be made,
1200either because of how it is mounted or if parallactifiying had to track
1201at 90 degrees rather than 0. Use \cmd{rotate\_linpolphase} to correct
1202the position angle. Running this function twice results in the sum of
1203the corrections being applied because it is applied in-situ.
1204
1205\begin{verbatim}
1206 ASAP> scans.rotate_linpolphase(-20) # Degrees; correct for receiver mounting
1207
1208 # Receiver was tracking 90 degrees rather than 0
1209 ASAP> scans.rotate_linpolphase(90)
1210\end{verbatim}
1211
1212\subsection{Plotting}
1213\label{sec:polplot}
1214
1215To plot Stokes values, the plotter \cmd{set\_cursor} function should
1216be called first using the \cmd{pol} argument. The values which can be
1217plotted include a selection of [I,Q,U,V], [I, Plinear, Pangle, V],
1218[RR, LL] or [XX, YY, Real(XY), Imaginary(XY)]. (Plinear and Pangle are
1219the percentage and position angle of linear polarisation). Conversion
1220to circular polarisations are currently not available.
1221
1222Example:
1223
1224\begin{verbatim}
1225 ASAP> plotter.set_cursor(pol=``I Q'')
1226 ASAP> plotter.set_cursor(pol=``RR LL'')
1227 ASAP> plotter.set_cursor(pol=``XX YY'')
1228 ASAP> plotter.set_cursor(pol=``I Plinear'')
1229\end{verbatim}
1230
1231Row, beam and IF selection are also available in \cmd{set\_cursor} as
1232describe in section~\ref{sec:plotter_cursor}.
1233
1234\subsection{Saving}
1235
1236When saving data using the \cmd{save} function, the \cmd{stokes}
1237argument can be used to save the data as Stoke values when saving in
1238FITS format.
1239
1240Example:
1241
1242\begin{verbatim}
1243 ASAP> scans.save('myscan.sdfits', 'SDFITS', stokes=True)
1244\end{verbatim}
1245
1246
1247\section{Scantable Mathematics}
1248
1249It is possible to to simple mathematics directly on scantables from
1250the command line using the \cmd{+, -, *, /} operators as well as their
1251cousins \cmd{+=, -= *=, /=}. This works between two scantables or a
1252scantable and a float. (Note that it does not work for integers).
1253
1254\begin{verbatim}
1255 ASAP> sum = scan1+scan2
1256 ASAP> scan2 = scan1+2.0
1257 ASAP> scan *= 1.05
1258\end{verbatim}
1259
1260\section{Scripting}
1261
1262Because asap is based on python, it easy for the user write their own
1263scripts and functions to process data. This is highly recommended as
1264most processing of user data could then be done in a couple of steps
1265using a few simple user defined functions. A Python primer is beyond
1266the scope of this userguide. See the asap home pages for a scripting
1267tutorial or the main python website for comprehensive documentation.
1268
1269\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
1270\hspace{1cm} http://www.python.org/doc/Introduction.html
1271
1272\subsection{Running scripts}
1273
1274The asap global function \cmd{execfile} reads the named text file and
1275executes the contained python code. This file can either contain
1276function definitions which will be used in subsequent processing or
1277just a set of commands to process a specific dataset.
1278
1279\subsection{asapuserfuncs.py}
1280
1281The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
1282asap is started. The user can use this to define a set of user
1283functions which are automatically available each time asap is
1284used. The \cmd{execfile} function can be called from within this file.
1285
1286\section{Worked examples}
1287
1288In the following section a few examples of end-to-end processing of
1289some data in asap are given.
1290
1291\subsection{Mopra}
1292
1293\subsection{Parkes Polarimetry}
1294
1295The following example is processing of some Parkes polarmetric
1296observations of OH masers at 1.6~GHz. Because digital filters where
1297used in the backend, the baselines are stable enough not to require a
1298quotient spectra. The 4~MHz bandwidth is wide enough to observe both
1299the 1665 and 1667~MHz OH maser transitions. Each source was observed
1300once for about 10 minutes. Tsys information was not written to the
1301rpfits file (a nominal 25K values was used), so the amplitudes need
1302to be adjusted based on a separate log file. A simple user function is
1303used to simplify this, contained in a file called mypol.py:
1304
1305\begin{verbatim}
1306def xyscale(data,xtsys=1.0,ytsys=1.0,nomtsys=25.0) :
1307
1308 data.set_cursor(pol=0)
1309 data.scale(xtsys/nomtsys,allaxes=False)
1310
1311 data.set_cursor(pol=1)
1312 data.scale(ytsys/nomtsys,allaxes=False)
1313
1314 data.set_cursor(pol=2)
1315 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
1316
1317 data.set_cursor(pol=3)
1318 data.scale((xtsys+ytsys)/(2*nomtsys),allaxes=False)
1319\end{verbatim}
1320
1321The typical asap session would be
1322
1323\begin{verbatim}
1324
1325# Remind ourself the name of the rpfits files
1326ls
1327
1328# Load data from an rpfits file
1329d1665 = scantable('2005-10-27_0154-P484.rpf')
1330
1331# Check what we have just loaded
1332d1665.summary
1333
1334# View the data in velocity
1335d1665.set_unit('km/s')
1336d1665.set_freqframe('LSRK')
1337
1338# Correct for the known phase offset in the crosspol data
1339d1665.rotate_xyphase(-4)
1340
1341# Create a copy of the data and set the rest frequency to the 1667 MHz
1342# transition
1343d1667 = d1665.copy()
1344d1667.set_restfreqs(lines=['OH1667'])
1345d1667.summary
1346
1347# Copy out the scan we wish to process
1348g351_5 = d1665.get_scan('351p160')
1349g351_7 = d1667.get_scan('351p160')
1350
1351# Plot the data
1352plotter.plot(g351_5,g351_7) # Only shows one panel
1353
1354# Tell the plotter to stack polarisation and panel scans
1355plotter.set_mode('p','s')
1356
1357# Correct for the Tsys using our predefined function
1358execfile('mypol.py') # Read in the function
1359xyscale(g351_5,23.2,22.7) # Execute it on the data
1360xyscale(g351_7,23.2,22.7)
1361
1362# Only plot the velocity range of interest
1363plotter.set_range(-30,10)
1364
1365# Baseline the data
1366msk = g351_5.create_mask([-20,-15],[0,5])
1367g351_5.poly_baseline(msk,1)
1368msk = g351_7.create_mask([-20,-15],[0,5])
1369g351_7.poly_baseline(msk,1)
1370
1371# Update the plot with the baselined data
1372plotter.plot()
1373
1374# Look at the various polarisation products
1375plotter.set_cursor(pol='RR LL')
1376plotter.set_cursor(pol='I Plinear')
1377plotter.set_cursor(pol='I Q U V')
1378
1379# Save the plot as postscript
1380plotter.save('g361_stokes.ps')
1381
1382# Save the process spectra
1383g351_5.save('junk5.asap')
1384g351_7.save('junk7.asap')
1385
1386\end{verbatim}
1387
1388\subsection{Tidbinbilla}
1389
1390The following example is processing of some Tidbinbilla observations
1391of NH$_3$ at 12~mm. Tidbinbilla has (at the time of observations) a
1392single polarisation, but can process two IFs simultaneously. In the
1393example, the first half of the observation was observing the (1,1) and
1394(2,2) transitions simultaneously). The second half observed only the
1395(4,4) transition due to bandwidth limitations. The data is position
1396switched, observing first an reference to the west, then the source
1397twice and finally reference to the east.
1398
1399\begin{verbatim}
1400
1401# Load the rpfits file and inspect
1402d = scantable('2003-03-16_082048_t0002.rpf')
1403print d
1404
1405# Make the quotient spectra
1406q = d.auto_quotient()
1407print q
1408
1409# Plot/select in velocity
1410q.set_freqframe('LSRK')
1411q.set_unit('km/s')
1412
1413# Seperate data from the (1,1)&(2,2) and (4,4) transitions
1414g1 = q.get_scan(range(6)) # Rows 0..5
1415g2 = q.get_scan(range(6,12)) # Rows 6..11
1416
1417# Align data in velocity
1418g1.freq_align(perif=True)
1419g2.freq_align(perif=True)
1420
1421# Average individual scans
1422a1 = g1.average_time()
1423a2 = g2.average_time()
1424
1425# Rpfits file only contrains a single rest frequency. Set both
1426a1.set_restfreqs(freqs= [23694.4700e6,23722.6336e6])
1427
1428plotter.plot(a1,a2)
1429plotter.set_mode('i','s')
1430x = raw_input()
1431
1432a1.auto_poly_baseline()
1433a2.auto_poly_baseline()
1434
1435plotter.plot()
1436
1437a1.smooth('gauss',5)
1438a2.smooth('gauss',5)
1439plotter.plot()
1440
1441\end{verbatim}
1442
1443\newpage
1444
1445\section{Appendix}
1446
1447\subsection{Function Summary}
1448
1449\begin{verbatim}
1450 [The scan container]
1451 scantable - a container for integrations/scans
1452 (can open asap/rpfits/sdfits and ms files)
1453 copy - returns a copy of a scan
1454 get_scan - gets a specific scan out of a scantable
1455 summary - print info about the scantable contents
1456 set_cursor - set a specific Beam/IF/Pol 'cursor' for
1457 further use
1458 get_cursor - print out the current cursor position
1459 stats - get specified statistic of the spectra in
1460 the scantable
1461 stddev - get the standard deviation of the spectra
1462 in the scantable
1463 get_tsys - get the TSys
1464 get_time - get the timestamps of the integrations
1465 get_unit - get the currnt unit
1466 set_unit - set the abcissa unit to be used from this
1467 point on
1468 get_abcissa - get the abcissa values and name for a given
1469 row (time)
1470 set_freqframe - set the frame info for the Spectral Axis
1471 (e.g. 'LSRK')
1472 set_doppler - set the doppler to be used from this point on
1473 set_instrument - set the instrument name
1474 get_fluxunit - get the brightness flux unit
1475 set_fluxunit - set the brightness flux unit
1476 create_mask - return an mask in the current unit
1477 for the given region. The specified regions
1478 are NOT masked
1479 get_restfreqs - get the current list of rest frequencies
1480 set_restfreqs - set a list of rest frequencies
1481 lines - print list of known spectral lines
1482 flag_spectrum - flag a whole Beam/IF/Pol
1483 save - save the scantable to disk as either 'ASAP'
1484 or 'SDFITS'
1485 nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
1486 history - print the history of the scantable
1487 get_fit - get a fit which has been stored witnh the data
1488 average_time - return the (weighted) time average of a scan
1489 or a list of scans
1490 average_pol - average the polarisations together.
1491 The dimension won't be reduced and
1492 all polarisations will contain the
1493 averaged spectrum.
1494 auto_quotient - return the on/off quotient with
1495 automatic detection of the on/off scans
1496 quotient - return the on/off quotient
1497 scale - return a scan scaled by a given factor
1498 add - return a scan with given value added
1499 bin - return a scan with binned channels
1500 resample - return a scan with resampled channels
1501 smooth - return the spectrally smoothed scan
1502 poly_baseline - fit a polynomial baseline to all Beams/IFs/Pols
1503 auto_poly_baseline - automatically fit a polynomial baseline
1504 recalc_azel - recalculate azimuth and elevation based on
1505 the pointing
1506 gain_el - apply gain-elevation correction
1507 opacity - apply opacity correction
1508 convert_flux - convert to and from Jy and Kelvin brightness
1509 units
1510 freq_align - align spectra in frequency frame
1511 rotate_xyphase - rotate XY phase of cross correlation
1512 rotate_linpolphase - rotate the phase of the complex
1513 polarization O=Q+iU correlation
1514 [Math] Mainly functions which operate on more than one scantable
1515
1516 average_time - return the (weighted) time average
1517 of a list of scans
1518 quotient - return the on/off quotient
1519 simple_math - simple mathematical operations on two scantables,
1520 'add', 'sub', 'mul', 'div'
1521 [Fitting]
1522 fitter
1523 auto_fit - return a scan where the function is
1524 applied to all Beams/IFs/Pols.
1525 commit - return a new scan where the fits have been
1526 commited.
1527 fit - execute the actual fitting process
1528 store_fit - store the fit paramaters in the data (scantable)
1529 get_chi2 - get the Chi^2
1530 set_scan - set the scantable to be fit
1531 set_function - set the fitting function
1532 set_parameters - set the parameters for the function(s), and
1533 set if they should be held fixed during fitting
1534 set_gauss_parameters - same as above but specialised for individual
1535 gaussian components
1536 get_parameters - get the fitted parameters
1537 plot - plot the resulting fit and/or components and
1538 residual
1539 [Plotter]
1540 asapplotter - a plotter for asap, default plotter is
1541 called 'plotter'
1542 plot - plot a (list of) scantable
1543 save - save the plot to a file ('png' ,'ps' or 'eps')
1544 set_mode - set the state of the plotter, i.e.
1545 what is to be plotted 'colour stacked'
1546 and what 'panelled'
1547 set_cursor - only plot a selected part of the data
1548 set_range - set a 'zoom' window
1549 set_legend - specify user labels for the legend indeces
1550 set_title - specify user labels for the panel indeces
1551 set_ordinate - specify a user label for the ordinate
1552 set_abcissa - specify a user label for the abcissa
1553 set_layout - specify the multi-panel layout (rows,cols)
1554
1555 [Reading files]
1556 reader - access rpfits/sdfits files
1557 read - read in integrations
1558 summary - list info about all integrations
1559
1560 [General]
1561 commands - this command
1562 print - print details about a variable
1563 list_scans - list all scantables created bt the user
1564 del - delete the given variable from memory
1565 range - create a list of values, e.g.
1566 range(3) = [0,1,2], range(2,5) = [2,3,4]
1567 help - print help for one of the listed functions
1568 execfile - execute an asap script, e.g. execfile('myscript')
1569 list_rcparameters - print out a list of possible values to be
1570 put into \$HOME/.asaprc
1571 mask_and,mask_or,
1572 mask_not - boolean operations on masks created with
1573 scantable.create_mask
1574
1575 Note:
1576 How to use this with help:
1577 # function 'summary'
1578 [xxx] is just a category
1579 Every 'sub-level' in this list should be replaces by a '.' Period when
1580 using help
1581 Example:
1582 ASAP> help scantable # to get info on ths scantable
1583 ASAP> help scantable.summary # to get help on the scantable's
1584 ASAP> help average_time
1585
1586\end{verbatim}
1587
1588\subsection{Installation}
1589
1590ASAP depends on a number of third-party libraries which you must
1591have installed before attempting to build ASAP. These are:
1592
1593\begin{itemize}
1594\item AIPS++
1595\item Boost
1596\item Matplotlib
1597\item python/ipython
1598\end{itemize}
1599
1600Debian Linux is currently supported and we intend also
1601to support other popular Linux flavours, Solaris and Mac.
1602
1603Of the dependencies, AIPS++ is the most complex to install.
1604
1605\subsection{ASCII output format}
1606
1607\subsection{.asaprc settings}
1608
1609\asaprc{verbose}{{\bf True}/False}{Print verbose output}
1610
1611\asaprc{insitu}{{\bf True}/False}{Apply operations on the input
1612scantable or return new one}
1613
1614% plotting
1615
1616\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
1617
1618\asaprc{plotter.gui}{{\bf True}/False}{Do we want a GUI or plot to a
1619file}
1620
1621\asaprc{plotter.stacking}{{\bf Pol} Beam IF Scan Time}{Default mode for
1622colour stacking}
1623
1624\asaprc{plotter.panelling}{Pol Beam IF {\bf Scan} Time}{Default mode
1625for panelling}
1626
1627\asaprc{plotter.ganged}{{\bf True}/False}{Push panels together, to
1628share axislabels}
1629
1630\asaprc{plotter.decimate}{True/{\bf False}}{Decimate the number of
1631points plotted by a factor of nchan/1024}
1632
1633% default colours/linestyles
1634%\asaprc{plotter.colours}{.}{.}
1635%\asaprc{plotter.linestyles{.}{.}
1636
1637% scantable
1638\asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
1639format when saving}
1640
1641\asaprc{scantable.autoaverage}{{\bf True}/False}{Auto averaging on
1642read}
1643
1644\asaprc{scantable.freqframe}{{\bf LSRK} TOPO BARY etc}{default
1645frequency frame to set when function scantable.set\_freqframe is
1646called}
1647
1648\asaprc{scantable.allaxes}{{\bf True}/False}{Apply action to all axes
1649not just the cursor location}
1650
1651\asaprc{scantable.plotter}{{\bf True}/False}{Use internal plotter}
1652
1653\asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level
1654of information printed by summary}
1655
1656\end{document}
1657
Note: See TracBrowser for help on using the repository browser.