FRML Instruction

FRML( options ) formulaname = function(T)

FRML( options ) formulaname depvar = function(T)

FRML( options) formulaname depvar

# list of explanatory variables (in Regression Format, only for REGRESSORS option)

FRML is one of the most important instructions in RATS. It defines a formula which can be used for non-linear estimation, forecasting, and simulation. When you are using the FRML for non-linear estimation, you should do your NONLIN instruction first, so the free coefficients will be declared.

Select which form to use based upon the following:

•MAXIMIZE requires only the function, and will ignore a dependent variable (depvar) if one is specified.

•Simulations and forecasts require a left-side variable (depvar).

•Formulas for NLLS and NLSYSTEM can take either form. For models which require a dependent variable, NLLS gives you the option of specifying the dependent variable with the FRML or with the NLLS instruction itself. With NLSYSTEM, however, you must specify any dependent variables in the FRML instructions.

Wizard

You can use the Statistics—Equation/FRML Wizard to define formulas.

Parameters

formulaname	symbolic name for the right hand side formula
depvar	dependent (or left-side) variable for a full equation.

Options

EQUATION=equation to convert

LASTREG/[NOLASTREG]

REGRESSORS/[NOREGRESSORS]

The (mutually exclusive) options EQUATION and LASTREG can be used to convert the specified equation or the last regression to a formula. Skip the parameters after formulaname when you use EQUATION or LASTREG. You should only use FRML(EQUATION=xxx) after you have estimated the equation. The REGRESSORS option generates the right hand side of the formula from a list of regressors supplied (in regression format) on a supplementary card. Omit the “=” symbol and function if you use this option.

VECTOR=VECTOR for parameters

NAMES="base for parameter names"

PARMSET=PARMSET to create or modify

ADDPARMS/[NOADDPARMS]

If you use EQUATION, LASTREG, or REGRESSORS and want to be able to use the formula for non-linear estimation, use the VECTOR or NAMES option to tell RATS to construct the formula using free parameter variables, rather than fixed numbers, for the coefficients.

If you use the VECTOR option, the parameters will be the elements of that VECTOR. For instance, if you use VECTOR=BB, the parameters will be BB(1), BB(2), etc. FRML will take care of dimensioning the vector. If you use the NAMES option, FRML will use parameters created by appending 1, 2, etc. to base name that you give. For instance, NAME="BB" will give you parameters BB1, BB2, etc. With either of these options, the parameters will be initialized with the current coefficients of the regression or equation.

If you would like the parameters to be added to a parameter set (PARMSET for short), use the PARMSET or ADDPARMS option, or both:

•Use PARMSET by itself to create a new PARMSET with the name you supply. If a PARMSET with the same name already exists, it will be overwritten.

•Use PARMSET with ADDPARMS to append the new parameters to an existing PARMSET (a new set will be created if necessary).

•Use ADDPARMS by itself to append the parameters to the default internal parameter set.

You must also use VECTOR or NAMES to specify how the parameters are created.

COEFFS=VECTOR of (fixed) coefficients

If you use EQUATION, LASTREG, or REGRESSORS and want the FRML coefficients to be treated as fixed at a particular set of coefficients (other than the ones currently in the input EQUATION or the last regression if you're using LASTREG), use the COEFFS option to input those. Note that the FRML coefficients are fixed at the values at the time that the FRML instruction is executed—if you want to be able to change them, later, use the VECTOR option instead (even if you don't plan on using the FRML for estimation).

IDENTITY/[NOIDENTITY]

Use the option IDENTITY when the formula you are defining is an identity.

VARIANCE=residual variance

Residual variance for this formula. You only need to supply this if you are going to use SIMULATE.

RESIDUALS=series of residuals

Series holding the residuals for this formula.

Description

FRML defines a function of the form

$f\left( {{X_{1t}},{X_{2t}}, \ldots ,{X_{kt}},{\theta _1},{\theta _2}, \ldots ,{\theta _p}} \right)$

