lsst::afw::table::CovarianceMatrixKey< T, N > Class Template Reference

#include <aggregates.h>

Inheritance diagram for lsst::afw::table::CovarianceMatrixKey< T, N >:

Public Types
using	ErrKeyArray = std::vector<Key<T>>
using	CovarianceKeyArray = std::vector<Key<T>>
using	NameArray = std::vector<std::string>
using	Value
	The data type for get and set.

Public Member Functions
	CovarianceMatrixKey ()
	Construct an invalid instance; must assign before subsequent use.
	CovarianceMatrixKey (ErrKeyArray const &err, CovarianceKeyArray const &cov=CovarianceKeyArray())
	Construct a from arrays of per-element Keys.
	CovarianceMatrixKey (SubSchema const &s, NameArray const &names)
	Construct from a subschema and an array of names for each parameter of the matrix.
	CovarianceMatrixKey (CovarianceMatrixKey const &)
	CovarianceMatrixKey (CovarianceMatrixKey &&)
CovarianceMatrixKey &	operator= (CovarianceMatrixKey const &)
CovarianceMatrixKey &	operator= (CovarianceMatrixKey &&)
	~CovarianceMatrixKey () noexcept override
Eigen::Matrix< T, N, N >	get (BaseRecord const &record) const override
	Get a covariance matrix from the given record.
void	set (BaseRecord &record, Eigen::Matrix< T, N, N > const &value) const override
	Set a covariance matrix in the given record (uses only the lower triangle of the given matrix)
T	getElement (BaseRecord const &record, int i, int j) const
	Return the element in row i and column j.
void	setElement (BaseRecord &record, int i, int j, T value) const
	Set the element in row i and column j.
bool	isValid () const noexcept
	Return True if all the constituent error Keys are valid.
bool	operator== (CovarianceMatrixKey const &other) const noexcept
	Compare the FunctorKey for equality with another, using its constituent Keys.
bool	operator!= (CovarianceMatrixKey const &other) const noexcept
std::size_t	hash_value () const noexcept
	Return a hash of this object.
virtual void	set (BaseRecord &record, T const &value) const=0

Static Public Member Functions
static CovarianceMatrixKey	addFields (Schema &schema, std::string const &prefix, NameArray const &names, std::string const &unit, bool diagonalOnly=false)
	Add covariance matrix fields to a Schema, and return a CovarianceMatrixKey to manage them.
static CovarianceMatrixKey	addFields (Schema &schema, std::string const &prefix, NameArray const &names, NameArray const &units, bool diagonalOnly=false)
	Add covariance matrix fields to a Schema, and return a CovarianceMatrixKey to manage them.

Detailed Description

template<typename T, int N>
class lsst::afw::table::CovarianceMatrixKey< T, N >

Definition at line 519 of file aggregates.h.

Member Typedef Documentation

CovarianceKeyArray

template<typename T, int N>

using lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceKeyArray = std::vector<Key<T>>

Definition at line 522 of file aggregates.h.

ErrKeyArray

template<typename T, int N>

using lsst::afw::table::CovarianceMatrixKey< T, N >::ErrKeyArray = std::vector<Key<T>>

Definition at line 521 of file aggregates.h.

NameArray

template<typename T, int N>

using lsst::afw::table::CovarianceMatrixKey< T, N >::NameArray = std::vector<std::string>

Definition at line 523 of file aggregates.h.

Value

using lsst::afw::table::FunctorKey< T >::Value

inherited

The data type for get and set.

Definition at line 77 of file FunctorKey.h.

Constructor & Destructor Documentation

CovarianceMatrixKey() [1/5]

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceMatrixKey ( )

default

Construct an invalid instance; must assign before subsequent use.

CovarianceMatrixKey() [2/5]

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceMatrixKey ( ErrKeyArray const & err, CovarianceKeyArray const & cov = CovarianceKeyArray() )

explicit

Construct a from arrays of per-element Keys.

The err array Keys should point to the square root of the diagonal of the covariance matrix. The cov array Keys should point to the off-diagonal elements of the lower-triangle, packed first in rows, then in columns (or equivalently, in the upper-triangle, packed first in columns, then in rows). For a 4x4 matrix, the order is is:

