PhotoCalib.h

Go to the documentation of this file.

/*
 * LSST Data Management System
 * Copyright 2017 LSST Corporation.
 *
 * This product includes software developed by the
 * LSST Project (http://www.lsst.org/).
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the LSST License Statement and
 * the GNU General Public License along with this program.  If not,
 * see <http://www.lsstcorp.org/LegalNotices/>.
 */

#ifndef LSST_AFW_IMAGE_PHOTOCALIB_H
#define LSST_AFW_IMAGE_PHOTOCALIB_H

#include <cmath>  // For quiet_nan in the deprecated block

#include "boost/format.hpp"

#include "lsst/afw/math/BoundedField.h"
#include "lsst/afw/math/ChebyshevBoundedField.h"
#include "lsst/geom/Point.h"
#include "lsst/geom/Box.h"
#include "lsst/afw/table/Source.h"
#include "lsst/afw/table/io/Persistable.h"
#include "lsst/afw/typehandling/Storable.h"
#include "lsst/afw/image/MaskedImage.h"
#include "lsst/daf/base/PropertyList.h"
#include "lsst/pex/exceptions/Exception.h"
#include "lsst/utils/Magnitude.h"

namespace lsst {
namespace afw {
namespace image {

struct Measurement {
    Measurement(double value, double error) : value(value), error(error) {}
    double const value;
    double const error;
};

std::ostream &operator<<(std::ostream &os, Measurement const &measurement);

inline void assertNonNegative(double value, std::string const &name) {
    if (value < 0) {
        throw LSST_EXCEPT(lsst::pex::exceptions::InvalidParameterError,
                          (boost::format("%s must be positive: %.3g") % name % value).str());
    }
}

class PhotoCalib final : public table::io::PersistableFacade<PhotoCalib>, public typehandling::Storable {
public:
    // Allow move, but no copy
    PhotoCalib(PhotoCalib const &) = default;
    PhotoCalib(PhotoCalib &&) = default;
    PhotoCalib &operator=(PhotoCalib const &) = delete;
    PhotoCalib &operator=(PhotoCalib &&) = delete;

    ~PhotoCalib() override = default;

    PhotoCalib() : PhotoCalib(0) {}

    explicit PhotoCalib(double calibrationMean, double calibrationErr = 0,
                        lsst::geom::Box2I const &bbox = lsst::geom::Box2I())
            : _calibrationMean(calibrationMean), _calibrationErr(calibrationErr), _isConstant(true) {
        assertNonNegative(_calibrationMean, "Calibration mean");
        assertNonNegative(_calibrationErr, "Calibration error");
        ndarray::Array<double, 2, 2> coeffs = ndarray::allocate(ndarray::makeVector(1, 1));
        coeffs[0][0] = calibrationMean;
        _calibration = std::make_shared<afw::math::ChebyshevBoundedField>(
                afw::math::ChebyshevBoundedField(bbox, coeffs));
    }

    PhotoCalib(std::shared_ptr<afw::math::BoundedField> calibration, double calibrationErr = 0)
            : _calibration(calibration),
              _calibrationMean(computeCalibrationMean(calibration)),
              _calibrationErr(calibrationErr),
              _isConstant(false) {
        assertNonNegative(_calibrationMean, "Calibration (computed via BoundedField.mean()) mean");
        assertNonNegative(_calibrationErr, "Calibration error");
    }

    PhotoCalib(double calibrationMean, double calibrationErr,
               std::shared_ptr<afw::math::BoundedField> calibration, bool isConstant)
            : _calibration(calibration),
              _calibrationMean(calibrationMean),
              _calibrationErr(calibrationErr),
              _isConstant(isConstant) {
        assertNonNegative(_calibrationMean, "Calibration mean");
        assertNonNegative(_calibrationErr, "Calibration error");
    }

    double instFluxToNanojansky(double instFlux, lsst::geom::Point<double, 2> const &point) const;

    double instFluxToNanojansky(double instFlux) const;

    Measurement instFluxToNanojansky(double instFlux, double instFluxErr,
                                     lsst::geom::Point<double, 2> const &point) const;

    Measurement instFluxToNanojansky(double instFlux, double instFluxErr) const;

    Measurement instFluxToNanojansky(const afw::table::SourceRecord &sourceRecord,
                                     std::string const &instFluxField) const;

    ndarray::Array<double, 2, 2> instFluxToNanojansky(afw::table::SourceCatalog const &sourceCatalog,
                                                      std::string const &instFluxField) const;

    void instFluxToNanojansky(afw::table::SourceCatalog &sourceCatalog, std::string const &instFluxField,
                              std::string const &outField) const;

    double instFluxToMagnitude(double instFlux, lsst::geom::Point<double, 2> const &point) const;

    double instFluxToMagnitude(double instFlux) const;

    Measurement instFluxToMagnitude(double instFlux, double instFluxErr,
                                    lsst::geom::Point<double, 2> const &point) const;

    Measurement instFluxToMagnitude(double instFlux, double instFluxErr) const;

    Measurement instFluxToMagnitude(afw::table::SourceRecord const &sourceRecord,
                                    std::string const &instFluxField) const;

    ndarray::Array<double, 2, 2> instFluxToMagnitude(afw::table::SourceCatalog const &sourceCatalog,
                                                     std::string const &instFluxField) const;

    void instFluxToMagnitude(afw::table::SourceCatalog &sourceCatalog, std::string const &instFluxField,
                             std::string const &outField) const;

    MaskedImage<float> calibrateImage(MaskedImage<float> const &maskedImage,
                                      bool includeScaleUncertainty = true) const;

    afw::table::SourceCatalog calibrateCatalog(afw::table::SourceCatalog const &catalog,
                                               std::vector<std::string> const &instFluxFields) const;

