*!	Ver. 1.3 help file for v. 2.22 of -rayplot- 21May2018 by Mead Over

Title

rayplot -- Post-estimation command to graph the total,
average and marginal cost functions after a multiple-output cost function
has been specified and estimated using Stata's factor variables

Syntax

rayplot [if] [in],
required options
[optional options]

Options

Required options
zvar(varname) Untransformed version of the dependent variable
of the preceding cost-function estimation. Typically this variable is the total cost
per accounting period, which is the sum of the costs of all the individual
factor inputs. Fitted values of this variable
will be used as the numerator for average cost estimates.

yvar(varname) Untransformed version of an output variable
included, possibly transformed by one of the eligible monotonic transformations,
as a right-hand-side variable in the estimated total cost function.
See the description of the chain options for the eligible
transformations.

xvars(varlist) Untransformed versions of one or more
additional output variables
included, possibly transformed by one of the eligible monotonic transformations,
as a right-hand-side variable in the estimated total cost function.
To specify M outputs, the user specifies one yvar and M-1 xvars.
See the description of the chain options for the eligible
transformations.

xvalues(numlist) Provide a list of the values of the xvar
at which the total, marginal and average costs and their confidence intervals
will be estimated by Stata's margins command.
The displayed total, marginal and average cost curves
will be constructed by connecting the points estimated at these values of
the output identified as the xvar. If there are multiple
output variables in the xvars option, the values are those of the
composite variable graphed on the horizontal axis of all the graphs.

se Requests computation of the standard errors of margins predictions
which are used to construct confidence intervals for estimates of total cost,
average cost, maginal cost and the RES and to display those intervals
on the associated graphs. Selecting this option
multiplies execution time by a factor of 3 to 10.

slopes(numlist) Specifies the ray or hyperplane through output space
along which the total, marginal and average cost functions are projected.
When the slopes(numlist) option contains only a single number, it defines
the value of the parameter B in the equation:

yvar = A + B*xvar

When the intercept, A, is zero, the default, the parameter B
determines the slope of a ray through the origin
in the plane spanned by the two outputs
(yvar,xvar) along which estimates of total, marginal and average
cost, and of the ray economies of scale, are calculated.

When the slopes(numlist) option contains more than one number,
the numbers refer successively to the parameters B1, ... , BM-1,
where M is total number of output variables included
on the right-hand-side of the estimated total cost function. These
parameters define a multidimensional "ray" or hyperplane in the M-dimensional
output space according to the equation:

yvar = A + B1*xvar1 + B2*xvar2 + B3*xvar3 + ... + BM-1*xvarM-1.

Computation options
chainlhs(trans) Transformation applied to zvar
which rayplot unwinds in order to compute and graph
the cost curves. Eligible specifications of trans are
ln, sqrt, log10.

chainwrt(trans) Transformation applied to xvar and yvar
and zvar which rayplot unwinds in order to compute and graph
the cost curves. Eligible specifications of trans are
ln, sqrt, log10.

chain(trans) Transformation applied to all three variables
specified by the required options xvar, yvar and zvar
which rayplot unwinds in order to compute and graph
the cost curves. Use this option only when both chainlhs(trans)
and chainwrt(trans) would specify the same transformation.
Eligible specifications of trans are
ln, sqrt, log10.

