FITSArchive.h

//-*-C++-*-
/***************************************************************************
 *
 *   Copyright (C) 2003-2009 by Willem van Straten
 *   Licensed under the Academic Free License version 2.1
 *
 ***************************************************************************/
 
// psrchive/Base/Formats/PSRFITS/Pulsar/FITSArchive.h
 
#ifndef __Pulsar_FITSArchive_h
#define __Pulsar_FITSArchive_h
 
#include "Pulsar/BasicArchive.h"
#include "Pulsar/Agent.h"
#include "FITSError.h"
 
#include <fitsio.h>
 
namespace Pulsar
{
  class FITSHdrExtension;
  class ObsExtension;
  class WidebandCorrelator;
  class Receiver;
  class ITRFExtension;
  class CalInfoExtension;
  class ProcHistory;
  class Passband;
  class DigitiserStatistics;
  class PolnCalibratorExtension;
  class FluxCalibratorExtension;
  class CalibratorStokes;
  class CalibrationInterpolatorExtension;
  class ConfigurableProjectionExtension;
  class DigitiserCounts;
  class FITSSUBHdrExtension;
  class ProfileColumn;
  class CoherentDedispersion;
  class SpectralKurtosis;
  class ObsDescription;
  class CrossCovarianceMatrix;
  class DynamicResponse;
 
  class Pointing;
  class AuxColdPlasmaMeasures;


  
  class FITSArchive : public BasicArchive {
 
  public:

    FITSArchive ();

    FITSArchive (const FITSArchive& archive);

    ~FITSArchive ();

    const FITSArchive& operator= (const FITSArchive& archive);

    FITSArchive (const Archive& archive);

    void copy (const Archive& archive);
 
    // //////////////////////////////////////////////////////////////////
    //
    // implement the pure virtual methods of the Archive base class
    //

    FITSArchive* clone () const;
 
    // //////////////////////////////////////////////////////////////////
    //
    // FITSArchive specific interface
    //

    void update_history ();

    static std::string get_template_name ();

    static void unload (fitsfile*, const FITSHdrExtension*);

    static void unload (fitsfile*, const ObsExtension*);
    
    static void unload (fitsfile*, const Receiver*);

    static void unload (fitsfile*, const WidebandCorrelator*);

    static void unload (fitsfile*, const ITRFExtension*);

    static void unload (fitsfile*, const CalInfoExtension*);
    
    static void unload (fitsfile*, const ProcHistory*);
    
    static void unload (fitsfile*, const Passband*);
    
    void unload (fitsfile*, const DigitiserStatistics*) const;
    
    void unload (fitsfile*, const DigitiserCounts*) const;
    
    static void unload (fitsfile*, const PolnCalibratorExtension*);
    
    static void unload (fitsfile*, const FluxCalibratorExtension*);

    static void unload (fitsfile*, const CalibratorStokes*);

    static void unload (fitsfile*, const CalibrationInterpolatorExtension*);
   
    static void unload (fitsfile*, const ConfigurableProjectionExtension*);
 
    static void unload (fitsfile*, const FITSSUBHdrExtension*);
    
    static void unload (fitsfile*, const CoherentDedispersion*);

    void unload (fitsfile*, const Pointing*, int row) const;

    static void unload (fitsfile*, const AuxColdPlasmaMeasures*, int row);

    static void unload (fitsfile*, const ObsDescription*);

    static void unload (fitsfile*, const CrossCovarianceMatrix*);

    static void unload (fitsfile*, const DynamicResponse*);

    double get_offs_sub( unsigned int isub ) const;
 
    // Correct error due to REF_MJD precision
    void refmjd_rounding_correction();

    void set_search_mode() { search_mode = true; };
 
  protected:
 
    class SKLoader;
    
    friend class Archive::Advocate<FITSArchive>;
 
    // Advocates the use of the FITSArchive plugin
    class Agent : public Archive::Advocate<FITSArchive> {
      
    public:
      
      Agent () {}
      
      bool advocate (const char* filename);
      
      std::string get_name () { return "PSRFITS"; }
      
      std::string get_description ();
      
    };

    virtual void load_header (const char* filename);
    
    virtual Integration*
    load_Integration (const char* filename, unsigned subint);
    
    bool can_unload () const { return true; }

    virtual void unload_file (const char* filename) const;

    template<typename T>
    void load_amps (fitsfile*, Integration*, unsigned isubint, int colnum);
 
    // //////////////////////////////////////////////////////////////////////
    //
    // ADDITIONAL ATTRIBUTES
    //

    float psrfits_version;

    double chanbw;
    
    bool scale_cross_products;

