lsst::gauss2d::GaussianEvaluator< T, Data, Indices > Class Template Reference

A class that evaluates 2D Gaussians and renders them in images. More...

#include <evaluate.h>

Inheritance diagram for lsst::gauss2d::GaussianEvaluator< T, Data, Indices >:

Public Types
typedef Image< T, Data >	DataT
typedef ImageArray< T, Data >	ImageArrayT
typedef Image< idx_type, Indices >	IndicesT

Public Member Functions
	GaussianEvaluator (int x=0, const std::shared_ptr< const ConvolvedGaussians > gaussians=nullptr)
	GaussianEvaluator (const std::shared_ptr< const ConvolvedGaussians > gaussians, const std::shared_ptr< const Image< T, Data > > data=nullptr, const std::shared_ptr< const Image< T, Data > > sigma_inv=nullptr, const std::shared_ptr< Image< T, Data > > output=nullptr, const std::shared_ptr< Image< T, Data > > residual=nullptr, const std::shared_ptr< ImageArrayT > grads=nullptr, const std::shared_ptr< const Image< idx_type, Indices > > grad_param_map=nullptr, const std::shared_ptr< const Image< T, Data > > grad_param_factor=nullptr, const std::shared_ptr< const Image< idx_type, Indices > > extra_param_map=nullptr, const std::shared_ptr< const Image< T, Data > > extra_param_factor=nullptr, const std::shared_ptr< const Image< T, Data > > background=nullptr)
	Construct a GaussianEvaluator, inferring outputs from inputs.
	~GaussianEvaluator () override=default
Data const &	IMAGE_NULL_CONST () const
Indices const &	INDICES_NULL_CONST () const
ImageArray< T, Data > const &	IMAGEARRAY_NULL_CONST () const
const CoordinateSystem &	get_coordsys () const
size_t	get_n_cols () const
size_t	get_n_rows () const
size_t	get_size () const
double	loglike_pixel (bool to_add=false)
	Compute the model and/or log-likelihood and/or gradient (d(log-likelihood)/dx) and/or Jacobian (dmodel/dx) for a Gaussian mixture model.
std::string	repr (bool name_keywords=false, std::string_view namespace_separator=Object::CC_NAMESPACE_SEPARATOR) const override
	Return a full, callable string representation of this.
std::string	str () const override
	Return a brief, human-readable string representation of this.

Static Public Member Functions
static std::string_view	null_str (const std::string_view &namespace_separator)

Static Public Attributes
static constexpr std::string_view	CC_NAMESPACE_SEPARATOR = "::"
	The C++ namespace separator.
static constexpr std::string_view	NULL_STR_GENERAL = "None"
static constexpr std::string_view	PY_NAMESPACE_SEPARATOR = "."

Detailed Description

template<typename T, class Data, class Indices>
class lsst::gauss2d::GaussianEvaluator< T, Data, Indices >

A class that evaluates 2D Gaussians and renders them in images.

This class is designed for repeated re-evaluation of Gaussian mixture models by caching references to the inputs and outputs.

Template Parameters

T	The data type (e.g. float, int)
Data	The data array class
Indices	The index array class (usually a size_t array)

Definition at line 668 of file evaluate.h.

Member Typedef Documentation

DataT

template<typename T, class Data, class Indices>

typedef Image<T, Data> lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::DataT

Definition at line 670 of file evaluate.h.

ImageArrayT

template<typename T, class Data, class Indices>

typedef ImageArray<T, Data> lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::ImageArrayT

Definition at line 671 of file evaluate.h.

IndicesT

template<typename T, class Data, class Indices>

typedef Image<idx_type, Indices> lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::IndicesT

Definition at line 672 of file evaluate.h.

Constructor & Destructor Documentation

GaussianEvaluator() [1/2]

template<typename T, class Data, class Indices>

lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::GaussianEvaluator ( int x = 0, const std::shared_ptr< const ConvolvedGaussians > gaussians = nullptr )

inline

Definition at line 674 of file evaluate.h.

{}

