Export the coverage-suggestion builder so a caller can compute suggestions without rerunning the verb #75

New Issue

2026-10-04T08:37:37-04:00

jared commented

2026-10-04 08:37:37 -04:00

cog_chat now calls the internal .build_suggestions() directly (cog_chat #67, decision
0021), and would rather call an exported function.

Why. cog_chat builds each government's peer comparison with cog_spending() and
cog_revenue() over about 11 governments. Naming the categories, which is the only way
to get the "re-run with recipe = …" suggestions, adds about 0.2 s to every session that
opens a government, and most sessions never ask a peer question. cog_chat now calls both
verbs with no category, filters the rows to its categories, and builds the suggestions
only when the peer tool is first used. Building the suggestions alone takes about
0.15 s for Spokane's cohort; repeating both verbs with categories named takes about
0.55 s.

What it calls today (uscogdata 0.4.0), with the arguments .verb_spendrev() passes:

uscogdata:::.build_suggestions(
  uscogdata:::.ensure_session(),
  uscogdata:::.make_cohort(uscogdata:::.coerce_govid_input(govids, arg = "govid")),
  years, category, data.frame(year = years_present), "harmonized",
  flow_prefixes,                       # c("E","F","G") or c("T","A","U","B","C","D")
  uscogdata:::.select_long_view(view_base, "harmonized"),
  all_categories = FALSE, subtype_col = subtype_col,
  subtype_scope = uscogdata:::.expenditure_concept_subtypes("primary"))  # or .revenue_concept_subtypes("total")

That is seven internal names, any of which an upgrade can change.

Ask. An exported function that returns the same list the verbs attach as
attr(x, "provenance")$suggestions, for a set of governments, years, categories, a
flow and a concept, given the years the caller's rows cover. Something like
cog_suggestions(govid, years, category, flow = c("spending", "revenue"), concept, years_present).
The list's order is not stable today (two identical calls returned the same
suggestions in different orders), and a stable order would help a caller that compares
them.

cog_chat's suite checks the internal call against the verbs' own suggestions on every
run, so a change to the builder fails there before it reaches a reader.

cog_chat now calls the internal `.build_suggestions()` directly (cog_chat #67, decision 0021), and would rather call an exported function. **Why.** cog_chat builds each government's peer comparison with `cog_spending()` and `cog_revenue()` over about 11 governments. Naming the categories, which is the only way to get the "re-run with recipe = …" suggestions, adds about 0.2 s to every session that opens a government, and most sessions never ask a peer question. cog_chat now calls both verbs with no category, filters the rows to its categories, and builds the suggestions only when the peer tool is first used. Building the suggestions alone takes about 0.15 s for Spokane's cohort; repeating both verbs with categories named takes about 0.55 s. **What it calls today** (uscogdata 0.4.0), with the arguments `.verb_spendrev()` passes: ```r uscogdata:::.build_suggestions( uscogdata:::.ensure_session(), uscogdata:::.make_cohort(uscogdata:::.coerce_govid_input(govids, arg = "govid")), years, category, data.frame(year = years_present), "harmonized", flow_prefixes, # c("E","F","G") or c("T","A","U","B","C","D") uscogdata:::.select_long_view(view_base, "harmonized"), all_categories = FALSE, subtype_col = subtype_col, subtype_scope = uscogdata:::.expenditure_concept_subtypes("primary")) # or .revenue_concept_subtypes("total") ``` That is seven internal names, any of which an upgrade can change. **Ask.** An exported function that returns the same list the verbs attach as `attr(x, "provenance")$suggestions`, for a set of governments, years, categories, a flow and a concept, given the years the caller's rows cover. Something like `cog_suggestions(govid, years, category, flow = c("spending", "revenue"), concept, years_present)`. The list's order is not stable today (two identical calls returned the same suggestions in different orders), and a stable order would help a caller that compares them. cog_chat's suite checks the internal call against the verbs' own suggestions on every run, so a change to the builder fails there before it reaches a reader.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Civilytics/uscogdata#75