LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Types | Public Member Functions | Static Public Member Functions | List of all members
lsst::afw::table::CovarianceMatrixKey< T, N > Class Template Referenceabstract

#include <aggregates.h>

Inheritance diagram for lsst::afw::table::CovarianceMatrixKey< T, N >:
lsst::afw::table::FunctorKey< Eigen::Matrix< T, N, N > > lsst::afw::table::OutputFunctorKey< T > lsst::afw::table::InputFunctorKey< T >

Public Types

using ErrKeyArray = std::vector< Key< T > >
 
using CovarianceKeyArray = std::vector< Key< T > >
 
using NameArray = std::vector< std::string >
 
using Value = Eigen::Matrix< T, N, N >
 The data type for get and set. More...
 

Public Member Functions

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

Detailed Description

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

Definition at line 432 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 435 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 434 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 436 of file aggregates.h.

◆ Value

using lsst::afw::table::FunctorKey< Eigen::Matrix< T, N, N > >::Value = Eigen::Matrix< T, N, N >
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 188 of file aggregates.cc.

189  : _err(err), _cov(cov) {
190  if (N != Eigen::Dynamic) {
191  LSST_THROW_IF_NE(err.size(), std::size_t(N), pex::exceptions::LengthError,
192  "Size of err array (%d) does not match template argument (%d)");
193  }
194  if (!cov.empty()) {
195  LSST_THROW_IF_NE(cov.size(), err.size() * (err.size() - 1) / 2, pex::exceptions::LengthError,
196  "Size of cov array (%d) is does not match with size inferred from err array (%d)");
197  bool haveCov = false;
198  for (typename CovarianceKeyArray::const_iterator i = _cov.begin(); i != _cov.end(); ++i) {
199  if (i->isValid()) haveCov = true;
200  }
201  if (!haveCov) _cov.resize(0);
202  }
203 }
#define LSST_THROW_IF_NE(N1, N2, EXC_CLASS, MSG)
Check whether the given values are equal, and throw an LSST Exception if they are not.
Definition: asserts.h:38
T begin(T... args)
T end(T... args)
T resize(T... args)

◆ 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 206 of file aggregates.cc.

207  : _err(names.size()), _cov(names.size() * (names.size() - 1) / 2) {
208  int const n = names.size();
209  int k = 0;
210  bool haveCov = false;
211  for (int i = 0; i < n; ++i) {
212  _err[i] = s[names[i] + "Err"];
213  for (int j = 0; j < i; ++j, ++k) {
214  try {
215  _cov[k] = s[names[i] + "_" + names[j] + "_Cov"];
216  haveCov = true;
217  } catch (pex::exceptions::NotFoundError &) {
218  try {
219  _cov[k] = s[names[j] + "_" + names[i] + "_Cov"];
220  haveCov = true;
221  } catch (pex::exceptions::NotFoundError &) {
222  }
223  }
224  }
225  }
226  if (!haveCov) _cov.resize(0);
227 }
T size(T... args)

◆ 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]schemaSchema to add fields to.
[in]prefixString 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]unitsVector 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]namesVector of strings containing the names of the quantities the covariance matrix represents the uncertainty of.
[in]diagonalOnlyIf true, only create fields for the error values.

Definition at line 149 of file aggregates.cc.

151  {
152  if (N != Eigen::Dynamic) {
153  LSST_THROW_IF_NE(names.size(), std::size_t(N), pex::exceptions::LengthError,
154  "Size of names array (%d) does not match template argument (%d)");
155  LSST_THROW_IF_NE(units.size(), std::size_t(N), pex::exceptions::LengthError,
156  "Size of units array (%d) does not match template argument (%d)");
157  }
158  ErrKeyArray err;
159  CovarianceKeyArray cov;
160  err.reserve(names.size());
161  for (std::size_t i = 0; i < names.size(); ++i) {
162  err.push_back(schema.addField<T>(schema.join(prefix, names[i] + "Err"),
163  "1-sigma uncertainty on " + names[i], units[i]));
164  }
165  if (!diagonalOnly) {
166  cov.reserve((names.size() * (names.size() - 1)) / 2);
167  for (std::size_t i = 0; i < names.size(); ++i) {
168  for (std::size_t j = 0; j < i; ++j) {
169  // We iterate over the lower-triangular part of the matrix in row-major order,
170  // but we use the upper-triangular names (i.e. we switch the order of i and j, below).
171  // That puts the elements in the order expected by the constructor we call below,
172  // while creating the field names users would expect from the ordering of their name
173  // vector (i.e. _a_b_Cov instead of _b_a_Cov if names=[a, b]).
174  cov.push_back(schema.addField<T>(
175  schema.join(prefix, names[j], names[i], "Cov"),
176  "uncertainty covariance between " + names[j] + " and " + names[i],
177  units[j] + (units[j].empty() || units[i].empty() ? "" : " ") + units[i]));
178  }
179  }
180  }
181  return CovarianceMatrixKey<T, N>(err, cov);
182 }
std::string prefix
Definition: SchemaMapper.cc:72
table::Schema schema
Definition: python.h:134
std::vector< Key< T > > ErrKeyArray
Definition: aggregates.h:434
std::vector< Key< T > > CovarianceKeyArray
Definition: aggregates.h:435
T reserve(T... args)

