Context Navigation

← Previous Change
Next Change →

Changeset 790 for branches/Release12/doc

Timestamp:

12/09/05 13:24:44 (19 years ago)

Author:

phi196

Message:

Added index, Mopra example, updated function sumary

File:

: 1 edited

branches/Release12/doc/cookbook.tex (modified) (56 diffs)

Legend:

: Unmodified
: Added
: Removed

branches/Release12/doc/cookbook.tex

-              r774
+              r790
 \usepackage{calc}
 \usepackage[dvips]{graphicx}
+\usepackage{makeidx}
 % Adjust the page size
 …
   \begin{minipage}[t]{\textwidth-75mm}#3\end{minipage}
+}
+\makeindex
 \begin{document}
 …
 \end{itemize}
 To start asap log onto one of these Linux hosts and enter
+\index{Running}To start asap log onto one of these Linux hosts and enter
 \begin{verbatim}
 …
 \section{Interface}
 ASAP is written in C++ and python. The user interface uses the
+\index{Interface}ASAP is written in C++ and python. The user interface uses the
 ``ipython'' interactive shell, which is a simple interactive interface
 to python. The user does not need to understand python to use this,
 …
 \subsection{Objects}
+\index{objects}
 The ASAP interface is based around a number of ``objects'' which the
 user deals with. Objects range from the data which have been read from
 …
 \subsection{Member Functions (functions)}
+Following the object oriented approach, objects have associated
+``member functions'' which can either be used to modify the data in
+some way or change global properties of the object. In this document
+member functions will be referred to simply as functions. From the
+command line, the user can execute these functions using the syntax:
+\index{Functions!member}Following the object oriented approach,
+objects have associated ``member functions'' which can either be used
+to modify the data in some way or change global properties of the
+object. In this document member functions will be referred to simply
+as functions. From the command line, the user can execute these
+functions using the syntax:
 \begin{verbatim}
   ASAP> out = object.function(arguments)
 …
 \subsection{Global Functions}
 It does not make sense to implement some functions as member
+\index{Functions!global}It does not make sense to implement some functions as member
 functions, typically functions which operate on more than one
 scantable (e.g. time averaging of many scans). These functions will
 …
 \subsection{Interactive environment}
+ipython has a number of useful interactive features and a few things
 to be aware of for the new user.
+\index{ipython!environment}ipython has a number of useful interactive
+features and a few things to be aware of for the new user.
 \subsubsection{String completion}
+Tab completion is enabled for all function names. If you type the
+first few letters of a function name, then type {\tt <TAB>} the
+function name will be auto completed if it is un-ambiguous, or a list
+of possibilities will be given. Auto-completion works for the user
+object names as well as function names. It does not work for
+filenames, nor for function arguments.
+\index{ipython!string completion}Tab completion is enabled for all
+function names. If you type the first few letters of a function name,
+then type {\tt <TAB>} the function name will be auto completed if it
+is un-ambiguous, or a list of possibilities will be
+given. Auto-completion works for the user object names as well as
+function names. It does not work for filenames, nor for function
+arguments.
 Example
 …
 \subsubsection{Leading Spaces}
+Python uses leading space to mark blocks of code. This means that it
+you start a command line with a space, the command generally will
 fail with an syntax error.
+\index{ipython!leading space}Python uses leading space to mark blocks
+of code. This means that it you start a command line with a space, the
+command generally will fail with an syntax error.
 \subsubsection{Variable Names}
+During normal data processing, the user will have to create named
+variables to hold spectra etc. These must conform to the normal python
+syntax, specifically they cannot contain ``special'' characters such
+as \@ \$ etc and cannot start with a number (but can contain numbers).
+Variable (and function) names are case sensitive.
+\index{ipython!variable names}During normal data processing, the user
+will have to create named variables to hold spectra etc. These must
+conform to the normal python syntax, specifically they cannot contain
+``special'' characters such as \@ \$ etc and cannot start with a
+number (but can contain numbers).  Variable (and function) names are
+case sensitive.
 \subsubsection{Unix Interaction}
