RE: st: how to cite Stata helpfile

["Seed, Paul" <paul.seed@kcl.ac.uk>]

There are differences in what is expected and permitted in different 
journals & areas of research.  In my own field (biomedical research), 
there is a clear distinction between learned papers & books (mainly 
published in peer-reviewed journals or by learned societies), which are 
included in the Reference section, and scientific technology, which is 
described in the text of the article, generally in the methods section. A 
typical sentence would be "Data analaysis was conduced using the 
statistical program Stata (Version 11.2, StataCorp, College Station, 
Texas)." The equipnent used for bio-assays and the quality of life 
questionnaires etc. would be described similarly.  

Where the method being used is unusual, a reference would also be given.
If I relied heavily on a particular technique, I might name the command, and 
refer to the Stata Journal article where it is described; much as Nick suggests. 
For -ivreg2-, idf there was nothing in the help file, I would start by typing -findit ivreg2- and noting that the first 
response is to Kit Baum's book.

The reference would be along the lines of 
Christopher F. Baum (2006) "An Introduction to Modern Econometrics Using Stata"
chapter 8 "Instrumental-variables estimators" Stata Press ISBN-13:  978-1-59718-013-9

If (more usually), there was no book, I might go for 
C. F. Baum, M. E. Schaffer, & S. Stillman (2003)
Instrumental variables and GMM: Estimation and testing
Stata Journal 3(1):1-31

However,  if I actually checked the helpfile, I would find the preferred form:
 Baum, C. F., M. E. Schaffer, and S. Stillman. 2007.  ivreg2: Stata module for extended instrumental
variables/2SLS, GMM and AC/HAC, LIML, and k-class regression. Boston College Department of Economics,
Statistical Software Components S425401. Downloadable from http://ideas.repec.org/c/boc/bocode/s425401.html.

Finally, if we were strictly limited on references, I might have to settle for
extending the sentence above: "Data analaysis was conduced using the statistical program Stata 
(Version 11.2, StataCorp, College Station, Texas), and the user-written command 
-ivreg2- for instrumental variable regression (authors Baum, CF, ME Schaffer, and S Stillman,
 Boston College Department of Economics, Boston, Massachusetts." 


Date: Tue, 08 Nov 2011 11:57:41 -0500
From: Richard Williams <richardwilliams.ndu@gmail.com>
Subject: RE: st: how to cite Stata helpfile
At 11:21 AM 11/8/2011, Nick Cox wrote:
>I disagree to some extent with Richard's recommendations, 
>particularly on what he calls "utilities".
Fair enough. Perhaps it would be a good practice to include a 
footnote or acknowledgement like "Several user-written Stata routines 
were employed in this analysis. These include XXX (Cox, 2009); XXX 
(Baum, 2007)." Authors can help their cause by explicitly saying in 
the help file that they expect citations and show how the work should 
be cited. If the editor wants to kill the citations, well, at least 
you've tried.
Incidentally, articles often don't even say what major package was 
used (e.g. Stata, SAS, SPSS) let alone the specific programs. I 
usually harass authors to provide such details and to make their data 
and code available if at all possible. I also tell people that if you 
have written some sort of Stata program, you'll probably have a lot 
more impact and get a lot more citations if you provide the software 
so people can do it themselves rather than have to figure out how to 
program from scratch.
>If anybody's published work, meaning work made public, was important 
>to you in work with Stata that you in turn want to publish, then you 
>have a moral obligation to cite it.
>
>Second-guessing how useful a citation might be to the original 
>author is scarcely the point. Citations that don't help a career 
>much don't do much harm either.
>
>Also, it so happens that many papers in many fields include little 
>or nothing on the data management that lay behind the analysis, and 
>so there is often not a section where citations would be 
>appropriate, but that is an empirical question, not a matter of principle.
>
>Also, whether reviewers or editors of certain journals will accept 
>citations to programs alone can be a tricky question, but authors 
>are surely honour-bound to try to cite others' work responsibly and fully.
>
>There is a bizarre confusion in some quarters between "making freely 
>available", which many people do in the Stata community, and 
>"relinquishing intellectual property rights", a different matter altogether.
>
>Nick
>n.j.cox@durham.ac.uk
>
>Richard Williams
>
>At 03:05 PM 11/7/2011, Jet wrote:
> >HI, how to cite a Stata helpfile (e.g., betafit) if needed? Wonder if
> >there is any suggested way to do so. Thanks!
>
>The Stata 12 User's Guide says
>
>The suggested citation for this software is
>StataCorp. 2011. Stata: Release 12. Statistical Software. College
>Station, TX: StataCorp LP.
>
>For a built in command, I suppose you could also cite the appropriate
>reference manual. I would especially do that if I was directly
>quoting from the manual. The manual usually has the same text as the
>help file, and more.
>
>For a user-written command --
>
>I would suggest seeing if the help file includes a suggested
>citation. If you  are using one of my programs, my strong preference
>is that you cite one of my published articles, assuming I have
>written a relevant article for the command.
>
>Barring that, or in addition to, you might try citing the repec
>pages. For example, the user-written ivreg2 help file makes this suggestion:
>
>---------------
>ivreg2 is not an official Stata command. It is a free contribution to
>the research community, like a paper. Please cite it as such:
>
>      Baum, C.F., Schaffer, M.E., Stillman, S. 2010.  ivreg2: Stata
>module for extended instrumental variables/2SLS, GMM and AC/HAC, LIML
>and k-class regression. http://ideas.repec.org/c/boc/bocode/s425401.html
>---------------
>
>As to when to cite - my own feeling is that if you are using a
>user-written estimation command, you should cite the authors of that
>command. Utilities, probably not, unless they had a really major
>impact on the analysis. If you do feel a deep debt of gratitude for
>some utilities, perhaps those authors could be mentioned in the
>acknowledgments instead. Citations of published work are what is
>going to help most scholars the most, but other types of appreciation
>are nice as well.
>
>
>*
>*   For searches and help try:
>*   http://www.stata.com/help.cgi?search
>*   http://www.stata.com/support/statalist/faq
>*   http://www.ats.ucla.edu/stat/stata/
- -------------------------------------------
Richard Williams, Notre Dame Dept of Sociology
OFFICE: (574)631-6668, (574)631-6463
HOME:   (574)289-5227
EMAIL:  Richard.A.Williams.5@ND.Edu
WWW:    http://www.nd.edu/~rwilliam
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/
------------------------------
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/