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, Int 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  Int 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<Int> rowIndex_p; // mapping of rows to time and ifr slots
318  Vector<uInt> selRows_p; // range of rows from selms_p returned by getData
319  Int startRow_p, maxRow_p; // start and length of range of rows
321 
322 };
323 inline Int 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 
casacore::MSSelector::Residual
@ Residual
Definition: MSSelector.h:295
casacore::Slicer
Definition: Slicer.h:290
casacore::MSSelector::ifrAxis_p
Vector< Int > ifrAxis_p
Definition: MSSelector.h:314
casacore::Matrix< Double >
casacore::MSSelector::useSlicer_p
Bool useSlicer_p
Definition: MSSelector.h:305
casacore::MSSelector::getAveragedFlag
Array< Bool > getAveragedFlag(Array< Bool > &avFlag, const ArrayColumn< Bool > &col) const
"average" flag, at present all output which has a flagged input is flagged
casacore::MSSelector::nFuncType
@ nFuncType
Definition: MSSelector.h:292
casacore::MSSelector::nrow
Int nrow() const
Number of rows in selected table.
Definition: MSSelector.h:323
casacore::MSSelector::dataDescId
Vector< Int > dataDescId() const
Return the data desc IDs selected
Definition: MSSelector.h:324
casacore::MSSelector::MSSelector
MSSelector()
casacore::MSSelector::ifrSelection_p
Vector< Int > ifrSelection_p
Definition: MSSelector.h:314
casacore::MSSelector::polId_p
Vector< uInt > polId_p
Definition: MSSelector.h:303
casacore::MSDerivedValues
Definition: MSDerivedValues.h:111
casacore::MSSelector::msd_p
MSDerivedValues msd_p
Definition: MSSelector.h:316
casacore::MSSelector::subSet_p
Bool subSet_p
Definition: MSSelector.h:311
casacore::MSSelector::Model
@ Model
Definition: MSSelector.h:295
casacore::MSSelector::getAveragedData
void getAveragedData(Array< Complex > &avData, const Array< Bool > &flag, const ArrayColumn< Complex > &col) const
average and convert data
casacore::MSSelector::polSlice_p
Slice polSlice_p
Definition: MSSelector.h:308
casacore::MSSelector::savems_p
MeasurementSet savems_p
Definition: MSSelector.h:299
casacore::MSSelector::useIfrDefault_p
Bool useIfrDefault_p
Definition: MSSelector.h:320
casacore::MSSelector::getAveragedFlag
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
casacore::MSSelector::nDataType
@ nDataType
Definition: MSSelector.h:295
casacore::MSSelector::operator=
MSSelector & operator=(const MSSelector &other)
Assignment, this will initialize the MS with other's MS.
casacore::MSSelector::initSelection
Bool initSelection(Bool reset=False)
As above without the data desc id argument.
casacore::MSSelector::selRows_p
Vector< uInt > selRows_p
Definition: MSSelector.h:318
casacore::MSSelector::Imag
@ Imag
Definition: MSSelector.h:292
casacore::MSSelector::ms_p
MeasurementSet ms_p
Definition: MSSelector.h:297
casacore::MSSelector::ObsResidual
@ ObsResidual
Definition: MSSelector.h:295
casacore::MSSelector::timeAverage
void timeAverage(Array< Bool > &dataFlags, Array< Complex > &data, const Array< Bool > &flags, const Array< Float > &weights)
time average the input data, return new flags
casacore::MSSelector::Data
@ Data
Definition: MSSelector.h:292
casacore::MSSelector::select
Bool select(const String &msSelect)
Select the MS based on the TaQL selection string.
casacore::ArrayColumn< Complex >
casacore::MSSelector::Amp
@ Amp
Definition: MSSelector.h:292
casacore::StokesConverter
Definition: StokesConverter.h:110
casacore::MSSelector::ObsFloat
@ ObsFloat
Definition: MSSelector.h:295
casacore::MSSelector::dataDescId_p
Vector< Int > dataDescId_p
Definition: MSSelector.h:302
casacore::MSSelector::initSelection
Bool initSelection(const Vector< Int > &dataDescIds, Bool reset=False)
initialize the selection by specifying, optionally, the DATA_DESC_IDs.
casacore::MSSelector::msIter_p
MSIter * msIter_p
Definition: MSSelector.h:300
casacore::MSSelector::chanFreq_p
Matrix< Double > chanFreq_p
Definition: MSSelector.h:315
casacore::MSSelector
Definition: MSSelector.h:114
casacore::MSSelector::initSel_p
Bool initSel_p
Definition: MSSelector.h:301
casacore::MSSelector::rowIndex_p
Matrix< Int > rowIndex_p
Definition: MSSelector.h:317
casacore::MSSelector::startRow_p
Int startRow_p
Definition: MSSelector.h:319
casacore::Table
Definition: Table.h:154
casacore::Double
double Double
Definition: aipstype.h:55
casacore::MSSelector::haveSlicer_p
Bool haveSlicer_p
Definition: MSSelector.h:306
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::MSSelector::chanSel_p
Vector< Int > chanSel_p
Definition: MSSelector.h:304
casacore::MSSelector::chanSlice_p
Slice chanSlice_p
Definition: MSSelector.h:308
casacore::MSSelector::MSSelector
MSSelector(MeasurementSet &ms)
construct from an MS, the MS will supply the range of the various parameters that can be selected on.
casacore::MSSelector::iterInit
Bool iterInit(const Vector< String > &columns, Double interval, Int maxRows=0, Bool addDefaultSortColumns=True)
Set up an iterator, iterating over the specified columns, with optional time interval and maximum num...
casacore::MSSelector::spwId_p
Vector< uInt > spwId_p
Definition: MSSelector.h:303
casacore::MSSelector::getAveragedData
void getAveragedData(Array< Complex > &avData, const Array< Bool > &flag, const ArrayColumn< Complex > &col, const Slicer &rowSlicer) const
average and convert data, with row Slicer
casacore::MSSelector::maxRow_p
Int maxRow_p
Definition: MSSelector.h:319
casacore::Slice
Definition: Slice.h:94
casacore::MSSelector::Observed
@ Observed
Definition: MSSelector.h:295
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::Table::nrow
uInt nrow() const
Get the number of rows.
Definition: Table.h:1201
casacore::MSSelector::selms_p
MeasurementSet selms_p
Definition: MSSelector.h:298
casacore::MSSelector::putData
Bool putData(const Record &items)
Put the data for the items provided.
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::MSSelector::iterEnd
Bool iterEnd()
End the iteration (before reaching the last iteration) and set the selection back to the state before...
casacore::MSSelector::~MSSelector
~MSSelector()
casacore::MSSelector::MSSelector
MSSelector(const MSSelector &other)
Copy constructor, this will initialize the MS with other's MS.
casacore::MSSelector::selectChannel
Bool selectChannel(Int nChan, Int start, Int width, Int incr)
Set the mapping from input channels in the DATA column to output channels.
casacore::MSSelector::getData
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...
casacore::MSSelector::makeSlicer
void makeSlicer(Int start, Int nCorr) const
make the data slicer, pass in the first and the number of correlations to select
casacore::MSSelector::selectPolarization
Bool selectPolarization(const Vector< String > &wantedPol)
Specify the output polarization.
casacore::MSSelector::checkSelection
Bool checkSelection()
check if the data description selection has been done & do default selection if not.
casacore::MSSelector::polIndex_p
Vector< Int > polIndex_p
Definition: MSSelector.h:309
casacore::MSSelector::select
Bool select(const Record &items, Bool oneBased=False)
Select the MS based on the selections present in the input record.
casacore::MeasurementSet
Definition: MeasurementSet.h:243
casacore::MSIter
An iterator class for MeasurementSets
Definition: MSIter.h:162
casacore::MSSelector::selectedTable
Table selectedTable() const
Return the selected table.
Definition: MSSelector.h:325
casacore::MSSelector::getAveragedData
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
casacore::Array< Complex >
casacore::MSSelector::stokesConverter_p
StokesConverter stokesConverter_p
Definition: MSSelector.h:312
casacore::MSSelector::slicer_p
Slicer slicer_p
Definition: MSSelector.h:307
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::MSSelector::iterOrigin
Bool iterOrigin()
(Re)Set the iterator to the first iteration, call this after iterInit.
casacore::MSRange
Definition: MSRange.h:107
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::MSSelector::Corrected
@ Corrected
Definition: MSSelector.h:295
casacore::Record
Definition: Record.h:181
casacore::MSSelector::getWeight
Array< Float > getWeight(const ArrayColumn< Float > &wtCol, Bool sigma=False) const
get the weight, set sigma=True when retrieving sigma's
casacore::MSSelector::reorderFlagRow
void reorderFlagRow(Array< Bool > &flagRow)
reorder from 2d to 1d (removing ifr axis)
casacore::MSSelector::iterNext
Bool iterNext()
Step the iterator, sets the selection to the current table iteration.
casacore::Vector< Int >
casacore::MSSelector::Phase
@ Phase
Definition: MSSelector.h:292
casacore::MSSelector::getAveragedData
void getAveragedData(Array< Float > &avData, const Array< Bool > &flag, const ArrayColumn< Float > &col) const
average and convert float data
casacore::MSSelector::polSelection_p
Vector< String > polSelection_p
Definition: MSSelector.h:313
casacore::MSSelector::bandwidth_p
Matrix< Double > bandwidth_p
Definition: MSSelector.h:315
casacore::MSSelector::setMS
void setMS(MeasurementSet &ms)
Change or Set the MS this MSSelector refers to.
casacore::MSSelector::lastDataDescId_p
Vector< Int > lastDataDescId_p
Definition: MSSelector.h:302
casacore::MSSelector::wantedOne_p
Int wantedOne_p
Definition: MSSelector.h:310
casacore::MSSelector::convert_p
Bool convert_p
Definition: MSSelector.h:311
casacore::MSSelector::reorderWeight
void reorderWeight(Array< Float > &weight)
reorder from 2d to 1d (removing ifr axis)
casacore::MSSelector::putAveragedFlag
void putAveragedFlag(const Array< Bool > &avFlag, ArrayColumn< Bool > &col)
"unaverage" flag, distribute the flags back to the channels that went into the average
casacore::MSSelector::selected
Bool selected() const
Return the selection status of the table.
Definition: MSSelector.h:326
casacore::MSSelector::Real
@ Real
Definition: MSSelector.h:292
casacore::MSSelector::Ratio
@ Ratio
Definition: MSSelector.h:295