GaussianEvaluator() [2/2]

template<typename T, class Data, class Indices>

lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::GaussianEvaluator ( const std::shared_ptr< const ConvolvedGaussians > gaussians, const std::shared_ptr< const Image< T, Data > > data = nullptr, const std::shared_ptr< const Image< T, Data > > sigma_inv = nullptr, const std::shared_ptr< Image< T, Data > > output = nullptr, const std::shared_ptr< Image< T, Data > > residual = nullptr, const std::shared_ptr< ImageArrayT > grads = nullptr, const std::shared_ptr< const Image< idx_type, Indices > > grad_param_map = nullptr, const std::shared_ptr< const Image< T, Data > > grad_param_factor = nullptr, const std::shared_ptr< const Image< idx_type, Indices > > extra_param_map = nullptr, const std::shared_ptr< const Image< T, Data > > extra_param_factor = nullptr, const std::shared_ptr< const Image< T, Data > > background = nullptr )

inline

Construct a GaussianEvaluator, inferring outputs from inputs.

Parameters

gaussians	N x 6 matrix of Gaussian parameters [cen_x, cen_y, flux, sigma_x, sigma_y, rho]
coordsys	Coordinate system for all images.
data	2D input Data matrix.
sigma_inv	2D inverse sigma (sqrt variance) map of the same size as data.
output	2D output matrix of the same size as ImageD.
residual	2D output matrix for residual ((data-model)/sigma) of the same size as data.
grads	Output for gradients. Can either an M x 1 vector or M x Data 3D Jacobian matrix, where M <= N x 6 to allow for condensing gradients based on grad_param_map.
grad_param_map	Nx6 matrix of indices of grad to add each gradient to. For example, if four gaussians share the same cen_x, one could set grad_param_map[0:4,0] = 0. All values must have index < grad.size().
grad_param_factor	Nx6 matrix of multiplicative factors for each gradient term. For example, if a Gaussian is a sub-component of a multi-Gaussian component with a total flux parameter but fixed ratios, as in multi-Gaussian Sersic models.
extra_param_map	Nx2 matrix of indices to add to an extra (meta)parameter. The first item is the index of the Gaussian to add and the second is the index of the metaparameter.
extra_param_factor	Nx3 matrix of multiplicative factors for each extra gradient term. The factors are ordered L, sigma_x, sigma_y.
background	A background model image. Only 1x1 (constant level) backgrounds are supported.

