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

Backwards compatibility API for Calib->PhotoCalib transition

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      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

              • Assignee:
                Parejkoj John Parejko
                Reporter:
                Parejkoj John Parejko
                Watchers:
                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:

                  Summary Panel