source: trunk/doc/userguide.tex@ 1027

Last change on this file since 1027 was 1011, checked in by mar637, 19 years ago

some more updates for asap2 - Ticket #9

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 63.4 KB
Line 
1\documentclass[11pt]{article}
2\usepackage{a4}
3\usepackage{calc}
4\usepackage[dvips]{graphicx}
5\usepackage{makeidx}
6
7% Adjust the page size
8\addtolength{\oddsidemargin}{-0.4in}
9\addtolength{\evensidemargin}{+0.4in}
10\addtolength{\textwidth}{+0.8in}
11
12\setlength{\parindent}{0mm}
13\setlength{\parskip}{1ex}
14
15\title{ATNF Spectral Analysis Package\\User Guide v2.0beta }
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 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
269The building block of a scantable is an integration, which is a single
270row of a scantable. Each row contains just one spectrum for each beam, IF and
271polarisation. For example Parkes multibeam data would contain many
272beams, one IF and 2-4 polarisations, while the new Mopra 8-GHz
273filterbank will eventually produce one beam, many IFs, and 2-4
274polarisations. All of the combinations of Beams/IFs an Polarisations are
275contained in seperate rows. These rows are grouped in cycles (same time stamp).
276
277A collection of cycles for one source is termed
278a scan (and each scan has a unique numeric identifier, the SCANNO). A
279scantable is then a collection of one or more scans. If you have
280scan-averaged your data in time, i.e. you have averegaed all cycles within
281a scan, then each scan would hold just one (averaged) integration.
282
283Many of the functions which work on scantables can either return a
284new scantable with modified data or change the scantable insitu. Which
285method is used depends on the users preference. The default can be
286changed via the {\tt .asaprc} resource file.
287
288For example a Mopra scan with a 4s intergration time, two IFs and
289dual polarisations has two (2s) cycles.
290
291\begin{verbatim}
292SCANNO CYCLENO BEAMNO IFNO POLNO
2930 0 0 0 0
2940 0 0 0 1
2950 0 0 1 0
2960 0 0 1 1
2970 1 0 0 0
2980 1 0 0 1
2990 1 0 1 0
3000 1 0 1 1
301
302\end{verbatim}
303
304
305\subsubsection {Contents}
306
307\index{Scantable!contents}A scantable has header information and data
308(a scantable is actually an AIPS++ Table and it is generally stored in
309memory when you are manipulating it with ASAP. You can save it to
310disk and then browse it with the AIPS++ Table browser if you know how
311to do that !).
312
313The data are stored in columns (the length of a column is the number of
314rows/spectra of course).
315
316
317Two important columns are those that describe the frequency setup. We mention
318them explicitly here because you need to be able to understand the presentation
319of the frequency information and possibly how to manipulate it.
320
321These columns are called FREQ\_ID and MOLECULE\_ID. They contain indices, for
322each IF, pointing into tables with all of the frequency and rest-frequency
323information for that integration. More on these below when we discuss
324the \cmd{summary} function in the next subsection.
325
326There are of course many other columns which contain the actual spectra,
327the flags, the Tsys, the source names and so on.
328
329There is also a function \cmd{summary} to list a summary of the scantable.
330You will find this very useful.
331
332Example:
333
334\begin{verbatim}
335 ASAP> scans = scantable('MyData.rpf')
336 ASAP> scans.summary() # Brief listing
337
338 # Equivalent to brief summary function call
339 ASAP> print scan
340\end{verbatim}
341
342The summary function gives you a scan-based summary, presenting the
343scantable as a cascading view od Beams and IFs.
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 but 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 this 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 cursor setting, selected row and selected
505frequency reference 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}
1288Data can be converted between linear and circular polarisations and stokes.
1289
1290\begin{verbatim}
1291 ASAP> stokescans = linearscans.convert_pol("stokes")
1292\end{verbatim}
1293
1294
1295\subsection{Plotting}
1296\label{sec:polplot}
1297
1298\index{Polarisation!plotting}To plot Stokes values, a selector object
1299must be created and the set\_polarisation function used to select the
1300desired polarisation products.
1301
1302The values which can be plotted include a selection of [I,Q,U,V], [I,
1303Plinear, Pangle, V], [RR, LL] or [XX, YY, Real(XY),
1304Imaginary(XY)]. (Plinear and Pangle are the percentage and position
1305angle of linear polarisation).
1306
1307Example:
1308
1309\begin{verbatim}
1310 ASAP> selection = selector()
1311
1312 ASAP> selection.set_polarisations(``I Q U V'')
1313 ASAP plotter.set_selection(selection); # Select I, Q, U \& V
1314
1315 ASAP> selection.set_polarisations(``I Q'')
1316 ASAP plotter.set_selection(selection); # Select just I \& Q
1317
1318 ASAP> selection.set_polarisations(``RR LL'')
1319 ASAP plotter.set_selection(selection); # Select just RR \& LL
1320
1321 ASAP> selection.set_polarisations(``XX YY'')
1322 ASAP plotter.set_selection(selection); # Select linears
1323
1324 ASAP> selection.set_polarisations(``I Plinear'')
1325 ASAP plotter.set_selection(selection); # Fractional linear
1326
1327 ASAP> selection.set_polarisations(``Pangle'')
1328 ASAP plotter.set_selection(selection); # Position angle
1329
1330\end{verbatim}
1331
1332Scan, beam and IF selection are also available in the selector object as
1333describe in section~\ref{sec:selection}.
1334
1335\subsection{Saving}
1336
1337\index{Polarisation!saving}When saving data using the \cmd{save}
1338function, the \cmd{stokes} argument can be used to save the data as
1339Stoke values when saving in FITS format.
1340
1341Example:
1342
1343\begin{verbatim}
1344 ASAP> scans.save('myscan.sdfits', 'SDFITS', stokes=True)
1345\end{verbatim}
1346
1347\section{Scantable Mathematics}
1348
1349\index{Scantable!maths}It is possible to to simple mathematics
1350directly on scantables from the command line using the \cmd{+, -, *,
1351/} operators as well as their cousins \cmd{+=, -= *=, /=}. This works
1352between a scantable and a float. (Note that it does
1353not work for integers).
1354
1355{\em Currently mathematics between two scantables is not available }
1356
1357% ASAP> sum = scan1+scan2
1358\begin{verbatim}
1359 ASAP> scan2 = scan1+2.0
1360 ASAP> scan *= 1.05
1361\end{verbatim}
1362
1363\section{Scripting}
1364
1365\index{Scripting}Because asap is based on python, it easy for the user
1366write their own scripts and functions to process data. This is highly
1367recommended as most processing of user data could then be done in a
1368couple of steps using a few simple user defined functions. A Python
1369primer is beyond the scope of this userguide. See the asap home pages
1370for a scripting tutorial or the main python website for comprehensive
1371documentation.
1372
1373\hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
1374
1375\hspace{1cm} http://www.python.org/doc/Introduction.html
1376
1377\subsection{Running scripts}
1378
1379The asap global function \cmd{execfile} reads the named text file and
1380executes the contained python code. This file can either contain
1381function definitions which will be used in subsequent processing or
1382just a set of commands to process a specific dataset.
1383
1384\subsection{asapuserfuncs.py}
1385
1386The file $\sim$/.asap/asapuserfuncs.py is automatically read in when
1387asap is started. The user can use this to define a set of user
1388functions which are automatically available each time asap is
1389used. The \cmd{execfile} function can be called from within this file.
1390
1391\section{Worked examples}
1392
1393In the following section a few examples of end-to-end processing of
1394some data in asap are given.
1395
1396\subsection{Mopra}
1397\index{Mopra}
1398
1399The following example is of some dual polarisation, position switched
1400data from Mopra. The source has been observed mulitple times split
1401into a number of seperate rpfits files. To make the processing easier,
1402the first step is to \cmd{cat} the seeprate rpfits files together and
1403load as a whole (future versions of asap will make this unnecessary).
1404
1405
1406\begin{verbatim}
1407# get a list of the individual rpfits files in the current directory
1408myfiles = list_files()
1409
1410# Load the data into a scantable
1411data = scantable(myfiles)
1412print data
1413
1414# Form the quotient spectra
1415q = data.auto_quotient()
1416print q
1417
1418# Look at the spectra
1419plotter.plot(q)
1420
1421# Set unit and reference frame
1422q.set_unit('km/s')
1423q.set_freqframe('LSRK')
1424
1425# Average all scans in time, aligning in velocity
1426av = q.average_time(align=True)
1427plotter.plot(av)
1428
1429# Remove the baseline
1430msk = av.create_mask([100,130],[160,200])
1431av.poly_baseline(msk,2)
1432
1433# Average the two polarisations together
1434iav = av.average_pol()
1435print iav
1436plotter.plot(iav)
1437
1438# Set a sensible velocity range on the plot
1439plotter.set_range(85,200)
1440
1441# Smooth the data a little
1442av.smooth('gauss',4)
1443plotter.plot()
1444
1445# Fit a guassian to the emission
1446f = fitter()
1447f.set_function(gauss=1)
1448f.set_scan(av)
1449f.fit()
1450
1451# View the fit
1452f.plot()
1453
1454# Get the fit parameters
1455f.get_parameters()
1456
1457\end{verbatim}
1458
1459
1460\subsection{Parkes Polarimetry}
1461
1462\index{Parkes}\index{Polarisation}The following example is processing
1463of some Parkes polarmetric observations of OH masers at
14641.6~GHz. Because digital filters where used in the backend, the
1465baselines are stable enough not to require a quotient spectra. The
14664~MHz bandwidth is wide enough to observe both the 1665 and 1667~MHz
1467OH maser transitions. Each source was observed once for about 10
1468minutes. Tsys information was not written to the rpfits file (a
1469nominal 25K values was used), so the amplitudes need to be adjusted
1470based on a separate log file. A simple user function is used to
1471simplify this, contained in a file called mypol.py:
1472
1473\begin{verbatim}
1474def xyscale(data,xtsys=1.0,ytsys=1.0,nomtsys=25.0) :
1475
1476 selection = selector()
1477 selection.set_polarisations(0)
1478 data.set_selection(selection)
1479 data.scale(xtsys/nomtsys)
1480
1481 selection.set_polarisations(1)
1482 data.set_selection(selection)
1483 data.scale(ytsys/nomtsys)
1484
1485 selection.set_polarisations(0)
1486 data.set_selection(selection)
1487 data.scale((xtsys+ytsys)/(2*nomtsys))
1488
1489 selection.set_polarisations(0)
1490 data.set_selection(selection)
1491 data.scale((xtsys+ytsys)/(2*nomtsys))
1492\end{verbatim}
1493
1494The typical asap session would be
1495
1496\begin{verbatim}
1497
1498# Remind ourself the name of the rpfits files
1499ls
1500
1501# Load data from an rpfits file
1502d1665 = scantable('2005-10-27_0154-P484.rpf')
1503
1504# Check what we have just loaded
1505d1665.summary()
1506
1507# View the data in velocity
1508d1665.set_unit('km/s')
1509d1665.set_freqframe('LSRK')
1510
1511# Correct for the known phase offset in the crosspol data
1512d1665.rotate_xyphase(-4)
1513
1514# Create a copy of the data and set the rest frequency to the 1667 MHz
1515# transition
1516d1667 = d1665.copy()
1517d1667.set_restfreqs([1667.3590], 'MHz')
1518d1667.summary()
1519
1520# Copy out the scan we wish to process
1521g351_5 = d1665.get_scan('351p160')
1522g351_7 = d1667.get_scan('351p160')
1523
1524# Baseline both
1525msk = g351_5.create_mask([-30,-25],[-5,0])
1526g351_5.poly_baseline(msk,order=1)
1527msk = g351_7.create_mask([-30,-25],[-5,0])
1528g351_7.poly_baseline(msk,order=1)
1529
1530
1531# Plot the data. The plotter can only plot a single scantable
1532# So we must merge the two tables first
1533
1534plotscans = merge(g351_5, g351_7)
1535
1536plotter.plot(plotscans) # Only shows one panel
1537
1538# Tell the plotter to stack polarisation and panel scans
1539plotter.set_mode('p','s')
1540
1541# Correct for the Tsys using our predefined function
1542execfile('mypol.py') # Read in the function xyscale
1543xyscale(g351_5,23.2,22.7) # Execute it on the data
1544xyscale(g351_7,23.2,22.7)
1545
1546# Only plot the velocity range of interest
1547plotter.set_range(-30,10)
1548
1549# Update the plot with the baselined data
1550plotter.plot()
1551
1552# Look at the various polarisation products
1553selection = selector()
1554selection.set_polarisations(``RR LL'')
1555plotter.set_selection(selection)
1556selection.set_polarisations(``I Plinear'')
1557plotter.set_selection(selection)
1558selection.set_polarisations(``I Q U V'')
1559plotter.set_selection(selection)
1560
1561# Save the plot as postscript
1562plotter.save('g351_stokes.ps')
1563
1564# Save the process spectra
1565plotscans.save('g351.asap')
1566
1567\end{verbatim}
1568
1569\subsection{Tidbinbilla}
1570
1571\index{Tidbinbilla}The following example is processing of some
1572Tidbinbilla observations of NH$_3$ at 12~mm. Tidbinbilla has (at the
1573time of observations) a single polarisation, but can process two IFs
1574simultaneously. In the example, the first half of the observation was
1575observing the (1,1) and (2,2) transitions simultaneously). The second
1576half observed only the (4,4) transition due to bandwidth
1577limitations. The data is position switched, observing first an
1578reference to the west, then the source twice and finally reference to
1579the east.
1580
1581\begin{verbatim}
1582
1583# Load the rpfits file and inspect
1584d = scantable('2003-03-16_082048_t0002.rpf')
1585print d
1586
1587# Make the quotient spectra
1588q = d.auto_quotient()
1589print q
1590
1591del d
1592
1593# Plot/select in velocity
1594q.set_freqframe('LSRK')
1595q.set_unit('km/s')
1596
1597# Correct for gain/el effects
1598
1599q.recalc_azel() # Tid does not write the elevation
1600q.gain_el()
1601q.opacity(0.05)
1602
1603# Seperate data from the (1,1)&(2,2) and (4,4) transitions
1604g1 = q.get_scan(range(6)) # scans 0..5
1605g2 = q.get_scan(range(6,12)) # scans 6..11
1606
1607# Align data in velocity
1608g1.freq_align()
1609g2.freq_align()
1610
1611# Average individual scans
1612a1 = g1.average_time()
1613a2 = g2.average_time()
1614
1615# Rpfits file only contains a single rest frequency. Set both
1616a1.set_restfreqs([23694.4700e6,23722.6336e6])
1617
1618plotter.plot(a1)
1619plotter.set_mode('i','t')
1620
1621a1.auto_poly_baseline()
1622
1623plotter.plot()
1624
1625a1.smooth('gauss',5)
1626plotter.plot()
1627
1628
1629\end{verbatim}
1630
1631\newpage
1632
1633\section{Appendix}
1634
1635\subsection{Function Summary}
1636
1637\index{Functions!summary}%
1638\begin{verbatim}
1639ASAP> commands()
1640 [The scan container]
1641 scantable - a container for integrations/scans
1642 (can open asap/rpfits/sdfits and ms files)
1643 copy - returns a copy of a scan
1644 get_scan - gets a specific scan out of a scantable
1645 (by name or number)
1646 set_selection - set a new subselection of the data
1647 get_selection - get the current selection object
1648 summary - print info about the scantable contents
1649 stats - get specified statistic of the spectra in
1650 the scantable
1651 stddev - get the standard deviation of the spectra
1652 in the scantable
1653 get_tsys - get the TSys
1654 get_time - get the timestamps of the integrations
1655 get_sourcename - get the source names of the scans
1656 get_azimuth - get the azimuth of the scans
1657 get_elevation - get the elevation of the scans
1658 get_parangle - get the parallactic angle of the scans
1659 get_unit - get the current unit
1660 set_unit - set the abcissa unit to be used from this
1661 point on
1662 get_abcissa - get the abcissa values and name for a given
1663 row (time)
1664 set_freqframe - set the frame info for the Spectral Axis
1665 (e.g. 'LSRK')
1666 set_doppler - set the doppler to be used from this point on
1667 set_dirframe - set the frame for the direction on the sky
1668 set_instrument - set the instrument name
1669 get_fluxunit - get the brightness flux unit
1670 set_fluxunit - set the brightness flux unit
1671 create_mask - return an mask in the current unit
1672 for the given region. The specified regions
1673 are NOT masked
1674 get_restfreqs - get the current list of rest frequencies
1675 set_restfreqs - set a list of rest frequencies
1676 flag_spectrum - flag data
1677 save - save the scantable to disk as either 'ASAP'
1678 or 'SDFITS'
1679 nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans
1680 nscan - the number of scans in the scantable
1681 nrow - te number of spectra in the scantable
1682 history - print the history of the scantable
1683 get_fit - get a fit which has been stored witnh the data
1684 average_time - return the (weighted) time average of a scan
1685 or a list of scans
1686 average_pol - average the polarisations together.
1687 The dimension won't be reduced and
1688 all polarisations will contain the
1689 averaged spectrum.
1690 convert_pol - convert to a different polarisation type
1691 auto_quotient - return the on/off quotient with
1692 automatic detection of the on/off scans
1693 (matched pairs and 1 off - n on)
1694 scale - return a scan scaled by a given factor
1695 add - return a scan with given value added
1696 bin - return a scan with binned channels
1697 resample - return a scan with resampled channels
1698 smooth - return the spectrally smoothed scan
1699 poly_baseline - fit a polynomial baseline to all Beams/IFs/Pols
1700 auto_poly_baseline - automatically fit a polynomial baseline
1701 recalc_azel - recalculate azimuth and elevation based on
1702 the pointing
1703 gain_el - apply gain-elevation correction
1704 opacity - apply opacity correction
1705 convert_flux - convert to and from Jy and Kelvin brightness
1706 units
1707 freq_align - align spectra in frequency frame
1708 rotate_xyphase - rotate XY phase of cross correlation
1709 rotate_linpolphase - rotate the phase of the complex
1710 polarization O=Q+iU correlation
1711 freq_switch - perform frequency switching on the data
1712 stats - Determine the specified statistic, e.g. 'min'
1713 'max', 'rms' etc.
1714 stddev - Determine the standard deviation of the current
1715 beam/if/pol
1716
1717 [Math] Mainly functions which operate on more than one scantable
1718
1719 average_time - return the (weighted) time average
1720 of a list of scans
1721 quotient - return the on/off quotient
1722 simple_math - simple mathematical operations on two scantables,
1723 'add', 'sub', 'mul', 'div'
1724 [Fitting]
1725 fitter
1726 auto_fit - return a scan where the function is
1727 applied to all Beams/IFs/Pols.
1728 commit - return a new scan where the fits have been
1729 commited.
1730 fit - execute the actual fitting process
1731 store_fit - store the fit parameters in the data (scantable)
1732 get_chi2 - get the Chi^2
1733 set_scan - set the scantable to be fit
1734 set_function - set the fitting function
1735 set_parameters - set the parameters for the function(s), and
1736 set if they should be held fixed during fitting
1737 set_gauss_parameters - same as above but specialised for individual
1738 gaussian components
1739 get_parameters - get the fitted parameters
1740 plot - plot the resulting fit and/or components and
1741 residual
1742 [Plotter]
1743 asapplotter - a plotter for asap, default plotter is
1744 called 'plotter'
1745 plot - plot a scantable
1746 save - save the plot to a file ('png' ,'ps' or 'eps')
1747 set_mode - set the state of the plotter, i.e.
1748 what is to be plotted 'colour stacked'
1749 and what 'panelled'
1750 set_selection - only plot a selected part of the data
1751 set_range - set a 'zoom' window [xmin,xmax,ymin,ymax]
1752 set_legend - specify user labels for the legend indeces
1753 set_title - specify user labels for the panel indeces
1754 set_abcissa - specify a user label for the abcissa
1755 set_ordinate - specify a user label for the ordinate
1756 set_layout - specify the multi-panel layout (rows,cols)
1757 set_colors - specify a set of colours to use
1758 set_linestyles - specify a set of linestyles to use if only
1759 using one color
1760 set_mask - set a plotting mask for a specific polarization
1761
1762 [Reading files]
1763 reader - access rpfits/sdfits files
1764 open - attach reader to a file
1765 close - detach reader from file
1766 read - read in integrations
1767 summary - list info about all integrations
1768
1769 [General]
1770 commands - this command
1771 print - print details about a variable
1772 list_scans - list all scantables created bt the user
1773 list_files - list all files readable by asap (default rpf)
1774 del - delete the given variable from memory
1775 range - create a list of values, e.g.
1776 range(3) = [0,1,2], range(2,5) = [2,3,4]
1777 help - print help for one of the listed functions
1778 execfile - execute an asap script, e.g. execfile('myscript')
1779 list_rcparameters - print out a list of possible values to be
1780 put into $HOME/.asaprc
1781 mask_and,mask_or,
1782 mask_not - boolean operations on masks created with
1783 scantable.create_mask
1784
1785 Note:
1786 How to use this with help:
1787 # function 'summary'
1788 [xxx] is just a category
1789 Every 'sub-level' in this list should be replaces by a '.' Period when
1790 using help
1791 Example:
1792 ASAP> help scantable # to get info on ths scantable
1793 ASAP> help scantable.summary # to get help on the scantable's
1794 ASAP> help average_time
1795
1796
1797\end{verbatim}
1798
1799\subsection{ASCII output format}
1800
1801\subsection{.asaprc settings}
1802\index{.asaprc}
1803\asaprc{verbose}{{\bf True}/False}{Print verbose output, good to disable in scripts}
1804
1805\asaprc{insitu}{{\bf True}/False}{Apply operations on the input
1806scantable or return new one}
1807
1808% plotting
1809
1810\asaprc{useplotter}{{\bf True}/False}{Preload a default plotter}
1811
1812\asaprc{plotter.gui}{{\bf True}/False}{Do we want a GUI or plot to a
1813file}
1814
1815\asaprc{plotter.stacking}{{\bf Pol} Beam IF Scan Time}{Default mode for
1816colour stacking}
1817
1818\asaprc{plotter.panelling}{Pol Beam IF {\bf Scan} Time}{Default mode
1819for panelling}
1820
1821\asaprc{plotter.ganged}{{\bf True}/False}{Push panels together, to
1822share axislabels}
1823
1824\asaprc{plotter.decimate}{True/{\bf False}}{Decimate the number of
1825points plotted by a factor of nchan/1024}
1826
1827% default colours/linestyles
1828%\asaprc{plotter.colours}{.}{.}
1829%\asaprc{plotter.linestyles{.}{.}
1830
1831% scantable
1832\asaprc{scantable.save}{{\bf ASAP} SDFITS FITS ASCII MS2}{Default output
1833format when saving}
1834
1835\asaprc{scantable.autoaverage}{{\bf True}/False}{Auto averaging on
1836read}
1837
1838\asaprc{scantable.freqframe}{{\bf LSRK} TOPO BARY etc}{default
1839frequency frame to set when function scantable.set\_freqframe is
1840called or the data is imported}
1841
1842\subsection{Installation}
1843
1844\index{Installation}ASAP depends on a number of third-party libraries which you must
1845have installed before attempting to build ASAP. These are:
1846
1847\begin{itemize}
1848\item AIPS++
1849\item Boost
1850\item Matplotlib
1851\item python/ipython
1852\end{itemize}
1853
1854Debian Linux is currently supported and we intend also
1855to support other popular Linux flavours, Solaris and Mac.
1856
1857Of the dependencies, AIPS++ is the most complex to install.
1858
1859\printindex
1860
1861\end{document}
1862
Note: See TracBrowser for help on using the repository browser.