Improve references to computer code, software, packages, functions, etc.
Questions and answers on CV.SE will often refer to computer code, software, packages, or individual functions. That might include full chunks of code for implementation of statistical methods discussed in the post, or it might include in-text references to packages and functions that are useful for the methods. Here are some tips for "best practice" with regard to improving these aspects of a post:
computer-code font for all references to code, software and packages: Full code chunks are automatically shown using
computer-code font but it is also desirable for in-text references to these things to appear in this font. (You should also make sure you use correct capitalisation of names of packages and functions in any software applications that are case-sensitive.) This assists the reader in seeing which aspects of the discussion pertain to software implementation, and it also ensures that references to packages and functions appear in a consistent font both in the body of the text and in any accompanying code chunks.
State what language you are using: This may seem an obvious point, but sometimes posters forget to specify the language they are using for their code (e.g.,
Stata, etc.). Many experienced coders will recognise the language, but not all users will. Best practice here is to explicitly state the coding language you are using.
Add relevant external links for packages and functions: When giving an in-text reference to a package for a piece of statistical software, it is desirable to give an external link to the relevant documentation for the package. When giving an in-text reference to a function, it is desirable to give an external link to the page showing the information for that function (e.g., function arguments, output, description, examples, etc.). You only need to do this once, so that the reader has a link to relevant documentation, so don't feel the need to link over and over again if you mention a package or function multiple times. Links may not be necessary for functions and packages that are in common use, but they are extremely helpful for obscure functions or packages. For packages in
R you can link to their page in CRAN and for functions in
R you can link to their information pages at rdrr.io or the UPenn R help pages. These sources give useful links for readers to help them understand the syntax used for a package or function.
Make sure your code runs and is replicable: When you give chunks of computer code you should check to make sure that your code runs on a newly loaded console, without any other preliminary commands that have not been included. You may assume that the user has the relevant software and has downloaded all required packages, but you need to remember to include commands to load relevant packages if you are using functions from them. If you are doing randomisation then you should also "set the seed" to ensure that any pseudo-random numbers generated in the code are replicable. If you include graphical output in your post then you should make sure that the graphical output you give is what is produced in your code. (There may be some cases where you give a graph without showing the code, in which case this does not apply.)
Use proper annotation in chunks of computer code: Even though questions and answers will usually have some accompanying text giving context to any relevant computer code, it is still good practice to ensure that chunks of code are annotated with labels that break up the parts into manageable chunks, and tell the reader what the parts of the code are doing. As a general rule, the code should not be out of place in an application where the user does not have access to the original question/answer.
Avoiding hard-coding specific parameter values in code: Many questions on CV.SE ask for the answer to a specific statistical question with a particular set of parameters. Notwithstanding this fact, the goal of answers is to be broadly applicable to variations of the question that might be of interest to other readers. This means that when giving computer code for answers, it is often useful to separate out the specific parameter values used for the particular question from the general form of the code to get the answer. Rather than "hard-coding" the parameter values, instead add a line of code defining each relevant parameter value and then reference these values in the code. This makes it easier for readers to substitute other parameter values if they want to apply your method to their own problem.
Use helpful names for things in code: Ideally, all variables and other objects in your code should have names that bear a close resemblance to their actual content, or to the notation usually used to represent them in statistical discussions. For small pieces of code it is usually possible to name your objects in a helpful way, but this may become cumbersome if you have a long piece of code with many intermediate objects, so some reasonable judgment is needed. In any case, consider naming your data as
DATA and your model as
MODEL and so on, to make it obvious to the reader what these objects are. In programs like
R that are case-sensitive, one useful thing you can do is to name your objects with upper-case and then have these roughly match up with argument inputs of functions which are written in lower-case (e.g., if you have a function that takes an input
slope then create a variable
SLOPE for its value and then input it to the function as
slope = SLOPE).
In the section below I show an example of a bad version of a question that uses poor practices for coding, and then an edited version that applies the above practices.
You can implement Kaplan-Meier using bootstrap methods with the bootkm function in hmisc, but you will need to set $q = 0.8$ because that is not the default. Here is how you do this with one-hundred bootstrap repetitions for a test of quantile difference for a variable for males and females:
S <- Surv(runif(400))
dd <- data.frame(var = S, type = c(rep('M', 200), rep('F', 200)))
ssm <- bootkm(a['type' == 'M'], b = 100, q = 0.8)
ssf <- bootkm(a['type' == 'F'], b = 100, q = 0.8)
You can implement Kaplan-Meier using bootstrap methods with the
bootkm function in the
Hmisc package in
R. The function takes an input
q for the quantile, so you will need to set this to your desired value. The function also takes an input
b for the number of bootstrap iterations (500 by default), but we will only use 100 iterations. Here is how you perform 100 bootstrap iterations for a test of quantile difference for the survival time for males and females in a mock set of data (where the true difference is zero):
#Load required libraries
#Create some mock survival data (using the survival package)
#Survival times for a sample of males (M) and females (F)
n <- 400
TIME <- Surv(runif(n))
DATA <- data.frame(Time = TIME, Sex = c(rep('M', 200), rep('F', 200)))
#Perform the bootstrap iterations (using the Hmisc package)
QUANTILE <- 0.8
ITERATIONS <- 100
BOOT.MALE <- bootkm(DATA[DATA$Sex == 'M', ], b = ITERATIONS, q = QUANTILE)
BOOT.FEMALE <- bootkm(DATA[DATA$Sex == 'F', ], b = ITERATIONS, q = QUANTILE)
#Describe the quantile difference