- Timestamp:
- 08/30/06 12:30:43 (18 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
tags/Release2.1.0b/doc/userguide.tex
r1064 r1215 13 13 \setlength{\parskip}{1ex} 14 14 15 \title{ATNF Spectral Analysis Package\\User Guide v2. 0}15 \title{ATNF Spectral Analysis Package\\User Guide v2.1\\DRAFT } 16 16 \author{Chris Phillips} 17 17 … … 24 24 } 25 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 26 36 \makeindex 27 28 37 29 38 \begin{document} … … 39 48 package. 40 49 41 This userguide has been updated for the ASAP 2.0 release which has a 42 number of significant changes which affect the user interface. Please 43 report any mistakes you find. 50 This userguide is being updated for the ASAP 2.1. Please report any 51 mistakes you find. 44 52 45 53 \section{Installation and Running} … … 53 61 \item Mopra - use host {\tt minos} 54 62 \end{itemize} 63 64 Or use your own Linux desktop. 65 66 {\em Note. ASAP2.1 only runs on ATNF Linux machines which have been 67 updated to Debian Sarge and are using the ``DEBIANsarge'' 68 /usr/local. If your favourite machine has not been upgraded, send a 69 request your your friendly IT support.} 55 70 56 71 \index{Running}To start asap log onto one of these Linux hosts and enter … … 266 281 267 282 The building block of a scantable is an integration, which is a single 268 row of a scantable. Each row contains just one spectrum for each beam, IF and 269 polarisation. For example Parkes multibeam data would contain many 270 beams, one IF and 2-4 polarisations, while the new Mopra 8-GHz 271 filterbank will eventually produce one beam, many IFs, and 2-4 272 polarisations. All of the combinations of Beams/IFs an Polarisations are 283 row of a scantable. Each row contains just one spectrum for each beam, 284 IF and polarisation. For example Parkes OH-multibeam data would 285 normally contain 13 beams, 1 IF and 2 polarisations, Parkes 286 methanol-multibeam data would contain 7 beams, 2 IFs and 2 287 polarisations while the Mopra 8-GHz MOPDS filterbank will produce one 288 beam, many IFs, and 2-4 polarisations. 289 290 All of the combinations of Beams/IFs an Polarisations are 273 291 contained in seperate rows. These rows are grouped in cycles (same time stamp). 274 292 275 A collection of cycles for one source is termed 276 a scan (and each scan has a unique numeric identifier, the SCANNO). A 277 scantable is then a collection of one or more scans. If you have 278 scan-averaged your data in time, i.e. you have averegaed all cycles within 279 a scan, then eachscan would hold just one (averaged) integration.280 281 Many of the functions which work on scantables can either return a 282 newscantable with modified data or change the scantable insitu. Which293 A collection of cycles for one source is termed a scan (and each scan 294 has a unique numeric identifier, the SCANNO). A scantable is then a 295 collection of one or more scans. If you have scan-averaged your data 296 in time, i.e. you have averegaed all cycles within a scan, then each 297 scan would hold just one (averaged) integration. 298 299 Many of the functions which work on scantables can either return a new 300 scantable with modified data or change the scantable insitu. Which 283 301 method is used depends on the users preference. The default can be 284 302 changed via the {\tt .asaprc} resource file. … … 309 327 The data are stored in columns (the length of a column is the number of 310 328 rows/spectra of course). 311 312 329 313 330 Two important columns are those that describe the frequency setup. We mention … … 476 493 \end{verbatim} 477 494 478 {\em Currently the following is not implemented }495 {\em Currently the following is not implemented 479 496 480 497 In both of the above modes, you can also specify the rest frequencies via … … 486 503 ASAP> scans.set_restfreqs(freqs=['OH1665','OH1667']) 487 504 \end{verbatim} 488 505 } 489 506 490 507 \subsubsection{Masks} … … 649 666 \end{verbatim} 650 667 651 %If this is not sufficient the following alternative method can be used.652 % 653 %\subsection{Separate reference and source observations}654 % 655 %\index{Quotient spectra}Most data from ATNF observatories656 %distinguishes on and off source data using the file name. This makes657 %it easy to create two scantables with the source and reference658 %data. As long as there was exactly one reference observation for each659 %on source observation for following method will work.660 % 661 %For Mopra and Parkes data:662 %\begin{verbatim}663 %ASAP> r = scans.get_scan('*_R')664 %ASAP> s = scans.get_scan('*_S')665 %\end{verbatim}666 % 667 %For Tidbinbilla data668 %\begin{verbatim}669 %ASAP> r = scans.get_scan('*_[ew]')670 %ASAP> s = scans.get_scan('*_[^ew]')671 %\end{verbatim}672 % 673 %\subsection{Make the quotient spectra}674 % 675 %Use the quotient function676 % 677 %\begin{verbatim}678 %ASAP> q = s.quotient(r)679 %\end{verbatim}680 % 681 %This uses the rows in scantable \cmd{r} as reference spectra for the682 %rows in scantable \cmd{s}. Scantable \cmd{r} must have either 1 row683 %(which is applied to all rows in \cmd{s}) or both scantables must have684 %the same number of rows.668 If 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 673 distinguishes on and off source data using the file name. This makes 674 it easy to create two scantables with the source and reference 675 data. As long as there was exactly one reference observation for each 676 on source observation for following method will work. 677 678 For 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 684 For 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 692 Use the quotient function 693 694 \begin{verbatim} 695 ASAP> q = s.quotient(r) 696 \end{verbatim} 697 698 This uses the rows in scantable \cmd{r} as reference spectra for the 699 rows 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 701 the same number of rows. 685 702 686 703 \subsection{Time average separate scans} … … 702 719 703 720 The default is to use integration time weighting. The alternative is 704 to use none, variance, Tsys weighting or Tsys \& integration time. 721 to use none, variance, Tsys weighting, Tsys \& integration time or 722 median averaging. 705 723 706 724 \begin{verbatim} … … 808 826 # Or in two steps 809 827 ASAP> scans = scantable('2004-11-23_1841-P484.rpf') 810 ASAP> scans.set_fluxunit('Jy) 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 834 information as to the feed polarisation. ASAP will set a default based 835 on the antenna, but this will often be wrong the data has been read, 836 the default can be changed using the \cmd{set\_feedtype} function with 837 an argument of \cmd{'linear'} or \cmd{'circular'}. 838 839 E.g: 840 841 \begin{verbatim} 842 ASAP> scans = scantable('2004-11-23_1841-P484.rpf') 843 ASAP> scans.set_feedtype('circular') 811 844 \end{verbatim} 812 845 … … 996 1029 \end{verbatim} 997 1030 998 999 1031 \section{Plotter} 1000 1032 … … 1135 1167 ASAP> plotter.save('myplot.ps') 1136 1168 ASAP> plotter.save('myplot.png', dpi=80) 1169 \end{verbatim} 1170 1171 \subsection{Plotter Customisation} 1172 1173 The plotter allows the user to change most properties such as text 1174 size and colour. The \cmd{commands} funcation and {\cmd help\ 1175 asapplotter} list all the possible commands that can be used with the 1176 plotter. 1177 1178 \commanddef{set\_colors}{Change the default colours used for line 1179 plotting. 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 1182 plotter cycles through the colours. Example:} {ASAP> 1183 plotter.set\_colors('red blue green')\\ ASAP> 1184 plotter.set\_colors(`\#0000 blue \#FF00FF')\\ } 1185 1186 \commanddef{set\_linestyles}{Change the line styles used for 1187 plots. 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 1221 The 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 1225 will 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 1229 coordinates. \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 1234 specifed \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 1236 while 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 1241 specifed \cmd{x} position (in world coordinates) between \cmd{ymin} 1242 and \cmd{ymax} (in relative coordinates, ie 0.0 is the left hand edge 1243 of 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}{ 1251 ASAP> 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}{ 1258 ASAP> 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.}{ 1263 ASAP>plotter.text(-10,7,"CO") 1264 } 1265 1266 1267 1268 These functions all take a set of \cmd{kwargs} commands. These can be 1269 used to set colour, linewidth fontsize etc. These are standard 1270 matplotlib 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 1281 Examples: 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) 1137 1285 \end{verbatim} 1138 1286 … … 1347 1495 \end{verbatim} 1348 1496 1497 \section{Specialised Processing} 1498 1499 \subsection{Multibeam MX mode} 1500 1501 MX mode is a specific observing approach with a multibeam where a 1502 single source is observed cycling through each beam. The scans when 1503 the beam is off source is used as a reference for the onsource 1504 scan. The function \cmd{mx\_quotient} is used to make a quotient 1505 spectrum from an MX cycle. This works averaging the ``off-source'' 1506 scans for each beam (either a median average or mean) and using this 1507 as a reference scan in a normal quotient (for each beam). The final 1508 spectrum for each beam is returned on a new scantable containing 1509 single scan (it the scan numbers are re-labelled to be the same). Note 1510 that the current version of \cmd{mx\_quotient} only handles a single 1511 MX cycle, ie if each beam has observed the source multiple times you 1512 will need to use the selector object multiple times to select a single 1513 MX cycle, run \cmd{mx\_quotient} for each cycle then merge the 1514 resulting scan tables back together. 1515 1516 Example: 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 1524 The function \cmd{average\_beam} averages multiple beam data 1525 together. This is need if MX mode has been used to make a long 1526 integration 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 1349 1536 \section{Scantable Mathematics} 1350 1537 … … 1639 1826 \index{Functions!summary}% 1640 1827 \begin{verbatim} 1641 ASAP> commands() 1828 1642 1829 [The scan container] 1643 1830 scantable - a container for integrations/scans … … 1646 1833 get_scan - gets a specific scan out of a scantable 1647 1834 (by name or number) 1835 drop_scan - drops a specific scan out of a scantable 1836 (by number) 1648 1837 set_selection - set a new subselection of the data 1649 1838 get_selection - get the current selection object … … 1669 1858 set_dirframe - set the frame for the direction on the sky 1670 1859 set_instrument - set the instrument name 1860 set_feedtype - set the feed type 1671 1861 get_fluxunit - get the brightness flux unit 1672 1862 set_fluxunit - set the brightness flux unit … … 1676 1866 get_restfreqs - get the current list of rest frequencies 1677 1867 set_restfreqs - set a list of rest frequencies 1678 flag_spectrum - flag data 1679 save - save the scantable to disk as either 'ASAP' 1680 or 'SDFITS' 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' 1681 1872 nbeam,nif,nchan,npol - the number of beams/IFs/Pols/Chans 1682 1873 nscan - the number of scans in the scantable … … 1687 1878 or a list of scans 1688 1879 average_pol - average the polarisations together. 1689 The dimension won't be reduced and 1690 all polarisations will contain the 1691 averaged spectrum. 1880 average_beam - average the beams together. 1692 1881 convert_pol - convert to a different polarisation type 1693 1882 auto_quotient - return the on/off quotient with 1694 automatic detection of the on/off scans 1695 (matched pairs and 1 off - n on) 1696 scale - return a scan scaled by a given factor 1697 add - return a scan with given value added 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 1698 1888 bin - return a scan with binned channels 1699 1889 resample - return a scan with resampled channels … … 1708 1898 units 1709 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 1710 1902 rotate_xyphase - rotate XY phase of cross correlation 1711 1903 rotate_linpolphase - rotate the phase of the complex … … 1716 1908 stddev - Determine the standard deviation of the current 1717 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 1718 1922 1719 1923 [Math] Mainly functions which operate on more than one scantable … … 1724 1928 simple_math - simple mathematical operations on two scantables, 1725 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 1726 1946 [Fitting] 1727 1947 fitter … … 1746 1966 called 'plotter' 1747 1967 plot - plot a scantable 1968 plot_lines - plot a linecatalog overlay 1748 1969 save - save the plot to a file ('png' ,'ps' or 'eps') 1749 1970 set_mode - set the state of the plotter, i.e. … … 1760 1981 set_linestyles - specify a set of linestyles to use if only 1761 1982 using one color 1983 set_font - set general font properties, e.g. 'family' 1984 set_histogram - plot in historam style 1762 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 1763 2007 1764 2008 [Reading files] … … 1780 2024 execfile - execute an asap script, e.g. execfile('myscript') 1781 2025 list_rcparameters - print out a list of possible values to be 1782 put into $HOME/.asaprc 2026 put into .asaprc 2027 rc - set rc parameters from within asap 1783 2028 mask_and,mask_or, 1784 2029 mask_not - boolean operations on masks created with 1785 2030 scantable.create_mask 1786 1787 Note:1788 How to use this with help:1789 # function 'summary'1790 [xxx] is just a category1791 Every 'sub-level' in this list should be replaces by a '.' Period when1792 using help1793 Example:1794 ASAP> help scantable # to get info on ths scantable1795 ASAP> help scantable.summary # to get help on the scantable's1796 ASAP> help average_time1797 1798 1799 2031 \end{verbatim} 1800 2032 … … 1808 2040 scantable or return new one} 1809 2041 1810 % plotting1811 1812 2042 \asaprc{useplotter}{{\bf True}/False}{Preload a default plotter} 1813 2043 … … 1827 2057 points plotted by a factor of nchan/1024} 1828 2058 1829 % default colours/linestyles 1830 %\asaprc{plotter.colours}{.}{.} 1831 %\asaprc{plotter.linestyles{.}{.} 2059 \asaprc{plotter.histogram}{True/{\bf False}}{Plot spectrum using 2060 histogram 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}}{} 1832 2069 1833 2070 % scantable … … 1841 2078 frequency frame to set when function scantable.set\_freqframe is 1842 2079 called or the data is imported} 2080 2081 \asaprc{scantable.verbosesummary}{True/{\bf False}}{Control the level 2082 of information printed by summary} 2083 2084 \asaprc{scantable.storage}{{\bf memory}/disk}{Storage of scantables in 2085 memory of via based disk tables} 1843 2086 1844 2087 \subsection{Installation}
Note:
See TracChangeset
for help on using the changeset viewer.