[Rd] survival changes

[Joshua Ulrich]

On Sat, Jun 1, 2019 at 5: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.
>
I encountered several issues like this while making a change to xts. I
encountered several buggy and inconsistent behaviors while moving
attributes from the xts object to the xts object's index attribute.  I
don't want to "fix" some of these in the next version, because
downstream packages may rely on the old behavior.

Though it's specific to Python, "API Evolution the Right Way" has many
good strategies.
https://emptysqua.re/blog/api-evolution-the-right-way/

The "Deleting Features" and "Changing Behavior" sections are most
relevant to your situation.

> 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.
>
This seems reasonable. It would also give you opportunity to warn
users if functions that expect a new object receive an old object.
That would help them convert any of their functions that rely on the
old structure/behavior.

You could also add a global option to enable warnings with the default
set to FALSE for the first release.  Let users know they can set that
option to TRUE to identify places where they may need to modify their
use cases.

> 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.
>
Rather than an entirely new class, I wonder if you could instead make
the new class a subclass.  I'm not sure whether this has advantages
over adding an element, but it's another possibility.

> 3. Something I haven't thought of.
>
I don't have any other ideas, but I would be happy to discuss offline
if that would be helpful.

> Number 2 has a cleanness about it, but there is a long term nuisance about it wrt
> documentation.  Users, not unreasonably, expect the survfit function to produce a survfit
> object, and that is what they look for in the help pages.
>
> I plan to have 3.0-x on github before userR so that users can begin to play with it (and
> to get feeback before pushing to CRAN), so need to make a decision.
>
> Terry T.
>
>
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



-- 
Joshua Ulrich  |  about.me/joshuaulrich
FOSS Trading  |  www.fosstrading.com
R/Finance 2019 | www.rinfinance.com