Definition at line 699 of file evaluate.h.

            : _gaussians(gaussians == nullptr ? GAUSSIANS_NULL : *gaussians),
              _gaussians_ptr(gaussians == nullptr ? nullptr : gaussians),
              _n_gaussians(_gaussians.size()),
              _do_output(output != nullptr),
              _is_sigma_image((sigma_inv != nullptr) && (sigma_inv->size() > 1)),
              _do_residual(residual != nullptr),
              _has_background(background != nullptr),
              _gradienttype((grads != nullptr && grads->size() > 0)
                                    ? (((grads->size() == 1) && ((*grads)[0].get_n_rows() == 1))
                                               ? GradientType::loglike
                                               : GradientType::jacobian)
                                    : GradientType::none),
              _do_extra(
                      extra_param_map != nullptr && extra_param_factor != nullptr
                      && (_gradienttype == GradientType::loglike || _gradienttype == GradientType::jacobian)),
              _backgroundtype(background != nullptr ? (_background->size() == 1 ? BackgroundType::constant
                                                                                : BackgroundType::none)
                                                    : BackgroundType::none),
              _get_likelihood((data != nullptr) && (sigma_inv != nullptr)),
              _data(data),
              _sigma_inv(sigma_inv),
              _output(output),
              _residual(residual),
              _grads(grads),
              _grad_param_map((_gradienttype == GradientType::none)
                                      ? nullptr
                                      : ((grad_param_map != nullptr)
                                                 ? grad_param_map
                                                 : detail::_param_map_default<Indices>(_gaussians.size()))),
              _grad_param_factor(
                      (_gradienttype == GradientType::none)
                              ? nullptr
                              : ((grad_param_factor != nullptr)
                                         ? grad_param_factor
                                         : detail::_param_factor_default<Data>(_gaussians.size()))),
              _extra_param_map((_gradienttype == GradientType::none)
                                       ? nullptr
                                       : ((extra_param_map != nullptr)
                                                  ? extra_param_map
                                                  : detail::_param_map_default<Indices>(_gaussians.size(),
                                                                                        N_EXTRA_MAP, 0))),
              _extra_param_factor((_gradienttype == GradientType::none)
                                          ? nullptr
                                          : ((extra_param_factor != nullptr)
                                                     ? extra_param_factor
                                                     : detail::_param_factor_default<Data>(
                                                               _gaussians.size(), N_EXTRA_FACTOR, 0.))),
              _grad_extra(_do_extra ? std::make_unique<detail::GradientsExtra<T, Data, Indices>>(
                                              *extra_param_map, *extra_param_factor, _grads, _n_gaussians)
                                    : nullptr),
              _grad_param_idx(_grad_param_map == nullptr ? std::vector<size_t>{} : _get_grad_param_idx()),
              _n_cols(_data == nullptr ? (_output == nullptr ? (_gradienttype == GradientType::jacobian
                                                                        ? (*_grads)[0].get_n_cols()
                                                                        : 0)
                                                             : _output->get_n_cols())
                                       : _data->get_n_cols()),
              _n_rows(_data == nullptr ? (_output == nullptr ? (_gradienttype == GradientType::jacobian
                                                                        ? (*_grads)[0].get_n_rows()
                                                                        : 0)
                                                             : _output->get_n_rows())
                                       : _data->get_n_rows()),
              _size(_n_cols * _n_rows),
              _coordsys(_data == nullptr ? (_output == nullptr ? (_gradienttype == GradientType::jacobian
                                                                          ? (*_grads)[0].get_coordsys()
                                                                          : COORDS_DEFAULT)
                                                               : _output->get_coordsys())
                                         : _data->get_coordsys()) {
        if (gaussians == nullptr) throw std::runtime_error("Gaussians can't be null");
        if (_has_background && background->size() > 1)
            throw std::runtime_error("Background model size can't be > 1");
        if (!(_n_cols > 0 && _n_rows > 0))
            throw std::runtime_error("Data can't have n_rows/cols == 0; "
                                     + std::to_string(output == nullptr));
        if (!_do_extra && ((extra_param_map != nullptr) || (extra_param_factor != nullptr))) {
            throw std::runtime_error(
                    "Must pass all of extra_param_map, extra_param_factor and grads"
                    " to compute extra gradients");
        }
        if (_get_likelihood) {
            // The case of constant variance per pixel
            if (_is_sigma_image) {
                if (_n_cols != _sigma_inv->get_n_cols() || _n_rows != _sigma_inv->get_n_rows()) {
                    throw std::runtime_error("Data matrix dimensions [" + std::to_string(_n_cols) + ','
                                             + std::to_string(_n_rows)
                                             + "] don't match inverse variance dimensions ["
                                             + std::to_string(_sigma_inv->get_n_cols()) + ','
                                             + std::to_string(_sigma_inv->get_n_rows()) + ']');
                }
                if (_sigma_inv->get_coordsys() != _data->get_coordsys()) {
                    throw std::runtime_error("sigma_inv coordsys=" + _sigma_inv->get_coordsys().str()
                                             + "!= coordsys=" + get_coordsys().str());
                }
            }
        } else if ((data != nullptr) || (sigma_inv != nullptr)) {
            throw std::runtime_error("Passed only one non-null data/sigma_inv");
        }
        // TODO: Add more coordsys compatibility checks
        if (_gradienttype != GradientType::none) {
            const size_t n_gpm = _grad_param_map->get_n_rows();
            const size_t n_gpf = _grad_param_factor->get_n_rows();
 
            if ((n_gpm != _n_gaussians) || (n_gpf != _n_gaussians)) {
                throw std::invalid_argument("nrows for grad_param_map,factor=" + std::to_string(n_gpm) + ","
                                            + std::to_string(n_gpf)
                                            + " != n_gaussians=" + std::to_string(_n_gaussians));
            }
 
            if ((_grad_param_map->get_n_cols() != N_PARAMS_GAUSS2D)
                || (_grad_param_factor->get_n_cols() != N_PARAMS_GAUSS2D)) {
                throw std::invalid_argument("n_cols for grad_param_map,factor=" + std::to_string(n_gpm) + ","
                                            + std::to_string(n_gpf));
            }
 
            const size_t n_grad = (_gradienttype == GradientType::jacobian) ? _grads->size()
                                                                            : (_grads->at(0).get_n_cols());
            size_t idx_g_max = 0;
            size_t idx_e_gauss_max = 0;
            size_t idx_e_param_max = 0;
            for (size_t g = 0; g < _n_gaussians; ++g) {
                for (size_t p = 0; p < N_PARAMS_GAUSS2D; ++p) {
                    auto value = _grad_param_map->get_value_unchecked(g, p);
                    if (value > idx_g_max) idx_g_max = value;
                }
                auto value = _extra_param_map->get_value_unchecked(g, 0);
                if (value > idx_e_gauss_max) idx_e_gauss_max = value;
                value = _extra_param_map->get_value_unchecked(g, 1);
                if (value > idx_e_param_max) idx_e_param_max = value;
            }
            if (!((idx_e_gauss_max < _n_gaussians) && (idx_e_param_max < n_grad))) {
                throw std::invalid_argument(" max extra_param_map[0]=" + std::to_string(idx_e_gauss_max)
                                            + " !< n_gaussians=" + std::to_string(_n_gaussians) + " and/or "
                                            + " max extra_param_map[1]=" + std::to_string(idx_e_param_max)
                                            + " !< n_grad=" + std::to_string(n_grad));
            }
            if (!(idx_g_max < n_grad)) {
                throw std::invalid_argument("max grad_param_map,extra_param_map[1]="
                                            + std::to_string(idx_g_max)
                                            + " !< n_grad=" + std::to_string(n_grad));
            }
        }
        if (_gradienttype == GradientType::loglike) {
            if (!_get_likelihood) {
                throw std::runtime_error(
                        "Can't compute likelihood gradient without computing likelihood;"
                        " did you pass data and sigma_inv arrays?");
            }
        } else if (_gradienttype == GradientType::jacobian) {
            // This should never happen because the ImageArray constructor requires identical dimensions, but
            // anyway
            size_t idx_jac = 0;
            for (const auto& jac_img : *_grads) {
                if (!(jac_img->get_n_rows() == _n_rows && jac_img->get_n_cols() == _n_cols)) {
                    throw std::runtime_error("grads[0] matrix dimensions [" + std::to_string(_n_cols) + ','
                                             + std::to_string(_n_rows)
                                             + "] don't match Jacobian matrix (grads["
                                             + std::to_string(idx_jac) + "]) dimensions ["
                                             + std::to_string(jac_img->get_n_cols()) + ','
                                             + std::to_string(jac_img->get_n_rows()) + ']');
                }
            }
        }
    }

