help for bmjcip(Roger Newson)

Format confidence intervals and P-values for medical journals

bmjcip varlist [if] [in]
[ , cformat(%fmt) pformat(%fmt)
xmlsub esub(esubstitution_rule) elzero
starvar(varname)
prefix(string) suffix(string)
pprefix(string) psuffix(string)
refexp(exp) reflabel(string)
headline(characteristic_name [, headline_suboptions]) ]

where varlist is a list of 1 to 5 numeric variable names, of the form

pvarname

or

estvarname pvarname

or

estvarname ciminvarname cimaxvarname

or

estvarname ciminvarname cimaxvarname pvarname

or

estvarname ciminvarname cimaxvarname pvarname qvarname

and estvarname ciminvarname cimaxvarname, pvarname and qvarname
are the names of the estimate, lower confidence bound, upper confidence bound, P-value and Q-value variables,
and %fmt is a numeric display format,
and characteristic_name is the name of a variable characteristic,
and esubstitution_rule is any one of

none | x10 | rtfsuper | texsuper | htmlsuper | smclsuper | mdsuper

and headline_suboptions can be any subset of the headline suboptions

estimate(string) lower(string) upper(string) pvalue(string) qvalue(string)

Description

bmjcip reformats a list of numeric variables,
containing estimates and/or confidence limits, P-values and/or Q-values,
to string variables, containing the same values formatted for presentation in medical journals.
The new string variables replace the old numeric variables,
and have the same names, variable labels, variable characteristics, and positions in the dataset.
bmjcip is usually used in output datasets (or resultssets) produced by the parmest package,
and the reformatted string variables are usually later output using the listtab package,
for input to Microsoft Word or other word processors.
It requires the sdecode package in order to work.
The sdecode, parmest and listtab packages can all be downloaded from SSC.

Options for bmjcip

cformat(%fmt) specifies a display format,
used for the estimates and confidence limits.
The estimates and confidence limits may then be reformatted using a separate rule,
specified by the esub() option.
However, bmjcip also adds parentheses and commas to the confidence limits,
as expected by medical journals.

pformat(%fmt) specifies a display format,
used for the P-value and Q-value.
If absent, then pformat(%-10.2g) is the default.
The P-value and Q-value may then be reformatted using a separate rule,
specified by the esub() option.
(See Remarks below.)

xmlsub specifies that, in the decoded string output variables,
the substrings "&", "<" and ">" will be replaced throughout with the XML entity references
"&amp;", "&lt;" and "&gt;", respectively.
This is useful if the decoded string output variables are intended for output
to a table in a document in XHTML, or in other XML-based languages.
This substitution, if specified, is performed before any substitution specified by the esub() option.

esub(esubstitution_rule) specifies a rule for substitution of the strings "e-" and "e+"
in decoded estimates, confidence limits, P-values and Q-values.
These strings indicate a following exponent (conventionally presented in documents as a superscript),
and are especially important for very small P-values and Q-values.
The esubstitution_rule may be
none, x10 (the default), rtfsuper, texsuper, htmlsuper, smclsuper, or mdsuper.
The substitution rules are the same as the ones documented in the help for
the esub() option of sdecode.
The x10 substitution rule is intended for users
who intend to cut and paste the decoded confidence intervals and P-values manually into a word processor document,
and then intend to convert superscripts manually to a superscript font in the document.
The rtfsuper substitution rule is intended for users who intend to generate a Rich Text Format (RTF) document,
and to output the decoded confidence intervals and P-values to that document.
The texsuper substitution rule is intended for users
who intend to output the decoded confidence intervals, P-values and Q-values to a TeX document.
The htmlsuper substitution rule is intended for users
who intend to output the decoded confidence intervals, P-values and Q-values to a HTML document.
The smclsuper substitution rule is intended for users
who intend to output the decoded confidence intervals, P-values and Q-values to Stata graphics text,
which is a branch of the Stata Markup and Control Language (SMCL).
The mdsuper substitution rule is intended for users
who intend to output the decoded confidence intervals, P-values and Q-values to a Markdown document.

elzero specifies that leading zeros in exponents in decoded estimates, confidence limits and P-values will not be removed.
If elzero is not specified, then these leading zeros are removed.

starvar(varname) specifies a string variable,
whose value will be appended to the decoded Q-value variable (if one exists),
or otherwise to the decoded P-value variable (if one exists),
or otherwise to the decoded upper confidence limit variable.
Usually, the starvar() variable contains stars or other footnote specifiers.

prefix(string) specifies a prefix, to be added to the left of the decoded string values.

suffix(string) specifies a suffix, to be added to the right of the decoded string values.

pprefix(string) specifies a special prefix,
to be added to the left of the decoded string values of the P-value and Q-value variables.
If unset, pprefix() is set to prefix().

psuffix(string) specifies a suffix,
to be added to the right of the decoded string values of the P-value and Q-value variables.
If unset, psuffix() is set to suffix().

refexp(exp) specifies an expression,
which, when evaluated, should be 1 for observations corresponding to reference parameters,
and 0 for other observations.
In observations where the refexp() expression is true,
bmjcip will assign a value of the reflabel() string to the decoded P-value variable
(if the varlist has 1 or 2 variables),
or to the decoded lower confidence limit variable (if the varlist has 3, 4 or 5 variables).
If the varlist has 3, 4 or 5 variables,
then, in reference observations, the decoded lower confidence limit variable will be replaced with an empty string ("").
If the varlist has 4 or 5 variables,
then, in reference observations, the decoded P-value will be replaced with an empty string.
If the dataset in memory is an output dataset produced by the parmest package,
and the user has specified the omit option for parmest,
then the user may specify the option reflabel(omit),
and the reference observations will then be those for which the variable omit is equal to 1,
implying that the corresponding parameter is omitted.

reflabel(string) specifies a label for reference observations,
defined using the reflabel() expression.
If refexp() has been specified, and reflabel() has not,
then reflabel() defaults to "(ref)".
If refexp() is not specified,
then reflabel() is ignored.

headline(characteristic_name [, headline_suboptions])
specifies the name of a variable characteristic to be set by bmjcip
for each of the variables to be reformatted.
This characteristic will contain, for each variable, a headline string, which might be used when listing the variables.
For instance, if the characteristic_name is varname,
then bmjcip sets the characteristic var[varname] for each of the variables reformatted.
If the user then lists the variables using the list command with the subvarname option,
then the variables are listed using the characteristic var[varname]
in the headline row above each variable,
instead of the variable name.
The character value set by headline() for each of the reformatted variables has a default,
which is typically "Estimate", "(95%", "CI)", "P" and "Q"
for the variables
estvarname, ciminvarname, cimaxvarname, pvarname and qvarname, respectively.
However, the user can reset the headline strings,
using the headline_suboptions.

Suboptions for the headline() option of bmjcip

estimate(string) specifies a headline string for the variable estvarname,
containing the estimates.
In default, it is set to estimate("Estimate").
The user may prefer to specify estimate("OR") if the estimates are odds ratios,
or estimate("GM") if the estimates are geometric means.

lower(string) specifies the headline string for the variable ciminvarname,
containing the lower confidence limits.
In default, it is set to lower("(level%"), where level is a numeric percentage confidence level.
The value of level is taken from the variable characteristic ciminvarname[level],
if that characteristic has a numeric value,
and is otherwise taken from the system setting c(level), set by set level.
For instance, if level is 95,
then the lower() option defaults to lower("(95%").
If ciminvarname was created as a lower confidence limit by any module of the parmest package,
then the variable characteristic ciminvarname[level]
will normally be set correctly.
However, in the general case, it is the responsibility of the user to ensure that this confidence level is the correct confidence level
used for calculating the variables ciminvarname and cimaxvarname.

upper(string) specifies the headline string for the variable cimaxvarname,
containing the upper confidence limits.
The default is upper("CI)").

pvalue(string) specifies the headline string for the variable pvarname,
containing the P-values.
The default is pvalue("P").

qvalue(string) specifies the headline string for the variable qvarname,
containing the Q-values.
The default is pvalue("Q").

Remarks

Guidelines for presentation of confidence intervals in medical journals are given in Altman et al. (2000).
The name bmjcip was chosen because these guidelines were written originally
for the British Medical Journal (BMJ) group of journals.

A Q-value is a P-value adjusted for multiple comparisons.
In Stata, they may be generated using the qqvalue package,
downloadable from SSC.

The presentation of P-values (including Q-values) is still subject to some controversy, even among statisticians.
This was why the pformat() option was provided,
defaulting to pformat(%-10.2g).
~Under this default, bmjcip initially converts a P-value of 1 to 1.0,
a P-value less than 1 and no less than .00001 to a left-justified decimal number
with no zero before the decimal point,
a P-value below 0.00001 and greater than 0 to the format x.ye-z
(where x and y are digits and z is an integer),
and a P-value of 0 to 0.
The string e- may then be converted in a way specified by the esub() option,
allowing very small P-values to be displayed with the exponent as a superscript.
Note that, if the P-values are output by listtab and converted manually into Microsoft Word tables,
then the user must convert each "-z" to a superscript manually.

If the user wishes to keep the original numeric variables,
then the user may use clonevar to make new numeric variables that are copies of the original variables,
and then reformat these to string variables using bmjcip.

For more about the use of bmjcip with listtab and other packages to create tables,
see Newson (2012).

Examples

The following lines of code input the auto dataset,
and use regress and parmest to replace it with an output dataset (or resultsset),
with one observation for each parameter of a model predicting car weight from repair record,
and data on parameter estimates, confidence limits and P-values.
This resultsset is described and listed.

. sysuse auto, clear

. regress weight i.rep78

. parmest, norestore omit format(estimate min* max* %8.2f)

. describe

. list

The following examples demonstrate bmjcip with the dataset created above.
Note that these examples must begin with preserve and end with restore
in order to restore the original resultsset for the next example.

. preserve

. bmjcip p

. list parm p

. restore

. preserve

. bmjcip estimate p

. list parm estimate p

. restore

. preserve

. bmjcip estimate min95 max95 p

. list parm estimate min95 max95 p

. restore

. preserve

. bmjcip estimate min95 max95 p, cformat(%10.3f) refexp(omit)

. list parm estimate min95 max95 p

. restore

. preserve

. bmjcip estimate min95 max95, cf(%10.1f) refexp(omit) reflabel("(Ref.)")

. list parm estimate min95 max95

. restore

The following examples demonstrate the use of the headline() option
to reset the characteristic var[varname],
used by the subvarname option of the list command.

. preserve

. bmjcip estimate min95 max95 p, head(varname)

. list parm estimate min95 max95 p, abbr(32) subvar

. restore

. preserve

. bmjcip estimate min95 max95 p, head(varname, e("Coef.") l("[95%") u("CI]") p("P>|t|"))

. list parm estimate min95 max95 p, abbr(32) subvar

. restore

The following example demonstrates the use of the headline() option
with the listtab package.
The listtab_vars module is used to create a local macro myhead1,
containing a headline row for an HTML table.
The listtab module types the table, complete with its headline row.
The whole table can then be cut and pasted from the Stata results window into Microsoft Word or another word processor,
and then converted from a text form to an HTML table.

. preserve

. bmjcip estimate min95 max95 p, esub(htmlsuper) head(varname)

. listtab_vars parm estimate min95 max95 p, rstyle(htmlhead) substitute(char varname) local(myhead1)

. listtab parm estimate min95 max95 p, rstyle(html) type headlines("<table>" "`myhead1'") footlines("</table>")

. restore

The following example demonstrates the standard 20th century practice, in medical journals,
of reporting P-values below a certain minimum level simply as being less than that minimum level,
which, in this example, is .0005.
This practice removes the problem of formatting very small P-values,
which would otherwise have to be presented with exponents.
However, in the early 21st century,
biochips with a million (or more) assays became available,
allowing medical scientists to measure the associations of all these assays with a disease.
On average, 500 of these associations will have sample P-values less than 00005,
even if all associations are null in the population at large.
This implies that a P-value less than 00005 is not necessarily "as good as zero".
There is still no consensus on the best solution to this problem,
even among medical statisticians.
Note that the xmlsub option is used here,
so that the label "<.0005" is reformatted to "&lt;.0005",
allowing the decoded string variables to be included in a table in an XHTML document.

. preserve

. replace p=0 if p<.0005

. lab def _p 0 "<.0005"

. lab val p _p

. bmjcip estimate min95 max95 p, xmlsub

. describe

. list parm estimate min95 max95 p

. restore

Author

Roger Newson, King's College London, UK.

Email: r.newson@kcl.ac.uk

References

Altman, D. G., D. Machin, T. N Bryant and M. J Gardner.
2000.
Statistics with Confidence.
2nd ed.
London, UK: British Medical Journal.

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12(2): 191-213.
Download from The Stata Journal website.

Also see

Manual: [D] destring, [D] clonevar, [D] format, [P] char

Help: [D] tostring, [D] destring, [D] clonevar, [D] format, [P] char

sdecode, parmest, listtab, qqvalue if installed