boxcox(#) Specifies that the output variables on the right-hand-side
are to be transformed by the Box-Cox transformation with
parater #.
Any transformations of the left-hand-side variable (e.g. total cost)
and/or of the other right-hand-side variables (e.g. the input prices)
are specified using the options,
chainlhs(trans) and chainwrt(trans)
or alternatively by using chain(trans). For analysis of a
"Generalized Translog Multiproduct Cost Function" in the sense
Caves Christensen and Tretheway (1980), specify
boxcox(#) chain(ln), where # is selected by
the user. The default value of # is boxcox(0.5)

eqname(passthru) When the cost function has been estimated using
a multi-equation estimator such as sureg, use this option to
specify which of the several equations is the cost function.

restore(string) When the desired set of estimation results is not
current in Stata's working memory, this command enables rayplot to
estimates restore previously stored results and use them in
its computations.

cmdline(string) When rayplot fails to properly
parse the command line stored in e(cmdline) from the previous estimation
the user can provide that command line here. Rarely used.

yweight(real 1) Rarely used.

level(real) Specifies a confidence level other than the default
95% for use in determining the width of computed and graphed confidence intervals.
Eligible values are those for set level. Rarely used.

force Option passed to Stata's margins command which
sometimes enables rayplot to proceed despite singularities in the
data. Rarely used.

intercept(real) Specifies the value of the parameter A in the equation
defining the ray or hyperplane in output space along which rayplot
computes and displays the ray total cost, marginal cost and average cost and
the ray economies of scale. See the description of the
option slopes(numlist) above. The default value is zero. Rarely used.

Titling options
xtitle1(string) First line of the title for the x-axis of all
produced graphs.

xtitle2(string) Second line of the title for the x-axis of all
produced graphs. The user may specify xtitle1(string)
and xtitle2(string) or only xtitle1(string).

tcytitle(string) Y-axis title for the graph of total cost
(the zvar), against the composite output variable.

resytitle(string) Y-axis title for the graph of
the index of the ray economies of scale as a function of the
composite output variable.

acytitle(string) Y-axis title for the graph of average cost
(the ratio of the zvar to the composite output index)
as a function of the composite output variable.

mcytitle(string) Y-axis title for the graph of marginal cost
(the derivative of the zvar with respect to the composite output index)
as a function of the composite output variable.

acmcytitle(string) Y-axis title for the graph of both average and
marginal cost as a function of the composite output variable.

ytitle2(string) Allows the user to specify a second line
for the Y-axis title which appears on all graphs except those of the
ray economies of scale

subtitle(string) Subtitle appearing on all graphs except those of
the ray economies of scale.

note(passthru) A note to appear at the bottom edge of all graphs.

Reporting options
verbose Expand the results printed to Stata's results window
to include the output of Stata's margins command and other intermediate
calculations

Saving options
keep Instructs rayplot to retain in memory the variables it
creates for use in drawing the cost function depictions. The created values of
right-hand-side variables will have the subscript "_at", while the
versions of total cost, average cost and marginal cost estimated at those values
of the right-hand-side variables will have the suffix "_hat".

replace Instructs rayplot to overwrite any pre-existing
variables which have the same names as created variables.

saving(filename) Instructs rayplot to save the created data
in a Stata data file named filename or, if the destination option is specified,
in destpath\filename}.

destination(destpath) Specifies the location on the hard disk of a folder
into which any saved data (i.e. dta file} or graphs (i.e. gph files)
will be saved. Requires the saving option.

gphprefix(string) By default, rayplot attaches a specific
graph name to each created graph. Executing rayplot
a second time overwrites graphs still in memory of the same name. In order
to accumulate, display, save and
otherwise manipulate the graphs from more than one execution of rayplot,
the user may choose to use this option to specify a prefix
that is prepended to all the graph names created by a given execution
of rayplot.

Description

A key objective of the estimation of a cost function is the computation
of estimates of the marginal and average cost of each output.
Once a multiple-output cost function has been estimated,
the definition and computation of the marginal cost of any right-hand-side variable,
such as an output, is straightforward. However, when the specified functional form
includes non-linear interactions of that variable with other variables,
the procedure can be tedious and error prone. The program rayplot is designed
to simplify and automate these calculations.

rayplot assumes that a preceding estimation command
has estimated a function relating variation in a dependent or
zvar variable, typically total cost, to a set of right-hand-side
variables, which includes at least two variables, xvar and yvar,
typically representing the level of production of each of two outputs
of a multiple output production process.
The objective of rayplot is to construct and display a series of
two-dimensional graphs which characterize the relationship of total cost
to outputs. All of the constructed graphs have the same horizontal axis,
a user specified linear combination of all the outputs. The various graphs
estimate and display on the vertical axis one or more
of the functions known as the ray total cost, the ray average cost,
the ray marginal cost or the ray economies of scale on the vertical axis.

rayplot requires that any non-linear interactions in the relationship between
the dependent variable and any of the two or more output variables be captured
by Stata's continuous factor variables syntax, so that, for example, the square
of a variable called x is represented as c.x#c.x, its cube by c.x#c.x#c.x and
the interaction of variables x and y is represented by c.x#c.y.

Discussion

rayplot is one of a suite of programs designed to facilitate the
estimation and interpretation of multiple output cost functions.
Other programs in the collection can be found from within Stata by clicking
here
or by typing into Stata's command window the following command:

view net from http://digital.cgdev.org/doc/stata/MO/flexcost

See the help file for flexmake for further discussion of flexible
functional forms for cost functions.

When total cost is a function of more than one output, a marginal cost
is defined for any one of the outputs as the increment to total cost associated with
a one unit increase in that output, holding all other outputs, all prices and
all other cost determinants constant.
Formally, the marginal cost of an output is the partial derivative of total cost
with respect to that single output.

A companion program in this suite of programs,
firstpartial exploits Stata's factor variable syntax
in order to parse the estimated cost function
and return to the user an expression for the partial derivative
of estimated total cost function with respect to the output of interest.
By feeding this expression to Stata's margins command,
the user can estimate the marginal cost of the output at any point
in sample space and thus can trace out the marginal cost curve as a function
of the quantity of that output.

In the design of policy towards an industry in which firms typically
produce multiple outputs, policy makers and industry representatives are aware
that marginal cost is an insufficient guide to regulating the price or reimbursement
for outputs. In the presence of fixed costs or other sources of economies of scale,
a firm may be producing its outputs at such low marginal cost that
receiving only the marginal cost as payment for each unit of output would
generate total revenue substantially less than the total cost of production -
thus driving the firm out of business.

When firms produce only a single output, they can avoid losses
by receiving at least the average cost of that output as payment for each unit produced.
In the single output case, the definition of average cost is unambiguous and
an average cost curve can be constructed as a function of output.
With a single output, a downward sloping average cost function is associated with
economies of scale, an upward sloping one with diseconomies of scale, a flat
average cost function denotes constant returns to scale and the minimum
of a U-shaped average cost curve is known as the "minimum efficient scale" of production.
Aware of these chracteristics of average cost in the single output firm, policy makers
responsible for setting the reimbursement prices for an output of interest ask analysts
for the average cost of that output, or, if economies of scale seem pertinent,
for the average cost of the output at various scales of production.

When the estimated cost function allows for the possibility of economies of
scope in joint production by including more than one output on the
right-hand-side, defining and estimating the average cost of an output
is not so straightforward.
Except in the special case where total costs are "sub-additive"
(Baumol et al., 1982),
the average cost of any output will vary
depending on how much of the other output is jointly produced in the same
firm. The solution to this ambiguity is for the user to specify a "ray" in output
space along which the average cost is computed. In the typical application,
this ray is defined by a linear relationship among the output variables such as:

yvar = A + B*xvar

when there are two output variables or:

yvar = A + B1*xvar1 + B2*xvar2 + B3*xvar3 + ... + BM-1*xvarM-1.

when there are M output variables.

Examples

Under construction

Stored Results

In the return space, rayplot returns a list of all the variables
graphed in the total, average and marginal cost curves and in the ray economies
of scale graph, whether are not the user has requested these variables be retained
(option keep) or saved (option saving(filename)).

r(newvrbls) List of created variables.

References

Baum, C. and T. Linz (2009) "Evaluating concavity for production and cost functions,"
Stata Journal, 9-1, pp. 161â€“165.

Baum, C. (2010) "Stata tip 88: Efficiently evaluating elasticities with the margins command,"
Stata Journal, 10-2, pp. 309â€“312.

Baumol, W.J., J.C. Panzar, R.D. Willig (1982)
Contestable Markets and the Theory of Industrial Structure.
Harcourt, Brace Jovanovich.

Caves, Douglas W., Laurits R. Christensen, Michael W. Tretheway (1980)
"Flexible Cost Functions for Multiproduct Firms"
The Review of Economics and Statistics, Vol. 62, No. 3, pp. 477-481.

Greene, W. H. 1997. Econometric Analysis. 3rd ed. Upper Saddle River, NJ: Prentice Hall.

------ 2012. Econometric Analysis. 7th ed. Upper Saddle River, NJ: Prentice Hall.

Meyer-Rath, G. and M. Over (2012) "HIV Treatment as Prevention:
Modelling the Cost of Antiretroviral Treatment —
State of the Art and Future Directions". PLoS Med 9(7): e1001247.
doi:10.1371/journal.pmed.1001247

Wiens, E.G. (Accessed 10/30/16)
"Egwald Economics: Cost Functions", Web page.

Author

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