${y_t} = f\left( {{X_{1t}},{X_{2t}}, \ldots ,{X_{kt}},{\theta _1},{\theta _2}, \ldots ,{\theta _p}} \right)$

where each $X_t$ is a RATS data series, and each $\theta$ is a REAL variable or element of a real-valued array. If you are using the FRML for non-linear estimation, you will usually need to do a NONLIN instruction prior to defining the FRML to introduce the parameters. Note that you also can define formulas without any $\theta$ parameters.

RATS stores the relationship in a variable of type FRML, with the name you supply for formulaname. In general, you write the function in terms of the INTEGER time subscript T in the same manner as the right side expression is written for SET. As with SET you can use either series or series(T) to refer to the current value of series and series{lag} for a lagged value.

Once you have defined a formula (and specified values for any $\theta$ variables, if there are any), you can use it in expressions with

formulaname(entry)

which will take the value of function(entry). You can do this no matter which form of the FRML command you chose—RATS only uses the function(T) part in the full equations.

Examples

frml avgvalue = (gdp{2}+gdp{1}+gdp+gdp{-1}+gdp{-2})/ 5.0

compute avg1909 = avgvalue(1909:1)

compute avg1901 = avgvalue(1901:1)

compute avg1885 = avgvalue(1885:1)

evaluates five year moving averages of GDP around specified time periods.

frml(identity) gdpid gdp = consmptn+invest+govtexp+netexp

frml(identity) logm1id logm1 = log(m1)

sur(inst) 3

# conseq

# inveq

# wageeq

frml(equation=conseq) consfrml

frml(equation=inveq) invfrml

frml(equation=wageeq) wagefrml

The first FRML instruction sets up GDPID as the standard income accounting identity. The second is a definitional identity required for certain types of models. The last group of instructions estimates a set of three equations (CONSEQ, INVEQ, WAGEEQ) by three stage least squares, then converts the three estimated equations to formulas.

Simplifying Your Life—Using “Sub FRMLs”

Your formulas can include references to other formulas, as long as the “sub” FRML has been defined earlier. This allows you to separate out the different parts of an overall model, into, say, a regression model and a variance model. For instance, the following shows two equivalent code fragments to estimate a regression of Y on X1 and X2 with first-order autocorrelation correction using common factor restrictions. (Note: these should give almost identical results to AR1).

nonlin rho b1 b2 b3

frml auto1 = rho*y{1} + (1-rho)*b1 + $

b2*(x1-rho*x1{1}) + b3*(x2-rho*x2{1})

linreg y

# constant x1 x2

compute rho=%rho, b1=%beta(1), b2=%beta(2), b3=%beta(3)

nlls(frml=auto1) y

or:

nonlin rho

linreg y

# constant x1 x2

frml(lastreg,names="B",addparms) regfrml

frml auto1 = rho*y{1} + regfrml(t) - rho*regfrml(t-1)

compute rho = %rho

nlls(frml=auto1) y

The second example builds AUTO1 using a second formula (named REGFRML) for the regression part. This can make it simpler to code a complex formula, and does make it simpler to change it. If you want to add an additional explanatory variable to the model the first way, you need to change the NONLIN, FRML, LINREG and COMPUTE instructions. All you need to do in the second is change the supplementary card on LINREG. The first FRML instruction in this second example does all of the following:

•Creates REGFRML with the variables B1, B2 and B3 for the three regression coefficients.

•Initializes B1, B2 and B3 to the values estimated by LINREG.

•Adds B1, B2 and B3 to the list of NONLIN parameters.

If you are creating a formula using a number of “subfrmls,” we would strongly suggest that you explicitly use subfrml(T) (as we’ve done above) rather than subfrml alone when you need to refer to the subformula. This makes it easier to tell formula references from series references.

Reducing Computing Time

You are likely to find subformulas a very handy device in writing your FRMLS. They may, however, obscure how much redundant calculation is done by the overall formula. The instruction

frml truncate = %logdensity(sigmasq,y-rhsfrml) - $

