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:

the input injection catalog is loaded and column names standardized;
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$);

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;

sources are injected into the exposure injection image using GalSim;
provenance metadata is added to the resultant source injected dataset;
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...

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 ...

Navigation