TransformingVi2.h

Go to the documentation of this file.
00001 //# VisibilityIterator.h: Step through the MeasurementEquation by visibility
00002 //# Copyright (C) 1996,1997,1998,1999,2000,2001,2002,2003
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the Implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: VisibilityIterator2.h,v 19.14 2006/02/28 04:48:58 mvoronko Exp $
00027 
00028 #if ! defined (MSVIS_TransformingVi2_H_121115_0950)
00029 #define MSVIS_TransformingVi2_H_121115_0950
00030 
00031 #include <casa/aips.h>
00032 #include <msvis/MSVis/ViImplementation2.h>
00033 
00034 #include <map>
00035 #include <vector>
00036 
00037 #include <measures/Measures/Stokes.h>
00038 
00039 namespace casa { //# NAMESPACE CASA - BEGIN
00040 
00041 template <typename T> class Vector;
00042 
00043 namespace vi {
00044 
00045 //# forward decl
00046 
00047 class VisBuffer2;
00048 
00049 class ChannelSelector;
00050 class ChannelSelectorCache;
00051 typedef Vector<Vector <Slice> > ChannelSlicer;
00052 class SpectralWindowChannelsCache;
00053 class SpectralWindowChannels;
00054 class SubtableColumns;
00055 
00056 
00057 // <summary>
00058 // VisibilityIterator2 iterates through one or more readonly MeasurementSets
00059 // </summary>
00060 
00061 // <use visibility=export>
00062 
00063 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00064 // </reviewed>
00065 
00066 // <prerequisite>
00067 //   <li> <linkto class="MSIter">MSIter</linkto>
00068 //   <li> <linkto class="MeasurementSet">MeasurementSet</linkto>
00069 //   <li> <linkto class="VisSet">VisSet</linkto>
00070 // </prerequisite>
00071 //
00072 // <etymology>
00073 // The VisibilityIterator2 is a readonly iterator returning visibilities
00074 // </etymology>
00075 //
00076 // <synopsis>
00077 // VisibilityIterator2 provides iteration with various sort orders
00078 // for one or more MSs. It has member functions to retrieve the fields
00079 // commonly needed in synthesis calibration and imaging.
00080 //
00081 // One should use <linkto class="VisBuffer">VisBuffer</linkto>
00082 // to access chunks of data.
00083 // </synopsis>
00084 //
00085 // <example>
00086 // <code>
00087 // //
00088 // </code>
00089 // </example>
00090 //
00091 // <motivation>
00092 // For imaging and calibration you need to access an MS in some consistent
00093 // order (by field, spectralwindow, time interval etc.). This class provides
00094 // that access.
00095 // </motivation>
00096 //
00097 // <thrown>
00098 //    <li>
00099 //    <li>
00100 // </thrown>
00101 //
00102 // <todo asof="1997/05/30">
00103 //   <li> cleanup the currently dual interface for visibilities and flags
00104 //   <li> sort out what to do with weights when interpolating
00105 // </todo>
00106 
00107 class TransformingVi2 : public ViImplementation2 {
00108 
00109 public:
00110 
00111     // Destructor
00112 
00113     virtual ~TransformingVi2 ();
00114 
00115     // Report the the ViImplementation type
00116     //  (should be specialized in child classes)
00117     virtual String ViiType() const { return String("UnknownTrans( ")+getVii()->ViiType()+" )"; };
00118 
00119     //   +==================================+
00120     //   |                                  |
00121     //   | Iteration Control and Monitoring |
00122     //   |                                  |
00123     //   +==================================+
00124 
00125 
00126     // Methods to control and monitor subchunk iteration
00127 
00128     virtual void origin ();
00129     virtual Bool more () const;
00130     virtual void next ();
00131     virtual Subchunk getSubchunkId () const;
00132 
00133     // Methods to control chunk iterator
00134 
00135     virtual void originChunks (Bool forceRewind = False);
00136     virtual Bool moreChunks () const;
00137     virtual void nextChunk ();
00138 
00139     virtual Bool isWritable () const;
00140 
00141     // Return the time interval (in seconds) used for iteration.
00142     // This is not the same as the INTERVAL column.  Setting the
00143     // the interval requires calling origin chunks before performing
00144     // further iterator.
00145 
00146     virtual Double getInterval() const;
00147     virtual void setInterval (Double timeInterval);
00148 
00149     // Select the channels to be returned.  Requires calling originChunks before
00150     // performing additional iteration.
00151 
00152     virtual void setFrequencySelections (const FrequencySelections & selection);
00153 
00154     // Set the 'blocking' size for returning data.
00155     // With the default (0) only a single integration is returned at a time, this
00156     // is what is currently required for the calibration software. With blocking
00157     // set, up to nRows can be returned in one go. The chunk
00158     // size determines the actual maximum.
00159 
00160     virtual void setRowBlocking (Int nRows);
00161 
00162     virtual Bool existsColumn (VisBufferComponent2 id) const;
00163 
00164     virtual const SortColumns & getSortColumns() const;
00165 
00166     virtual Bool isNewArrayId () const;
00167     virtual Bool isNewFieldId () const;
00168     virtual Bool isNewMs () const;
00169     virtual Bool isNewSpectralWindow () const;
00170 
00171     // Return the number of rows in the current iteration
00172 
00173     virtual Int nRows () const;
00174 
00175     // Return the row ids as from the original root table. This is useful
00176     // to find correspondance between a given row in this iteration to the
00177     // original ms row
00178 
00179     virtual void getRowIds (Vector<uInt> & rowids) const;
00180 
00181     virtual VisBuffer2 * getVisBuffer (const VisibilityIterator2 *);
00182     virtual VisBuffer2 * getVisBuffer ();
00183 
00184 
00185     //   +=========================+
00186     //   |                         |
00187     //   | Subchunk Data Accessors |
00188     //   |                         |
00189     //   +=========================+
00190 
00191     // Return antenna1
00192 
00193     virtual void antenna1 (Vector<Int> & ant1) const;
00194 
00195     // Return antenna2
00196 
00197     virtual void antenna2 (Vector<Int> & ant2) const;
00198 
00199     // Return the correlation type (returns Stokes enums)
00200 
00201     virtual void corrType (Vector<Int> & corrTypes) const;
00202 
00203     // Return current DataDescription Id
00204 
00205     virtual Int dataDescriptionId () const;
00206 
00207     // Return actual time interval
00208 
00209     virtual void  exposure (Vector<Double> & expo) const;
00210 
00211     // Return feed1
00212 
00213     virtual void feed1 (Vector<Int> & fd1) const;
00214 
00215     // Return feed2
00216 
00217     virtual void feed2 (Vector<Int> & fd2) const;
00218 
00219     // Return the current FieldId
00220 
00221     virtual void fieldIds (Vector<Int>&) const;
00222 
00223 
00224     // Return the current ArrayId
00225 
00226     virtual void arrayIds (Vector<Int>&) const;
00227 
00228     // Return the current Field Name
00229 
00230     virtual String fieldName () const;
00231 
00232     // Return flag for each polarization, channel and row
00233 
00234     virtual void flag (Cube<Bool> & flags) const;
00235 
00236     // Return flag for each channel & row
00237 
00238     virtual void flag (Matrix<Bool> & flags) const;
00239 
00240     // Determine whether FLAG_CATEGORY is valid.
00241 
00242     virtual Bool flagCategoryExists () const;
00243 
00244     // Return flags for each polarization, channel, category, and row.
00245 
00246     virtual void flagCategory (Array<Bool> & flagCategories) const;
00247 
00248     // Return row flag
00249 
00250     virtual void flagRow (Vector<Bool> & rowflags) const;
00251 
00252     // Return the OBSERVATION_IDs
00253 
00254     virtual void observationId (Vector<Int> & obsids) const;
00255 
00256     // Return current Polarization Id
00257 
00258     virtual Int polarizationId () const;
00259 
00260     // Return the PROCESSOR_IDs
00261 
00262     virtual void processorId (Vector<Int> & procids) const;
00263 
00264     // Return scan number
00265 
00266     virtual void scan (Vector<Int> & scans) const;
00267 
00268     // Return the current Source Name
00269 
00270     virtual String sourceName () const;
00271 
00272     // Return the STATE_IDs
00273 
00274     virtual void stateId (Vector<Int> & stateids) const;
00275 
00276 
00277     // Return feed configuration matrix for specified antenna
00278 
00279     virtual void jonesC (Vector<SquareMatrix<Complex, 2> > & cjones) const;
00280 
00281     // Return frame for polarization (returns PolFrame enum)
00282 
00283     virtual Int polFrame () const;
00284 
00285     // Return sigma
00286 
00287     virtual void sigma (Matrix<Float> & sigmat) const;
00288 
00289     // Return current SpectralWindow
00290 
00291     virtual Int spectralWindow () const;
00292 
00293     virtual void spectralWindows (Vector<Int> & spws) const;
00294 
00295     // Return MJD midpoint of interval.
00296 
00297     virtual void time (Vector<Double> & t) const;
00298 
00299     // Return MJD centroid of interval.
00300 
00301     virtual void timeCentroid (Vector<Double> & t) const;
00302 
00303     // Return nominal time interval
00304 
00305     virtual void timeInterval (Vector<Double> & ti) const;
00306 
00307     // Return u,v and w (in meters)
00308 
00309     virtual void uvw (Matrix<Double> & uvwmat) const;
00310 
00311     // Return the visibilities as found in the MS, Cube (npol,nchan,nrow).
00312 
00313     virtual void visibilityCorrected (Cube<Complex> & vis) const;
00314     virtual void visibilityModel (Cube<Complex> & vis) const;
00315     virtual void visibilityObserved (Cube<Complex> & vis) const;
00316 
00317     // Return FLOAT_DATA as a Cube (npol, nchan, nrow) if found in the MS.
00318 
00319     virtual void floatData (Cube<Float> & fcube) const;
00320 
00321     // Return the visibility 4-vector of polarizations for each channel.
00322     // If the MS doesn't contain all polarizations, it is assumed it
00323     // contains one or two parallel hand polarizations.
00324 
00325 //    virtual void visibilityCorrected (Matrix<CStokesVector> & vis) const;
00326 //    virtual void visibilityModel (Matrix<CStokesVector> & vis) const;
00327 //    virtual void visibilityObserved (Matrix<CStokesVector> & vis) const;
00328 
00329     // Return the shape of the visibility Cube
00330 
00331     virtual IPosition visibilityShape () const;
00332 
00333     // Return weight
00334 
00335     virtual void weight (Matrix<Float> & wtmat) const;
00336 
00337     // Determine whether WEIGHT_SPECTRUM exists.
00338 
00339     virtual Bool weightSpectrumExists () const;
00340     virtual Bool sigmaSpectrumExists () const;
00341 
00342     // Return weightspectrum (a weight for each channel)
00343 
00344     virtual void weightSpectrum (Cube<Float> & wtsp) const;
00345     virtual void sigmaSpectrum (Cube<Float> & wtsp) const;
00346 
00347     // Return the number of sub-intervals in the current chunk
00348 
00349     //   +------------------------+
00350     //   |                        |
00351     //   | Angular Data Providers |
00352     //   |                        |
00353     //   +------------------------+
00354 
00355     // True if all elements of the cube returned by getBeamOffsets are zero
00356 
00357     virtual Bool allBeamOffsetsZero () const;
00358 
00359     // Return the antenna AZ/EL Vector (nant)
00360 
00361     virtual MDirection azel0 (Double time) const;
00362     static void azel0Calculate (Double time, MSDerivedValues & msd,
00363                                 MDirection & azel0, const MEpoch & mEpoch0);
00364 
00365     virtual const Vector<MDirection> & azel (Double time) const;
00366     static void azelCalculate (Double time, MSDerivedValues & msd, Vector<MDirection> & azel,
00367                                Int nAnt, const MEpoch & mEpoch0);
00368 
00369     // Return feed parallactic angles Vector (nant) (1 feed/ant)
00370 
00371     virtual const Vector<Float> & feed_pa (Double time) const;
00372     static Vector<Float> feed_paCalculate (Double time, MSDerivedValues & msd,
00373                                            Int nAntennas, const MEpoch & mEpoch0,
00374                                            const Vector<Float> & receptor0Angle);
00375 
00376     // Return a cube containing pairs of coordinate offsets for each
00377     // receptor of each feed (values are in radians, coordinate system is fixed
00378     // with antenna and is the same one as used to define the BEAM_OFFSET
00379     // parameter in the feed table). The cube axes are receptor, antenna, feed.
00380 
00381     virtual const Cube<RigidVector<Double, 2> > & getBeamOffsets () const;
00382 
00383     // Return the hour angle for the specified time
00384 
00385     virtual Double hourang (Double time) const;
00386     static Double hourangCalculate (Double time, MSDerivedValues & msd, const MEpoch & mEpoch0);
00387 
00388     // Return nominal parallactic angle at specified time
00389     // (does not include feed position angle offset--see feed_pa)
00390     // A global value for all antennas (e.g., small array)
00391 
00392     virtual const Float & parang0 (Double time) const;
00393     static Float parang0Calculate (Double time, MSDerivedValues & msd, const MEpoch & epoch0);
00394 
00395     // Per antenna:
00396 
00397     virtual const Vector<Float> & parang (Double time) const;
00398     static Vector<Float> parangCalculate (Double time, MSDerivedValues & msd,
00399                                           int nAntennas, const MEpoch mEpoch0);
00400 
00401     // Return the current phase center as an MDirection
00402 
00403     virtual const MDirection & phaseCenter () const;
00404 
00405     // Return receptor angles for all antennae and feeds
00406     // First axis of the cube is a receptor number,
00407     // 2nd is antennaId, 3rd is feedId
00408     // Note: the method is intended to provide an access to MSIter::receptorAngles
00409     // for VisBuffer in the multi-feed case. It may be worth to change the
00410     // interface of feed_pa to return the information for all feeds.
00411 
00412     virtual const Cube<Double> & receptorAngles () const;
00413 
00414     //   +=========================+
00415     //   |                         |
00416     //   | Chunk and MS Level Data |
00417     //   |                         |
00418     //   +=========================+
00419 
00420     // return a string mount identifier for each antenna
00421 
00422     virtual const Vector<String> & antennaMounts () const;
00423 
00424     virtual MEpoch getEpoch () const;
00425 
00426     // Return imaging weight (a weight for each channel)
00427     // virtual Matrix<Float> & imagingWeight (Matrix<Float> & wt) const;
00428 
00429     virtual const VisImagingWeight & getImagingWeightGenerator () const;
00430 
00431     virtual MFrequency::Types getObservatoryFrequencyType () const; //???
00432     virtual MPosition getObservatoryPosition () const;
00433     virtual Vector<Float> getReceptor0Angle ();
00434 
00435     virtual Int getReportingFrameOfReference () const;
00436     virtual void setReportingFrameOfReference (Int frame);
00437 
00438     virtual Vector<Int> getChannels (Double time, Int frameOfReference,
00439                                      Int spectralWindowId, Int msId) const;
00440     virtual Vector<Int> getCorrelations () const;
00441     virtual Vector<Stokes::StokesTypes> getCorrelationTypesDefined () const;
00442     virtual Vector<Stokes::StokesTypes> getCorrelationTypesSelected () const;
00443 
00444     virtual Vector<Double> getFrequencies (Double time, Int frameOfReference,
00445                                            Int spectralWindowId, Int msId) const;
00446     virtual void dataDescriptionIds(Vector<Int> &) const;
00447 
00448     //reference to actual ms in interator
00449 
00450     virtual Int msId () const; // zero-based index of current MS in set of MSs
00451     virtual const MeasurementSet & ms () const;
00452     virtual Int getNMs () const;
00453 
00454     // Name of nominal MS (will typically be beneath several layers)
00455     virtual String msName () const;
00456 
00457     // Call to use the slurp i/o method for all scalar columns. This
00458     // will set the BucketCache cache size to the full column length
00459     // and cause the full column to be cached in memory, if
00460     // any value of the column is used. In case of out-of-memory,
00461     // it will automatically fall-back on the smaller cache size.
00462     // Slurping the column is to be considered as a work-around for the
00463     // Table i/o code, which uses BucketCache and performs extremely bad
00464     // for random access. Slurping is useful when iterating non-sequentially
00465     // an MS or parts of an MS, it is not tested with multiple MSs.
00466 
00467     virtual void slurp () const;
00468 
00469     // Access the current ROMSColumns object in MSIter
00470 
00471     virtual const vi::SubtableColumns & subtableColumns () const;
00472 
00473     // get back the selected spectral windows and spectral channels for
00474     // current ms
00475 
00476     virtual const SpectralWindowChannels & getSpectralWindowChannels (Int msId, Int spectralWindowId) const;
00477 
00478     //assign a VisImagingWeight object to this iterator
00479 
00480     virtual void useImagingWeight (const VisImagingWeight & imWgt);
00481 
00482     // Return number of antennasm spws, polids, ddids
00483 
00484     virtual Int nAntennas () const;
00485     virtual Int nDataDescriptionIds () const;
00486     virtual Int nPolarizationIds () const;
00487     virtual Int nRowsInChunk () const; // number rows in current chunk
00488     virtual Int nRowsViWillSweep () const; // number of rows in all selected ms's
00489     virtual Int nSpectralWindows () const;
00490 
00491     //   +-------------------+
00492     //   |                   |
00493     //   | Writeback Methods |
00494     //   |                   |
00495     //   +-------------------+
00496 
00497     // This method writes back any changed (dirty) components of the provided
00498     // VisBuffer and is the preferred method for writing data out.
00499 
00500     virtual void writeBackChanges (VisBuffer2 * vb);
00501 
00502     // Write/modify the flags in the data.
00503     // This will flag all channels in the original data that contributed to
00504     // the output channel in the case of channel averaging.
00505     // All polarizations have the same flag value.
00506     virtual void writeFlag (const Matrix<Bool> & flag);
00507 
00508     // Write/modify the flags in the data.
00509     // This writes the flags as found in the MS, Cube (npol,nchan,nrow),
00510     // where nrow is the number of rows in the current iteration (given by
00511     // nRow ()).
00512     virtual void writeFlag (const Cube<Bool> & flag);
00513 
00514     // Write/modify the flag row column; dimension Vector (nrow)
00515     virtual void writeFlagRow (const Vector<Bool> & rowflags);
00516 
00517     virtual void writeFlagCategory(const Array<Bool>& fc);
00518 
00519     // Write/modify the visibilities.
00520     // This is possibly only for a 'reference' MS which has a new DATA column.
00521     // The first axis of the matrix should equal the selected number of channels
00522     // in the original MS.
00523     // If the MS does not contain all polarizations, only the parallel
00524     // hand polarizations are used.
00525 //    virtual void writeVisCorrected (const Matrix<CStokesVector> & visibilityStokes);
00526 //    virtual void writeVisModel (const Matrix<CStokesVector> & visibilityStokes);
00527 //    virtual void writeVisObserved (const Matrix<CStokesVector> & visibilityStokes);
00528 
00529     // Write/modify the visibilities
00530     // This writes the data as found in the MS, Cube (npol,nchan,nrow).
00531     virtual void writeVisCorrected (const Cube<Complex> & vis);
00532     virtual void writeVisModel (const Cube<Complex> & vis);
00533     virtual void writeVisObserved (const Cube<Complex> & vis);
00534 
00535     // Write/modify the weights
00536     virtual void writeWeight (const Matrix<Float> & wt);
00537 
00538     // Write/modify the weightMat
00539     //virtual void writeWeightMat (const Matrix<Float> & wtmat);
00540 
00541     // Write/modify the weightSpectrum
00542     virtual void writeWeightSpectrum (const Cube<Float> & wtsp);
00543     virtual void writeSigmaSpectrum (const Cube<Float> & wtsp);
00544 
00545     // Write/modify the Sigma
00546     virtual void writeSigma (const Matrix<Float> & sig);
00547 
00548     // Write/modify the ncorr x nrow SigmaMat.
00549     //virtual void writeSigmaMat (const Matrix<Float> & sigmat);
00550 
00551     // Write the information needed to generate on-the-fly model visibilities.
00552 
00553     virtual void writeModel(const RecordInterface& rec, Bool iscomponentlist=True,
00554                             Bool incremental=False);
00555 
00556     virtual void setWeightScaling (CountedPtr <WeightScaling> weightscaling);
00557     virtual Bool hasWeightScaling () const;
00558     virtual CountedPtr<WeightScaling> getWeightScaling () const;
00559 
00560     // Library of static transformations available for all TVIs
00561     static void calculateFlagRowFromFlagCube (const Cube<Bool> &flagCube, Vector<Bool> &flagRow);
00562 
00563 protected:
00564 
00565     TransformingVi2 (ViImplementation2 * inputVi);
00566 
00567     void configureNewSubchunk ();
00568     void configureNewSubchunk (Int msId, const String & msName, Bool isNewMs,
00569                                Bool isNewArrayId, Bool isNewFieldId,
00570                                Bool isNewSpectralWindow, const Subchunk & subchunk,
00571                                Int nRows, Int nChannels, Int nCorrelations,
00572                                const Vector<Int> & correlations,
00573                                const Vector<Stokes::StokesTypes> & correlationsDefined,
00574                                const Vector<Stokes::StokesTypes> & correlationsSelected,
00575                                CountedPtr<WeightScaling> weightScaling);
00576 
00577     VisibilityIterator2 * getVi () const;
00578     ViImplementation2 * getVii () const;
00579     void setVisBuffer (VisBuffer2 * vb);
00580     VisBuffer2 * getVisBufferConst () const {return vb_p;}
00581 
00582     // jagonzal (to be reviewed by jjacobs): I need to set inputVii_p to NULL from
00583     // MSTransformIterator destructor because MSTransformIteratorFactory is borrowing
00584     // the ViImplementation2 from the input iterator, which is deleted in the first
00585     // steps of the MSTransformIterator destructor.
00586     ViImplementation2 * inputVii_p;
00587 
00588 private:
00589 
00590     VisBuffer2 * vb_p; // [own]
00591     CountedPtr<WeightScaling> weightScaling_p;
00592 };
00593 
00594 } // end namespace vi
00595 
00596 } //# NAMESPACE CASA - END
00597 
00598 #endif // ! defined (MSVIS_TransformingVi2_H_121115_0950)
00599 
00600 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1