Change in calibration flag names as per RFC-498

Ticket DM-14997 has just been merged. This implements RFC-498: Homogenize naming of calibration flags. Prior to this merge we were in a state of having inhomogeneous naming conventions for the set of calibrations flags in the form of a mixture of underscore and camelCase for the third/final “descriptor”, making it difficult to remember which standard to use when trying to select on a given flag:

  • calib_detected
  • calib_psfCandidate
  • calib_psfUsed
  • calib_psf_reserved (changed from calib_psfReserved on DM-12207)
  • calib_astrometryUsed
  • calib_photometry_used (changed from calib_photometryUsed on DM-12207)
  • calib_photometry_reserved (changed from calib_photometryReserved on [DM-12207(

DM-14998 saw an update to the documentation which now specifies a preference for the underscore convention for the final descriptor. Specifically, it reads:

Two rules of thumb are:

  • if two words are not individually meaningful (or mean something
    different when separated), join them with CamelCase;

  • if the prefix of a field name represents a conceptual group of
    multiple fields, use underscores to join the group name to the group

See for the full set of guidelines for Field naming.

Following this recommendation, the following schema field name changes have been made:

  • calib_psfCandidate -> calib_psf_candidate
  • calib_psfUsed -> calib_psf_used
  • calib_astrometryUsed -> calib_astrometry_used

Data processed following this merge will have the new names, while older datasets will still have the old naming convention. I have done a GitHub-wide search on calib_psfUsed (the most commonly used flag) and found that there are a number of uses in notebooks and personal repo code that make use of some of these flags for source selection. I will ping as many as I can to have a look at this post.

For those wanting to maintain backwards compatibility with older datasets,
here is an example snippet of code that should do the trick for you (I am
implementing something similar on DM-15109 in the pipe_analysis repo for
this purpose):

# Dict of alias mappings
flagsToAliasDict = {"calib_psf_used": "calib_psfUsed",
                    "calib_psf_candidate": "calib_psfCandidate",
                    "calib_astrometry_used": "calib_astrometryUsed"}

def setAliasMap(catalog, aliasMappingDict, prefix=""):
    """Set an alias map for backwards compatibility if running on a
       pre-RFC-498 processed catalog

    catalog : `lsst.afw.table.SourceCatalog`
       The source catalog to which the mapping will be added.
    aliasMappingDict : `dict` of `str`
      A `dict` representing the alias mappings to be added to ``catalog``'s
      schema with the key representing the new name to be mapped to the
      value which represents the old name.  Note that the mapping will only
      be added if the old name exists in ``catalog``’s schema.
    prefix : `str`, optional
       This `str` will be prepended to the alias names (used, e.g., in matched
       catalogs for which "src_" and "ref_" prefixes have been added to all
       schema names).  Both the old and new names have ``prefix`` associated
       with them (default is an empty string).

    catalog : `lsst.afw.table.SourceCatalog`
       The source catalog with the alias mappings added to the schema.
    aliasMap = catalog.schema.getAliasMap()
    for newName, oldName in aliasMappingDict.items():
        if prefix + oldName in catalog.schema:
            aliasMap.set(prefix + newName, prefix + oldName)
    return catalog

Call with:

catalog = setAliasMap(catalog, flagsToAliasDict)