{smcl}
{* *! version 1.0 23 Aug 2020}{...}
{vieweralsosee "" "--"}{...}
{vieweralsosee "Install command2" "ssc install command2"}{...}
{vieweralsosee "Help command2 (if installed)" "help command2"}{...}
{viewerjumpto "Syntax" "rcspc##syntax"}{...}
{viewerjumpto "Description" "rcspc##description"}{...}
{viewerjumpto "Examples" "rcspc##examples"}{...}
{viewerjumpto "Author" "rcspc##author"}{...}

{title:Title}
{phang}
{bf:rcspc} - Restricted cubic spline contrasts - Prefix command estimating effect 
measure values (contrasts) from a reference value and their confidence 
interval for a set of effect modifier values.

{marker syntax}{...}
{title:Syntax}

{p 8 20}
{cmdab:rcspc, }{it:mandatory_options}
[{it:optional_options twoway_options}]{cmd::} regression command

{synoptset 50 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Mandatory}

{synopt:{opt at(numlist min=1  sort)}} A numlist of length greater than 1. 
The values of the continuous effect at which to estimate the effect measure.{p_end}

{synopt:{opt ref:erence(numlist max=1)}}The reference value to contrast from.{p_end}

{syntab:Optional}
{synopt:{opt pc:tknots(numlist min=3  max=10  >0  <100  sort)}} A numlist of 
values between 0 and 100. 
The length of the numlist must be between 3 and 10. 
They specify the percentages of the percentiles that are used for calculating 
the restricted cubic splines.{p_end}

{synopt:{opt nk:nots(#)}} Integer value between 3 and 7 specifying recommended 
standard set of percentages, described in [opt nknots} in 
{mansection R mksplineMethodsandformulas: {cmd:mkspline}, Methods and formulas}. 
Default value is 4. If option {opt p:ctknots} is set, option {opt n:knots} is 
ignored.{p_end}

{synopt:{opt k:eepcubicsplines}}Keep the generated cubic spline regressors for 
detailed analysis.{p_end}

{synopt:{opt inc:ludereference}} Include reference value in points and graph.
To when the reference value is outside the interval of the continuous effect 
variable.
{p_end}

{synopt:{opt e:form}} Exponentiate the estimated effect measures.{p_end}

{synopt:{opt rcspcnames(namelist min=4  max=4)}} Rename the generated variables 
with the requested values of the continuous effect variable, 
the estimated effect measures
and the 95% CI for the estimated effect measure. Must have length 4.
Default names are "__second_variable_name", "__second_variable_name_contrast",
"__second_variable_name_lb" and "__second_variable_name_ub"{p_end}

{synopt:{opt ci:limits(numlist max=1  >50  <100)}}A numlist of length 1. 
A real between 0 and 100. 
Option to change the percentage for the confidence intervals from the
default 95 (%).{p_end}

{synopt:{opt gr:aph}} Generate a default graph.{p_end}

{synopt:{opt twoway_options:}} Generate a default graph with the twoway options.
Option {opt gr:aph} is not necessary in this case.{p_end}

{synoptline}
{p2colreset}{...}
{p 4 6 2}

{marker description}{...}
{title:Description}
{pstd}

{pstd}
The prefix command {cmd:rcspc} takes a regression command as an argument. 
From the regression command argument {cmd:rcspc} uses the first variable as an 
outcome variable, the second as continuous effect variable transformed into a 
function using cubic splines.

{pstd}
For each value in the numlist specified in the {opt at:} option, the estimated 
contrast from the specified reference value and the confidence interval 
limits (normal approximation) are saved in four variables. 
For reproducibility, detailed results are stored in the returned values.

{pstd}
A simple default graph of the estimates and the 95% confidence interval 
are generated by the option {opt gr:aph}. 
It is deliberately simple but easily modifiable by any {cmd:twoway} option.
if any {cmd:twoway} option is set the the option {opt gr:aph} is not necessary.

{pstd}
The calculations in prefix command {cmd:rcspc} are based on returned matrices e(b) 
and e(V) and are therefore independent of the type of regression performed. 
Interesting contrasts (directly or exponentiated) that may be studied with this 
approach include:

{pstd}
* difference in means using -regress- or -mixed-{break}
* odds ratios using -logit- or -logistic-{break}
* odds ratios in a matched study using -clogit-{break}
* risk differences using -binreg-{break}
* relative risks using -binreg-{break}
* hazard ratios using -stcox-{break}
* incidence rate ratios using -poisson- or -nbreg-{break}

{pstd}
Contrasts in -glm- are also possible to analyse.

{pstd}
The author developed this command to estimate and visualise effect modification 
on a contrast or the log of the contrast.
However, the command can also be used to visualise gap developments by a 
continuous variable e.g. visualising the income gap over time between the 
two genders.

{marker examples}{...}
{title:Examples}

{pstd}Data are described in {browse "http://biostat.mc.vanderbilt.edu/dupontwd/wddtext":Statistical Modeling for Biomedical Researchers}.{p_end}
{phang}The book is a very good reference.{p_end}

{pstd}{bf:Click once on the commands (blue text) below to perform these in Stata.}{p_end}
{phang}Retrieve data{p_end}
{phang}. {stata `"use "http://biostat.mc.vanderbilt.edu/dupontwd/wddtext/data/1.4.11.Sepsis.dta", clear"'}{p_end}

{phang}Use the {cmd:rcspc} prefix command to estimate the risk differences for 
apache scores 0(5)40 from reference value 0 and generate the default graph 
named contrast{p_end}
{phang}. {stata `"rcspc, at(0(2)40) reference(0) name(contrast, replace) ytitle("Mortality risk difference, reference 0"): binreg fate apache, rd"'}{p_end}

{marker results}{...}
{title:Stored results}

{pstd}
{cmd:rcspc} stores the following in {cmd:r()}:

{synoptset 20 tabbed}{...}
{p2col 4 20 19 2: Macros}{p_end}
{synopt:{cmd:r(graph_cmd)}}The {help twoway:twoway} graph command generating the graph.{p_end}
{synopt:{cmd:r(rcspcnames)}}The names of the variables generated.{p_end}
{synopt:{cmd:r(command)}}The regression command generating the estimates.{p_end}

{p2col 4 20 19 2: Matrices}{p_end}
{synopt:{cmd:r(predictions)}}Predicted unexposed, predicted exposed and 
predicted contrast as well as their confidence intervals.{p_end}
{synopt:{cmd:r(regressors)}}Regressors used for the predictions.{p_end}
{synopt:{cmd:r(knots)}}The knots used for the unexposed and exposed parts 
of the second risk factor.{p_end}

{marker author}{...}
{title:Authors and support}

{phang}{bf:Author:}{break}
 	Niels Henrik Bruun, {break}
	Aalborg University Hospital
{p_end}
{phang}{bf:Support:} {break}
	{browse "mailto:niels.henrik.bruun@gmail.com":niels.henrik.bruun@gmail.com}
{p_end}