Title

C-function Specification

Vars-by-Funcs Syntax

The most concise syntax, when it suffices, is:

[varelist] [: C-func(VxF details) [C-func(VxF details) ...]]

You specify a set of variables and a set of functions, and each function is applied to each variable.

If varelist is not specified, all variables are used.

If no functions are specified, a command-specific default is used.

Explicit Syntax

You can also specify each result explicitly:

C-func(exp details) [C-func(exp details) ...]

Or, to save some typing, you can cross some variables and functions in an otherwise explicit list:

C-func(exp details) | VxF(vars-by-funcs) [...]

where vars-by-funcs is the entire Vars-by-Funcs Syntax, above.

C-Func

Description

The general theme of the C-funcs is that they act on a column of data, in contrast with the standard functions, which typically act row-by-row (ie, observation-by-observation). For example:

o- The standard function min(a,b,c,d) returns the minimum, in each observation, of a, b, c, and d.

o- The C-func Min(a) returns the minimum of a across all observations (the whole column).

No errors are generated for string or numeric data; however, as noted below some functions return missing for string data.

Except for Nobs() and (), all of the functions exclude missing values.

Syntax -- Note the required C-apitalization

Function Description String returns

Mean(Cfexp [,options]) mean missing
Var(Cfexp [,options]) variance missing
SD(Cfexp [,options]) standard deviation missing
Sum(Cfexp [,options]) sum missing

Med(Cfexp [,options]) median string
P(Cfexp [,options]) nth percentile string
Min(Cfexp [,options]) nth minimum string
Max(Cfexp [,options]) nth maximum string

N(Cfexp [,options]) count (ie, not missing) numeric
True(Cfexp [,options]) not zero missing
Uniq(Cfexp [,options]) distinct values numeric

Nobs( [,options]) number of observations --
(Cfexp [,options]) apply options only string

Nobs() takes no main parameter; it returns the relevant number of observations.
Depending on the context, that would be rows in the dataset, or in the subset selected by [if] [in] and/or by() variables.

() can be used to apply options, such as name() or nlabel(), to a Cfexp.
Generally, if you supply a Cfexp outside of a function, it will be treated as (Cfexp) instead of causing an error.

Standard Options

weight(varname) specifies a variable holding frequency weights.

name(newvarname) specifies a variable name for the results of the function, when it will end up in a dataset (eg, collapsel, elgen).

nlabel(text) specifies a variable label for the results of the function, when it will end up in a dataset (eg, collapsel, elgen).

description(text) specifies a descriptive label for the results of the function, when it will be directly displayed (eg, tstats, tlist).

format(format) specifies either a standard stata format, or the name of an existing variable in the dataset.
If a variable is specified, both that variable's format, and its value labels will be applied to the result, if possible.

All of the standard options except weight() are ignored when their C-funcs are nested inside other C-funcs.

Option for Min() and Max()

integer specifies the position relative to the extreme. 1, the default, is the absolute min or max. Min(var,3) would return the 3rd lowest value.

Option for P()

integer specifies the percentile. When not specified, it defaults to 50. P(var,25) would return the 25th percentile.

Options for True() and Nobs()

% or / specify that the results be returned as percent or proportion, rather than count:

For True(), the denominator is the number not missing in the cell.

For Nobs(), the denominator is the total number of observations for the command - ie, across all by-groups.

Cfexp

A Cfexp (the main parameter for a C-func) is an extension of the standard Stata expression.
It can inlcude standard functions, nested C-funcs, and the following R-functions:

Rsum(varelist)
Rmean(varelist)
Rmin(varelist)
Rmax(varelist)
Rn(varelist) -- number not missing
Rtrue(varelist) -- number not missing and not zero
Rvars(varelist) -- number of variables in varelist

R-functions act on a set of variables, row-by row. They are essentially just shortcuts;
eg, instead of writing a1+a2+a3+a4+a5, one might write Rsum(a*).

For evaluation, R-functions are converted into the corresponding standard expressions, and so the usual restrictions would apply. For example, Rmean() of strings would cause an error.

Explicit vs VxF context

The above description applies the explicit context, in which the entire contents of the C-func is specified.
In the VxF context - that is, after a : - The Cfexp must refer to the varelist before the colon. It can do this in one of two ways:

1) The Cfexp may be omitted entirely, or

2) a marker - #V - must be included to stand in for the actual variables.

For example, the C-funcs below would be applied to each variable beginning with the letter a:

mean and median: a*: Mean() Med()
a*: Mean(#V) Med(#V)

centered: a*: #V-Mean()
a*: #V-Mean(#V)

weighted mean: a*: Mean(, weight(#V_wt))
a*: Mean(#V, weight(#V_wt))

The last example assumes that, for each variable aX, the dataset includes a matching variable, aX_wt.