Namespace lsst::afw::table¶

namespace table

Unnamed Group

typedef lsst::geom::Angle Angle

typedef lsst::geom::SpherePoint SpherePoint

Unnamed Group

template<typename RecordT, typename Catalog, typename T> std::shared_ptr<RecordT> _Catalog_find(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T> int _Catalog_lower_bound(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T> int _Catalog_upper_bound(Catalog const &catalog, T const &value, Key<T> const &key)

template<typename Catalog, typename T> std::pair<int, int> _Catalog_equal_range(Catalog const &catalog, T const &value, Key<T> const &key)

Typedefs

typedef PointKey<int> Point2IKey

typedef PointKey<double> Point2DKey

using Box2IKey = BoxKey<lsst::geom::Box2I>

using Box2DKey = BoxKey<lsst::geom::Box2D>

typedef ColumnViewT<ExposureRecord> ExposureColumnView

typedef ExposureCatalogT<ExposureRecord> ExposureCatalog

typedef ExposureCatalogT<ExposureRecord const> ConstExposureCatalog

typedef CatalogT<BaseRecord> BaseCatalog

typedef CatalogT<BaseRecord const> ConstBaseCatalog

typedef ColumnViewT<SimpleRecord> SimpleColumnView

typedef SortedCatalogT<SimpleRecord> SimpleCatalog

typedef SortedCatalogT<SimpleRecord const> ConstSimpleCatalog

typedef SourceColumnViewT<SourceRecord> SourceColumnView

typedef SortedCatalogT<SourceRecord> SourceCatalog

typedef SortedCatalogT<SourceRecord const> ConstSourceCatalog

typedef ColumnViewT<AmpInfoRecord> AmpInfoColumnView

typedef CatalogT<AmpInfoRecord> AmpInfoCatalog

typedef CatalogT<AmpInfoRecord const> ConstAmpInfoCatalog

typedef Match<SimpleRecord, SimpleRecord> SimpleMatch

typedef Match<SimpleRecord, SourceRecord> ReferenceMatch

typedef Match<SourceRecord, SourceRecord> SourceMatch

typedef std::vector<SimpleMatch> SimpleMatchVector

typedef std::vector<ReferenceMatch> ReferenceMatchVector

typedef std::vector<SourceMatch> SourceMatchVector

typedef std::int64_t RecordId

Type used for unique IDs for records.

FITS isn’t fond of uint64, so we can save a lot of pain by using signed ints here unless we really need unsigned.

typedef lsst::afw::detection::Footprint Footprint

typedef boost::mpl::vector<RecordId, std::uint16_t, std::int32_t, float, double, lsst::geom::Angle, std::uint8_t> ScalarFieldTypes: An MPL vector of scalar field types.

typedef boost::mpl::vector<RecordId, std::uint16_t, std::int32_t, float, double, lsst::geom::Angle, std::uint8_t, Flag, std::string, Array<std::uint16_t>, Array<int>, Array<float>, Array<double>, Array<std::uint8_t>> FieldTypes: An MPL vector of all field types.

Enums

enum CoordinateType

Enum used to set units for geometric FunctorKeys.

Values:

PIXEL

CELESTIAL

enum SourceFitsFlags

Bitflags to be passed to SourceCatalog::readFits and SourceCatalog::writeFits

Note that these flags may also be passed when reading/writing SourceCatalogs via the Butler, by passing a “flags” key/value pair as part of the data ID.

Values:

SOURCE_IO_NO_FOOTPRINTS = 0x1: Do not read/write footprints at all.

SOURCE_IO_NO_HEAVY_FOOTPRINTS = 0x2: Read/write heavy footprints as non-heavy footprints.

Functions

SourceMatchVector matchXy(SourceCatalog const &cat1, SourceCatalog const &cat2, double radius, MatchControl const &mc = MatchControl())

Parameters

cat1: first catalog
cat2: second catalog
radius: match radius (pixels)
mc: how to do the matching (obeys MatchControl::findOnlyClosest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, in pixels, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchXy(cat1,radius). The match is performed in pixel space (2d cartesian).

SourceMatchVector matchXy(SourceCatalog const &cat, double radius, MatchControl const &mc = MatchControl())

Parameters

cat: the catalog to self-match
radius: match radius (pixels)
mc: how to do the matching (obeys MatchControl::symmetricMatch)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, in pixels, is at most radius. The match is performed in pixel space (2d cartesian).

SourceMatchVector matchXy(SourceCatalog const &cat1, SourceCatalog const &cat2, double radius, bool closest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, in pixels, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchXy(cat1,radius). The match is performed in pixel space (2d cartesian).

Parameters

[in] cat1: first catalog
[in] cat2: second catalog
[in] radius: match radius (pixels)
[in] closest: if true then just return the closest match

SourceMatchVector matchXy(SourceCatalog const &cat, double radius, bool symmetric)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, in pixels, is at most radius. The match is performed in pixel space (2d cartesian).

Parameters

[in] cat: the catalog to self-match
[in] radius: match radius (pixels)
[in] symmetric: if cat to true symmetric matches are produced: i.e. if (s1, s2, d) is reported, then so is (s2, s1, d).

template<typename Cat1, typename Cat2> std::vector<Match<typename Cat1::Record, typename Cat2::Record>> matchRaDec(Cat1 const &cat1, Cat2 const &cat2, lsst::geom::Angle radius, MatchControl const &mc = MatchControl())

Parameters

cat1: first catalog
cat2: second catalog
radius: match radius
mc: how to do the matching (obeys MatchControl::findOnlyClosest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchRaDec(cat1,radius). The match is performed in ra, dec space.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

template<typename Cat> std::vector<Match<typename Cat::Record, typename Cat::Record>> matchRaDec(Cat const &cat, lsst::geom::Angle radius, MatchControl const &mc = MatchControl())

Parameters

cat: the catalog to self-match
radius: match radius
mc: how to do the matching (obeys MatchControl::symmetricMatch)

template<typename Cat1, typename Cat2> std::vector<Match<typename Cat1::Record, typename Cat2::Record>> matchRaDec(Cat1 const &cat1, Cat2 const &cat2, lsst::geom::Angle radius, bool closest)

Compute all tuples (s1,s2,d) where s1 belings to cat1, s2 belongs to cat2 and d, the distance between s1 and s2, is at most radius. If cat1 and cat2 are identical, then this call is equivalent to matchRaDec(cat1,radius). The match is performed in ra, dec space.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

Parameters

[in] cat1: first catalog
[in] cat2: second catalog
[in] radius: match radius
[in] closest: if true then just return the closest match

template<typename Cat> std::vector<Match<typename Cat::Record, typename Cat::Record>> matchRaDec(Cat const &cat, lsst::geom::Angle radius, bool symmetric)

Compute all tuples (s1,s2,d) where s1 != s2, s1 and s2 both belong to cat, and d, the distance between s1 and s2, is at most radius. The match is performed in ra, dec space.

This is instantiated for Simple and Source catalogs.

Parameters

[in] cat: the catalog to self-match
[in] radius: match radius
[in] symmetric: if cat to true symmetric matches are produced: i.e. if (s1, s2, d) is reported, then so is (s2, s1, d).

template<typename Record1, typename Record2> BaseCatalog packMatches(std::vector<Match<Record1, Record2>> const &matches)

Return a table representation of a MatchVector that can be used to persist it.

The schema of the returned object has “first” (RecordId), “second” (RecordID), and “distance” (double) fields.

Parameters

[in] matches: A std::vector of Match objects to convert to table form.

template<typename Cat1, typename Cat2> std::vector<Match<typename Cat1::Record, typename Cat2::Record>> unpackMatches(BaseCatalog const &matches, Cat1 const &cat1, Cat2 const &cat2)

Reconstruct a MatchVector from a BaseCatalog representation of the matches and a pair of catalogs.

If an ID cannot be found in the given tables, that pointer will be set to null in the returned match vector.

Note: The first and second catalog arguments must be sorted in ascending ID order on input; this will allow us to use binary search algorithms to find the records referred to by the match table.

This is instantiated for Simple-Simple, Simple-Source, and Source-Source catalog combinations.

Parameters

[in] matches: A normalized BaseCatalog representation, as produced by packMatches.
[in] cat1: A CatalogT containing the records used on the ‘first’ side of the match, sorted by ascending ID.
[in] cat2: A CatalogT containing the records used on the ‘second’ side of the match, sorted by ascending ID. May be the same as first.

template<typename ReferenceCollection> void updateRefCentroids(geom::SkyWcs const &wcs, ReferenceCollection &refList)

Update centroids in a collection of reference objects

Template Parameters

RefCollection: Type of sequence of reference objects, e.g. lsst::afw::table::SimpleCatalog or std::vector<std::shared_ptr<lsst::afw::table::SimpleRecord>>

Parameters

[in] wcs: WCS to map from sky to pixels
[inout] refList: Collection of reference objects. The schema must have three fields:
- ”coord”: a field containing an ICRS lsst::afw::SpherePoint; this field is read
- ”centroid”: a field containing lsst::geom::Point2D; this field is written
- ”hasCentroid”: a flag; this field is written

Exceptions

lsst::pex::exceptions::NotFoundError: if refList’s schema does not have the required fields.

template<typename SourceCollection> void updateSourceCoords(geom::SkyWcs const &wcs, SourceCollection &sourceList)

Update sky coordinates in a collection of source objects

Template Parameters

SourceCollection: Type of sequence of sources, e.g. lsst::afw::table::SourceCatalog or std::vector<std::shared_ptr<lsst::afw::table::SourceRecord>>

Parameters

[in] wcs: WCS to map from pixels to sky
[inout] sourceList: Collection of sources. The schema must have two fields:
- ”slot_Centroid”: a field containing lsst::geom::Point2D; this field is read
- ”coord”: a field containing an ICRS lsst::afw::SpherePoint; this field is written

Exceptions

lsst::pex::exceptions::NotFoundError: if refList’s schema does not have the required fields.

class AliasMap

#include <AliasMap.h>

Mapping class that holds aliases for a Schema

Aliases need not be complete, but they must match to the beginning of a field name to be useful. For example, if “a_b_c” is a true field name, “x_->a_b” is a valid alias that will cause “x_y_c” to map to “a_b_c”, but “y_z->b_c” will not cause “a_y_z” to be matched.

Aliases are not checked to see if they match any existing fields, and if an alias has the same name as a field name, it will take precedence and hide the true field.

Unlike the other components of a Schema, aliases can be modified and removed, even after a Table has been constructed from the Schema.

AliasMaps are shared when Schemas are copy-constructed, but can be separated manually by calling Schema::disconnectAliases() or Schema::setAliasMap(). In addition, the AliasMap is deep-copied when used to construct a Table (or Catalog).

In order to allow Tables to react to changes in aliases (which may be used to define cached Keys held by the table, as in SourceTable’s “slots” mechanism), an AliasMap that is part of a Schema held by a Table will hold a pointer to that Table, and call BaseTable::handleAliasChanges() when its aliases are set or removed.

template<typename T> class Array

#include <misc.h>

Tag types used to declare specialized field types.

See the documentation for specializations of FieldBase and KeyBase for more information.

template<typename T> class ArrayKey : public lsst::afw::table::FunctorKey<ndarray::Array<T const, 1, 1>>, public lsst::afw::table::ReferenceFunctorKey<ndarray::ArrayRef<T, 1, 1>>, public lsst::afw::table::ConstReferenceFunctorKey<ndarray::ArrayRef<T const, 1, 1>>

#include <arrays.h>

A FunctorKey used to get or set a ndarray::Array from a sequence of scalar Keys.

ArrayKey operates on the convention that arrays are defined by a set of contiguous scalar fields (i.e. added to the Schema in order, with no interruption) of the same type, with a common field name prefix and “_0”, “_1” etc. suffixes.

class BaseColumnView

#include <BaseColumnView.h>

Column-wise view into a sequence of records that have been allocated contiguously.

A BaseColumnView can be created from any iterator range that dereferences to records, as long as those records’ field data is contiguous in memory. In practice, that means they must have been created from the same table, and be in the same order they were created (with no deletions). It also requires that those records be allocated in the same block, which can be guaranteed with BaseTable::preallocate().

Geometric (point and shape) fields cannot be accessed through a BaseColumnView, but their scalar components can be.

BaseColumnView and its subclasses are always non-const views into a catalog, and so cannot be obtained from a catalog-of-const (trying this results in an exception, not a compilation error). As a result, all its accessors return arrays of non-const elements, even though they are themselves const member functions. This is no different from a shared_ptr<T>’s get() member function returning a non-const T*, even though get() is a const member function.

Subclassed by lsst::afw::table::ColumnViewT< RecordT >

class BaseRecord

#include <BaseRecord.h>

Base class for all records.

BaseRecord is a polymorphic base class that provides the core record interface: access to fields and links back to the table it is associated with. Field access is provided by the templated get, set, and operator[] member functions. As templates they are nonvirtual and cannot be overridden by subclasses. The implementations for these accessors is in the FieldBase template specializations.

Each subclass of BaseRecord should be paired with a subclass of BaseTable. All record creation goes through a table, as the table allocates the memory used to store a record’s fields and holds the Schema instance that defines those fields.

Records are noncopyable, and are hence usually passed by shared_ptr or [const-]reference.

Subclassed by lsst::afw::detection::PeakRecord, lsst::afw::table::ExposureRecord, lsst::afw::table::SimpleRecord

class BaseTable : public std::enable_shared_from_this<BaseTable>

#include <BaseTable.h>

Base class for all tables.

Tables have two largely distinct purposes:

They serve as factories for records, allocating their field data in blocks.
They carry additional information (such as the schema) that should be shared by multiple records.

It’s mostly a matter of convenience that we use the same class to serve both needs.

Tables do not actually maintain a list of all the records they have allocated - but those records hold a pointer back to the table. This allows the work of holding and iterating over records to be delegated to templated container classes (such as CatalogT) while allowing tables to be polymorphic, non-template classes. In some sense, then, it may make more sense to think of a table as a combination factory and “container header”.

Tables are always created in shared_ptrs (a requirement of enable_shared_from_this). BaseTable provides a make static member function to create a new table, and most derived table classes should do the same.

Each table class should be associated with a particular record class (1-to-1). Each table instance may be associated with many record instances.

Subclassed by lsst::afw::detection::PeakTable, lsst::afw::table::ExposureTable, lsst::afw::table::SimpleTable

class BitsColumn

#include <BaseColumnView.h>

A packed representation of a collection of Flag field columns.

The packing of bits here is not necessarily the same as the packing using in the actual table, as the latter may contain more than 64 bits spread across multiple integers.

A BitsColumn can only be constructed by calling BaseColumnView::getBits().

template<typename Box> class BoxKey : public lsst::afw::table::FunctorKey<Box>

#include <aggregates.h>

A FunctorKey used to get or set a lsst::geom::Box2I or Box2D from a (min, max) pair of PointKeys.

The Box2IKey and Box2DKey typedefs should be preferred to using the template name directly.

template<typename BaseT> class CatalogIterator : public boost::iterator_adaptor<CatalogIterator<BaseT>, BaseT, BaseT::value_type::element_type>

#include <Catalog.h>

Iterator class for CatalogT.

Iterators dereference to record references or const references, even though the CatalogT container is based on a vector of shared_ptr internally. This is usually very convenient (and is one of the reasons for having a custom container class in the first place).

Sometimes, however, we’d like to get a shared_ptr from an iterator (especially because records are noncopyable). With that in mind, CatalogIterator is implicitly convertible to the shared_ptr type it holds internally, and can also be assigned a shared_ptr to set the pointer in the underlying container. This conversion makes sense from the perspective that both iterators and smart pointers mimic the interface of pointers and provide the same interface to get at the underlying record.

template<typename RecordT> class CatalogT

#include <Catalog.h>

A custom container class for records, based on std::vector.

CatalogT wraps a std::vector<std::shared_ptr<RecordT>> in an interface that looks more like a std::vector<RecordT>; its iterators and accessors return references or const references, rather than pointers, making them easier to use. It also holds a table, which is used to allocate new records and determine the schema, but no checking is done to ensure that records added to the catalog use the same table or indeed have the same schema.

Because a CatalogT is holds shared_ptrs internally, many of its operations can be either shallow or deep, with new deep copies allocated by the catalog’s table object. New records can be also be inserted by pointer (shallow) or by value (deep).

The constness of records is determined by the constness of the first template parameter to CatalogT; a container instance is always either const or non-const in that respect (like smart pointers). Also like smart pointers, const member functions (and by extension, const_iterators) do not allow the underlying pointers to be changed, while non-const member functions and iterators do.

CatalogT does not permit empty (null) pointers as elements. As a result, CatalogT has no resize member function.

CatalogT has a very different interface in Python; it mimics Python’s list instead of C++’s std::vector. It is also considerably simpler, because it doesn’t need to deal with iterator ranges or the distinction between references and shared_ptrs to records. See the Python docstring for more information.

Subclassed by lsst::afw::table::SortedCatalogT< RecordT >

class CentroidSlotDefinition : public lsst::afw::table::SlotDefinition: #include <slots.h>
SlotDefinition specialization for centroids.

template<typename RecordT> class ColumnViewT : public lsst::afw::table::BaseColumnView: Subclassed by lsst::afw::table::SourceColumnViewT< RecordT >

template<typename T> class ConstReferenceFunctorKey

#include <FunctorKey.h>

Base class for objects that can return a const reference to part of a record, but are not a true Key

Objects that inherit from ConstReferenceFunctorKey can be passed to BaseRecord::operator[], just as true Keys can, but the record will simply pass itself to ReferenceFunctorKey::getConstReference().

Note: We’d combine this with the ReferenceFunctorKey interface if it weren’t for the fact that we can’t pass multiple template arguments to a Swig macro if either contains commas, and we’d need that to wrap a combined interface base class.

class CoordKey : public lsst::afw::table::FunctorKey<lsst::geom::SpherePoint>

#include <aggregates.h>

A FunctorKey used to get or set celestial coordinates from a pair of lsst::geom::Angle keys.

Coords are always stored and returned in the ICRS system. Coords in other systems may be assigned, but this will result in a conversion to ICRS.

class EllipseKey : public lsst::afw::table::FunctorKey<lsst::afw::geom::ellipses::Ellipse>: #include <aggregates.h>
A FunctorKey used to get or set a geom::ellipses::Ellipse from an (xx,yy,xy,x,y) tuple of Keys.

template<typename RecordT> class ExposureCatalogT : public lsst::afw::table::SortedCatalogT<RecordT>

#include <Exposure.h>

Custom catalog class for ExposureRecord/Table.

We don’t expect to subclass ExposureRecord/Table, so unlike other Catalogs we can (and do) define some ExposureCatalogT member functions in Exposure.cc where the explicit instantiation is done.

class ExposureRecord : public lsst::afw::table::BaseRecord: #include <Exposure.h>
Record class used to store exposure metadata.

class ExposureTable : public lsst::afw::table::BaseTable

#include <Exposure.h>

Table class used to store exposure metadata.

Record class used to store exposure metadata.

template<typename T> struct Field : public lsst::afw::table::FieldBase<T>

#include <Field.h>

A description of a field in a table.

Field combines a type with the field name, documentation, units, and in some cases, the size of the field.

Specializations for different field types are inherited through FieldBase; see the documentation for those specializations for additional information about particular field types.

template<typename T> struct FieldBase

#include <FieldBase.h>

Field base class default implementation (used for numeric scalars and lsst::geom::Angle).

template<typename U> struct FieldBase<Array<U>>

#include <FieldBase.h>

Field base class specialization for arrays.

The Array tag is used for both fixed-length (same size in every record, accessible via ColumnView) and variable-length arrays; variable-length arrays are initialized with a size of 0. Ideally, we’d use complete different tag classes for those two very different types, but boost::variant and boost::mpl put a limit of 20 on the number of field types, and we’re running out. In a future reimplementation of afw::table, we should fix this.

template<> struct FieldBase<Flag>

#include <Flag.h>

Specialization for Flag fields.

Flag fields are handled specially in many places, because their keys have both an offset into an integer element and the bit in that element; while other fields have one or more elements per field, Flags have multiple fields per element. This means we can’t put all the custom code for Flag in FieldBase, and because Flags have an explicit Key specialization, we put the record access implementation in Key.

Subclassed by lsst::afw::table::Field< Flag >, lsst::afw::table::Key< Flag >

template<> struct FieldBase<std::string>

#include <FieldBase.h>

Field base class specialization for strings.

Subclassed by lsst::afw::table::Key< std::string >

class FluxSlotDefinition : public lsst::afw::table::SlotDefinition: #include <slots.h>
SlotDefinition specialization for fluxes.

template<typename T> class FunctorKey : public lsst::afw::table::OutputFunctorKey<T>, public lsst::afw::table::InputFunctorKey<T>

#include <FunctorKey.h>

Convenience base class that combines the OutputFunctorKey and InputFunctorKey

Most objects that can set a calculated or compound value from a record can also get that value back, so we provide this class to aggregate those interfaces.

class IdFactory

#include <IdFactory.h>

A polymorphic functor base class for generating record IDs for a table.

The IDs produced by an IdFactory need not be sequential, but they must be unique, both with respect to the IDs it generates itself and those passed to it via the notify() member function. Valid IDs must be nonzero, as zero is used to indicate null in some contexts.

template<typename T> class InputFunctorKey

#include <FunctorKey.h>

Base class for objects that can set a value on a record, but are not a true Key themselves.

Objects that inherit from InputFunctorKey can be passed to BaseRecord::set(), just as true Keys can, but the record will simply pass itself to OutputFunctorKey::set() along with the value that was passed.

Subclassed by lsst::afw::table::FunctorKey< T >

template<typename T> class Key : public lsst::afw::table::KeyBase<T>, public lsst::afw::table::FieldBase<T>

#include <Key.h>

A class used as a handle to a particular field in a table.

All access to table data ultimately goes through Key objects, which know (via an internal offset) how to address and cast the internal data buffer of a record or table.

Keys can be obtained from a Schema by name:

schema.find("myfield").key

and are also returned when a new field is added. Compound and array keys also provide accessors to retrieve scalar keys to their elements (see the documentation for the KeyBase specializations), even though these element keys do not correspond to a field that exists in any Schema. For example:

Schema schema;
Key< Array<float> > arrayKey = schema.addField< Array<float> >("array", "docs for array", 5);
Key< Point<int> > pointKey = schema.addField< Point<int> >("point", "docs for point");
Key<float> elementKey = arrayKey[3];
Key<int> xKey = pointKey.getX();
std::shared_ptr<BaseTable> table = BaseTable::make(schema);
std::shared_ptr<BaseRecord> record = table.makeRecord();
assert(&record[arrayKey][3] == &record[elementKey3]);
assert(record.get(pointKey).getX() == record[xKey]);

Key inherits from FieldBase to allow a key for a dynamically-sized field to know its size without needing to specialize Key itself or hold a full Field object.

template<> class Key<Flag> : public lsst::afw::table::KeyBase<Flag>, public lsst::afw::table::FieldBase<Flag>

#include <Flag.h>

Key specialization for Flag.

Flag fields are special; their keys need to contain not only the offset to the integer element they share with other Flag fields, but also their position in that shared field.

Flag fields operate mostly like a bool field, but they do not support reference access, and internally they are packed into an integer shared by multiple fields so the marginal cost of each Flag field is only one bit.

template<typename T> class KeyBase

#include <KeyBase.h>

A base class for Key that allows subfield keys to be extracted for some field types.

template<typename U> class KeyBase<Array<U>>: #include <KeyBase.h>
KeyBase specialization for Arrays.

template<> class KeyBase<Flag>

#include <Flag.h>

A base class for Key that allows the underlying storage field to be extracted.

Subclassed by lsst::afw::table::Key< Flag >

template<typename Record1, typename Record2> struct Match

#include <Match.h>

Lightweight representation of a geometric match between two records.

This is a template so it can hold derived record classes without a lot of casting and properly use lsst::geom::Angle for the distance when we do spherical coordinate matches.

class MatchControl: #include <Match.h>
Pass parameters to algorithms that match list of sources

template<typename T> class OutputFunctorKey

#include <FunctorKey.h>

Base class for objects that can extract a value from a record, but are not a true Key themselves.

Objects that inherit from OutputFunctorKey can be passed to BaseRecord::get(), just as true Keys can, but the record will simply pass itself to OutputFunctorKey::get() and return the result.

Subclassed by lsst::afw::table::FunctorKey< T >

template<typename T> class PointKey : public lsst::afw::table::FunctorKey<lsst::geom::Point<T, 2>>: #include <aggregates.h>
A FunctorKey used to get or set a lsst::geom::Point from an (x,y) pair of int or double Keys.

class QuadrupoleKey : public lsst::afw::table::FunctorKey<lsst::afw::geom::ellipses::Quadrupole>: #include <aggregates.h>
A FunctorKey used to get or set a geom::ellipses::Quadrupole from a tuple of constituent Keys.

template<typename T> class ReferenceFunctorKey

#include <FunctorKey.h>

Base class for objects that can return a non-const reference to part of a record, but are not a true Key

Objects that inherit from ReferenceFunctorKey can be passed to BaseRecord::operator[], just as true Keys can, but the record will simply pass itself to ReferenceFunctorKey::getReference().

Note: We’d combine this with the ConstReferenceFunctorKey interface if it weren’t for the fact that we can’t pass multiple template arguments to a Swig macro if either contains commas, and we’d need that to wrap a combined interface base class.

class Schema

#include <Schema.h>

Defines the fields and offsets for a table.

Schema behaves like a container of SchemaItem objects, mapping a descriptive Field object with the Key object used to access record and ColumnView values. A Schema is the most important ingredient in creating a table.

Because offsets for fields are assigned when the field is added to the Schema, Schemas do not support removing fields, though they do allow renaming.

Field names in Schemas are expected to be underscore-separated names (e.g. ‘a_b_c’, but see afwTableFieldNames for the full conventions, including when to use underscores vs. CamelCase). The SubSchema class and Schema::operator[] provide a heirarchical interface to these names, but are implemented entirely as string splitting/joining operations that ultimately forward to member functions that operate on the fully-qualified field name, so there is no requirement that names be separated by underscores, and no performance advantage to using a SubSchema.

A SchemaMapper object can be used to define a relationship between two Schemas to be used when copying values from one table to another or loading/saving selected fields to disk.

Schema uses copy-on-write, and hence should always be held by value rather than smart pointer. When creating a Python interface, functions that return Schema by const reference should be converted to return by value (returnCopy) to ensure proper memory management and encapsulation.

template<typename T> struct SchemaItem: #include <SchemaImpl.h>
A simple pair-like struct for mapping a Field (name and description) with a Key (used for actual data access).

class SchemaMapper

#include <SchemaMapper.h>

A mapping between the keys of two Schemas, used to copy data between them.

SchemaMapper is initialized with its input Schema, and contains member functions to add mapped or unmapped fields to the output Schema.

class ShapeSlotDefinition : public lsst::afw::table::SlotDefinition: #include <slots.h>
SlotDefinition specialization for shapes.

class SimpleRecord : public lsst::afw::table::BaseRecord

#include <Simple.h>

Record class that must contain a unique ID field and a celestial coordinate field.

SimpleTable / SimpleRecord are intended to be the base class for records representing astronomical objects. In additional to the minimal schema and the convenience accessors it allows, a SimpleTable may hold an IdFactory object that is used to assign unique IDs to new records.

Subclassed by lsst::afw::table::SourceRecord

class SimpleTable : public lsst::afw::table::BaseTable

#include <Simple.h>

Table class that must contain a unique ID field and a celestial coordinate field.

Record class that must contain a unique ID field and a celestial coordinate field.

SimpleTable / SimpleRecord are intended to be the base class for records representing astronomical objects. In additional to the minimal schema and the convenience accessors it allows, a SimpleTable may hold an IdFactory object that is used to assign unique IDs to new records.

Subclassed by lsst::afw::table::SourceTable

class SlotDefinition

#include <slots.h>

Base class for helper classes that define slots on SourceTable/SourceRecord.

Each type of slot corresponds to a subclass of SlotDefinition, and each actual slot corresponds to a particular field name prefix. For instance, to look up the centroid slot, we look for fields named “slot_Centroid_x” and “slot_Centroid_y”. Instead of actually naming a particular field that, however, we use Schema’s alias mechanism (see AliasMap) to make these field name lookups resolve to the name of other fields. The actual definition of the slots is thus managed by the Schema’s AliasMap, though a SourceTable object will cache Keys for the various slots to make sure accessing slot values is efficient (more precisely, when you set an alias related to a slot on an AliasMap, any table it corresponds to will receive a notification that it should update its Keys). These cached Keys are actually stored within the SlotDefinition (as data members of derived classes).

Note that the uncertainty and failure flag components of slots are not required; a slot may have only a measurement defined, or a measurement and either one of these (but not both). A slot may not have only an uncertainty and/or a a failure flag, however.

A SlotDefinition instance is not just an internal object used by SourceTable; it can also be used to inspect the slots via SourceTable::getXxxSlot(), which is now the preferred way to access the Keys that slots correspond to. SlotDefinition objects should only be constructed by SourceTable, however.

Subclassed by lsst::afw::table::CentroidSlotDefinition, lsst::afw::table::FluxSlotDefinition, lsst::afw::table::ShapeSlotDefinition

struct SlotSuite

#include <slots.h>

An aggregate containing all of the current slots used in SourceTable.

This is essentially for internal use by SourceTable only; it is defined here to keep the source code for the slot mechanism in one place as much as possible.

template<typename RecordT> class SortedCatalogT : public lsst::afw::table::CatalogT<RecordT>

#include <SortedCatalog.h>

Custom catalog class for record/table subclasses that are guaranteed to have an ID, and should generally be sorted by that ID.

For a record/table pair to be used with SortedCatalogT, the table class must provide a static getIdKey() member function that returns the key to the ID field.

Subclassed by lsst::afw::table::ExposureCatalogT< RecordT >

class SourceRecord : public lsst::afw::table::SimpleRecord

#include <Source.h>

Record class that contains measurements made on a single exposure.

Sources provide four additions to SimpleRecord / SimpleRecord:

Specific fields that must always be present, with specialized getters. The schema for a SourceTable should always be constructed by starting with the result of SourceTable::makeMinimalSchema.
A shared_ptr to a Footprint for each record.
A system of aliases (called slots) in which a SourceTable instance stores keys for particular measurements (a centroid, a shape, and a number of different fluxes) and SourceRecord uses this keys to provide custom getters and setters. These are not separate fields, but rather aliases that can point to custom fields. See the SlotDefinition hierarchy for more information.

class SourceTable : public lsst::afw::table::SimpleTable

#include <Source.h>

Table class that contains measurements made on a single exposure.

Record class that contains measurements made on a single exposure.

Sources provide four additions to SimpleRecord / SimpleRecord:

Specific fields that must always be present, with specialized getters. The schema for a SourceTable should always be constructed by starting with the result of SourceTable::makeMinimalSchema.
A shared_ptr to a Footprint for each record.
A system of aliases (called slots) in which a SourceTable instance stores keys for particular measurements (a centroid, a shape, and a number of different fluxes) and SourceRecord uses this keys to provide custom getters and setters. These are not separate fields, but rather aliases that can point to custom fields. See the SlotDefinition hierarchy for more information.

class SubSchema

#include <Schema.h>

A proxy type for name lookups in a Schema.

Elements of schema names are assumed to be separated by underscores (“a_b_c”); an incomplete lookup is one that does not resolve to a field. Not that even complete lookups can have nested names; a Point field, for instance, has “x” and “y” nested names.

This proxy object is implicitly convertible to both the appropriate Key type and the appropriate Field type, if the name is a complete one, and supports additional find() operations for nested names.

SubSchema is implemented as a proxy that essentially calls Schema::find after concatenating strings. It does not provide any performance advantage over using Schema::find directly. It is also lazy, so looking up a name prefix that does not exist within the schema is not considered an error until the proxy is used.

Some examples:

Schema schema(false);
Key<int> a_i = schema.addField<int>("a_i", "integer field");
Key< Point<double> > a_p = schema.addField< Point<double> >("a_p", "point field");

assert(schema["a_i"] == a_i);
SubSchema a = schema["a"];
assert(a["i"] == a_i);
Field<int> f_a_i = schema["a_i"];
assert(f_a_i.getDoc() == "integer field");
assert(schema["a_i"] == "a_i");
assert(schema.find("a_p_x") == a_p.getX());

namespace detail

Functions

int indexCovariance(int i, int j)

Defines the ordering of packed covariance matrices.

This storage is equivalent to LAPACK ‘UPLO=U’.

int computeCovariancePackedSize(int size): Defines the packed size of a covariance matrices.

struct FlagExtractor: #include <BaseColumnView.h>
Functor to compute a flag bit, used to create an ndarray expression template for flag columns.

struct RecordData

#include <BaseTable.h>

Helper struct that contains the information passed from BaseTable to BaseRecord at construction.

This can’t be a nested class of either of those two classes for dependency reasons, but it should nevertheless be considered opaque by all derived Table and Record classes.

class SchemaImpl

#include <SchemaImpl.h>

A private implementation class to hide the messy details of Schema.

This can’t be a real pimpl class, because some of the most important functionality is in the forEach function, a templated function we can’t explicitly instantiate in a source file. But putting all the details here draws a clear line between what users should look at (Schema) and what they shouldn’t (this).

Because Schema holds SchemaImpl by shared pointer, one SchemaImpl can be shared between multiple Schemas (and SubSchemas), which implement copy-on-write by creating a new SchemaImpl if the pointer they have isn’t unique when they are modified.

class SchemaMapperImpl

#include <SchemaMapperImpl.h>

A private implementation class to hide the messy details of SchemaMapper.

This class is very similar in spirit to SchemaImpl; look there for more information (though SchemaMapper is not copy-on-write).

namespace io

Functions

LSST_EXCEPTION_TYPE(PersistenceError, lsst::pex::exceptions::IoError, lsst::afw::table::io::PersistenceError)

An exception thrown when problems occur during persistence. An exception thrown when an InputArchive’s contents do not make sense.

This is the exception thrown by the LSST_ARCHIVE_ASSERT macro.

struct ArchiveIndexSchema

#include <ArchiveIndexSchema.h>

Schema for the index catalog that specifies where objects are stored in the data catalogs.

Each row in the index catalog corresponds to a combination of an object and a data catalog, and contains the range of rows used by that object in the catalog (in the ‘row0’ and ‘nrows’ fields). The ‘cat.archive’ field indicates which catalog in the archive the index entry refers to (where 0 is the index itself, and 1 is the first data catalog), and ‘cat.persistable’ refers to which catalog the index entry refers to from the perspective of the saved object.

An object may thus have more than one row in the index, but the ‘id’ and ‘name’ fields must be the same for all index entires that correspond to a single object. These contain, respectively, the unique ID returned by OutputArchive::put and the name returned by Persistable::getPersistenceName() and used by InputArchive to look up a PersistableFactory in the registry.

class CatalogVector : public std::vector<BaseCatalog>

#include <CatalogVector.h>

A vector of catalogs used by Persistable.

This should really be thought of as just a typedef, but we can’t forward-declare a typedef to a template class, so we use a trivial subclass instead. That may seem like a dirty hack, but it has a huge benefit in keeping compilation times down: it keeps us from needing to include Catalog.h in Persistable.h, which otherwise would pull all of the afw::table headers into the header of any class that wanted to make use of a Persistable subclass.

CatalogVector is also used in such limited circumstances that we don’t really have to worry about the fact that std::vector doesn’t have a virtual destructor and that we only have default and copy constructors for CatalogVector.

class FitsColumnReader: #include <FitsSchemaInputMapper.h>
Polymorphic reader interface used to read different kinds of objects from one or more FITS binary table columns.

class FitsReader

#include <FitsReader.h>

A utility class for reading FITS binary tables.

FitsReader itself provides the implementation for reading standard FITS binary tables (with a limited subset of FITS column types), but it also allows subclasses to be used instead, depending on what’s actually in the FITS file. If the FITS header has the key “AFW_TABLE” with a value other than “BASE”, FitsReader::apply consults a registry of subclasses to retreive one corresponding to that key. This means the type of records/tables loaded correctly depends on the file itself, rather than the caller. For instance, if you load a FITS table corresponding to a saved SourceCatalog using BaseCatalog::readFits, you’ll actually get a BaseCatalog whose record are actually SourceRecords and whose table is actually a SourceTable. On the other hand, if you try to load a non-Source FITS table into a SourceCatalog, you’ll get an exception when it tries to dynamic_cast the table to a SourceTable.

class FitsSchemaInputMapper

#include <FitsSchemaInputMapper.h>

A class that describes a mapping from a FITS binary table to an afw::table Schema.

A FitsSchemaInputMapper is created every time a FITS binary table is read into an afw::table catalog, allowing limited customization of the mapping between on-disk FITS table columns an in-memory fields by subclasses of BaseTable.

The object is constructed from a daf::base::PropertyList that represents the FITS header, which is used to populate a custom container of FitsSchemaItems. These can then be retrieved by name or column number via the find() methods, allowing the user to create custom readers for columns or groups of columns via addColumnReader(). They can also be removed from the “regular” fields via the erase() method. Those regular fields are filled in by the finalize() method, which automatically generates mappings for any FitsSchemaItems that have not been removed by calls to erase(). Once finalize() has been called, readRecord() may be called repeatedly to read FITS rows into record objects according to the mapping that has been defined.

struct FitsSchemaItem: #include <FitsSchemaInputMapper.h>
A structure that describes a field as a collection of related strings read from the FITS header.

class FitsWriter

#include <FitsWriter.h>

Writer object for FITS binary tables.

FitsWriter itself provides support for writing FITS binary tables from base containers. Derived record/base pairs should derive their own writer from FitsWriter and reimplement BaseTable::makeFitsWriter to return it. Subclasses will usually delegate most of the work back to FitsWriter.

class InputArchive

#include <InputArchive.h>

A multi-catalog archive object used to load table::io::Persistable objects.

An InputArchive can be constructed directly from the catalogs produced by OutputArchive, or more usefully, read from a multi-extension FITS file.

See: OutputArchive

class OutputArchive

#include <OutputArchive.h>

A multi-catalog archive object used to save table::io::Persistable objects.

OutputArchive should generally be used directly only by objects that do not themselves inherit from Persistable, but contain many objects that do (such as Exposure). It provides an interface for adding objects to the archive (put()), transforming them into catalogs that can be retrieved directly or written to a FITS file. The first catalog is an index that indicates which rows of the subsequent catalogs correspond to each object.

See getIndexCatalog() for a more detailed description of the index.

class OutputArchiveHandle

#include <OutputArchive.h>

An object passed to Persistable::write to allow it to persist itself.

OutputArchiveHandle provides an interface to add additional catalogs and save nested Persistables to the same archive.

class Persistable

#include <Persistable.h>

A base class for objects that can be persisted via afw::table::io Archive classes.

Inheriting from Persistable provides a public API for reading/writing individual objects to FITS that is fully defined in the base class, with derived classes only needing to implement persistence to catalogs. It is expected that objects that contain multiple persistables (such as Exposures) will create their own InputArchives and OutputArchives, and use these to avoid writing the same object twice (which would otherwise be a big concern for future objects like ExposureCatalog and CoaddPsf).

Generally speaking, an abstract base class that inherits from Persistable should also inherit from PersistableFacade<Base>. A concrete class that inherits (possibly indirectly) from Persistable should inherit from PersistableFacade<Derived> (though this just provides a slightly nicer interface to users), implement isPersistable(), getPersistenceName(), getPythonModule(), and write(), and define a subclass of PersistenceFactory. Inheritance from PersistableFacade should always precede inheritance from Persistable.

Persistable has no pure virtual member functions, and instead contains a default implementation that throws LogicError when the user attempts to save an object for which persistence has not actually been implemented.

Subclassed by lsst::afw::math::Function< Kernel::Pixel >, lsst::afw::cameraGeom::DetectorCollection, lsst::afw::cameraGeom::TransformMap, lsst::afw::detection::Footprint, lsst::afw::geom::Transform< FromEndpoint, ToEndpoint >, lsst::afw::math::BoundedField, lsst::afw::math::Function< ReturnT >, lsst::afw::math::Kernel, lsst::meas::modelfit::Mixture, lsst::afw::geom::Transform< afw::geom::Point2Endpoint, afw::geom::GenericEndpoint >

template<typename T> class PersistableFacade

#include <Persistable.h>

A CRTP facade class for subclasses of Persistable.

Derived classes should generally inherit from PersistableFacade at all levels, but only inherit from Persistable via the base class of each hierarchy. For example, with Psfs:

class Psf: public PersistableFacade<Psf>, public Persistable { ... };
class DoubleGaussianPsf: public PersistableFacade<DoubleGaussianPsf>, public Psf { ... };

Inheriting from PersistableFacade is not required for any classes but the base of each hierarchy, but doing so can save users from having to do some dynamic_casts.

Note: PersistableFacade should usually be the first class in a list of base classes; if it appears after a base class that inherits from different specialization of PersistableFacade, those base class member functions will hide the desired ones.

class PersistableFactory

#include <Persistable.h>

A base class for factory classes used to reconstruct objects from records.

Classes that inherit from Persistable should also subclass PersistableFactory, and instantiate exactly one instance of the derived factory with static duration (usually the class and instance are both defined in an anonymous namespace in a source file).

Subclassed by lsst::meas::algorithms::KernelPsfFactory< T, K >

namespace python

Functions

template<typename T> void declarePersistableFacade(pybind11::module &module, std::string const &suffix)

Wraps an instantiation of PersistableFacade.

Pybind11 shall assume that PersistableFacade is managed using std::shared_ptr, as this is required for compatibility with existing subclasses of PersistableFacade. This means that wrapping will only work if new classes also use std::shared_ptr as their holder type.

Template Parameters

T: The type of object this PersistableFacade is for.

Parameters

module: The pybind11 module that shall contain PersistableFacade<T>
suffix: A string to disambiguate this class from other PersistableFacades. The Python name of this class shall be PersistableFacade<suffix>.

template<typename Class, typename ...Args> void addPersistableMethods(pybind11::class_<Class, Args...> &cls)

Add table::io::Persistable and PersistableFacade methods to the pybind11 wrapper for a class

Use this instead of declarePersistableFacade to avoid circular import issues in Python; it allows your class to be used without importing lsst.afw.table.

Use as follows:

When declaring the pybind11 class that wraps your Class do not list table::io::PersistableFacade<Class> and table::io::Persistable as subclasses.
Call this function to wrap the methods that make your object persistable.

namespace python

Typedefs

using PyCatalog = pybind11::class_<CatalogT<Record>, std::shared_ptr<CatalogT<Record>>>

using PyColumnView = pybind11::class_<ColumnViewT<Record>, std::shared_ptr<ColumnViewT<Record>>, BaseColumnView>

using PySortedCatalog = pybind11::class_<SortedCatalogT<Record>, std::shared_ptr<SortedCatalogT<Record>>, CatalogT<Record>>

Functions

template<typename T, typename Record> ndarray::Array<typename Field<T>::Value const, 1, 1> _getArrayFromCatalog(CatalogT<Record> const &catalog, Key<T> const &key)

Extract a column from a potentially non-contiguous Catalog.

Parameters

catalog: Catalog
key: Key to column to extract

template<typename Record> ndarray::Array<double const, 1, 1> _getArrayFromCatalog(CatalogT<Record> const &catalog, Key<lsst::geom::Angle> const &key)

Parameters

catalog: Catalog
key: Key to column to extract

template<typename T, typename Record> void declareCatalogOverloads(PyCatalog<Record> &cls)

Declare field-type-specific overloaded catalog member functions for one field type

Template Parameters

T: Field type.
Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

[in] cls: Catalog pybind11 class.

template<typename Record> PyCatalog<Record> declareCatalog(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Wrap an instantiation of lsst::afw::table::CatalogT<Record>.

In addition to calling this method you must call addCatalogMethods on the class object in Python.

Template Parameters

Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

[in] wrappers: Package manager class will be added to.
[in] name: Name prefix of the record type, e.g. “Base” or “Simple”.
[in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

template<typename Record> PyColumnView<Record> declareColumnView(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Declare member and static functions for a given instantiation of lsst::afw::table::ColumnViewT<RecordT>.

Template Parameters

Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

[in] wrappers: Package manager class will be added to.
[in] name: Name prefix of the record type, e.g. “Base” or “Simple”.
[in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

template<typename Record> PySortedCatalog<Record> declareSortedCatalog(utils::python::WrapperCollection &wrappers, std::string const &name, bool isBase = false)

Wrap an instantiation of lsst::afw::table::SortedCatalogT<Record>.

In addition to calling this method (which also instantiates and wraps the CatalogT base class), you must call addCatalogMethods on the class object in Python.

Template Parameters

Record: Record type, e.g. BaseRecord or SimpleRecord.

Parameters

[in] wrappers: Package manager class will be added to.
[in] name: Name prefix of the record type, e.g. “Base” or “Simple”.
[in] isBase: Whether this instantiation is only being used as a base class (used to set the class name).

Navigation

Namespace lsst::afw::table¶