◆ 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]schemaSchema to add fields to.
[in]prefixString 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]unitUnit for for error (standard deviation) values; covariance matrix elements will be unit^2.
[in]namesVector of strings containing the names of the quantities the covariance matrix represents the uncertainty of.
[in]diagonalOnlyIf true, only create fields for the error values.

Definition at line 141 of file aggregates.cc.

143  {
144  NameArray units(names.size(), unit);
145  return addFields(schema, prefix, names, units, diagonalOnly);
146 }
std::vector< std::string > NameArray
Definition: aggregates.h:436
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.
Definition: aggregates.cc:141

◆ 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 259 of file aggregates.cc.

259  {
260  Eigen::Matrix<T, N, N> value = makeZeroMatrix(_err.size(), this);
261  int const n = _err.size();
262  int k = 0;
263  for (int i = 0; i < n; ++i) {
264  T err = record.get(_err[i]);
265  value(i, i) = err * err;
266  if (!_cov.empty()) {
267  for (int j = 0; j < i; ++j, ++k) {
268  if (_cov[k].isValid()) {
269  value(i, j) = value(j, i) = record.get(_cov[k]);
270  }
271  }
272  }
273  }
274  return value;
275 }
bool isValid() const noexcept
Return True if all the constituent error Keys are valid.
Definition: aggregates.cc:294
T empty(T... args)

◆ 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 336 of file aggregates.cc.

336  {
337  if (i == j) {
338  T err = record.get(_err[i]);
339  return err * err;
340  }
341  if (_cov.empty()) {
342  return 0.0;
343  }
344  Key<T> key = (i < j) ? _cov[j * (j - 1) / 2 + i] : _cov[i * (i - 1) / 2 + j];
345  return key.isValid() ? record.get(key) : 0.0;
346 }

◆ hash_value()

template<typename T , int N>
std::size_t lsst::afw::table::CovarianceMatrixKey< T, N >::hash_value
noexcept

Return a hash of this object.

Definition at line 329 of file aggregates.cc.

329  {
330  // Completely arbitrary seeds, different to avoid any weird degeneracies/interactions
331  return utils::hashCombine(17, utils::hashIterable(19, _err.begin(), _err.end()),
332  utils::hashIterable(23, _cov.begin(), _cov.end()));
333 }
std::size_t hashCombine(std::size_t seed) noexcept
Combine hashes.
Definition: hashCombine.h:35
std::size_t hashIterable(std::size_t seed, InputIterator begin, InputIterator end) noexcept
Combine hashes in an iterable.
Definition: hashCombine.h:93

◆ isValid()

template<typename T , int N>
bool lsst::afw::table::CovarianceMatrixKey< T, N >::isValid
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 294 of file aggregates.cc.

294  {
295  int const n = _err.size();
296  if (n < 1) return false;
297  for (int i = 0; i < n; ++i) {
298  if (!_err[i].isValid()) return false;
299  }
300  return true;
301 }

◆ operator!=()

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

Definition at line 537 of file aggregates.h.

537 { 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 304 of file aggregates.cc.

304  {
305  if (_err.size() != other._err.size()) {
306  return false;
307  }
308  if (_cov.size() != other._cov.size()) {
309  return false;
310  }
311  int const n = _err.size();
312  int k = 0;
313  for (int i = 0; i < n; ++i) {
314  if (_err[i] != other._err[i]) {
315  return false;
316  }
317  if (!_cov.empty()) {
318  for (int j = 0; j < i; ++j, ++k) {
319  if (_cov[k] != other._cov[k]) {
320  return false;
321  }
322  }
323  }
324  }
325  return true;
326 }

◆ 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 278 of file aggregates.cc.

278  {
279  int const n = _err.size();
280  int k = 0;
281  for (int i = 0; i < n; ++i) {
282  record.set(_err[i], std::sqrt(value(i, i)));
283  if (!_cov.empty()) {
284  for (int j = 0; j < i; ++j, ++k) {
285  if (_cov[k].isValid()) {
286  record.set(_cov[k], value(i, j));
287  }
288  }
289  }
290  }
291 }
T sqrt(T... args)

◆ set() [2/2]

template<typename T >
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,
value 
) const

Set the element in row i and column j.

Definition at line 349 of file aggregates.cc.

349  {
350  if (i == j) {
351  record.set(_err[i], std::sqrt(value));
352  } else {
353  if (_cov.empty()) {
354  throw LSST_EXCEPT(
355  pex::exceptions::LogicError,
356  (boost::format("Cannot set covariance element %d,%d; no fields for covariance") % i % j)
357  .str());
358  }
359  Key<T> key = (i < j) ? _cov[j * (j - 1) / 2 + i] : _cov[i * (i - 1) / 2 + j];
360  if (!key.isValid()) {
361  throw LSST_EXCEPT(
362  pex::exceptions::LogicError,
363  (boost::format("Cannot set covariance element %d,%d; no field for this element") % i % j)
364  .str());
365  }
366  record.set(key, value);
367  }
368 }
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174

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