log(%cdf((rhsfrml(t)-tr)/sqrt(sigmasq)))

sets up the log likelihood function for a truncated sample, where RHSFRML is a sub-formula representing the model. As written, this will compute RHSFRML twice for each individual on each function evaluation. This can be reworked to evaluate RHSFRML just once:

frml truncate = (z=rhsfrml(t)) , $

%logdensity(sigmasq,y-z) - $

log(%cdf((z-tr)/sqrt(sigmasq)))

This calculates RHSFRML once (per individual/per evaluation), saving it into the scalar Z, which is then used in the rest of the formula. This cuts the computing time substantially if RHSFRML is long or complex.

Self-Referencing Formulas

You cannot create a FRML which is defined using an explicit reference to itself. If the value of your formula at T depends upon previously calculated values of itself (directly or indirectly), you need to write your FRML to store the values into a series as they are computed. The lagged values then come from the series.

ARCH and GARCH models are the most common types of such recursively defined functions. For instance, in an ARCH-M model, the variance depends upon the lagged residual and the residual depends upon the variance. We can't write down two simple FRML's for this without each (at least indirectly) referencing itself. While this can be done with GARCH, we'll show how to define FRML's to do it. The first of these uses the UU series to save the squared residuals for use in the variance formula.

set u = 0.0

set uu = %seesq

frml archvar = a0 + a1 * uu{1}

frml regresid = y - b1 - b2 * x1 - b3 * sqrt(archvar(t))

frml archlogl = u(t)=regresid(t), uu(t)=u(t)^2, $

%logdensity(archvar(t),u)

We now give a somewhat quicker formulation which also saves the variance in a series. This eliminates redundant calculations of ARCHVAR.

set u = 0.0

set uu = %seesq

set v = %seesq

frml archvar = a0 + a1 * uu{1}

frml regresid = y - b1 - b2 * x1 - b3 * sqrt(v)

frml archlogl = (v(t)=archvar(t)), (u(t)=regresid(t)), $

uu(t)=u(t)^2, %logdensity(v,u)

When you have several layers of formulas, be careful that calculations are done in the correct order. REGRESID depends upon the current value of ARCHVAR, so ARCHVAR has to be calculated first.

VECTORs of FRMLs

RATS allows you to create arrays of FRMLs. For instance,

dec vect[frml] f(3)

nonlin b1 b2

frml f(1) = exp(b1+b2*log(x))

frml f(2) = (b1+b2*sqrt(x))^2

frml f(3) = b1+b2*x

compute b1=b2=0.0

do i=1,3

nlls(frml=f(i)) y

end do i

will estimate three functional forms for the relationship between Y and X.

You have to be careful, however, if the FRML’s are defined in a loop. Wherever you use the loop index in the formula definition, you must prefix it with the & symbol. For instance, the following sets up formulas to estimate Black’s version of CAPM (Campbell, Lo and MacKinlay (1997), chapter 5) for N assets. The asset returns are in the vector of series S.

dec vector b(n)

dec vect[frml] blackf(n)

nonlin gamma b

do i=1,n

frml blackf(i) s(i) = (1-b(&i))*gamma+b(&i)*market

end do i

The &i’s are needed in the formula because (1-b(i))*gamma+b(i)*market is a perfectly good formula, which, when it is evaluated by NLSYSTEM or MAXIMIZE later will use the value of i at the time that the estimation instruction is executed. &i tells FRML to use the value of i at the time that the formula is defined.

FRMLs of other Types

You can also use FRML to define formulas which evaluate to data types other than REAL. These are used for many of the components of a state-space model by DLM. To do this, you must first DECLARE the type of the formula. The formula definition on FRML should then evaluate to the type that you want. As examples:

declare frml[vect] ub

frml ub = ||u1{1},u2{1}||

declare frml[complex] transfer

frml transfer = (1+b*%zlag(t,1))/$

((1‑a*%zlag(t,1))*%conjg((1‑%zlag(t,1))^D))