Add a tutorial inverting AIA and XRT images for the DEM of a jet

[roytsmart]

Adds docs/tutorials/dem.rst, a tutorial that finds the DEM of a coronal jet from six AIA channels and XRT Al_poly. The jet is event E of Parker et al. (2022), observed during the ESIS flight on 2019-09-30.

What the tutorial does

1. Load XRT. It takes the Al_poly image at 18:08:00, just before the first one with saturated pixels, and subtracts the leak. XRT saturates only 6 pixels at 18:08:19 and 3 at 18:08:37, in runs of 3 down a column (blooming). Every other image of the event is unsaturated, so XRT is used at every pixel.
2. Co-align. hinode.xrt.open now does this by default (Correct the pointing of XRT images with the co-alignment databases of SolarSoft, by default from the cross-correlation with AIA. #5): it moves the center of the image to the position in the SolarSoft coalignment database from the cross-correlation with AIA (Yoshimura & McKenzie 2015), as xrt_read_coaldb, /aia_cc does. The tutorial just shows xrt.coalignment (1, the cross-correlation with AIA). For this image the shift is −0.34″, +0.68″, and the pointing matches the manual shift this PR used to apply to within 5×10⁻⁷″, so none of the numbers in the text change.
3. Load AIA. In each channel it keeps the registered image whose exposure is centered closest to the middle of the XRT exposure. JSOC finds images by their 12 s slot (T_REC), and an image can be taken up to 12 s after the start of its slot, so a search returns images outside the range too. Taking the first one, as before, put 94, 211 and 335 Å 8 to 10 s from the XRT middle; now all six are within 0.7 to 5.3 s.
4. Match the resolution. It blurs AIA by a Gaussian of the difference in quadrature of the two PSF cores, about 2″ for XRT and 1.3″ for AIA. It then sums AIA onto the XRT pixels by conservative regridding, and puts both instruments in units per steradian.
5. AIA uncertainty. This is sdo.aia.uncertainty, summed onto the XRT pixels. It is scaled by how much the blur and the regridding average down white noise, a factor of 0.156 in variance. Without that factor the AIA noise is overestimated, and the inversion fits AIA better than its noise warrants and XRT worse.
6. XRT uncertainty, measured from the data. It divides the differences between consecutive frames by the Filtergram.uncertainty of both frames, with F at log T 6.3, in quiet pixels outside the box around the jet:
   • The measured variance is 0.153 of the model's.
   • The correlation between adjacent pixels is 0.43 inside the 8 × 8 JPEG blocks and 0.28 across block edges.
   • The tutorial attributes this to charge diffusion in the CCD plus JPEG compression. Neither is in Kobelski et al. (2014). It scales the uncertainty to the measured noise until there is a model of both. A two-point covariance for that model was requested on Spread the noiseless signal of a sensor with the kernel of its charge diffusion optika#255.
7. Temperature response. The AIA responses are normalized to EVE and include chiantifix, the empirical correction of Boerner et al. (2014) for the lines near 1 MK that CHIANTI is missing from 94 Å. Without it the DEM predicts about half of the observed 94 Å; with it, about 80%. Both responses are evaluated at the time of the images (AIA degradation, XRT contamination).
8. Invert. It runs utu.dem.plowman (smoothness 8) on log T 5.0 to 7.5, on all seven channels at every pixel, and on AIA alone for comparison. Over most of the box, the DEM from AIA alone predicts 3 to 18 times the observed XRT, with a median of 9.
9. Results. Emission measure maps in four temperature bins, a false-color image of the whole DEM made with named_arrays.colorsynth as in the sdo tutorial (linear scale up to the 99.5th percentile), the DEMs of the base and of the spire (joint and AIA only), and maps of χ² and of predicted over observed XRT.
10. Cross-calibration. A closing section says what Athiray & Winebarger (2024) and Del Zanna et al. (2022) found, and how to try a factor.

The inversion runs at full XRT resolution, by choice, until we've looked at the results.

Other changes

• Doc dependencies: solar-dynamics-observatory>=1.2, which is the first release with the AIA temperature response, and utu>=0.3.
• Intersphinx: entries for sunpy, sdo and utu.
• Bibliography: Lemen 2012, Boerner 2012, Boerner 2014, Plowman & Caspi 2020, Yoshimura & McKenzie 2015, Parker 2022, Athiray & Winebarger 2024, Del Zanna 2022.
• Index: a Tutorials section.

Things to know

• The build needs JSOC. The AIA images come from JSOC through sdo.aia.open. Earlier today JSOC answered NoDataDirectory for every AIA record for a few hours, which would break the docs build while it lasts.
• The grid starts at log T 5.0, not 5.5. The far wing of the 335 Å passband (0.4 to 2% of its peak area at 550 to 800 Å) takes in O V 629.7 Å and the other transition-region lines, so 335 Å responds more at log T 5.2 to 5.4 than at its Fe XVI peak, where the other channels respond at less than a fifth of their peaks. Starting at 5.5 left 145 pixels with χ² above 3, 32 of them around the base, where the joint DEM under-predicted 335 Å by 1.7 to 1.9 everywhere. Starting at 5.0 leaves one. Below 5.5 the DEM rests mostly on 335 Å and the smoothness, so ESIS O III, O IV and O V would be the independent check.
• The data barely constrain a cross-calibration factor now. On the new grid, multiplying the XRT response by 2 leaves the median χ² at 0.97 and puts 29 pixels above 3; 0.5 or 0.8 leaves none. On the old grid ×2 gave 1937, so that earlier preference against factors above 1 came from the grid. That's for the step 4 table, not the tutorial.
• Median reduced χ² is 0.97. The DEM predicts about 20% more XRT than observed in every pixel (5th to 95th percentile 1.16 to 1.31). That stays at 1.21 to 1.23 for any cross-calibration factor from 0.5 to 2, so it comes from the inversion stopping at χ² = 1, not from the calibration. The text says so, and that a smaller chi2_target fits it a little more closely (1.14 at 0.5). The DEM also predicts about 20% less 94 Å than observed, even with chiantifix.
• Two dark spots in XRT stand out in the ratio map. They look like contamination spots that the Level 1 processing didn't fill in. They are not masked.

Test plan

• sphinx-build -b html docs docs/_build succeeds locally with every cell executing, with one benign astropy VerifyWarning about BLANK in the AIA headers.
• All six figures were checked by eye, again after the grid change.
• Read the Docs build on this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_011VGPHLGJi8acbuLYSfBHTk

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.84%. Comparing base (35d848e) to head (ece1295).

Additional details and impacted files

@@           Coverage Diff           @@
##             main       #4   +/-   ##
=======================================
  Coverage   99.84%   99.84%           
=======================================
  Files          18       18           
  Lines        1968     1968           
=======================================
  Hits         1965     1965           
  Misses          3        3           

Flag	Coverage Δ
unittests	99.84% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.

[read-the-docs-community]

Documentation build overview

📚 hinode | 🛠️ Build #35076080 | 📁 Comparing ece1295 against latest (13f1915)

  🔍 Preview build  

8 files changed · + 1 added · ± 7 modified

+ Added

• tutorials/dem.html

± Modified

• genindex.html
• index.html
• _autosummary/hinode.xrt.Filtergram.html
• _autosummary/hinode.xrt.open.html
• _modules/hinode/xrt/_data.html
• _modules/hinode/xrt/_filtergrams.html
• _modules/hinode/xrt/_xrt.html