err[0]^2   cov[0]     cov[1]     cov[3]
cov[0]     err[1]^2   cov[2]     cov[4]
cov[1]     cov[2]     err[2]^2   cov[5]
cov[3]     cov[4]     cov[5]     err[3]^2

The cov array may also be empty, to indicate that no off-diagonal elements are stored, and should be set to zero. If not empty, the size of the cov matrix must be exactly n*(n-1)/2, where n is the size of the err matrix.

Definition at line 222 of file aggregates.cc.

        : _err(err), _cov(cov) {
    if (N != Eigen::Dynamic) {
        LSST_THROW_IF_NE(err.size(), std::size_t(N), pex::exceptions::LengthError,
                         "Size of err array (%d) does not match template argument (%d)");
    }
    if (!cov.empty()) {
        LSST_THROW_IF_NE(cov.size(), err.size() * (err.size() - 1) / 2, pex::exceptions::LengthError,
                         "Size of cov array (%d) is does not match with size inferred from err array (%d)");
        bool haveCov = false;
        for (typename CovarianceKeyArray::const_iterator i = _cov.begin(); i != _cov.end(); ++i) {
            if (i->isValid()) haveCov = true;
        }
        if (!haveCov) _cov.resize(0);
    }
}

CovarianceMatrixKey() [3/5]

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceMatrixKey	(	SubSchema const &	s,
		NameArray const &	names )

Construct from a subschema and an array of names for each parameter of the matrix.

The field names should match the following convention:

• diagonal elements should have names like "p1Err", where "p1" is the name of the parameter, and should contain the square root of the variance in that parameter.
• off-diagonal elements hould have names like "p1_p2_Cov", where "p1" and "p2" are names of parameters. For example, for the covariance matrix of a position, we'd look for "xErr", "yErr", and "x_y_Cov".

Definition at line 240 of file aggregates.cc.

        : _err(names.size()), _cov(names.size() * (names.size() - 1) / 2) {
    int const n = names.size();
    int k = 0;
    bool haveCov = false;
    for (int i = 0; i < n; ++i) {
        _err[i] = s[names[i] + "Err"];
        for (int j = 0; j < i; ++j, ++k) {
            try {
                _cov[k] = s[names[i] + "_" + names[j] + "_Cov"];
                haveCov = true;
            } catch (pex::exceptions::NotFoundError &) {
                try {
                    _cov[k] = s[names[j] + "_" + names[i] + "_Cov"];
                    haveCov = true;
                } catch (pex::exceptions::NotFoundError &) {
                }
            }
        }
    }
    if (!haveCov) _cov.resize(0);
}

CovarianceMatrixKey() [4/5]

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceMatrixKey ( CovarianceMatrixKey< T, N > const & )

default

CovarianceMatrixKey() [5/5]

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::CovarianceMatrixKey ( CovarianceMatrixKey< T, N > && )

default

~CovarianceMatrixKey()

template<typename T, int N>

lsst::afw::table::CovarianceMatrixKey< T, N >::~CovarianceMatrixKey ( )

overridedefaultnoexcept

Member Function Documentation

addFields() [1/2]

template<typename T, int N>

CovarianceMatrixKey< T, N > lsst::afw::table::CovarianceMatrixKey< T, N >::addFields ( Schema & schema, std::string const & prefix, NameArray const & names, NameArray const & units, bool diagonalOnly = false )

static

Add covariance matrix fields to a Schema, and return a CovarianceMatrixKey to manage them.

Parameters

[out]	schema	Schema to add fields to.
[in]	prefix	String used to form the first part of all field names. Suffixes of the form '_xErr' and '_x_y_Cov' will be added to form the full field names (using names={'x', 'y'} as an example).
[in]	units	Vector of units for for error (standard deviation) values; covariance matrix elements will have "{units[i]} {units[j]}" or "{units[i]}^2", depending on whether units[i] == units[j].
[in]	names	Vector of strings containing the names of the quantities the covariance matrix represents the uncertainty of.
[in]	diagonalOnly	If true, only create fields for the error values.

