lsst.meas.algorithms.loadReferenceObjects Namespace Reference

Classes
class	_FilterCatalog
class	LoadReferenceObjectsConfig
class	ReferenceObjectLoader

Functions
	getFormatVersionFromRefCat (refCat)
	filterRefCat (refCat, refFluxField, maxRefObjects=None, minRefMag=None, log=None)
	getRefFluxField (schema, filterName)
	getRefFluxKeys (schema, filterName)
	applyProperMotionsImpl (log, catalog, epoch)

Function Documentation

applyProperMotionsImpl()

lsst.meas.algorithms.loadReferenceObjects.applyProperMotionsImpl	(		log,
			catalog,
			epoch )

Apply proper motion correction to a reference catalog.

Adjust position and position error in the ``catalog``
for proper motion to the specified ``epoch``,
modifying the catalog in place.

Parameters
----------
log : `lsst.log.Log` or `logging.Logger`
    Log object to write to.
catalog : `lsst.afw.table.SimpleCatalog`
    Catalog of positions, containing:

    - Coordinates, retrieved by the table's coordinate key.
    - ``coord_raErr`` : Error in Right Ascension (rad).
    - ``coord_decErr`` : Error in Declination (rad).
    - ``pm_ra`` : Proper motion in Right Ascension (rad/yr,
        East positive)
    - ``pm_raErr`` : Error in ``pm_ra`` (rad/yr), optional.
    - ``pm_dec`` : Proper motion in Declination (rad/yr,
        North positive)
    - ``pm_decErr`` : Error in ``pm_dec`` (rad/yr), optional.
    - ``epoch`` : Mean epoch of object (an astropy.time.Time)
epoch : `astropy.time.Time`
    Epoch to which to correct proper motion.

Definition at line 1003 of file loadReferenceObjects.py.

def applyProperMotionsImpl(log, catalog, epoch):
    """Apply proper motion correction to a reference catalog.
 
    Adjust position and position error in the ``catalog``
    for proper motion to the specified ``epoch``,
    modifying the catalog in place.
 
    Parameters
    ----------
    log : `lsst.log.Log` or `logging.Logger`
        Log object to write to.
    catalog : `lsst.afw.table.SimpleCatalog`
        Catalog of positions, containing:
 
        - Coordinates, retrieved by the table's coordinate key.
        - ``coord_raErr`` : Error in Right Ascension (rad).
        - ``coord_decErr`` : Error in Declination (rad).
        - ``pm_ra`` : Proper motion in Right Ascension (rad/yr,
            East positive)
        - ``pm_raErr`` : Error in ``pm_ra`` (rad/yr), optional.
        - ``pm_dec`` : Proper motion in Declination (rad/yr,
            North positive)
        - ``pm_decErr`` : Error in ``pm_dec`` (rad/yr), optional.
        - ``epoch`` : Mean epoch of object (an astropy.time.Time)
    epoch : `astropy.time.Time`
        Epoch to which to correct proper motion.
    """
    if "epoch" not in catalog.schema or "pm_ra" not in catalog.schema or "pm_dec" not in catalog.schema:
        log.warning("Proper motion correction not available from catalog")
        return
    if not catalog.isContiguous():
        raise RuntimeError("Catalog must be contiguous")
    catEpoch = astropy.time.Time(catalog["epoch"], scale="tai", format="mjd")
    log.info("Correcting reference catalog for proper motion to %r", epoch)
    # Use `epoch.tai` to make sure the time difference is in TAI
    timeDiffsYears = (epoch.tai - catEpoch).to(astropy.units.yr).value
    coordKey = catalog.table.getCoordKey()
    # Compute the offset of each object due to proper motion
    # as components of the arc of a great circle along RA and Dec
    pmRaRad = catalog["pm_ra"]
    pmDecRad = catalog["pm_dec"]
    offsetsRaRad = pmRaRad*timeDiffsYears
    offsetsDecRad = pmDecRad*timeDiffsYears
    # Compute the corresponding bearing and arc length of each offset
    # due to proper motion, and apply the offset.
    # The factor of 1e6 for computing bearing is intended as
    # a reasonable scale for typical values of proper motion
    # in order to avoid large errors for small values of proper motion;
    # using the offsets is another option, but it can give
    # needlessly large errors for short duration.
    offsetBearingsRad = numpy.arctan2(offsetsDecRad*1e6, offsetsRaRad*1e6)
    offsetAmountsRad = numpy.hypot(offsetsRaRad, offsetsDecRad)
    for record, bearingRad, amountRad in zip(catalog, offsetBearingsRad, offsetAmountsRad):
        record.set(coordKey,
                   record.get(coordKey).offset(bearing=bearingRad*geom.radians,
                                               amount=amountRad*geom.radians))
    # TODO DM-36979: this needs to incorporate the full covariance!
    # Increase error in RA and Dec based on error in proper motion
    if "coord_raErr" in catalog.schema:
        catalog["coord_raErr"] = numpy.hypot(catalog["coord_raErr"],
                                             catalog["pm_raErr"]*timeDiffsYears)
    if "coord_decErr" in catalog.schema:
        catalog["coord_decErr"] = numpy.hypot(catalog["coord_decErr"],
                                              catalog["pm_decErr"]*timeDiffsYears)

