revision analysis first draft

[dsweber2]

Checklist

Please:

• Make sure this PR is against "dev", not "main" (unless this is a release
  PR).
• Request a review from one of the current main reviewers:
  brookslogan, nmdefries.
• Makes sure to bump the version number in DESCRIPTION. Always increment
  the patch version number (the third number), unless you are making a
  release PR from dev to main, in which case increment the minor version
  number (the second number).
• Describe changes made in NEWS.md, making sure breaking changes
  (backwards-incompatible changes to the documented interface) are noted.
  Collect the changes under the next release number (e.g. if you are on
  1.7.2, then write your changes under the 1.8 heading).
• See DEVELOPMENT.md for more information on the development
  process.

Change explanations for reviewer

This adds a function that computes some per-epi-key (so normally geo_value-time_value pairs) stats about revisions. Under normal operation it drops all NA values so they are treated as missing. It returns a tibble that has 1 row for each epi-key, with columns:

1. min_lag: the minimum time to any value (if drop_nas=FALSE, this includes NA's)
2. max_lag: the amount of time until the final (new) version (same caveat for drop_nas=FALSE, though it is far less likely to matter)
3. max_change: the difference between the smallest and largest values (this always excludes NA values)
4. max_rel_change: max_change divided by the largest value (so it will always be less than 1). Note that this need not be the final value. It will be NA whenever max_change is 0.
5. time_to_x_final: where x is the percent_final_value (default). This gives the lag when the value is within 1-x of the value at the final time. For example, consider the series (0,20, 99, 150, 102, 100); then time_to_x_final is the 5th index, since even though 99 is within 20%, it is outside the window afterwards at 150.

The function also (optionally) prints out an overall summary of this summary.

This PR factors out compactification into a standalone function (since I needed it to drop NAs effectively.

Still to do:

• basic tests on a simple example
• make sure the docs make sense and include reasonable examples

Magic GitHub syntax to mark associated Issue(s) as resolved when this is merged into the default branch

• Resolves basic revision analysis stats #491

[dsweber2]

❯ checking dependencies in R code ... WARNING
  '::' or ':::' import not declared from: ‘glue’

makes no sense, the only usage of glue is via glue::glue. thanks Logan, I was looking at the wrong description

[brookslogan]

Sorry, I got caught up on a few style/convention/technicalities points. Main "substantive" things are that I think the names of some quantities need some brainstorming.

Need to do another pass about correctness (think we flagged some things on Slack).

[brookslogan]

• Complaining/brainstorming more about naming.
• I'm getting some surprising results regarding min and max lags. Think there might be a bug here and maybe some pre-existing issues. Hoping you can figure out what's up before we push the button on this. user error

[brookslogan]

Suggested change

	return(revision_behavior)
	return(invisible(revision_behavior))

---

idea: we might also want to make this an S3-classed thing with a print that will print the summary + a pointer to use as_tibble() to get the underlying data.

[dsweber2]

I dunno, I personally find printing the full thing under if you haven't assigned it to a variable to be somewhat useful, if maybe a bit cluttered.

[brookslogan]

Sure. Might consider then:

• [Adding some sort of explanatory blurb to explain what this tibble is... it'd be convenient to just tack this on to the end of the summary you print, but might be a little hard to word]
• Alternatively, if printing the summary, also explicitly print revision_behavior, but with a little explanatory blurb beforehand, and returning invisibly if the summary printing was requested (to not double-print it) [--- maybe this is too much clutter..]

(Any way, always returning invisibly isn't the right thing. Should definitely return visibly if the summary wasn't printed.)

[brookslogan]

Realized my previous main concern wasn't actually an issue.