~GaussianEvaluator()

template<typename T, class Data, class Indices>

lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::~GaussianEvaluator ( )

overridedefault

Member Function Documentation

get_coordsys()

template<typename T, class Data, class Indices>

const CoordinateSystem & lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::get_coordsys ( ) const

inline

Definition at line 878 of file evaluate.h.

{ return _coordsys; }

get_n_cols()

template<typename T, class Data, class Indices>

size_t lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::get_n_cols ( ) const

inline

Definition at line 879 of file evaluate.h.

{ return (_n_cols); }

get_n_rows()

template<typename T, class Data, class Indices>

size_t lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::get_n_rows ( ) const

inline

Definition at line 880 of file evaluate.h.

{ return (_n_rows); }

get_size()

template<typename T, class Data, class Indices>

size_t lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::get_size ( ) const

inline

Definition at line 881 of file evaluate.h.

{ return (_size); }

IMAGE_NULL_CONST()

template<typename T, class Data, class Indices>

Data const & lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::IMAGE_NULL_CONST ( ) const

inline

Definition at line 874 of file evaluate.h.

{ return this->_data_null_const; }

IMAGEARRAY_NULL_CONST()

template<typename T, class Data, class Indices>

ImageArray< T, Data > const & lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::IMAGEARRAY_NULL_CONST ( ) const

