Fake source insertion has been available in the stack for a while now (see Sophie’s community post here: https://community.lsst.org/t/new-tasks-for-fake-source-insertion/3722). Briefly, sources can be inserted into either single exposure images (calexps) or coadds. Those sources can either be specified as a double Sersic profile (bulge+disk model) in a catalog, or directly as images. While this model is already working well for several science pipelines consumers, following discussions on the #dm-fsi slack channel, I would like to propose a number of changes and improvements to the fake source insertion framework. Note that Sophie and Lee were very helpful in preparing this list, but any terrible ideas below should be attributed solely to me.

1) Convert the `InsertFakesTask.addFakeSources` method into a free function. This method is arguably more implementation than interface at the moment, but I’d like to change that. In particular, I’d like to simplify third-party access to the source insertion framework, e.g. enabling:

  from lsst.pipe.tasks.insertFakes import addFakeSources

  addFakeSources(…) # use the function…

2) To increase the usability of (1) change the signature of addFakeSources. The current method accepts a target image, an iterator of insertion images, and a sourceType. The image iterator is currently created by other InsertFakesTask methods, and handles things like the WCS and PSF convolution. The proposed free function would instead have interface described by the following docstring:

Parameters

  ----------

  image : `lsst.afw.image.exposure.exposure.ExposureF`

    The image into which the fake sources should be added

  objects : `typing.Iterator` [`tuple` [’lsst.geom.SpherePoint`, `galsim.GSObject`]]

    An iterator of tuples that contains (or generates) locations and object

    surface brightness profiles to inject.

  calibFluxRadius : `float`, optional

    Aperture radius (in pixels) used to define the calibration for this

    image+catalog. This is used to produce the correct instrumental fluxes

    within the radius. The value should match that of the field defined in

    slot_CalibFlux_instFlux.

This signature factors out any dependency on the class instance (indeed, it becomes a free function). Using the WCS and PSF is handled directly inside the free function. The iteration is over GalSim objects (together with where to insert them) instead of images. The primary motivation of this change is to facilitate iteration over arbitrary GalSim objects, as well as (1) above.

(Note that (1) and (2) are already coded up in https://jira.lsstcorp.org/browse/DM-28853, which I made before realizing I should probably RFC some of these).

3) The current catalog source size/ellipticity is over-parameterized, which may lead to confusion. Specifically, the catalog has columns for half light radius (HLR), semi-major axis (a), and semi-minor axis (b). These are not independent. For example, the GalSim convention uses HLR = sqrt(a*b) (though other conventions are possible). I recommend combining the major and minor semi axes into a single column “axisRatio”. Other conventions are also possible, e.g., (a, b) instead of (HLR, axisRatio).

4) There is no column to specify the bulge-to-disk flux ratio. The current behavior is that the flux ratio is always 1.0. Recommend adding “bulgeDiskFluxRatio”.

5) Changes to configuration variable names and default values.

• Many of the InsertFakesTask config variables exist to control which column names in an input catalog correspond to which parameters of a double Sersic model. Both the config variable names themselves and their default values use an inconsistent naming scheme. For example, the config names “raColName”, “decColName”, “sourceSelectionColName” are appended with “ColName”, but other similarly behaving config names do not, e.g. “diskHLR”.
• Config names are inconsistent in the order of [bulge|disk] and the parameter name: e.g. “bulgeHLR” vs. “aBulge”.
• Default values (which I understand correspond to a particular pre-existing database) are similarly inconsistent. E.g., “DiskHalfLightRadius”, “disk_n” and “a_d” are all used to refer to disk properties.
  I propose that relevant config variable names all take the form “[bulge|disk] {Param}ColName” and default values all take the form “[bulge|disk]{Param}

  “.

6) The current catalog schema controls magnitudes via parameters (uMagVar, gMagVar, …). The “Var” exists to indicate that magnitudes may vary from epoch to epoch, but I was confused into thinking this meant “Variance”. I propose renaming this simply “uMag, gMag, …”.

7) When the source for insertions is a FITS file rather than a catalog, the column name to use for the FITS filename is hardcoded to band + “imFilename”. We propose making this a config variable too, with name fitsFilenameColName and default value “uFitsFilename”, “gFitsFilename”, …

(3 - 7) together imply the following change to the config variable name -> default value mapping.

Current
—————
raColName -> raJ2000
decColName -> decJ2000
diskHLR -> DiskHalfLightRadius
bulgeHLR -> BulgeHalfLightRadius
magVar -> [band]magVar
nDisk -> disk_n
nBulge -> bulge_n
aDisk -> a_d
aBulge -> a_b
bDisk -> b_d
bBulge -> b_b
paDisk -> pa_disk
paBulge -> pa_bulge
sourceSelectionColName -> templateSource

Proposed
——————
raColName -> ra
decColName -> dec
bulgeHLRColName -> bulgeHLR
bulgeAxisRatioColName -> bulgeAxisRatio
bulgePAColName -> bulgePA
bulgeNColName -> bulgeN
diskHLRColName -> diskHLR
diskAxisRatioColName -> diskAxisRatio
diskPAColName -> diskPA
diskNColName -> diskN
bulgeDiskFluxRatioColName -> bulgeDiskFluxRatio
magColName -> [band]Mag
selectColName -> select
fitsFilenameColName -> [band]FitsFilename

8) When the insertion source is a fits file rather than a double Sersic model, the current behavior is to interpret the pixels in the source image file as squares with scale equal to the target image wcs pixelScale() (i.e., the target wcs pixel scale at the pixel origin). Since this pixel scale can vary from target exposure to exposure (especially from target calexp to calexp), this implies that the same input image will manifest differently on the sky when inserted into different target images. In particular, one cannot consistently coadd fake sources from calexps this way.

I propose that instead, the pixel scales of fits-file sources be set primarily by reading standard WCS keywords from the corresponding fits headers. As a fallback, if the image header doesn’t contain WCS information (or it fails to be read in), then the pixel scale of input fits images can be specified in arcseconds from a config parameter named fitsPixelScale. The default value of fitsPixelScale would be set to NaN, so using it must be intentional and never accidental.

There are two options for what to do if fitsPixelScale is still NaN during fallback. a) Fail immediately with an error message telling the user to set fitsPixelScale (or add a wcs to the header). b) Revert back to current behavior (i.e., assume the insertion image and target image have the same pixel scale). Option A raises the barrier to using the code for simple tasks where exactness may not be required, but does indeed reduce exactness.

9) Assuming the above is adopted, then I propose deprecating obsoleted config fields (listed above) and InsertFakesTask methods (specifically `processImagesForInsertion`, `mkFakeGalsimGalaxies`, `mkFakeStars`). We would also deprecate the method version of `addFakeSources`.