+Basic unix shell commands (\cmd{pwd}, \cmd{ls}, \cmd{cd} etc) can be
+issued from within ASAP. This allows the user to do things like look
+at files in the current directory. The shell command ``\cmd{cd}''
+works within ASAP, allowing the user to change between data
+directories. Unix programs cannot be run this way, but the shell
+escape ``$!$'' can be used to run arbitrary programs. E.g.
+\index{ipython!unix interaction}Basic unix shell commands (\cmd{pwd},
+\cmd{ls}, \cmd{cd} etc) can be issued from within ASAP. This allows
+the user to do things like look at files in the current directory. The
+shell command ``\cmd{cd}'' works within ASAP, allowing the user to
+change between data directories. Unix programs cannot be run this way,
+but the shell escape ``$!$'' can be used to run arbitrary
+programs. E.g.
 \begin{verbatim}
 …
 \subsection{Help}
+ASAP has built in help for all functions. To get a list of functions type:
+\index{Help}ASAP has built in help for all functions. To get a list of
+functions type:
 \begin{verbatim}
 …
 \subsection{Customisation - .asaprc}
+ASAP use an \cmd{.asaprc} file to control the user's preference of
+default values for various functions arguments. This includes the
+defaults for arguments such as \cmd{insitu}, scantable \cmd{freqframe}
+and the plotters \cmd{set\_mode} values. The help on individual
+functions says which arguments can be set default values from the
+\cmd{.asaprc} file. To get a sample contents for the \cmd{.asaprc}
 file use then command \cmd{list\_rcparameters}.
+\index{.asaprc}ASAP use an \cmd{.asaprc} file to control the user's
+preference of default values for various functions arguments. This
+includes the defaults for arguments such as \cmd{insitu}, scantable
+\cmd{freqframe} and the plotters \cmd{set\_mode} values. The help on
+individual functions says which arguments can be set default values
+from the \cmd{.asaprc} file. To get a sample contents for the
+\cmd{.asaprc} file use then command \cmd{list\_rcparameters}.
 Common values include:
 …
 \section{Scantables}
+\index{Scantables}
 \subsection {Description}
 \subsubsection {Basic Structure}
+ASAP data handling works on objects called scantables.  A scantable
+holds your data, and also provides functions to operate
 upon it.
+\index{Scantable!structure}ASAP data handling works on objects called
+scantables.  A scantable holds your data, and also provides functions
+to operate upon it.
 The building block of a scantable is an integration, which is a single
 …
 \subsubsection {Contents}
