From 733ae50f0ed9e274fb0deafb42f82af7f6cfbdad Mon Sep 17 00:00:00 2001 From: Dave Davis Date: Tue, 10 Dec 2024 16:28:49 -0500 Subject: [PATCH] rcal-954 user requests --- docs/roman/pipeline_run.rst | 9 ++-- .../references_general/references_general.rst | 4 ++ docs/roman/stpipe/call_via_run.rst | 3 +- docs/roman/stpipe/config_asdf.rst | 4 +- docs/roman/stpipe/user_pipeline.rst | 2 +- docs/roman/stpipe/user_step.rst | 44 ++++++++++++++++--- 6 files changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/roman/pipeline_run.rst b/docs/roman/pipeline_run.rst index 2697fdb74..295164ceb 100644 --- a/docs/roman/pipeline_run.rst +++ b/docs/roman/pipeline_run.rst @@ -21,7 +21,7 @@ For example, the exposure level pipeline is implemented by the class run this pipeline is: :: - $ strun romancal.pipeline.ExposurePipeline r0008308002010007027_06311_0019_WFI01_uncal.asdf + $ strun romancal.pipeline.ExposurePipeline r0008308002010007027_0019_wfi01_uncal.asdf Pipeline classes also have a **pipeline name**, or **alias**, that can be used @@ -71,7 +71,8 @@ From the Python Prompt ------------------------------ You can execute a pipeline or a step from within python by using the -``call`` method of the class. +``call`` method of the class. This creates a new instance of the class +and runs the pipeline or step. The ``call`` method creates a new instance of the class and runs the pipeline or step. Optional parameter settings can be specified by via keyword arguments or @@ -82,10 +83,10 @@ For the exposure pipeline and steps, :: from romancal.pipeline import ExposurePipeline - result = ExposurePipeline.call('r0000101001001001001_01101_0001_WFI01_uncal.asdf') + result = ExposurePipeline.call('r0000101001001001001_0001_wfi01_uncal.asdf') from romancal.linearity import LinearityStep - result = LinearityStep.call('r0000101001001001001_01101_0001_WFI01_uncal.asdf') + result = LinearityStep.call('r0000101001001001001_0001_wfi01_uncal.asdf') One difference between the mosaic level pipeline and the exposure level pipeline is that the mosaic level pipeline is generally designed to run on multiple overlapping exposures. To achieve diff --git a/docs/roman/references_general/references_general.rst b/docs/roman/references_general/references_general.rst index db828eaf2..de4261a53 100644 --- a/docs/roman/references_general/references_general.rst +++ b/docs/roman/references_general/references_general.rst @@ -51,6 +51,8 @@ documentation on each reference file. +---------------------------------------------+--------------------------------------------------+ | :ref:`flatfield ` | :ref:`FLAT ` | +---------------------------------------------+--------------------------------------------------+ +| :ref:`GAIN ` | :ref:`ramp_fitting ` | ++---------------------------------------------+--------------------------------------------------+ | :ref:`linearity ` | :ref:`LINEARITY ` | +---------------------------------------------+--------------------------------------------------+ | :ref:`photom ` | :ref:`PHOTOM ` | @@ -78,6 +80,8 @@ documentation on each reference file. +--------------------------------------------------+---------------------------------------------+ | :ref:`PHOTOM ` | :ref:`photom ` | +--------------------------------------------------+---------------------------------------------+ +| :ref:`READNOISE ` | :ref:`ramp_fitting ` | ++--------------------------------------------------+---------------------------------------------+ | :ref:`SATURATION ` | :ref:`saturation ` | +--------------------------------------------------+---------------------------------------------+ diff --git a/docs/roman/stpipe/call_via_run.rst b/docs/roman/stpipe/call_via_run.rst index ad17bbcb9..9fad623b3 100644 --- a/docs/roman/stpipe/call_via_run.rst +++ b/docs/roman/stpipe/call_via_run.rst @@ -6,7 +6,8 @@ Executing a pipeline or pipeline step directly, or via run() When calling a pipeline or step instance directly, or using the ``run`` method, you can specify individual parameter values manually. In this case, parameter files are not used. If you use ``run`` after instantiating with a parameter -file, the parameter file will be ignored. +file (as is done when using the :ref:`call` method), +the parameter file will be ignored. :: diff --git a/docs/roman/stpipe/config_asdf.rst b/docs/roman/stpipe/config_asdf.rst index ea96396e0..923d517b9 100644 --- a/docs/roman/stpipe/config_asdf.rst +++ b/docs/roman/stpipe/config_asdf.rst @@ -178,13 +178,13 @@ Remember that parameter values can come from numerous sources. Refer to :ref:`Parameter Precedence` for a full listing of how parameters can be set. From the ``SourceCatalogStep`` example, if all that needed to change is the -``aperture_ee1`` parameter with a setting of ``30.0``, +``aperture_ee1`` parameter with a setting of ``30``, the ``parameters`` block need only contain the following: .. code-block:: parameters: - aperture_ee1: 30.0 + aperture_ee1: 30 Pipeline Configuration diff --git a/docs/roman/stpipe/user_pipeline.rst b/docs/roman/stpipe/user_pipeline.rst index c6da9e3a9..5c7dde510 100644 --- a/docs/roman/stpipe/user_pipeline.rst +++ b/docs/roman/stpipe/user_pipeline.rst @@ -186,7 +186,7 @@ From Python Once the pipeline has been configured (as above) it can be executed using run. - pipe(input_data) + pipe.run(input_data) Caching details --------------- diff --git a/docs/roman/stpipe/user_step.rst b/docs/roman/stpipe/user_step.rst index 707524510..f6212251c 100644 --- a/docs/roman/stpipe/user_step.rst +++ b/docs/roman/stpipe/user_step.rst @@ -181,6 +181,40 @@ the equivalent `from_cmdline` call would be:: ExposurePipeline.from_cmdline([' r0000101001001001001_0001_wfi01_uncal.asdf', 'steps.ramp_fit.override_gain', 'roman_wfi_gain_0033.asdf']) +call() +`````` + +Class method `Step.call` is the slightly more programmatic, and preferred, +method of executing a step or pipeline. When using ``call``, one gets the full +configuration initialization that +one gets with the ``strun`` command or ``Step.from_cmdline`` method. The call +signature is:: + + Step.call(input, logcfg=None, **parameters) + +The positional argument ``input`` is the data to be operated on, usually a +string representing a file path or a :ref:`DataModel`. The optional +keyword argument ``config_file`` is used to specify a local parameter file. The +optional keyword argument ``logcfg`` is used to specify a logging configuration file. +Finally, the remaining optional keyword arguments are the parameters that the +particular step accepts. The method returns the result of the step. A basic +example is:: + + from romancal.jump import JumpStep + output = JumpStep.call('r0000101001001001001_0001_wfi01_uncal.asdf') + +makes a new instance of `JumpStep` and executes using the specified exposure +file. `JumpStep` has a parameter ``rejection_threshold``. To use a different +value than the default, the statement would be:: + + output = JumpStep.call('r0000101001001001001_0001_wfi01_uncal.asdf', + rejection_threshold=42.0) + +If one wishes to use a :ref:`parameter file`, specify the path +to it using the ``config_file`` argument:: + + output = JumpStep.call('r0000101001001001001_0001_wfi01_uncal.asdf', + config_file='my_jumpstep_config.asdf') run() ````` @@ -198,11 +232,11 @@ example is:: `input` in this case can be a asdf file containing the appropriate data, or the output of a previously run step/pipeline, which is an instance of a particular :ref:`datamodel`. -There is no parameter initialization that occurs, either by a local -parameter file or from a CRDS-retrieved parameter reference -file. Parameters can be set individually on the instance, as is shown -above. Parameters can also be specified as keyword arguments when -instantiating the step. The previous example could be re-written as:: +Unlike the ``call`` class method, there is no parameter initialization that +occurs, either by a local parameter file or from a CRDS-retrieved parameter +reference file. Parameters can be set individually on the instance, as is shown +above. Parameters can also be specified as keyword arguments when instantiating +the step. The previous example could be re-written as:: from romancal.flatfield import FlatFieldStep