Name matchData()'s arguments for what they are

[chross22]

matchData() joins two sf point objects by space and time. It was never specific to species observations or environmental data — but speciesDat and envDat described one use of it as though it were the only one, and the docs followed the names, so the general case was invisible.

matchData(dat, source)

dat is the side that gets columns added; source is the side they come from. Tag positions against a model field, moorings against satellite retrievals, one gridded product against another — all the same operation, and now obviously so. There's a test that matches two grids to each other with nothing species-shaped involved.

The old names still work

They warn, but they work:

matchData(observations, env)                 # positional, unchanged
matchData(dat = observations, source = env)  # new
matchData(speciesDat = obs, envDat = env)    # still works, warns

taupatch calls them by name at R/covariates.R:271, and any script written against the old signature does too. Breaking those silently would be worse than carrying a shim. Verified against taupatch's exact call form after rebuilding:

warn: `speciesDat` is now `dat`...
warn: `envDat` is now `source`...
taupatch call works, SST: 2 9

One related change

The collision suffix moves from .env to .matched, for the same reason. Nothing depended on the old one — checked across this package, taupatch, and derivoce.

Thoroughness

The rename goes all the way down, not just the signature:

• detect_temporal_resolution() takes x rather than envDat
• standardize_time_columns() takes dat, and its errors say `dat` rather than "speciesDat"
• the CRS errors name `dat` / `source`
• every call site in the roxygen and README shows the new names
• the README section is retitled from "Matching to observations" to "Matching", and leads with the general case
• test fixtures renamed from make_species_dat/make_env_dat to make_observations/make_env

Four new tests: the deprecation shim (both names, and that old and new produce identical results), positional and named forms, the .matched suffix leaving the caller's column untouched, and a grid-to-grid match.

Verification

R CMD check — Status: OK. Full suite green. Installed into both R 4.6.1 and 4.3.2. All README anchors re-checked.

🤖 Generated with Claude Code