Definition at line 183 of file aggregates.cc.

                                                                                  {
    if (N != Eigen::Dynamic) {
        LSST_THROW_IF_NE(names.size(), std::size_t(N), pex::exceptions::LengthError,
                         "Size of names array (%d) does not match template argument (%d)");
        LSST_THROW_IF_NE(units.size(), std::size_t(N), pex::exceptions::LengthError,
                         "Size of units array (%d) does not match template argument (%d)");
    }
    ErrKeyArray err;
    CovarianceKeyArray cov;
    err.reserve(names.size());
    for (std::size_t i = 0; i < names.size(); ++i) {
        err.push_back(schema.addField<T>(schema.join(prefix, names[i] + "Err"),
                                           "1-sigma uncertainty on " + names[i], units[i]));
    }
    if (!diagonalOnly) {
        cov.reserve((names.size() * (names.size() - 1)) / 2);
        for (std::size_t i = 0; i < names.size(); ++i) {
            for (std::size_t j = 0; j < i; ++j) {
                // We iterate over the lower-triangular part of the matrix in row-major order,
                // but we use the upper-triangular names (i.e. we switch the order of i and j, below).
                // That puts the elements in the order expected by the constructor we call below,
                // while creating the field names users would expect from the ordering of their name
                // vector (i.e. _a_b_Cov instead of _b_a_Cov if names=[a, b]).
                cov.push_back(schema.addField<T>(
                        schema.join(prefix, names[j], names[i], "Cov"),
                        "uncertainty covariance between " + names[j] + " and " + names[i],
                        units[j] + (units[j].empty() || units[i].empty() ? "" : " ") + units[i]));
            }
        }
    }
    return CovarianceMatrixKey<T, N>(err, cov);
}

addFields() [2/2]

template<typename T, int N>

CovarianceMatrixKey< T, N > lsst::afw::table::CovarianceMatrixKey< T, N >::addFields ( Schema & schema, std::string const & prefix, NameArray const & names, std::string const & unit, bool diagonalOnly = false )

static

Add covariance matrix fields to a Schema, and return a CovarianceMatrixKey to manage them.

Parameters

[out]	schema	Schema to add fields to.
[in]	prefix	String used to form the first part of all field names. Suffixes of the form '_xErr' and '_x_y_Cov' will be added to form the full field names (using names={'x', 'y'} as an example).
[in]	unit	Unit for for error (standard deviation) values; covariance matrix elements will be unit^2.
[in]	names	Vector of strings containing the names of the quantities the covariance matrix represents the uncertainty of.
[in]	diagonalOnly	If true, only create fields for the error values.

Definition at line 175 of file aggregates.cc.

                                                                                                         {
    NameArray units(names.size(), unit);
    return addFields(schema, prefix, names, units, diagonalOnly);
}

get()

template<typename T, int N>

Eigen::Matrix< T, N, N > lsst::afw::table::CovarianceMatrixKey< T, N >::get ( BaseRecord const & record ) const

overridevirtual

Get a covariance matrix from the given record.

Implements lsst::afw::table::OutputFunctorKey< T >.

Definition at line 293 of file aggregates.cc.

                                                                                  {
    Eigen::Matrix<T, N, N> value = makeZeroMatrix(_err.size(), this);
    int const n = _err.size();
    int k = 0;
    for (int i = 0; i < n; ++i) {
        T err = record.get(_err[i]);
        value(i, i) = err * err;
        if (!_cov.empty()) {
            for (int j = 0; j < i; ++j, ++k) {
                if (_cov[k].isValid()) {
                    value(i, j) = value(j, i) = record.get(_cov[k]);
                }
            }
        }
    }
    return value;
}

getElement()

template<typename T, int N>

T lsst::afw::table::CovarianceMatrixKey< T, N >::getElement	(	BaseRecord const &	record,
		int	i,
		int	j ) const

Return the element in row i and column j.

Definition at line 370 of file aggregates.cc.

                                                                                    {
    if (i == j) {
        T err = record.get(_err[i]);
        return err * err;
    }
    if (_cov.empty()) {
        return 0.0;
    }
    Key<T> key = (i < j) ? _cov[j * (j - 1) / 2 + i] : _cov[i * (i - 1) / 2 + j];
    return key.isValid() ? record.get(key) : 0.0;
}

hash_value()

template<typename T, int N>

std::size_t lsst::afw::table::CovarianceMatrixKey< T, N >::hash_value ( ) const

noexcept

Return a hash of this object.

Definition at line 363 of file aggregates.cc.

                                                               {
    // Completely arbitrary seeds, different to avoid any weird degeneracies/interactions
    return cpputils::hashCombine(17, cpputils::hashIterable(19, _err.begin(), _err.end()),
                                 cpputils::hashIterable(23, _cov.begin(), _cov.end()));
}

