Class PhotoCalib

Inheritance Relationships

Base Types

Class Documentation

class PhotoCalib : public lsst::afw::table::io::PersistableFacade<PhotoCalib>, public Storable

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).

PhotoCalib(std::shared_ptr<afw::math::BoundedField> calibration, double calibrationErr = 0)

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).

PhotoCalib(double calibrationMean, double calibrationErr, std::shared_ptr<afw::math::BoundedField> calibration, bool isConstant)

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 to sourceCatalog[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 to sourceCatalog[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 matching instFluxFields, 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 in instFluxFields 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

getCalibrationMean(), getCalibrationErr()

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

PhotoCalib::getCalibrationMean()

Return

The normalized spatially-variable calibration.

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

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

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 if other is a PhotoCalib; otherwise false.

Protected Functions

std::string getPersistenceName() const
void write(OutputArchiveHandle &handle) const