\value{} section to polish() via a
new @return roxygen block, addressing CRAN feedback that
man/polish.Rd was missing the \value tag.DESCRIPTION
Description field in the authors (year) <doi:...>
form required by CRAN: Grossetti, Ieva and Paganoni (2018) doi:10.1007/s10729-017-9400-z. The same reference was
already documented under @references in
augment().survplot() no longer accepts the out
argument and now always returns a gg/ggplot object. The
fitted survival curve and the Kaplan-Meier curve are exposed as named
fields on the returned plot for parity with prevplot():
p <- survplot(model, km = TRUE)
p # prints the plot
p$fitted # data.table — survival probabilities
p$km # data.table — Kaplan-Meier curveCloses #4.
Code that previously did
out <- survplot(..., out = "all") and then unwrapped
through out$p, out$fitted, out$km
should drop the out argument and access the data tables
directly on the plot. The return type collapsing from a wrapper list to
a ggplot means that ggplot operations now compose without unwrapping:
p + theme_bw(), ggsave("plot.pdf", p), and
patchwork-style combinations all work on the returned plot
directly.
Calls passing out = ... raise a clear migration error
pointing to the new pattern. The trampoline that catches the legacy
argument will itself be removed in v2.3.0.
prevplot() exposes the long-format prevalence data used
to build the plot via p$prevalence, so both plotting
functions now expose their data through the same $ idiom.
The field is populated on both the M = FALSE
(ggplot) and M = TRUE (patchwork)
return paths.survplot()
out = ... shapes with attribute-field assertions on the
returned plot, plus a regression test for the legacy-argument
trampoline.prevplot() populates
$prevalence on the M = FALSE,
ci = TRUE, and M = TRUE paths.survplot() roxygen @returns
and @details sections around the new contract. The vignette
and worked examples in man/survplot.Rd now demonstrate the
$fitted / $km access pattern.$prevalence field on
prevplot()’s @returns.augment() now closes the post-discharge observation
window of alive subjects at t_cens instead of repeating the
last t_end. Previously, the final transition row for any
subject who survived to the censoring date carried the same time as the
preceding row, silently truncating the at-risk window. Any
msm model fitted on the augmented data was therefore
biased: transition-rate estimates were systematically pulled downward
because every alive subject’s post-discharge follow-up was collapsed to
zero duration. Closes #7.
Models refit on augment() output produced with
msmtools 2.1.4 or later will give different (and more
correct) parameter estimates than models fitted on output from earlier
versions. The behaviour of subjects who died (pattern
values 1 or 2) is unchanged.
The internal regression fixture
tests/testthat/fixtures/augment-hosp-date.rds has been
regenerated against the corrected augment()
output.
Added regression coverage for the at-risk window of alive subjects and for the unchanged time semantics of subjects who died.
Completed the data.table bracket-spacing normalisation started in
the 2.1.3 audit. R/augment.R,
R/augment-helpers.R, and the testthat files now share the
unspaced dt[, col := value] convention already used by the
plotting and polish sources.
.onAttach() is excluded from coverage reports via
# nocov markers; startup messages add nothing to test
signal.
patchwork moved from Imports to
Suggests. It is only required by
prevplot(M = TRUE), which now issues an informative error
when the package is not installed.
scales removed entirely. The single percent
formatter used by prevplot() is now an inline labeller,
eliminating a hard runtime dependency.
Generalised the package framing to longitudinal observational data of any domain; the bundled hospital dataset remains the worked example but is no longer presented as the only use case.
Minor wording tweaks in augment() and
prevplot() Rd to drop clinical-specific terminology where
it did not add precision.
prevplot(M = TRUE) guarded by
testthat::skip_if_not_installed("patchwork"), so the suite
remains green on CRAN’s --no-suggests runs..Rbuildignore to exclude generated tarballs,
PDFs, and any local planning scratch directories.Added print_plot to survplot() and
prevplot(). The default print_plot = TRUE
preserves the previous interactive behavior, while
print_plot = FALSE returns plot objects without printing
them.
Added verbosity to survplot() and
prevplot() and replaced direct console output with the
shared cli verbosity helpers.
Added clearer argument validation for plotting flags, grid sizes, bootstrap sizes, time ranges, custom times, and state selectors.
Qualified plotting calls to external package functions explicitly instead of relying on roxygen imports.
Made polish() time-column handling explicit.
Omitting time or setting time = NULL now
auto-detects augmented_int, then
augmented_num; calls error clearly when neither column is
available.
Replaced remaining polish() console output with the
shared cli verbosity helpers used by
augment().
Qualified polish() calls to external
data.table functions explicitly instead of relying on
roxygen imports.
Added clearer validation for polish() inputs,
including missing columns and terminal outcome schemas with anything
other than 2 or 3 unique values.
polish() time-column auto-detection
behavior.polish() time resolution,
missing columns, invalid pattern schemas, missing-value checks, and
summary verbosity.Added a copy argument to augment() and
polish(). The default copy = FALSE preserves
the historical memory-efficient by-reference behavior, while
copy = TRUE protects caller-owned data before
preprocessing.
Clarified the preprocessing contract around
data.table by-reference semantics.
augment() may add n_events and change the
input key when copy = FALSE; polish() may
change the input key while identifying duplicate transitions.
Added shared validation for scalar logical flags used by preprocessing functions.
Made the augment() state vocabulary stricter and
clearer: custom state values must now be supplied as a
character vector of three unique labels, not as a list.
Made more_status = NULL explicit in
augment() so the optional expanded status path is visible
in the function signature.
Documented the performance and safety tradeoff behind
copy = FALSE and copy = TRUE in the function
help, README, and vignette.
Clarified that pattern describes the terminal
outcome schema, while state describes the generated
transition-state labels.
Added tests covering by-reference preservation with
copy = FALSE, input protection with
copy = TRUE, and validation of logical flags.
Added tests for custom state vectors, invalid state
specifications, and explicit more_status = NULL.
Split augment() into private helpers for validation,
event preparation, pattern matching, status construction, time-column
creation, and expanded status handling.
Replaced the verbose flag in augment()
and polish() with a verbosity argument. The
accepted levels are "quiet", "summary", and
"progress", with a global default available through
options(msmtools.verbosity = ...).
augment() and polish() now always
return data.table objects. The previous
convert argument has been removed; use
as.data.frame() on the result when a plain
data.frame is required.
data.table-only
return contract and added coverage for the new verbosity
argument.augment() and
polish() ahead of the planned internal refactor.Converted package documentation sources to roxygen2 markdown style.
Kept the vignette on the lightweight HTML vignette workflow while cleaning old LaTeX-style bibliography markup.
Refreshed the README and vignette around the current 2.x workflow and modern dependency baseline.
Replaced heavier multi-state model examples with guarded examples so CRAN checks do not execute model-fitting workflows.
Reworked the existing tests so expected warnings are asserted
inside test_that() blocks instead of being emitted during
test setup.
Added regression coverage for augment() across
two-state and three-state patterns, date, numeric, and difftime time
columns, supplied t_death, expanded statuses, conversion
behavior, and generated augmented time columns.
Added regression coverage for polish()
duplicate-removal and no-duplicate behavior.
Raised the supported baseline to R 4.1 and current CRAN releases of the main runtime dependencies used by msmtools.
Removed the unused development helper usethis
from Suggests.
testthat::expect_is() calls with
testthat::expect_s3_class() for compatibility with
testthat 3rd edition.This is a CRAN resubmission after msmtools was archived because compatibility issues with newer data.table releases were not corrected in time. No user-facing behaviour has changed.
Kept the compatibility fixes for current
data.table releases by avoiding deprecated
substitute() calls on the left-hand side of :=
assignments.
Retained the focused non-standard evaluation cleanup in
augment() and polish() needed for CRAN checks,
without introducing the broader refactor attempted on the historical
substitute_fix branch.
This is a maintenance release addressing compatibility issues that caused the package to be removed from CRAN. No user-facing behaviour has changed.
Removed all uses of substitute() on the left-hand
side of := in data.table operations inside
augment() and polish(). This pattern was
deprecated by data.table and produced errors on current
CRAN versions. Column assignment now uses the recommended
(var) := idiom.
Replaced every remaining eval(substitute(data$var))
and eval(substitute(class(data$var))) construct with direct
data[[var]] and class(data[[var]]) equivalents
across augment() and polish(). The previous
forms were fragile and harder to reason about.
Replaced class(...) == "type" comparisons with
inherits() throughout augment(), as required
by current R CMD CHECK.
@docType "package" /
NULL pattern in msmtools.R with the current
"_PACKAGE" sentinel required by roxygen2
>= 7.2.This is a maintenance update. There are no major updates worth noting apart from a few tweaks to the vignette, which was not rendered appropriately.
msmtools sees several updates which come with
potential breaking changes due to the dropping of several arguments in
some functions. The most relevant feature being shipped with v2.0.0 is
that both survplot() and prevplot() now
support ggplot2. All in all, this justifies the jump in
versions thus bringing msmtools to version 2.0.0.
survplot() requires much less arguments now but at the
same time is a bit less flexible. This is particularly reflected in plot
customization which is now “self-imposed”. I summarize what’s different
w.r.t. v1.3 below:
gg and ggplot object.survplot() returns nothing but the rendered plot
by default. The user can tell the function to return additional objects
like the fitted data, the Kaplan-Meier data
km, or one of them with the argument out.survplot() always returns
a data.table when out requires such
object.survplot() twice with different input parameters and
the combine the plots afterwards. The underlying data structures for the
plot are always returned and made available through a
gg/ggplot object.prevplot() has been greatly improved. There
are no more loops in the function and everything is done by reference so
it is very efficient. I briefly summarize what’s different w.r.t. v1.3
below:
prevplot() always returns a gg/ggplot
object.prevalence.msm().facet_wrap() to automatically decide how many grobs to
render. For now, there is no customization possible since I expect that
for most cases the number of states is limited in number anyway. There
might be some flexibility added in future releases.M = TRUE, prevplot() uses
patchwork to wrap the two plots in two different rows.
The first row has the standard prevalence plot, the second row has the
Deviance M.survplot() lets you specify the type of confidence
intervals for the Kaplan-Meier in addition to the already available
types for the fitted curve. The argument is ci_km.out which takes a vector of characters.survplot() always renders the plot and
returns it.prevplot() drops plot layering in favor of direct
ggplot2 support.prevplot() has become faster due to smarter data
extraction and binding.polish() is introduced. This adds
support in the preprocessing part of the analysis. polish()
addresses the specific problem of different transitions occurring at the
same exact time within a given subject. This is a case for which a
multi-state model fails to estimate the probability associated with the
two transitions. At the moment, the whole subject specified by
data_key is deleted.Global variables are now correctly declared on top of functions
using utils::globalVariables(). This prevents the
assignment to NULL in the preamble of functions which
decreases the elegance of the code.
The printing of information is now way more simpler and is not
based on sink() anymore. This has been done to be less
intrusive into the OS when redirecting on console messages. Also, no
more OS type check is done so that the control with argument
verbose is the most general possible. Warnings are still
controlled as usual, so that they get printed, if any, just after the
function call.
The vignette has been updated to include new features and it is now in HTML format which provides a faster and lighter access.
Improved the documentation’s readability in the ‘Value’ section
for augment() and survplot().
In the documentation of augment() now there is an
explicit example which returns a data.frame.
Windows builds of msmtools are now constantly checked through Appveyor.
The author/maintainer e-mail has changed to match his new affiliation and now is francesco.grossetti@unibocconi.it.
After augment() has been run, results are now
visible at the very first call. This means that you can finally print on
console the augmented dataset right away.
pandoc versions prior to 1.17 do not fully support
spaces in file names and caused a warning when compiling
msmtools under Fedora using both clang and
gcc. Now all file names are without spaces.
msmtools 1.3 has been built using pandoc
1.19.2 and pandoc-citeproc 0.10.4.1
msmtools can now run with R 3.0.0 and above for retro compatibility reasons.
augment() gains the new argument
check_NA which allows the user to decide if the function
should run some checks to find missing data in the following arguments:
data_key, n_events, pattern,
t_start and t_end. Default is
FALSE. Missing data checks are always carried out on
more_status.
augment() gains the new argument
convert which if set to TRUE efficiently
converts the output to the old school data.frame
class.
survplot() gains the new argument
return.all which saves you some typing time when requesting
both the data of the Kaplan-Meier and the fitted survival. Arguments
return.km and return.p now are set to
NULL by default instead of FALSE.
survplot() gains the new argument
convert which if set to TRUE efficiently
converts any object returned to the old school data.frame
class.
augment() now also accepts an object of class
data.frame as input. If so, the function internally
converts it to a data.table.
augment() now accepts t_augmented
without quotes too. Default name is still “augmented”.
augment() gets a whole new implementation which
comes into play when pattern has only 2 values (‘alive’ and
‘dead’). Now the procedure runs with computational time only slightly
longer than the standard 3 values in pattern. This is due
thanks to the fast joins method adopted.
augment() now is much faster when defining the
target size for the reshaping. This was a bottleneck which caused memory
issues and wasted time.
General memory optimization in the function
augment(). Now the function uses ~ 30% less
memory.
All the functions now have more detailed and better written helps.
Some minor changes in the vignette to encapsulate new functionalities.
In augment(), the sequential status is now correctly
computed. There was a wrong call which blocked the object defined by
n_events.
In augment(), when pattern was detected
with two unique values, inconsistent results were produced during the
status flag assignment. This was due to a wrong rounding of the amount
of augmenting factor for each unit.
augment() now is way faster then in v1.0 thanks to a
new implementation when defining patterns.
augment() now uses the faster uniqueN()
to extract the number of unique values in a vector.
augment() now correctly positions new created
variables.augment() in-line help now provides correct information
on what it returns.