JP-3892: Update Jump Documentation

[kmacdonald-stsci]

Resolves JP-3892

This PR addresses jump step documentation detailing the logical control flow of the step. Also, a small bug was fixed in the computation of total_sigclip_groups.

Regression test run for the bug fix:
https://github.com/spacetelescope/RegressionTests/actions/runs/29337654497

Tasks

• update or add relevant tests
• update relevant docstrings and / or docs/ page
• Does this PR change any API used downstream? (if not, label with no-changelog-entry-needed)
  • write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see changelog readme for instructions)
  • if your change breaks existing functionality, also add a changes/<PR#>.breaking.rst news fragment
• run regression tests with this branch installed ("git+https://github.com/<fork>/stcal@<branch>")
  • jwst regression test
  • romancal regression test

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.90%. Comparing base (bb256db) to head (a363d55).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #562   +/-   ##
=======================================
  Coverage   91.90%   91.90%           
=======================================
  Files          63       63           
  Lines        8926     8926           
=======================================
  Hits         8203     8203           
  Misses        723      723           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[drlaw1558]

Thanks @kmacdonald-stsci ; I don't think we want to remove the existing information though, just add to it.

In rough words, something like:

"Jumps in the ramps of a given pixel are detected using statistics of the two-point differences between successive groups. Those statistics either use sigma clipping or the method described by Anderson+Gordon.

If only_use_ints=True and nints > minimum_sigclip_groups: sigma clip across integrations for each group difference in the ramp (e.g., sigma clip groups 3-2 for all integrations, then sigma clip groups 4-3 for all integrations, etc).

If only_use_ints=False and nints*ngroups > minimum_sigclip_groups: sigma clip across all group differences and all integrations simultaneously (e.g., treat all group differences within an integration and in other integrations equally).

Otherwise if there are at least min_diffs_single_pass in each integration do (SOMETHING???) to find jumps.

Otherwise use the 10point iterative approach below."

I'm a little unclear on some things though:

• Even if not sigma clipping there's a split when min_usable_diffs >= twopt_p.min_diffs_single_pass to call look_for_more_than_one_jump, and otherwise to call iterative_jump. min_diffs_single_pass says that it's a MIRI shower parameters in the docs, but that doesn't seem right- it looks like it affects everything. What is look_for_more_than_one_jump doing though and how is this different from sigma clipping? To answer my own question, I think it's the case that the astropy stats sigma clipping is empirically determining sigma from the ensemble of group differences, while the look_for_more_than_one_jump version is theoretically determining sigma from the nominal read+poisson noise.

• I don't think the description in the docs of minimum_groups is accurate. It says the minimum number to use sigma clipping, but I think it's the minimum number to do ANY type of jump detection? If so this seems to be labelled incorrectly in many places, from stcal readthedocs to both stcal and jwst inline docs.