{smcl}
{* *! version 1.0.2 11 July 2019}{...}
{* *! version 1.0.1 2 April 2019}{...}
{title:Title}
{phang}
{bf:bcss} {hline 2} a command to create graphs to show how baseline data (prospective or retrospective) affect sample size for a cluster randomised trial.
{marker syntax}{...}
{title:Syntax}
{phang}
Prospective data collection:
{p 8 17 2}
{cmdab:bcss},
{opt pi:list(numlist)}
{opt r:ho(#)}
{opt pro:spective}
{opt t:otal(#)}
[{it:other_options}]
{phang}
Retrospective data collection:
{p 8 17 2}
{cmdab:bcss},
{opt pi:list(numlist)}
{opt r:ho(#)}
{opt ret:rospective}
{opt e:ndline(#)}
[{it:other_options}]
{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Main}
{synopt:{opt pi:list(numlist)}} specifies the ranges of pi (cluster autocorrelation): the correlation between the underlying cluster population means at baseline and endline.
{pstd}
{p_end}
{synopt:{opt r:ho(#)}} the intra-cluster correlation (ICC).
{pstd}
{p_end}
{synopt:{opt pro:spective}} specified when prospective baseline data collection is required.
{pstd}
{p_end}
{synopt:{opt t:otal(#)}} the cluster size (n_b+n_e) when prospective data collection is selected, where n_b is the number of baseline measurements and n_e is the number of endline measurements from each cluster.
{pstd}
{p_end}
{synopt:{opt ret:rospective}} specified when retrospective baseline data collection is required.
{pstd}
{p_end}
{synopt:{opt e:ndline(#)}} the cluster size (n_e) when retrospective data collection is selected (the baseline data of size n_b is already collected before the trial).
{syntab:Prospective options}
{pstd}
{p_end}
{synopt:{opt propx:axis(numlist min=2 max=2)}} the min and max ranges of the x axis for prospective baseline data graphs (proportions).
{pstd}
{p_end}
{synopt:{opt propy:axis(numlist min=2 max=2)}} the min and max ranges of the y axis for prospective baseline data graphs.
{pstd}
{p_end}
{synopt:{opt propys:tep(numlist max=1)}} the step on the y axis for prospective baseline data graphs.
{syntab:Retrospective options}
{pstd}
{p_end}
{synopt:{opt retx:axis(numlist min=2 max=2)}} the min and max ranges of the x axis for retrospective baseline data graphs (ratios).
{pstd}
{p_end}
{synopt:{opt rety:axis(numlist min=2 max=2)}} the min and max ranges of the y axis for retrospective baseline data graphs.
{pstd}
{p_end}
{synopt:{opt retys:tep(numlist max=1)}} the step on the y axis for retrospective baseline data graphs.
{syntab:General options}
{pstd}
{p_end}
{synopt:{opt leg:endoptions(string)}} user defined legend options, such as position and size.
{pstd}
{p_end}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
{marker description}{...}
{title:Description}
{pstd}
{pstd}
{cmd:bcss} displays graphs examining the impact of varying the amount of prospective/retrospective baseline data collection on the number of clusters required in a cluster randomised trial
with different cluster autocorrelation and intra-cluster correlation values.
See {help bcss##CopasHooper:Copas and Hooper} for details.
{pstd}
The user must specify either prospective (and total) or retrospective (and endline) in the syntax for prospective or retrospective baseline data collection respectively.
{pstd}
Prospective baseline data are measurements taken as part of the trial, retrospective baseline data are measurements already taken which are not included therefore in the sample size for the trial.
{pstd}
The x axes values on the prospective data graphs are proportions.
{pstd}
The x axes values on the retrospective data graphs are ratios.
{pstd}
The user can choose to change the graph axes, however if one axis range is specified then the corresponding axis must also be specified (e.g. if the user selects certain x axis values, then they must also select the corresponding y axis values).
Either all or none of the axis options must be specified.
{pstd}
The legend position and size can be changed by the user, using standard legend syntax within legendoptions().
{pstd}
Theta opt is the optimum proportion of baseline measurements to maximise power, shown on the prospective data graphs as θ_opt=(mρπ+ρ-1)/[ρm(1+π)] where m = "total cluster size" = n_b+n_e
{pstd}
Please note that it is not advisable to set pi or rho at the boundary values (e.g. 1) for these graphical representations.
{marker examples}{...}
{title:Examples}
{pstd}
{pstd}
bcss, pi(0.5 0.6 0.7) rho(0.01) pro total(200) propxaxis(0 0.5) propyaxis(1 1.25) propystep(0.05)
{pstd}
bcss, pi(0.5 0.6 0.7) rho(0.01) ret endline(200) retxaxis(0 2) retyaxis(0 1) retystep(0.1)
{pstd}
with user defined legend options:
{pstd}
bcss, pi(0.5 0.6 0.7) rho(0.01) pro total(200) propxaxis(0 0.5) propyaxis(1 1.25) propystep(0.05) leg(pos(5) size(small))
{title:References}
{pstd}
{pstd}{marker CopasHooper}
Copas AJ and Hooper R. Cluster randomised trials with different numbers of measurements at baseline and endline: Sample size and optimal allocation. Clinical Trials {browse "https://journals.sagepub.com/doi/full/10.1177/1740774519873888"}
{title:Author}
{pstd}
Ella Marley-Zagar, MRC Clinical Trials Unit, University College London.
Email {browse "mailto:e.marley-zagar@ucl.ac.uk":e.marley-zagar@ucl.ac.uk}
{title:Further note: installation from Github}
{pstd}
Please note the latest version of bcss can be found at {browse "https://github.com/UCL/bcss/"}
The bcss.ado file can be installed within Stata directly from github by typing:
net install github, from("https://haghish.github.io/github/")
github install UCL/bcss