inline

Definition at line 876 of file evaluate.h.

{ return this->_data_array_null_const; }

INDICES_NULL_CONST()

template<typename T, class Data, class Indices>

Indices const & lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::INDICES_NULL_CONST ( ) const

inline

Definition at line 875 of file evaluate.h.

{ return this->_indices_null_const; }

loglike_pixel()

template<typename T, class Data, class Indices>

double lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::loglike_pixel ( bool to_add = false )

inline

Compute the model and/or log-likelihood and/or gradient (d(log-likelihood)/dx) and/or Jacobian (dmodel/dx) for a Gaussian mixture model.

This function calls a series of templated functions with explicit instantiations. This is solely for the purpose of avoiding having to manually write a series of nested conditionals. My hope is that the templating will insert no-op functions wherever there's nothing to do instead of a needless branch inside each pixel's loop, and that the compiler will actually inline everything for maximum performance. Whether that actually happens or not is anyone's guess.

TODO: Consider override to compute LL and Jacobian, even if it's only useful for debug purposes.

Returns

The log likelihood.

Definition at line 897 of file evaluate.h.

                                              {
        const OutputType output_type
                = this->_do_output ? (to_add ? OutputType::add : OutputType::overwrite) : OutputType::none;
        return output_type == OutputType::overwrite
                       ? loglike_gaussians_pixel_output<OutputType::overwrite>()
                       : (output_type == OutputType::add
                                  ? loglike_gaussians_pixel_output<OutputType::add>()
                                  : loglike_gaussians_pixel_output<OutputType::none>());
    }

null_str()

static std::string_view lsst::gauss2d::Object::null_str ( const std::string_view & namespace_separator )

inlinestaticinherited

Definition at line 49 of file object.h.

                                                                              {
        return namespace_separator == CC_NAMESPACE_SEPARATOR ? "nullptr" : NULL_STR_GENERAL;
    }

repr()

template<typename T, class Data, class Indices>

std::string lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::repr ( bool name_keywords = false, std::string_view namespace_separator = Object::CC_NAMESPACE_SEPARATOR ) const

inlineoverridevirtual

Return a full, callable string representation of this.

Parameters

name_keywords	Whether to prefix arguments with "{name}=", where name is the arg name in the header (as with keyword arguments in Python).
namespace_separator	The string to use to delimit namespaces, i.e. :: in C++ and . in Python.

Returns

A callable string representation of this, which should return an an identical object to this.

Note

The representation with name_keywords=false must be callable in C++. The representation with name_keywords=true should be callable in Python, if there are any bindings.

Implements lsst::gauss2d::Object.