filterRefCat()

lsst.meas.algorithms.loadReferenceObjects.filterRefCat	(		refCat,
			refFluxField,
			maxRefObjects = None,
			minRefMag = None,
			log = None )

Sub-select a number of reference objects starting from the brightest
and maxing out at the number specified by maxRefObjects.

No further trimming is done if len(refCat) > maxRefObjects after trimming
to minRefMag.

Parameters
----------
refCat : `lsst.afw.table.SimpleCatalog`
    Catalog of reference objects to trim.
refFluxField : `str`
    Field of refCat to use for flux.
maxRefObjects : `int` or `None`, optional
    Maximum number of reference objects (i.e. trim refCat down to
    this number of objects).
minRefMag : `int` or `None`, optional
    Minimum (i.e. brightest) magnitude to include in the reference
    catalog.
log : `lsst.log.Log` or `logging.Logger` or `None`, optional
    Logger object used to write out messages. If `None`, no messages
    will be logged.

Returns
-------
filteredCat : `lsst.afw.table.SimpleCatalog`
    Catalog trimmed to the maximum brightness and/or maximum number set
    in the task config from the brightest flux down.

Definition at line 848 of file loadReferenceObjects.py.

def filterRefCat(refCat, refFluxField, maxRefObjects=None, minRefMag=None, log=None):
    """Sub-select a number of reference objects starting from the brightest
    and maxing out at the number specified by maxRefObjects.
 
    No further trimming is done if len(refCat) > maxRefObjects after trimming
    to minRefMag.
 
    Parameters
    ----------
    refCat : `lsst.afw.table.SimpleCatalog`
        Catalog of reference objects to trim.
    refFluxField : `str`
        Field of refCat to use for flux.
    maxRefObjects : `int` or `None`, optional
        Maximum number of reference objects (i.e. trim refCat down to
        this number of objects).
    minRefMag : `int` or `None`, optional
        Minimum (i.e. brightest) magnitude to include in the reference
        catalog.
    log : `lsst.log.Log` or `logging.Logger` or `None`, optional
        Logger object used to write out messages. If `None`, no messages
        will be logged.
 
    Returns
    -------
    filteredCat : `lsst.afw.table.SimpleCatalog`
        Catalog trimmed to the maximum brightness and/or maximum number set
        in the task config from the brightest flux down.
    """
    if maxRefObjects is None and minRefMag is None:
        if log is not None:
            log.debug("No filtering of the reference catalog has been actually requested "
                      "(i.e maxRefObjects and minRefMag are both `None`)  Returning "
                      "original catalog.")
        return refCat
 
    filteredCat = refCat.copy(deep=True)
 
    if minRefMag is not None:
        refFlux = filteredCat.get(refFluxField)
        refMag = (refFlux*astropy.units.nJy).to_value(astropy.units.ABmag)
        if numpy.nanmin(refMag) <= minRefMag:
            filteredCat = filteredCat[(refMag > minRefMag)].copy(deep=True)
            if log is not None:
                log.info("Trimming the loaded reference catalog to %s > %.2f", refFluxField, minRefMag)
 
    if maxRefObjects is not None:
        if len(filteredCat) <= maxRefObjects:
            if log is not None:
                log.debug("Number of reference objects in reference catalog = %d (max is %d). "
                          "Returning catalog without further filtering.",
                          len(filteredCat), maxRefObjects)
            return filteredCat
        if log is not None:
            log.info("Trimming number of reference objects in refCat from %d down to %d. ",
                     len(refCat), maxRefObjects)
        if not filteredCat.isContiguous():
            filteredCat = filteredCat.copy(deep=True)
 
        refFlux = filteredCat.get(refFluxField)
        sortedRefFlux = refFlux[refFlux.argsort()]
        minRefFlux = sortedRefFlux[-(maxRefObjects + 1)]
 
        selected = (filteredCat.get(refFluxField) > minRefFlux)
        filteredCat = filteredCat[selected]
 
    if not filteredCat.isContiguous():
        filteredCat = filteredCat.copy(deep=True)
 
    if log is not None:
        if len(filteredCat) > 0:
            refFlux = filteredCat[refFluxField]
            refMag = (refFlux*astropy.units.nJy).to_value(astropy.units.ABmag)
            log.info("Reference catalog magnitude range for filter %s after trimming: refMagMin = %.2f; "
                     "refMagMax = %.2f", refFluxField, numpy.nanmin(refMag), numpy.nanmax(refMag))
        else:
            log.warning("Length of reference catalog after filtering is 0.")
    return filteredCat
 
 

