Retargeting subtasks of command-line tasks¶

Subtasks of command-line tasks are dynamically retargetable, meaning that you can configure which task class is run by a parent class. Subtask retargeting is a special case of command-line task configuration.

A common use of retargeting is to change a default subtask for a camera-specific one. For example:

lsst.obs.subaru.isr.SuprimeCamIsrTask: a version of instrument signature removal (ISR or detrending) for Suprime-Cam and Hyper Suprime-Cam.
lsst.obs.sdss.selectSdssImages.SelectSdssImagesTask: an version of the task that selects images for co-addition of SDSS stripe 82 images.

How you retarget a subtask and override its config parameters depends on whether the task is specified as an lsst.pex.config.ConfigurableField (the most common case) or as an lsst.pex.config.RegistryField. Both scenarios are described on this page.

Viewing configured subtasks¶

To see what subtasks are currently configured to run with a command-line task, use the --show tasks argument (this runs the command-line task in a dry-run mode that shows tasks but does not process data). For example:

processCcd.py REPOPATH --output output --show tasks

An example of the printed output is:

sub-tasks:
calibrate: lsst.pipe.tasks.calibrate.CalibrateTask
calibrate.applyApCorr: lsst.meas.base.applyApCorr.ApplyApCorrTask
calibrate.astromRefObjLoader: lsst.meas.algorithms.loadIndexedReferenceObjects.LoadIndexedReferenceObjectsTask
calibrate.astrometry: lsst.meas.astrom.astrometry.AstrometryTask
calibrate.astrometry.matcher: lsst.meas.astrom.matchOptimisticB.matchOptimisticBContinued.MatchOptimisticBTask
...

This subtask hierarchy is interpreted as follows:

The calibrate subtask of the command-line task (processCcd.py) is configured to use lsst.pipe.tasks.calibrate.CalibrateTask.
calibrate (again, implemented by CalibrateTask) has a subtask named astrometry, which is currently configured to use the lsst.meas.astrom.astrometry.AstrometryTask task.
calibrate.astrometry has a subtask named matcher, which is implemented by MatchOptimisticBTask.

Note that if the calibrate.astrometry task is retargeted to a different task class, the subtask of calibrate.astrometry may change (for example, calibrate.astrometry.matcher may no longer exist).

How to retarget a subtask configured as a ConfigurableField with a configuration file¶

To retarget a subtask specified as an lsst.pex.config.ConfigurableField, you must use a configuration file (specified by --configfile, see How to use configuration files). Inside a configuration file, retargeting is done in two steps:

Import the Task class you intend to use.
Assign that class to to the subtask configuration using the retarget method.

For example, to retarget the subtask named configurableSubtask with a class FooTask, this configuration file should contain:

from ... import FooTask
config.configurableSubtask.retarget(FooTask)

Once a subtask is retargeted, you can configure it as normal by setting attributes to configuration parameters. For example:

config.configurableSubtask.subtaskParam1 = newValue

Warning

When you retarget a task specified by an lsst.pex.config.ConfigurableField you lose all configuration overrides for both the old and new task. This limitation is not shared by lsst.pex.config.RegistryField.

How to retarget a subtask configured as a RegistryField with a configuration file¶

To retarget a subtask specified as an lsst.pex.config.RegistryField, set the field’s name attribute in a configuration file (using --configfile). Here is an example that assumes a task FooTask is defined in module .../foo.py and registered using name foo:

import .../foo.py
config.registrySubtask.name = "foo"

Besides retargeting the registry subtask, there are two ways to configure parameters for tasks in a registry:

Set parameters for the active subtask using the RegistryField’s active attribute.
Set parameters for any registered task using dictionary notation and the subtask’s registered name.

These configuration methods are described next.

Configure the active subtask configured as a RegistryField¶

You may configure the retargeted subtask in a configuration file by setting the subtask configuration’s active attribute. For example:

config.registrySubtask.active.subtaskParam1 = newValue

These configurations can also be specified directly on the command line as a --config argument. For example:

--config registrySubtask.active.subtaskParam1=newValue

Configure any subtask in a registry¶

Alternatively, you can then configure parameters for any subtask in the registry using key-value access. For example:

config.registrySubtask["foo"].subtaskParam1 = newValue

Navigation