Changeset 538
- Timestamp:
- 03/08/05 11:51:55 (20 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/cookbook.tex
r537 r538 1 1 %% TODO 2 %% Help doco3 %% .asaprc4 2 %% Intro 5 %% Plotter options - pol etc6 3 %% Fit saving 7 4 … … 54 51 \end{verbatim} 55 52 56 This starts the asap. To quit, you need to type 53 This starts the asap. To quit, you need to type \verb+^+-d (control-d). 57 54 58 55 \section{Interface} … … 99 96 some way or change global properties of the object. In this document 100 97 member functions will be referred to simply as functions. From the 101 command line, the user can ex cute these functions using the syntax:98 command line, the user can execute these functions using the syntax: 102 99 \begin{verbatim} 103 100 ASAP> out = object.function(arguments) … … 105 102 106 103 Where \cmd{out} is the name of the returned variable (could be a new 107 scantable object, or a vector of data, or a status ret rn), \cmd{object} is the104 scantable object, or a vector of data, or a status return), \cmd{object} is the 108 105 object variable name (set by the user), \cmd{function} is the name of 109 106 the member function and \cmd{arguments} is a list of arguments to the … … 123 120 124 121 Some functions do not make sense to be implemented as member 125 functions, typically fu ctions which operate on more than one scantable122 functions, typically functions which operate on more than one scantable 126 123 (e.g. time averaging of many scans). These functions will always be 127 refer ed to as global functions.128 129 \subsection{Interactive enviro ment}124 referred to as global functions. 125 126 \subsection{Interactive environment} 130 127 131 128 ipython has a number of useful interactive features and a few things to be aware … … 136 133 Tab completion is enabled for all function names. If you type the 137 134 first few letters of a function name, then type <TAB> the function 138 name will be auto completed if it is un-ambig ious, or a list of135 name will be auto completed if it is un-ambiguous, or a list of 139 136 possibilities will be given. Auto-completion works for the user 140 137 object names as well as function names. It does not work for filenames, … … 169 166 \subsection{Help} 170 167 171 Help me... 168 ASAP has built in help for all functions. To get a list of functions type: 169 170 \begin{verbatim} 171 ASAP> commands 172 \end{verbatim} 173 174 To get help on specific functions, the built in help needs to be given 175 the object and function name. E.g. 176 177 \begin{verbatim} 178 ASAP> help scantable.get_scan 179 ASAP> help scantable.stats 180 ASAP> help plotter.plot 181 ASAP> help fitter.plot 182 183 ASAP> scans = scantable('mydata.asap') 184 ASAP> help scans.get_scan # Same as above 185 186 ASAP> help average_time # Global functions just need their name 187 188 \end{verbatim} 189 190 Note that if you just type \cmd{help} the internal ipython help is 191 invoked, which is probably {\em not} what you want. Type \verb+^+-d 192 (control-d) to escape from this. 172 193 173 194 \subsection{.asaprc} 174 195 196 ASAP use a \cmd{.asaprc} file to control the users preferences of 197 default values for various functions arguments. This includes the 198 defaults for aguments such as \cmd{insitu}, scantable \cmd{freqframe} 199 and the plotters \cmd{set\_mode} values. The help on individual 200 functons says which agruments can be set default values from the 201 \cmd{.asaprc} file. To get a sample contents for the \cmd{.asaprc} 202 file use then command \cmd{list\_rcparameters}. 203 204 Common values include: 205 \begin{verbatim} 206 # apply operations on the input scantable or return new one 207 insitu : False 208 209 # default ouput format when saving scantable 210 scantable.save : 'ASAP' 211 212 213 # default frequency frame to set when function 214 # scantable.set_freqframe is called 215 scantable.freqframe : 'LSRK' 216 217 # auto averaging on read 218 scantable.autoaverage : True 219 \end{verbatim} 175 220 176 221 \section{Scantables} … … 213 258 214 259 Two important columns are those that describe the frequency setup. We mention 215 them explicitly here because you need to be able to under tand the presentation260 them explicitly here because you need to be able to understand the presentation 216 261 of the frequency information and possibly how to manipulate it. 217 262 … … 276 321 \end{verbatim} 277 322 278 279 280 323 \subsection{State} 281 282 324 283 325 Each scantable contains "state"; these are properties applying to all … … 285 327 286 328 Examples are the selection of beam, IF and polarisation, spectral unit 287 (e.g. $km/s$) frequency reference frame (e.g. BARY) and velocity doppler329 (e.g. $km/s$) frequency reference frame (e.g. BARY) and velocity Doppler 288 330 type (e.g. RADIO). 289 290 291 331 292 332 \subsubsection{Units, Doppler and Frequency Reference Frame} … … 306 346 can be computed in any of these units), plotting and mask creation. 307 347 308 The velocity doppler can be changed with the \cmd{set\_doppler}348 The velocity Doppler can be changed with the \cmd{set\_doppler} 309 349 function, and the frequency reference frame can be changed with the 310 350 \cmd{set\_freqframe} function. … … 335 375 336 376 \begin{verbatim} 337 ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0) # Selected for specified source/IF 338 ASAP> scans.set_restfreqs(freqs=1.667359e9) # Selected for all sources and IFs 377 # Select for specified source/IF 378 ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0) 379 380 # Select for all sources and IFs 381 ASAP> scans.set_restfreqs(freqs=1.667359e9) 339 382 \end{verbatim} 340 383 … … 348 391 349 392 \begin{verbatim} 350 ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0) # Selected for specified source/IF 351 ASAP> scans.set_restfreqs(freqs=1.667359e9) # Selected for all sources and IFs 393 # Select for specified source/IF 394 ASAP> scans.set_restfreqs(freqs=1.667359e9, source='NGC253', theif=0) 395 396 # Select for all sources and IFs 397 ASAP> scans.set_restfreqs(freqs=1.667359e9) 352 398 \end{verbatim} 353 399 … … 390 436 Most functions work on all rows of a scan table. Exceptions are the 391 437 fitter and plotter. If you wish to only operate on a selected set of 392 scantable rows, us w the \cmd{get_scan} function to copy the rows into438 scantable rows, use the \cmd{get\_scan} function to copy the rows into 393 439 a new scantable. 394 440 … … 501 547 502 548 In the following section, a simple data reduction to form a quotient 503 spectrum of a single source is followed. Variations of this approach 504 are given later. 549 spectrum of a single source is followed. In the following it has been 550 assume that the \cmd{.asaprc} file has been used to set \cmd{insitu} 551 to a default value or \cmd{True}. 505 552 506 553 %\subsection{Editing} … … 770 817 ASAP> ss = scans.get_scan(10) # Get the 11th scan (zero based) 771 818 ASAP> ss = scans.get_scan(range(10)) # Get the first 10 scans 819 ASAP> ss = scans.get_scan(range(10,20)) # Get the next 10 scans 772 820 ASAP> ss = scans.get_scan([2,4,6,8,10]) # Get a selection of scans 773 821 … … 839 887 840 888 841 842 889 \section{Plotter} 843 890 … … 847 894 ``plotter''. This would normally be used for standard plotting. 848 895 849 The plotter, optionally, will run in a mul ipanel mode and contain896 The plotter, optionally, will run in a multipanel mode and contain 850 897 multiple plots per panel. The user must tell the plotter how they want 851 898 the data distributed. This is done using the set\_mode function. The 852 899 default can be set in the users {\tt .asaprc} file. The units (and frame 853 etc) of the ab cissa will be whatever has previously been set by854 set\_unit, set\_freqframeetc.900 etc) of the abscissa will be whatever has previously been set by 901 \cmd{set\_unit}, \cmd{set\_freqframe} etc. 855 902 856 903 Typical plotter usage would be: … … 865 912 scanrow in a separate panel. 866 913 867 Other poss bilities include:914 Other possibilities include: 868 915 869 916 \begin{verbatim} 870 917 # Plot multiple IFs per panel 871 918 ASAP> plotter.set_mode(stacking='i',panelling='t') 872 more???? 919 920 # Plot multiple beams per panel 921 ASAP> plotter.set_mode(stacking='b',panelling='t') 922 923 # Plot one IF per panel, time stacked 924 ASAP> plotter.set_mode('t', 'i') 925 926 # Plot each scan in a seperate panel 927 ASAP> plotter.set_mode('t', 's') 928 929 \end{verbatim} 930 931 \subsection{Plot Selection} 932 \label{sec:plotter_cursor} 933 934 The plotter can plot up to 25 panels and stacked spectra per 935 panel. If you have data larger than this (or for your own sanity) you 936 need to select a subset of this data. This is particularly true for 937 multibeam or multi IF data. The plotter \cmd{set\_cursor} function is 938 used to select a subset of the data. The arguments \cmd{row}, 939 \cmd{beam} and \cmd{IF} all accept a vector if indices corresponding 940 to tow, beam or IF selection. Only the selected data will be plotted. 941 So select on polarisation, see section~\ref{sec:polplot}. 942 943 Examples: 944 945 \begin{verbatim} 946 # Select second IF 947 ASAP> plotter.set_cursor(IF=[1]) 948 949 # Select first 4 beams 950 ASAP> plotter.set_cursor(beam=[0,1,2,3]) 951 952 # Select a few rows 953 ASAP> plotter.set_cursor(row=[2,4,6,10]) 954 955 # Multiple selection 956 ASAP> plotter.set_cursor(IF=[1], beam=[0,2], row=range(10)) 873 957 \end{verbatim} 874 958 … … 900 984 901 985 \end{itemize} 986 987 \subsection{Plot selection} 902 988 903 989 \subsection{Other control} … … 989 1075 # Plot the first and third component plus the model sum 990 1076 ASAP> f.plot(components=[-1,0,2]) # -1 means the compoment sum 991 992 1077 \end{verbatim} 993 1078 … … 998 1083 cases will be added on an as needed basic. 999 1084 1000 But how do you actually do it... 1085 Conversions of linears to Stokes or Circular polarisations are done 1086 ``on-the-fly''. Leakage cannot be corrected for nor are there routines 1087 able to calibrate position angle offsets. 1088 1089 \subsection{Simple Calibration} 1090 1091 {\em Currently the receiver position angle is not stored in the rpfits 1092 file. This serverly hampers correct handling of polarimetry.} 1093 1094 It is possible that there is a phase offset between polarisation which 1095 will effect the phase of the cross polarisation 1096 correlation. \cmd{rotate\_xyphase} can be used to correct for this 1097 error. The user must know how to determine the size of the phase 1098 offset. 1099 1100 \begin{verbatim} 1101 ASAP> scans.rotate_xyphase(10.5) 1102 \end{verbatim} 1103 1104 Note that if this function is run twice, the sum of the two values is 1105 applied. 1106 1107 A correction for the receiver paralactic angle may need to be made, 1108 either because of how it is mounted or if paralactifiying had to track 1109 at 90 degrees rather than 0. Use \cmd{rotate\_linpolphase} to correct 1110 the position angle. Running this function twice results in the sum of 1111 the corrections being applied. 1112 1113 \begin{verbatim} 1114 ASAP> scans.rotate_linpolphase(-20) # Correct for receiver mounting 1115 1116 # Receiver was tracking 90 degrees rather than 0 1117 ASAP> scans.rotate_linpolphase(90) 1118 \end{verbatim} 1119 1120 \subsection{Plotting} 1121 \label{sec:polplot} 1122 1123 To plot stokes values, the plotter \cmd{set\_cursor} function should 1124 be called first using the \cmd{pol} argument. The values which can be 1125 plotted include a selection of [I,Q,U,V], [I, Plinear, Pangle, V] or 1126 [XX, YY, Real(XY), Imaginary(XY)]. (Plinear and Pangle are the 1127 percentage and position angle of linear polarisation). Conversion to 1128 circular polarisations are currently not available. 1129 1130 Example: 1131 1132 \begin{verbatim} 1133 ASAP> plotter.set_cursor(pol=[``I'',''Q''] 1134 ASAP> plotter.set_cursor(pol=[``XX'',''YY''] 1135 ASAP> plotter.set_cursor(pol=[``I'',''Plinear''] 1136 \end{verbatim} 1137 1138 Row, beam and IF selection are also available in \cmd{set\_cursor} as 1139 describe in section~\ref{sec:plotter_cursor}. 1140 1141 \subsection{Saving} 1142 1143 When saving data using the \cmd{save} function, the \cmd{stokes} 1144 argument can be used to save the data as Stoke values when saving in 1145 FITS format. 1146 1147 Example: 1148 1149 \begin{verbatim} 1150 ASAP> scans.save('myscan.sdfits', 'SDFITS', stokes=True) 1151 \end{verbatim} 1001 1152 1002 1153 \section{Function Summary} … … 1113 1264 range(3) = [0,1,2], range(2,5) = [2,3,4] 1114 1265 help - print help for one of the listed functions 1115 execfile - execute an asap script, e.g. execfile('myscript') list_rcparameters - print out a list of possible values to be 1116 put into $HOME/.asaprc 1266 execfile - execute an asap script, e.g. execfile('myscript') 1267 list_rcparameters - print out a list of possible values to be 1268 put into \$HOME/.asaprc 1117 1269 mask_and,mask_or, 1118 1270 mask_not - boolean operations on masks created with … … 1128 1280 ASAP> help scantable.summary # to get help on the scantable's 1129 1281 ASAP> help average_time 1130 1131 1132 \end{verbatim} 1133 1134 \section{Scripting} 1135 1136 Malte to add something 1282 \end{verbatim} 1283 1284 %\section{Scripting} 1285 1286 %Malte to add something 1137 1287 1138 1288 \section{Appendix} 1139 1289 1140 1290 \subsection{Installation} 1141 1142 1291 1143 1292 ASAP depends on a number of third-party libraries which you must
Note:
See TracChangeset
for help on using the changeset viewer.