Documentation and package name

[BKievit1]

Thank you for all the work you’ve done to create this package. My colleague (@nialldavison) and I have explored psm3mkv in more detail (version 0.2.0.9000) and have identified two more issues worth mentioning. The first is outlined below and is related broadly with documentation.

In some cases, documentation of functions was brief, which led to delays in understanding their purpose and/or function. Examples of this include (but are not limited to):

• create_dummydata, create_dummmydata_flexbosms, create_dummydata_survcan: Consider describing each column in the tibble output and how these differ to the columns in the original datasets.
• vlookup, vonelookup: Documentation headers are incomplete (they are currently “VLOOKUP function” and “VoneLOOKUP function” respectively) and it isn’t clear how these functions differ, without delving deeper into the underlying code.
• create_extrafields: The documentation should describe which additional fields are created. Additionally, describe the requirements for the ds dataset input.
• calc_haz_psm, calc_surv_psmpps: In the example vignette, goodness of fit statistics are outputted for psm_simple and psm_complex methods, but it’s not clear how these approaches differ in the documentation.

In other cases, documentation incorrectly describes the function:

• calc_likes: The output section does not describe what is currently created by the function.
• graph_survs: The output section says there are four datasets/graphics but there are actually five. Additionally, it may be worth describing what each of these datasets/graphics are.

Lastly, we suggest that the package name, psm3mkv, be re-considered. The current name may be difficult to understand or remember, which may impact it’s future uptake. A couple of alternative options could be compare3state or efficienCE, either may address these concerns.

[dom-muston]

Thank you very much for reviewing the code and the helpful suggestions on naming and improving the documentation

[dom-muston]

I've just made some commits in the prepcran branch for the following:

create_dummydata, create_dummydata_flexbosms, create_dummydata_survcan: Only create_dummydata is now externalized. Label attributes are added to the datasets. However, a user particularly interested in how these illustrative datasets were created would be more effectively directed to the code.

vlookup, vonelookup: The documentation for vlookup is extended; vonelookup is no longer externalized.

create_extrafields: Documentation extended.

Goodness of fit for psm_simple and psm_complex: The difference between these methods is explained further in the accompanying paper and in the mortality vignette.

calc_likes: I substantially revised the format of the tables in the outputted list, and revised the documentation accordingly.

[dom-muston]

I've also reviewed and updated the graph_survs documentation. Sorry you don't like the package name! :) Thanks again for taking the time to review and raise this Issue.