[Epic H] User-Facing API Ergonomics & Dependency Reduction

[chris-prener]

[Epic H] User-Facing API Ergonomics & Dependency Reduction

Goal

Make zippeR's public API self-contained and idiomatic for R users, and close out the Phase 3 dependency-reduction research deferred from Epic E. By the end of this epic, a user should be able to complete every setup and analysis step through zi_-prefixed functions without reaching into another package, and we should have a decided (not open-ended) position on dplyr and on bare-name argument support.

Why now?

Epic E's dependency-reduction work removed six Imports (purrr, spatstat.univar, stringr, httr, readr, tidyr) but explicitly deferred two Phase 3 items — #86 (dplyr removal, 108 call sites) and #88 (bare/unquoted column names via base R NSE) — as too large to fold into an audit epic. Both are research-first items whose conclusions shape the package's long-term API and dependency posture, so they should be settled before the next feature cycle rather than carried indefinitely.

Separately, #108 surfaced a concrete ergonomics gap: the Census API key setup step is the only piece of package setup that requires calling a function from a different package (tidycensus::census_api_key()). That is a small, well-scoped fix that belongs with the same theme.

Acceptance criteria (epic-level)

• zi_census_api_key() is exported, documented, tested, and referenced from zi_get_demographics(), zi_aggregate(), the README, and the vignettes (feat: add zi_census_api_key() wrapper around tidycensus::census_api_key() #108).
• The dplyr removal question (research: evaluate dplyr removal feasibility (108 call sites) #86) reaches a documented decision — either an ADR recording the intent to remove with a phased plan, or an ADR/issue comment recording an explicit decision to retain dplyr with rationale. "Still researching" is not an acceptable end state.
• The bare-name NSE question (enhancement: support bare (unquoted) column name inputs via base R NSE #88) reaches a documented decision with the same standard, including an explicit stance on backwards compatibility for existing character-string inputs.
• No user-facing documentation instructs the user to call a non-zippeR function to complete core package setup.
• R CMD check remains at 0 errors / 0 warnings / 0 notes throughout.

Decisions and constraints

• tidycensus stays. feat: add zi_census_api_key() wrapper around tidycensus::census_api_key() #108 wraps it rather than reimplementing key storage; tidycensus is already a hard Import and is the upstream for demographic retrieval.
• No rlang. Per enhancement: support bare (unquoted) column name inputs via base R NSE #88's original framing, any NSE work must use base R (substitute(), deparse(), match.call()) — adding rlang would run directly counter to the dependency-reduction goal.
• Backwards compatibility is non-negotiable. Character-string column inputs must keep working regardless of what enhancement: support bare (unquoted) column name inputs via base R NSE #88 concludes. Any breaking change would require its own ADR and a deprecation cycle matching the input_zip/dict precedent (chore: remove deprecated arguments (input_zip, dict) from zi_crosswalk() #71).
• Research issues may conclude "no". Deciding to keep dplyr is a valid, epic-completing outcome if the base R rewrite would materially hurt readability or maintainability.
• ADR expected for research: evaluate dplyr removal feasibility (108 call sites) #86 and enhancement: support bare (unquoted) column name inputs via base R NSE #88 outcomes — both are structural choices future sessions could re-litigate, which is exactly the ADR bar in .github/copilot-instructions.md.

Sub-issues

• feat: add zi_census_api_key() wrapper around tidycensus::census_api_key() #108 — feat: add zi_census_api_key() wrapper around tidycensus::census_api_key()
• research: evaluate dplyr removal feasibility (108 call sites) #86 — research: evaluate dplyr removal feasibility (108 call sites)
• enhancement: support bare (unquoted) column name inputs via base R NSE #88 — enhancement: support bare (unquoted) column name inputs via base R NSE

Dependencies

graph TD
  86["#86 dplyr removal research"] --> 88["#88 bare-name NSE"]
  108["#108 zi_census_api_key()"]

Loading

• research: evaluate dplyr removal feasibility (108 call sites) #86 should be decided before enhancement: support bare (unquoted) column name inputs via base R NSE #88 — if dplyr is removed, the NSE surface is rewritten anyway, and the two decisions would otherwise be made against different assumptions about the internals.
• feat: add zi_census_api_key() wrapper around tidycensus::census_api_key() #108 is fully independent and can ship first.

Related work

• Requirements doc: none — tiny-epic bypass
• Supporting objective: O1 (CRAN-ready package quality) in docs/OBJECTIVES.md
• ADRs: to be filed at research: evaluate dplyr removal feasibility (108 call sites) #86 and enhancement: support bare (unquoted) column name inputs via base R NSE #88 decision points
• Predecessors: [Epic E] [Epic E] Code & Test Quality Audit #48 (Code & Test Quality Audit) — deferred research: evaluate dplyr removal feasibility (108 call sites) #86 and enhancement: support bare (unquoted) column name inputs via base R NSE #88 to this epic
• Successors: [Epic J] — next release, which ships whatever lands here; [Epic L] [Epic L] dplyr Removal Implementation #129 — follow-up implementation epic executing ADR-0005's dplyr removal decision once research: evaluate dplyr removal feasibility (108 call sites) #86 (this epic's research sub-issue) closes

Out of scope

• Actually executing a full dplyr removal. research: evaluate dplyr removal feasibility (108 call sites) #86 is research; the implementation, if approved, becomes its own epic.
• Removing tibble — already evaluated and closed in research: evaluate tibble dependency (coupled to dplyr ecosystem) #87.
• Removing deprecated zi_crosswalk() arguments (chore: remove deprecated arguments (input_zip, dict) from zi_crosswalk() #71) — time-gated to early 2027, tracked separately.
• CI/CD and infrastructure work — see [Epic I].