-
Notifications
You must be signed in to change notification settings - Fork 8
/
helpfile.py
2024 lines (1498 loc) · 78.6 KB
/
helpfile.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
## help texts for the commands
Help = {
##################################################################
# ms
##################################################################
"ms":
"""ms [msname [options]]
open MS/display current MS
If a MeaurementSet (MS) is opened, the code initializes all mappings and
analyzes the frequency setup. After having opened an MS you can proceed with
selecting data and operating on it.
The command supports the following options:
column=<data column name>
use column '<data column name>' to load data from. By
default the code auto-selects between 'DATA' and 'LAG_DATA'
spw_order=<reordering method>
using this option it is possible to set the spectral window
(re)ordering method. See the 'r'(ange) command for background.
Recognized values for <reordering method> are:
by_frequency re-order spectral windows by
frequency. this is the default
by_id do not reorder the spectral windows,
present them in the order they
appear in the spectral_window table
unique=t(rue)|f(alse)
override the global setting of 'unique'; influences
which meta data to read (see the help of the 'uniq'
command)
readflags=t(rue)|f(alse)
wether to read the FLAG+FLAG_ROW columns; see the 'show' command.
Default: True
Example:
> ms X3c1.ms unique=f spw_order=by_id column=alma_phase_corr
""",
##################################################################
# indexr
##################################################################
"indexr":
"""inde?xr
run indexr to create scan list of current MS
Attempt to mimic Classic AIPS task 'INDXR'. Note that both 'indexr' and 'indxr'
are recognized as command (*).
Sometimes it is handy to be able to select data from an MS by scan rather than
by time range or bluntly by source. After having run 'indexr' on the current
opened MS it is now possible to use scan indices to select a time-range and
source using the 'scan' command.
Inspect the list of scans using 'r scan' (see the 'r' command ('r'='range')) or
the 'listr' command. It was decided to not include the scan list in the default
'r' output because it can be quite a long list.
A scan, as defined by this software, is a time-continuous range where the same
(sub)array of telescopes (ARRAY_ID) is observing the same source (FIELD_ID).
Note that no attempt is being made yet to deal with observing using different
modes (FREQ_GROUP, via DATA_DESCRIPTION_ID and SPECTRAL_WINDOW) at the same
time. We assume that the same ARRAY_ID, at the same TIME cannot be observing at
more than one FREQ_GROUP (setup).
Should this be a problem, contact verkouter@jive.nl and request it. You might
get lucky.
(*) RossB pointed out to the author, significantly after the fact, that, in
fact, the aips task was called 'indxr' and not 'indexr', which is how the
command was implemented in jplotter. The 'e' is now optional. (April 2018)
""",
##################################################################
# scan
##################################################################
"scan":
"""scan [simple-syntax|complicated-syntax]
select or display scan selection
After having run 'indexr' it is possible to select entire scan(s) (using
'simple-syntax') or a specific part of a set of scan(s), based on their
properties using 'complex-syntax'.
==================== simple-syntax ===========================
Selecting whole scan(s) or scan ranges is simple; use the following syntax:
> scan [id|id-id|id-id:step]*
'id' is the scan number as printed by 'listr' or 'r scan'. Ranges are inclusive
of end points.
Example:
> scan 10-12 20 30-40:2
==================== complex-syntax ===========================
Sometimes it is useful to select only a part of a scan - say if you want to
time average some data but do not want to have to integrate the whole scan. Or
sometimes you want to select scans based on other properties than just their
number. For those applications the complex-syntax offers an SQL like selection
mechanism. Mostly useful in conjunction with 'solint' equal to none (see
'solint') command.
The general idea of the complex-syntax is to select a time range from a set of
scans, optionally satisfying some condition(s):
time-expression 'to' time-expression ['where' cond ['order by' ...] [limit ...]]
The "time 'to' time" expression will be evaluated for all scans satisfying the
conditions, to end up with a list of time ranges selected from the MS, if
succesful.
The first time-expression represents the start time of the desired data range
out of a matching scan, the second one, obviously, the end time.
If no 'where' conditions are specified ALL scans match.
time-expression
---------------
A 'time-expression' can be an arithmetic expression involving symbolic values
(explained later), absolute time stamps (less useful in this context but still
supported) and durations (very useful in this context).
Within a 'time-expression' the symbols 'start', 'mid' and 'end' are available
and they represent the respective values of the matching scans.
'time-expressions' are simple arithmetic expression, e.g.:
"start + 10" or "end - (2 * (end-start)/4)"
When dealing with time, numbers are not necessarily the best choice. For your
convenience, durations are supported. They allow the specification of offsets
in a more natural way. Durations are integer numbers followed by time units of
'd'(ays) 'h'(ours) 'm'(inutes) 's'(econds). Seconds have an optional sub-second
part.
"3d2h22m" for a duration of 3 days, 2 hours and 22 minutes
"0.2s"
The fields in a duration are optional but the order is important - a "higher"
unit of time MUST come before a lower one. So "3d10.2s" is valid but "10s2m"
isn't.
Combining the symbolic values and the durations it become very intuitive to
write e.g. the following:
start + 22.5s to end - 1m22s
to select this time range out of each matching scan. A more useful example
would be to e.g. select the 10 seconds in the middle of the desired scans:
mid - 5s to mid + 5s
Or to skip the first and last 10 seconds of a scan:
start + 10s to end - 10s
The 'where' clause
------------------
Each scan has a number of attributes, most of them self-explaining:
start the scan start time
end its end time
mid the mid-point ((end - start) / 2)
length the scan's length in seconds
t_int the integration time as listed in the MS (float)
scan_number the value of the SCAN_NUMBER column for this scan (int)
field_id the value of the FIELD_ID column for this scan (int)
field the name of the source (unmapped FIELD_ID value) (string)
array_id the value of the ARRAY_ID column for this scan (int)
In the 'where' clause you can select scans based on expressions involving these
attributes. Logic operators 'and' and/or 'or' and parenthesized expressions are
also supported:
> .... where t_int < 10 and (scan_number = 20 or scan_number = 30)
Besides the standard relational operators ("<", "<=", "=", ">" and ">=") the
system implements the 'in' and '~' operators.
The 'in' operator allows selecting scan where an attribute's value is contained
in a list of values:
<attribute> 'in' [ value {,value} ]
Example:
> .... where field_id in [0, 13, 20-30:2]
The '~' and 'like' operators are specifically meant for string-valued fields,
like the source name. The '~'/'like' means "string compare" rather than
arithmetically compare. The '~'/'like' operators support two types of operands,
<string> or <regex>. The <regex> allows you full regular expression support,
e.g. case insensitive mathing and partial pattern matching:
<attribute> '~' <string> | <regex>
<attribute> 'like' <string> | <regex>
<string> may be a (single)quoted string like 'string' or just characters.
The string match will be case sensitive. 'string' may contain the shell
wildcard characters '*' or '?' and their interpretation and effect is
identical to shell wild card matching/expansion.
When using wildcards be sure to use the quoted string "'pattern'" version
or else the expression parser will interpret the '*' as arithmetic
multiplication.
<regex> is specfied as sed(2) regex: "/pattern/{flags}". Currently the only
supported flag is "i" to make it a case-insensitive pattern.
Examples:
The following two conditions are _almost_ identical; the second version
will match all source names starting with 'm15' as well as those starting
with 'M15'. The first one only those starting with 'M15'.
> .... where field ~ 'M15*'
> .... where field ~ /m15.*/i
Full regular expression support:
> .... where field ~ /(m15|3c)[0-9]*/i
In all of the condition expressions a wider format of time formats is supported
than just duration (see previous section). When selecting based on time the
same time formats as under the 'time' command are feasible: full-fledged time
stamps and time stamps on days relative to the reference day of the experiment
(day 0 of the experiment).
> .... where start>14-jun-2013/12h43m0s
> .... where end <= 0/23h30m30s
""",
##################################################################
# uniq
##################################################################
"uniq":
"""uniq [01tf]
Analyze MS for unique meta data or just load the subtables.
A MeasurementSet carries a lot of meta data in subtables, like the ANTENNA
table for antenna information or the SPECTRAL_WINDOW table for frequency
information.
The presence of data in these subtables has no relation to having any rows in
the MAIN table referring to it; the ANTENNA table could contain the full list
of known stations whilst in the MAIN table only data from three stations is
present. This means that you could get the idea that there's a hundred antennae
worth of data in your MS, just looking at all the available antenna ID's. This
in turn could lead to unexpected effects when selecting data only to find out
that "your selection is empty".
jiveplot offers you a choice of which meta data to display/allow you to select
from (see the "r" command - the 'range' of selectables).
If 'uniq' is True, upon opening of the MS the MAIN table will be analyzed and
only the meta data for stations, frequencies, sources that are actually
referred will be loaded and allowed for selection.
If you would rather just load the full meta data tables, set 'uniq' to False
and all *possible* meta data is loaded and available for selection. Again -
wether there's actual data in (some of) the selection is pot luck.
On (very) large MSs (>10Million rows) the analysis will take a measurable
(though hopefully still short) time. This may be an argument to set 'uniq' to
False for quick opening of MSs.
Changing the setting will not take effect until a new MS is opened.
""",
##################################################################
# uniq
##################################################################
"taql":
"""taql [TaQL Query|none]
display/edit raw TaQL query
Without arguments shows the TaQL query representing the current selection.
Use the 'command' version with extreme caution - it will overwrite the actual
current TaQL query without altering the actual selection. It may be useful
though to be able just to run your own queries, as long as you know what to
expect (or what not to expect).
""",
##################################################################
# r
##################################################################
"r":
"""r (bl|src|time|fq|ch|p|sb|ant)*
display range of selectables in current MS
This command displays the meta-data found in the MS. Without arguments an
overview of all meta data is given, with the exception of baselines. With one
or more arguments the command displays the range of the indicated selectable
meta data.
Baselines can only be displayed if specifically asked for ("r bl"). Most
entries speak for themselves; think of the antenna list, the source list or the
time range of the experiment.
One entry is significantly less directly related to how information is stored
and labelled in the MS: the spectral/frequency information.
This is because the labelling the MS uses is very different from how scientists
think about their frequency setups. This code re-organizes the frequency
meta-data and presents it in a fashion that is more familiar (and more sensible
IMHO - author's note).
In the MS visibility data are labelled with (amongst others) a single integer,
called the DATA_DESCRIPTION_ID. The DATA_DESCRIPTION_ID in turn maps to a
*pair* of integer indices: a SPECTRAL_WINDOW_ID (a row number in the
SPECTRAL_WINDOW table) and a POLARIZATION_ID (a row number in the POLARIZATION
table).
A single row in the SPECTRAL_WINDOW table describes a channel/subband; an entity
having frequency, bandwidth and number-of-spectral channels. A row in the
POLARIZATION table contains a set of physical polarization products - effectively
describing the polarization combinations present in the visibility data matrix.
From this it can be seen that it is possible to have the same SPECTRAL_WINDOW
correlated with different polarization setups; there is no *unique* way of
mapping a DATA_DESCRIPTION_ID to a frequency subband; to do this correctly one
must _always_ also tell which POLARIZATION_ID is desired. Of course if there's
only one POLARIZATION_ID present in the MS (i.e. everything correlated with the
same settings) this simplifies things a bit but still, the system must know
about it.
The SPECTRAL_WINDOW table is just a collection of descriptions of subbands.
There is no sort order - neither implicit nor explicit. Therefore it is
impossible to assume that, say, SPECTRAL_WINDOW_ID #x maps to subband #x in the
experiment's frequency setup. Furthermore, if the experiment observed using
multiple frequency setups, there is no guarantee that the SPECTRAL_WINDOWS are
written in the order the setups were used or stored elsewhere.
The author thinks that to place this burden on the end-user is insane - any
decent front-end should read this meta-data and present it in a sane way. This
is what the system does to sanitize:
* read the complete spectral window table.
* for each subband, gather all the polarization ids the subband was
correlated with, by reading the DATA_DESCRIPTION table
* group spectral windows by their FREQ_GROUP - a number to group
SPECTRAL_WINDOWS together as one setup, configuration, mode, identified by
FREQ_GROUP
* sort the subbands for each FREQ_GROUP in increasing frequency, based on
the frequency of the first spectral channel in the subband and re-label them
as subband 0 - (n-1), with "n" being the number of subbands found for the
FREQ_GROUP
All the information is displayed in the range command like below. This output
was from a slightly instrumented MS - such that it has multiple frequency
groups (setups) and the subbands in one of the setups were correlated using two
polarization combinations.
Per frequency group it lists the frequency group id and name, followed by the
subbands. Per subband the essential properties are listed like the first
frequency in the subband, bandwidth and how many spectral channels. Following
that all polarization ids (Pxxx) that specific subband was correlated with are listed,
including what the physical products in polarization setup xxx were.
listFreqs: FREQID=0 [sess311.L512]
listFreqs: SB 0: 1626.4978MHz/8.0MHz 1024ch P0=RR,LL
listFreqs: SB 1: 1634.4900MHz/8.0MHz 1024ch P0=RR,LL
listFreqs: SB 2: 1642.4978MHz/8.0MHz 1024ch P0=RR,LL
listFreqs: SB 3: 1650.4900MHz/8.0MHz 1024ch P0=RR,LL
listFreqs: FREQID=1 [FakeGrp]
listFreqs: SB 0: 2626.4978MHz/8.0MHz 1024ch P0=RR,LL P1=RR,RL,LR,LL
listFreqs: SB 1: 2634.4900MHz/8.0MHz 1024ch P0=RR,LL P1=RR,RL,LR,LL
listFreqs: SB 2: 2642.4978MHz/8.0MHz 1024ch P0=RR,LL P1=RR,RL,LR,LL
These labels are used consistently throughout the plotting program to label or
designate "which subband do you mean". Plots are labelled using the FREQID,
SUBBAND and POLID indices, rather than those found in the MS. Where applicable
these indices are unmapped to their physical meanings (ie "polarization index 0"
will be written as "RR,LL".
""",
##################################################################
# pl
##################################################################
"pl":
"""pl [--force]
plot current selection with current plot-properties
The system tries very hard to detect if anything has changed or not before
starting time-consuming operations such as reading the data, regenerating the
plots or redrawing the plots. For example, if the window size is changed and
nothing else then the plot(s) do not get automatically redrawn. Use '--force'
to force the system to redraw anyway. Can be used in other cases where the
system did not pick up a change. In such a case, please create a github issue
and use '--force' in the meantime.""",
##################################################################
# pp
##################################################################
"pp":
"""pp
display current plot-properties
Properties are e.g. which plot type, if averaging is to be applied, if so
_which_ averaging (scalar, vector) is used etc.
""",
##################################################################
# lp
##################################################################
"lp":
"""lp
list all currently known plottypes""",
##################################################################
# y (not implemented?!)
##################################################################
"y":
"""y [<type>]
set/display Y-Axis type
<type> is one of:
[amp|pha|anp|re|im|reim|wt]""",
##################################################################
# x (not implemented?!)
##################################################################
"x":
"""x [<type>]
set/display X-Axis type
<type> is one of [time|chan]""",
"avt":
"""avt [<method>]
set/display time averaging method
<method> is one of: [none|scalar|vector|vectornorm]
vectornorm is like vector only the complex numbers are first normalized
before they are averaged. This is mostly useful for phase-versus-* plots.
""",
##################################################################
# avc
##################################################################
"avc":
"""avc [<method>]
set/display channel averaging method
<method> is one of: [none|scalar|vector|vectornorm]
vectornorm is like vector only the complex numbers are first normalized
before they are averaged. This is mostly useful for phase-versus-* plots.
""",
##################################################################
# solint
##################################################################
"solint":
"""solint [none|<time duration>]
set/display time averaging interval
When time averaging is requested (see 'avt') on 'quantity versus channel'
plots, the system must be told to integrate in which size 'time bin'.
In 'quantity versus time' plots, the time averaging setting 'avt' is ignored
but 'solint' is honoured if set. In this case the 'by time' data will be scalar
averaged into bins of length 'solint' seconds, thus potentially reducing the
amount of points to be plotted.
The averaged data will be time stamped with the midpoint of the 'solint'
interval.
The 'solint' duration can be specified in
d(ays), h(ours), m(inutes) and s(seconds)
and combinations thereof, honouring the hierarchy:
"smaller" units must follow "larger" units of time:
> solint 1.2s (set to 1.2 seconds)
> solint 1.2m (set to 1.2 minutes, i.e. 72.0s)
> solint 1h3.2s (set to 3603.2 seconds)
> solint 1s1m (invalid; m(inutes) is larger than s(econds))
Depending on the type of plots and value of 'solint', time averaging does
different things:
solint value = none / not set
-----------------------------
in 'quantity versus channel' plots:
This is a special case of time averaging. There is no pre-defined size of
time bin but all data of the selected time range(s) will be averaged
separately. See the 'time' and 'scan' commands on how to select multiple
time ranges.
E.g. if you selected whole scans then each scan will represent a time range
and thus all data of each individual scan will be averaged separately, to
produce a result per scan.
The same applies to time range(s) selected using the 'time' command -
all data from an individual time range will be averaged.
in 'quantity versus time' plots:
no effect; each data point found in the selected time range(s) (if any
selected) is plotted as-is
solint value > 0.1
-------------------
In both types of plots, data will be accumulated in bins of size 'solint'
seconds and averaged before being plotted. In 'quantity by channel' plots, the
data are averaged according to the 'avt' averaging method (vector or scalar).
In 'by time' plots the data are (implicitly) scalar averaged over the 'solint'
time interval.
Any useful application of time averaging has the solint greater than the
integration time (see 'r'(ange) command). Values < 1.0s are perfectly
legitimate but may defeat the purpose, unless the integration time of the data
is << 1.0s of course.
Note that no attempt will be made to deal with data that partially spills into
the previous or next time bin. The time stamp of an integration will be
truncated such that it will be an integer multiple of the 'solint' value,
disregarding fractions of the integration time falling outside the solint
interval.
This is mostly an efficiency measure, to allow plotting very large data sets.
For detailed inspection it's always better to zoom in to the area of interest
w/o time averaging.
The time averaging code currently implements a hard lower limit for solint of
0.1 seconds.
Of course this parameter's name pays homage to Classic AIPS.
""",
##################################################################
# nchav
##################################################################
"nchav":
"""nchav [none|<#-of-channels>]
set/display channel averaging interval
When channel averaging is requested (see 'avc') this parameter governs how the
selected channels are processed.
Either all selected channels are averaged down to one or they are binned in
groups of nchav channels. The table below summarizes what the effects of the
settings are.
nchav result
----- --------------------------------------------------------------
none all selected channels [even if they are a disjoint set] are
averaged down to one value. the channel label in the plots
will be '*' in stead of the channel number
>1 for each selected channel the system computes a destination
bin number using integer divide on "<channel #> / nchav".
Data will be averaged per destination bin. The channel label
will be "<bin number>*"
Example:
> avc scalar # turn on channel averaging for nchav to have effect
> ch 2:9 21:27 # select some channels
> nchav 4 # bin in groups of 4
Now the output will contain data sets with the following 'channel' labels
"0*" containing data from channel 2,3 (only two channels)
"1*" ,, 4..7 (full group of 4)
"2*" ,, 8,9 (two channels again)
"5*" ,, 21,22,23 (only three channels)
"6*" ,, 24..27 (guess what)
Of course this parameter's name also pays homage to Classic AIPS.
""",
##################################################################
# wt
##################################################################
"wt":
"""wt [double]
set/display weight threshold
Data with a weigth less than this threshold will be marked as flagged. When
averaging data in time and/or frequency these points do not count towards the
average.
See the 'show' command to control the (un)display of flagged data.
""",
##################################################################
# new
##################################################################
"new":
"""new [<type> t(rue)|f(alse)]*
set/display condition(s) on which new plots are created
<type> is one of [p|ch|bl|sb|src|time|all] or a comma-separated list of these,
for each of the seven interferometric axes:
p(olarization), ch(annel=frequency bin),
b(ase)l(ine), s(ub)b(and), s(ou)rc(e) and time.
The pseudo-type 'all' can be used to easily clear or set all values to the same
value.
Setting <type> to T(rue) means that for every unique value of <type> in the
current selection a new plot will be created. This allows exact grouping of the
selected data which is to be compared/investigated.
Example:
You want to compare the polarization response for different baselines per
subband:
> new all false p,sb true
means that a plot is started for each unique polarization, subband
combination and all baselines, sources, times and channels overplotted.
Suppose you want to compare the polarization response from different
baselines by subband. Then a 'new plot' setting of:
> new all false sb t
indicates that only for each unique subband a new plot is started. All
baselines, channels &cet will be overplotted.
Note: the '*' behind the syntax means that this sequence may be repeated any
number of times! i.e. with one single 'new' command you can set any number of
values.
Example:
> new p,bl true ch,sb,src,time false
would completely overwrite the current settings""",
##################################################################
# pge / nxt / prev / n / p
##################################################################
"pge":
"""(nxt|prev) [nr]
advance/go back [nr] pages of plots
The default is one page of plots""",
##################################################################
# nxy
##################################################################
"nxy":
"""n[x|y] [<int>]
set/display number of plots in x/y direction
*** important note ***
IF the number of generated plots is less than nx * ny, the system will maximize
the size of the plots itself discarding nx/ny settings!
""",
##################################################################
# sl
##################################################################
"sl":
"""sl
display current data selection""",
##################################################################
# ch
##################################################################
"ch":
"""ch [none|<range>|<singlechannel> ...]*
set/display current channel selection
Without arguments displays the current channel selection and returns.
Using the special selection 'none' you can disable channel selection.
For not-'none' selections each "ch" command starts with an empty channel
selection. Each (white-space separated!) argument is parsed and the indicated
channel(s) are added to the selection. A <range> of channels may be specified
as ch1:ch2[:inc]; which select all channels from 'ch1' up-to-and-including
'ch2' with increment inc, which defaults to 1.
For your convenience the following symbols have been defined:
[first|mid|last|all]
each of which will evaluate to the corresponding channel in the current MS.
arithmetic is supported, eg:
> ch 0.1*last:0.9*last
would select the inner 80% of the channels
> ch mid-2:mid+2
selects the five channels around the center
channel.
""",
##################################################################
# bl
##################################################################
"bl":
"""bl (none|[[+-][!]<blcode>]*)
set/display current baseline selection
Without arguments displays the current baseline selection and returns.
The special selection 'none' empties the baseline selection.
Each "bl" command first clears the selection. Then, the arguments ('selectors')
are processed from left-to-right, each selector modifying the selection up to
that point as indicated by the selector:
<blcode> => +<blcode> (no leading "+" or "-" defaults to "+")
+<blcode> = add baseline(s) matching <blcode> to selection
-<blcode> = remove .. .. .. from ..
<blcode> is a specification of which baseline(s) to in- or exclude and can
take several forms:
<blcode> the concatenation of two antenna names; also the reverse
combination will be matched; e.g. "+wbef" will add the baseline
Effelsberg to Westerbork, whether it is present as "WbEf" or
"EfWb"
<antenna name>
shorthand for "<antenna name>*" (wildcard '*' is valid but
superfluous) This form matches all baselines to <antenna>, e.g.
"-wb" means "remove all baselines to wb". The system looks for
baselines where "wb" is either the first or the second component
of the baseline
<antenna number>
an integer; select baseline(s) where either component is the
antenna with the ID <antenna number> from the ANTENNA subtable.
'<identifier>'
force 'identifier to be interpreted as string. Especially helpful in
case e.g. 'importfitsidi' has given the antennas names that
consists of numbers. E.g. "+'1'*" means "add baselines to the
antenna with the name "1" in stead of the id of 1.
(id1|id2|...|idN)
This is the 'alternatives' specification. Matches baselines
where either component matches id1 or id2 or ... or idN.
E.g. "-(wb|'12'|2)" removes baselines to antennas with names
"Wb", "12" and id 2.
auto|cross|none
Useful aliases that do what it sais on the tin. Irrespective of
the current data set they always select either the auto, cross
baselines present or no baselines at all (clear the selection).
Examples:
bl cross -wb +efwb
= select all cross baselines, remove all baselines to "Wb"
but add WbEf (or EfWb) back in to the selection
wb* = match all baselines to westerbork ("wb")
including baselines like "efwb"
jb(wb|ef) = match baselines "jbwb" and "jbef"
(jb|mc)(wb|nt) = matches four baselines
('12'|12)* = match baselines to antennas with name "12" as well with
antenna id 12
""",
##################################################################
# time
##################################################################
"time":
"""time [none | [t1 'to' [+]t2 [,t3]*]]
select/display time range(s) or single integration(s)
A lot can be done with this command - this help describes all three major
sections: the syntax, the time formats supported and the arithmetic/symbols that
can be used. The latter is extremely powerful, a definitive must-read!
The special selector 'none' can be used to clear the current time selection.
===== selection syntax =====
Multiple time ranges/instances in time can be selected; use a comma separated
list of time(range) selectors.
"t1 to [+]t2"
The syntax "t1 to [+]t2" selectes the time range from time stamp "t1" up to and
including time stamp "t2". If the first character of "t2" is a plus sign ("+")
the remainder of "t2" is interpreted as a duration, relative to t1.
"t3"
A single time stamp selects the integration with that time stamp. This may be
difficult as it requires the time in the MS to match very closely with the
parsed value.
===== time formats =====
A number of time-specifying formats is supported.
The general format of a time stamp is:
[date|dayoffset]time stamp
meaning that a time stamp must be prefixed with an (absolute) date or a relative
day, where day 0 is the date on which the experiment starts.
Each of the parts in the syntax potentially has various recognized formats:
* time stamp
hh:mm:ss[.sss] (1)
[*d[*h[*m[*[.*]s]]]] (2)
In (1) the hours, minutes and seconds are implicit, thus the colons are
mandatory. In format (2), however, any of the fields may be left out; the
"*" means a number, the character following the number indicates the unit.
Examples:
2:44:30.5 (i.e. 2h 44m 30.5s)
1h2.25s (i.e. 1h 0m 2.25s)
* date
yyyy/mm/dd[/T]
dd-(MON|mm)-yyyy[/T]
In order to keep the date parsing predictable (the underlying CASA code can
parse into unpredictable results!) the amount of supported date formats has
been limited to the above formats.
In both cases the year (yyyy) MUST be specified as a four digit quantity
(to disambiguate). "mm", "dd" are numeric fields (1 or 2 digits), "MON" is
the three-letter English month name.
The date code is followed by a time stamp (see previous section): the
date and time must be separated. Both the "/" as well as the ISO8601 "T"
separator are recognized.
Examples:
31-oct-2011/0:1:1 (yields: 31-Oct-2011/00:00:01.000)
2012/6/1T16h31m50.3s (yields: 01-Jun-2012/16:31:50.300)
* dayoffset
[-]nrdays/
By prefixing a time stamp with "<number>/" or "-<number>/" the time stamp is
placed on the date computed from adding the offset <number> to the start
date of the experiment.
Examples:
Suppose the start-time of the experiment is
31-Oct-2011/12:42:30.000
then:
-1/16:31:50.3 gives 30-Oct-2011/16:31:50.300
1/12h gives 01-Nov-2011/12:00:00.000
===== arithmetic =====
Ah, now it's getting interesting. In order to ease selecting time ranges in the
experiment some symbolic time stamps have been implemented as well the
possibility to do elementary arithmetic on time stamps.
The following pseudo time stamps have been defined:
$start $mid $end $length $t_int
When used, they evaluate to the corresponding value (in absolute date/time,
except for the duration and integration time) based on the current MS.
In order to help dealing with time, for arithmetic one can use 'durations' -
time spans. They look a lot like time stamps but they are not; they just
translate in "a number of seconds".
The support 'duration' format is:
[*d[*h[*m[*[.*]s]]]]
Which means, like with the time stamp before, any of the fields may be
omitted but a 'larger' unit of time MUST precede a 'smaller' one.
Below are a number of examples of actual time stamp agnostic selections, that
will select the indicated time range of the experiment, irrespective of the
_actual_ time stamps in the experiment.
# select time range from start -> end (the whole experiment)
> time $start to $end
# select time range from start -> start + length (id.)
> time $start to + $length
# select the second half of the experiment
> time $start + ($length/2) to $end
# the third hour-and-a-half:
> time $start + 2*1h30m to +1h30m
# the last hour of the experiment:
> time $end - 1h to $end
# do some arithmetic using the integration time:
# select 10 integrations after skipping the first 5:
> time $start + 5 * $t_int to + 10 * $t_int
# Involving relative day time stamps - select
# from 23h00m00s on day 0 of the experiment to 01h00m00s
# on the next day of the experiment.
> time 0/23h to 1/1h
# of course you can mix + match
> time $start to 0/23h30m
> time 1/1h to $end - 1h
# comma separated statements select multiple time ranges.
# here we select two 1 minute time ranges, 1 minute apart.
# (this time we show the output on the terminal)
> time $start to +1m , $start + 2m to +1m
time: 31-Oct-2011/12:42:31.250 -> 31-Oct-2011/12:43:31.250
time: 31-Oct-2011/12:44:31.250 -> 31-Oct-2011/12:45:31.250
# note that overlapping time ranges will be automatically joined!
> time $start to +4m , $start + 3m to +3m
time: 31-Oct-2011/12:42:31.250 -> 31-Oct-2011/12:48:31.250
Anyway, you get the idea. You'll find lots of caveats, constructions that won't
be recognized or give very weird time values. Still, you should be able to make
good use of this feature, as can be seen from the examples.
Stuff that certainly don't work:
> time [-]1/$start
because the relative day offset expects a time stamp to follow, not a full
fledged date-and-time.
However, this can trivially be rewritten to:
> time $start [+-] 1d
which *does* work and gives the expected date+time stamp.""",
##################################################################
# s
##################################################################
"s":
"""sb [<range> <single sp.window>]
set/display current spectralwindow (subband) selection.
<range> may be specified as spw1:spw2[:inc] selecting
spectral windows spw1->spw2 with increment inc (defaults
to 1). The word all would select all spectral windows""",
##################################################################
# p
##################################################################
"p":
"""p [<polcombi> <polcombi>... ]:
set/display current polarization selection
<polcombi> may be specified as two out of [xylr*] or the
string all. eg: l* would select ll lr ** would select
all polarizations note: for your pleasure the following
symbolic selections have been added:
[all|parallel|cross]""",
##################################################################
# src
##################################################################
"src":
"""src [none|[[-+][!]<source>]*]:
set/display current source selection
Without arguments displays the current source selection and returns.
The special selector 'none' removes the current source selection.
Each "src" command first clears the selection. Then, the arguments ('selectors')
are processed from left-to-right, each selector modifying the current selection
as indicated by the selector:
<source> = +<source> (no "+-" specified defaults to "+")