getFormatVersionFromRefCat()

lsst.meas.algorithms.loadReferenceObjects.getFormatVersionFromRefCat

(

refCat

)

"Return the format version stored in a reference catalog header.

Parameters
----------
refCat : `lsst.afw.table.SimpleCatalog`
    Reference catalog to inspect.

Returns
-------
version : `int`
    Format version integer.

Raises
------
ValueError
    Raised if the catalog is version 0, has no metadata, or does not
    include a "REFCAT_FORMAT_VERSION" key.

Definition at line 41 of file loadReferenceObjects.py.

def getFormatVersionFromRefCat(refCat):
    """"Return the format version stored in a reference catalog header.
 
    Parameters
    ----------
    refCat : `lsst.afw.table.SimpleCatalog`
        Reference catalog to inspect.
 
    Returns
    -------
    version : `int`
        Format version integer.
 
    Raises
    ------
    ValueError
        Raised if the catalog is version 0, has no metadata, or does not
        include a "REFCAT_FORMAT_VERSION" key.
    """
    errMsg = "Version 0 refcats are no longer supported: refcat fluxes must have nJy units."
    md = refCat.getMetadata()
    if md is None:
        raise ValueError(f"No metadata found in refcat header. {errMsg}")
 
    try:
        version = md.getScalar("REFCAT_FORMAT_VERSION")
        if version == 0:
            raise ValueError(errMsg)
        else:
            return version
    except KeyError:
        raise ValueError(f"No version number found in refcat header metadata. {errMsg}")
 
 

getRefFluxField()

lsst.meas.algorithms.loadReferenceObjects.getRefFluxField	(		schema,
			filterName )

Get the name of a flux field from a schema.

Parameters
----------
schema : `lsst.afw.table.Schema`
    Reference catalog schema.
filterName : `str`
    Name of camera filter.

Returns
-------
fluxFieldName : `str`
    Name of flux field.

Notes
-----
Return the alias of ``anyFilterMapsToThis``, if present
else, return ``*filterName*_camFlux`` if present,
else, return ``*filterName*_flux`` if present (camera filter name
matches reference filter name), else raise an exception.

Raises
------
RuntimeError
    Raised if an appropriate field is not found.

Definition at line 928 of file loadReferenceObjects.py.

def getRefFluxField(schema, filterName):
    """Get the name of a flux field from a schema.
 
    Parameters
    ----------
    schema : `lsst.afw.table.Schema`
        Reference catalog schema.
    filterName : `str`
        Name of camera filter.
 
    Returns
    -------
    fluxFieldName : `str`
        Name of flux field.
 
    Notes
    -----
    Return the alias of ``anyFilterMapsToThis``, if present
    else, return ``*filterName*_camFlux`` if present,
    else, return ``*filterName*_flux`` if present (camera filter name
    matches reference filter name), else raise an exception.
 
    Raises
    ------
    RuntimeError
        Raised if an appropriate field is not found.
    """
    if not isinstance(schema, afwTable.Schema):
        raise RuntimeError("schema=%s is not a schema" % (schema,))
    try:
        return schema.getAliasMap().get("anyFilterMapsToThis")
    except LookupError:
        pass  # try the filterMap next
 
    fluxFieldList = [filterName + "_camFlux", filterName + "_flux"]
    for fluxField in fluxFieldList:
        if fluxField in schema:
            return fluxField
 
    raise RuntimeError("Could not find flux field(s) %s" % (", ".join(fluxFieldList)))
 
 

getRefFluxKeys()

lsst.meas.algorithms.loadReferenceObjects.getRefFluxKeys	(		schema,
			filterName )

Return keys for flux and flux error.

Parameters
----------
schema : `lsst.afw.table.Schema`
    Reference catalog schema.
filterName : `str`
    Name of camera filter.

Returns
-------
keys : `tuple` of (`lsst.afw.table.Key`, `lsst.afw.table.Key`)
    Two keys:

    - flux key
    - flux error key, if present, else None

Raises
------
RuntimeError
    If flux field not found.

Definition at line 970 of file loadReferenceObjects.py.

def getRefFluxKeys(schema, filterName):
    """Return keys for flux and flux error.
 
    Parameters
    ----------
    schema : `lsst.afw.table.Schema`
        Reference catalog schema.
    filterName : `str`
        Name of camera filter.
 
    Returns
    -------
    keys : `tuple` of (`lsst.afw.table.Key`, `lsst.afw.table.Key`)
        Two keys:
 
        - flux key
        - flux error key, if present, else None
 
    Raises
    ------
    RuntimeError
        If flux field not found.
    """
    fluxField = getRefFluxField(schema, filterName)
    fluxErrField = fluxField + "Err"
    fluxKey = schema[fluxField].asKey()
    try:
        fluxErrKey = schema[fluxErrField].asKey()
    except Exception:
        fluxErrKey = None
    return (fluxKey, fluxErrKey)