Namespace lsst::afw::table::io

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