wiki:SdqaRatingTutorial
Last modified 10 years ago Last modified on 03/18/2009 10:05:18 AM

SDQA Rating Tutorial

An SDQA Rating is basically the computed value of an SDQA Metric and its uncertainty. SDQA Metrics are diverse, predefined measures that characterize image quality; e.g., image statistics, astrometric and photometric figures of merit and associated errors, counts of various things, like extracted sources, etc.

This tutorial is for applications developers who want to modify their pipelines to compute SDQA Ratings and make them available to the SDQA Pipeline for subsequent processing and persistence in the database. The basic steps are to

  1. Identify the SDQA Metrics for which your pipeline will be computing SDQA Ratings.
  2. Create SDQA Rating objects and use them to contain the SDQA data.
  3. Package SDQA Rating objects into a SdqaRatingSet? object.
  4. Wrap the SdqaRatingSet? object in a PersistableSdqaRatingVector? object within your pipeline.py script, assign it a unique clipboard-dictionary name, and put it on the clipboard.
  5. Configure your pipeline's OutputStage? policy file.

1. Identify SDQA Metrics of Interest

The SDQA development team has compiled a number of SDQA Metrics for the LSST project. The compilation is far from complete and work on it continues.

The attributes of a SDQA metric are name, physical units, data type, and definition. A database record for each SDQA metric will be stored in the sdqa_Metric database table, and a corresponding record for associated SDQA thresholds will be stored in the sdqa_Threshold database table.

If the SDQA metric for which your pipeline will be computing SDQA ratings is not included in the Trac-wiki compilation, please contact a member of the SDQA development team and have them assign a name to your SDQA metric.

Finally, make sure that the SDQA metrics of interest have associated records in the sdqa_Metric and sdqa_Threshold tables of the test database you will be using.

2. Create SDQA Rating Objects

Once you know the SDQA metric's name, and have the computed value and its error (uncertainty), you can instantiate a SdqaRating? object for it in your source code and load data into it.

Creating SDQA Rating Objects in C++

The C++ source code for the SdqaRating class is in the SVN repository under

DMS/sdqa/trunk/src/SdqaRating.cc

A complete example that shows how to create an SdqaRating object is

DMS/sdqa/tests/SdqaRating_1.cc

The required header files are

#include "lsst/sdqa/SdqaRating.h"
#include "lsst/pex/exceptions.h"

The name space for the SdqaRating class is

namespace sdqa = lsst::sdqa;

There is a constructor that creates an SdqaRating object in one step; for example,

sdqa::SdqaRating sr(string("img.psfFwhm"),  static_cast<double>(4.9),  static_cast<double>(0.13),  sdqa::SdqaRating::AMP)

The first argument is the SDQA Metric name, the second is the associated SDQA Rating value, the third is the value's uncertainty, and the fourth is an enum that identifies whether the value computed at the "FPA", "CCD", or "AMP" levels of image processing. The value and its uncertainty should be in the same physical units as defined for the associated SDQA Metric.

The above example tells the SDQA Pipeline to persist the SDQA Rating in the Science_Amp_Exposure SDQA_Rating_forScienceAmpExposure database table.

Creating SDQA Rating Objects in Python

Depending on your pipeline's particulars, you may wish to construct SDQA Rating objects in your pipeline.py script.

A complete example that shows how to do this is

DMS/sdqa/tests/SdqaRating_2.py

The required Python import statements are

import lsst.sdqa as sdqa
from lsst.pex.exceptions import LsstCppException

An example Python function for creating an SDQA Rating associated with SDQA Metric "photResponse" is

    def photResponseSdqaRating(value, error):
        sr = sdqa.SdqaRating("photResponse", value, error, sdqa.SdqaRating.CCD)

The first argument is the SDQA Metric name, the second is the associated SDQA Rating value, the third is the value's uncertainty, and the fourth is a C++ enum that identifies whether the value computed at the "FPA", "CCD", or "AMP" levels of image processing. The value and its uncertainty should be in the same physical units as defined for the associated SDQA Metric.

3. Package SDQA Rating Objects into a SdqaRatingSet? Object

In C++

  sdqa::SdqaRatingSet srs;
  int NVEC = 1;

  srs.clear();
  srs.reserve(NVEC);
  for (int i = 0; i < NVEC; ++i) {
      sdqa::SdqaRating::Ptr ptr(new sdqa::SdqaRating(n1, static_cast<double>(v1), e1, t1));
      srs.push_back(ptr);
  }

In Python

   import lsst.sdqa as sdqa

   sdqaRatings = sdqa.SdqaRatingSet()
   sdqaRatings.append(sdqa.SdqaRating("photResponse", photResponse,  photResponseErr, sdqa.SdqaRating.CCD))

4. Put PersistableSdqaRatingVector? Object on Clipboard in Pipeline.py Script

First, create a PersistableSdqaRatingVector? object in your pipeline.py script to wrap the SdqaRatingSet? object.

If you created your SdqaRatingSet? in C++, the getSdqaRatings() method returns the SdqaRatingSet? object:

persistableSdqaRatingVector = sdqa.PersistableSdqaRatingVector.getSdqaRatings()

If you created your SdqaRatingSet? in pipeline.py, then there is a PersistableSdqaRatingVector? constructor that can be used:

persistableSdqaRatingVector = sdqa.PersistableSdqaRatingVector(sdqaRatings)

Next, choose a unique clipboard-dictionary name for your PersistableSdqaRatingVector? object; e.g., "psfRatings". Finally, add the PersistableSdqaRatingVector? object to the clipboard.

self.activeClipboard.put("psfRatings", persistableSdqaRatingVector)

5. Configure Policy File of Pipeline's OutputStage?

In pipeline.py, the OutputStage? has under-the-hood functionality for persisting SDQA ratings in the database. To activate this functionality, all you need to do is add the unique name of the PersistableSdqaRatingVector? object, which is "psfRatings" in our example, to the OutputStage? policy file under "OutputItems?".