    afw::table::SourceCatalog calibrateCatalog(afw::table::SourceCatalog const &catalog) const;

    double magnitudeToInstFlux(double magnitude, lsst::geom::Point<double, 2> const &point) const;

    double magnitudeToInstFlux(double magnitude) const;

    double getCalibrationMean() const { return _calibrationMean; }

    double getCalibrationErr() const { return _calibrationErr; }

    double getInstFluxAtZeroMagnitude() const { return utils::referenceFlux / _calibrationMean; }

    std::shared_ptr<afw::math::BoundedField> computeScaledCalibration() const;

    std::shared_ptr<afw::math::BoundedField> computeScalingTo(std::shared_ptr<PhotoCalib> other) const;

    bool operator==(PhotoCalib const &rhs) const;

    bool operator!=(PhotoCalib const &rhs) const { return !(*this == rhs); }

    bool isPersistable() const noexcept override { return true; }

    /* Backwards compatibility with old Calib object */

    [[deprecated("No-op: PhotoCalib never throws on negative instFlux. Will remove after v18.")]] static void
    setThrowOnNegativeFlux(bool raiseException) noexcept {
        ;  // do nothing!
    }
    [[deprecated("No-op: PhotoCalib never throws on negative instFlux. Will remove after v18.")]] static bool
    getThrowOnNegativeFlux() noexcept {
        return false;
    }

    [
            [deprecated("For backwards compatibility with Calib; use `instFluxToMagnitude` instead. To be "
                        "removed after v18.")]] double
    getMagnitude(double instFlux) const {
        return instFluxToMagnitude(instFlux);
    }

    [
            [deprecated("For backwards compatibility with Calib; use `instFluxToMagnitude` instead. To be "
                        "removed after v18.")]] ndarray::Array<double, 1>
    getMagnitude(ndarray::Array<double const, 1> const &instFlux) const;
    [
            [deprecated("For backwards compatibility with Calib; use `instFluxToMagnitude` instead. To be "
                        "removed after v18.")]] std::pair<double, double>
    getMagnitude(double instFlux, double instFluxErr) const {
        auto result = instFluxToMagnitude(instFlux, instFluxErr);
        return std::make_pair<const double &, const double &>(result.value, result.error);
    };
    [[deprecated(
            "For backwards compatibility with Calib; use `instFluxToMagnitude` instead. To be "
            "removed after v18.")]] 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;
    [[deprecated(
            "For backwards compatibility with Calib; use `magnitudeToInstFlux` instead. To be removed "
            "after v18.")]] double
    getFlux(double magnitude) const {
        return magnitudeToInstFlux(magnitude);
    }
    [[deprecated(
            "For backwards compatibility with Calib: use `getCalibrationMean`, `getCalibrationErr`, or "
            "`getInstFluxAtZeroMagnitude. To be removed after v18.")]] std::pair<double, double>
    getFluxMag0() const {
        return std::make_pair<double, double>(getInstFluxAtZeroMagnitude(),
                                              std::numeric_limits<double>::quiet_NaN());
    }
    [[deprecated(
            "PhotoCalib is immutable: create a new one with the calibration factor and calibration error,"
            " or create it like an old Calib object with makePhotoCalibFromCalibZeroPoint.")]] void
    setFluxMag0(double, double = 0) const {
        std::string msg =
                "PhotoCalib is immutable: create a new `PhotoCalib` with the calibration"
                " factor and error, or create it like an old Calib object with "
                "`makePhotoCalibFromCalibZeroPoint`.";
        throw LSST_EXCEPT(pex::exceptions::RuntimeError, msg);
    }

    std::shared_ptr<typehandling::Storable> cloneStorable() const override;

    std::string toString() const override;

    bool equals(typehandling::Storable const &other) const noexcept override;
    // PhotoCalib equality comparable but intentionally not hashable

protected:
    std::string getPersistenceName() const override;

    void write(OutputArchiveHandle &handle) const override;

private:
    std::shared_ptr<afw::math::BoundedField> _calibration;

    // The "mean" calibration, defined as the geometric mean of _calibration evaluated over _calibration's
    // bbox. Computed on instantiation as a convinience. Also, the actual calibration for a spatially-constant
    // calibration.
    double _calibrationMean;

    // The standard deviation of this PhotoCalib.
    double _calibrationErr;

    // Is this spatially-constant? Used to short-circuit getting centroids.
    bool _isConstant;

    double evaluate(lsst::geom::Point<double, 2> const &point) const;
    ndarray::Array<double, 1> evaluateArray(ndarray::Array<double, 1> const &xx,
                                            ndarray::Array<double, 1> const &yy) const;
    ndarray::Array<double, 1> evaluateCatalog(afw::table::SourceCatalog const &sourceCatalog) const;

    double computeCalibrationMean(std::shared_ptr<afw::math::BoundedField> calibration) const;

    void instFluxToNanojanskyArray(afw::table::SourceCatalog const &sourceCatalog,
                                   std::string const &instFluxField,
                                   ndarray::Array<double, 2, 2> result) const;
    void instFluxToMagnitudeArray(afw::table::SourceCatalog const &sourceCatalog,
                                  std::string const &instFluxField,
                                  ndarray::Array<double, 2, 2> result) const;
};

std::shared_ptr<PhotoCalib> makePhotoCalibFromMetadata(daf::base::PropertySet &metadata, bool strip = false);

std::shared_ptr<PhotoCalib> makePhotoCalibFromCalibZeroPoint(double instFluxMag0, double instFluxMag0Err);

}  // namespace image
}  // namespace afw
}  // namespace lsst

#endif  // LSST_AFW_IMAGE_PHOTOCALIB_H