Skip to content

Commit

Permalink
Merge pull request #1082 from spacetelescope/DR-user-guide-update-2
Browse files Browse the repository at this point in the history
Added several more images and updates for build context.
  • Loading branch information
hbrown-ST authored Oct 7, 2024
2 parents b1ac858 + 3a61527 commit 423b4d3
Show file tree
Hide file tree
Showing 7 changed files with 60 additions and 21 deletions.
12 changes: 7 additions & 5 deletions documentation/crds_users_guide/source/command_line_tools.rst
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,10 @@ New Context
...........

crds.bestrefs always computes best references with respect to a context which
can be explicitly specified with the `--new-context` parameter. If `--new-context`
is not specified, the default latest context is determined by consulting
can be explicitly specified with the `--new-context` parameter. For JWST, if `--new-context`
is not specified, the default build context is determined by checking the CRDS Server to find the
appropriate context for the Calibration Software that a user has locally installed.
In the case of HST or Roman, the default latest context is determined by consulting
the CRDS server or looking in the local cache.

...........
Expand Down Expand Up @@ -809,7 +811,7 @@ explained above:
.. code-block:: bash
$ crds list --cat jwst_nirspec_dark_0036.fits
CRDS - INFO - Symbolic context 'jwst-latest' resolves to 'jwst_0167.pmap'
CRDS - INFO - Symbolic context 'jwst-build' resolves to 'jwst_0167.pmap'
File: '/grp/crds/jwst/references/jwst/jwst_nirspec_dark_0036.fits'
{'A1_COL_C': '8.9600000e+002',
'A1_CONF1': '2.1846000e+004',
Expand Down Expand Up @@ -930,7 +932,7 @@ Sometimes it's desirable to know the individual exposures CRDS associates with a

.. code-block:: bash
$ python m crds.list --latest-context
$ python m crds.list --build-context
jwst_0204.pmap
lists the context which has been *commanded* as default on the CRDS server.
Expand Down Expand Up @@ -974,7 +976,7 @@ contexts:
jwst_0208.pmap
jwst_0209.pmap
$ crds list --resolve-contexts --contexts jwst-miri-dark-latest
$ crds list --resolve-contexts --contexts jwst-miri-dark-build
jwst_miri_dark_0012.rmap
$ crds list --resolve-contexts --contexts jwst-niriss-superbias-2016-01-01T00:00:00
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 14 additions & 8 deletions documentation/crds_users_guide/source/library_use.rst
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,8 @@ reference file paths:
context : The name of the pipeline context mapping which should be
used to define best reference lookup rules, or None. If
`context` is None, use the latest pipeline mapping.
`context` is None, use the latest pipeline mapping. For JWST,
this is the build context mapping.
str
Expand Down Expand Up @@ -147,7 +148,7 @@ reference type:
filling in appropriate reference type keywords.
Define best references using either .pmap `context` or the default
CRDS latest context if context=None.
CRDS context if context=None.
If `reftypes` is defined, assign bestrefs to only the listed
reftypes, otherwise assign all reftypes.
Expand Down Expand Up @@ -181,15 +182,20 @@ crds.get_default_context()
..........................

`get_default_context()` returns the name of the pipeline mapping which is
currently the Latest Context
currently the Build Context in the case of JWST based on the version of the locally installed
Calibration code, while it returns the Latest Context for HST and Roman from the Crds Server or the local cache.
!!!!!!!!!!!!!!!!!!!

*Latest Context* is the .pmap which is nominally in use by the pipeline.
While it's common to make new files the latest as each context is added, it's
For HST and Roman, *Latest Context* is the .pmap which is nominally in use by the pipeline. For JWST, see below.
While it's common to make new files become the *Latest* as each context is added, it's
possible for the *Latest Context* to lag behind the *Edit Context* when
new files are being added but need additional testing in OPS. Deriving
from the *Latest Context* is a crude kind of reversion since CRDS
effectively branches around any existing subsequent contexts. use.
new files are being added but need additional testing in OPS, and the *Latest Context* when the
new files are confirmed. Deriving from the *Latest Context* is a crude kind of reversion since CRDS
effectively branches around any existing subsequent contexts.

*Build Context* applies to JWST, and is the .pmap which corresponds to the most recently installed
JWST DMS Install and JWST Calibration code. It is guaranteed to work with that delivered code, and stays consistent
after new reference files are delivered.

The default context defines the matching rules used to determine best
reference files for a given set of parameters:
Expand Down
21 changes: 19 additions & 2 deletions documentation/crds_users_guide/source/pipeline_management.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Set Context
This section describes the website page used by operators to update the default
CRDS context.

*Set Context* enables setting the latest, edit, and versions contexts.
*Set Context* enables setting the build, latest, edit, and versions contexts.

.. figure:: images/web_set_context.png
:scale: 50 %
Expand All @@ -55,7 +55,7 @@ CRDS context.
CRDS enables contexts to be distributed before their adoption as the pipeline
default. Set Context is used to select the default pipeline (latest)
context.

Setting the latest context changes state on the CRDS server which must be
subsequently sync'ed to remote pipelines and users.

Expand All @@ -68,6 +68,23 @@ submissions.
Setting the *versions* context defines the context used to locate the SYSTEM
CALVER reference file used to define calibration software component versions.

Selecting the *build* context for the Context Type changes the menu that you can use:

.. figure:: images/web_set_build_context.png
:scale: 50 %
:alt: set build context inputs

It adds a CAL_VER option that allows the user to set a pre-existing Cal Version, or a custom one
that a user inputs.

.. figure:: images/web_set_build_drop.png
:scale: 50 %
:alt: drop for build context inputs

Selecting the checkbox for Update Home Page Banner / Pipeline Build Context will update the
build context displayed in the front page banner if the context being set is newer then the
existing banner context.

Sync Pipeline CRDS Cache
++++++++++++++++++++++++

Expand Down
5 changes: 4 additions & 1 deletion documentation/crds_users_guide/source/web_services.rst
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,10 @@ when the cache is synchronized. Since this value is inapplicable if a pipeline
is run in "remote" mode computing best references on the CRDS Server, the
generally preferred value is from `get_default_context()` since it always
reflects the intended latest context regardless of the pipeline's CRDS
mode.
mode. For JWST, get_default_context() retrieves the "build" context associated
with the version of JWST pipeline calibration software installed locally,
which may or may not differ from the "latest" context.
This ensures compatibility between reference files and calibration software.

The actual default context for a pipeline can be obtained as follows:

Expand Down
21 changes: 16 additions & 5 deletions documentation/crds_users_guide/source/web_site_use.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,23 @@ For HST
:alt: hst home page of CRDS website



<--Applicable only to JWST and RST

Build Context Banner
----------------------
The Build Context Banner displays the CRDS Context that was delivered with a DMS build, and
is guaranteed to work with that build. It will be the latest context when a DMS build is installed,
but will not be the most current after references get delivered and the latest context is updated.

Clicking on the `build contexts` link will bring up a table that displays the JWST Calibration Code Version that was
available when a particular context was delivered.

.. figure:: images/web_context_build_table.png
:scale: 50 %
:alt: Build CRDS contexts

-->

Latest References
----------------------
Expand Down Expand Up @@ -83,11 +98,7 @@ Clicking on the `all contexts` link will bring up every context that has ever be
<--Applicable only to JWST and RST

Clicking on the `build contexts` link will bring up a table that displays the JWST Calibration Code Version that was
available when a particular context was delivered.

.. figure:: images/web_context_build_table.png
:scale: 50 %
:alt: Build CRDS contexts
available when a particular context was delivered, just as it did in the banner.

Clicking a `Cal Ver` link will take you to the github release of that JWST Calibration version:

Expand Down

0 comments on commit 423b4d3

Please sign in to comment.