ExposureInjectTask

Inject Synthetic Sources Into Single-Frame Exposures

ExposureInjectTask injects synthetic sources into single-frame exposures. A user-supplied input catalog defines the positions and characteristics for synthetic sources to be generated. If the user opts instead to inject pre-built FITS postage stamp images, the path to these must be supplied. The GalSim software package is used to generate synthetic postage stamps (if required) before performing source injection into an image.

As an output, an injected_ variant of the input dataset type will be created. For exposure-level imaging, the default input is a postISRCCD dataset type, producing an injected_postISRCCD output.

Processing Summary

ExposureInjectTask runs this sequence of operations:

  1. the input injection catalog is loaded and column names standardized;

  2. injection sources are cleaned according to certain criteria, including:

  • missing or erroneous magnitude information;

  • centroids that do not fall close to the injection area;

  • sources not selected by virtue of their visit or selection flag;

  • a source type which is not a supported GSObject class;

  • extreme Sérsic indices (i.e., outside the range \(0.3 \le n \le 6.2\));

  1. the input source is converted into a GalSim object:

  • no attempt at source injection will be made if the fully realized bounding box does not overlap with the injection image;

  1. sources are injected into the exposure injection image using GalSim;

  2. provenance metadata is added to the resultant source injected dataset;

  3. the injected image and associated injected catalog are output.

Python API Summary

from lsst.source.injection.inject_exposure import ExposureInjectTask
classExposureInjectTask(*, config=None, log=None, initInputs=None, **kwargs)

Exposure-level class for injecting sources into images...

attributeconfig

Access configuration fields and retargetable subtasks.

methodrun(injection_catalogs, input_exposure, psf, photo_calib, wcs)

Inject sources into an image...

See also

See the ExposureInjectTask API reference for complete details.

Configuration Fields

add_noise

Default
True
Field type

bool Field

Whether to randomly vary the injected flux in each pixel by an amount consistent with the injected variance.

bad_mask_names

Default
['BAD', 'CR', 'CROSSTALK', 'INTRP', 'NO_DATA', 'SAT', 'SUSPECT', 'UNMASKEDNAN']
Field type

str ListField

List of mask plane names indicating pixels to ignore when fitting flux vs variance in preparation for variance plane modification.

calib_flux_radius

Default
12.0
Field type

float Field

Aperture radius (in pixels) that was used to define the calibration for this image+catalog. This will be used to produce the correct instrumental fluxes within the radius. This value should match that of the field defined in slot_CalibFlux_instFlux.

col_dec

Default
'dec'
Field type

str Field

Column name for declination (in degrees).

col_draw_size

Default
'draw_size'
Field type

str Field

Column name providing pixel size of the region into which the source profile will be drawn. If this column is not provided as an input, the GalSim method getGoodImageSize will be used instead.

col_mag

Default
'mag'
Field type

str Field

Column name for magnitude.

col_ra

Default
'ra'
Field type

str Field

Column name for right ascension (in degrees).

col_source_type

Default
'source_type'
Field type

str Field

Column name for the source type used in the input catalog. Must match one of the surface brightness profiles defined by GalSim.

col_stamp

Default
'stamp'
Field type

str Field

Column name to identify FITS file postage stamps for direct injection. The strings in this column will be prefixed with a string given in stamp_prefix, to assist in providing the full path to a FITS file.

col_trail_length

Default
'trail_length'
Field type

str Field

Column name for specifying a satellite trail length (in pixels).

connections

Data type

lsst.pipe.base.config.ExposureInjectConfigConnections

Field type

ConfigField

Configurations describing the connections of the PipelineTask to datatypes

external_photo_calib

Default
False
Field type

bool Field

If True, use the photometric calibration from a visit summary table. If False (default), use the photometric calibration attached to the input exposure.

external_psf

Default
False
Field type

bool Field

If True, use the PSF model from a visit summary table. If False (default), use the PSF model attached to the input exposure.

external_wcs

Default
False
Field type

bool Field

If True, use the astrometric calibration from a visit summary table. If False (default), use the astrometric calibration attached to the input exposure.

fits_alignment

Default
'pixel'
Field type

str ChoiceField (optional)

Choices
'wcs'

Input image will be transformed such that the local WCS in the FITS header matches the local WCS in the target image. I.e., North, East, and angular distances in the input image will match North, East, and angular distances in the target image.

'pixel'

Input image will **not** be transformed. Up, right, and pixel distances in the input image will match up, right and pixel distances in the target image.

None

Field is optional

How should injections from FITS files be aligned?

inject_variance

Default
True
Field type

bool Field

Whether, when injecting flux into the image plane, to inject a corresponding amount of variance into the variance plane.

mask_plane_name

Default
'INJECTED'
Field type

str Field

Name assigned to the injected mask plane which is attached to the output exposure.

noise_seed

Default
0
Field type

int Field

Initial seed for random noise generation. This value increments by 1 for each injected object, so each object has an independent noise realization.

process_all_data_ids

Default
False
Field type

bool Field

If True, all input data IDs will be processed, even those where no synthetic sources were identified for injection. In such an eventuality this returns a clone of the input image, renamed to the output_exposure connection name and with an empty mask_plane_name mask plane attached.

saveLogOutput

Default
True
Field type

bool Field

Flag to enable/disable saving of log output for a task, enabled by default.

selection

Default
None
Field type

str Field (optional)

A string that can be evaluated as a boolean expression to select rows in the input injection catalog. To make use of this configuration option, the internal object name injection_catalog must be used. For example, to select all sources with a magnitude in the range 20.0 < mag < 25.0, set selection="(injection_catalog['mag'] > 20.0) & (injection_catalog['mag'] < 25.0)". The {visit} field will be substituted for the current visit ID of the exposure being processed. For example, to select only visits that match a user-supplied visit column in the input injection catalog, set selection="np.isin(injection_catalog['visit'], {visit})".

stamp_prefix

Default
''
Field type

str Field

String to prefix to the entries in the col_stamp column, for example, a directory path.

trim_padding

Default
100
Field type

int Field (optional)

Size of the pixel padding surrounding the image. Only those synthetic sources with a centroid falling within the image + trim_padding region will be considered for source injection.

Examples

An example calling this task from the command line using pipetask run:

pipetask --long-log --log-file $LOGFILE \
run --register-dataset-types \
-b $REPO \
-i $INPUT_DATA_COLL,$INJECTION_CATALOG_COLL \
-o $OUTPUT_COLL \
-p $SOURCE_INJECTION_DIR/pipelines/inject_exposure.yaml \
-d "instrument='HSC' AND exposure=1228 AND detector=51"

where

$LOGFILE

The full path to a user-defined output log file.

$REPO

The path to the butler repository.

$INPUT_DATA_COLL

The name of the input data collection.

$INJECTION_CATALOG_COLL

The name of the input injection catalog collection.

$OUTPUT_COLL

The name of the injected output collection.

$SOURCE_INJECTION_DIR

The path to the source injection module directory.

Debugging

Additional debug-level log information may be shown by setting the log-level option to DEBUG at runtime:

pipetask --log-level DEBUG ...