[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

"Official", "documented", and so forth [was: RE: st: AW: listing variables with certain characteristics]

From   "Nick Cox" <>
To   <>
Subject   "Official", "documented", and so forth [was: RE: st: AW: listing variables with certain characteristics]
Date   Fri, 28 Aug 2009 16:15:19 +0100

I'd like to believe that everyone is right, but some are more sloppy
than others in using terminology.... 

Here's my version of the truth. Although it may look complicated, it's
also a simplification, especially in terms of what I don't know I don't

"Official" in Stataland means, maximally or weak sense, bundled with
Stata as shipped by the company each release, or added in updates
between releases. 

Most of that code is written by StataCorp employees; even code that is
bundled with Stata but publicly attributed to users is worked over by
StataCorp employees before release -- in fact, quite often completely

In contrast, "user-written" in Stataland means what it says, except that
it excludes code written by users originally but now included with
Stata, as mentioned just above. It includes some code written by
StataCorp employees, who are users like everybody else. So, for example,
Bill Gould, President of StataCorp, may include some code in a Statalist
posting or a Mata Matters column in the Stata Journal. Its writing by a
company employee, even the President, does not make it official. Only if
it is explicitly included in Stata later does it become official. 

StataCorp employees who have this role of writing official code as part
or all of what they do are also called "developers".

-ds- has in this sense always been "official". It was born an official
command; it has been changed to include code originally written by
users, but that's consistent with the definition; the last person to
change the code was a StataCorp employee. This is not a matter of my
opinion or judgment; it's historical fact. 

I hope you noticed the lexicographic or legalist qualifier, "maximally
or weak sense". Clearly, different parts of Stata are not equal. Some,
especially the more visible parts, are much more important than others
and it's very important to users and developers that they work
consistently from release to release, as no one appreciates their
programs or do-files being broken by changes in Stata. Others are less
important. Quite a large fraction of Stata is written by StataCorp
developers for their own use, and although not all hidden from view,
most of that is not made highly visible either. That part is also highly

A minimal or strong sense of "official" is in effect not just shipped
but "supported". How strong is StataCorp's commitment to ensuring that
particular commands remain from release to release? The best single
guide to this is the kind of documentation provided. 

Here we come to some more terms that are more slippery than they might

"Documented" in Stataland has a special sense of "documented in the
manual as well as the help files". 

"Undocumented", perhaps most surprisingly of all, has a special sense of
"not documented in the manual" but "documented via help files". See
-help undocumented- if this idiosyncrasy is new to you. 

As of Stata 11, StataCorp has added a category of "previously
documented". See -help prdocumented-. Despite the adverb, this category
of commands remains documented in the sense that help files are still
accessible. As of Stata 11, -ds- is marked in this way. As I've said
before, I don't think that it has really been superseded by anything
else. But that is an judgment of mine and so neither here nor there.
Jeph is I think quite right in inferring that StataCorp are making no
promises about its survival or longevity. I think this is what is
implied by the statement that -ds- is no longer an official part of
Stata. Personally, I think it's at least a little confusing that the
term "official" is being used in this different sense. 

StataCorp has many degrees of letting old stuff fade away. For example,
the old -for- was abandoned in Stata 8, but I believe will still work,
but you'd need to fire up an old Stata or open an old manual to find any
help, so its use is definitely being discouraged. 

That still leaves many commands that really are "not documented". Anyone
new to all this might reasonably ask: how are they visible then? By
being names of .ado files that the curious find in rummaging in Stata's
folders; by being invoked in programs; by being mentioned in postings or
talks at users' meetings. 

Generalities aside, Jeph's specific problem remains. 

1. He could write a specific program that just checks for
characteristics. That would be a little more efficient than -ds- can be
because it would spend no time checking for other requests. I can't see
why he needs to do this during Stata 11 unless the programming is
otherwise fun. 

2. He could continue to use -ds-. If Stata 12 (or any other future
release)  dropped -ds-, he could copy the code to his personal folders,
although the copied -ds- might not work if something it called was not
included in that release. If that release introduced something else
called -ds-, he would need to change the name. 

I personally am not worried or exercised by the fate of -ds-. Programs
are not children: easy come, come go. Even if StataCorp drop -ds- and
fail to replace it by an equivalent, it would be easy enough to
re-create something similar under another name. 


Jeph Herrin

My esteem of Nick not withstanding, his assertion:

  "7. -ds- remains an official command. There is absolutely
   nothing unofficial about it."

is contradicted in my mind by the first line of the
help file in Stata 11:

  "ds continues to work but, as of Stata 9, is no longer an official
   part of Stata."

Now, if "official" is a dichotomous state, and StataCorp is
the ultimate arbiter of what is official and what is not, I would
have to say that at the least Nick's "absolutely" is unwarranted.

Martin Weiss wrote:
> "-ds- seems to be on the verge of extinction."
> See Nick`s recent statement number 7 to the contrary here:
Jeph Herrin
> I have often found it helpful to keep track of
> metadata associated with variables by assigning
> it as characteristics. So, for instance, a variable
> which is of type checkbox, in module 6, question 3
> of a survey might have
>     myvar[type]:        checkbox
>     myvar[module]:      6
>     myvar[question]:    3
> and so on. What I'm looking for is a good way to
> generate a list of variables that have, eg, module=6.
> Right now, the best I can do is
>    ds, has(char module)
> to get the list of variables that have a "module"
> characteristic, then loop over that list to pick
> out the ones where module=6. This bothers me because
> (a) it seems there should be a better way than looping
> and (b) -ds- seems to be on the verge of extinction.
> I'm about to write  my own utility to do this, since
> I need to do it so often, but thought I'd see if there
> wasn't a better way already out there. Is there a
> a direct way to get a list of variables where the
> characteristic exists and has a certain value?

*   For searches and help try:

© Copyright 1996–2017 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index