Vignette polish: prose tightening, formatting, structure (citations + km² + highways + towns + chunk hiding)#72
Merged
Conversation
Tightens the v0.2.5/v0.2.6 vignette citations so the source's specific findings show up in the prose rather than as end-of-statement attributions. Drops one cite that was decorative- only. Same edits applied to both regional vignettes. Per-cite changes (each appears in both kootenay-lake.Rmd and peace-fwcp.Rmd): - **Arguez and Vose 2011 — DROPPED.** The cite was attached to a prose claim that 1981-2010 is the WMO standard climate normal. Well-known fact; the cite was decorative. Removing it cleans up one of the weaker attributions. - **Karl 1993 — TIGHTENED.** Was: "is one of the textbook fingerprints of greenhouse warming [@karl_etal1993NewPerspective]." Now: "...textbook fingerprints. @karl_etal1993NewPerspective documented this first at the global scale, finding overnight minimums rose at roughly three times the rate of daytime maximums between 1951 and 1990 (0.84 vs 0.28 °C)." Surfaces the 3:1 ratio + actual numbers from Karl's NH-and-some-SH analysis. - **Mantua 2010 + Eaton-Scheller 1996 — TIGHTENED.** Was a single end-of-statement [@Cite1; @cite2] attribution. Now: distinct sentences naming Mantua's Washington-State scope + projection of reduced reproductive success, plus Eaton & Scheller's 57-species comparative finding (cold/cool-water lose more thermal habitat than warm-water under same forcing). - **Kang 2016 — TIGHTENED.** Was: "Fraser Basin documents the same kind of freshet advance [@kang_etal2016ImpactsRapidly] at comparable magnitude." Now: "@kang_etal2016ImpactsRapidly documented a ~10-day advance in the spring freshet at Hope between 1949 and 2006, with persistent declines through autumn recession just when salmon are migrating up the Fraser." Surfaces the 10-day number + the salmon-migration-window detail that maps directly onto the FWCP fish-passage audience. Hansen 2012, Pepin 2015 + Rangwala-Miller 2012, and Ficklin-Novick 2017 left as-is — each was already doing prose work in v0.2.5/v0.2.6. Independent Explore subagent re-verified the specific numbers (3:1 ratio, 0.84/0.28 C, Washington watersheds, 57 species, ~10-day advance, 1949-2006 window, Hope gauge) against source quote archives + PDFs. All matched. No edits recommended. vignettes/references.bib regenerated via data-raw/regenerate_bib.R (the v0.2.7 helper) — drops from 18 to 17 entries (Arguez & Vose removed). Kootenay and peace-fwcp now cite the same 17-key set. Refs #71.
Two vignette polish fixes that go alongside the citation tightening: - **km^2 → km²** in 4 places (2 per vignette: AOI map fig.cap + ggplot subtitle). The literal "^2" was rendering as caret-2 text rather than a superscript. Unicode km² renders correctly in both pandoc-html and ggplot-text contexts. - **Highway symbology** lifted from the gq registry (/Users/airvine/Projects/repo/gq/inst/registry/reg_qgis_restoration.json, the RH1/RH2 entries): grey casing (#9c9c9c) under warm-yellow fill (#ffe585), drawn as two stacked geom_sf calls. Replaces the prior solid #333333 single-stroke. Reads more like a topographic map. Applied to both AOI maps (linewidth 0.75 + 0.5) and both Spatial Pattern maps (linewidth 0.6 + 0.4).
NewGraphEnvironment
changed the title
Hides 14 chunks in kootenay-lake.Rmd and 12 in peace-fwcp.Rmd. Targets: AOI map, Spatial Pattern map, plot-dtr (manual), all facet ggplots, all kableExtra wrappers (snow-seasonal-table, rollup, wsg-ecoregion-table), WSG map, load-aoi (data plumbing). Visible code now dominated by cd_*() calls (catalog, extract, plot-tmean/prcp/tmax/tmin, snow-swe-max/doy-50/rate-peak/fraction) plus the precomputed-data load + cd recipe comment blocks (Phase 2 will lift those out). Both vignettes render cleanly post-edit (rmarkdown::render verified; no chunk eval breakage; figures + tables produced as before).
…chunks Splits 5 chunks in kootenay-lake.Rmd and 4 in peace-fwcp.Rmd. Each former 'mixed-content' chunk (cd recipe in '# Equivalent to:' comment + render code) becomes a pair: a shown eval=FALSE chunk displaying the cd code the user would write live, plus an echo=FALSE companion that does the actual rds load + render. Splits applied: - extract → extract-recipe (cd_extract) + extract-load - trend → trend-recipe (cd_baseline + cd_anomaly + cd_trend + cd_summary) + trend-table - compare → compare-recipe (cd_compare) + compare-table - per-ecoregion-compute → per-ecoregion-recipe (full cd loop: cd_extract -> cd_baseline -> cd_anomaly -> cd_trend -> cd_compare per polygon) + per-ecoregion-reshape - per-wsg-compute (kootenay only) → per-wsg-recipe + per-wsg-reshape Reader's flow now: cd recipe (visible, copy-pasteable) -> output (table or figure, source hidden). The cd API is the visible code in the vignette rather than buried inside comment blocks beneath ggplot/kableExtra boilerplate. Both vignettes render cleanly after the splits — no eval-order regressions, all variables (ts, ano, trn, cmp, results, wsg_results) remain in scope for downstream chunks.
NewGraphEnvironment
changed the title
Makes the package source explicit at every visible (and hidden) function call. Reader sees `cd::cd_extract(catalog, aoi)` not just `cd_extract(catalog, aoi)` — pedagogically obvious which function comes from which package, especially in the per-ecoregion / per-WSG loops where cd functions are interleaved with base R lapply / list / seq_len / nrow. Affected functions: cd_catalog, cd_crop, cd_extract, cd_baseline, cd_anomaly, cd_compare, cd_trend, cd_summary, cd_plot_timeseries, cd_plot_comparison. Mechanically applied via a single sed pass per vignette using a word-boundary-aware regex (matches bare cd_<func>( only, won't double-prefix already-prefixed calls). Inline references in narrative prose (e.g. "`cd_extract()` crops...") also picked up the prefix for consistency. Both vignettes render cleanly post-edit.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bundle of regional-vignette polish in one PR. Four themes:
1. Citation prose tightening (the original scope)
Tightened end-of-statement parenthetical attributions ("name-drop") into prose that surfaces the source's specific findings ("doing-work"). Same edits applied to both vignettes (they share the cite set).
arguez_vose2011DefinitionStandard— was attached to "1981-2010 = WMO standard" which is a well-known fact, not a methodology argument needing peer-reviewed grounding.Independent Explore subagent re-verified every specific number/finding lifted into the prose against source archives + PDFs. All matched. No edits required.
2. km² + highway styling polish
km^2→km²in 4 places (fig captions + ggplot subtitles). Was rendering as caret-2 text.gq/inst/registry/reg_qgis_restoration.json(theRH1/RH2entries): grey casing (#9c9c9c) under warm-yellow fill (#ffe585), drawn as two stackedgeom_sfcalls — reads like a topo map. Replaces prior solid#333333single-stroke. Applied to both AOI maps + both Spatial Pattern maps.3. Kootenay town filter
Reduced
inst/extdata/context_kootenay_lake.gpkgtowns layer from 12 → 6: Rossland, Castlegar, Nelson, Cranbrook, Kaslo, Nakusp. Updateddata-raw/example_context_kootenay_lake.Rto keep the canonical source consistent.4. Vignette chunk hide + cd-recipe lift (Option B restructure)
Both vignettes' visible code was dominated by ggplot/kableExtra/dplyr boilerplate, with cd_*() calls buried in
# Equivalent to:comment blocks. Restructured:echo = FALSE). 14 chunks in kootenay, 12 in peace. Targets: AOI map, Spatial Pattern map, manual DTR plot, all facet ggplots, all kableExtra wrappers (snow-seasonal-table, rollup, wsg-ecoregion-table), WSG map, load-aoi (data plumbing). Outputs (figures + tables) still visible; source code hidden.eval = FALSEcompanion chunks. 5 splits in kootenay, 4 in peace:extract→extract-recipe(cd_extract) +extract-loadtrend→trend-recipe(cd_baseline + cd_anomaly + cd_trend + cd_summary) +trend-tablecompare→compare-recipe(cd_compare) +compare-tableper-ecoregion-compute→per-ecoregion-recipe(full cd loop per polygon) +per-ecoregion-reshapeper-wsg-compute(kootenay only) →per-wsg-recipe+per-wsg-reshapeReader's flow becomes: cd recipe (visible, copy-pasteable) → output (table/figure, source hidden) → narrative. The cd API is the visible code rather than ggplot fluff. Snow-section chunks (
snow-swe-max,snow-doy-50,snow-rate-peak,snow-fraction) are kept visible — they're already purecd_trend()+cd_plot_timeseries()calls.vignettes/references.bibregenerated via the v0.2.7data-raw/regenerate_bib.Rhelper — drops 18 → 17 entries (Arguez & Vose removed). Both vignettes share the same 17-key set.Relates to NewGraphEnvironment/sred-2025-2026#23.
Fixes #71.
Test plan
rmarkdown::render(locally verified after each phase + after combined edits)[@key]markers resolve in both vignettesvignettes/references.bibhas 17 entriescd_*()calls🤖 Generated with Claude Code