Definition at line 907 of file evaluate.h.

                                                                                                       {
        std::string null = namespace_separator == Object::CC_NAMESPACE_SEPARATOR ? "nullptr" : "None";
        // These are sadly just to keep formatting aligned nicely
        auto is_kw = name_keywords;
        auto name_sep = namespace_separator;
        std::string c = ", ";
        std::string rval = (  // I really want this on a separate line; I'd also prefer single indent, but...
                type_name_str<GaussianEvaluator>(false, name_sep) + "("  // make clang-format align nicely
                + (is_kw ? "gaussians=" : "") + repr_ptr(_gaussians_ptr, is_kw, name_sep) + ", "  //
                + (is_kw ? "data=" : "") + repr_ptr(_data, is_kw, name_sep) + ", "                //
                + (is_kw ? "sigma_inv=" : "") + repr_ptr(_sigma_inv, is_kw, name_sep) + ", "      //
                + (is_kw ? "output=" : "") + repr_ptr(_output, is_kw, name_sep) + ", "            //
                + (is_kw ? "residual=" : "") + repr_ptr(_residual, is_kw, name_sep) + ", "        //
                + (is_kw ? "grads=" : "") + repr_ptr(_grads, is_kw, name_sep) + ", "              //
                + (is_kw ? "grad_param_map=" : "") + repr_ptr(_grad_param_map, is_kw, name_sep) + ", "
                + (is_kw ? "grad_param_factor=" : "") + repr_ptr(_grad_param_factor, is_kw, name_sep) + c
                + (is_kw ? "extra_param_map=" : "") + repr_ptr(_extra_param_map, is_kw, name_sep) + ", "
                + (is_kw ? "extra_param_factor=" : "") + repr_ptr(_extra_param_factor, is_kw, name_sep) + c
                + (is_kw ? "background=" : "") + repr_ptr(_background, is_kw, name_sep) + ")");
        return rval;
    }

str()

template<typename T, class Data, class Indices>

std::string lsst::gauss2d::GaussianEvaluator< T, Data, Indices >::str ( ) const

inlineoverridevirtual

Return a brief, human-readable string representation of this.

Implements lsst::gauss2d::Object.

Definition at line 929 of file evaluate.h.

                                   {
        std::string c = ", ";
        // The comments force clang-format to keep to a more readable one var per line
        std::string rval = (                                                                 //
                type_name_str<GaussianEvaluator>(true) + "("                                 //
                + "gaussians=" + str_ptr(_gaussians_ptr) + c                                 //
                + "do_extra=" + std::to_string(_do_extra) + c                                //
                + "do_output=" + std::to_string(_do_output) + c                              //
                + "do_residual=" + std::to_string(_do_residual) + c                          //
                + "has_background=" + std::to_string(_has_background) + c                    //
                + "is_sigma_image=" + std::to_string(_is_sigma_image) + c                    //
                + "backgroundtype=" + std::to_string(static_cast<int>(_backgroundtype)) + c  //
                + "get_likelihood=" + std::to_string(_get_likelihood) + c                    //
                + "data=" + str_ptr(_data) + c                                               //
                + "sigma_inv=" + str_ptr(_sigma_inv) + c                                     //
                + "output=" + str_ptr(_output) + c                                           //
                + "residual=" + str_ptr(_residual) + c                                       //
                + "grads=" + str_ptr(_grads) + c                                             //
                + "grad_param_map=" + str_ptr(_grad_param_map) + c                           //
                + "grad_param_factor=" + str_ptr(_grad_param_factor) + c                     //
                + "extra_param_map=" + str_ptr(_extra_param_map) + c                         //
                + "extra_param_factor=" + str_ptr(_extra_param_factor) + c                   //
                + "grad_extra=" + str_ptr(_grad_extra ? _grad_extra.get() : nullptr) + c     //
                + "grad_param_idx=" + to_string_iter(_grad_param_idx) + c                    //
                + "n_cols=" + std::to_string(_n_cols) + c                                    //
                + "n_rows=" + std::to_string(_n_rows) + c                                    //
                + "coordsys=" + _coordsys.str()                                              //
                + ")"                                                                        //
        );
        return rval;
    }

Member Data Documentation

CC_NAMESPACE_SEPARATOR

std::string_view lsst::gauss2d::Object::CC_NAMESPACE_SEPARATOR = "::"

staticconstexprinherited

The C++ namespace separator.

Definition at line 45 of file object.h.

NULL_STR_GENERAL

std::string_view lsst::gauss2d::Object::NULL_STR_GENERAL = "None"

staticconstexprinherited

Definition at line 46 of file object.h.

PY_NAMESPACE_SEPARATOR

std::string_view lsst::gauss2d::Object::PY_NAMESPACE_SEPARATOR = "."

staticconstexprinherited

Definition at line 47 of file object.h.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-10.0.0/Linux64/gauss2d/g9125e01d80+fcb1d3bbc8/include/lsst/gauss2d/evaluate.h