Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-573

Backwards compatibility API for Calib->PhotoCalib transition

    XMLWordPrintable

Details

    • RFC
    • Status: Implemented
    • Resolution: Done
    • DM
    • None

    Description

      The API of the new PhotoCalib object is entirely different from the old Calib API: it is defined in terms of a flux calibration factor instead of a magnitude zero point, methods are named e.g. instFluxToMagnitude instead of getMagnitude, and it never raises an exception when given a negative instrumental flux. To ease the transition to PhotoCalib, I propose that PhotoCalib gain the following deprecated methods from Calib until v18.0:

          /**
           * Return an instrumental flux and error (in ADU) given magnitude and magnitude error.
           *
           * Assumes that the errors are small and uncorrelated.
           *
           * @param mag The AB magnitude of the object.
           * @param magErr The error in the magnitude.
           */
          std::pair<double, double> getFlux(double const mag, double const magErr) const;
          ndarray::Array<double, 1> getFlux(ndarray::Array<double const, 1> const& mag) const;
          std::pair<ndarray::Array<double, 1>, ndarray::Array<double, 1>> getFlux(
                  ndarray::Array<double const, 1> const& mag, ndarray::Array<double const, 1> const& magErr) const;
       
          /**
           * Return a magnitude and magnitude error given instrumental flux and error (in ADU).
           *
           * @param instFlux The measured instFlux of the object (ADU).
           * @param instFluxErr The error in the measured instFlux (ADU).
           */
          std::pair<double, double> getMagnitude(double const instFlux, double const instFluxErr) const;
          ndarray::Array<double, 1> getMagnitude(ndarray::Array<double const, 1> const& instFlux) const;
          std::pair<ndarray::Array<double, 1>, ndarray::Array<double, 1>> getMagnitude(
                  ndarray::Array<double const, 1> const& instFlux,
                  ndarray::Array<double const, 1> const& instFluxErr) const;
      

      Other methods on Calib that we will not provide backwards-compatible deprecated methods for:

      • setFluxMag0: Invalid; PhotoCalib is immutable.
      • getFluxMag0: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0-point and not the 0-point error, which has a non-trivial relationship with the calibration error. This was most commonly used to construct a new Calib, about which see the next point.
      • Construction from a "instFlux at zero magnitude" double: this cannot be distinguished from the existing calibrationMean constructor. If such functionality is strongly desired, we could add a makePhotoCalibFromZeroPoint (or similar) free function, but I doubt it is necessary: users rarely have to construct their own photoCalib, and PhotoCalib will be able to read older Exposure files that contain persisted Calibs.
      • get/setThrowOnNegativeFlux: Invalid; PhotoCalib is immutable and never throws in this manner.
      • operator*= and operator/=: Invalid; PhotoCalib is immutable. We could provide operator* and operator/ though (returning a new PhotoCalib), if this functionality was important.

      Attachments

        Issue Links

          Activity

            People

              Parejkoj John Parejko
              Parejkoj John Parejko
              Jim Bosch, John Parejko, John Swinbank, Leanne Guy, Paul Price, Robert Lupton, Tim Jenness, Yusra AlSayyad
              Votes:
              0 Vote for this issue
              Watchers:
              8 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                Jenkins

                  No builds found.