+A scantable has header information and data (a scantable is actually an AIPS++
+Table and it is stored in Memory when you are manipulating it with ASAP.
+You can store it to disk and then browse it with the AIPS++
+Table browser if you know how to do that !).
+\index{Scantable!contents}A scantable has header information and data
+(a scantable is actually an AIPS++ Table and it is stored in Memory
+when you are manipulating it with ASAP.  You can store it to disk and
+then browse it with the AIPS++ Table browser if you know how to do
+that !).
 The data are stored in columns (the length of a column is the number of
 …
 \subsection{Management}
+During processing it is possible to create a large number of scan
+tables. These all consume memory, so it is best to periodically remove
+unneeded scan tables. Use \cmd{list\_scans} to print a list of all
 scantables and \cmd{del} to remove unneeded ones.
+\index{Scantable!management}During processing it is possible to create
+a large number of scan tables. These all consume memory, so it is best
+to periodically remove unneeded scan tables. Use \cmd{list\_scans} to
+print a list of all scantables and \cmd{del} to remove unneeded ones.
 Example:
 …
 \subsection{State}
+Each scantable contains "state"; these are properties  applying to all
 of the data in the scantable.
+\index{Scantable!state}Each scantable contains "state"; these are
+properties applying to all of the data in the scantable.
 Examples are the selection of beam, IF and polarisation,  spectral unit
 …
 \subsubsection{Rest Frequency}
+ASAP reads the line rest frequency from the RPFITS file when reading
+the data. The values stored in the RPFITS file are not always correct
+and so there is a function \cmd{set\_restfreq} to set the rest frequencies.
+\index{Scantable!rest frequency}ASAP reads the line rest frequency
+from the RPFITS file when reading the data. The values stored in the
+RPFITS file are not always correct and so there is a function
+\cmd{set\_restfreq} to set the rest frequencies.
 For each integration, there is a rest-frequency per IF (the rest
 …
 \subsection{Data Selection}
+Data selection is currently fairly limited. This will be improved in
 the future.
+\index{Scantable!data selection}Data selection is currently fairly limited. This
+will be improved in the future.
 \subsubsection{Cursor}
+Generally the user will want to run functions on all rows in a
+scantable. This allows very fast reduction of data. There are situations
+when functions should only operate on specific elements of the spectra. This
+is handled by the scantable cursor, which allows the user to select a
+single beam, IF and polarisation combination.
+\index{Scantable!cursor}Generally the user will want to run functions
+on all rows in a scantable. This allows very fast reduction of
+data. There are situations when functions should only operate on
+specific elements of the spectra. This is handled by the scantable
+cursor, which allows the user to select a single beam, IF and
+polarisation combination.
 Example :
 …
 \subsubsection{Row number}
+Most functions work on all rows of a scan table. Exceptions are the
+fitter and plotter. If you wish to only operate on a selected set of
+scantable rows, use the \cmd{get\_scan} function to copy the rows into
 a new scantable.
+\index{Scantable!row selection}Most functions work on all rows of a
+scan table. Exceptions are the fitter and plotter. If you wish to only
+operate on a selected set of scantable rows, use the \cmd{get\_scan}
+function to copy the rows into a new scantable.
 \subsubsection{Allaxes}
+Many functions have an \cmd{allaxes} option which controls whether the
+function will operate on all elements within a scantable row, or just
+those selected with the current cursor. The default is taken from the
+users {\tt .asaprc} file.
+\index{allaxes}\index{Scantable!allaxes}Many functions have an
+\cmd{allaxes} option which controls whether the function will operate
+on all elements within a scantable row, or just those selected with
+the current cursor. The default is taken from the users {\tt .asaprc}
+file.
 \subsubsection{Masks}
+Many tasks (fitting, baseline subtraction, statistics etc) should only
+be run on range of channels. Depending on the current ``unit'' setting
+this range is set directly as channels, velocity or frequency
+ranges. Internally these are converted into a simple boolean mask for
+each channel of the abscissa. This means that if the unit setting is
+later changed, previously created mask are still valid. (This is not
+true for functions which change the shape or shift the frequency axis).
+You create masks with the function \cmd{create\_mask} and this specified
+\index{Masks}\index{Scantable!masks}Many tasks (fitting, baseline
+subtraction, statistics etc) should only be run on range of
+channels. Depending on the current ``unit'' setting this range is set
+directly as channels, velocity or frequency ranges. Internally these
+are converted into a simple boolean mask for each channel of the
+abscissa. This means that if the unit setting is later changed,
+previously created mask are still valid. (This is not true for
+functions which change the shape or shift the frequency axis).  You
+create masks with the function \cmd{create\_mask} and this specified
 the channels to be included in the selection.
 …
 \section{Data Input}
 Data can be loaded in one of two ways; using the reader object or via
+\index{Reading data}Data can be loaded in one of two ways; using the reader object or via
 the scantable constructor. The scantable method is simpler but the
 reader allow the user more control on what is read.
 …
 \subsection{Scantable constructor}
+This loads all of the data from filename into the scantable object scans
+and averages all the data within a scan (i.e.  the resulting scantable
+\index{Scantable constructor}\index{Scantable!constructor}This loads
+all of the data from filename into the scantable object scans and
+averages all the data within a scan (i.e.  the resulting scantable
 will have one row per scan).  The recognised input file formats are
 RPFITS, SDFITS (singledish fits), ASAP's scantable format and aips++
 MeasurementSet2 format.
 Example usage:
 …
 \subsection{Reader object}
+For more control when reading data into ASAP, the reader object should
+be used.  This has the option of only reading in a range of integrations
+and does not perform any scan averaging of the data, allowing analysis
+of the individual integrations.  Note that due to limitation of the
+RPFITS library, only one reader object can be open at one time reading
+RPFITS files.  To read multiple RPFITS files, the old reader must be
+destroyed before the new file is opened.  However, multiple readers can
+be created and attached to SDFITS files.
+\index{Reader object}\index{Scantable!reader object}For more control
+when reading data into ASAP, the reader object should be used.  This
+has the option of only reading in a range of integrations and does not
+perform any scan averaging of the data, allowing analysis of the
+individual integrations.  Note that due to limitation of the RPFITS
+library, only one reader object can be open at one time reading RPFITS
+files.  To read multiple RPFITS files, the old reader must be
+destroyed before the new file is opened.  However, multiple readers
+can be created and attached to SDFITS files.
 …
 %How and when?
 \subsection{Auto quotient}
+Quotients can be computed ``automatically''. This requires the data to
 have matching source/reference pairs or one reference for multiple
+sources. Auto quotient assumes reference scans have a trailing ``\_R''
+in the source name for data from Parkes and Mopra, and a trailing
 ``e'' or ``w'' for data fro, Tidbinbilla.
+\index{Auto quotient}Quotients can be computed ``automatically''. This
+requires the data to have matching source/reference pairs or one
+reference for multiple sources. Auto quotient assumes reference scans
+have a trailing ``\_R'' in the source name for data from Parkes and
+Mopra, and a trailing ``e'' or ``w'' for data fro, Tidbinbilla.
 \begin{verbatim}
 …
 \subsection{Separate reference and source observations}
+Most data from ATNF observatories distinguishes on and off source data
+using the file name. This makes it easy to create two scantables with
 the source and reference data. As long as there was exactly one
+reference observation for each on source observation for following
 method will work.
+\index{Quotient spectra}Most data from ATNF observatories
+distinguishes on and off source data using the file name. This makes
+it easy to create two scantables with the source and reference
+data. As long as there was exactly one reference observation for each
+on source observation for following method will work.
 For Mopra and Parkes data:
 …
 \subsection{Time average separate scans}
+If you have observed the source with multiple source/reference cycles you
+will want to scan-average the quotient spectra together.
+\index{Time average}If you have observed the source with multiple
+source/reference cycles you will want to scan-average the quotient
+spectra together.
 \begin{verbatim}
 …
 \end{verbatim}
+Note that, if needed, you should run \cmd{freq\_align}, \cmd{gain\_el}
+and \cmd{opacity} before you average the data in time (\S
+\ref{sec:gainel} \& \ref{sec:freqalign}).
 \subsection{Baseline fitting}
+To make a baseline fit, you must first create a mask of channels to
 use in the baseline fit.
+\index{Baseline fitting}To make a baseline fit, you must first create
+a mask of channels to use in the baseline fit.
 \begin{verbatim}
 …
 \subsubsection{Auto-baselining}
 The function \cmd{auto\_poly\_baseline} can be used to automatically
+\index{Auto-baseline}The function \cmd{auto\_poly\_baseline} can be used to automatically
 baseline your data without having to specify channel ranges for the
 line free data. It automatically figures out the line-free emission
 …
 \subsection{Average the polarisations}
 If you are just interested in the highest SNR for total intensity you
+\index{average\_pol}If you are just interested in the highest SNR for total intensity you
 will want to average the parallel polarisations together.
 …
 \subsection{Calibration}
 For most uses, calibration happens transparently as the input data
+\index{Calibration}For most uses, calibration happens transparently as the input data
 contains the Tsys measurements taken during observations. The nominal
 ``Tsys'' values may be in Kelvin or Jansky. The user may wish to
 …
 \subsubsection{Brightness Units}
+RPFITS files do not contain any information as to whether the telescope
+calibration was in units of Kelvin or Janskys.  On reading the data a
+default value is set depending on the telescope and frequency of
+observation.  If this default is incorrect (you can see it in the
+listing from the \cmd{summary} function) the user can either override
+this value on reading the data or later.  E.g:
+\index{Brightness Units}RPFITS files do not contain any information as
+to whether the telescope calibration was in units of Kelvin or
+Janskys.  On reading the data a default value is set depending on the
+telescope and frequency of observation.  If this default is incorrect
+(you can see it in the listing from the \cmd{summary} function) the
+user can either override this value on reading the data or later.
+E.g:
 \begin{verbatim}
 …
 \subsubsection{Tsys scaling}
+Sometime the nominal Tsys measurement at the telescope is wrong due to
+an incorrect noise diode calibration. This can easily be corrected for
+with the scale function. By default, \cmd{scale} only scans the
 spectra and not the corresponding Tsys.
+\index{Tsys scaling}Sometime the nominal Tsys measurement at the
+telescope is wrong due to an incorrect noise diode calibration. This
+can easily be corrected for with the scale function. By default,
+\cmd{scale} only scans the spectra and not the corresponding Tsys.
 \begin{verbatim}
 …
 \subsubsection{Unit Conversion}
+To convert measurements in Kelvin to Jy (and vice versa) the global
+function \cmd{convert\_flux} is needed. This converts and scales the data
+from K to Jy or vice-versa depending on what the current brightness unit is
+set to. The function knows the basic parameters for some frequencies
+and telescopes, but the user may need to supply the aperture
+efficiency, telescope diameter or the Jy/K factor.
+\index{Unit conversion}To convert measurements in Kelvin to Jy (and
+vice versa) the global function \cmd{convert\_flux} is needed. This
+converts and scales the data from K to Jy or vice-versa depending on
+what the current brightness unit is set to. The function knows the
+basic parameters for some frequencies and telescopes, but the user may
+need to supply the aperture efficiency, telescope diameter or the Jy/K
+factor.
 \begin{verbatim}
 …
 \subsubsection{Gain-Elevation and Opacity Corrections}
+As higher frequencies (particularly $>$20~GHz) it is important to make
+corrections for atmospheric opacity and gain-elevation effects.
+\label{sec:gainel}
+\index{Gain-elevation}As higher frequencies (particularly $>$20~GHz)
+it is important to make corrections for atmospheric opacity and
+gain-elevation effects.
 Note that currently the elevation is not written correctly into
 …
 \end{verbatim}
 Gain-elevation curves for some telescopes and frequencies are known to
 ASAP (currently only for Tidbinbilla at 20~GHz).  In these cases making
+gain-corrections is simple.  If the gain curve for your data is not
 known, the user can supply either a gain polynomial or text file
+ASAP (currently only for Tidbinbilla at 20~GHz).  In these cases
+making gain-corrections is simple.  If the gain curve for your data is
+not known, the user can supply either a gain polynomial or text file
 tabulating gain factors at a range of elevations (see \cmd{help
 scantable.gain\_el}).
 …
 \end{verbatim}
+Opacity corrections can be made with the global function
+\cmd{opacity}. This should work on all telescopes as long as a
 measurement of the opacity factor was made during the observation.
+\index{Opacity}Opacity corrections can be made with the global
+function \cmd{opacity}. This should work on all telescopes as long as
+a measurement of the opacity factor was made during the observation.
 \begin{verbatim}
 …
 \subsection{Frequency Frame Alignment}
+When time averaging a series of scans together, it is possible that
+the velocity scales are not exactly aligned.  This may be for many
+reasons such as not Doppler tracking the observations, errors in the
+Doppler tracking etc.  This mostly affects very long integrations or
+integrations averaged together from different days.  Before averaging
+such data together, they should be frequency aligned using
+\cmd{freq\_align}.
+\label{sec:freqalign}
+\index{Frequency alignment}\index{Velicity alignment}When time
+averaging a series of scans together, it is possible that the velocity
+scales are not exactly aligned.  This may be for many reasons such as
+not Doppler tracking the observations, errors in the Doppler tracking
+etc.  This mostly affects very long integrations or integrations
+averaged together from different days.  Before averaging such data
+together, they should be frequency aligned using \cmd{freq\_align}.
 E.g.:
 …
 \section{Scantable manipulation}
+While it is very useful to have many independent sources within one
+scantable, it is often inconvenient for data processing. The
+\cmd{get\_scan} function can be used to create a new scantable with a
+selection of scans from a scantable. The selection can either be on
+the source name, with simple wildcard matching or set of scan ids.
+\index{Scantable!manipulation}While it is very useful to have many
+independent sources within one scantable, it is often inconvenient for
+data processing. The \cmd{get\_scan} function can be used to create a
+new scantable with a selection of scans from a scantable. The
+selection can either be on the source name, with simple wildcard
+matching or set of scan ids.
 For example:
 …
 \section{Data Output}
+ASAP can save scantables in a variety of formats, suitable for reading
+into other packages. The formats are:
+\index{Scantable!save}\index{Saving data}ASAP can save scantables in a
+variety of formats, suitable for reading into other packages. The
+formats are:
 \begin{itemize}
 …
 \section{Plotter}
 Scantable spectra can be plotted at any time. An asapplotter object is
+\index{Plotter}Scantable spectra can be plotted at any time. An asapplotter object is
 used for plotting, meaning multiple plot windows can be active at the
 same time. On start up a default asapplotter object is created called
 …
 \label{sec:plotter_cursor}
+The plotter can plot up to 25 panels and stacked spectra per
+panel. If you have data larger than this (or for your own sanity) you
+need to select a subset of this data. This is particularly true for
+multibeam or multi IF data. The plotter \cmd{set\_cursor} function is
+used to select a subset of the data. The arguments \cmd{row},
+\cmd{beam} and \cmd{IF} all accept a vector of indices corresponding
+to row, beam or IF selection. Only the selected data will be plotted.
+To select on polarisation, see section~\ref{sec:polplot}.
+\index{Plotter!selection}The plotter can plot up to 25 panels and
+stacked spectra per panel. If you have data larger than this (or for
+your own sanity) you need to select a subset of this data. This is
+particularly true for multibeam or multi IF data. The plotter
+\cmd{set\_cursor} function is used to select a subset of the data. The
+arguments \cmd{row}, \cmd{beam} and \cmd{IF} all accept a vector of
+indices corresponding to row, beam or IF selection. Only the selected
+data will be plotted.  To select on polarisation, see
+section~\ref{sec:polplot}.
 Examples:
 …
 \subsection{Plot Control}
+The plotter window has a row of buttons on the lower left. These can
+be used to control the plotter (mostly for zooming the individual
 plots). From left to right:
+\index{Plotter!control}The plotter window has a row of buttons on the
+lower left. These can be used to control the plotter (mostly for
+zooming the individual plots). From left to right:
 \begin{itemize}
 …
 \item[Save] (floppy disk). Save the plot as a postscript or .png file
+You can also type ``g'' in the plot window to toggle on and off grid
+lines. Typing 'l' turns on and off logarithmic Y-axis.
 \end{itemize}
 …
 \section{Fitting}
+Currently multicomponent Gaussian function is available. This is done
+by creating a fitting object, setting up the fit and actually fitting
+the data. Fitting can either be done on a single scantable row/cursor
+selection or on an entire scantable using the \cmd{auto\_fit} function.
+\index{Fitting}Currently multicomponent Gaussian function is
+available. This is done by creating a fitting object, setting up the
+fit and actually fitting the data. Fitting can either be done on a
+single scantable row/cursor selection or on an entire scantable using
+the \cmd{auto\_fit} function.
 \begin{verbatim}
 …
 \subsection{Fit saving}
+One you are happy with your fit, it is possible to store it as part of
 the scantable.
+\index{Fitter!Fit saving}One you are happy with your fit, it is
+possible to store it as part of the scantable.
 \begin{verbatim}
 …
 \section{Polarisation}
+Currently ASAP only supports polarmetric analysis on linearly
+polarised feeds and the cross polarisation products measured. Other
 cases will be added on an as needed basic.
+\index{Polarisation}Currently ASAP only supports polarmetric analysis
+on linearly polarised feeds and the cross polarisation products
+measured. Other cases will be added on an as needed basic.
 Conversions of linears to Stokes or Circular polarisations are done
 …
 for transparent polarimetric calibration.}
+It is possible that there is a phase offset between polarisation which
+will effect the phase of the cross polarisation correlation, and so give
+rise to spurious polarisation. \cmd{rotate\_xyphase} can be used to
+correct for this error. At this point, the user must know how to
+determine the size of the phase offset themselves.
+\index{Polarisation!calibration}It is possible that there is a phase
+offset between polarisation which will effect the phase of the cross
+polarisation correlation, and so give rise to spurious
+polarisation. \cmd{rotate\_xyphase} can be used to correct for this
+error. At this point, the user must know how to determine the size of
+the phase offset themselves.
 \begin{verbatim}
 …
 \label{sec:polplot}
+To plot Stokes values, the plotter \cmd{set\_cursor} function should
+be called first using the \cmd{pol} argument. The values which can be
+plotted include a selection of [I,Q,U,V], [I, Plinear, Pangle, V],
+[RR, LL] or [XX, YY, Real(XY), Imaginary(XY)]. (Plinear and Pangle are
+the percentage and position angle of linear polarisation). Conversion
+to circular polarisations are currently not available.
+\index{Polarisation!plotting}To plot Stokes values, the plotter
+\cmd{set\_cursor} function should be called first using the \cmd{pol}
+argument. The values which can be plotted include a selection of
+[I,Q,U,V], [I, Plinear, Pangle, V], [RR, LL] or [XX, YY, Real(XY),
+Imaginary(XY)]. (Plinear and Pangle are the percentage and position
+angle of linear polarisation). Conversion to circular polarisations
+are currently not available.
 Example:
 …
 \subsection{Saving}
 When saving data using the \cmd{save} function, the \cmd{stokes}
+argument can be used to save the data as Stoke values when saving in
 FITS format.
+\index{Polarisation!saving}When saving data using the \cmd{save}
+function, the \cmd{stokes} argument can be used to save the data as
+Stoke values when saving in FITS format.
 Example:
 …
 \section{Scantable Mathematics}
+It is possible to to simple mathematics directly on scantables from
+the command line using the \cmd{+, -, *, /} operators as well as their
+cousins \cmd{+=, -= *=, /=}. This works between two scantables or a
+scantable and a float. (Note that it does not work for integers).
+\index{Scantable!maths}It is possible to to simple mathematics
+directly on scantables from the command line using the \cmd{+, -, *,
+/} operators as well as their cousins \cmd{+=, -= *=, /=}. This works
+between two scantables or a scantable and a float. (Note that it does
+not work for integers).
 \begin{verbatim}
 …
 \section{Scripting}
+Because asap is based on python, it easy for the user write their own
+scripts and functions to process data. This is highly recommended as
+most processing of user data could then be done in a couple of steps
+using a few simple user defined functions. A Python primer is beyond
+the scope of this userguide. See the asap home pages for a scripting
+tutorial or the main python website for comprehensive documentation.
+\index{Scripting}Because asap is based on python, it easy for the user
+write their own scripts and functions to process data. This is highly
+recommended as most processing of user data could then be done in a
+couple of steps using a few simple user defined functions. A Python
+primer is beyond the scope of this userguide. See the asap home pages
+for a scripting tutorial or the main python website for comprehensive
+documentation.
 \hspace{1cm} http://www.atnf.csiro.au/computing/software/asap/tutorials
 …
 \subsection{Mopra}
+\index{Mopra}
+The following example is of some dual polarisation, position switched
+data from Mopra. The source has been observed mulitple times split
+into a number of seperate rpfits files. To make the processing easier,
+the first step is to \cmd{cat} the seeprate rpfits files together and
+load as a whole (future versions of asap will make this unnecessary).
+\begin{verbatim}
+# Concatenate the individual rpfits files together before loading
+!cat 2005-06*.rpf > data.rpf
+# Load the data into a scantable
+data = scantable('data.rpf')
+print data
+# Form the quotient spectra
+q = data.auto_quotient()
+print q
+# Look at the spectra
+plotter.plot(q)
+# Velocity align the data before averaging
+q.set_unit('km/s')
+q.set_freqframe('LSRK')
+q.freq_align()
+# Average all scans in time
+av = q.average_time()
+plotter.plot(av)
+# Remove the baseline
+msk = av.create_mask([100,130],[160,200])
+av.poly_baseline(msk,2)
+# Average the two polarisations together
+iav = av.average_pol()
+print iav
+plotter.plot(iav)
+# Set a sensible velocity range on the plot
+plotter.set_range(85,200)
+# Smooth the data a little
+av.smooth('gauss',4)
+plotter.plot()
+# Fit a guassian to the emission
+f = fitter()
+f.set_function(gauss=1)
+f.set_scan(av)
+f.fit()
+# View the fit
+f.plot()
+# Get the fit parameters
+f.get_parameters()
+\end{verbatim}
 \subsection{Parkes Polarimetry}
+The following example is processing of some Parkes polarmetric
+observations of OH masers at 1.6~GHz. Because digital filters where
+used in the backend, the baselines are stable enough not to require a
+quotient spectra. The 4~MHz bandwidth is wide enough to observe both
+the 1665 and 1667~MHz OH maser transitions. Each source was observed
+once for about 10 minutes. Tsys information was not written to the
+rpfits file (a nominal 25K values was used), so the amplitudes need
+to be adjusted based on a separate log file. A simple user function is
+used to simplify this, contained in a file called mypol.py:
+\index{Parkes}\index{Polarisation}The following example is processing
+of some Parkes polarmetric observations of OH masers at
+.6~GHz. Because digital filters where used in the backend, the
+baselines are stable enough not to require a quotient spectra. The
+~MHz bandwidth is wide enough to observe both the 1665 and 1667~MHz
+OH maser transitions. Each source was observed once for about 10
+minutes. Tsys information was not written to the rpfits file (a
+nominal 25K values was used), so the amplitudes need to be adjusted
+based on a separate log file. A simple user function is used to
+simplify this, contained in a file called mypol.py:
 \begin{verbatim}
 …
 \subsection{Tidbinbilla}
+The following example is processing of some Tidbinbilla observations
+of NH$_3$ at 12~mm. Tidbinbilla has (at the time of observations) a
+single polarisation, but can process two IFs simultaneously. In the
+example, the first half of the observation was observing the (1,1) and
+(2,2) transitions simultaneously). The second half observed only the
+(4,4) transition due to bandwidth limitations. The data is position
+switched, observing first an reference to the west, then the source
+twice and finally reference to the east.
+\index{Tidbinbilla}The following example is processing of some
+Tidbinbilla observations of NH$_3$ at 12~mm. Tidbinbilla has (at the
+time of observations) a single polarisation, but can process two IFs
+simultaneously. In the example, the first half of the observation was
+observing the (1,1) and (2,2) transitions simultaneously). The second
+half observed only the (4,4) transition due to bandwidth
+limitations. The data is position switched, observing first an
+reference to the west, then the source twice and finally reference to
+the east.
 \begin{verbatim}
 …
 \subsection{Function Summary}
+\index{Functions!summary}%
 \begin{verbatim}
     [The scan container]
 …
             get_tsys        - get the TSys
             get_time        - get the timestamps of the integrations
+            get_azimuth     - get the azimuth of the scans
+            get_elevation   - get the elevation of the scans
+            get_parangle    - get the parallactic angle of the scans
             get_unit        - get the currnt unit
             set_unit        - set the abcissa unit to be used from this
 …
 \subsection{Installation}
 ASAP depends on a number of third-party libraries which you must
+\index{Installation}ASAP depends on a number of third-party libraries which you must
 have installed before attempting to build ASAP. These are:
 …
 \subsection{.asaprc settings}
+\index{.asaprc}
 \asaprc{verbose}{{\bf True}/False}{Print verbose output}
 …
 of information printed by summary}
+\printindex
 \end{document}

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 790 for branches/Release12/doc

Legend:

branches/Release12/doc/cookbook.tex

Download in other formats: