source: trunk/doc/userguide.tex@ 1456

Last change on this file since 1456 was 1394, checked in by Malte Marquarding, 17 years ago

some minor fixes for typos and outdated info

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