File PhotoCalib.h¶
Implementation of the Photometric Calibration class.
-
namespace
lsst
Class for a simple mapping implementing a generic AstrometryTransform.
Remove all non-astronomical counts from the Chunk Exposure’s pixels.
Forward declarations for lsst::utils::Cache
For details on the Cache class, see the Cache.h file.
It uses a template rather than a pointer so that the derived classes can use the specifics of the transform. The class simplePolyMapping overloads a few routines.
A base class for image defects
Numeric constants used by the Integrate.h integrator routines.
Compute Image Statistics
- Note
Gauss-Kronrod-Patterson quadrature coefficients for use in quadpack routine qng. These coefficients were calculated with 101 decimal digit arithmetic by L. W. Fullerton, Bell Labs, Nov 1981.
- Note
The Statistics class itself can only handle lsst::afw::image::MaskedImage() types. The philosophy has been to handle other types by making them look like lsst::afw::image::MaskedImage() and reusing that code. Users should have no need to instantiate a Statistics object directly, but should use the overloaded makeStatistics() factory functions.
-
namespace
afw
-
namespace
image
Functions
-
std::ostream &
operator<<
(std::ostream &os, Measurement const &measurement)¶
-
void
assertNonNegative
(double value, std::string const &name)¶ Raise lsst::pex::exceptions::InvalidParameterError if value is not >=0.
Used for checking the calibration mean/error in the constructor.
- Parameters
value
: Value that should be positive.name
: Text to prepend to error message.
- Exceptions
lsst::pex::exceptions::InvalidParameterError
: if value < 0
-
std::shared_ptr<PhotoCalib>
makePhotoCalibFromMetadata
(daf::base::PropertySet &metadata, bool strip = false)¶ Construct a PhotoCalib from FITS FLUXMAG0/FLUXMAG0ERR keywords.
This provides backwards compatibility with the obsoleted Calib object that PhotoCalib replaced. It should not be used outside of reading old Exposures written before PhotoCalib existed.
- Return
Pointer to the constructed PhotoCalib, or nullptr if FLUXMAG0 is not in the metadata.
- Parameters
metadata
: FITS header metadata containing FLUXMAG0 and FLUXMAG0ERR keys.strip
: Strip FLUXMAG0 and FLUXMAG0ERR frommetadata
?
-
std::shared_ptr<PhotoCalib>
makePhotoCalibFromCalibZeroPoint
(double instFluxMag0, double instFluxMag0Err)¶ Construct a PhotoCalib from the deprecated
Calib
-style instFluxMag0/instFluxMag0Err values.This provides backwards compatibility with the obsoleted Calib object that PhotoCalib replaced. It should not be used outside of tests that compare with old persisted Calib objects.
- Return
Pointer to the constructed PhotoCalib.
- Parameters
instFluxMag0
: The instrumental flux at zero magnitude. If 0, the resultingPhotoCalib
will have infinite calibrationMean and non-finite (inf or NaN) calibrationErr.instFluxMag0Err
: The instrumental flux at zero magnitude error. If 0, the resultingPhotoCalib
will have 0 calibrationErr.
-
struct
Measurement
¶ - #include <PhotoCalib.h>
A value and its error.
Public Functions
-
Measurement
(double value, double error)¶
-
-
class
PhotoCalib
: public lsst::afw::table::io::PersistableFacade<PhotoCalib>, public Storable - #include <PhotoCalib.h>
The photometric calibration of an exposure.
A PhotoCalib is a BoundedField (a function with a specified domain) that converts from post-ISR counts-on-chip (ADU) to flux and magnitude. It is defined such that a calibration of 1 means one count is equal to one nanojansky (nJy, 10^-35 W/m^2/Hz in SI units). The nJy was chosen because it represents a linear flux unit with values in a convenient range (e.g. LSST’s single image depth of 24.5 is 575 nJy). See more detailed discussion in: https://pstn-001.lsst.io/
PhotoCalib is immutable.
The spatially varying flux calibration has units of nJy/ADU, and is defined such that, at a position (x,y) in the domain of the boundedField calibration and for a given measured source instFlux:
\[ instFlux*calibration(x,y) = flux [nJy] \]while the errors (constant on the domain) are defined as:\[ sqrt((instFluxErr/instFlux)^2 + (calibrationErr/calibration)^2)*flux = fluxErr [nJy] \]This implies that the conversions from instFlux and instFlux error to magnitude and magnitude error are as follows:\[ -2.5*log_{10}(instFlux*calibration(x,y)*1e-9/referenceFlux) = magnitude \]where referenceFlux is the AB Magnitude reference flux from Oke & Gunn 1983 (first equation),
\[ referenceFlux = 1e23 * 10^{(48.6/-2.5)} \]and\[ 2.5/log(10)*sqrt((instFluxErr/instFlux)^2 + (calibrationErr/calibration)^2) = magnitudeErr \]Note that this is independent of referenceFlux.Public Functions
-
PhotoCalib
(PhotoCalib const&)
-
PhotoCalib
(PhotoCalib&&)
-
PhotoCalib &
operator=
(PhotoCalib const&)
-
PhotoCalib &
operator=
(PhotoCalib&&)
-
~PhotoCalib
()
-
PhotoCalib
() Create a empty, zeroed calibration.
-
PhotoCalib
(double calibrationMean, double calibrationErr = 0, lsst::geom::Box2I const &bbox = lsst::geom::Box2I()) Create a non-spatially-varying calibration.
- Parameters
[in] calibrationMean
: The spatially-constant calibration (must be non-negative).[in] calibrationErr
: The error on the calibration (must be non-negative).[in] bbox
: The bounding box on which this PhotoCalib is valid. If not specified, this PhotoCalib is valid at any point (i.e. an empty bbox).
Create a spatially-varying calibration.
- Parameters
[in] calibration
: The spatially varying photometric calibration (must have non-negative mean).[in] calibrationErr
: The error on the calibration (must be non-negative).
Create a calibration with a pre-computed mean. Primarily for de-persistence.
- Parameters
[in] calibrationMean
: The mean of the calibration() over its bounding box (must be non-negative).[in] calibrationErr
: The error on the calibration (must be non-negative).[in] calibration
: The spatially varying photometric calibration.[in] isConstant
: Is this PhotoCalib spatially constant?
-
double
instFluxToNanojansky
(double instFlux, lsst::geom::Point<double, 2> const &point) const Convert instFlux in ADU to nJy at a point in the BoundedField.
If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
- Return
The flux in nJy.
- Parameters
[in] instFlux
: The source instFlux in ADU.[in] point
: The point that instFlux is measured at.
-
double
instFluxToNanojansky
(double instFlux) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
Measurement
instFluxToNanojansky
(double instFlux, double instFluxErr, lsst::geom::Point<double, 2> const &point) const Convert instFlux and error in instFlux (ADU) to nJy and nJy error.
If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
- Return
The flux in nJy and error.
- Parameters
[in] instFlux
: The source fluxinstFlux in ADU.[in] instFluxErr
: The instFlux error.[in] point
: The point that instFlux is measured at.
-
Measurement
instFluxToNanojansky
(double instFlux, double instFluxErr) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
Measurement
instFluxToNanojansky
(const afw::table::SourceRecord &sourceRecord, std::string const &instFluxField) const Convert
sourceRecord[instFluxField_instFlux]
(ADU) at location(sourceRecord.get("x"), sourceRecord.get("y"))
(pixels) to flux and flux error (in nJy).- Return
The flux in nJy and error for this source.
- Parameters
[in] sourceRecord
: The source record to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”
-
ndarray::Array<double, 2, 2>
instFluxToNanojansky
(afw::table::SourceCatalog const &sourceCatalog, std::string const &instFluxField) const Convert
sourceCatalog[instFluxField_instFlux]
(ADU) at locations(sourceCatalog.get("x"), sourceCatalog.get("y"))
(pixels) to nJy.- Return
The flux in nJy and error for this source.
- Parameters
[in] sourceCatalog
: The source catalog to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”
-
void
instFluxToNanojansky
(afw::table::SourceCatalog &sourceCatalog, std::string const &instFluxField, std::string const &outField) const Convert
sourceCatalog[instFluxField_instFlux]
(ADU) at locations(sourceCatalog.get("x"), sourceCatalog.get("y"))
(pixels) to nJy and write the results back tosourceCatalog[outField_mag]
.- Parameters
[in] sourceCatalog
: The source catalog to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”[in] outField
: The field to write the nJy and magnitude errors to. Keys of the form “*_instFlux” and “*_instFluxErr” must exist in the schema.
-
double
instFluxToMagnitude
(double instFlux, lsst::geom::Point<double, 2> const &point) const Convert instFlux in ADU to AB magnitude.
If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
- Return
The AB magnitude.
- Parameters
[in] instFlux
: The source instFlux in ADU.[in] point
: The point that instFlux is measured at.
-
double
instFluxToMagnitude
(double instFlux) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
Measurement
instFluxToMagnitude
(double instFlux, double instFluxErr, lsst::geom::Point<double, 2> const &point) const Convert instFlux and error in instFlux (ADU) to AB magnitude and magnitude error.
If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
- Return
The AB magnitude and error.
- Parameters
[in] instFlux
: The source instFlux in ADU.[in] instFluxErr
: The instFlux error (standard deviation).[in] point
: The point that instFlux is measured at.
-
Measurement
instFluxToMagnitude
(double instFlux, double instFluxErr) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
Measurement
instFluxToMagnitude
(afw::table::SourceRecord const &sourceRecord, std::string const &instFluxField) const Convert
sourceRecord[instFluxField_instFlux]
(ADU) at location(sourceRecord.get("x"), sourceRecord.get("y"))
(pixels) to AB magnitude.- Return
The magnitude and magnitude error for this source.
- Parameters
[in] sourceRecord
: The source record to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”
-
ndarray::Array<double, 2, 2>
instFluxToMagnitude
(afw::table::SourceCatalog const &sourceCatalog, std::string const &instFluxField) const Convert
sourceCatalog[instFluxField_instFlux]
(ADU) at locations(sourceCatalog.get("x"), sourceCatalog.get("y"))
(pixels) to AB magnitudes.- Return
The magnitudes and magnitude errors for the sources.
- Parameters
[in] sourceCatalog
: The source catalog to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”
-
void
instFluxToMagnitude
(afw::table::SourceCatalog &sourceCatalog, std::string const &instFluxField, std::string const &outField) const Convert instFluxes in a catalog to AB magnitudes and write back into the catalog.
Convert
sourceCatalog[instFluxField_instFlux]
(ADU) at locations(sourceCatalog.get("x"), sourceCatalog.get("y"))
(pixels) to AB magnitudes and write the results back tosourceCatalog[outField_mag]
.- Parameters
[in] sourceCatalog
: The source catalog to get instFlux and position from.[in] instFluxField
: The instFlux field: Keys of the form “*_instFlux” and “*_instFluxErr” must exist. For example: instFluxField=”slot_PsfFlux” will use the fields named: “slot_PsfFlux_instFlux”, “slot_PsfFlux_instFluxErr”[in] outField
: The field to write the magnitudes and magnitude errors to. Keys of the form “*_instFlux”, “*_instFluxErr”, *_mag”, and “*_magErr” must exist in the schema.
-
MaskedImage<float>
calibrateImage
(MaskedImage<float> const &maskedImage, bool includeScaleUncertainty = true) const Return a flux calibrated image, with pixel values in nJy.
Mask pixels are propagated directly from the input image.
- Return
The calibrated masked image.
- Parameters
maskedImage
: The masked image to calibrate.includeScaleUncertainty
: Include the uncertainty on the calibration in the resulting variance?
-
afw::table::SourceCatalog
calibrateCatalog
(afw::table::SourceCatalog const &catalog, std::vector<std::string> const &instFluxFields) const Return a flux calibrated catalog, with new
_flux
,_fluxErr
,_mag
, and_magErr
fields.If the input catalog already has
_flux
,_mag
,_fluxErr
, and/or_magErr
fields matchinginstFluxFields
, they will be replaced with the new fields.- Return
A deep copy of the input catalog, with new calibrated flux and magnitude fields. Elements of
instFluxFields
that have_instFluxErr
will be used to compute the_fluxErr
and_magErr
fields.- Parameters
catalog
: The source catalog to compute calibrated fluxes for.instFluxFields
: The fields to calibrate (optional). If not provided, every field ending with_instFlux
will be calibrated.
- Exceptions
lsst::pex::exceptions::NotFoundError
: if any item ininstFluxFields
does not have a corresponding*_instFlux
field in catalog.schema.
-
afw::table::SourceCatalog
calibrateCatalog
(afw::table::SourceCatalog const &catalog) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
double
magnitudeToInstFlux
(double magnitude, lsst::geom::Point<double, 2> const &point) const Convert AB magnitude to instFlux (ADU).
If passed point, use the exact calculation at that point, otherwise, use the mean scaling factor.
Useful for inserting fake sources into an image.
- Return
Source instFlux in ADU.
- Parameters
[in] magnitude
: The AB magnitude to convert.[in] point
: The position that magnitude is to be converted at.
-
double
magnitudeToInstFlux
(double magnitude) const This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
-
double
getCalibrationMean
() const Get the mean photometric calibration.
This value is defined, for instFlux at (x,y), such that:
\[ instFlux*computeScaledCalibration()(x,y)*getCalibrationMean() = instFluxToNanojansky(instFlux, (x,y)) \]- See
PhotoCalib::computeScaledCalibration(), getCalibrationErr(), getInstFluxAtZeroMagnitude()
- Return
The spatial mean of this calibration.
-
double
getCalibrationErr
() const Get the mean photometric calibration error.
This value is defined such that for some instFluxErr, instFlux, and flux:
\[ sqrt((instFluxErr/instFlux)^2 + (calibrationErr/calibration(x,y))^2)*flux = fluxErr [nJy] \]- See
PhotoCalib::computeScaledCalibration(), getCalibrationMean()
- Return
The calibration error.
-
double
getInstFluxAtZeroMagnitude
() const Get the magnitude zero point (the instrumental flux corresponding to 0 magnitude).
This value is defined such that:
\[ instFluxToMagnitude(getInstFluxAtZeroMagnitude()) == 0 \]- See
PhotoCalib::computeScaledCalibration(), getCalibrationMean()
- Return
The instFlux magnitude zero point.
-
double
getLocalCalibration
(lsst::geom::Point<double, 2> const &point) const Get the local calibration at a point.
This value is defined such that:
\[ instFluxToNanojansky(instFlux, point) == localCalibration * inst \]Use getCalibrationErr() to get the spatially constant error on the calibration.
- See
- Return
The local calibration at a point.
- Parameters
[in] point
: The position that magnitude is to be converted at.
-
std::shared_ptr<afw::math::BoundedField>
computeScaledCalibration
() const Calculates the spatially-variable calibration, normalized by the mean in the valid domain.
This value is defined, for instFlux at (x,y), such that:
\[ instFlux*computeScaledCalibration()(x,y)*getCalibrationMean() = instFluxToNanojansky(instFlux, (x,y)) \]- See
- Return
The normalized spatially-variable calibration.
Calculates the scaling between this PhotoCalib and another PhotoCalib.
The BoundedFields of these PhotoCalibs must have the same BBoxes (or one or both must be empty).
With:
c = instFlux at position (x,y)
this = this PhotoCalib
other = other PhotoCalib
return = BoundedField returned by this method the return value from this method is defined as:
\[ this.instFluxToNanojansky(c, (x,y))*return(x, y) = other.instFluxToNanojansky(c, (x,y)) \]
- Return
The BoundedField as defined above.
- Warning
Not implemented yet: See DM-10154.
- Parameters
[in] other
: The PhotoCalib to scale to.
-
bool
operator==
(PhotoCalib const &rhs) const Two PhotoCalibs are equal if their component bounded fields and calibrationErr are equal.
-
bool
operator!=
(PhotoCalib const &rhs) const Two PhotoCalibs are equal if their component bounded fields and calibrationErr are equal.
-
bool
isPersistable
() const
-
std::shared_ptr<typehandling::Storable>
cloneStorable
() const Create a new PhotoCalib that is a copy of this one.
-
std::string
toString
() const Create a string representation of this object.
-
bool
equals
(typehandling::Storable const &other) const Compare this object to another Storable.
- Return
*this == other
ifother
is a PhotoCalib; otherwisefalse
.
Protected Functions
-
std::string
getPersistenceName
() const
-
void
write
(OutputArchiveHandle &handle) const
Private Functions
-
double
evaluate
(lsst::geom::Point<double, 2> const &point) const¶ Return the calibration evaluated at a point.
Helper function to manage constant vs. non-constant PhotoCalibs
-
ndarray::Array<double, 1>
evaluateArray
(ndarray::Array<double, 1> const &xx, ndarray::Array<double, 1> const &yy) const¶ Return the calibration evaluated at a sequence of points.
-
ndarray::Array<double, 1>
evaluateCatalog
(afw::table::SourceCatalog const &sourceCatalog) const¶ Return the calibration evaluated at the centroids of a SourceCatalog.
Returns the spatially-constant calibration (for setting _calibrationMean)
-
void
instFluxToNanojanskyArray
(afw::table::SourceCatalog const &sourceCatalog, std::string const &instFluxField, ndarray::Array<double, 2, 2> result) const¶ Helpers for converting arrays of instFlux.
-
void
instFluxToMagnitudeArray
(afw::table::SourceCatalog const &sourceCatalog, std::string const &instFluxField, ndarray::Array<double, 2, 2> result) const¶
-
-
std::ostream &
-
namespace