Reorganize revision analysis around interpretation questions

[jingjtang]

Summary

This PR restructures the revision analysis report into a question-driven narrative.

@JavierMtzRdz @RoniRos, the preview link is here:
https://jingjtang.github.io/analysis-notebooks/revision_analysis/revision_hospital_admissions_smoothed_covid19_from_claims_api_state.html

Major changes

1. Reorganized the report structure around analytic questions

The previous report was organized around reporting latency, revision duration, bias, location bias, and convergence as separate technical sections. The new structure follows the reader’s likely workflow:

• Is the first published value biased?
• How soon can we trust the signal?
• Is revision behavior different by location?
• Are there patterns over observation time?
• Are revision patterns related to other signal features?

This makes the report easier to scan and aligns repeated visualizations across overall, location, and time views.

2. Clarified terminology for version, issue, reference date, and lag

Readers may see in the “results at a glance” table that the claims signal starts to be reported at lag 3, but this should not be interpreted as meaning that data are unavailable to Delphi before that point. For some preprocessed API signals, especially smoothed signals, the earliest versions may be intentionally withheld from public reporting because they are not yet reliable enough for interpretation. In this sense, the API issue or version date is better understood as a publication or processing timestamp, rather than necessarily the first date when the underlying raw data became available.

The definition of lag was also ambiguous in the previous report. It used two related quantities:

• days since first publication: version - first_report
• published-version lag: version - time_value, where time_value is the reference date

This distinction can be confusing for readers who are not already familiar with the data structure, and it can make some figures harder to compare. In this revision, I make the lag definition consistent throughout the report:
lag = version - time_value

@RoniRos, what do you think about this choice? We can change it back if the previous definition seems more informative for some analyses.

3. Standardized revision-distance and stabilization views

As for the shared “revision distance” definition: abs(published value - latest value) / abs(latest value)
(@JavierMtzRdz @RoniRos, “revision distance” may not be the best name, so suggestions are welcome)
The report reuses this same definition across overall, by-location, and by-season views, making the plots easier to compare. Cumulative stabilization plots and median/IQR revision-distance curves are presented in a more consistent order and style.

4. Improved location-level reporting

Location sections now use HHS region ordering and labels. Location plots include HHS grouping annotations, uppercase state labels, and HHS-region paged views where needed to avoid overcrowded state-level facets.

5. Added surveillance-season time analysis

Calendar-year comparisons were replaced with MMWR week 40-39 surveillance seasons. The report explains this choice and applies it consistently to time-based revision summaries.

6. Expanded exploratory signal-feature diagnostics

Section 5 now explores additional dimensions beyond location and time:
signal magnitude vs. relative spread
revision-distance heatmap by reference date and lag
revision distance by initial publication lag

TODO

Currently works for state-level daily data. Compatibility with weekly and county-level data still needs to be tested.

[jingjtang]

@RoniRos @JavierMtzRdz
I made some updates to the revision analysis notebook. Please feel free to take a look at the new version:

https://jingjtang.github.io/analysis-notebooks/revision_analysis/revision_hospital_admissions_smoothed_covid19_from_claims_api_state.html

I would love to hear your thoughts, especially on:

1. Whether any terminology, notation, or figure design is unclear.
2. Whether the narrative is easy to follow and flows naturally.
3. Whether there are any additional diagnostics, explanations, or visualizations that you think would be useful to include.

• Clarified the notation section
• Updated terminology throughout:
  • Replaced ambiguous uses of “value” with “Report value”.
  • Replaced unclear “observation” language with either “report” or “location-reference-date pair”, depending on the analysis unit.
  • Replaced “observation time” with “reference date”.
  • Replaced “observation season” with “epi season”.
  • Replaced “Final revision” with the 0% threshold.
  • Standardized “Relative Error spread” terminology.
• Updated the configuration table:
  • Added “Minimum revision history”, default was set to be 1 year.
• Performance/code organization updates:
  • Added shared preprocessing objects to avoid repeated calculations.
  • Cached several expensive chunks.
  • Standardized internal naming where helpful, e.g. pair_summary, epi_season, and n_reports.