[Rd] survival changes

[Peter Langfelder]

On Sat, Jun 1, 2019 at 3:22 AM Therneau, Terry M., Ph.D. via R-devel
<r-devel using r-project.org> wrote:
>
> In the next version of the survival package I intend to make a non-upwardly compatable
> change to the survfit object.  With over 600 dependent packages this is not something to
> take lightly, and I am currently undecided about the best way to go about it.  I'm looking
> for advice.
>
> The change: 20+ years ago I had decided not to include the initial x=0,y=1 data point in
> the survfit object itself.  It was not formally an estimand and the plot/points/lines etc
> routines could add this on themselves.  That turns out to have been a mistake, and has led
> to a steady proliferation of extra bits as I realized that the time axis doesn't always
> start at 0, and later (with multi state) that y does not always start at 1 (though the
> states sum to 1), and later the the error doesn't always start at 0, and another
> realization with cumulative hazard, and ...
> The new survfit method for multi-state coxph models was going to add yet another special
> case.  Basically every component is turning into a duplicate of "row 1" vs "all the
> others".  (And inconsistently named.)
>
> Three possible solutions
> 1. Current working draft of survival_3.0.3:  Add a 'version' element to the survfit object
> and a 'survfit2.3' function that converts old to new.  All my downstream functions (print,
> plot,...) start with an "if (old) update to new" line.  This has allowed me to stage
> updates to the functions that create survfit objects -- I expect it to happen slowly.
> There will also be a survfit3.2 function to go backwards. Both the forward and backwards
> functions leave objects alone if they are currently in the desired format.
>
> 2. Make a new class "survfit3" and the necessary 'as' functions. The package would contain
> plot.survfit and plot.survfit3 methods, the former a two line "convert and call the
> second" function.
>
> 3. Something I haven't thought of.

A more "clean break" solution would be to start a whole new package
(call it survival2) that would make these changes, and deprecate the
current survival. You could add warnings about deprecation and urging
users to switch in existing survival functions. You could continue
bugfixes for survival but only add new features to survival2. The new
survival2 and the current survival could live side by side on CRAN for
quite some time, giving maintainers of dependent packages (and just
plain users) enough time to switch. This could allow you to
change/clean up other parts of the package that you could perhaps also
use a rethink/rewrite, without too much concern for backward
compatibility.

Peter