|
1 | | -# epiprocess 0.5.0.9999 (development version) |
| 1 | +# epiprocess 0.7.0 |
2 | 2 |
|
3 | 3 | Note that `epiprocess` uses the [Semantic Versioning |
4 | | -("semver")](https://semver.org/) scheme for all release versions, but not for |
5 | | -development versions. A ".9999" suffix indicates a development version. |
| 4 | +("semver")](https://semver.org/) scheme for all release versions, but any |
| 5 | +inter-release development versions will include an additional ".9999" suffix. |
| 6 | + |
| 7 | +## Breaking changes: |
| 8 | + |
| 9 | +* Changes to `epi_slide` and `epix_slide`: |
| 10 | + * If `f` is a function, it is now required to take at least three arguments. |
| 11 | + `f` must take an `epi_df` with the same column names as the archive's `DT`, |
| 12 | + minus the `version` column; followed by a one-row tibble containing the |
| 13 | + values of the grouping variables for the associated group; followed by a |
| 14 | + reference time value, usually as a `Date` object. Optionally, it can take |
| 15 | + any number of additional arguments after that, and forward values for those |
| 16 | + arguments through `epi[x]_slide`'s `...` args. |
| 17 | + * To make your existing slide computations work, add a third argument to |
| 18 | + your `f` function to accept this new input: e.g., change `f = function(x, |
| 19 | + g, < any other arguments>) { < body> } ` to `f = function(x, g, rt, <any |
| 20 | + other arguments>) { <body> }`. |
| 21 | + |
| 22 | +## New features: |
| 23 | + |
| 24 | +* `epi_slide` and `epix_slide` also make the window data, group key and reference |
| 25 | + time value available to slide computations specified as formulas or tidy |
| 26 | + evaluation expressions, in additional or completely new ways. |
| 27 | + * If `f` is a formula, it can now access the reference time value via `.z` or |
| 28 | + `.ref_time_value`. |
| 29 | + * If `f` is missing, the tidy evaluation expression in `...` can now refer to |
| 30 | + the window data as an `epi_df` or `tibble` with `.x`, the group key with |
| 31 | + `.group_key`, and the reference time value with `.ref_time_value`. The usual |
| 32 | + `.data` and `.env` pronouns also work, but`pick()` and `cur_data()` are not; |
| 33 | + work off of `.x` instead. |
| 34 | +* `epix_slide` has been made more like `dplyr::group_modify`. It will no longer |
| 35 | + perform element/row recycling for size stability, accepts slide computation |
| 36 | + outputs containing any number of rows, and no longer supports `all_rows`. |
| 37 | + * To keep the old behavior, manually perform row recycling within `f` |
| 38 | + computations, and/or `left_join` a data frame representing the desired |
| 39 | + output structure with the current `epix_slide()` result to obtain the |
| 40 | + desired repetitions and completions expected with `all_rows = TRUE`. |
| 41 | +* `epix_slide` will only output grouped or ungrouped tibbles. Previously, it |
| 42 | + would sometimes output `epi_df`s, but not consistently, and not always with |
| 43 | + the metadata desired. Future versions will revisit this design, and consider |
| 44 | + more closely whether/when/how to output an `epi_df`. |
| 45 | + * To keep the old behavior, convert the output of `epix_slide()` to `epi_df` |
| 46 | + when desired and set the metadata appropriately. |
| 47 | + |
| 48 | +## Improvements: |
| 49 | + |
| 50 | +* `epi_slide` and `epix_slide` now support `as_list_col = TRUE` when the slide |
| 51 | + computations output atomic vectors, and output a list column in "chopped" |
| 52 | + format (see `tidyr::chop`). |
| 53 | +* `epi_slide` now works properly with slide computations that output just a |
| 54 | + `Date` vector, rather than converting `slide_value` to a numeric column. |
| 55 | + |
| 56 | +# epiprocess 0.6.0 |
| 57 | + |
| 58 | +## Breaking changes: |
| 59 | + |
| 60 | +* Changes to both `epi_slide` and `epix_slide`: |
| 61 | + * The `n`, `align`, and `before` arguments have been replaced by new `before` |
| 62 | + and `after` arguments. To migrate to the new version, replace these |
| 63 | + arguments in every `epi_slide` and `epix_slide` call. If you were only using |
| 64 | + the `n` argument, then this means replacing `n = <n value>` with `before = |
| 65 | + <n value> - 1`. |
| 66 | + * `epi_slide`'s time windows now extend `before` time steps before and |
| 67 | + `after` time steps after the corresponding `ref_time_values`. See |
| 68 | + `?epi_slide` for details on matching old alignments. |
| 69 | + * `epix_slide`'s time windows now extend `before` time steps before the |
| 70 | + corresponding `ref_time_values` all the way through the latest data |
| 71 | + available at the corresponding `ref_time_values`. |
| 72 | + * Slide functions now keep any grouping of `x` in their results, like |
| 73 | + `mutate` and `group_modify`. |
| 74 | + * To obtain the old behavior, `dplyr::ungroup` the slide results immediately. |
| 75 | +* Additional `epi_slide` changes: |
| 76 | + * When using `as_list_col = TRUE` together with `ref_time_values` and |
| 77 | + `all_rows=TRUE`, the marker for excluded computations is now a `NULL` entry |
| 78 | + in the list column, rather than a `NA`; if you are using `tidyr::unnest()` |
| 79 | + afterward and want to keep these missing data markers, you will need to |
| 80 | + replace the `NULL` entries with `NA`s. Skipped computations are now more |
| 81 | + uniformly detectable using `vctrs` methods. |
| 82 | +* Additional`epix_slide` changes: |
| 83 | + * `epix_slide`'s `group_by` argument has been replaced by `dplyr::group_by` and |
| 84 | + `dplyr::ungroup` S3 methods. The `group_by` method uses "data masking" (also |
| 85 | + referred to as "tidy evaluation") rather than "tidy selection". |
| 86 | + * Old syntax: |
| 87 | + * `x %>% epix_slide(<other args>, group_by=c(col1, col2))` |
| 88 | + * `x %>% epix_slide(<other args>, group_by=all_of(colname_vector))` |
| 89 | + * New syntax: |
| 90 | + * `x %>% group_by(col1, col2) %>% epix_slide(<other args>)` |
| 91 | + * `x %>% group_by(across(all_of(colname_vector))) %>% epix_slide(<other args>)` |
| 92 | + * `epix_slide` no longer defaults to grouping by non-`time_value`, non-`version` |
| 93 | + key columns, instead considering all data to be in one big group. |
| 94 | + * To obtain the old behavior, precede each `epix_slide` call lacking a |
| 95 | + `group_by` argument with an appropriate `group_by` call. |
| 96 | + * `epix_slide` now guesses `ref_time_values` to be a regularly spaced sequence |
| 97 | + covering all the `DT$version` values and the `version_end`, rather than the |
| 98 | + distinct `DT$time_value`s. To obtain the old behavior, pass in |
| 99 | + `ref_time_values = unique(<ungrouped archive>$DT$time_value)`. |
| 100 | +* `epi_archive`'s `clobberable_versions_start`'s default is now `NA`, so there |
| 101 | + will be no warnings by default about potential nonreproducibility. To obtain |
| 102 | + the old behavior, pass in `clobberable_versions_start = |
| 103 | + max_version_with_row_in(x)`. |
| 104 | + |
| 105 | +## Potentially-breaking changes: |
| 106 | + |
| 107 | +* Fixed `[` on grouped `epi_df`s to maintain the grouping if possible when |
| 108 | + dropping the `epi_df` class (e.g., when removing the `time_value` column). |
| 109 | +* Fixed `epi_df` operations to be more consistent about decaying into |
| 110 | + non-`epi_df`s when the result of the operation doesn't make sense as an |
| 111 | + `epi_df` (e.g., when removing the `time_value` column). |
| 112 | +* Changed `bind_rows` on grouped `epi_df`s to not drop the `epi_df` class. Like |
| 113 | + with ungrouped `epi_df`s, the metadata of the result is still simply taken |
| 114 | + from the first result, and may be inappropriate |
| 115 | + ([#242](https://github.com/cmu-delphi/epiprocess/issues/242)). |
| 116 | +* `epi_slide` and `epix_slide` now raise an error rather than silently filtering |
| 117 | + out `ref_time_values` that don't meet their expectations. |
| 118 | + |
| 119 | +## New features: |
| 120 | + |
| 121 | +* `epix_slide`, `<epi_archive>$slide` have a new parameter `all_versions`. With |
| 122 | + `all_versions=TRUE`, `epix_slide` will pass a filtered `epi_archive` to each |
| 123 | + computation rather than an `epi_df` snapshot. This enables, e.g., performing |
| 124 | + pseudoprospective forecasts with a revision-aware forecaster using nested |
| 125 | + `epix_slide` operations. |
| 126 | + |
| 127 | +## Improvements: |
| 128 | + |
| 129 | +* Added `dplyr::group_by` and `dplyr::ungroup` S3 methods for `epi_archive` |
| 130 | + objects, plus corresponding `$group_by` and `$ungroup` R6 methods. The |
| 131 | + `group_by` implementation supports the `.add` and `.drop` arguments, and |
| 132 | + `ungroup` supports partial ungrouping with `...`. |
| 133 | +* `as_epi_archive`, `epi_archive$new` now perform checks for the key uniqueness |
| 134 | + requirement (part of |
| 135 | + [#154](https://github.com/cmu-delphi/epiprocess/issues/154)). |
6 | 136 |
|
7 | 137 | ## Cleanup: |
8 | 138 |
|
9 | 139 | * Added a `NEWS.md` file to track changes to the package. |
| 140 | +* Implemented `?dplyr::dplyr_extending` for `epi_df`s |
| 141 | + ([#223](https://github.com/cmu-delphi/epiprocess/issues/223)). |
10 | 142 | * Fixed various small documentation issues ([#217](https://github.com/cmu-delphi/epiprocess/issues/217)). |
11 | 143 |
|
12 | 144 | # epiprocess 0.5.0: |
|
0 commit comments