autocalib_fiberflat --fit-gradient option

[sbailey]

In desihub/desisurveyops#174, @sybenzvi identified multiple nights with O(10%) gradients in the fiberflats which we believe to be due to mis-alignment between the telescope and the calibration screen. Add an option desi_autocalib_fiberflat --fit-gradient that would fit (and correct!) a gradient to the nightly fiberflat compared to a reference fiberflat (maybe from an average over multiple good nights, or maybe it is sufficient to use a default in $DESI_SPECTRO_CALIB).

If the gradient is entirely due to dome mis-alignment, we could likely constrain the tilt orientation and solve for a single slope parameter. Otherwise we may need to solve for 2. It's unclear to be whether a single reference fiberflat is good enough to use, or whether there is enough variation with time (especially before/after focal plane maintenance) that we'd need multiple reference fiberflats.

Time is tight, but it would be great to get this in for Jura / Y3. Help needed!

[sbailey]

turning this into an itemized list:

1. Identify if the angle of the gradient is entirely determined by the PARALLAC (parallactic angle) keyword or whether we need to separately fit it in addition to the tilt.
2. Determine if the existing default fiberflats in $DESI_SPECTRO_CALIB/spec//fiberflatnight.fits are sufficient to serve as references, or whether we need different ones averaged over many nights
3. Determine if any of the existing default fiberflats in $DESI_SPECTRO_CALIB/spec//fiberflatnight.fits are themselves tilted and should not be used as references and should be replaced with better ones.
4. Write fitting code that takes the N fiberflatnight images from a night plus N reference images and fits a tilt and possibly a rotation angle depending upon the answer to (1).  Support cases where we are missing a petal on a night, and cases where there is an overall offset (we don't care about a constant offset term, but we do care about the slope).
5. Test on all nights that you've identified as bad, especially looking out for edge cases like individual outlier fibers distorting the overall fit.
6. Integrate the code from (4) into a desi_autocalib_fiberflat --fit-gradient option
7. Add pipeline+exposure_tables hooks to know what nights should use that extra option (Anthony + Stephen)

[sybenzvi]

@sbailey, later today I'll take a look at identifying reference nights (item 2) and/or building a time-averaged reference with bad periods removed (item 3) and I'll post some results in an accessible area in $CFS/desi.

ps - what I posted in desihub/desisurveyops#174 was based on the median flat fielding correction in the flatfibernight*.fits files. I did not investigate variation with wavelength. I assumed that's a second-order effect but I'll check that while I'm at it.

[rongpu]

I emulated what @sybenzvi did (and also using 20230929 as reference) for all nights since the past summer shutdown, and then fit a linear gradient to it. Here are two examples that show a clear gradient: Plots for each night can be found here: https://data.desi.lbl.gov/desi/users/rongpu/plots/fiberflatnight/

Plotting the per-night gradient as a vector and color-code the points with the date of observation: or alternatively plotting the gradient amplitude vs date (color-coded with angle): There are two periods that have a significant gradient: the first half of October 2023, and December 2023 (and a few nights into January) when the gradient changes direction by almost (but not exactly) 180 degrees compared to October. All these nights since summer 2023 have the same parallactic angle, so it does not explain this directional difference. All these plots are in R band. B and Z bands show very similar results.

[sybenzvi]

Very nice @rongpu.

If the telescope always goes to the same position during cals and the dome position encoders were saying it was in place when it wasn't, then maybe it's no surprise that the parallactic angle in the header never changes.

This might be a naive suggestion, but could we ignore that angle and just zero out the flat field gradient using your fits to one of the really bad nights? Then re-run the pipeline and check the effect on the throughput.

[sbailey]

I think we can get a non-180 degree difference in the direction of the gradient if we also have a small offset in elevation. e.g. if the telescope is pointed a bit high, then mis-aligning the dome screen in one azimuthal direction removes light from the upper-right, while mis-aligning it in the opposite azimuthal direction removes light from the upper-left (not lower-left).

[rongpu]

The choice of which night to use as reference does not matter much as long as it's one of the "good" nights. The fiberflats from 20240125 looks fine and its intrinsic gradient is close to the "average" gradient, so we can simply use that night as reference for all the nights that need correcting. (There is a small change in gradient from September 2023 to January 2024, but the change is less than +-1% edge-to-edge so it's negligible.)

If I use 20240125 as reference and set the threshold for correction at +-2% edge-to-edge, 33 night are flagged: 20230925, 20231001, 20231002, 20231003, 20231004, 20231005, 20231006, 20231007, 20231008, 20231009, 20231010, 20231011, 20231012, 20231013, 20231014, 20231015, 20231203, 20231204, 20231205, 20231207, 20231214, 20231216, 20231217, 20231218, 20231219, 20231220, 20231221, 20231228, 20231229, 20231230, 20231231, 20240101, 20240102.

The flagged nights are marked as crosses in this plot: