{smcl}
{* *! version 1.0.0 06may2019}{...}
{title:Title}

{p2colset 5 19 20 2}{...}
{p2col:{hi:cifunction} {hline 2}} Computes and graphically displays all possible confidence intervals around a point estimate {p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 14 2}
{cmd:cifunction}
{it: #b}
{cmd:,}
{opt se(#)}
[
{opt df(#)}
{opt eform}
{opt fig:ure}[{cmd:(}{it:{help twoway_options:twoway_options}}{cmd:)}]
{opt sav:ing}({it:{help filename:filename}, replace})
]

{pstd}
{it:#b} can be specified as a coefficient or exponentiated value (e.g. OR, HR, IRR)


{synoptset 26 tabbed}{...}
{synopthdr}
{synoptline}
{p2coldent:* {opt se(#)}}specify the standard error of the estimate {p_end}
{synopt:{opt df(#)}}specify the degrees of freedom if {it:#b} is t-distributed (e.g. when using {helpb regress} to produce estimates){p_end}
{synopt:{opt eform}}indicate that the coefficient is exponentiated (e.g. OR, RR, IRR) {p_end}
{synopt:{opt fig:ure}[{cmd:(}{it:{help twoway_options:twoway_options}}{cmd:)}]}produces a {it:confidence interval function} plot. Specifying {cmd:figure} 
without options (or not specifying {cmd:figure} at all) uses the default graph settings {p_end}
{synopt :{help prefix_saving_option:{bf:{ul:sav}ing(}{it:filename}{bf:, replace)}}}save results to {it:filename}. The suboption "replace" is allowed{p_end}
{synoptline}
{p 4 6 2}* se() must be specified.{p_end}



{title:Description}

{pstd}
{opt cifunction} computes and plots the {it: confidence interval function} (Sullivan and Foster 1990) which is also referred to as the 
{it:confidence curve} (Birnbaum 1961), {it:P-value function} (Poole 1987; Miettinen 1985; Rothman et al. 2008), and {it: consonance interval} (Folks 1981). 
A CI-function is a graphical display of all possible CIs around a specified point estimate. The peak of the curve indicates the point estimate, and the 
concentration of the curve around the point estimate indicates the precision of the estimate. A narrow CI-function would result from a large study with 
high precision, and a broad CI-function would result from a small study that had low precision. CI functions convey much more of 
the essential information by indicating the range of values that are reasonably compatible with the observations, assuming the statistical model is correct. 
They can also show that the data do not contain the information necessary for reassurance about an absence of effect (Rothman et al. 2008). 

{pstd}
{opt cifunction} is an immediate command, see {helpb immed}.



{title:Options}

{p 4 8 2}
{cmd:se(}{it:#}{cmd:)} specifies the standard error of the estimate. {cmd:se()} is required.

{p 4 8 2}
{cmd:df(}{it:#}{cmd:)} specifies the degrees of freedom if {it:#b} is t-distributed (e.g. when using {helpb regress} to compute estimates). 

{p 4 8 2}
{cmd:eform} specifies that the coefficient is exponentiated (e.g. OR, RR, IRR) {p_end}

{p 4 8 2}
{cmd:figure}[{cmd:(}{it:{help twoway_options:twoway_options}}{cmd:)}] produces
a range plot, shading the area between the upper and lower CI limits. Specifying {cmd:figure} without options (or simply not specifying {cmd:figure}) uses the
default graph settings.

{p 4 8 2}
{cmd:{help prefix_saving_option:{bf:{ul:sav}ing(}{it:filename}{bf:, replace)}}} specifies the filename where all the variables generated by {cmd:cifunction} will be saved. {cmd:replace}, used with 
{cmd:saving}, specifies that {it:{help filename}} can be replaced if it already exists.



{title:Examples from Sullivan and Foster (1990)}

{pmore}Reproduce Figure 1.{p_end}

{pmore} First we use {helpb getregstats} (downloadable from SSC) to get the standard error for a risk ratio of 2.0 with p-value of 0.05.{p_end}
{pmore2}{bf:{stata "getregstats 2.0, p(0.05) mod(rr)": . getregstats 2.0, p(0.05) mod(rr)}} {p_end}

{pmore}We then use {cmd: cifunction} specifying the point estimate and std. error. We modify the {cmd:figure} to improve the presentation.{p_end}
{pmore2}{bf:{stata "cifunction 2.0, se(.707306) eform fig(xscale(log) xlab(0.5 1 2 5 10) xtitle(Risk Ratio (Log Scale))) " : . cifunction 2.0, se(.707306) eform fig(xscale(log) xlab(0.5 1 2 5 10) xtitle("Risk Ratio (Log Scale)"))}} {p_end}


{pmore}Reproduce Figure 2.{p_end}

{pmore}Set-up{p_end}
{pmore2}{bf:{stata "webuse dollhill3, clear": . webuse dollhill3, clear}} {p_end}
{pmore2}{bf:{stata "poisson deaths smokes if agecat==1, exposure(pyears) irr": . poisson deaths smokes if agecat==1, exposure(pyears) irr}} {p_end}
{pmore2}{bf:{stata "poisson deaths smokes if agecat==2, exposure(pyears) irr": . poisson deaths smokes if agecat==2, exposure(pyears) irr}} {p_end}
{pmore2}{bf:{stata "poisson deaths smokes if agecat==3, exposure(pyears) irr": . poisson deaths smokes if agecat==3, exposure(pyears) irr}} {p_end}
{pmore2}{bf:{stata "poisson deaths smokes if agecat==4, exposure(pyears) irr": . poisson deaths smokes if agecat==4, exposure(pyears) irr}} {p_end}

{pmore} We plug in these coefficients and std. errors into {cmd: cifunction} and further modify the {cmd:figure}. {p_end}
{p 8 17 2}{cmd:. cifunction 5.736638 2.138812 1.46824 1.35606, se(4.181258 .6520701 .295728 .2748845) eform ///} {break}
				{cmd: fig(xscale(log) xlabel(.3 .5 1 2 5 10 20 50 100) legend(label(1 "35-44") label(2 "45-54") label(3 "55-64") label(4 "65-74") ///} {break}
				{cmd: title("Age Group", size(small))) xtitle("Rate Ratio (Log Scale)")))}{p_end}
{pmore2}({stata "cifunction_ex 1":click to run}){p_end}


{pmore}Reproduce Figure 3.{p_end}

{pmore}Set-up, using {helpb cci} on data from Mann et al (1976), then run {helpb getregstats} to get std errors.{p_end}
{pmore2}{bf:{stata "cci 10 36 5 40, woolf": . cci 10 36 5 40, woolf}} {p_end}
{pmore2}{bf:{stata "cci 18 78 7 86, woolf": . cci 18 78 7 86, woolf}} {p_end}
{pmore2}{bf:{stata "getregstats 2.835165, ucl(7.151794) mod(or)": . getregstats 2.835165, ucl(7.151794) mod(or)}} {p_end}
{pmore2}{bf:{stata "getregstats 2.222222, ucl(7.118025) mod(or)": . getregstats 2.222222, ucl(7.118025) mod(or)}} {p_end}

{pmore}We then run {cmd: cifunction} using both estimates for crude and pooled.{p_end}
{p 8 17 2}{cmd: . cifunction 2.222222  2.835165, se(1.319891 1.33843) eform ///} {break}
				{cmd: fig(xscale(log) xlabel(.2 .5 1 2 5 10 20) ///} {break}
				{cmd: legend(label(1 Crude) label(2 Pooled)) xtitle("Odds Ratio (Log Scale)")))}{p_end}
{pmore2}({stata "cifunction_ex 2":click to run}){p_end}


{pmore}Reproduce Figure 4.{p_end}

{pmore}Set-up, using {helpb getregstats} on data from from Table 5 (for Finland, New Orleans/Los Angeles, Denmark, and Upstate New York) in Gufferman et al (1984) to get std errors.{p_end}
{pmore2}{bf:{stata "getregstats 0.7, l(.2) mod(rr)": . getregstats 0.7, l(.2) mod(rr)}} {p_end}
{pmore2}{bf:{stata "getregstats 1.2, l(.8) mod(rr)": . getregstats 1.2, l(.8) mod(rr)}} {p_end}
{pmore2}{bf:{stata "getregstats 1.3, l(.5) mod(rr)": . getregstats 1.3, l(.5) mod(rr)}} {p_end}
{pmore2}{bf:{stata "getregstats 3.6, l(1.3) mod(rr)": . getregstats 3.6, l(1.3) mod(rr)}} {p_end}

{pmore}We then run {cmd: cifunction} using all estimates.{p_end}
{p 8 17 2}{cmd: cifunction .7 1.2 1.3 3.6, se(.4474236 .2482485 .6337692 1.870876) eform ///} {break}
				{cmd: fig(xscale(log) xlabel(.05 .1 .2 .5 1 2 5 10 30) ///} {break}
				{cmd: legend(label(1 "Finland") label(2 "NO/LA") label(3 "Denmark") ///} {break}
				{cmd: label(4 "Upstate NY")) xtitle("Relative Ratio (Log Scale)")))} {p_end}
{pmore2}({stata "cifunction_ex 3":click to run}){p_end}


{title:Example Figure 10.5 from Rothman et al (2008)}

{pmore}Using {helpb getregstats} to get std errors and produce Figure 10.5. Here we use the saving option as well.{p_end}
{pmore2}{bf:{stata "getregstats 0.88, l(0.76) model(or)": . getregstats 0.87, l(0.70) model(or)}} {p_end}
{pmore2}{bf:{stata "getregstats 0.87, l(0.70) model(or)": . getregstats 0.87, l(0.70) model(or)}} {p_end}

{p 8 17 2}{cmd: cifunction 0.87 0.88, se(.0965065 .0658232) eform fig( xlab(.5(.1)1.3) xtitle("Odds Ratio") ///} {break}
				{cmd: legend(label(1 "Eisenberger et al (1998)") ///} {break}
				{cmd: label(2 "Summary of 10 studies") ring(0) position(11))) sav(figdata, replace)} {p_end}
{pmore2}({stata "cifunction_ex 4":click to run}){p_end}



{title:Output table}

{pstd}
{cmd:cifunction} produces and stores several variables when the {cmd: saving()} option is specified.
Below is a list of each variable in the saved file. Variables ending with an integer indicate 
which estimates they belong to. When only one set of estimates is provided (i.e. point estimate and std. error),
the variables will be followed by 1.

{synoptset 16}{...}
{synopt:Variable}Description{p_end}
{synoptline}
{synopt:{cmd:cilev}}sequencing range of CIs (from 0 to 99.99) {p_end}
{synopt:{cmd:plev}}sequencing range of P-values (from 0.0001 to 1.0) {p_end}
{synopt:{cmd:sval}}S-values computed for respective {it: plev} values (see Greenland [2019]) {p_end}
{synopt:{cmd:lcl(#)}}computed lower confidence limits{p_end}
{synopt:{cmd:ucl(#)}}computed upper confidence limits{p_end}
{synoptline}
{p2colreset}{...}




{title:Acknowledgments}

{p 4 4 2}
I thank John Moran for advocating that I write this package as well as providing suggestions for improvement. 



{title:References}

{phang}
Birnbaum, A. 1961. Confidence curves: An omnibus technique for estimation and testing statistical hypotheses. 
{it:Journal of the American Statistical Association} 56: 246-249.

{phang}
Folks, J. F. 1981. {it:Ideas of Statistics}. 
New York: John Wiley & Sons.

{phang}
Greenland, S. 2019. Valid P-Values Behave Exactly as They Should:
Some Misleading Criticisms of P-Values and Their Resolution With S-Values.
{it: The American Statistician} 73(sup1): 106-114.

{phang}
Gufferman, S., and E. Delzell. 1984. Epidemiology of Hodgkin's disease. 
{it: Epidemiology Review} 6: 76-106.

{phang}
Mann, J. I., Inman, W. H. W., and M. Thorogood. 1968. Oral contraceptive use in older women and fatal myocardial infarction. 
{it:British Medical Journal} 2: 193-199.

{phang}
Miettinen, O. S. 1985. {it:Theoretical Epidemiology: Principles of Occurrence Research in Medicine}. 
New York: John Wiley & Sons.

{phang}
Poole, C. 1987. Beyond the confidence interval. 
{it: American Journal of Public Health} 77: 195-199.

{phang}
Rothman, K. J., Greenland, S. and T. L. Lash. 2008. {it:Modern epidemiology (Vol. 3)}. 
Philadelphia: Wolters Kluwer Health/Lippincott Williams & Wilkins.

{phang}
Sullivan, K.M. and D. A. Foster. 1990. Use of the confidence interval function. 
{it:Epidemiology} 1: 39-42.



{marker citation}{title:Citation of {cmd:cifunction}}

{p 4 8 2}{cmd:cifunction} is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such: {p_end}

{p 4 8 2}
Linden A. (2019). CIFUNCTION: Stata module for computing and graphically displaying all possible confidence intervals around a point estimate.
Statistical Software Components, Boston College Department of Economics.



{title:Author}

{p 4 4 2}
Ariel Linden{break}
President, Linden Consulting Group, LLC{break}
alinden@lindenconsulting.org{break}



{title:Also see}

{p 4 8 2} Online: {helpb getregstats} (if installed), {helpb niceloglabels} (if installed){p_end}