source: trunk/doc/userguide.tex@ 1007

Last change on this file since 1007 was 971, checked in by mar637, 19 years ago

proof read chris' lat version. added some info.

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