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
41namespace casacore { //# NAMESPACE CASACORE - BEGIN
42
43template <class T> class ArrayColumn;
44class Record;
45class 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
117public:
118
120
121 // construct from an MS, the MS will supply the range of the various
122 // parameters that can be selected on.
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
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
234protected:
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)
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
290private:
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
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};
323inline rownr_t MSSelector::nrow() const { return selms_p.nrow();}
326inline 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
rownr_t nrow() const
Number of rows in selected table.
Definition: MSSelector.h:323
Matrix< Double > bandwidth_p
Definition: MSSelector.h:315
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
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
Array< Float > getWeight(const ArrayColumn< Float > &wtCol, Bool sigma=False) const
get the weight, set sigma=True when retrieving sigma's
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.
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
Array< Bool > getAveragedFlag(Array< Bool > &avFlag, const ArrayColumn< Bool > &col) const
"average" flag, at present all output which has a flagged input is flagged
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
MSSelector & operator=(const MSSelector &other)
Assignment, this will initialize the MS with other's MS.
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
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