Details

RFC

Status: Implemented

Resolution: Done

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 backwardscompatible deprecated methods for:
 setFluxMag0: Invalid; PhotoCalib is immutable.
 getFluxMag0: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0point and not the 0point error, which has a nontrivial 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
John Parejko
created issue 
John Parejko
made changes 
John Parejko
made changes 
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:
{code} /** * 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; {code} Other methods on {{Calib}} that we will not provide backwardscompatible deprecated methods for: * {{setFluxMag0}}: Invalid; PhotoCalib is immutable. * {{getFluxMag0}}: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0point and not the 0point error, which has a nontrivial 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 {{Calib}}s. * {{get/setThrowOnNegativeFlux}}: Invalid; PhotoCalib is immutable and never throws in this manner. 
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:
{code} /** * 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; {code} Other methods on {{Calib}} that we will not provide backwardscompatible deprecated methods for: * {{setFluxMag0}}: Invalid; PhotoCalib is immutable. * {{getFluxMag0}}: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0point and not the 0point error, which has a nontrivial 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. 
John Parejko
made changes 
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:
{code} /** * 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; {code} Other methods on {{Calib}} that we will not provide backwardscompatible deprecated methods for: * {{setFluxMag0}}: Invalid; PhotoCalib is immutable. * {{getFluxMag0}}: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0point and not the 0point error, which has a nontrivial 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. 
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:
{code} /** * 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; {code} Other methods on {{Calib}} that we will not provide backwardscompatible deprecated methods for: * {{setFluxMag0}}: Invalid; PhotoCalib is immutable. * {{getFluxMag0}}: PhotoCalib has getInstFluxAtZeroMagnitude, which only returns the 0point and not the 0point error, which has a nontrivial 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. 
John Parejko
made changes 
Watchers  Jim Bosch, John Parejko, John Swinbank, Paul Price, Robert Lupton, Tim Jenness, Yusra AlSayyad [ Jim Bosch, John Parejko, John Swinbank, Paul Price, Robert Lupton, Tim Jenness, Yusra AlSayyad ]  Jim Bosch, John Parejko, John Swinbank, Leanne Guy, Paul Price, Robert Lupton, Tim Jenness, Yusra AlSayyad [ Jim Bosch, John Parejko, John Swinbank, Leanne Guy, Paul Price, Robert Lupton, Tim Jenness, Yusra AlSayyad ] 
John Parejko
made changes 
John Parejko
made changes 
John Swinbank
made changes 
Status  Proposed [ 10805 ]  Flagged [ 10606 ] 
John Parejko
made changes 
Planned End  20/Feb/19 10:49 PM  22/Feb/19 10:49 PM 
Gabriele Comoretto [X] (Inactive)
made changes 
Remote Link  This issue links to "Page (Confluence)" [ 19818 ] 
Wil O'Mullane
made changes 
Status  Flagged [ 10606 ]  Board Recommended [ 11405 ] 
John Parejko
made changes 
John Swinbank
made changes 
Status  Board Recommended [ 11405 ]  Adopted [ 10806 ] 
Gabriele Comoretto [X] (Inactive)
made changes 
Remote Link  This issue links to "Page (Confluence)" [ 19938 ] 
John Parejko
made changes 
Resolution  Done [ 10000 ]  
Status  Adopted [ 10806 ]  Implemented [ 11105 ] 
Gabriele Comoretto [X] (Inactive)
made changes 
Remote Link  This issue links to "Page (Confluence)" [ 20324 ] 