isValid()

template<typename T, int N>

bool lsst::afw::table::CovarianceMatrixKey< T, N >::isValid ( ) const

noexcept

Return True if all the constituent error Keys are valid.

Note that if the only one or more off-diagonal keys are invalid, we assume that means those terms are zero, not that the whole FunctorKey is invalid.

Definition at line 328 of file aggregates.cc.

                                                       {
    int const n = _err.size();
    if (n < 1) return false;
    for (int i = 0; i < n; ++i) {
        if (!_err[i].isValid()) return false;
    }
    return true;
}

operator!=()

template<typename T, int N>

bool lsst::afw::table::CovarianceMatrixKey< T, N >::operator!= ( CovarianceMatrixKey< T, N > const & other ) const

inlinenoexcept

Definition at line 624 of file aggregates.h.

{ return !(*this == other); }

operator=() [1/2]

template<typename T, int N>

CovarianceMatrixKey< T, N > & lsst::afw::table::CovarianceMatrixKey< T, N >::operator= ( CovarianceMatrixKey< T, N > && )

default

operator=() [2/2]

template<typename T, int N>

CovarianceMatrixKey< T, N > & lsst::afw::table::CovarianceMatrixKey< T, N >::operator= ( CovarianceMatrixKey< T, N > const & )

default

operator==()

template<typename T, int N>

bool lsst::afw::table::CovarianceMatrixKey< T, N >::operator== ( CovarianceMatrixKey< T, N > const & other ) const

noexcept

Compare the FunctorKey for equality with another, using its constituent Keys.

Definition at line 338 of file aggregates.cc.

                                                                                          {
    if (_err.size() != other._err.size()) {
        return false;
    }
    if (_cov.size() != other._cov.size()) {
        return false;
    }
    int const n = _err.size();
    int k = 0;
    for (int i = 0; i < n; ++i) {
        if (_err[i] != other._err[i]) {
            return false;
        }
        if (!_cov.empty()) {
            for (int j = 0; j < i; ++j, ++k) {
                if (_cov[k] != other._cov[k]) {
                    return false;
                }
            }
        }
    }
    return true;
}

set() [1/2]

template<typename T, int N>

void lsst::afw::table::CovarianceMatrixKey< T, N >::set ( BaseRecord & record, Eigen::Matrix< T, N, N > const & value ) const

override

Set a covariance matrix in the given record (uses only the lower triangle of the given matrix)

Definition at line 312 of file aggregates.cc.

                                                                                               {
    int const n = _err.size();
    int k = 0;
    for (int i = 0; i < n; ++i) {
        record.set(_err[i], std::sqrt(value(i, i)));
        if (!_cov.empty()) {
            for (int j = 0; j < i; ++j, ++k) {
                if (_cov[k].isValid()) {
                    record.set(_cov[k], value(i, j));
                }
            }
        }
    }
}

set() [2/2]

virtual void lsst::afw::table::InputFunctorKey< T >::set ( BaseRecord & record, T const & value ) const

pure virtualinherited

setElement()

template<typename T, int N>

void lsst::afw::table::CovarianceMatrixKey< T, N >::setElement	(	BaseRecord &	record,
		int	i,
		int	j,
		T	value ) const

Set the element in row i and column j.

Definition at line 383 of file aggregates.cc.

                                                                                          {
    if (i == j) {
        record.set(_err[i], std::sqrt(value));
    } else {
        if (_cov.empty()) {
            throw LSST_EXCEPT(
                    pex::exceptions::LogicError,
                    (boost::format("Cannot set covariance element %d,%d; no fields for covariance") % i % j)
                            .str());
        }
        Key<T> key = (i < j) ? _cov[j * (j - 1) / 2 + i] : _cov[i * (i - 1) / 2 + j];
        if (!key.isValid()) {
            throw LSST_EXCEPT(
                    pex::exceptions::LogicError,
                    (boost::format("Cannot set covariance element %d,%d; no field for this element") % i % j)
                            .str());
        }
        record.set(key, value);
    }
}

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-11.0.0/Linux/afw/g4cdb532a89+a047e97985/include/lsst/afw/table/aggregates.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-11.0.0/Linux/afw/g4cdb532a89+a047e97985/src/table/aggregates.cc