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 "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/cpputils/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) const;
    // TODO[DM-49400]: remove the overload below.
    [[deprecated(
        "The includeScaleUncertainty option is deprecated and does nothing. Will be removed after v29."
    )]]
    MaskedImage<float> calibrateImage(MaskedImage<float> const &maskedImage,
                                      bool includeScaleUncertainty) const;


    MaskedImage<float> uncalibrateImage(MaskedImage<float> const &maskedImage) const;
    // TODO[DM-49400]: remove the overload below.
    [[deprecated(
        "The includeScaleUncertainty option is deprecated and does nothing. Will be removed after v29."
    )]]
    MaskedImage<float> uncalibrateImage(MaskedImage<float> const &maskedImage,
                                        bool includeScaleUncertainty) 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 nanojanskyToInstFlux(double nanojansky, lsst::geom::Point<double, 2> const &point) const;

    double nanojanskyToInstFlux(double nanojansky) const;

    double getCalibrationMean() const { return _calibrationMean; }

    double getCalibrationErr() const { return _calibrationErr; }

    bool isConstant() const { return _isConstant; }

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

    double getLocalCalibration(lsst::geom::Point<double, 2> const &point) const { return evaluate(point); }

    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; }

    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