RCAL-513 Update uneven ramp fitting documentation

[stscieisenhamer]

Resolves RCAL-513

Closes #

This PR addresses ...

Checklist

• added entry in CHANGES.rst under the corresponding subsection
• updated relevant tests
• updated relevant documentation
• updated relevant milestone(s)
• added relevant label(s)
• ran regression tests, post a link to the Jenkins job below. How to run regression tests on a PR

[stscieisenhamer]

@schlafly Still work-in-progress. However, I wanted to get a review of the description section. I have added the information that is in the paper and should correspond to the stcal.ramp_fitting.ols_cas22.fit_ramps code.

However, there is a bit more math, going from the segments to the resultants, that occurs in stcal.ramp_fitting.ols_cas22.fit_ramps_casertano after the fit_ramps is called, basically combining the segments back to their resultants. I can "math this out", but was wondering if there is a source paper (or something) that is better to use to match terminology.

There are still technical issues, such as filling out the parameters for the step, etc. that need to be completed, but wanted you to get an early look at this.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!.

[schlafly]

This looks good to me. Re combining segment ramps into a single ramp for each pixel, the goal was to do an inverse-variance weighted average using the read noise variances for each segment. That's not part of the Casertano+22 paper, as you say, and isn't documented anywhere.

Generically the right thing to do when combining a bunch of measurements to get a mean is to do an inverse variance weighted average with the total variances. However, the Poisson variance is proportional to the derived slope, so if you use that to do the weighting you systematically downweight ramps where the flux is high, leading to a negative bias. It would likely be better to do something like derive an initial flux from a straight average or median of the segments, use it to compute new total variances for each segment, and then use those total variances to do the inverse variance weighted mean. But that could be future work; I just did the inverse variance weighted mean using the read noise variances.

[stscieisenhamer]

Rest of the formulae have been documented. This will definitely need re-review. Also updated the parameter documentation.

[stscieisenhamer]

Regression test though it appears something is up with them, and this is documentation only anyways.

[schlafly]

This looks good. I left a few minor comments. The most important one is to check the denominator of the variances; I think some parentheses are misplaced. Thanks!

[schlafly]

Sorry, a few more minor nits, but looks good!

[schlafly]

I think of a 'segment' as a block of consecutive resultants with no jumps in between. One segment is fine; e.g., this is the case for a ramp with no cosmic rays. A segment with one resultant isn't fine and gets skipped.

[stscieisenhamer]

Nope, I got the terminology wrong. Trying again...

[schlafly]

Suggested change

	terminated where saturation flags are found. Pixels are processed simultaneously
	in blocks. The size of the block depends on the image size and the number of
	resultants.
	terminated where saturation flags are found.

We just process pixels one by one.

[schlafly]

LGTM, thanks!