Document attribute "ratio" returned by counting_process()

[jdblischak]

I updated the documentation for counting_process() to match its latest behavior. The returned attribute is now ratio.

xref: #276, #281

Idea for future improvement: It would be a good idea to also document the attribute ratio in the documentation for sim_pw_surv() too. The counting_process() code describes the simple ratio of event counts as the "empirical ratio", so I assume that sim_pw_surv() must be doing something different to calculate its ratio.

simtrial/R/counting_process.R

Lines 151 to 158 in 85cdc8f

	# if `x` is generated by sim_pw_surv
	if ("generate_by_simpwsurv" %in% names(attributes(x))) {
	ratio <- attributes(x)$ratio
	} else {
	# if not, calcualte the emperical ratio
	ratio <- sum(x$treatment == arm) / sum(x$treatment != arm)
	}
	attr(ans, "ratio") <- ratio

[LittleBeannie]

I updated the documentation for counting_process() to match its latest behavior. The returned attribute is now ratio.

xref: #276, #281

Idea for future improvement: It would be a good idea to also document the attribute ratio in the documentation for sim_pw_surv() too. The counting_process() code describes the simple ratio of event counts as the "empirical ratio", so I assume that sim_pw_surv() must be doing something different to calculate its ratio.

simtrial/R/counting_process.R

Lines 151 to 158 in 85cdc8f

	# if `x` is generated by sim_pw_surv
	if ("generate_by_simpwsurv" %in% names(attributes(x))) {
	ratio <- attributes(x)$ratio
	} else {
	# if not, calcualte the emperical ratio
	ratio <- sum(x$treatment == arm) / sum(x$treatment != arm)
	}
	attr(ans, "ratio") <- ratio

I wanted to clarify the two ways for utilizing counting_process:

1. The first method involves using sim_pw_surv(...) |> counting_process(...). In this case, the ratio for counting_process is derived from the block argument in sim_pw_surv. For example, if you set block = c("control", "control", "experimental", "experimental"), this indicates a ratio of 1.
2. The second method involves using x |> counting_process(...), where x is generated manually by the user. Here, the ratio is determined based on empirical data.

I hope this explanation is clear. I will proceed to merge the PR now.

[LittleBeannie]

Thank you, @jdblischak!

[jdblischak]

I hope this explanation is clear.

@LittleBeannie Yes! Very clear now. Thanks for the detailed explanation. Now I understand this line of code from the end of sim_pw_surv():

simtrial/R/sim_pw_surv.R

Line 195 in 289eb5d

attr(ans, "ratio") <- sum(block == "experimental") / sum(block == "control")

I'm planning to submit a documentation PR to explain the ratio attribute returned by sim_pw_surv()