source: trunk/doc/userguide.tex@ 1164

Last change on this file since 1164 was 1064, checked in by phi196, 18 years ago

Minor updates

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