*! Help file Version 1.72 11Dec2017 for firstpartial.ado

Title

firstpartial -- Construct the derivative
of an estimation command's variable list containing factor variables.

Syntax

firstpartial
wrt_varname
,
cmdline(string)
[options]

Options

Required options

wrt_varname The name of an existing variable with respect to which
firstpartial finds the first partial derivative. This is the -wrt- variable.

cmdline(string) The commmand line from a Stata estimation command
that is linear in the parameters. See below

Optional options

chain(string) unwind transformation for both dependent and -wrt- variables

chainlhs(string) unwind transformation for dependent variable

chainwrt(string) unwind transformation for -wrt- variable

boxcox(#) parameter with which boxcox transformation is made for -wrt- variable
(output only); default is boxcox(0.5)

force force execution even if the prefix on varname
does not match the -chain- option

Description

firstpartial enables the computation of the estimated partial
derivative of the right-hand-side of any Stata estimation command
that is linear in the parameters. Examples of such estimation commands
are reg, xtreg, frontier, ivregress,
logit, logistic, probit, xtivreg, sureg and reg3.
The right-hand-side can include non-linear terms, provided that
they are constructed using Stata's factor variables.

Of course, in the absence of interactions, the partial derivative
with respect to a right-hand-side variable
is just its estimated coefficient.
So the utility of this program is mainly due to its ability
to analytically derive a Stata expression for the first-partial
derivative of a right-hand-side variable that is interacted
with other variables (or squared or cubed) using the
factor variable syntax.

This program accepts an estimation command line as input and produces
a Stata "expression" as output.
The produced expression defines the estimated first-partial derivative
as a function of the estimation data and the estimated parameters.
Then the user can compute an estimate of the first-partial derivative
for any value(s) of the right-hand-side variables by using the expression
in a subequent generate or margins command.

By executing firstpartial recursively, an earlier version of
the program could yield a Stata expression for estimated
second and higher derivatives as well as cross-partial derivatives.
This feature is no longer working in version 1.13.

For the simplest possible example, suppose the command line expression is:

. reg y x1 x2 c.x1#c.x2

Define y_hat as the fitted value of y from the above regresion.
After this equation is estimated, the command combination:

. firstpartial x1, cmdline("reg y x1 x2 c.x1#c.x2")

. margins, expression("`r(expression)'")

will compute the estimated partial derivative of y_hat with respect to
x1 at every sample point. The program firstpartial is not necessary
in this simple example, because the margins command with the option
dydx(x1) makes the same computation. However, the margins command
does not return an expression for the first partial derivative for further use.

The added value of combining firstpartial with margins allows the
computation of point and interval estimates of parameters
like Allan-Uzawa elasticities of substitution, for which the formula is in turn
a function of first-partial derivatives.

Another feature of firstpartial is its ability to apply the chain
rule in order to "unwind" a derivative when the variables in the estimations
are themselves functions of more fundamental variables. Consider, for example,
the command line expression:

. reg ln_y ln_x1 ln_x2 c.ln_x1#c.ln_x2

where adding prefix "ln_" indicates that a variable is the logarithm
of its original value. After this equation is estimated, the command combination:

. firstpartial ln_x1, cmdline("reg ln_y ln_x1 ln_x2 c.ln_x1#c.ln_x2")

. margins, expression("`r(expression)'")

will compute the estimated partial derivative of ln_y_hat with respect to
ln_x1, which economists know as the elasticity of y with respect to x1.
However, if the y represents total output and the x1 represents, for example,
the quantity of labor, we might also want to know the estimated marginal product of labor,
which is defined as:

MP_L = (d_ln_y/d_x1)*(y_hat/x1)

Adding the chain(ln) option to firstpartial facilitates this computation
by yielding a factor variable expression which margins uses to compute
both point and interval estimates of the marginal product at specified values of the right-hand-side
variables. Here's the code:

. firstpartial ln_x1, cmdline("reg ln_y ln_x1 ln_x2 c.ln_x1#c.ln_x2") chain(ln)

. margins, expression("`r(margexpression)'")

firstpartial works with the companion program flexmake and can
unwind any of the monotonic transformations which can be produced by flexmake.
In addition to the natural logarithm, flexmake can generate, and
firstpartial can unwind, the square-root, boxcox and log10 transformations.
Furthermore, firstpartial can unwind a different one of these transformations
on the left- and right-sides of the estimating equation.

For a discussion of the potential utility of the Box-Cox transformation, see the
helpfile for flexmake and the entry in Stata's reference manuals
for Stata's boxcox estimation command.

Examples

For the following examples to work, the program
flexmake must also be installed. Like firstpartial, the user can
install it from CGD's Stata repository
here.

To demonstrate the use of the firstpartial command, we replicate the
results in Christensen and Greene(1976) using data from that study provided
by Bill Green on his NYU website as companion to his econometrics textbook
Greene (

Example 1.

. *	Setup: use data from Christensen and Greene(1976)

. import delimited using "http://people.stern.nyu.edu/wgreene/Text/Edition7/TableF4-4.txt", delimiters(" ", collapse) varn(2) clear

. drop v11

. genl plbypf = pl/pf

. genl pkbypf = pk/pf

. genl costbypf = 1000000*cost/pf

. *	make transformation

. flexmake costbypf, outputs(q) prices(pkbypf plbypf) ln half replace

. return list

. global depvar `r(depvar)'

. global ownprices `r(ownprices)'

. global ownprices2 `r(ownprices2)'

. global crossprices `r(crossprices)'

. global ownoutputs `r(ownoutputs)'

. global ownoutputs2 `r(ownoutputs2)'

. global crossoutputs `r(crossoutputs)'

. global outputsxprices `r(outputsxprices)'

. *	Now estimate the translog system

. constraint 1 _b[ln_costbypf:c.ln_pkbypf] = _b[sk:_cons]

. constraint 2 _b[ln_costbypf:c.ln_plbypf] = _b[sl:_cons]

. constraint 3 _b[ln_costbypf:c.ln_pkbypf#c.ln_pkbypf#c.__half] = _b[sk:ln_pkbypf]

. constraint 4 _b[ln_costbypf:c.ln_plbypf#c.ln_plbypf#c.__half] = _b[sl:ln_plbypf]

. constraint 5 _b[ln_costbypf:c.ln_pkbypf#c.ln_plbypf] = _b[sl:ln_pkbypf]

. constraint 6 _b[ln_costbypf:c.ln_pkbypf#c.ln_plbypf] = _b[sk:ln_plbypf]

. constraint 7 _b[ln_costbypf:c.ln_q#c.ln_pkbypf] = _b[sk:ln_q]

. constraint 8 _b[ln_costbypf:c.ln_q#c.ln_plbypf] = _b[sl:ln_q]

. sureg ($depvar $ownprices $ownprices2 $crossprices $ownoutputs $ownoutputs2 $crossoutputs $outputsxprices ) (sk $ownprices $ownoutputs ) (sl $ownprices $ownoutputs ), constraints(1/8)

. predict ln_costbypf_hat, xb

. *	First partial deriviative w.r.t. output, which is the marginal cost of output at the mean

. firstpartial ln_q , cmdline(`e(cmdline)') chain(ln)

. global margexpression `r(margexpression)'

. global genexpression `r(genexpression)'

. *	The program returns in the local macro -r(genexpression)- the expression for the marginal cost

. *	evaluated at every point in the sample. Using this expression requires that

. *	the user create the variable -depvar-_hat using the predict command.

. *	Then -gen- can create the observation-by-observation marginal costs.

. gen d_TC_d_q = $

. lab var d_TC_d_q "Marginal cost of output"

. *	So one option for computing a summary value for the marginal cost

. *	is simply to compute the mean of the generated variable.

. sum d_TC_d_q if e(sample)

. *	Using firstpartial's local macro -r(margexpression)- (which was stored

. *	above as the global macro $), Stata's -margins- program

. *	computes not only the the marginal cost, but also its standard forecast error.

. *	Without other options, margins is also evaluating the marginal cost by observation.

. *	So its estimate matches the mean of the estimate from the -generate- command.

. margins , expression($)

. *	Furthermore, the margins command will easily compute the predicted marginal cost

. *	of output at other values of output. For this purpose, its best to hold other variables

. *	at fixed values, such as with the "atmeans" option

. sum ln_q, det

. margins , expression($) atmeans at(ln_q=(`r(mean)' `r(p10)' `r(p25)' `r(p50)' `r(p75)' `r(p90)'))

. *	And the command marginsplot gives the marginal cost curve as a function of ln_q

. marginsplot, xlabel(,angle(45) format(%9.3f)) ytitle("Marginal cost of output")

(click to run)

Example 2.

. *	By iterating flexmake we can estimate with a boxcox transformation of output

. *	First set up the problem by downloading the data and defining the variables and constraints

(click to run, before the following commands)

. *	Then iterate in search of the best fitting value of lambda

(click to run, after clicking above to set up the problem)

. *	Here are the results of the iteration showing that the best fit is the first iteration.

. *	But there is a second local likelihood maximum achieved on the 12th iteration with lambda = 0.12 .

(click to run, after clicking above to search for best lambda)

. *	Re-estimate with these two values of lambda, storing the estimates

(click to run)

. *	Display the table of estimated parameters for comparison across models

(click to run, after running all the above examples)

Stored results

firstpartial stores the following in r():

Macros

r(depvar) variable of which derivative is taken

r(wrt) variable with respect to which derivative is taken

r(expression) expression of derivative using variables in the
estimated equation, which may or may not have been transformed

r(genexpression) expression of derivative using original variables;
for use in a subsequent generate command

r(margexpression) expression of derivative using original variables;
for use in a subsequent margins command

r(tokenswithwrt) regressor with -wrt-

r(tokenswowrt) regressor without -wrt-

References

Christensen, L.R. and Greene, W.H., 1976. Economies of scale in US electric power generation.
The Journal of Political Economy, pp.655-676.

Greene, W.H., 2012. Econometric Analysis, Stern School of Business, New York University.

Author

Mead Over at:
Email: MOver@CGDev.Org if you observe any problems.

Default value of boxcox is 0.5