Document why two values are needed as parameters (outlier_detection)

[stscijgbot-jp]

Issue JP-3503 was created on JIRA by Misty Cracraft:

There are multiple parameters scattered throughout the code that have two values as a list, with no explanation of why two values are needed. We need to tell users what the two values are, and why they're different.

The two parameters in outlier_detection that have two values with no explanation are:

SNR and scale.

https://jwst-pipeline.readthedocs.io/en/stable/jwst/outlier_detection/arguments.html

There are a few other tickets on updating documentation for outlier_detection, so maybe the updates are becoming more urgent.

[stscijgbot-jp]

Comment by Misty Cracraft on JIRA:

In Slack, Howard said Anton Koekemoer  might have insight into why there are two parameter values for scale?

For SNR, copying text from JP-1647: Something along the lines of what M. Regan communicated in the Slack discussion would be helpful: "The user must specify two cut-off signal-to-noise (SNR) values for determining whether a pixel should be masked: the first for detecting the primary cosmic ray, and the second for masking lower-level bad pixels adjacent to those found in the first pass. Since cosmic rays often extend across several pixels, the adjacent pixels make use of a slightly lower SNR threshold."

[stscijgbot-jp]

Comment by Bryan Hilbert on JIRA:

If I recall, the original astrodrizzle documentation talks a bit about cases where multiple values are used for a parameter. I'm pretty sure I've gone there in the past to try to find details.

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

thanks, and yes here's what I just posted in slack too:

thanks for passing this on. These parameters were initially implemented in MultiDrizzle (which then became the foundation for Astrodrizzle / drizzepac) and they are documented here:[https://hst-docs.stsci.edu/drizzpac/chapter-5-drizzlepac-software-package/5-2-astrodrizzle-the-new-drizzle-workhorse]where it says this, for the SNR parameter (which also has 2 values, like the scale parameter, and both these parameters have the same behaviour):

The user must specify two cut-off signal-to-noise (SNR) values for determining whether a pixel should be masked: the first for detecting the primary cosmic ray, and the second for masking lower-level bad pixels adjacent to those found in the first pass.

So for JWST, could the readthedocs page for outlier detection (which @cracraft refers to):

https://jwst-pipeline.readthedocs.io/en/latest/jwst/outlier_detection/arguments.html

be updated please, for both the snr and the scale parameters, to capture this behaviour? Here’s some text that I would suggest to add as an additional sentence to the current desciptions, for both the snr and the scale parameters:

Two values are specified, where the first value is used for rejecting outliers in all pixels across the image, while the second value is used to reject additional lower-level outliers in pixels that are adjacent to those identified in the first pass.

Could @bushouse let us know please once SCSB has updated the readthedocs pages to include the above text for both the snr and scale parameters?

 

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

added Howard Bushouse  to the watchers so he can let us know here once SCSB has updated the readthedocs page for these two parameters (snr and scale)

[stscijgbot-jp]

Comment by David Law on JIRA:

I had the relevant code open anyway, so see #8177

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Fixed by #8177

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

Updates docs are now viewable at https://jwst-pipeline.readthedocs.io/en/latest/jwst/outlier_detection/arguments.html

[stscijgbot-jp]

Comment by Misty Cracraft on JIRA:

So long as the same text is valid for both the snr and scale, the update is fine with me, and explains that there are two iterations of the code, and why we need two values. So that is fine from my perspective.