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 uselsst.pipe.tasks.calibrate.CalibrateTask
.calibrate
(again, implemented byCalibrateTask
) has a subtask namedastrometry
, which is currently configured to use thelsst.meas.astrom.astrometry.AstrometryTask
task.calibrate.astrometry
has a subtask namedmatcher
, which is implemented byMatchOptimisticBTask
.
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 --config-file
or --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 --config-file
or --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
’sactive
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