    std::string state_scale;

    std::string state_pol_type;

    double predicted_phase;

    Reference::To<const Predictor> hdr_model;
 
    // //////////////////////////////////////////////////////////////////////
 
    // load the Pulsar::Parameters
    void load_Parameters (fitsfile*);
 
    // unload the Pulsar::Parameters
    void unload_Parameters (fitsfile*) const;
 
    // load the Pulsar::Predictor model
    void load_Predictor (fitsfile*);
 
    // unload the Pulsar::Predictor model
    void unload_Predictor (fitsfile*) const;
 
    // Archive Extensions used by FITSArchive
    
    // Extension I/O routines
    void load_ProcHistory (fitsfile*);
    void no_ProcHistory (fitsfile*);
 
    void load_DigitiserStatistics (fitsfile*);
    void load_DigitiserCounts(fitsfile*);
    void load_Passband (fitsfile*);
    void load_PolnCalibratorExtension (fitsfile*);
    void load_FluxCalibratorExtension (fitsfile*);
    void load_CalibratorStokes (fitsfile*);
    void load_CalibrationInterpolatorExtension (fitsfile*);
    void load_ConfigurableProjectionExtension (fitsfile*);
    void load_Receiver (fitsfile*);
    void load_ITRFExtension (fitsfile*);
    void load_CalInfoExtension (fitsfile*);
    void load_WidebandCorrelator (fitsfile*);
    void load_FITSSUBHdrExtension ( fitsfile * );
    void load_CoherentDedispersion (fitsfile*);
    void load_ObsDescription (fitsfile*);
    void load_CrossCovarianceMatrix (fitsfile*);
    void load_DynamicResponse(fitsfile*);
 
    template<class Ext>
    void unload (fitsfile*, const char* hdu_name) const;
    
    void load_integration_state ( fitsfile * );
    void load_state ( fitsfile * );
 
    void load_Pointing (fitsfile*, int row, Integration*);
    void load_Plasma (fitsfile*, int row, Integration*);
    void load_SpectralKurtosis (fitsfile*, int row, Integration*);
 
    void interpret_scale ( );
    void interpret_pol_type ( );

    static void delete_hdu (fitsfile*, const char* hdu_name);
 
    // //////////////////////////////////////////////////////////////////////
 
    // Helper function to write an integration to a file
    void unload_Integration (fitsfile*, int row, const Integration*) const;

    void unload_integrations (fitsfile*) const;

    void clean_Pointing_columns (fitsfile*) const;

    void add_Pointing_columns (fitsfile*) const;

    void load_Pointing_columns (fitsfile* fptr);

    int get_last_pointing_column (fitsfile* fptr) const;

    void unload_sk_integrations (fitsfile*) const;
 
  private:
 
    // Correct the reference epoch in WBC data taken during commissioning
    void P236_reference_epoch_correction ();
 
    // Correct the reference epoch in WBC data taken during commissioning
    bool correct_P236_reference_epoch;
 
    // The data file contains search mode data, not folded pulse profiles
    bool search_mode;
 
    // Flag set when data are loaded from a PSRFITS file
    bool loaded_from_fits;

    mutable unsigned naux_profile;

    mutable double aux_nsample;
    
    // Reference epoch is used during unload_Integration
    /* This attribute enables proper handling of time stamps when there
       is no FITSHdrExtension in use (as is the case in psrconv) */
    mutable MJD reference_epoch;
 
    struct pointing_info_column 
    {
      std::string name;
      std::string unit;
      std::string description;
      int colnum;
    };
 
    mutable std::vector<pointing_info_column> extra_pointing_columns;
 
    // Gate duty cycle passed on to all sub-integrations
    mutable double gate_duty_cycle;
 
    // Profile load/unload algorithm
    mutable Reference::To<ProfileColumn> load_dat_io, unload_dat_io;
 
    // Prepare dat_io attribute for use
    void setup_dat (fitsfile*, Reference::To<ProfileColumn>&) const;
 
    // Auxilliary data load/unload algorithm
    mutable Reference::To<ProfileColumn> load_aux_io, unload_aux_io;
 
    // Prepare dat_io attribute for use
    void setup_aux (fitsfile*, Reference::To<ProfileColumn>&, unsigned) const;
 
    // Set all attributes to default values
    void init ();
 
    // Pointer to file used for reading (only)
    fitsfile* read_fptr;
 
    // Name of file used for reading 
    std::string read_filename;
  };
 
  extern template Registry::List<Archive::Agent>::Enter<FITSArchive::Agent>
  Archive::Advocate<FITSArchive>::entry;
 
}
 
#endif