casacore
MSSelector.h
Go to the documentation of this file.
1 //# MSSelector.h: this defines MSSelector, which specifies MS selections
2 //# Copyright (C) 1997,1998,1999,2000,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 #ifndef MS_MSSELECTOR_H
30 #define MS_MSSELECTOR_H
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/Vector.h>
34 #include <casacore/casa/Arrays/Slice.h>
35 #include <casacore/casa/Arrays/Slicer.h>
36 #include <casacore/ms/MeasurementSets/MeasurementSet.h>
37 #include <casacore/ms/MeasurementSets/StokesConverter.h>
38 #include <casacore/ms/MSOper/MSDerivedValues.h>
39 #include <casacore/ms/MSSel/MSSelectionKeywords.h>
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 template <class T> class ArrayColumn;
44 class Record;
45 class MSIter;
46 
47 // <summary>
48 // MSSelector specifies selections on a MeasurementSet
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
54 // </reviewed>
55 
56 // <prerequisite>
57 // <li> MeasurementSet
58 // <li> Record
59 // </prerequisite>
60 //
61 // <etymology>
62 // MSSelector's main function is selection of data from a MeasurementSet
63 // </etymology>
64 //
65 // <synopsis>
66 // This class is used to select and retrieve data from a MeasurementSet.
67 // It allows selections on e.g., time, field, spectral window (all row based),
68 // but also on channel and polarization (within a row). It can optionally
69 // do polarization conversion, spectral averaging and time averaging on the
70 // data retrieved and allows modified data to be written back to the Table.
71 // This class also provides the DO interface to the MS Iterator.
72 // The ms DO uses this class to allow these operations to be done from glish.
73 //
74 // <example> <srcblock>
75 // MSSelector msSelector(myMS);
76 // // select data desc Id 1
77 // msSelector.initSelection(1);
78 // Vector<String> items(3);
79 // // fill in some fields
80 // items(0)="field_id";
81 // items(1)="time";
82 // items(2)="num_chan";
83 // // get the range of values for the items specified
84 // MSRange msRange(msSelector.selectedTable(),msSelector.spectralWindow());
85 // Record range=msRange.range(items);
86 // //.. change the ranges as needed
87 // // now select with the new range
88 // msSelector.select(range);
89 // Int nchan=10, start=3, width=1, incr=2;
90 // msSelector.selectChannel(nchan,start,width,incr)
91 // // get out some data
92 // Vector<String> dataItems(3);
93 // dataItems(0)="data";
94 // dataItems(1)="antenna1";
95 // dataItems(2)="antenna2";
96 // Record dataRec=msSelector.getData(items);
97 // </srcblock></example>
98 // </synopsis>
99 //
100 // <motivation>
101 // Selection from an MS is needed in various places. It makes sense to
102 // provide a uniform interface for MS selection.
103 // </motivation>
104 //
105 // <thrown>
106 // <li>
107 // </thrown>
108 //
109 // <todo asof="1998/12/11">
110 // <li> provide access to all other columns in the MS?
111 // </todo>
112 
114 {
115  friend class MSRange;
116 
117 public:
118 
120 
121  // construct from an MS, the MS will supply the range of the various
122  // parameters that can be selected on.
123  explicit MSSelector(MeasurementSet& ms);
124 
125  // Copy constructor, this will initialize the MS with other's MS
126  MSSelector(const MSSelector& other);
127 
128  // Assignment, this will initialize the MS with other's MS
130 
132 
133  // Change or Set the MS this MSSelector refers to.
135 
136  // initialize the selection by specifying, optionally,
137  // the DATA_DESC_IDs.
138  // If you don't specify the dataDescIds and the data shape is constant
139  // all data is selected, if the shape does change, only the first
140  // dataDescId is selected. If you specify a number of dataDescIds
141  // and they all have the same shape, they are all selected, otherwise
142  // only the first is selected. The function returns false if
143  // the selection was limited due to changing data shape.
144  // Use the reset argument to return to the completely unselected ms.
145  Bool initSelection(const Vector<Int>& dataDescIds, Bool reset=False);
146 
147  // As above without the data desc id argument
149 
150  // Return the data desc IDs selected
151  Vector<Int> dataDescId() const;
152 
153  // Set the mapping from input channels in the DATA column to
154  // output channels. nChan is the number of output channels,
155  // start is the first channel to use, width specifies how wide a
156  // block of channels to average, increment specifies the start of
157  // the next block relative to the start of the current block.
158  // Note: averaging uncalibrated data should be avoided (no bandpass applied)
159  Bool selectChannel(Int nChan, Int start, Int width, Int incr);
160 
161  // Specify the output polarization.
162  // Missing input polarizations are assumed to be zero.
163  // This selection/conversion assumes that parallactic angle rotation
164  // is taken care of elsewhere (i.e., results may only be correct for
165  // CORRECTED_DATA and MODEL_DATA conversions, not for the observed DATA)
167 
168  // Select the MS based on the selections present in the input record.
169  // The format of this record is the same as that returned by range.
170  // Not all possible items can be selected on, some are quietly ignored.
171  // Correct for one-based indexing if oneBased is True.
172  Bool select(const Record& items, Bool oneBased=False);
173 
174  // Select the MS based on the TaQL selection string
175  Bool select(const String& msSelect);
176 
177  // Return the data for the items requested, all returned values
178  // will be arrays, the last dimension of these is the table row number.
179  // The data arrays are normally 3D with axes: polarization, frequency, row.
180  // If ifrAxis is set to True, the data arrays returned will be 4D, with
181  // the data being split out along an extra interferometer axis, the
182  // axes will be: polarization, frequency, interferometer and time.
183  // Missing interferometers will be marked flagged.
184  // The order of the interferometers is that specified by the last
185  // select call.
186  // Add a (flagged) gap in the data at every antenna1 change if ifrAxisGap>0.
187  // Use inc > 1 to return data from every inc'th row.
188  // Use average=True to vector average the data along the row or time axis
189  // taking the weights column into account (use selectChannel to average
190  // channels together as well). Note that different interferometers will be
191  // averaged together if ifrAxis is False.
192  // Correct for one-based indexing if oneBased is True.
193  Record getData(const Vector<String>& items, Bool ifrAxis,
194  Int ifrAxisGap=0, Int inc=1,
195  Bool average=False, Bool oneBased=False);
196 
197  // Put the data for the items provided. Note that only fields corresponding
198  // to actual table columns can be put (i.e., no AMPLITUDEs, IFR_NUMBERs etc)
199  // The data will need to have the correct shape for the column and a last
200  // dimension matching the number of selected rows (or last two dimensions
201  // matching times and interferometers, for data retrieved with ifraxis=T)
202  // Channel selection is supported, but the width parameter has to be 1.
203  Bool putData(const Record& items);
204 
205  // Set up an iterator, iterating over the specified columns, with
206  // optional time interval and maximum number of rows to return at once
207  // (the default of zero returns all rows). To keep MSIter from adding
208  // the default sort columns, specify addDefaultSortColumns=False
209  Bool iterInit(const Vector<String>& columns,
210  Double interval, rownr_t maxRows=0,
211  Bool addDefaultSortColumns=True);
212 
213  // Step the iterator, sets the selection to the current table iteration.
214  // Returns false if there is no more data
215  // and sets the selection back to the state before iteration started.
217 
218  // (Re)Set the iterator to the first iteration, call this after iterInit.
220 
221  // End the iteration (before reaching the last iteration)
222  // and set the selection back to the state before iteration started.
224 
225  // Number of rows in selected table
226  rownr_t nrow() const;
227 
228  // Return the selected table
229  Table selectedTable() const;
230 
231  // Return the selection status of the table
232  Bool selected() const;
233 
234 protected:
235  // average and convert data
236  void getAveragedData(Array<Complex>& avData, const Array<Bool>& flag,
237  const ArrayColumn<Complex>& col) const;
238 
239  // average and convert float data
240  void getAveragedData(Array<Float>& avData, const Array<Bool>& flag,
241  const ArrayColumn<Float>& col) const;
242 
243  // average and convert data, with row Slicer
244  void getAveragedData(Array<Complex>& avData, const Array<Bool>& flag,
245  const ArrayColumn<Complex>& col,
246  const Slicer & rowSlicer) const;
247 
248  // average and convert float data, with row Slicer
249  void getAveragedData(Array<Float>& avData, const Array<Bool>& flag,
250  const ArrayColumn<Float>& col,
251  const Slicer & rowSlicer) const;
252 
253  // "average" flag, at present all output which has a flagged input is flagged
255  const ArrayColumn<Bool>& col) const;
256 
257  // "average" flag, at present all output which has a flagged input is flagged,
258  // with row Slicer
260  const ArrayColumn<Bool>& col,
261  const Slicer& rowSlicer) const;
262 
263  // "unaverage" flag, distribute the flags back to the channels that went
264  // into the average
265  void putAveragedFlag(const Array<Bool>& avFlag,
266  ArrayColumn<Bool>& col);
267 
268  // get the weight, set sigma=True when retrieving sigma's
270  Bool sigma=False) const;
271 
272  // make the data slicer, pass in the first and the number of correlations
273  // to select
274  void makeSlicer(Int start, Int nCorr) const;
275 
276  // reorder from 2d to 1d (removing ifr axis)
277  void reorderFlagRow(Array<Bool>& flagRow);
278 
279  // reorder from 2d to 1d (removing ifr axis)
281 
282  // time average the input data, return new flags
283  void timeAverage(Array<Bool>& dataFlags, Array<Complex>& data,
284  const Array<Bool>& flags, const Array<Float>& weights);
285 
286  // check if the data description selection has been done & do default
287  // selection if not. Return False if the selection fails.
289 
290 private:
291  // The function types
293 
294  // The data types
296 
297  MeasurementSet ms_p; // the original ms
298  MeasurementSet selms_p; // the selected ms
299  MeasurementSet savems_p; // the saved preselection
307  mutable Slicer slicer_p;
317  Matrix<Int64> rowIndex_p; // mapping of rows to time and ifr slots
318  RowNumbers selRows_p; // range of rows from selms_p returned by getData
319  rownr_t startRow_p, maxRow_p; // start and length of range of rows
321 
322 };
323 inline rownr_t MSSelector::nrow() const { return selms_p.nrow();}
325 inline Table MSSelector::selectedTable() const {return selms_p;}
326 inline Bool MSSelector::selected() const {return initSel_p;}
327 
328 
329 } //# NAMESPACE CASACORE - END
330 
331 #endif
332 
An iterator class for MeasurementSets.
Definition: MSIter.h:162
void reorderFlagRow(Array< Bool > &flagRow)
reorder from 2d to 1d (removing ifr axis)
void getAveragedData(Array< Complex > &avData, const Array< Bool > &flag, const ArrayColumn< Complex > &col) const
average and convert data
Array< Bool > getAveragedFlag(Array< Bool > &avFlag, const ArrayColumn< Bool > &col) const
"average" flag, at present all output which has a flagged input is flagged
rownr_t nrow() const
Number of rows in selected table.
Definition: MSSelector.h:323
Matrix< Double > bandwidth_p
Definition: MSSelector.h:315
MSSelector & operator=(const MSSelector &other)
Assignment, this will initialize the MS with other's MS.
Bool checkSelection()
check if the data description selection has been done & do default selection if not.
void getAveragedData(Array< Complex > &avData, const Array< Bool > &flag, const ArrayColumn< Complex > &col, const Slicer &rowSlicer) const
average and convert data, with row Slicer
void timeAverage(Array< Bool > &dataFlags, Array< Complex > &data, const Array< Bool > &flags, const Array< Float > &weights)
time average the input data, return new flags
Array< Float > getWeight(const ArrayColumn< Float > &wtCol, Bool sigma=False) const
get the weight, set sigma=True when retrieving sigma's
Bool putData(const Record &items)
Put the data for the items provided.
Vector< Int > ifrSelection_p
Definition: MSSelector.h:314
MSDerivedValues msd_p
Definition: MSSelector.h:316
Vector< String > polSelection_p
Definition: MSSelector.h:313
Bool selectChannel(Int nChan, Int start, Int width, Int incr)
Set the mapping from input channels in the DATA column to output channels.
Vector< Int > dataDescId() const
Return the data desc IDs selected
Definition: MSSelector.h:324
void makeSlicer(Int start, Int nCorr) const
make the data slicer, pass in the first and the number of correlations to select
Vector< Int > ifrAxis_p
Definition: MSSelector.h:314
void reorderWeight(Array< Float > &weight)
reorder from 2d to 1d (removing ifr axis)
Bool iterNext()
Step the iterator, sets the selection to the current table iteration.
Vector< uInt > polId_p
Definition: MSSelector.h:303
Vector< Int > polIndex_p
Definition: MSSelector.h:309
Bool selected() const
Return the selection status of the table.
Definition: MSSelector.h:326
Record getData(const Vector< String > &items, Bool ifrAxis, Int ifrAxisGap=0, Int inc=1, Bool average=False, Bool oneBased=False)
Return the data for the items requested, all returned values will be arrays, the last dimension of th...
Bool iterOrigin()
(Re)Set the iterator to the first iteration, call this after iterInit.
void getAveragedData(Array< Float > &avData, const Array< Bool > &flag, const ArrayColumn< Float > &col, const Slicer &rowSlicer) const
average and convert float data, with row Slicer
Bool select(const String &msSelect)
Select the MS based on the TaQL selection string.
Bool selectPolarization(const Vector< String > &wantedPol)
Specify the output polarization.
Bool iterInit(const Vector< String > &columns, Double interval, rownr_t maxRows=0, Bool addDefaultSortColumns=True)
Set up an iterator, iterating over the specified columns, with optional time interval and maximum num...
void putAveragedFlag(const Array< Bool > &avFlag, ArrayColumn< Bool > &col)
"unaverage" flag, distribute the flags back to the channels that went into the average
MeasurementSet ms_p
Definition: MSSelector.h:297
Vector< Int > dataDescId_p
Definition: MSSelector.h:302
Vector< Int > lastDataDescId_p
Definition: MSSelector.h:302
RowNumbers selRows_p
Definition: MSSelector.h:318
void setMS(MeasurementSet &ms)
Change or Set the MS this MSSelector refers to.
MeasurementSet selms_p
Definition: MSSelector.h:298
Vector< uInt > spwId_p
Definition: MSSelector.h:303
StokesConverter stokesConverter_p
Definition: MSSelector.h:312
Array< Bool > getAveragedFlag(Array< Bool > &avFlag, const ArrayColumn< Bool > &col, const Slicer &rowSlicer) const
"average" flag, at present all output which has a flagged input is flagged, with row Slicer
MSSelector(MeasurementSet &ms)
construct from an MS, the MS will supply the range of the various parameters that can be selected on.
Matrix< Int64 > rowIndex_p
Definition: MSSelector.h:317
MSSelector(const MSSelector &other)
Copy constructor, this will initialize the MS with other's MS.
void getAveragedData(Array< Float > &avData, const Array< Bool > &flag, const ArrayColumn< Float > &col) const
average and convert float data
Matrix< Double > chanFreq_p
Definition: MSSelector.h:315
Vector< Int > chanSel_p
Definition: MSSelector.h:304
Bool initSelection(const Vector< Int > &dataDescIds, Bool reset=False)
initialize the selection by specifying, optionally, the DATA_DESC_IDs.
Bool select(const Record &items, Bool oneBased=False)
Select the MS based on the selections present in the input record.
Table selectedTable() const
Return the selected table.
Definition: MSSelector.h:325
MeasurementSet savems_p
Definition: MSSelector.h:299
Bool iterEnd()
End the iteration (before reaching the last iteration) and set the selection back to the state before...
Bool initSelection(Bool reset=False)
As above without the data desc id argument.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
rownr_t nrow() const
Get the number of rows.
Definition: Table.h:1171
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
uInt64 rownr_t
Define the type of a row number in a table.
Definition: aipsxtype.h:46