source: trunk/doc/userguide.tex@ 1219

Last change on this file since 1219 was 1217, checked in by mar637, 18 years ago

Merge from Release2.1.0b tag

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