hrossman/pymsm

Docs and onboarding material

CamDavidsonPilon opened this issue · 2 comments

CamDavidsonPilon commented

Some of these are easy tasks, some are just suggestions to provide better docs.

  1. The github action badges on the README.md point to the .svg image, but should point to the action (ex: https://github.com/hrossman/pymsm/actions/workflows/tests.yml instead of https://github.com/hrossman/pymsm/actions/workflows/tests.yml/badge.svg)
  2. Running the code here did give an error at the end (a lifelines convergence error - can these be caught and report back to the user something more useful?)
  3. In this intro, can you describe what a survival MSM is and why one might want to use it? How does it fit into the survival analysis toolkit?
  4. Maybe a quick explanation or interpretation of the plot on this page. How should I read it?
  5. In examining a model, what should I, the naive reader, be looking for? (BTW I like the color scheme you picked for the stackplot)
  6. The full examples are nice. I think you could add more context about what the dataset is describing, how you are modelling it / choices you make, and conclusions you (the experts) draw from it).
  7. Some broken latex on this page

Overall, I like your docs! I would like more emphasis on educating newbies. Y'all are experts, teach me!

hrossman commented

Hi @CamDavidsonPilon just to let you know, we (@ayya-keshet and I) still haven't finished dealing with all these issues but agree with them and will start fixing them and ping you once we're done. Thanks

hrossman commented
  1. Fixed.
  2. Code fixed.
  3. Added sections to the intro of background and motivation and extended capabilities.
  4. Updated a short explainer in the page.
  5. Updated the docs.
  6. Will try to improve.
  7. Page cut in favour of the JOSS paper which will contain that material and all the latex formulas. Will link to the paper directly fom the docs once it's out :)

Thanks for all these!