Functions

This page lists all functions in fdm and is a valuable reference. If you are new you may want to look at a tutorial first or browse through the cheat sheet or snippets to get an idea of what you can do. But once you know how fdm works this will be a frequenct visit as functions are important in fdm … in fact …

Everything is a function

In fdm there are no keywords as everything is a function. Thus if you want to use an if statement you’d rather use the if function, like so

if( <condition>, <then>, <else> );

Here is an example

if( a > 10,
	( print "It is really large", flag = "red" ),
	( print "Nah, no problem", flag = "green" ) );

Note how the arguments have been bracketed to allow for more complex then and else clauses.

How about a loop? Well, the basic format is

while( <condition>, <statements> );

So to print multiplication tables, use something like

# Outer loop
i = 1;
while( i <= 12,

	# Inner loop
	j = 1,

	while( j < 7,

		print( i + " x " + j + " = " + ( i * j ) ),
		j = j + 1
	),

	i = i + 1
);

The manual below lists all the functions available in fdm.

Alphabetical function index

abs Absolute value
accumulate Accumulate a series
accuracy Set accuracy of calculations
acf Autocorrelation function
acos Arc cosine of argument
acosh Area hyperbolic cosine
acov Autocovariance function
aggregate Aggregate a series
and Logical and
arima Fit an ARIMA model to a series
asin Arcsine of argument
asinh Area hyperbolic sine
atan Arctan of argument
atanh Area hyperbolic tangent
average Average of a series
avgPerDayOfWeek Average per day of week of a series
avgPerMonth Average per month of a series
avgPerPeriod Average per period (e.g. month) of a series
bars Bar chart
beta Beta function
betaCdf Cumulative Beta probability distribution
betaPdf Beta probability distribution
betaQnt Beta probability distribution quantiles
calcStatus Set or retrieve the calculation status
call Call a user defined function
cauchyCdf Cumulative Cauchy probability distribution
cauchyPdf Cauchy probability distribution
cauchyQnt Cauchy probability distribution quantiles
ceil Ceiling
chiSqCdf Cumulative Chi square probability distribution
chiSqPdf Chi square probability distribution
chiSqQnt Chi square probability distribution quantiles
cols Number of columns in a matrix
complex Enter a complex number
corr Correlation coefficient
cos Cosine of angle
cosh Hyperbolic cosine
count Count observations in a series
covar Covariance
d Difference
dLn Natural logarithm difference
dLnPrev Natural logarithm difference
dPrev Difference to previous observation
dataCsv Load data from a CSV file
dataFred Download data from FRED
dataGet Retrieve a series of another frequency
dataPut Store a given series into the document
dataReplace Store a given series into the document, replacing existing data if present
dataSetDelete Delete a data set from local storage
dataSetList List locally stored data sets
dataSetLoad Load a previously saved data set
dataSetSave Save all data to a named data set
dataSetValue Extract a value from a data set
dataStatsSa Load data from STATSSA
dataValue Extract a value from a data set
dateIndex Frequency index for a given date
day Return the day of a date index
define Define a function
diff Differentiate symbolically
driveAdd Adjust a value using a driver series
driveMul Adjust a value using a driver series
dy Yearly difference
dyPrev Yearly difference for daily observations
e Euler’s number
empty Empty series
erf Error function
erfc Complementary error function
ewma Exponentially weighted moving average
ewmaLength Exponentially weighted moving average with a length argument
exp Exponentiate using Euler’s number e
expCdf Cumulative exponential probability distribution
expPdf Exponential probability distribution
expQnt Exponential probability distribution quantiles
fCdf Cumulative Snedecor’s F probability distribution
fPdf Snedecor’s F probability distribution
fQnt Quantiles of Snedecor’s F probability distribution
fact Factorial
first Value of first observation of a series
firstDate First observation’s date index
floor Floor
format Format settings
formatFix Fixed format
formatGen General format
formatReset Reset formatting settings
formatSci Scientific format
funcExists See if a function is defined
funcMin Report user defined function minimum
funcMinArg Report the argument at which a user defined function evaluated to a minimum
funcMinReset Reset the minimum of a user defined function
funcOptimFr Optimise a function using Fletcher-Reeves
funcOptimNm Optimise a function using Nelder-Mead
funcOptimPr Optimise a function using Polak-Ribière
funcOptimise Optimise a function
funcZoom Zoom in on a function
gamma Gamma function
gammaCdf Cumulative gamma probability distribution
gammaPdf Gamma probability distribution
gammaQnt Quantiles of the Gamma probability distribution
getProperty Retrieve a series property
grade Grade a value
gradient Calculate the (numerical) gradient of a function
hessian Calculate the (numerical) hessian of a function
hpFilter Hodrick-Prescott filter
if If-then-else function
incBeta Incomplete beta function
invGammaCdf Cumulative inverse gamma probability distribution
invGammaPdf Inverse gamma probability distribution
invGammaQnt Quantiles of the inverse gamma probability distribution
isCharacter Check if something is a character
isColumnVector Check if something is a column vector
isEmpty Check if a series is empty
isMatrix Check if something is a matrix
isMissing Check if something is missing
isNumber Check if something is a number
isRowVector Check if something is a row vector
isSeries Check if something is a series
isString Check if something is a string
isVector Check if something is a vector
kalmanFilter Kalman filter
kurt Sample kurtosis of a series
lag Lag a series
laplaceCdf Cumulative Laplace probability distribution
laplacePdf Laplace probability distribution
laplaceQnt Laplace probability distribution quantiles
last Value of last observation of a series
lastDate Last observation’s date index
left Return the left part of a string
length Length of a string
levyCdf Cumulative Levy probability distribution
levyPdf Levy probability distribution
levyQnt Quantiles of the Levy probability distribution
limit Limit a data series to a subset of its observations
ln Natural logarithm
log10 Log base 10
logNormCdf Cumulative log normal probability distribution
logNormPdf Log normal probability distribution
logNormQnt Log normal probability distribution quantiles
lowIncGamma Lower incomplete gamma function
lower Lower case string
matrix Create a matrix
matrix0 Return a matrix filled with zeroes
matrix1 Return a matrix filled with ones
matrixAsSeries Convert a matrix into a data series of observations
matrixC Return a column matrix filled with a given number
matrixCatColumns Concatenate the columns of two or more matrices
matrixCatRows Concatenate the rows of two or more matrices
matrixColumns Number of columns in a matrix
matrixDelColumns Remove a given set of columns from a matrix
matrixDelRows Remove a given set of rows from a matrix
matrixDiag Convert a vector into a diagonal matrix
matrixEig Calculate the eigenvalues of a square matrix
matrixEigBig Calculate some of the eigenvalues of a large square matrix
matrixEigVect Calculate the eigenvectors of a square matrix
matrixElDiv Element by element division of two matrices
matrixElMul Element by element multiplication of two matrices
matrixElPow Element by element raise to a power of two matrices
matrixGetColumns Extract a given set of columns from a matrix
matrixGetRows Extract a given set of rows from a matrix
matrixHess Decompose a matrix into Hessenberg form
matrixI Return the identity matrix
matrixKronProd Return the Kronecker product of two matrices
matrixObs Create an observation matrix
matrixQR Decompose a matrix into QR form
matrixR Return a row matrix filled with a given number
matrixRand Create a random matrix
matrixRows Number of rows in a matrix
matrixSolveCg Solve A.x = b for x using conjugate gradients
matrixSolveSd Solve A.x = b for x using steepest descent
matrixSum Sum of all matrix elements
matrixT Return the transposed of a matrix
matrixTrace Trace of a square matrix
matrixVec Vectorise a matrix
matrixVech Half-vectorise a matrix
matrixX Return a matrix filled with a given number
matrixXx Return the product of a transposed matrix with itself
max Maximum of a series
median Median of a series
merge Merge series
mid Return a portion of a string
min Minimum of a series
month Return the month of a date index
normCdf Cumulative normal probability distribution
normPdf Normal probability distribution
normQnt Normal probability distribution quantiles
not Logical not
observe Create a series with some observations
ols Ordinary least squares
omit Omit a given value from a series
omitZero Omit all zero valued observations from a series
or Logical or
p Percentage change
pPrev Percentage change in subsequent observations
pa Annualised percentage change
paPrev Annualised percentage change in subsequent observations
pacf Partial autocorrelation function
parent Evaluate in parent context
paretoCdf Cumulative Pareto probability distribution
paretoPdf Pareto probability distribution
paretoQnt Pareto probability distribution quantiles
periodogram Generate a periodogram or periodic trend for a series
pi Ratio between circumference and diameter of a circle
polyRoots Calculate roots of a polynomial
prev Lag a series of subsequent observations
print Print arguments to the log
py Percentage change per year
pyPrev Annual percentage change in subsequent observations
quarter Return the quarter of a date index
rand Draws a random number
randFast Quickly draws a random number
randSeed Seeds the random number generator
randType Select the type of random number generator
repeat Create a series by repeating a sequence
replace Replace a given value with another value in a series
replaceMissing Replace missing values in a series
replaceZero Replace zero values in a series
reportAdd Create a new report and store it into the document
reportDelete Delete a report
rezBeta Regularized incomplete beta function
rezGammaLo Regularized lower gamma function
rezGammaUp Regularized upper gamma function
right Return the right part of a string
round Round to nearest integer
rows Number of rows in a matrix
scenariosAdd Add scenarios to the document
scenariosDelete Delete scenarios
semester Return the semester of a date index
setProperty Set a series property
shockAdd Simulate and add a random shock
shockMul Simulate and multiply with a random shock
sign Signum
sin Sine of angle
sinh Hyperbolic sine
skew Sample skewness of a series
sma Simple moving average
sort Sort the observations of a series
sortDateIndex Sort the date indices of a series
sqrt Square root
statReport Generate a diagnostic statistics report for a series
std Sample standard deviation of a series
sum Sum of a series
tCdf Student’s t cumulative probability distribution
tPdf Student’s t probability distribution
tQnt Student’s t probability distribution quantiles
tan Tangent of angle
tanh Hyperbolic tangent
testMeans Test the equality of means hypothesis given two samples
testVariances Test if the variances from two samples are the same
today Date index of today
uniformCdf Cumulative uniform probability distribution
uniformPdf Uniform probability distribution
uniformQnt Uniform probability distribution quantiles
upIncGamma Upper incomplete gamma function
upper Upper case string
var Sample variance of a series
weibullCdf Weibull cumulative probability distribution
weibullPdf Weibull probability distribution
weibullQnt Weibull probability distribution quantiles
while While loop
xor Logical xor
year Return the year of a date index
z Standardise observations

Categorical function index

Control

if If-then-else function
while While loop

Data

dataCsv Load data from a CSV file
dataFred Download data from FRED
dataGet Retrieve a series of another frequency
dataPut Store a given series into the document
dataReplace Store a given series into the document, replacing existing data if present
dataSetDelete Delete a data set from local storage
dataSetList List locally stored data sets
dataSetLoad Load a previously saved data set
dataSetSave Save all data to a named data set
dataSetValue Extract a value from a data set
dataStatsSa Load data from STATSSA
dataValue Extract a value from a data set

Data series

accumulate Accumulate a series
acf Autocorrelation function
acov Autocovariance function
aggregate Aggregate a series
arima Fit an ARIMA model to a series
average Average of a series
avgPerDayOfWeek Average per day of week of a series
avgPerMonth Average per month of a series
avgPerPeriod Average per period (e.g. month) of a series
bars Bar chart
corr Correlation coefficient
count Count observations in a series
covar Covariance
d Difference
dLn Natural logarithm difference
dLnPrev Natural logarithm difference
dPrev Difference to previous observation
dy Yearly difference
dyPrev Yearly difference for daily observations
ewma Exponentially weighted moving average
ewmaLength Exponentially weighted moving average with a length argument
first Value of first observation of a series
firstDate First observation’s date index
getProperty Retrieve a series property
hpFilter Hodrick-Prescott filter
kalmanFilter Kalman filter
kurt Sample kurtosis of a series
lag Lag a series
last Value of last observation of a series
lastDate Last observation’s date index
limit Limit a data series to a subset of its observations
max Maximum of a series
median Median of a series
merge Merge series
min Minimum of a series
observe Create a series with some observations
ols Ordinary least squares
omit Omit a given value from a series
omitZero Omit all zero valued observations from a series
p Percentage change
pPrev Percentage change in subsequent observations
pa Annualised percentage change
paPrev Annualised percentage change in subsequent observations
pacf Partial autocorrelation function
periodogram Generate a periodogram or periodic trend for a series
prev Lag a series of subsequent observations
py Percentage change per year
pyPrev Annual percentage change in subsequent observations
repeat Create a series by repeating a sequence
replace Replace a given value with another value in a series
replaceMissing Replace missing values in a series
replaceZero Replace zero values in a series
setProperty Set a series property
skew Sample skewness of a series
sma Simple moving average
sort Sort the observations of a series
sortDateIndex Sort the date indices of a series
statReport Generate a diagnostic statistics report for a series
std Sample standard deviation of a series
sum Sum of a series
var Sample variance of a series

Date

dateIndex Frequency index for a given date
day Return the day of a date index
month Return the month of a date index
quarter Return the quarter of a date index
semester Return the semester of a date index
today Date index of today
year Return the year of a date index

Logical

and Logical and
isCharacter Check if something is a character
isColumnVector Check if something is a column vector
isEmpty Check if a series is empty
isMatrix Check if something is a matrix
isMissing Check if something is missing
isNumber Check if something is a number
isRowVector Check if something is a row vector
isSeries Check if something is a series
isString Check if something is a string
isVector Check if something is a vector
not Logical not
or Logical or
xor Logical xor

Mathematics

abs Absolute value
accuracy Set accuracy of calculations
acos Arc cosine of argument
acosh Area hyperbolic cosine
asin Arcsine of argument
asinh Area hyperbolic sine
atan Arctan of argument
atanh Area hyperbolic tangent
beta Beta function
ceil Ceiling
cos Cosine of angle
cosh Hyperbolic cosine
diff Differentiate symbolically
e Euler’s number
empty Empty series
erf Error function
erfc Complementary error function
exp Exponentiate using Euler’s number e
fact Factorial
floor Floor
gamma Gamma function
incBeta Incomplete beta function
ln Natural logarithm
log10 Log base 10
lowIncGamma Lower incomplete gamma function
pi Ratio between circumference and diameter of a circle
polyRoots Calculate roots of a polynomial
rand Draws a random number
randFast Quickly draws a random number
randSeed Seeds the random number generator
randType Select the type of random number generator
rezBeta Regularized incomplete beta function
rezGammaLo Regularized lower gamma function
rezGammaUp Regularized upper gamma function
round Round to nearest integer
sign Signum
sin Sine of angle
sinh Hyperbolic sine
sqrt Square root
tan Tangent of angle
tanh Hyperbolic tangent
upIncGamma Upper incomplete gamma function

Matrix

cols Number of columns in a matrix
matrix Create a matrix
matrix0 Return a matrix filled with zeroes
matrix1 Return a matrix filled with ones
matrixAsSeries Convert a matrix into a data series of observations
matrixC Return a column matrix filled with a given number
matrixCatColumns Concatenate the columns of two or more matrices
matrixCatRows Concatenate the rows of two or more matrices
matrixColumns Number of columns in a matrix
matrixDelColumns Remove a given set of columns from a matrix
matrixDelRows Remove a given set of rows from a matrix
matrixDiag Convert a vector into a diagonal matrix
matrixEig Calculate the eigenvalues of a square matrix
matrixEigBig Calculate some of the eigenvalues of a large square matrix
matrixEigVect Calculate the eigenvectors of a square matrix
matrixElDiv Element by element division of two matrices
matrixElMul Element by element multiplication of two matrices
matrixElPow Element by element raise to a power of two matrices
matrixGetColumns Extract a given set of columns from a matrix
matrixGetRows Extract a given set of rows from a matrix
matrixHess Decompose a matrix into Hessenberg form
matrixI Return the identity matrix
matrixKronProd Return the Kronecker product of two matrices
matrixObs Create an observation matrix
matrixQR Decompose a matrix into QR form
matrixR Return a row matrix filled with a given number
matrixRand Create a random matrix
matrixRows Number of rows in a matrix
matrixSolveCg Solve A.x = b for x using conjugate gradients
matrixSolveSd Solve A.x = b for x using steepest descent
matrixSum Sum of all matrix elements
matrixT Return the transposed of a matrix
matrixTrace Trace of a square matrix
matrixVec Vectorise a matrix
matrixVech Half-vectorise a matrix
matrixX Return a matrix filled with a given number
matrixXx Return the product of a transposed matrix with itself
rows Number of rows in a matrix

Other

grade Grade a value

Output

format Format settings
formatFix Fixed format
formatGen General format
formatReset Reset formatting settings
formatSci Scientific format
print Print arguments to the log

Report

reportAdd Create a new report and store it into the document
reportDelete Delete a report

Simulate

driveAdd Adjust a value using a driver series
driveMul Adjust a value using a driver series
scenariosAdd Add scenarios to the document
scenariosDelete Delete scenarios
shockAdd Simulate and add a random shock
shockMul Simulate and multiply with a random shock

Statistics

betaCdf Cumulative Beta probability distribution
betaPdf Beta probability distribution
betaQnt Beta probability distribution quantiles
cauchyCdf Cumulative Cauchy probability distribution
cauchyPdf Cauchy probability distribution
cauchyQnt Cauchy probability distribution quantiles
chiSqCdf Cumulative Chi square probability distribution
chiSqPdf Chi square probability distribution
chiSqQnt Chi square probability distribution quantiles
expCdf Cumulative exponential probability distribution
expPdf Exponential probability distribution
expQnt Exponential probability distribution quantiles
fCdf Cumulative Snedecor’s F probability distribution
fPdf Snedecor’s F probability distribution
fQnt Quantiles of Snedecor’s F probability distribution
gammaCdf Cumulative gamma probability distribution
gammaPdf Gamma probability distribution
gammaQnt Quantiles of the Gamma probability distribution
invGammaCdf Cumulative inverse gamma probability distribution
invGammaPdf Inverse gamma probability distribution
invGammaQnt Quantiles of the inverse gamma probability distribution
laplaceCdf Cumulative Laplace probability distribution
laplacePdf Laplace probability distribution
laplaceQnt Laplace probability distribution quantiles
levyCdf Cumulative Levy probability distribution
levyPdf Levy probability distribution
levyQnt Quantiles of the Levy probability distribution
logNormCdf Cumulative log normal probability distribution
logNormPdf Log normal probability distribution
logNormQnt Log normal probability distribution quantiles
normCdf Cumulative normal probability distribution
normPdf Normal probability distribution
normQnt Normal probability distribution quantiles
paretoCdf Cumulative Pareto probability distribution
paretoPdf Pareto probability distribution
paretoQnt Pareto probability distribution quantiles
tCdf Student’s t cumulative probability distribution
tPdf Student’s t probability distribution
tQnt Student’s t probability distribution quantiles
testMeans Test the equality of means hypothesis given two samples
testVariances Test if the variances from two samples are the same
uniformCdf Cumulative uniform probability distribution
uniformPdf Uniform probability distribution
uniformQnt Uniform probability distribution quantiles
weibullCdf Weibull cumulative probability distribution
weibullPdf Weibull probability distribution
weibullQnt Weibull probability distribution quantiles
z Standardise observations

String

left Return the left part of a string
length Length of a string
lower Lower case string
mid Return a portion of a string
right Return the right part of a string
upper Upper case string

User functions

calcStatus Set or retrieve the calculation status
call Call a user defined function
define Define a function
funcExists See if a function is defined
funcMin Report user defined function minimum
funcMinArg Report the argument at which a user defined function evaluated to a minimum
funcMinReset Reset the minimum of a user defined function
funcOptimFr Optimise a function using Fletcher-Reeves
funcOptimNm Optimise a function using Nelder-Mead
funcOptimPr Optimise a function using Polak-Ribière
funcOptimise Optimise a function
funcZoom Zoom in on a function
gradient Calculate the (numerical) gradient of a function
hessian Calculate the (numerical) hessian of a function
parent Evaluate in parent context

Functions

abs

Absolute value

Category: Mathematics

Notes

Calculates the absolute value of the argument.

Arguments

This function takes a single argument, which is either a number or a series.

Example usage

print( abs( -1 ) );        # Print 1
print( abs( X ) );         # Element by element abs of series X

accumulate

Accumulate a series

Category: Data series

Notes

Calculates and returns the series accumulation. The accumulation represents the way in which the series accumulates, e.g. change or percentage change.

The behaviour of this function for daily frequencies is to use subsequent observations rather than keeping to strict, fixed distances in time. Thus the percentage change accumulation will calculate percentage change from Friday to the subsequent observation on Monday if Saturday and Sunday are missing, as is common in daily data.

Arguments

This function takes two arguments:

The series to accumulate.
(Optional) The accumulation to return, one of
- "d" or "change"
  Calculate the change or
```
y(t) - y(t-1)
```
  The result is the same as
```
d( X )
```
  or for daily series
```
dPrev( X )
```
- "dy", "changeyear" or "annualchange"
  Calculate the annual change, e.g. for monthly, calculate
```
y(t) - y(t-12)
```
  The result is the same as
```
dy( X )
```
  or for daily series
```
dyPrev( X )
```
- "%", "p", "pct", "percent", "%change", "percentchange" or "percentagechange"
  Calculate the percentage change i.e.
```
y(t) / y(t-1) - 1
```
  The result is the same as
```
p( X )
```
  or for daily series
```
pPrev( X )
```
- "py", "percentyear", "%changeyear", "%yoy", "percentchangeyear" or "percentagechangeyear"
  Calculate the annual or year on year (yoy) percentage change, e.g. for monthly, calculate
```
y(t) / y(t-12) - 1
```
  The result is the same as
```
py( X )
```
  or for daily series
```
pyPrev( X )
```
- "pa", "%an", "%ann", "percentannualised", "%changeannualised", "percentchangeannualised", "percentannualized", "%changeannualized", "percentchangeannualized" or "percentagechangeannualized"
  Calculate the annualised percentage change, e.g. for monthly data, calculate
```
( y(t) / y(t-1) ^ 12 ) - 1
```
  The result is the same as
```
pa( X )
```
  or for daily series
```
paPrev( X )
```

Note that the second argument is optional, and if not provided 4 is assumed (annual percentage change). The frequency is used to determine the length to use when calculating annual or annualised accumulations.

Also note that this second argument can be either a value or a string. The string is not case sensitive, i.e. either "change" or "Change" will select option 1.

Example usage

accumulate( X, 1 ); # Same as d( X ),  calculate change
accumulate( X, 2 ); # Same as dy( X ), calculate annual change
accumulate( X, 3 ); # Same as p( X ),  calculate percentage change
accumulate( X, 4 ); # Same as py( X ), calculate annual percentage (yoy) change
accumulate( X, 5 ); # Same as pa( X ), calculate annualised percentage change

accuracy

Set accuracy of calculations

Category: Mathematics

Notes

Specifies how many significant digits should be used when performing calculations. Basic algebraic operations such as plus, minus, multiply and divide will be accurate to roughly this many significant digits but more complex calculations, although performed with this set accuracy, will probably not be accurate to this many digits.

The default accuracy setting is 50 digits. This is much higher than normal machine precision, which causes calculations to take a lot longer to be performed.

Note that small errors accumulate, sometimes rapidly, and a given accuracy does not mean that a calculation will be precise to the given significant digit.

Arguments

This function takes a single argument, namely a value between 1 and 40000. The argument is then used to set the accuracy of all subsequent calculations.

Example usage

accuracy( 100 ); # Set accuracy to 100 significant digits
print( pi() );   # pi will now be calculated to 100 significant digits but
                 # it may not be accurate to 100 digits ...

acf

Autocorrelation function

Category: Data series

Notes

Calcualtes and returns the autocorrelation function as a series.

The first observation, at index 0, will be 1. The next observation, at index 1, will be the first order autocorrelation and so on. Note that here the divisor will be n and not n - k.

Arguments

This function takes two arguments, namely the series for which to calculate the autocorrelation function and secondly the maximum order to calculate.

Series
The series for which to calculate autocorrelations.
(Optional) order
The maximum order autocorrelation to calculate. The returned series will typically have 1 more value than this number, with the first value being 1 for the zero order autocorrelation. It may have fewer observations if it was unable to calculate the autocorrelation at a given order.

Example usage

print( acf( X ) );

acos

Arc cosine of argument

Category: Mathematics

Notes

Calculates, in radians, the arc cosine or inverse cosine of the argument.

Arguments

This function takes a single argument, which is either a number or a series.

Example usage

print( acos( 0.5 ) );

acosh

Area hyperbolic cosine

Category: Mathematics

Notes

Returns the hyperbolic cosine angle that corresponds with given value.

Arguments

This function takes a single series or number as argument.

Example usage

print( acosh( 1 / 2 ) );
Y = acosh( X ); # Return new series with acosh of X as observations

acov

Autocovariance function

Category: Data series

Notes

Calcualtes and returns the autocovariance function as a series.

The first observation, at index 0, will be the variance. The next observation, at index 1, will be the first order autocovariance and so on. Note that here the divisor will be n and not n - k.

Arguments

This function takes two arguments, namely the series for which to calculate the autocovariance function and secondly the maximum order to calculate.

Series
The series for which to calculate autocovariances.
(Optional) order
The maximum order autocovariance to calculate. The returned series will typically have 1 more value than this number, with the first value being the variance added for the zero order autocovariance. It may have fewer observations if it was unable to calculate at a given order. If no value is given the default will be used, which depends on the frequency.

Example usage

print( acov( X ) );

aggregate

Aggregate a series

Category: Data series

Notes

Aggregates a series to annual observations. Aggregating to an annual figure is accomplished by, e.g. calculating the sum of all the monthly observations in a given year.

The returned series will use the year as index, so that e.g.

Y = aggregate( X ); Base = Y[ 2010 ];

will set Base equal to the average of X in the year 2010. If the current frequency is monthly for example, then 2010 as index refers to a nonsensical year 167 month 7, so after aggregating these indices should be treated as years and not as months.

Also note that years may not be "full". If a monthly series, for example has only values in January, February and March, then the "sum" aggregation will yield the sum of only these 3 months' observations as an aggregate value. If a monthly series with for example a single observation in January is aggregated, then the aggregate function will return that observation for the year figure as it is simultaneously the average, sum, minimum, maximum and last value for the year. If one of the "full" aggregation types are selected, then the aggregate function will not calculate an aggregate for a year unless that year is full. Thus it will only aggregate a monthly series for years where there are 12 observations available or a quarterly series where there are 4 observations available.

Arguments

This function takes two arguments:

The series to aggregate.
(Optional) The aggregation type, which is one of
- "avg" or "average"
  Calculate the average per year.
- "sum", "tot" or "total"
  Calculate the sum per year.
- "min" or "minimum"
  Calculate the minimum per year.
- "max" or "maximum"
  Calculate the maximum per year.
- "last" or "close"
  Calculate the last or closing value per year.
Note that the aggregations above may not use a full year. Thus if only 3 months of a year is available, the "sum" aggregate will return the sum of only those 3 observations as aggregate.

This may not be what is required and there are times when the aggregation should only work on "full" years, meaning e.g. all of the months in the year must have values before the aggregation is applied. For this reason the options below are provided. Note that these mirror the options given earlier but only return an aggregate for the year if the year is full or complete.
- "avgfull" or "averagefull"
  Calculate the average per "full" year.
- "sumfull", "totfull" or "totalfull"
  Calculate the sum per "full" year.
- "minfull" or "minimumfull"
  Calculate the minimum per "full" year.
- "maxfull" or "maximumfull"
  Calculate the maximum per "full" year.
- "lastfull" or "closefull"
  Calculate the last or closing value per "full" year.

Note that the second argument is optional, and if not provided 1 is assumed (average per year). Also note that the second argument can be a number or a string as indicated. The string is not case sensitive, i.e. either "AVG" or "Avg" will work.

Example usage

aggregate( X,  1 ); # Average of observations per year
aggregate( X,  2 ); # Sum of observations per year
aggregate( X,  3 ); # Minimum of observations per year
aggregate( X,  4 ); # Maximum of observations per year
aggregate( X,  5 ); # Last observation per year
aggregate( X,  6 ); # Average of observations per 'full' year
aggregate( X,  7 ); # Sum of observations per 'full' year
aggregate( X,  8 ); # Minimum of observations per 'full' year
aggregate( X,  9 ); # Maximum of observations per 'full' year
aggregate( X, 10 ); # Last observation per 'full' year

and

Logical and

Category: Logical

Notes

Evaluates the arguments one by one and, if any number is found that is either missing or zero, will stop and return 0. If all arguments have been evaluated and no missing or zero values were found, then 1 is returned.

Note that this means that not all arguments will be evaluated. The arguments are only evaluated up to the first zero or missing value.

Arguments

This function takes two or more arguments, all of which must reduce to a number.

Zero or missing values are taken to be FALSE and anything else is taken to be TRUE. This will "and" all the results, but exits early if possible.

Example usage

print( and( 1, 2, 3 ) );

arima

Fit an ARIMA model to a series

Category: Data series

Notes

This can be used to fit an ARIMA model to a time series.

Arguments

The ARIMA model takes some series y as input and then, based on the paramters requested, will difference that series into z and estimate the actual model on the differenced series.

Afterwards the differenced series will be forecast and the forecast values will be dedifferenced back to obtain a forecast for the original y series. This series can further be backtransformed, e.g. delogged, based on arguments supplied to the function, to obtain projected values in the original levels.

This function takes the following arguments:

(Optional) Model name
If the first argument is a string, then this is assumed to be the model name and the results of the estimation will be saved using that name. If the name used is, for example, "arima", as seen below
```
arima( "arima", y, 1, x1, x2 );    # Will store results to arima
```
then the root mean square error can for example be obtained using
```
rmse = dataSetValue( "arima", "nRmse" );
```
To estimate the model and not store back any results, simply omit this first argument, for example
```
arima( y, 1, x1, x2, x3 );
```
The model name must be a valid name, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign, a minus sign and a number sign.
When a model is estimated it generates a lot of output in the log. To silence this output, prefix the name with a minus sign, for example
```
arima( "-arima", y, 1, x1, x2 );
```
If a name is provided the results are normally only stored in memory, and not saved to disk as well. Thus the model's results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the model name, prefix the name with a plus sign, e.g.
```
arima( "+arima", y, 1, x1, x2 );
```
If the model name is prefixed with a number sign e.g.
```
arima( "#arima", y, 1, x1, x2 );
```
then a new report with the name "arima" (excluding the number sign) will be created and the results will be stored into that report. The table summary will contain a formatted overview of the model and the table itself will display a suitable projection. The model can for example be fitted to the log levels and the projection can be transformed back into levels as will be shown later. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
command to reduce clutter.
If results are stored to a model using a model name, the following arguments are available keys to extract results with later:
- Matrices
  - obsMat
    The observation matrix used to calculate the initial OLS estimates and also used to align the observations correctly.
  - zMat
    A column vector containing the differenced values used in the estimation. This is basically the LHS of the equation.
  - xMat
    A matrix containing the RHS of the equation used to calculate the initial OLS parameter estimates. This will have columns for autoregressive terms but will not contain any columns for moving average terms.
  - coefMat
    This contains the estimated coefficients. It has rows for the ARIMAX terms first, followed by the AR and then the seasonal AR coefficients. Then the MA and finally the seasonal MA coefficients follow. The first column contains the estimated coefficient, then the estimated coefficient standard error, z value and probability value. These are estimated from the hessian and is a bit blurry given the non-linear nature of the model.
  - rootMat
    This has a row for each of the roots of the AR, seasonal AR, MA and seasonal MA polynomials. The columns are firstly the real and imaginary parts of the root, then the root's modulus, frequency and period after that.
  - hess
    This contains the estimated hessian if available.
  - hessI
    This contains the inverted hessian matrix.
  - parHist
    This matrix has a row for the SSE and then a row for each parameter estimated. The first column is the initial parameters, calculated via OLS for the ARIMAX and AR terms and set to zero for the MA terms. Thereafter follows a column for each of the optimisation algorithms used. Thus if the parameters were estimated by a Nelder-Mead simplex followed by Newton-Raphson, this will contain a column for each of these methods with the resulting SSE and parameter estimates of each method.
- Series
  - y
    This contains a series of y values. These are the undifferenced values received as initial input.
  - z
    This series contains the differenced values used in the estimation. If the model has any ARIMAX terms then this could potentially have a lot less observations than the y series as only observations where there are values for all the ARIMAX terms will be retained.
  - zhat
    This contains the in-sample fitted values. These are fitted to the differenced series.
  - e
    This series contains the in-sample residuals.
  - ifor
    This series contains a 0 for each out-of-sample forecast and can be used when reporting to shade the forecast portion of the report.
  - zfor
    This contains forecasts for the differenced series. In sample it contains the actual differenced values and out-of-sample it contains the forecasts.
  - efor
    This contains the residuals used to calculate the forecasts with. In sample it will contain the calculated residuals and out-of-sample it will contain zeroes.
  - yfor
    This series contains the undifferenced forecasts. In sample it will have the actual values but out-of-sample it will be the forecast values.
  - projected
    This series contains projected values. When fitting an ARIMA model, you can requested that the values be transformed afterwards, e.g. to delog a logarithmic series, and then this series will contain the delog values. To give an example, suppose you fit a model to ln GDP, then the forecast value will contain forecasts of ln GDP, but you can exp these values to get the GDP forecasts. This might look something like the following
```
lgdp = ln( GDP )
gdp_fore = arima( lgdp, 1, matrix( 1, 3, 1, 1, 1 ), 10, "-exp" );
```
    Now gdp_fore will contain the delogged GDP values because of the "-exp" parameter that was supplied. The yfor series will contain forecasts of the logged values and this series (projected) will contain the delogged forecasts.
- Numbers
  - p
    The ARIMA p parameter or number of AR terms.
  - d
    The ARIMA d parameter or degree of differencing.
  - q
    The ARIMA p parameter or number of MA terms.
  - (capital) P
    The ARIMA P parameter or number of seasonal AR terms.
  - (capital) D
    The ARIMA D parameter or degree of seasonal differencing.
  - (capital) Q
    The ARIMA p parameter or number of seasonal MA terms.
  - s
    The ARIMA s parameter or the number of seasons in a year.
  - regular
    This indicates if the frequency is regular or not (1 or 0). A regular frequency requires a fixed distance between observations such as monthly or quarterly. There can not be gaps here, or if there are gaps in the observations, then it generates missing values. This if 2010Q1 and 2010Q3 are given, a missing value is generated for 2010Q2. If a series is not regular on the other hand, then gaps do not give rise to missing values. A daily series may have many gaps due to weekends and holidays but these should not generate missing values. An observation on a Friday followed by one on a Monday does not mean the Saturday and Sunday are missing, simply that is was a weekend. This if this series is differenced, the Friday observation will be subtracted from the Monday and the gap in the date will be ignored.
  - nObsY
    The number of observations in the original, undifferenced series.
  - nObs
    The number of observations in the differenced series that was used in the estimation.
  - nPar
    The number of parameters that was estimated.
  - nDf1
    The first degrees of freedom which is the number of non-constant coefficients.
  - nDf2
    The second degrees of freedom, which is the number of observations used in the estimation less the number of parameters estimated.
  - nSumE
    The sum of in-sample residuals.
  - nSumE2
    The sum of squared in-sample residuals.
  - nSumE3
    The sum of cubed in-sample residuals.
  - nSumE4
    The sum of in-sample residuals raised to the fourth power.
  - nTotVar
    The total variance in the differenced (z) values.
  - nExpVar
    The variance explained in the differenced (z) values.
  - nUnexpVar
    The unexplained variance or variance in the in-sample residuals. These variances are used to calculate an R Square and adjusted R Square value for the model but it must be used with a grain of salt given the non-linear nature of the model.
  - nZAvg
    The average of the differenced values.
  - nMse
    The mean square error.
  - nRmse
    The root mean square error
  - nRSq
    The R Square value calculated from the total and unexplained variance. Note that this must be used with care given the non-linear nature of the model.
  - nRSqAdj
    The adjusted R square value. This also needs to be interpreted with care given the non-linear nature of the model.
  - nF
    The model's F value, also calculated from the total and unexplained variance and to be used with care.
  - nFProb
    The F value's probability.
  - nDW
    The Durbin-Watson statistic measuring residual autocorrelation.
  - nLLHood
    The log likelihood.
  - nAic
    The Akaike information criteria.
  - nAicc
    The corrected AIC.
  - nBic
    The Bayesian or Schwarz information criteria.
  - nArch
    The ARCH effects test statistic.
  - nArchProb
    The probability of accepting the null of no ARCH effects (low values are bad).
  - nJarqueBera
    The Jarque-Bera test statistic for normal (guassian) residuals.
  - nJarqueBeraProb
    The probability of rejecting the null of gaussian residuals (low values are bad).
  - nSkew
    The residual skewness.
  - nKurt
    The residual kurtosis, 3 indicates "normal" kurtosis.
(Optional) Series
Any number of series to include as independent variables in the model. To include a constant also provide a value such as 1. So to fit a model using x1 and x2 and a constant, write something like this.
```
arima( y, 1, x1, x2 );
```
(Optional) ARIMA specification
This is provided as a matrix with up to 7 entries for each of the ARIMA( p, d, q )( P, D, Q )[ s ] parameters, e.g.
```
arima( y, 1, x1, matrix( 1, 7, p, d, q, P, D, Q, S ) );
```
If this is omitted, then an ARIMA( 1, 1, 1 ) model will be fitted to the data.
(Optional) horizon
The forecast horizon. The default is 20. The model will try to produce this many forecasts. If this parameter is given then a model specification must be provided.
(Optional) transformation
This parameter is a string that starts with a minus (-) and then gives the function to use to transform the forecast values once done. Think of the minus as an inversion sign. Thus if the model is fitted to log levels, you can request the delogged levels by adding a "-exp" argument like this
```
arima( y, 1, x1, x2, matrix( 1, 3, 1, 1, 1 ), 20, "-exp" );
```
The function name can be a built in or a user defined one, as long as it takes a single argument and can transform the final forecast series into the required projected series.
(Optional) Algorithms
This parameter specifies the algorithms to use to fit the model. It is a string with a letter for each algorithm to use, where valid letters are as follows
- S
  Nelder-Mead downhill simplex.
- F
  Conjugate gradients Fletcher-Reeves.
- P
  Conjugate gradients Polak-Ribière.
- N
  Newton-Raphson.
The default is "SP" meaning the downhill simplex algorithm will be used first and then followed by the Polak-Ribière algorithm. If you e.g. give "SSSS" then the downhill simplex will be applied four times in succession. If the model does not converge, try to use "SN" or "SSP" also for example.
(Optional) algorithm parameters
The final argument is an optional matrix with a column with parameters for each of the algorithms used. These columns are explained below based on the algorithm for which they were given.
- S
  Nelder-Mead downhill simplex. The first row contains the maximum number of iterations, the second the shrink step tolerance and the third the maximum difference tolerance. If any rows are omitted then the default value will be used for that parameter.
- F
  Conjugate gradients Fletcher-Reeves. The first row is the maximum number of iterations. This is followed by the maximum line search iterations and then the tolerance to use when calculating the gradient. Then the fourth row contains the tolerance used to calculate the hessian followed by the tolerance to use when line searching. Finally, in the sixth row, is the tolerance used to test for convergence. If any of these rows are omitted then the default values will be used.
- P
  Conjugate gradients Polak-Ribière. The algorithm parameters are the same as for the Fletcher-Reeves algorithm.
- N
  Newton-Raphson. Here the algorithm parameters are the maximum number of iterations, gradient and hessian tolerance and finally, in the fourth row, the tolerance used to test for convergence.

This returns a series of forecasts or, if a transformation was given the transformed forecasts. This series will have actual values in-sample and the forecast values out-of-sample.

Example usage

print( "Examples - arima" );

USGDP = dataFred( "GDPCA" );
arima( dLn( USGDP ) ); # ARIMA( 1, 1, 1 )( 0, 0, 0 ) model

asin

Arcsine of argument

Category: Mathematics

Notes

Calculates, in radians, the arc sine or inverse sine of the argument.

Arguments

This function takes a single argument, either a number or a series.

Example usage

print( asin( 0.5 ) );

asinh

Area hyperbolic sine

Category: Mathematics

Notes

Returns the hyperbolic sine angle that corresponds with given value.

Arguments

This function takes a single series or number as argument.

Example usage

print( asinh( 1 / 2 ) );
Y = asinh( X ); # Return new series with asinh of X as observations

atan

Arctan of argument

Category: Mathematics

Notes

Calculates, in radians, the arc tangent or inverse tan of the argument.

Arguments

This function takes a single argument, either a number or a series.

Example usage

print( atan( 0.5 ) );

atanh

Area hyperbolic tangent

Category: Mathematics

Notes

Returns the hyperbolic tangent angle that corresponds with given value.

Arguments

This function takes a single series or number as argument.

Example usage

print( atanh( 1 / 2 ) );
Y = atanh( X ); # Return new series with atanh of X as observations

average

Average of a series

Category: Data series

Notes

Calculates and returns the average of all the observations in a series.

Arguments

This takes a single argument, namely the series to average.

To calculate the average of a series between say 2010 and 2015, combine this with the limit function, for example

A = average( limit( dateIndex( 2010, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Example usage

# Calculate the average of X
average( X );

avgPerDayOfWeek

Average per day of week of a series

Category: Data series

Notes

Calculates and returns a series containing the average per day of week of the observations made for a series with daily frequency.

For lower frequency series, this will return an empty series. For daily series, it will return a new series with observation indexed 1 for the average observation value for Sunday, 2 for Monday and so on.

Note that if no observations were made on a Sunday for example, then the returned series will not have an observation at index 1. Thus missing values are used to indicate that no observations were available to calculate averages with.

Arguments

This function takes a single argument, namely the series for which the average per day of the week is to be calculated.

Example usage

APDOW = avgPerDayOfWeek( X ); # Calculate average per day of week

avgPerMonth

Average per month of a series

Category: Data series

Notes

Calculates and returns a series containing the average per month of observations made during a given month.

This is related to the avgPerPeriod function, but added especially to enable calculating the monthly averages of daily data. A daily series will return the average per day of the month if the avgPerPeriod function is used and the average per month if the avgPerMonth function is used. The returned series is indexed from 1 to 12 and the first observation, at index 1, is the average of all observations seen in January and so on.

Note that if no observations were made in February for example, then the returned series will not have an observation at index 2. Thus missing values are used to indicate that no observations were available to calculate averages with. This is especially relevant if lower frequency series are used. If for example a series with a frequency lower than 12, e.g. a quarterly series, is passed in as argument to this function then the returned series will contain at most 4 observations. Likewise the average per month of an annual series will return a single observation.

Arguments

This function takes a single argument, namely the series for which the average per month is to be calculated.

This can be combined with the limit function to calculate the average per period for a specific range. Thus to calcualte the average per month between 2000 and 2015 for example, use

avgPerMonth( limit( dateIndex( 2000, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Example usage

APM = avgPerMonth( X ); # Calculate average per month

avgPerPeriod

Average per period (e.g. month) of a series

Category: Data series

Notes

Calculates and returns a series containing the average per period.

A monthly series has for example 12 periods and a quarterly series 4 and this will return the average of observations in January (for monthly) or for Q1 (for quarterly series) and so on. The average for say January will be in the returned series' first value which can be indexed with 1, 2 for February and so on. Thus

APP = avgPerPeriod( X ); AvgJan = APP[ 1 ];

can be used to calculate and extract this first value. Note that the index no longer refers to a specific month or quarter but to the first (or second or so on) period's average.

Daily series return the average per day. The returned series contains 31 observations, with the index equivalent to the day of month on which the observation was made. Thus using an index of 1 on the returned series gives the average of all observations made on the first day of the month.

Arguments

This function takes a single argument, namely the series which average per period is to be calculated.

This can be combined with the limit function to calculate the average per period for a specific range. Thus to calculate the average per period between 2000 and 2015 for example, use

avgPerPeriod( limit( dateIndex( 2000, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Example usage

APP = avgPerPeriod( X ); # Calculate average per period

bars

Bar chart

Category: Data series

Notes

Prints a simple bar chart to the log.

Arguments

This function usually takes a single argument which is a series. It will then print a simple bar chart of it to the calculation log. This is especially useful when used in conjunction with the autocorrelation and partial autocorrelation functions (acf and pacf). There is an optional formatting argument that can be used to format the x-axis differently as discussed below.

Series
The series for which to generate a bar chart.
(Optional) format
This must evaluate to a number. If it evaluates to 0 then the index value of the observations will be used on the x-axis. This makes sense when plotting the autocorrelation or partial autocorrelation, but not when plotting a regular time series. Then use 1 here and the labels printed on the x-axis will be the formatted dates of each observation. If this is negative it will generate an error.

This returns the y-axis step size used if it was able to draw the bar chart. If unable to draw it, e.g. due to too few or too many observations, this will return a missing value.

Example usage

print( bars( X ) );
print( bars( X, 1 ) );

beta

Beta function

Category: Mathematics

Notes

Calculates and returns the beta function.

Arguments

This function takes two arguments, a and b, both of which may be either a number or a series.

Example usage

print( beta( 0.1, 0.2 ) );
print( gamma( 0.1 ) * gamma( 0.2 ) / gamma( 0.1 + 0.2 ) ); # Same as beta( 0.1, 0.2 )
print( beta( 1, X ) );

betaCdf

Cumulative Beta probability distribution

Category: Statistics

Notes

Returns the cumulative beta probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes three arguments:

x
The value at which to calculate the cdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) shape parameter of the distribution.

Example usage

print( betaCdf( 0.5, 1, 1 ) );
print( betaCdf( 0.99, 1, 1 ) );

betaPdf

Beta probability distribution

Category: Statistics

Notes

Returns the beta probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) shape parameter of the distribution.

Example usage

print( betaPdf( 0.2,  1, 2 ) );
print( betaPdf( 0.99, 1, 1 ) );

betaQnt

Beta probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the beta probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p. Therefore it is also called the inverse cumulative distribution function.

Arguments

This function takes three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) shape parameter of the distribution.

Example usage

print( betaQnt( 0.05, 1, 1 ) );
print( betaQnt( 0.01, 1, 10 ) );

calcStatus

Set or retrieve the calculation status

Category: User functions

Notes

This can be used to set the calculation status message that is displayed while a calculation is underway. It can also retrieve the current status message.

Arguments

This function takes one optional argument which is the new status message to display. This must evaluate to a string. If no arguments are given, then it simply returns the current status message without changing it.

Status message (Optional)
The new status message to display. If omitted, will not change the current status message.

This returns the current status message.

Example usage

msg = calcStatus();
calcStatus( "New status" );

call

Call a user defined function

Category: User functions

Notes

This calls a previously defined function and returns the result. The first argument is the name of the function and the remaining ones are the function arguments.

Arguments

This function takes the following arguments:

The name of the user defined function to call - this must evaluate to a string and is case sensitive.
The name of the variable - this is also case sensitive.
First argument to the function.
Second argument to the function.
...

This will run or execute the function and return the result.

Example usage

x = call( "add", 1, 2 );  # Add two numbers

cauchyCdf

Cumulative Cauchy probability distribution

Category: Statistics

Notes

Returns the cumulative Cauchy probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes up to three arguments:

x
The value at which to calculate the cdf.
(Optional) x0
The location parameter of the distribution; if omitted use zero.
(Optional) gamma
The scale parameter of the distribution; if omitted use one.

Example usage

print( cauchyCdf( 1.95 ) );
print( cauchyCdf( 110, 100, 10 ) );

cauchyPdf

Cauchy probability distribution

Category: Statistics

Notes

Returns the Cauchy probability distribution function (pdf).

Arguments

This function takes up to three arguments:

x
The value at which to calculate the pdf.
(Optional) x0
The location parameter of the distribution; if omitted use zero.
(Optional) gamma
The scale parameter of the distribution; if omitted use one.

Example usage

print( cauchyPdf( 2 ) );
print( cauchyPdf( 110, 100, 10 ) );

cauchyQnt

Cauchy probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the Cauchy probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p. Therefore it is also called the inverse cumulative distribution function.

Arguments

This takes up to three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
(Optional) x0
The mean of the distribution; if omitted use zero.
(Optional) gamma
The standard error of the distribution; if omitted use one.

Example usage

print( cauchyQnt( 0.05 ) );
print( cauchyQnt( 0.01, 100, 10 ) );

ceil

Ceiling

Category: Mathematics

Notes

Calculates the ceiling of the argument.

The ceiling is the smallest integer larger than or equal to the argument. Thus the ceiling of 0.1 is 1 and of -0.1 is 0 for example.

Arguments

This function takes a single value or series as argument.

Example usage

print( ceil(  0.1 ) ); # Will print  1
print( ceil(  0.9 ) ); # Will print  1
print( ceil(  1.0 ) ); # Will print  1
print( ceil( -0.1 ) ); # Will print  0
print( ceil( -0.9 ) ); # Will print  0
print( ceil( -1.0 ) ); # Will print -1

chiSqCdf

Cumulative Chi square probability distribution

Category: Statistics

Notes

Returns the cumulative chi square probability distribution function (cdf).

For a value x this returns the probability that a random variable drawn from this distribution will be less than x.

Arguments

This function takes up to two arguments:

x
The (non-negative) value at which to calculate the cdf.
(Optional) k
The (positive integer) degrees of freedom, use 1 if omitted.

Example usage

print( chiSqCdf( 2 ) );
print( chiSqCdf( 2, 1 ) );
print( chiSqCdf( 2, 5 ) );

chiSqPdf

Chi square probability distribution

Category: Statistics

Notes

Returns the chi square probability distribution function (pdf).

Arguments

This function takes up to two arguments:

x
The (non-negative) value at which to calculate the pdf.
(Optional) k
The (positive integer) degrees of freedom, use 1 if omitted.

Example usage

print( chiSqPdf( 2 ) );
print( chiSqPdf( 2, 1 ) );
print( chiSqPdf( 2, 5 ) );

chiSqQnt

Chi square probability distribution quantiles

Category: Statistics

Notes

Returns the quantiles of the chi square probability distribution.

Given a desired probability p this returns x so that CDF( x ) = p. Therefore it is also sometimes called the inverse cumulative distribution function.

Arguments

This function takes up to two arguments:

p
The quantile, between 0 and 1, to return.
(Optional) k
The positive integer degrees of freedom; use 1 if omitted.

Example usage

print( chiSqQnt( 0.01 ) );
print( chiSqQnt( 0.05, 1 ) );
print( chiSqQnt( 0.10, 5 ) );

cols

Number of columns in a matrix

Category: Matrix

Notes

Returns the number of columns in a matrix. This is equivalent to the longhand matrixColumns function.

Arguments

This function takes a single argument, the matrix for which to return the number of columns.

Example usage

print( cols( A ) );

corr

Correlation coefficient

Category: Data series

Notes

Calcualtes and returns Pearson's correlation coefficient between two series.

Only observations that coincide in terms of frequency index are used in the calculation. If either series exhibit no variance, or if there is no overlap between the two series, then a missing value is returned.

Arguments

This function takes two arguments, namely the two series to correlate.

Example usage

print( corr( X, Y ) );

cos

Cosine of angle

Category: Mathematics

Notes

Returns, in radians, the cosine of the angle.

Arguments

This function takes a single series or number as argument.

Example usage

print( cos( pi() / 4 ) );  # Print square root of 1/2
Y = cos( X );              # Return new series with cosine of X as observations

cosh

Hyperbolic cosine

Category: Mathematics

Notes

Returns, in radians, the hyperbolic cosine of the hyperbolic angle.

Arguments

This function takes a single series or number as argument.

Example usage

print( cosh( pi() / 4 ) );
Y = cosh( X ); # Return new series with cosine of X as observations

count

Count observations in a series

Category: Data series

Notes

Returns the number of observations in a series.

Arguments

This function takes a single argument, the series whose observation count it is to return.

Example usage

n = count( X ); avg = sum( X ) / n;

covar

Covariance

Category: Data series

Notes

Calcualtes and returns the sample covariance between two series.

Arguments

This function takes two arguments, namely the two series.

Example usage

print( covar( X, Y ) );

d

Difference

Category: Data series

Notes

Calculates the first difference of its argument, which must reduce to a series. For a series y( t ) this returns the difference

y(t) - y(t-1)

This is appropriate for regular frequencies such as monthly and quarterly, but not for daily series. Here there are often gaps in a series due to weekends and holidays and this function will not be able to deal with that correctly. For daily frequencies, the dPrev function is suggested.

Arguments

This takes a single argument, namely the series to difference.

Example usage

D1 = d( X );         # First order difference
D2 = d( d( X ) );    # Second order difference

dLn

Natural logarithm difference

Category: Data series

Notes

Calculates the difference in the natural logarithm of the series' observations.

Arguments

This function takes a single argument, which must be a series. This is meant for regular frequencies. For irregular frequencies, such as daily, consider using the dLnPrev function in stead.

Example usage

dLn( X );

dLnPrev

Natural logarithm difference

Category: Data series

Notes

Calculates the difference in the natural logarithm of the series' consecutive observations.

Arguments

This function takes a single argument, which must be a series. This is meant for irregular frequencies, such as daily observations.

Example usage

dLnPrev( X );

dPrev

Difference to previous observation

Category: Data series

Notes

Calculates the first difference of its argument, which must reduce to a series. Whereas the d function calculates the difference between observations spaced one bar apart, this calculates the difference between subsequent observations.

Daily data, for example, will require observations on Sunday and the subsequent Monday in order to calculate first differences using the d function while this function will calculate the difference between Friday and Monday, ignoring the gap in between the two observations. It is thus the recommended function to use for differencing daily data.

Arguments

This function takes a single argument, namely the series to difference.

Example usage

D1 = dPrev( X );             # First order difference
D2 = dPrev( dPrev( X ) );    # Second order difference

dataCsv

Load data from a CSV file

Category: Data

Notes

This loads data from a locally stored CSV file. It applies the same options that was used to previously import data from the file, such as frequency, separator and quote string options. A named column is extracted and optionally aggregated and returned.

Arguments

This function takes two required and one optional argument:

The name of the CSV file - this is case sensitive and must not include any path or extention.
The name of the column to extract - this is also case sensitive.
(Optional) The way in which the series is to be aggregated.
Note that this argument is only relevant if the series being downloaded has a different frequency than the current evaluation frequency. It then specifies how to aggregate the higher frequency series. See the aggregate function for the available options. If not supplied, the default 'Average' aggregation will be applied.

Example usage

CPI   = dataCsv( "EconData", "CPI" );       # Read from file EconData.csv and extract column named CPI

dataFred

Download data from FRED

Category: Data

Notes

Downloads data from FRED and returns it as a series. For more information and to look up available codes, see https://research.stlouisfed.org

Arguments

This function takes two arguments:

The code of the series to download.
(Optional) The way in which the series is to be aggregated.
Note that this argument is only relevant if the series being downloaded has a higher frequency than the current evaluation frequency. It then specifies how to aggregate the higher frequency series. See the aggregate function for the available options.

Example usage

USCPI   = dataFred( "CPIAUCSL" );       # Download US CPI
CSTRESS = dataFred( "CFSI", "last" ); # Download Cleveland Financial Stress
                                      # index and aggregate by taking the
                                      # last rather than average value

dataGet

Retrieve a series of another frequency

Category: Data

Notes

Used to retrieve data values that are of a frequency different to that of the calculation.

The function achieves this by specifying the case sensitive variable name of the series to retrieve as well as the case insensitive data source (e.g. CSV) and the case insensitive data key. Since this may imply a frequency conversion, the last parameter can be used to specify the way in which to aggregate observations from the source series.

Arguments

This function takes up to four arguments:

Variable name of the series to retrieve
Note that this may differ from the series name itself, e.g. after the series was edited to have a more descriptive name. Also note that this is case sensitive.
(Optional) Source to obtain the series from e.g. CSV
If this is not supplied the first series with the given variable name will be returned. This is case insensitive.
(Optional) Key used when retrieving e.g. the name of the CSV file
If this is not supplied the first series with the given variable name found in the source will be used. This may also be a missing value. This is case insensitive.
(Optional) The way in which the series is to be aggregated
This is only relevant if the source series has a higher frequency than the current calculation frequency. This argument then specifies how to aggregate the higher frequency series. See the aggregate function for the available options here. If this is omitted, then the series' properties is queried for an aggregation as the default aggregation is typically stored as a series property.

Example usage

avgCPI = dataGet( "CPI", "CSV", "myData.csv", "AVG" );
totGDP = dataGet( "GDP", "CSV", "myData.csv", "SUM" );

dataPut

Store a given series into the document

Category: Data

Notes

Used to put data back into the document. It will store any data series back into the document but will not replace any data. To replace data use the dataReplace function.

This function is similar to the dataReplace function, but is non-destructive and will only "put" a series if it is not already in the document. It returns 1 if the series will be stored to the document and 0 if not, i.e. if a series with the specified name already exists.

Note that, as with dataReplace, this does not create a local variable with the given name. Thus

dataReplace( "t", CPI );

will for example NOT create a local variable named t, and trying to use t, e.g. as in

u = t;

will fail or use a previously assigned or loaded t. The value of all variables are loaded when the calculation starts up and if t was not loaded then, or created later as part of the calculation, then the example assignment will fail. Even so, something like

u = dataGet( "t" );

will still work as expected.

Arguments

This fucntion takes either one or two arguments:

If a single argument is given, it must be the name of an existing data series. The name will be used to store the observations (after applying any transformations such as leads or lags) and properties of the data series back into the document. The source and key will be both be "CALC" and the document data's variable name will be the name of the series. Initially the name of the series (in the document) will also be the same but this can be changed at will. The variable name, however, cannot be changed and can for example be used later on to update the series with new values and properties using the dataReplace function.

If two arguments are given, then they must be:

A string variable name
Note that it must be a valid variable name, containing only alphanumerics and underscores. Neither special characters nor spaces will be accpeted.
This argument is evaluated and the result must be a data series
This series will be stored into the document using the first argument as variable name. If the series already exists in the document, it is not replaced.

Example usage

dataPut( CPI );        # Store CPI into CPI
dataPut( "USCPI2010", 100 * CPIAUCSL / CPIAUCSL[ average( limit( dateValue( 2010, 1, 1 ), dateValue( 2010, 12, 31 ), CPIAUCSL ) ) ] );
dataPut( GDP(-1) );    # Store GDP(-1) into GDP

dataReplace

Store a given series into the document, replacing existing data

if present

Category: Data

Notes

Used to put data back into the document. It will store any data series back into the document replacing any existing series if present. If existing data should be retained, use the dataPut function instead.

This function is similar to the dataPut function, but will override any existing series if present. To retain the existing series, use the dataPut function instead. It returns 1 since the series will be written to the document, even if already present in the document.

Note that, as with dataPut, this does not create a local variable with the given name. Thus

dataReplace( "t", CPI );

will for example NOT create a local variable named t, and trying to use t, e.g. as in

u = t;

u = dataGet( "t" );

will still work as expected.

Arguments

This function takes either one or two arguments:

If a single argument is given, it must be the name of an existing data series. The name will be used to store the observations (after applying any transformations such as leads or lags) and properties of the data series back into the document. The source and key will be both be "CALC" and the document data's variable name will be the name of the series. Initially the name of the series (in the document) will also be the same but this can be changed at will. The variable name, however, can not be changed and can for example be used later on to update the series with new values and properties using this function again.

If two argument are given, then they must be:

A string variable name
Note that it must be a valid variable name, containing only alphanumerics and underscores. Neither special characters nor spaces will be accepted.
This argument is evaluated and the result must be a data series
This series will be stored into the document using the first argument as variable name. If the series already exists in the document, it will be replaced by this one.

Example usage

dataReplace( CPI );        # Store CPI into CPI
dataReplace( "USCPI2010", 100 * CPIAUCSL / CPIAUCSL[ average( limit( dateValue( 2010, 1, 1 ), dateValue( 2010, 12, 31 ), CPIAUCSL ) ) ] );

dataSetDelete

Delete a data set from local storage

Category: Data

Notes

Deletes a previously saved data set from local storage.

Arguments

This function takes a single argument, namely the name of the data set to delete. It returns 1 if the data set was found and successfully deleted and 0 if it was not found.

Example usage

dataSetDelete( "sampleData" ); # Delete the data set named "sampleData"

dataSetList

List locally stored data sets

Category: Data

Notes

Used to list all locally stored data sets. It adds a list of locally stored data sets to the log and can be used to inspect what sets is stored locally.

Arguments

This function does not take any arguments. It returns the number of data sets stored locally.

Example usage

dataSetList(); # Print names and some details of locally stored data sets to log

dataSetLoad

Load a previously saved data set

Category: Data

Notes

Used to load a previously saved data set. The data set does not replace the data currently in memory, but stores it under the same name as that used to load it. Thus

datasetSave( "myData" );
data setLoad( "myData" );

will save all data in memory to "myData" and immediately load it again under the name "myData", in effect duplicating it.

Suppose we want to perform a calculation and see how the values of some variable change, for example, we could do something like

dataSetSave( "old" );
X = ... some calculation ...;
dif = X - dataSetValue( "old", "X" );

This will store all data to "old", perform some calculation and then compare the new value of X to its old value. This illustration is to explain the concept, data will mostly be saved to be reused elsewhere later.

Arguments

This function takes a single argument, namely the name of the data set.

Example usage

dataSetSave( "sampleData" ); # Save all data to the data set named "sampleData"
dataSetLoad( "sampleData" ); # Load the data set back into memory

dataSetSave

Save all data to a named data set

Category: Data

Notes

Saves all data currently in (main) memory to a named data set. It will only save data in main memory, not loaded data. Thus

dataSetLoad( "US" ); dataSetSave( "myData" );

will first load the "US" data set and then afterwards save all current data to a data set called "myData". This data set will not contain any data from "US" even though "US" has been loaded, but will only contain data calculated earlier on.

Arguments

This function takes a single argument, namely the name of the data set. All data currently in memory is saved to the data set, except for data contained in other named data sets.

Example usage

dataSetSave( "sampleData" ); # Save all data to the data set named "sampleData"

dataSetValue

Extract a value from a data set

Category: Data

Notes

Used to extract data from a data set after loading it.

Arguments

This function takes two required and one optional argument:

The name of the data set from which to extract a value.
The name of the variable to extract.
(Optional) The way in which to aggregate the data if it is a data series that is of a higher frequency than the current frequency. For valid argument values, see the aggregate function. If omitted, the default is to calculate the average of the higher frequency series.

Example usage

Var1 = "ABC";  # Set some variables
Var2 = 12.34;
Var3 = observe( dateIndex( 2010, 1, 1 ), 10, 11, 12, 13 );
dataSetSave( "sampleData" );     # Save variables to a data set
dataSetLoad( "sampleData" );     # Load variables
print( dataSetValue( "sampleData", "Var1" ) );   # Print out variable values
print( dataSetValue( "sampleData", "Var2" ) );
print( dataSetValue( "sampleData", "Var3" ) );

dataStatsSa

Load data from STATSSA

Category: Data

Notes

This loads data from STATSSA. It takes two arguments, the first being the release name (e.g. P0141 for CPI) and the second the series code (e.g. CPA00000 for All Items). It takes an optional third argument that is used to aggregate it if any frequency conversion is required.

Arguments

This function takes two required and one optional argument:

The name of the STATSSA release - this is case sensitive.
The name of the variable - this is also case sensitive.
(Optional) The way in which the series is to be aggregated.
Note that this argument is only relevant if the series has a different frequency than the current evaluation frequency. It then specifies how to aggregate the higher frequency series. See the aggregate function for the available options. If not supplied, the default 'Average' aggregation will be applied or, if an aggregation is known and predefined for the series, that will be used.

Example usage

CPI   = dataStatsSa( "P0141", "CPA00000" );   # Read CPA00000 from P0141

dataValue

Extract a value from a data set

Category: Data

Notes

Used to extract data from a data set after loading it.

This is similar to the dataSetValue function that is also used to extract a value from a data set. However, since the extraction happens from a data SET and since SET is normally used to put, not get, a value, this function is a convenience and more readable alternative for the same functionality.

Arguments

This function takes two required and one optional argument:

The name of the data set from which to extract a value.
The name of the variable to extract.
(Optional) The way in which to aggregate the data if it is a data series that is of a higher frequency than the current frequency. For valid argument values, see the aggregate function. If omitted, the default is to calculate the average of the higher frequency series.

Example usage

Var1 = "ABC";  # Set some variables
Var2 = 12.34;
Var3 = observe( dateIndex( 2010, 1, 1 ), 10, 11, 12, 13 );
dataSetSave( "sampleData" );     # Save variables to a data set
dataSetLoad( "sampleData" );     # Load variables
print( dataValue( "sampleData", "Var1" ) );   # Print out variable values
print( dataValue( "sampleData", "Var2" ) );
print( dataValue( "sampleData", "Var3" ) );

dateIndex

Frequency index for a given date

Category: Date

Notes

Converts a given date to a frequency index.

The frequency index can then be used to index a data series. Thus for monthly series, to get the value of say CPI in November of 2010, use

Nov2010Cpi = CPI[ dateIndex( 2010, 11, 1 ) ];

Data indices can also be used in normal calculations, so that the following will retrieve three consecutive values from the CPI data series for example.

I = dateIndex( 2010, 1, 1 );
CPIJan = CPI[ I     ];
CPIFeb = CPI[ I + 1 ];
CPIMar = CPI[ I + 2 ];

The returned value is a value converted into a proper indexing value for the current frequency.

Arguments

This function takes three arguments:

The year e.g. 2010 or 1980.
The month e.g. 1 for January or 12 for December.
The day of the month e.g. 1 or 28 or 30.

Thus the basic format is

dateIndex( YYYY, MM, DD )

Example usage

I2015 = dateIndex( 2015,  1,  1 );
I2016 = dateIndex( 2016,  1,  1 );
Start = dateIndex( 2015,  1,  1 );
End   = dateIndex( 2015, 12, 31 );
print( "Frequency", 1 + End - Start );

day

Return the day of a date index

Category: Date

Notes

This will return the day (of month) represented by a number. The number is interpreted as a date index using the current frequency. If the interval spans more than a day then the day of the last date in the interval is returned.

Arguments

This function takes a single argument which is the date index. It returns the day (of the month) in the current frequency represented by the number.

Example usage

di = dateIndex( 1975, 4, 12 )
print( day( i ) ); # Prints 12

define

Define a function

Category: User functions

Notes

This is used to define a new function that can later be called using the call function. This will return 0 if the function was created as a new function and 1 if it replaces an existing function definition. Note that functions are stored separately from other variables and thus they can have the same names as variables. Thus you can have both a variable and a function named e.g. x at the same time without creating a conflict.

Arguments

This function takes at least two arguments. The first, which must evaluate to a string, is the name of the function to define. The last is the function body and represents the code that will be executed when the function is called. If more arguments are given, they represent the arguments to the function itself.

The name of the function to define - this is case sensitive and must evaluate to a string.
The first argument to the function - this is case sensitive and must also evaluate to a string.
The second argument to the function - also a case sensitive string.
... other arguments ...
The body of the function as the final argument.

Example usage

define( "add", "x", "y", x + y );   # Add two numbers

diff

Differentiate symbolically

Category: Mathematics

Notes

Used to symbolically differentiate an expression to a given variable. It is meant for internal use and only some expressions support symbolic differentiation.

Also, after differentiating, no effort is made to simplify the expression, neither is the symbolic expression itself returned. Instead, the differenced expression is evaluated and the answer is returned.

Arguments

This function takes two arguments:

The expression to differentiate.
The variable to differentiate to.

Example usage

x = 1.2;
h = 0.00001;
print( diff( sin( x ), x ) );
print( cos( x ) );                        # Note diff( sin(x), x ) = cos( x )
print( ( sin( x + h ) - sin( x ) ) / h ); # Numerical differentiation

driveAdd

Adjust a value using a driver series

Category: Simulate

Notes

This adjusts a given value using a driver variable. The driver variable is treated as an add factor, and used to adjust a given value with a given driver value. The driver variable can be supplied either as a data series and index combination, or as a matrix and a row and column index combination. The combination is then used to look up the driver add factor to use to adjust the value with.

Arguments

This function takes three or four arguments. The first is the current value that needs to be adjusted. The next two or three arguments are used to specify the driver add factor and is either a data series followed by an index value or a matrix followed by a row and a column index. Thus the arguments are

Current value
This must evaluate to a number and gives the current value of the quantity.
Driver values, either a series or matrix
The driver add factor values can be supplied either as a series or as a matrix.
Series index or row index
If a series is supplied as driver, then this is the index into that series at which the driver value is located. It is thus typically a date idnex. This is also the last parameter if a data series is the driver. If a matrix is used as driver, then this specifies the row in which to find the driver add factor.
Column index
If a matrix is supplied as driver then this gives the column of the driver add factor to use.

Example usage

print( driveAdd( InterestRate, PastChanges, randomIndex ) );
print( driveAdd( InterestRate, PastChanges, randomRow, RateColumn ) );

driveMul

Adjust a value using a driver series

Category: Simulate

Notes

This adjusts a given value using a driver variable. The driver variable is treated as a multiplier, and used to adjust a given value with a given driver value. The driver variable can be supplied either as a data series and index combination, or as a matrix and a row and column index combination. The combination is then used to look up the driver multiplier to use to adjust the value with.

Arguments

This function takes three or four arguments. The first is the current value that needs to be adjusted. The next two or three arguments are used to specify the driver multiplier and is either a data series followed by an index value or a matrix followed by a row and a column index. Thus the arguments are

Current value
This must evaluate to a number and gives the current value of the quantity.
Driver values, either a series or matrix
The driver multiplier values can be supplied either a series or as a matrix.
Series index or row index
If a series is supplied as driver, then this is the index into that series at which the driver value is located. It is thus typically a date idnex. This is also the last parameter if a data series is the driver. If a matrix is used as driver, then this specifies the row in which to find the driver multiplier.
Column index
If a matrix is supplied as driver then this gives the column of the driver multiplier to use.

Example usage

print( driveMul( SharePrice, PastRatios, randomIndex ) );
print( driveMul( SharePrice, PastRatios, randomRow, ShareColumn ) );

dy

Yearly difference

Category: Data series

Notes

Calculates the differences over a year.

For a monthly series y( t ), it will for example calculate and return

y(t) - y(t-12)

Similarly, for a daily series, it will calculate and return

y(t) - y(t-365)

Note that this function may not be appropriate. For daily series, it is advisable to use the dyPrev function instead.

Arguments

This function takes a single argument, namely the series to difference.

Example usage

YOY = dy( X ) / X(-12);

dyPrev

Yearly difference for daily observations

Category: Data series

Notes

Also calculates the differences over a year.

It is especially useful when the frequency is daily. Then the simple dy function, i.e.

y(t) - y(t-365)

does not work as well.

This function works by ensuring observations are at least a year apart and also by ensuring that the previous observation is the most recent one that is still at least a year away from the current one. It will give better results for daily series and the same results for lower frequency series. Unfortunately it comes at a performance penalty, thus the dy function is preferred for the latter.

Arguments

This function takes a single argument, namely the series to difference.

Example usage

DYX = dyPrev( X );

e

Euler’s number

Category: Mathematics

Notes

Returns Euler's number, namely 2.718... . Since e is irrational, an approximation is returned.

Arguments

This function does not take any arguments but simply returns Euler's number. It still needs empty parenthesis to prevent an error from being generated.

Example usage

accuracy( 100 ); print( e() );

empty

Empty series

Category: Mathematics

Notes

Creates and returns an empty series.

Arguments

This function does not take any arguments.

Example usage

print(empty () );

erf

Error function

Category: Mathematics

Notes

Returns the error function of the argument.

Arguments

This function takes a single series or number as argument.

Example usage

print( erf( 1 ) );
print( erf( 2.34 ) );
z = 2.34;
print( diff( erf( z ), z ) );
print( 2 * exp( - z ^ 2 ) / sqrt( pi () ) );      # Same as diff( erf( z ), z )

erfc

Complementary error function

Category: Mathematics

Notes

Returns the complementary error function of the argument.

Arguments

This function takes a single series or number as argument.

Example usage

print( erfc( 1 ) );
print( erfc( 2.34 ) );
z = 2.34;
print( diff( erfc( z ), z ) );
print( - 2 * exp( - z ^ 2 ) / sqrt( pi () ) );      # Same as diff( erfc( z ), z )

ewma

Exponentially weighted moving average

Category: Data series

Notes

Calculates and returns the exponentially weighted moving average for a given series and weight. If s( t ) is the smoothed series at time t, this sets s( 1 ) = y( 1 ) and calculates and returns

s(t+1) = ( 1 - weight ) * y(t+1) + weight * s(t)

Use for example, a weight of 0.99 for a "slow" moving average and 0.2 for a "fast" moving average.

Arguments

This function takes two arguments:

The weight to use in calculations.
The series to smooth.

Example usage

Trend = ewma( 0.95, X );

ewmaLength

Exponentially weighted moving average with a length

argument

Category: Data series

Notes

Calculates an exponentially weighted moving average, similar to the ewma function but instead of taking a weight, it takes an integer "length" as parameter.

The length is then converted into a weight using

weight = 1 - 2 / ( 1 + length )

Arguments

This function takes two arguments:

The length.
The series to smooth.

Example usage

Trend = ewmaLength( 12, X );

exp

Exponentiate using Euler’s number e

Category: Mathematics

Notes

Calculates and returns e^x for a given x.

Arguments

This function takes a single argument and returns e raised to that argument. The argument can be either a series or a number.

Example usage

print( exp( 10 ) );
Y = exp( X );

expCdf

Cumulative exponential probability distribution

Category: Statistics

Notes

Returns the cumulative exponential probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes two arguments:

x
The value at which to calculate the cdf.
lambda
The rate (inverse scale) parameter of the distribution.

Example usage

print( expCdf(  5,  1 ) );
print( expCdf( 25, 10 ) );

expPdf

Exponential probability distribution

Category: Statistics

Notes

Returns the exponential probability distribution function (pdf).

Arguments

This function takes two arguments:

x
The value at which to calculate the pdf.
lambda
The rate or inverse scale parameter of the distribution.

Example usage

print( expPdf(   2,   1 ) );
print( expPdf( 110, 100 ) );

expQnt

Exponential probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the exponential probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and is therefore also called the inverse cumulative distribution function.

Arguments

This function takes two arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
lambda
The rate (inverse shape) parameter of the distribution.

Example usage

print( expQnt( 0.05,  1 ) );
print( expQnt( 0.99, 10 ) );

fCdf

Cumulative Snedecor’s F probability distribution

Category: Statistics

Notes

Returns the cumulative Snedecor's F probability distribution function (cdf).

For a given value x this returns the probability that a random variable from this distribution will be less than this value.

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
k1
The first (numerator) degrees of freedom.
k2
The second (denominator) degrees of freedom.

Example usage

print( fCdf( 2, 3, 4 ) );
print( fCdf( 110, 100, 10 ) );

fPdf

Snedecor’s F probability distribution

Category: Statistics

Notes

Returns Snedecor's F probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
k1
The first (numerator) degrees of freedom.
k2
The second (denominator) degrees of freedom.

Example usage

print( fPdf( 2, 3, 4 ) );
print( fPdf( 110, 100, 10 ) );

fQnt

Quantiles of Snedecor’s F probability distribution

Category: Statistics

Notes

This returns the quantiles of Snedecor's F probability distribution.

For a given probability value p, which lies between 0 and 1, this returns the critical value or quantile x so that CFD( x ) = p and is therefore also called the inverse cumulative probability distribution.

Arguments

This function takes three arguments:

p
The desired probability, between 0 and 1, for which to find the corresponding quantile.
k1
The first (numerator) degrees of freedom.
k2
The second (denominator) degrees of freedom.

Example usage

print( fQnt( 0.01,   3,  4 ) );
print( fQnt( 0.05, 100, 10 ) );
print( fQnt( 0.10,  25, 15 ) );

fact

Factorial

Category: Mathematics

Notes

Returns the factorial (e.g. x!) of the given value (e.g. x).

Arguments

This function takes a single series or number as argument.

Example usage

print( fact( 10 ) );
Y = fact( X ); # Return new series with factorial of X as observations

first

Value of first observation of a series

Category: Data series

Notes

Returns the value of the first observation of a data series. If the series is empty, it will return a missing value.

Arguments

This function takes a single argument, namely the series whose first observation value is to be returned.

Example usage

print( first( X ) );
print( ( last( X ) - first( X ) ) / ( lastDate( X ) - firstDate( X ) ) );
print( X[ firstDate( X ) ] );         # Same as first( X )

firstDate

First observation’s date index

Category: Data series

Notes

Returns the date index of the first observation of a series. If the series is empty, it will return a missing value.

Arguments

This function takes a single argument, namely the series whose first observation's date index is to be returned.

Example usage

print( firstDate( X ) );
print( ( last( X ) - first( X ) ) / ( lastDate( X ) - firstDate( X ) ) );
print( X[ firstDate( X ) ] );         # Same as first( X )

floor

Floor

Category: Mathematics

Notes

Calculates the floor of the argument.

The floor is the largest integer smaller than or equal to the argument. Thus the floor of 0.1 is 0 and the floor of -0.1 is -1 for example.

Arguments

This function takes a single value or series as argument.

Example usage

print( floor(  0.1 ) ); # Will print  0
print( floor(  0.9 ) ); # Will print  0
print( floor(  1.0 ) ); # Will print  1
print( floor( -0.1 ) ); # Will print -1
print( floor( -0.9 ) ); # Will print -1
print( floor( -1.0 ) ); # Will print -1
print( floor( X    ) ); # Element by element floor of series X

format

Format settings

Category: Output

Notes

Used to set the formatting parameters, such as the number of fractional digits or integer part grouping character to use.

Arguments

This function takes up to nine parameters:

The number of fractional digits or decimals to use.
(Optional) The field length.
The output is padded to ensure this length is attained.
(Optional) The string to use as prefix when printing number.
For example "USD".
(Optional) The string to use as postfix when printing numbers.
For example "%yoy".
(Optional) The character to use as decimal separator.
The default is . (as in 1.23).
(Optional) The character to use as integer portion grouping character.
The default is , (as in 123,456.23).
(Optional) The character to use as fractional portion grouping character.
The default is a blank (as in 123,456.23456). If this is set to / for example, then a formatted number may appear as 12.345/678/901 .
(Optional) The scale to use when formatting the number.
A scale of 0 leaves the number untouched, 1 is the same as multiplying it by 10 and -1 as dividing it by 10 and so forth. A value of 2 can be used to format percentages for example.
(Optional) The number of digits used as a cut off for E format.
If a number requires more than this many digits to print, then it will be printed using E notation.

Only one parameter is required while the rest can be omitted. To set only the first and third parameter, while leaving the rest unchanged for example, use something like

format( 10, ., "ZAR" );

Note how the missing value "." is used to indicate that an optional parameter should be left untouched in the above example.

Example usage

format( 10 );         # Now 1 will print as +1.0000000000

format( 100 ); accuracy( 100 ); print( pi () );

# After this 12345.6789012 will print as
#       pre+12i345i678d901f200f000f000pst
format( 10, 40, "pre", "pst", 'd', 'i', 'f', 3 );
print( 12345.6789012 );
# Reset formatting to default and print something
format( 4, 10, "", "", '.', ',', '', 0 );
print( 12345.6789012 );

formatFix

Fixed format

Category: Output

Notes

Causes subsequent formatting of numbers to use the "fixed" style.

This style uses a fixed number of digits following on the decimal separator, regardless of how big or small the number is, to format output. As a result very small numbers will display as zero and very large values will take up a lot of space.

To switch out of fixed format, use either the formatSci (scientific format) or the formatGen (general format) functions. The return value is 1 if fixed formatting was already switched on and 0 if it was not.

Arguments

This function does not take any arguments.

Example usage

formatFix ();
print( pi() * 10000000000000000000000000000000000000 );
print( pi() / 10000000000000000000000000000000000000 );
formatReset();

formatGen

General format

Category: Output

Notes

Causes subsequent formatting of numbers to use "general" formatting.

General formatting uses fixed formatting for values that can be dispalyed normally and scientific formatting for numbers that are very large or very small. It is the default formatting and is therefore the set format after a formatReset function call.

Arguments

This function does not take any arguments.

Example usage

formatGen ();
print( pi() * 10000000000000000000000000000000000000 );
print( pi() / 10000000000000000000000000000000000000 );
formatReset();

formatReset

Reset formatting settings

Category: Output

Notes

Resets all formatting settings, e.g. the number of decimals to print, back to their defaults.

Arguments

This function does not take any argument. It simply returns 1 upon completion.

Example usage

formatReset();

formatSci

Scientific format

Category: Output

Notes

Causes subsequent formatting of numbers to use the "scientific" style.

This style scales a number so that it always has only a single digit before the decimal separator and the rest behind it. The scale is shown using a postfixed E followed by the scale behind the number. All numbers, no matter how big or small, will thus display in the same way.

To switch out of scientific format, use either the formatFix (fixed format) or the formatGen (general format) functions. The return value is 1 if scientific formatting was already switched on and 0 if it was not.

Arguments

This function does not take any arguments.

Example usage

formatSci ();
print( pi() * 10000000000000000000000000000000000000 );
print( pi() / 10000000000000000000000000000000000000 );
formatReset();

funcExists

See if a function is defined

Category: User functions

Notes

This will check to see if a given user defined function exists. It returns 1 if it does and 0 if not.

Arguments

This function takes a single argument, namely the name of the user defined function. It will then return 1 if this function is defined or exists and 0 if not. Note that if a function is not defined in the current context, the parent context will also be queried.

fn
The case-sensitive name of the function - must evaluate to a string.

Example usage

print( "Examples - funcExists" );

funcExists( "??" );

funcMin

Report user defined function minimum

Category: User functions

Notes

This will report when a given user defined function evaluates to a new minimum. This function can be used to turn the reporting on or off and also to get the function's current minimum.

Arguments

This function takes a single argument, namely the name of the user defined function to report. It will then turn on reporting and will report whenever the function is evaluated at a new minimum value to the log. It only works for functions that return a single value as result. It can also be called with a second optional argument that can be used to turn the reporting on or off.

Calling this function will return the current minimum. If the minimum is not known or does not exist this will return a missing value.

If the function has never been called or if the function returns say a string or a matrix, then the minimum can not be calculated and will not be reported and this function will return a missing value.

fn
The case-sensitive name of the function - must evaluate to a string.
(Optional) report
If this evaluates to zero then reporting is turned off else it is turned on. If omitted then reporting is turned on. Once reporting is turned on this will report it to the log whenever the function evaluates to a new minimum.

Example usage

print( "Examples - funcMin" );

# Define a new function

define( "fn", "x", x ^ 2 );

# Reporting on

funcMin( "fn" );

# Throw 100 random numbers at function

i = 0;
while( i &lt; 100, call( "fn", rand () ), i = i + 1 );

# Report minimum and turn reporting off

print( funcMin( "fn", 0 ) );
# Print the current minimum

print( funcMin( "fn" ) );

# Turn minimum reporting on

funcMin( "fn", 1 );

# Turn minimum reporting off

funcMin( "fn", 0 );

funcMinArg

Report the argument at which a user defined function evaluated to a minimum

Category: User functions

Notes

This will report the argument where a user defined function evaluated to a minimum.

Arguments

This function takes a single argument, namely the name of the user defined function. If this function has been evaluated before, and if this evaluation resulting in a single numerical value, then the function's minimum and the argument at which it was evaluated is noted. This function then returns the (first) argument at which the current minimum was noted.

If a function takes multiple arguments, then an optional second argument can be supplied to indicate the desired argument to return. So if a function is defined to take x1 and x2, e.g.

  define( "fn", "x1", "x2", x1 ^ 2 / x2 );

then this will return x1. To return x2, call this with a second argument specifying the index of the argument to return, e.g.

  funcMinArg( "fn", 2 );

fn
The case-sensitive name of the function - must evaluate to a string.
(Optional) index
The index of the argument to return, defaults to 1 or first argument.

Example usage

print( "Examples - funcMinArg" );

# Define a new function

define( "fn", "x1", "x2", x1 ^ 2 / ( 1 + x2 ) );

# Reporting on

funcMin( "fn" );

# Throw 100 random numbers at function

i = 0;
while( i &lt; 100, call( "fn", rand(), rand() ), i = i + 1 );

# Report minimum and turn reporting off

print( "Min y ", funcMin( "fn", 0 ) );
# Report where the minimum was seen

print( "Min x1", funcMinArg( "fn", 1 ) );
print( "Min x2", funcMinArg( "fn", 2 ) );

funcMinReset

Reset the minimum of a user defined function

Category: User functions

Notes

This will reset the minimum (and minimum's argument) of a user defined function.

Arguments

This function takes a single argument, namely the name of the user defined function. It will then reset the function's minimum and the minimum's argument.

fn
The case-sensitive name of the function - must evaluate to a string.

This resets the minimum and returns 1 if the function had a known minimum and 0 otherwise.

Example usage

print( "Examples - funcMinReset" );

# Reset

funcMinReset( "fn" );

funcOptimFr

Optimise a function using Fletcher-Reeves

Category: User functions

Notes

This will optimise (minimise) a given user defined function using the nonlinear conjugate gradients with Newton-Rapshon and Fletcher-Reeves method.

Arguments

This function takes the following arguments:

function
The name of the function to optimise. This must be a user defined function that takes a single argument, which is the parameter value at which to evaluate the function.
initial
The initial value of the argument.
(Optional) maxIter
The maximum number of iterations.
(Optional) maxIterNr
The maximum number of Newton-Rapshon iterations.
(Optional) tol
The tolerance to use when testing function convergence.
(Optional) tolNr
The tolerance to use in the Newton-Raphson.
(Optional) tolGrad
The step size to use when calculating the gradient.
(Optional) tolHess
The step size to use when calculating the hessian.

This returns the argument at the found minimum.

Example usage

print( "Examples - funcOptimFr" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Optimise (minimum is at a, a ^ 2 )

print( funcOptimFr( "rb", matrix( 2, 1, 0, 0 ) ) );

funcOptimNm

Optimise a function using Nelder-Mead

Category: User functions

Notes

This will optimise (minimise) a given user defined function using the Nelder-Mead (simplex) method.

Arguments

This function takes the following arguments:

function
The name of the function to optimise. This must be a user defined function that takes a single argument, which is the parameter value at which to evaluate the function.
initial
The initial value of the argument.
(Optional) distance
The distances to use along each axis when constructing the initial simplex. This can be a single value in which case the same distance will be used for all axis.
(Optional) maxIter
The maximum number of iterations.
(Optional) tolShrink
The tolerance to use when checking for termination.
(Optional) tolMaxDiff
The tolerance to use when checking for termination.

Termination should happen on a shrink step. When the simplex is shrinking, the standard deviation in function values is calculated and if this is less than or equal to tolShrink the algorithm terminates. Otherwise, if the simples is not shrinking, the difference between the maximum and minimum function values is compared to tolMaxDiff and the algorithm terminates if it is less than or equal to this. Since it is preferable to terminate on a shrink, set tolMaxDiff to a much smaller value than tolShrink.

This returns the argument at the minimum simplex point upon termination.

Example usage

print( "Examples - funcOptimNm" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Optimise (minimum is at a, a ^ 2 )

print( funcOptimNm( "rb", matrix( 2, 1, 0, 0 ) ) );

funcOptimPr

Optimise a function using Polak-Ribière

Category: User functions

Notes

This will optimise (minimise) a given user defined function using the nonlinear conjugate gradients with secant and Polak- Ribière method.

Arguments

This function takes the following arguments:

function
The name of the function to optimise. This must be a user defined function that takes a single argument, which is the parameter value at which to evaluate the function.
initial
The initial value of the argument.
(Optional) maxIter
The maximum number of iterations.
(Optional) maxIterSec
The maximum number of secant iterations.
(Optional) tol
The tolerance to use when testing function convergence.
(Optional) tolSec
The tolerance to use in the secant.
(Optional) tolGrad
The step size to use when calculating the gradient.
(Optional) tolHess
The step size to use when calculating the hessian.

This returns the argument at the minimum.

Example usage

print( "Examples - funcOptimPr" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Optimise (minimum is at a, a ^ 2 )

print( funcOptimPr( "rb", matrix( 2, 1, 0, 0 ) ) );

funcOptimise

Optimise a function

Category: User functions

Notes

This will optimise (minimise) a given user defined function.

Arguments

This function takes the following arguments:

function
The name of the function to optimise. This must be a user defined function that takes a single argument, which is the parameter value at which to evaluate the function.
initial
The initial value of the argument.
(Optional) maxIter
The maximum number of iterations.
(Optional) tol
The tolerance to use when testing function convergence.
(Optional) tolGrad
The step size to use when calculating the gradient.
(Optional) tolHess
The step size to use when calculating the hessian.

This uses a Newton-Raphson based algorithm to minimise the function with and returns the argument or function parameter at the found minimum.

Example usage

print( "Examples - funcOptimise" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Optimise (minimum is at a, a ^ 2 )

print( funcOptimise( "rb", matrix( 2, 1, 0, 0 ) ) );

funcZoom

Zoom in on a function

Category: User functions

Notes

This will optimise (minimise) a given user defined function by 'zooming' in on it. It will perform a gridsearch with increasingly small step sizes to zoom in on the function's minimum.

Arguments

This function takes the following arguments:

function
The name of the function to optimise. This must be a user defined function that takes a single argument, which is the parameter value at which to evaluate the function. It then returns the value of the function at this parameter.
minimum
The minimum values at which to start the grid search. If the function takes a matrix (or series) as argument, then each entry in the matrix (or each observation in the series) will be used as the minimum value for that dimension of function.
maximum
The maximum values at which to end the grid search. These values, as with the minimum values, are inclusive and the search will end at, but not exceed, these value. Note that the order does not really matter, so these values need not be stricly greater than the minimum values. The minimum and maximum simply determines the the range through which to search.
(Optional) divisions
The number of divisions to divide the search range in per dimension. The default is 20, so a function with 2 parameters will take 21 x 21 = 441 steps to search. Note that there is one more step than the number of divisions as both endpoints are also evaluated. If this is a single value, the same will be used for all dimensions. Otherwise, its dimension must agree with that of the function's argument and each individual value will be used for its respective dimension. Thus if this is 20 then each dimension will be divided up into 20 divisions, but if it is e.g. matrix( 2, 1, 10, 5 ) then the first parameter's range will be divided into 10 divisions and the second into 5 divisions.
(Optional) depth
The number of times to zoom in. The default is 5, so a function with 2 parameters and 20 steps will result in 5 x 21 x 21 = 2,205 function evaluations. Note that, during function evaluation, a variable called depth will be created with initial value equal to 1 and counting up to depth as the zooming progresses. This can be used to perform any depth-specific processing inside the function.
(Optional) clicks
The number of 'clicks' to use when zooming in. If a parameter has a range of -1 to +1 and 20 divisions, then the function will be evaluated at -1.0 -0.9 -0.8 ... 0.8 0.9 1.0 during the first round. Suppose the minimum is observed at 0.5, then the default of 2 clicks will result in a new range being created from 0.3 to 0.7, which is 2 clicks either size of the 0.5 minimum. The next round will then use 20 divisions between 0.3 and 0.7 and evaluate the function at these 21 points. As with the steps parameter, this can either be a single value to apply to all parameter dimensions or a matrix of values where each one will be applied to its respective dimension. The clicks will not take the range outside of the supplied parameter range.

This function is helpful to optimise a badly behaving function in a given range. If the function has too many parameters, then the steps will have to be reduced dramatically to allow it to terminate within a reasonable amount of time. Remember that execution can be halted by clicking on the spinner at any time.

Example usage

print( "Examples - funcZoom" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector, dim 2
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Optimise (minimum is at a, a ^ 2 )
# Note that this will search between -5 and +5

print( funcZoom( "rb",
  matrix( 2, 1, -5, -5 ), matrix( 2, 1, 5, 5 ) ) );

gamma

Gamma function

Category: Mathematics

Notes

Calculates the gamma function of its argument.

Arguments

This function takes a single argument and return the gamma function value for that argument. The argument can be a numerical value or a series.

Example usage

print( gamma( 0.1 ) );
print( gamma( 15.6 ) );
print( gamma( -1.23 ) );
print( gamma( X ) );

gammaCdf

Cumulative gamma probability distribution

Category: Statistics

Notes

Returns the cumulative gamma probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes three arguments:

x
The value at which to calculate the cdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( gammaCdf(  0.5, 1, 1 ) );
print( gammaCdf( 20.0, 1, 5 ) );

gammaPdf

Gamma probability distribution

Category: Statistics

Notes

Returns the gamma probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( gammaPdf( 0.2,  1, 2 ) );
print( gammaPdf( 0.99, 1, 1 ) );

gammaQnt

Quantiles of the Gamma probability distribution

Category: Statistics

Notes

Returns the quantiles of the gamma probability distribution.

Arguments

This function takes three arguments:

p
The desired probability, between 0 and 1, for which to find the corresponding quantile.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( gammaQnt( 0.01,   3,  4 ) );
print( gammaQnt( 0.05, 100, 10 ) );
print( gammaQnt( 0.10,  25, 15 ) );

getProperty

Retrieve a series property

Category: Data series

Notes

Extracts a named property from a given data series.

Series are unique in that they also carry properties, which can be set to various string values. This allows for the retrieval of these properties. A numerical missing value is returned if the property can not be found, otherwise the string or numerical property value is returned.

Arguments

This function takes two arguments:

Series name
Note that this must reduce to a string, which is equal to the series name. This is not the series itself.
Property name
This is the name of the property to retrieve. It must also reduce to a string.

Note the distinction between the series and its name. If a series named

CPI

exists, for example, then

getProperty( "CPI", "unit" );

is correct and not

getProperty( CPI, "unit" );

Likewise one could use

serName = "CPI";
getProperty( serName, "unit" );

to achieve the same. Note here that the series' name is stored in serName; serName does not refer to the series itself.

A number of series properties are used when plotting and reporting, as given below. These properties are often dependant on the source of the series.

Properties are restricted to those listed below. Some properties are read only and can not be set. Property names are case insensitive.

accumulation
When getting, this returns a numerical value that describes the way in which the series accumulates. It can be set using a string or a number, for valid values, see the accumulate function.
aggregation
A description of the aggregation of the series, returned as a numerical value. This can be set using either a number or a string, with valid values described in the aggregate funtion.
area
The geographical area that the series applies to.
code
The code used by the publisher.
constant
A description of the measurement, being constant or current.
creation date
A string representing the creation date. This is a read only property.
description
A (longer) description of the series.
display name
The descriptive or display name of the series.
exclude from update
A numerical value that indicates if the series is excluded from automatic updates. A non-zero value indicates that it will not be updated automatically.
key
The key used to identify this series with. It is read only.
log
A log of events related to the series, often for internal use and read only.
notes
Data series notes, a general purpose area to keep series information.
publication number
The publication number in which this series is found.
release
The series release number.
release date
A description of the series release date.
seasonal
A description of the seasonality of the series.
series
The series name.
source
The source or publisher of the series. This is read only.
source opriginal
The original source or publisher of the series if it is a duplicated series. This is read only.
unit
The unit of measurement of observations.
variable
The variable name. This is read only.

Example usage

print( getProperty( "X", "unit" ) );

grade

Grade a value

Category: Other

Notes

This function can be used to grade an outcome. It takes pairs of arguments and evaluates the first one in the pair. If this argument evaluates to a non-zero value then it evaluates and returns the second argument in the pair, otherwise it proceeds to the next pair. If it reaches the end of the pairs it returns a missing value.

Arguments

This function takes pairs of arguments:

test
The test to evaluate to see if this grade applies.
grade
The grade to evaluate and return if the test yields a non-zero result.

This returns a missing value in case none of the tests evaluates to a non-zero result.

Example usage

print( "Examples - grade" );

# Grade a mark

print( grade( x &lt; 50, "Fail", x &lt; 80, "Pass", 1, "Pass with distinction" ) );

# Return a severity index of -2, -1, 0, 1 or 2

print( grade( x &lt; 20, -2, x &lt; 40, -1, x &lt; 60, 0, x &lt; 80, 1, 1, 2 ) );

gradient

Calculate the (numerical) gradient of a function

Category: User functions

Notes

This returns the numerically calculated gradient of a given user defined function. The user defined function must take a single argument as input.

Arguments

This function takes two required arguments:

fn
The name of the user defined function - a case sensitive string.
x
The value of the argument at which to calculate the gradient.
(Optional) h
The step size to use when approximating the gradient.

Example usage

print( "Examples - gradient" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Print the gradient at the origin

print( gradient( "rb", matrix( 2, 1, 0, 0 ) ) );

# Print the gradient at the minimum

print( gradient( "rb", matrix( 2, 1, a, a^2 ) ) );

hessian

Calculate the (numerical) hessian of a function

Category: User functions

Notes

This returns the numerically calculated hessian of a given user defined function. The user defined function must take a single argument as input.

The hessian is returned as a matrix, unless it contains a single element, in which case it is returned as a number.

Arguments

This function takes two required arguments:

fn
The name of the user defined function - a case sensitive string.
x
The value of the argument at which to calculate the hessian.
(Optional) tolGrad
The step size to use when approximating the gradient.
(Optional) tolHess
The step size to use when approximating the hessian.

Example usage

print( "Examples - hessian" );

# Define a function
# Rosenbrock with a = 1 and b = 100

# Parameters
a = 1;
b = 100;

define( "rb", "A",
{
  # Parameters
  a = parent( a );
  b = parent( b );

  # Note A is a column vector
  x = A[ 1; 1 ];
  y = A[ 2; 1 ];

  ( a - x ) ^ 2 + b * ( y - x ^ 2 ) ^ 2;
} );

# Print the hessian at the origin

print( hessian( "rb", matrix( 2, 1, 0, 0 ) ) );

# Print the hessian at the minimum

print( hessian( "rb", matrix( 2, 1, a, a^2 ) ) );

hpFilter

Hodrick-Prescott filter

Category: Data series

Notes

Calculates the Hodrick-Prescott filter for a given data series.

Arguments

This function takes up to two arguments:

x
The series for which to calculate the HP filter.
lambda
The lambda or smoothing paremeter to use, if not supplied, will use the square of the frequency times hundred.

Example usage

print( hpFilter( GDP ) );
print( hpFilter( CPI, 1600 ) );

if

If-then-else function

Category: Control

Notes

Implements if-then-else conditional logic. The structure of the function is

if( <condition>, <then>, <else (optional)> );

The condition is always evaluated and must reduce to a number. If the number is a missing value or zero, then the else part is executed. If the number is anything else, then the then part is executed. The return value is the evaluated expression, either <then> or <else> or if no <else> is given, the value of <condition> is returned. Thus one can do something like

yLabel = if( y > 0, "positive", "zero or negative" );

To cram multiple statements into the various sections, use curly braces or nest statements, for example

if( y > 0, { label = "Positive"; sgn = 1; }, if( y < 0, { label = "Negative"; sgn = -1; }, { label = "Zero"; sgn = 0 } ) );

Arguments

This function takes up to three arguments:

Condition
The condition is evaluated and if false (zero or missing), the else part is evaluated, if it is given.
Then
This section is required and is evaluated and returned if the condition is true, i.e. any number other than zero or missing.
(Optional) Else
This is evaluated and returned as the else condition if the condition is false (zero or missing). If this is omitted and the condition is false, the condition's value is returned instead.

Note that the condition must reduce to a number. If the number is zero or missing, the condition is considered false, otherwise it is considered true.

Example usage

y = 1;
if( y &gt; 0, { label = "Positive"; sgn = 1; }, if( y &lt; 0, { label = "Negative"; sgn = -1; }, { label = "Zero"; sgn = 0 } ) );
print( label, sgn );

y = 0;
if( y &gt; 0, { label = "Positive"; sgn = 1; }, if( y &lt; 0, { label = "Negative"; sgn = -1; }, { label = "Zero"; sgn = 0 } ) );
print( label, sgn );

y = -1;
if( y &gt; 0, { label = "Positive"; sgn = 1; }, if( y &lt; 0, { label = "Negative"; sgn = -1; }, { label = "Zero"; sgn = 0 } ) );
print( label, sgn );

incBeta

Incomplete beta function

Category: Mathematics

Notes

Calculates and returns the incomplete beta function.

Arguments

This function takes three arguments, z, a and b, all of which may be either a number or a series.

Example usage

print( incBeta( 0.2, 0.1, 0.3 ) );

invGammaCdf

Cumulative inverse gamma probability distribution

Category: Statistics

Notes

Returns the cumulative inverse gamma probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes three arguments:

x
The value at which to calculate the cdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( invGammaCdf(  0.5, 1, 1 ) );
print( invGammaCdf( 20.0, 1, 5 ) );

invGammaPdf

Inverse gamma probability distribution

Category: Statistics

Notes

Returns the inverse gamma probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( invGammaPdf( 0.2,  1, 2 ) );
print( invGammaPdf( 0.99, 1, 1 ) );

invGammaQnt

Quantiles of the inverse gamma probability distribution

Category: Statistics

Notes

Returns the quantiles of the inverse gamma probability distribution.

Arguments

This function takes three arguments:

p
The desired probability (between 0 and 1) for which to find the corresponding quantile.
alpha
The first (alpha) shape parameter of the distribution.
beta
The second (beta) rate parameter of the distribution.

Example usage

print( invGammaQnt( 0.01,   3,  4 ) );
print( invGammaQnt( 0.05, 100, 10 ) );
print( invGammaQnt( 0.10,  25, 15 ) );

isCharacter

Check if something is a character

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a character it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isCharacter( 'c' ) );

isColumnVector

Check if something is a column vector

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a matrix that has a single column it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isColumnVector( matrix( 5, 1,  1, 2, 3, 4, 5 ) ) );

isEmpty

Check if a series is empty

Category: Logical

Notes

Takes a series as argument and returns 1 if it is empty. It returns 0 if it is not empty. A series is empty if it has no observations.

Arguments

This function takes a single argument, namely the series to check for emptiness.

Example usage

print( isEmpty( empty () ) );
print( isEmpty( observe( dateIndex( 2010, 1, 1 ), 1, 2, 3 ) ) );

isMatrix

Check if something is a matrix

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a matrix it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isMatrix( 123 ) );

isMissing

Check if something is missing

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a missing value then it returns 1, otherwise it returns 0.

This can for example be used to check if a series has an observation for a given date, as in

Omit20100101 = isMissing( X[ dateIndex( 2010, 1, 1 ) ] );

which will store 1 into variable

Omit20100101

if the series does not have a valid observation for the given date.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isMissing( X[ dateIndex( 2010, 1, 1 ) ] ) );

isNumber

Check if something is a number

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a number it returns 1, otherwise it returns 0. Note that missing values are considered numbers.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isNumber( 123.45 ) );
print( isNumber( . ) );            # Missing value, which is a number

isRowVector

Check if something is a row vector

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a matrix that has a single row it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isRowVector( matrix( 1, 5,  1, 2, 3, 4, 5 ) ) );

isSeries

Check if something is a series

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a series it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isSeries( empty() ) );

isString

Check if something is a string

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a string it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isString( "abc" ) );

isVector

Check if something is a vector

Category: Logical

Notes

Takes a single argument and evaluates it. If it reduces to a matrix that has a single row or a single column it returns 1, otherwise it returns 0.

Arguments

This function takes and evaluates a single argument.

Example usage

print( isVector( matrix( 1, 5,  1, 2, 3, 4, 5 ) ) );

kalmanFilter

Kalman filter

Category: Data series

Notes

Simulate a Kalman filter.

This assumes a state equation

ξ_t+1 = F_tξ_t + v_t+1, var(v) = Q

and observation equation

y_t+1 = H'_tξ_t + A'_tx_t + w_t+1, var(w)=R

The filter can be simulated forwards and, optionally, backwards as well. It can also optionally calculate and return the implied value of the log likelihood function. This calculation is controlled by a number of 'flags' that are passed to the filter as explained below. When done, the filter can save results for future use.

Arguments

This function takes a minimum of four parameters, but can take several more:

(Optional) Model name and/or flags
If the first argument is a string, then this is assumed to be the model name and/or flags. There are three available flags:
- Minus sign -
  If the name is prefixed with a minus sign, then a backward simulation will be performed and the result of this simulation will be returned.
- Plus sign +
  If the name is prefixed with a plus sign, then the results will also be saved to disk for future reference. Otherwise the results will only be available as long as the calculation runs and be discarded afterwards.
- Percent sign %
  If the name is prefixed with a percentage sign then the implied log likelihood will also be calculated and the (total) log likelihood returned. If a minus sign flag is present, then the likelihood will be calculated and stored with the results, but the return value will still be the backward simulated state.
It is possible to only give flags and no name, e.g.
```
kalmanFilter( "-", F, Q, y, H );
```
and then the results will not be stored. Usually a name is provided, with or without flags, and then that name is used to store the results of the simulated to. The results that are available are discussed next.
- r
  The dimension of the state.
- n
  The dimension of the observation.
- l
  The number of observations.
- k
  The dimension of the exogenous observation.
- statePredict
  The lxr matrix of state predictions at each step. Each prediction is stored in a row.
- stateCovarPredict
  The l.rxr matrix of row-stacked state covariance predictions at each step.
- stateUpdate
  The lxr matrix of state updates at each step. Each update is stored in a row. This is also the value returned if no backward pass was performed and if no log-likelihood calculation was done.
- stateCovarUpdate
  The l.rxr matrix of row-stacked state covariance updates at each step.
- LLi
  If the log likelihood calculation was requested using the '%' flag, then this contains a lx1 vector of LLi values calculated at each step. These sum to the LL value discussed next.
- LL
  The log-likelihood value calculated for the filter. This is the sum of the LLi values and is also returned if the log-likelihood calculation was requested using the '%' flag and if a backward pass was not requested.
- stateBackward
  This is the smoothed or backward simulated state in case a backward pass was requested using the '-' flag. In that case, this will also be the value that the function returns.
- stateCovarBackward
  The state covariance matrices generated by the backward pass. These matrices are row-stacked so that the dimension of this result will be l.rxr .
State transition matrix F
A state transition matrix used to update the state with. This is usually a rxr matrix but, if F is unique in each time period, then row-stack l rxr state transition matrices so that this parameter is a l.rxr matrix, where l is the number of observations.
State covariance matrix Q
This is the state covariance matrix Q. It is also a rxr matrix with r the dimension of the state, but, if a unique covariance is required for each observation, then stack this into a l.rxr matrix
Observation matrix y
This contains the observations. Each row of this lxn matrix contains a vector of n observations. If this matrix is lxn+1, then it is assumed that it is an 'observation matrix' and that the first column contains the dates. This can either be given as a matrix or as a series, in which case a suitable observation matrix will be generated.
Observation mapping matrix H
This specifies the observation mapping matrix H. Note that this matrix will be transposed in order to calculate the observation estimate and error. This matrix is nxr but, if a unique map is required for each observation, provide a row-stack matrix with dimension l.nxr .
Optional observation covariance matrix R
This optional parameter can be omitted or a missing value (.) in which case the identity matrix will be used. It is a nxn matrix that specifies the observation covariance or, if a unique covariance for each observation is desired, it is a l.nxn matrix with l row-stacked covariance matrices.
Optional initial state ξ₀
This rx1 vector gives the initial state. If omitted or a missing value is provided, the initial state will be set to zero.
Optional initial state covariance P₀
This optional parameter can be omitted or replaced by a missing value, in which case the identity matrix will be used as initial covariance. Otherwise it must contain the rxr initial state covariance matrix estimate.
Optional exogenous mapping matrix A
This is the exogenous matrix A. If this is supplied then the next parameter (x) must also be provided. This matrix holds the exogenous map in a nxk matrix or, if a unique map is required for each observation, in a row-stacked n.lxk matrix. Here k is the dimension of the exogenous vector x.
Optional exogenous observations x
This must be provided if A is provided. It can be provided as a series in which case the exogenous dimension k is assumed to be 1 and A must have 1 column. Otherwise it can be provided as a matrix with k columns or, if the first column is a date, as a matrix with k+1 columns. The dates must agree with the observation dates. Each observation must be matched with an exogenous observation and thus this must have l rows.

Example usage

state = kalmanFilter( F, Q, y, H );
hp = kalmanFilter( "-", matrix( 2, 2, 2, -1, 1, 0 ), matrix( 2, 2, 1/1600 ), lGDP, matrix( 2, 1, 1 ) );

kurt

Sample kurtosis of a series

Category: Data series

Notes

Calculates and returns the (adjusted) sample kurtosis of the observations in a series. Note that the kurtosis of a normal distribution is 0.

Arguments

This function takes a single argument, being the series whose adjusted sample kurtosis is to be calculated and returned.

Example usage

print( kurt( X ) );

lag

Lag a series

Category: Data series

Notes

Used to lag a series. Any series can be lagged using braces (round brackets)

To return GDP lagged by one period for example, use

GDP(-1)

Likewise, to return GDP lagged by (a+b) periods, use

GDP(-(a+b))

Sometimes, however, it is easier to use the lag function to lag a series, as it allows for complex calculations to be performed on the fly, for example

lag( GDP / CPI, 1 )

Arguments

This function takes up to two parameters:

The series to lag.
(Optional) The amount of periods with which to lag; positive to lag, negative to lead and defaults to 1 if omitted.

Example usage

Xl1 = lag( X, 1 );                     # Same as X(-1)
Xl1 = lag( X );                        # Same as X(-1)
C2  = lag( sin( X ) / cos( X ), 2 );   # Complex series calculation
Xl2 = lag( X, 5 - 3 );                 # Complex lag amount calculation
X0  = lag( X(+1) );                    # Will lead and then lag X, so the result is X

laplaceCdf

Cumulative Laplace probability distribution

Category: Statistics

Notes

Returns the cumulative Laplace probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes up to three arguments:

x
The value at which to calculate the cdf.
(Optional) mu
The location of the distribution; if omitted use zero.
(Optional) b
The scale of the distribution; if omitted use one.

Example usage

print( laplaceCdf( 1.95 ) );
print( laplaceCdf( 110, 100, 10 ) );

laplacePdf

Laplace probability distribution

Category: Statistics

Notes

Returns the Laplace probability distribution function (pdf).

Arguments

This function takes up to three arguments:

x
The value at which to calculate the pdf.
(Optional) mu
The location of the distribution; if omitted use zero.
(Optional) b
The scale of the distribution; if omitted use one.

Example usage

print( laplacePdf( 2 ) );
print( laplacePdf( 110, 100, 10 ) );

laplaceQnt

Laplace probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the Laplace probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and is therefore also called the inverse cumulative distribution function.

Arguments

This function takes up to three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
(Optional) mu
The location of the distribution; if omitted use zero.
(Optional) b
The scale of the distribution; if omitted use one.

Example usage

print( laplaceQnt( 0.05 ) );
print( laplaceQnt( 0.01, 100, 10 ) );

last

Value of last observation of a series

Category: Data series

Notes

Return the value of the last observation of a data series. If the series is empty, it will return a missing value.

Arguments

This function takes a single argument, namely the series whose last observation value is to be returned.

Example usage

print( last( X ) );
print( ( last( X ) - first( X ) ) / ( lastDate( X ) - firstDate( X ) ) );
print( X[ lastDate( X ) ] );         # Same as last( X )

lastDate

Last observation’s date index

Category: Data series

Notes

Returns the date index of the last observation of a series. If the series is empty, it will return a missing value.

Arguments

This function takes a single argument, namely the series whose last observation's date index is to be returned.

Example usage

print( lastDate( X ) );
print( ( last( X ) - first( X ) ) / ( lastDate( X ) - firstDate( X ) ) );
print( X[ lastDate( X ) ] );         # Same as last( X )

left

Return the left part of a string

Category: String

Notes

Extracts and returns a portion of a string. It extracts the portion from the left a part of the string.

Arguments

This function takes two arguments:

String
The string from which to extract a substring.
Length
The length of the string to extract. This can not exceed the length of the string. The length can also not be negative. A length of zero will return an empty string.

Note that extraction starts from the left hand side.

Example usage

print( left( "abcdef", 2 ) );       # Will print ab

length

Length of a string

Category: String

Notes

Returns the length, in characters, of a string.

Arguments

This function takes a single argument, which must reduce to a string.

Example usage

print( length( "abc" ) );

levyCdf

Cumulative Levy probability distribution

Category: Statistics

Notes

Returns the cumulative Levy probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes three arguments:

x
The value at which to calculate the cdf.
mu
The location parameter of the distribution.
c
The scale parameter of the distribution.

Example usage

print( levyCdf( 2, 1, 2 ) );
print( levyCdf( 1, 0, 3 ) );       # The mode

levyPdf

Levy probability distribution

Category: Statistics

Notes

Returns the Levy probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
mu
The location parameter of the distribution.
c
The scale parameter of the distribution.

Example usage

print( levyPdf( 2, 1, 2 ) );
print( levyPdf( 1, 0, 3 ) );       # The mode

levyQnt

Quantiles of the Levy probability distribution

Category: Statistics

Notes

Returns the quantiles of the Levy probability distribution.

Arguments

This function takes three arguments:

p
The desired probability, between 0 and 1, for which to find the corresponding quantile.
mu
The location parameter of the distribution.
c
The scale parameter of the distribution.

Example usage

print( levyQnt( 0.50, 0, 3 ) );
print( levyQnt( 0.99, 5, 8 ) );
print( levyQnt( 0.01, 2, 7 ) );

limit

Limit a data series to a subset of its observations

Category: Data series

Notes

Takes two dates and a series and returns a series with observations limited to observations between these two dates, both inclusive.

Arguments

This function takes three arguments:

The (inclusive) date from which to return observations.
The (inclusive) date to which to return observations.
The series whose observations to limit to the given date range.

Example usage

from   = dateIndex( 2010, 5, 1 );
subset = limit( from, from + 2, X );   # Will return at most three observations
                                       # At from, from + 1 and from + 2
# Calculate the average between 2010 and 2015
average( limit( dateIndex( 2010,  1,  1 ),
                dateIndex( 2015, 12, 31 ), X ) );

# Calculate the average of X from May 2010 to Apr 2011
Y = average( limit( dateIndex( 2010, 5, 1 ),
                    dateIndex( 2011, 4, 1 ), X ) );

ln

Natural logarithm

Category: Mathematics

Notes

Calculates the natural logarithm of its argument, either a number or a series.

Arguments

This function takes a single argument and returns its natural logarithm. It can be either a number or a series.

Example usage

print( ln( 1 ) );
print( ln( e() ) );
print( ln( exp( 3 ) ) );
print( ln( 100 ) );
dlx = d( ln( X ) );

log10

Log base 10

Category: Mathematics

Notes

Calculates and returns the base 10 logarithm of its argument.

Arguments

This function takes a single argument and returns its logarithm base 10. It can be either a number or a series.

Example usage

print( log10( 1 ) );
print( log10( 10 ) );
print( log10( 100 ) );
print( log10( 1000 ) );
print( log10( e() ) );
print( log10( exp( 10 ) ) );

logNormCdf

Cumulative log normal probability distribution

Category: Statistics

Notes

Returns the cumulative log normal probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes up to three arguments:

x
The value at which to calculate the cdf.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( logNormCdf( 1.95 ) );
print( logNormCdf( 110, 100, 10 ) );

logNormPdf

Log normal probability distribution

Category: Statistics

Notes

This returns the log normal probability distribution function (pdf).

Arguments

This function takes up to three arguments:

x
The value at which to calculate the pdf.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( logNormPdf( 2 ) );
print( logNormPdf( 110, 100, 10 ) );

logNormQnt

Log normal probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the log normal probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and is therefore also called the inverse cumulative distribution function.

Arguments

This function takes up to three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( logNormQnt( 0.05 ) );
print( logNormQnt( 0.01, 100, 10 ) );

lowIncGamma

Lower incomplete gamma function

Category: Mathematics

Notes

Calculates and returns the lower incomplete gamma function.

Arguments

This function takes two arguments, s and x, both of which may be either a number or a series.

Example usage

print( lowIncGamma( 1, 1.23 ) );
print( 1 - exp( -1.23 ) );           # Same as lowIncGamma( 1, 1.23 )
print( lowIncGamma( 1, X ) );

lower

Lower case string

Category: String

Notes

Converts a string to its lowercase version.

Arguments

This function takes a single argument, which must reduce to a string. The string is converted to lowercase and returned.

Example usage

print( lower( "UPPER" ) );

matrix

Create a matrix

Category: Matrix

Notes

Creates and loads a matrix.

The first argument is the number of rows and the second is the number of columns. This will create a matrix with the given number of rows and columns. Any remaining values will be read into the matrix row by row. Thus

matrix( 2, 2, 1, 2, 3, 4 )

will create a 2x2 matrix with values

1 2
3 4

Note that not all values need to be given. Thus

matrix( 2, 2, 1 )

will for example create a matrix with 1 as first element and zeroes elsewhere, thus the values would be

1 0
0 0

Arguments

This function takes two or more arguments:

Rows
The number of rows in the matrix.
Columns
The number of columns in the matrix.
(Optional) Entries to load into the matrix in a row by row fashion.

Example usage

A    = matrix( 2, 3 );
print( A );
I3x3 = matrix( 3, 3,   1, 0, 0,   0, 1, 0,   0, 0, 1 );
print( I3x3 );

matrix0

Return a matrix filled with zeroes

Category: Matrix

Notes

Returns the zero matrix. The return value is a corresponding matrix filled with zeroes.

Arguments

This function takes up to two arguments:

Rows
The number of rows in the returned matrix.
(Optional) Columns
The optional number of columns. If omitted, it will be the same as the number of rows.

Example usage

print( matrix0( 10    ) );
print( matrix0( 10, 3 ) );      # Same as first 3 columns of the line above

matrix1

Return a matrix filled with ones

Category: Matrix

Notes

Returns a matrix filled with ones. The return value is a corresponding matrix filled with ones.

Arguments

This function takes up to two arguments:

Rows
The number of rows in the returned matrix.
(Optional) Columns
The optional number of columns. If omitted, it will be the same as the number of rows.

Example usage

print( matrix1( 10    ) );
print( matrix1( 10, 3 ) );      # Same as first 3 columns of the line above

matrixAsSeries

Convert a matrix into a data series of observations

Category: Matrix

Notes

Converts a matrix into a data series.

There are two alternatives, either using a matrix that contains dates and values or supplying the first observation as an argument and the matrix as values. The first alternative is described first.

The first column (or row) must contain the date indices and the second column (or row) the observed values. The date indices are converted as is and assumed to make sense given the current evaluation frequency. This is often used to convert data stored in an observation matrix back into a data series.

The first column of an observation matrix typically holds date indices and can be extracted using the matrixGetColumns function for example. Suppose an observation matrix is stored in obsMat and a matrix of residuals in eMat, then

eSeries = matrixAsSeries( matrixCatColumns( matrixGetColumns( obsMat, 1 ), eMat ) )

can be used to extract the date column from the observation matrix and then concatenate the residuals to this and, finally, to convert this back to a series.

Note that the date indices need not be consecutive nor unique. If a date index is repeated, the last value found will replace the earlier ones.

Alternatively the first argument can be a date and then that is used as the date of the first observation in the matrix, which is now a row- or column vector and which is supplied as the second argument.

Arguments

This function takes a single argument, namely a matrix to convert to a data series.

The matrix must have 2 columns or 2 rows. If it has 2 columns then the first column is used as date indices and the next as observation values, otherwise the first row is used as date indices and the second as observation values.

Alternatively this function can also take two arguments. If the fist argument is a date and the second a row or column vector, then the date will be used to generate consecutive dates for the observations.

Example usage

obsMat = matrix( 5, 2,  dateIndex( 2010, 1, 1 ), 1,  dateIndex( 2011, 1, 1 ), 2,
                        dateIndex( 2012, 1, 1 ), 3,  dateIndex( 2013, 1, 1 ), 4,
                        dateIndex( 2014, 1, 1 ), 5 );
print( matrixAsSeries( obsMat ) );         # Will create a series starting in 2010/1/1 with values [ 1, 2, 3, 4, 5 ]

matrixC

Return a column matrix filled with a given number

Category: Matrix

Notes

Returns a column matrix filled with a given number. The return value is a column matrix, i.e. a matrix with a single column, filled with the specified number.

Arguments

This function takes two arguments:

Value
The value to fill the column matrix with.
Rows
The number of rows to create the matrix with. The matrix will always only have a single column.

Example usage

print( matrixC( e(), 10 ) );      # 10 x e

matrixCatColumns

Concatenate the columns of two or more matrices

Category: Matrix

Notes

Concatenates the columns of at least two or more matrices passed as arguments, and returns the result.

Arguments

This function takes two or more matrices as arguments. The matrices must all have the same number of rows.

Example usage

B = matrix( 1, 2, 1, 1 );
C = matrix( 1, 2, 2, 2 );
D = matrix( 1, 2, 3, 3 );
E = matrix( 1, 2, 4, 4 );
F = matrix( 1, 2, 5, 5 );
A = matrixCatColumns( B, B, C, C, D, E, F );
print( A );

matrixCatRows

Concatenate the rows of two or more matrices

Category: Matrix

Notes

Concatenates the rows of at least two or more matrices passed as arguments, and returns the result.

Arguments

This function takes two or more matrices as arguments. The matrices must all have the same number of columns.

Example usage

B = matrix( 1, 2, 1, 1 );
C = matrix( 1, 2, 2, 2 );
D = matrix( 1, 2, 3, 3 );
E = matrix( 1, 2, 4, 4 );
F = matrix( 1, 2, 5, 5 );
A = matrixCatRows( B, B, C, C, D, E, F );
print( A );

matrixColumns

Number of columns in a matrix

Category: Matrix

Notes

Returns the number of columns in a matrix. This is equivalent to the shorthand cols function.

Arguments

This function takes a single argument, the matrix for which to return the number of columns.

Example usage

print( matrixColumns( A ) );

matrixDelColumns

Remove a given set of columns from a matrix

Category: Matrix

Notes

Returns a new matrix consisting of the original matrix but with some columns removed. A column may be removed multiple times, but it has no effect the second time.

Arguments

This function takes two or more arguments:

A matrix as first argument.
A list of columns to remove from it. The columns may be specified either as indices or as a series or a matrix.

Example usage

print( matrixDelColumns( matrix( 3, 3,  1, 0, 0,  0, 1, 0,  0, 0, 1 ), 2, 3 ) );

matrixDelRows

Remove a given set of rows from a matrix

Category: Matrix

Notes

Returns a new matrix consisting of the original matrix with some rows removed. A row may be removed multiple times, but it will have no effect the second time.

Arguments

This function takes two or more arguments:

A matrix as first argument.
A list of rows to remove from it. The rows may be specified either as indices or as a series or a matrix.

Example usage

print( matrixDelRows( matrix( 3, 3,  1, 0, 0,  0, 1, 0,  0, 0, 1 ), 2, 3 ) );

matrixDiag

Convert a vector into a diagonal matrix

Category: Matrix

Notes

Given a vector as input, this will put the elements of the vector on the diagonal of a new matrix and return that matrix. The input can be either a matrix with a single row or a single column. The off diagonal elements will be zero.

Arguments

This function takes a single argument which is the matrix with only a single row or single column. It returns a square matrix with those entries on the diagonal.

Example usage

print( matrixDiag( A ) );

matrixEig

Calculate the eigenvalues of a square matrix

Category: Matrix

Notes

This will calculate the eigenvalues of a square matrix and return it. It returns a matrix with two columns. Each row contains an eigenvalue with the first column containing its real and the second column containing its imaginary part. As eigenvalues may be complex, it is thus returned with two columns for each eigenvalue.

Note that the eigenvalues are sorted from largest (in absolute value) in the return matrix.

This uses the QR algorithm and is meant for small to medium sized matrices. For large matrices, the matrixEigBig should be used in stead. Keep in mind that all calculations are performed in arbitrary precision which carries a huge performance penalty for complex calculations such as this one. However, it is worth the wait.

Arguments

This function takes a single argument which is the square matrix whose eigenvalues it is to calulate.

Example usage

print( matrixEig( A ) );

matrixEigBig

Calculate some of the eigenvalues of a large square matrix

Category: Matrix

Notes

This will calculate the largest (in magnitude) eigenvalue and associated eigenvector of a square matrix and return it. It returns a matrix with two columns. The last row contains the eigenvalue while the first couple of rows contain the eigenvector. Thus the returned matrix will have one more row that the input matrix. Each row contains the real part of the eigenvector or eigenvalue in the first column and the imaginary part in the second column. This is similar to the matrixEig function and caters for the situation where the eigenvalue and eigenvector may be complex.

This uses the Arnoldi algorithm and is meant for larger matrices. For small to medium sized ones, consider using the QR based matrixEig function. Keep in mind that all calculations are performed in arbitrary precision which carries a huge performance penalty for complex calculations such as this one. However, it is worth the wait.

Arguments

This function takes two arguments. The first is the square matrix whose eigenvalues are desired and the second is the number of Arnoldi restarts required. An aribitrary value of 10 is typically fine. Thiss will calculate the largest (in magnitude) eigenvalue and associated eigenvector and return it, with the eigenvector in the first couple of rows and the eigenvalue in the last row. Thus the returned matrix will have one more row than the input matrix. The returned matrix will have 2 columns, one for the real and one for the imaginary part of the eigenvector and eigenvalue.

Example usage

print( matrixEigBig( A, 10 ) );

matrixEigVect

Calculate the eigenvectors of a square matrix

Category: Matrix

Notes

This will calculate the eigenvectors of a square matrix and return it. It takes as inputs the square matrix as well as the eigenvalues for which to calculate eigenvectors and returns a matrix with the same number of rows as the input matrix and two (!) columns for each eigenvector. The reason for two columns per eigenvector is because this is essentially a complex numbered calculation and the return matrix has a column for the real and imaginary part of each complex valued entry in the eigenvector. The eigenvalues are likewise complex and stored in a matrix with two columns, one for the real and one for the imaginary part, and a row for each (complex) eigenvalue.

Note that a symmetric matrix will have only real values eigenvalues and eigenvectors for example. If the eigenvalues are real valued, the output will still, for consistency, have two columns for each input eigenvalue.

Arguments

This function takes two arguments:

The square matrix for which to caculate eigenvectors
A matrix containing the eigenvalues for which to calculate eigenvectors. The matrix has two columns and a row for each eigenvalue. Each row contains one eigenvalue, with its real part in the first column and its imaginary part in the second column. This is typically the output from the matrixEig function. Note that the eigenvalues can be supplied as a matrix with only a single column, or the second column may contain only zeros. In either case, the calculation will not use complex arithmetic but for consistency the output matrix will still have two columns for each input eigenvalue. The imaginary column of each eigenvector will then simply contain zeros in all positions.

Example usage

print( matrixEigVect( A ) );

matrixElDiv

Element by element division of two matrices

Category: Matrix

Notes

Takes two matrices with the same dimensions and returns a new matrix, with the same dimension, and where each element is the ratio between the corresponding elements in the two input matrices. Thus if the input matrices are A and B for example, with A the first and B the second argument, returns C where

c[i;j] = a[i;j] / b[i;j]

Arguments

This function takes two arguments, namely the two matrices to divide element wise.

Example usage

print( matrixElDiv( A, B ) );

matrixElMul

Element by element multiplication of two matrices

Category: Matrix

Notes

Takes two matrices with the same dimensions and returns a new matrix, with the same dimension, and where each element is the product of the corresponding elements in the two input matrices. Thus if the input matrices are A and B for example, returns C where

c[i;j] = a[i;j] * b[i;j]

Arguments

This function takes two arguments, namely the two matrices to multiply element wise.

Example usage

print( matrixElMul( A, B ) );

matrixElPow

Element by element raise to a power of two matrices

Category: Matrix

Notes

Takes two matrices with the same dimensions and returns a new matrix, with the same dimension, and where each element is the corresponding element in the first input matrix raised to the power given by the corresponding element in the second matrix. Thus if the input matrices are A and B for example, returns C where

c[i;j] = a[i;j] ^ b[i;j]

Arguments

This function takes two arguments, namely the two matrices to element by element raise to the power.

Example usage

print( matrixElPow( A, B ) );

matrixGetColumns

Extract a given set of columns from a matrix

Category: Matrix

Notes

Returns a new matrix consisting of the columns extracted from a given matrix. A column may be extracted multiple times.

Arguments

This function takes two or more arguments:

A matrix as first argument.
A list of columns to extract from it. The columns may be specified either as indices or as a series or a matrix.

Example usage

print( matrixGetColumns( matrix( 3, 3,  1, 2, 3,  1, 2, 3,  1, 2, 3 ), 1, 1, 1, 2, 3 ) );

matrixGetRows

Extract a given set of rows from a matrix

Category: Matrix

Notes

Returns a new matrix consisting of the rows extracted from a given matrix. A row may be extracted multiple times.

Arguments

This function takes two or more arguments:

A matrix as first argument.
A list of rows to extract from it. The rows may be specified either as indices or as a series or a matrix.

Example usage

print( matrixGetRows( matrix( 3, 3,  1, 1, 1,  2, 2, 2,  3, 3, 3 ), 1, 1, 1, 2, 3 ) );

matrixHess

Decompose a matrix into Hessenberg form

Category: Matrix

Notes

Returns the Hessenberg matrix H where A = P H P'.

Arguments

This function takes a single argument which is the matrix to decompose.

Example usage

print( matrixHess( A ) );

matrixI

Return the identity matrix

Category: Matrix

Notes

Returns the identity matrix.

Arguments

This function takes up to two arguments and returns a corresponding identity matrix:

Rows
The number of rows in the returned identity matrix.
(Optional) Columns
The optional number of columns. If omitted, it will be the same as the number of rows.

Example usage

print( matrixI( 10    ) );
print( matrixI( 10, 3 ) );      # Same as first 3 columns of the line above

matrixKronProd

Return the Kronecker product of two matrices

Category: Matrix

Notes

Takes two matrices as argument and returns the Kronecker product of them.

Arguments

This function takes two arguments, namely the two matrices to multiply.

Example usage

print( matrixKronProd( A, B ) );

matrixObs

Create an observation matrix

Category: Matrix

Notes

Takes a combination of series and constants and uses that to create an observation matrix. The observation matrix is often used in building models.

A typical command would be

matrixObs( 1, X1, X2, X3 )

This will create a matrix with 5 columns. It will determine all the common dates between the 3 series X1, X2 and X3 and use that to extract observations into the observation matrix. The first column of the matrix will contain the date that was used to construct that row. In this example, the next column will be filled with ones and would typically represent a constant in some model. The next three columns will contain the relevant observations from X1, X2 and X3 respectively.

Arguments

This takes any number of arguments, but at least one must be a series. Arguments may be numerical constants or observation series.

Example usage

print( matrixObs( 1, X, Y ) );

matrixQR

Decompose a matrix into QR form

Category: Matrix

Notes

Returns the QR decomposition of the matrix A so that A = Q R and Q'Q = I. The returned matrix is an augmented matrix containing the two matrices [ Q R ]. The matrix is also constructed so that R have positive values on its diagonal.

Arguments

This function takes a single argument which is the matrix to decompose.

Example usage

print( matrixQR( A ) );

matrixR

Return a row matrix filled with a given number

Category: Matrix

Notes

Returns a row matrix filled with a given number.

Arguments

This function takes two arguments:

Value
The value to fill the row matrix with.
Columns
The number of columns to create the matrix with. The matrix will always only have a single row.

Example usage

print( matrixR( e(), 10 ) );      # 10 x e

matrixRand

Create a random matrix

Category: Matrix

Notes

Creates and returns a random matrix.

Arguments

This function takes up to three arguments and returns a matrix filled with random numbers based on these arguments. The numbers are all between 0 and 1, but the number of random digits each one contains can be set via the third parameter.

Rows
The number of rows in the returned matrix.
(Optional) Columns
The optional number of columns. If omitted, it will be the same as the number of rows.
(Optional) Digits
The number of digits to generate for each random number, defaults to 10 digits per number.

Example usage

print( matrixRand( 10    ) );
print( matrixRand( 10, 3 ) );
print( matrixRand( 10, 20, 30 ) );   # Lots of random digits

matrixRows

Number of rows in a matrix

Category: Matrix

Notes

Returns the number of rows in a matrix. This is equivalent to the shorthand rows function.

Arguments

This function takes a single argument, the matrix for which to return the number of rows.

Example usage

print( matrixRows( A ) );

matrixSolveCg

Solve A.x = b for x using conjugate gradients

Category: Matrix

Notes

Returns the solution x to A.x = b calculated using conjugate gradients.

Arguments

This function will solve A.x = b for x using conjugate gradients. It takes the following arguments.

A
The matrix A defining the system. It should be symmetric and positive definite.
b
The vector b.
(Optional) x0
The initial guess. If this is omitted, zero will be used.
(Optional) maxIter
The maximum number of iterations to use.
(Optional) tol
The tolerance to use when checking for termination.

Example usage

print( matrixSolveCg( A, b ) );

matrixSolveSd

Solve A.x = b for x using steepest descent

Category: Matrix

Notes

Returns the solution x to A.x = b calculated using steepest descent.

Arguments

This function will solve A.x = b for x using steepest descent. It takes the following arguments.

A
The matrix A defining the system. It should be symmetric and positive definite.
b
The vector b.
(Optional) x0
The initial guess. If this is omitted, zero will be used.
(Optional) maxIter
The maximum number of iterations to use.
(Optional) tol
The tolerance to use when checking for termination.

Example usage

print( matrixSolveSd( A, b ) );

matrixSum

Sum of all matrix elements

Category: Matrix

Notes

Returns the sum of all the elements of a matrix.

Arguments

This function takes one argument, a matrix, and returns the sum of all its elements.

Example usage

print( matrixSum( A ) );

matrixT

Return the transposed of a matrix

Category: Matrix

Notes

Returns the transposed matrix.

Arguments

This function takes a matrix as argument and returns its transposed.

Example usage

print( matrixT( A ) * A );

matrixTrace

Trace of a square matrix

Category: Matrix

Notes

Returns the trace given a square matrix.

Arguments

This function takes one argument, namely a square matrix, and returns its trace.

Example usage

print( matrixTrace( matrixI( 100 ) ) );

matrixVec

Vectorise a matrix

Category: Matrix

Notes

Vectorises a matrix, i.e. it returns a column vector containing all the columns of the matrix.

Arguments

This function takes a single argument, namely the matrix to vectorise.

Example usage

print( matrixVec( matrix( 2, 2, 1, 2, 3, 4 ) ) ); # Will return [ 1 3 2 4 ]'

matrixVech

Half-vectorise a matrix

Category: Matrix

Notes

Half-vectorises a matrix, i.e. it returns a column vector containing half of the matrix entries. The matrix must be square and is assumed to be symmetric. It returns the lower half.

Arguments

This function takes a single argument, namely the matrix to half-vectorise.

Example usage

print( matrixVech( matrix( 2, 2, 1, 2, 2, 3 ) ) ); # Will return [ 1 2 3 ]'

matrixX

Return a matrix filled with a given number

Category: Matrix

Notes

Returns a matrix filled with a given number.

Arguments

This function takes up to three arguments:

Value
The value to fill the matrix with.
(Optional) Rows
The number of rows in the returned matrix, if omitted use 1.
(Optional) Columns
The number of columns, if omitted will use the same as the number of rows.

Example usage

print( matrixX( pi() ) );
print( matrixX( pi(), 1, 10 ) );      # A row vector with 10 pis inside
print( matrixX( pi(), 5, 10 ) );      # Lots of pi

matrixXx

Return the product of a transposed matrix with itself

Category: Matrix

Notes

Takes a source matrix X and returns the product X'X.

It is typically used on an observation matrix and is more efficient than performing the calculations manually. A range of the source matrix may also be supplied in order to for example exclude the first column of date indices from the calculation.

Arguments

This function takes up to five arguments. The first argument is the source matrix X and the rest are optional and used to select the range from X to use in the calculation:

Source matrix
The matrix X to use in the calculation.
(Optional) Starting row
The row of X from which to start the calculations, will use 1 if omitted.
(Optional) Starting column
The column of X from which to start, will use 1 if omitted.
(Optional) Ending row
The final row to include in the calculations, if omitted will use the number of rows of X.
(Optional) Ending column
The final column to include in the calculations, if omitted will use the number of columns of X.

Example usage

M = matrix( 10, 3,  1, 1, 1,   2, 2, 2,   3, 3, 3,   4, 4, 4,   5, 5, 5,   6, 6, 6,   7, 7, 7,   8, 8, 8,   9, 9, 9,   10, 10, 10 );
print( matrixXx( M ) );
print( matrixXx( M, 1, 2 ) ); # Do not use first column

max

Maximum of a series

Category: Data series

Notes

Calculates and returns the maximum of all the observations in a series.

To calculate the maximum of a series between say 2010 and 2015, combine this with the limit function, for example

M = max( limit( dateIndex( 2010, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Arguments

This function takes a single argument, namely the series whose maximum is to be extracted and returned.

Example usage

# Calculate the maximum of X
M = max( X );

# Calculate the maximum between 2010 and 2015
max( limit( dateIndex( 2010,  1,  1 ),
            dateIndex( 2015, 12, 31 ), X ) );

# Calculate the maximum of X between May 2010 and Apr 2011
Y = max( limit( dateIndex( 2010, 5, 1 ),
                dateIndex( 2011, 4, 1 ), X ) );

median

Median of a series

Category: Data series

Notes

Calculates and returns the median of the observations in a series.

Arguments

This takes a series as a single argument, and returns the median.

To calculate the median of a series between say 2010 and 2015, combine this with the limit function, for example

M = median( limit( dateIndex( 2010, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Example usage

# Calculate the median of X
median( X );

merge

Merge series

Category: Data series

Notes

Merges two or more series by creating a new series with merged observations. If there is any overlap for any given date, then the first series' observation value is used.

Arguments

This function takes any number of series as arguments.

Example usage

A = observe( dateIndex( 2010, 1, 1 ), 5, 5, 5, 5, 5, 5, 5 );
B = observe( dateIndex( 2011, 1, 1 ), 2, 2, 2, 2, 2, 2, 2 );
print( merge( A, B ) ); # Will print a series with 5, 5, 5, 5, 5, 5, 5, 2
print( merge( B, A ) ); # Will print a series with 5, 2, 2, 2, 2, 2, 2, 2

mid

Return a portion of a string

Category: String

Notes

Extracts and returns a portion of a string.

Arguments

This function takes up to three arguments:

String
The string from which to extract a substring.
Start
The starting point of the extraction, with 1 being the first character.
(Optional) Length
The length of the string to extract, if omitted will extract the remainder of the string.

Example usage

print( mid( "abcdef", 2, 3 ) );       # Will print bcd

min

Minimum of a series

Category: Data series

Notes

Calculates and returns the minimum of all the observations in a series.

To calculate the minimum of a series between say 2010 and 2015, combine this with the limit function, for example

M = min( limit( dateIndex( 2010, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Arguments

This function takes a single argument, namely the series whose minimum is to be extracted and returned.

Example usage

# Calculate the minimum of X
M = min( X );

# Calculate the minimum between 2010 and 2015
min( limit( dateIndex( 2010,  1,  1 ),
            dateIndex( 2015, 12, 31 ), X ) );

# Calculate the minimum of X between May 2010 and Apr 2011
Y = min( limit( dateIndex( 2010, 5, 1 ),
                dateIndex( 2011, 4, 1 ), X ) );

month

Return the month of a date index

Category: Date

Notes

This will return the month represented by a number. The number is interpreted as a date index using the current frequency. If the interval spans more than a month then the month of the last date in the interval is returned.

Arguments

This function takes a single argument which is the date index. It returns the month in the current frequency represented by the number.

Example usage

di = dateIndex( 1975, 4, 1 )
print( month( i ) ); # Prints 4

normCdf

Cumulative normal probability distribution

Category: Statistics

Notes

Returns the cumulative normal probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes up to three arguments:

x
The value at which to calculate the cdf.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( normCdf( 1.95 ) );
print( normCdf( 110, 100, 10 ) );

normPdf

Normal probability distribution

Category: Statistics

Notes

Returns the normal probability distribution function (pdf).

Arguments

This function takes up to three arguments:

x
The value at which to calculate the pdf.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( normPdf( 2 ) );
print( normPdf( 110, 100, 10 ) );

normQnt

Normal probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the normal probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and is therefore also called the inverse cumulative distribution function.

Arguments

This function takes up to three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
(Optional) mu
The mean of the distribution; if omitted use zero.
(Optional) sigma
The standard error of the distribution; if omitted use one.

Example usage

print( normQnt( 0.05 ) );
print( normQnt( 0.01, 100, 10 ) );

not

Logical not

Category: Logical

Notes

Evaluates its argument and if the resulting number is a missing or zero value, it returns 1, otherwise it returns 0.

If the argument is a series, then all values in the series will be evaluated and a 0 or 1 returned for each one respectively, depending on whether it is a non-zero value or a zero value respectively.

Arguments

This function takes a single argument:

Number or series
This argument must reduce to a number or series. It returns 1 if the value is zero or missing, or a series where the corresponding observations are either 1 or 0.

Example usage

print( not( 1 ) );

observe

Create a series with some observations

Category: Data series

Notes

Manually creates a new series of observations.

Arguments

This function takes at least two arguments:

First date
The date index of the first observation.
Observations
This can be any number of (subsequent) observations. The first observation is loaded with the first argument as a date and the rest are each loaded for the subsequent date as determined by the frequency.

Example usage

# Series { 1 }
X = observe( dateIndex( 2010, 1, 1 ), 1 );

# Series { 1 2 3 }
X = observe( dateIndex( 2010, 1, 1 ), 1, 2, 3 );

# Series where observation date index and value agree
I = dateIndex( 2010, 1, 1 );
X = observe( I, I, I + 1, I + 2, I + 3, I + 4, I + 5 );

# Series with cubes
X = observe( I, 1^3, 2^3, 3^3, 4^3, 5^3, 6^3 );

ols

Ordinary least squares

Category: Data series

Notes

Fits an ols model and notes the results in the calculation log.

If the first argument is a string then it is assumed to be the name of the model and is used to save the results back for later use. Otherwise the first argument is assumed to be the left hand side or dependent variable as a series. The following arguments are taken to be the right hand side or independent variables and can be a mixture of series and constants, although using more than one constant will result in a model that can not be solved.

The returned value is the predicted values according to the model. The calculation log can be inspected to see the results of the estimation.

Arguments

This function takes one optional argument followed by at least two other arguments:

(Optional) Model name
If the first argument is a string, then this is assumed to be the model name and the results of the estimation will be saved using that name. If the name used is, for example, "ols", as seen below
```
ols( "ols", y, 1, x1, x2 );    # Will store results to ols
```
then the adjusted R Square can for example be obtained using
```
RSqAdj = dataSetValue( "ols", "nRSqAdj" );
```
To simply estimate the model and not store back any results, simply omit this first argument, for example
```
ols( y, 1, x1, x2, x3 );     # Fit y on a constant and x1, x2 and x3
```
The model name must be a valid name, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign, a minus sign and a number sign.
When a model is estimated it generates a lot of output in the log. To silence this output, prefix the name with a minus sign, for example
```
ols( "-ols", y, 1, x1, x2 );
```
If a name is provided the results are normally only stored in memory, and not saved to disk as well. Thus the model's results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the model name, prefix the name with a plus sign, e.g.
```
ols( "+ols", y, 1, x1, x2 );
```
If the model name is prefixed with a number sign e.g.
```
ols( "#ols", y, 1, x1, x2 );
```
then a new report with the name "ols" (excluding the number sign) will be created and the results will be stored into that report. The table summary will contain a formatted overview of the model and the table itself will display the actual, fitted and residual values. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
command to reduce clutter.
If results are stored to a model using a model name, the following arguments are available keys to extract results with:
- Matrices
  - bMat
    The column vector holding the estimated coefficient values.
  - bTestMat
    A matrix holding coefficient diagnostic values. Each row corresponds to one estimated coefficient with the the first row giving that coefficient's standard error. The second column gives the t value and the last column the probability that the coefficient is 0 as calculated using the t value.
  - eMat
    A column vector containing residuals.
  - e2Mat
    A column vector containing squared residuals.
  - invXxMat
    The inverse of the X'X matrix.
  - obsMat
    A matrix of observations. The first column is the date index, the next the left hand side or dependent observation and then the remaining columns is the right hand side or independent observations.
  - xMat
    A matrix containing all the right hand side or independent variable observations.
  - xxMat
    This contains the product X'X where X is the matrix of independent observations.
  - xyMatThe matrix Xy' where X is the matrix of independent and y is the column vector of dependent observation values.
  - yHatMat
    A column vector containing estimated or fitted values.
  - yMat
    A column vector containing the left hand side or dependent observation values.
- Values
  - nAic
    The Akaike information criteria.
  - nAicc
    The corrected AIC.
  - nArch
    The ARCH effects test statistic.
  - nArchProb
    The probability of accepting the null of no ARCH effects (low values are bad).
  - nBic
    The Bayesian or Schwarz information criteria.
  - nBreuschGodfrey
    The Breusch-Godfrey measure of residual autocorrelation. Note that by default this statistic is based on an estimation that is not zero padded.
  - nBreuschGodfreyProb
    The probability of accepting the null hypothesis of no residual autocorrelation. Low values reject this hypothesis and are therefore bad.
  - nBreuschPagan
    The Breusch-Pagan measure of residual homoscedasticity.
  - nBreuschPaganProb
    The probability of accepting the null hypothesis of homoscedastic residuals (low values are bad).
  - nDf1
    The first degrees of freedom, which is the number of non-constant right hand side variables.
  - nDf2
    The second degrees of freedom, which is the number of data points, i.e. rows in the X matrix, less the number of right hand side variables, i.e. columns in the X matrix.
  - nDW
    The Durbin-Watson measure of residual autocorrelation.
  - nExpVar
    The explained variance in the model.
  - nF
    The model's overall f value.
  - nFProb
    The probability that the model does not explain the variance, based on the f value.
  - nJarqueBera
    The Jarque-Bera test statistic for normal (guassian) residuals.
  - nJarqueBeraProb
    The probability of rejecting the null of gaussian residuals (low values are bad).
  - nJarqueBera
    The Jarque-Bera test statistic for normal (guassian) residuals.
  - nJarqueBeraProb
    The probability of rejecting the null of gaussian residuals (low values are bad).
  - nKurt
    The residual kurtosis, 3 indicates "normal" kurtosis.
  - nLHood
    The likelihood of the model.
  - nLLHood
    The log likelihood.
  - nMse
    The mean square residual, calculated using df2.
  - nObs
    The number of observations used in fitting the model.
  - nRmse
    The root mean square residual.
  - nRSq
    The R Square goodness of fit measure.
  - nRSqAdj
    The adjusted R Square measure.
  - nSkew
    The residual skewness.
  - nSumE
    The sum of the residuals, which should be zero or close to zero.
  - nSumE2
    The sum of squared residuals.
  - nSumE3
    The sum of cubed residuals.
  - nSumE4
    The sum of squared squared residuals.
  - nTotalVar
    The total variance in the left hand side variable.
  - nUnexpVar
    The unexplained variance in the model, same as sumE2.
  - nX
    The number of right hand side or independent variables in the model, including any constants.
  - nYAvg
    The average of the left hand side or dependent variable.
- Series
  - e
    Series of in sample residuals.
  - projected
    Series of projected values, which may extend beyond the estimation sample.
Dependent series
The series of dependent variable observations. It is best to limit this in order to use a less than full estimation sample, for example the following can be used to estimate using only the given sample's data.
```
ols( limit( estSampleStart, estSampleEnd, y ), 1, x1, x2 ... );
```
The projected series will then use all of the available data contained in the independent variables to calculate and may well extend beyond the restricted sample. Although any of the independent variables could also be restricted to achieve the same estimation sample it will result in the side effect of that independent variable not being available outside of the estimation sample and the projected values will only be in-sample.
Independent series
Any number of independent series. These may be either data series or constants.

Example usage

USGDP = dataFred( "GDPCA" );
ols( dLn( USGDP ), 1, dLn( USGDP(-1) ), dLn( USGDP(-2) ), dLn( USGDP(-3) ) ); # Simple AR(3) model

omit

Omit a given value from a series

Category: Data series

Notes

Omits all occurrences of a given value in a series.

Arguments

This function takes two arguments:

Series
A series whose observations will be omitted if the observation value equals a given value.
Value to look for
The value to find and omit. Observations with this value will be omitted in the returned series.

Example usage

print( omit( X, 999 ) );        # Omit all observations valued 999

omitZero

Omit all zero valued observations from a series

Category: Data series

Notes

Omits all zero value observations from a series.

Arguments

This function takes a single argument:

Series
The series from which to omit zero valued observations. It returns a new series, which is the same as the input series, except that all zero valued observations have been removed.

Example usage

print( omitZero( X ) );        # Omit all zero valued observations

or

Logical or

Category: Logical

Notes

Evaluates the arguments one by one and if any number is found that is not missing or zero, stops and returns 1. If all arguments have been evaluated and nothing but missing values and/or zeroes were found, 0 is returned.

Note that this means that not all arguments will be evaluated. Arguments are only evaluated up to the first non-zero or non-missing value.

Arguments

This function takes two or more arguments, all of which must reduce to a number.

Zero or missing values are taken to be FALSE and anything else is taken to be TRUE. This will "or" all the results, but will exit early if possible.

Example usage

print( or( 1, 2, 3 ) );

p

Percentage change

Category: Data series

Notes

Calculates the percentage change of its argument, which must reduce to a series.

For a series y( t ) this returns the series

y(t) / y(t-1) - 1

This is meant for regular frequencies such as monthly, quarterly and annually but is not appropriate for daily series. In daily series there are often gaps due to weekends and holidays and then the pPrev function may be more appropriate. This only works for observations spaced one bar apart while the pPrev function will operate on any subsequent observations, no matter the distance they are apart.

Arguments

This function takes a single argument:

Series
The series whose percentage change to calculate.

Example usage

GrowthPct = 100 * p( X );

pPrev

Percentage change in subsequent observations

Category: Data series

Notes

Calculates the percentage change between subsequent observations.

It is especially appropriate for daily observations, where there are often gaps due to weekends and holidays, that should be ignored when calculating percentage changes, for example. For regular frequencies, such as monthly, the p function may be more appropriate.

Arguments

This function takes a single argument:

Series
The series for which to calculate the percentage changes.

Example usage

P1 = pPrev( X );             # Percentage change

pa

Annualised percentage change

Category: Data series

Notes

Calculates and returns the annualised percentage change in the series it takes as argument.

For a series y( t ) of monthly observations for example this will calculate

( y(t) / y(t-1) ) ^ 12 - 1

Arguments

This function takes a single argument, namely a series.

Example usage

Y = pa( X );
Y = ( X / X(-1) ) ^ 12 - 1;       # Same if monthly

paPrev

Annualised percentage change in subsequent observations

Category: Data series

Notes

Calculates the annualised percentage changes in subsequent observations.

This is especially for use when the frequency is daily. Then the simple pa does not work well, as it calculates

( y(t) / y(t-365) ) ^ 365 - 1

This works by ensuring observations are at least a year apart and also by ensuring that the previous observation is the most recent one that is still at least a year away from the current one. It takes an optional annualisation factor, which by default is 365 for daily series.

Arguments

This function takes one required and one optional argument:

Series
The series for which to calculate annualised percentage changes.
(Optional) Annualisation factor
The optional annualisation factor, by default this is the periods per year for the frequency, e.g. 12 for monthly or 365 for daily.

Example usage

ANN = paPrev( X );

pacf

Partial autocorrelation function

Category: Data series

Notes

Calcualtes and returns the partial autocorrelation function asa series.

The first observation, at index 0, will be 1. The next observation, at index 1, will be the first order partial autocorrelation and so on. Note that here the divisor will be n and not n - k.

Arguments

This function takes two arguments, namely the series for which to calculate the partial autocorrelation function and secondly the maximum order to calculate.

Series
The series for which to calculate partial autocorrelations.
(Optional) order
The maximum order partial autocorrelation to calculate. The returned series will typically have 1 more value than this number, with the first value being 1 for the zero order partial autocorrelation. It may have fewer observations if it was unable to calculate the autocorrelation at a given order. Here the zero order partial autocorrelation is 1.

Example usage

print( pacf( X ) );

parent

Evaluate in parent context

Category: User functions

Notes

This will evaluate its arguments in the parent context.

Arguments

This can be used to evaluate an expression in the parent context.

Whenever a function is called, a new child context is created and especially the variables in the parent context are not availabe. This function provides a way to access the parent context and its variable values. Parent variables are accessible to the child context but child variables are not directly available to the parent context. Formatting, however, can be set in the child context and this will be reflected in the parent context as well. To share variables from the child context with the parent, use a data set as shown below.

Example usage

print( "Examples - parent" );

# Define a function in the parent context
# Note it adds 2 to its argument

define( "Inc", "x", x + 2 );

# Define a variable in the parent context

x = 10;

# Define a function - when called this
# will execute in the child context

define( "fn1",
{
  print( "fn1" );
  x = 5;                  # Defined in child context
  y = x + parent( x );    # Read from parent, y is 15
  z = parent( call( "Inc", x ) ); # Now z is 12!
                                  # x comes from parent

  format( 3 );            # Set in child and parent
  print( x, y, z );       # (formatting)

  parent( x = 20 );       # Set in the parent context

  dataSetSave( "fn1" );   # Save child values to a
                          # dataset so parent can get
                          # it later

  # This will call the parent function
  x = call( "Inc", 5 );   # x now 5 + 2 = 7
  print( x );

  # Define a function in the child context
  # Note here we add only 1
  define( "Inc", "x", x + 1 );

  x = call( "Inc", 5 );   # x now 5 + 1 = 6
  print( x );

  x = parent( call( "Inc", 5 ) );  # In parent context
  print( x );                      # x now 5 + 2 = 7

} );

print( "Running" );
call( "fn1" );
print( x );               # Will print 20 using
                          # formatting (and value)
                          # set in child

dataSetLoad( "fn1" );     # Load child values
                          # from a data set saved
                          # earlier and print it
print( dataSetValue( "fn1", "z" ) );

paretoCdf

Cumulative Pareto probability distribution

Category: Statistics

Notes

Returns the cumulative Pareto probability distribution function (cdf).

The returned value, which lies between 0 and 1, gives the probability that a random value drawn from this distribution will be smaller than x.

Arguments

This function takes three arguments:

x
The value at which to calculate the cdf.
xm
The scale parameter of the distribution.
alpha
The shape parameter of the distribution.

Example usage

print( paretoCdf( 1.95, 1, 5 ) );
print( paretoCdf( 110, 100, 10 ) );

paretoPdf

Pareto probability distribution

Category: Statistics

Notes

Returns the Pareto probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
xm
The scale parameter of the distribution.
alpha
The shape parameter of the distribution.

Example usage

print( paretoPdf( 2, 1, 5 ) );
print( paretoPdf( 110, 100, 10 ) );

paretoQnt

Pareto probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the Pareto probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and is therefore also called the inverse cumulative distribution function.

Arguments

This function takes three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
xm
The scale parameter of the distribution.
alpha
The shape parameter of the distribution.

Example usage

print( paretoQnt( 0.05,   5,  1 ) );
print( paretoQnt( 0.01, 100, 10 ) );

periodogram

Generate a periodogram or periodic trend for a series

Category: Data series

Notes

Generates and returns a series' periodogram or, alternatively, its trend based on the periodogram and optionally create a report containing the periodogram or trend.

Arguments

This function will calculate and return the periodogram, but, for a different set of arguments, will return the trend fitted to the series based on the periodogram. It typically takes a single namely the series whose periodogram is to be calculated and returned. However, a threshold can also be specified which will then be used to generate the trend as described below.

Also, optionally, a first (string) argument can be specified to control the way in which the periodogram is calculated and to create a report of the periodogram or trend that was calcualted as a result.

(Optional) The calculation flags and report name.
This optional argument can contain calculation flags and a name that can be used to save results to or to generate a report with.
There are two algorithms. The first is based on an arbitrary precision DFT and the second on a double precision FFT. The first is the default and is suitable for small series, say with 50 or fewer observations. The other one, although not applied in arbitrary precision, is much faster and should be used for series with more observations.
As described below, the tilde (~) flag should be used to request the FFT.
The following are supported in this argument.
- (Optional) Periodogram name
  If the first argument is a string, then this is assumed to be the periodogram name and the it will be saved using that name. If the name used is, for example, "p1", as seen below
```
periodogram( "p1", x1 );    # Will store results to p1
```
  then the number of observations can for example be obtained using
```
n = dataSetValue( "p1", "nObs" );
```
  To generate the periodogram without storing back any results, simply omit this first argument, for example
```
periodogram( x1 ); # Calculate for series x1
```
  The periodogram name must be valid, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign (+), a minus sign (-), a number sign (#) and a tilde (~).
  This command will generate a lot of output in the log but it can be silenced by prefixing the name with a minus sign, for example
```
periodogram( "-p1", x1 );
```
  or even
```
p = periodogram( "-", x1 );
```
  If a name is provided the results are only stored in memory and not saved to disk as well. Thus the results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the report name, prefix it with a plus sign, e.g.
```
periodogram( "+p1", x1 );
```
  If the report name is prefixed with a number sign e.g.
```
periodogram( "#p1", x1 );
```
  then a new report with the name "p1" (excluding the number sign and any other flags) will be created and the results will be stored into that report. The table summary will contain the report and the table itself will contain the intensities and periods or the series and its fitted trend. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
  command to reduce clutter.
  Note that the periodogram report is created in the index frequency and the trend report in the same frequency as the calculation.
  The report by default use the arbitrary precision DFT algorithm, which can be extremely slow for big series, say with 50 or more observations. To use the FFT, which gives approximately the same intensities, use the tilde (~) flag as illustrated below
```
periodogram( "~", x1 );
```
  If results are stored using a report name, the following arguments are available keys to extract results with later:
  - nCycles
    The number of cycles used to generate the trend if the trend was requested.
  - nExplained
    The percentage of the total variance explained by the trend if the trend was requested.
  - nObs
    The number of observations including any inserted zeroes used to fill gaps left by missing values.
  - nObsGaps
    The number of observations provided to the algorithm. This may include gaps that will be padded with zeroes.
  - nObsFFT
    The number of observations used by FFT if it was selected.
  - nFFTPow2
    The power of 2 used by FFT it was selected.
  - nFFTAdj
    The frequency adjustment factor used by FFT.
  - periodogram
    If the trend alternative is used then the periodogram is not returned, but it is available using this key.
  - abMat
    A matrix containing the spectrum (a and b) in columns 1 and 2.
  - IMat
    A matrix containing the frequency, period, intensity and relative intensity.
- Series
  The time series for which to construct a periodogram or trend. If it contains any missing values those gaps will be filled with zero values. If the FFT was requested the observations will be zero-padded to the closest power-of-2 sample size.
- Optional Threshold
  If a threshold is specified it will be used to fit a trend to the series using the resulting periodogram and the trend will be returned in stead of the relative intensities. The threshold can be positive and larger than or smaller than 1 or negative. Each of these ranges will lead to it being interpreted differently, as described below.
  - Positive and larger than or equal to one
    The value is interpreted as a number of cycles, e.g. 10, in which case the 10 most prominent cycles will be used to fit the trend with.
  - Positive but smaller than one
    The value is interpreted as the desired percentage of the total variance that the trend should explain. If a value of 0.9 is given for example, then the most prominent cycles will be added to the trend until the total variance it explains exceeds this amount.
  - Negative
    A negative value, say -0.2, will be interpreted as follows. All cycles that in this case explain more than 20% of the total variance will be added and used to construct the trend.
- Optional After
  The number of trend observations to extrapolate and append at the end of the sample.
- Optional Before
  The number of trend observations to extrapolate and insert before the start of the sample.

This function returns a series containing the relative (%) intensities or, if the trend alternative is selected, the fitted trend as a series.

Example usage

periodogram( X );

pi

Ratio between circumference and diameter of a circle

Category: Mathematics

Notes

Returns an approximation to the mathematical constant pi.

Arguments

This function does not take any arguments, but still requires empty parentheses to indicate that this is a function.

Example usage

accuracy( 200 ); c0 = pi();

polyRoots

Calculate roots of a polynomial

Category: Mathematics

Notes

Calculates and return the roots of a polynomial.

Arguments

This function takes as argument the coefficients of a polynomial, starting with the constant or lowest power coefficient and preceding to the highest power. The number of coefficients given determines the degree of the polynomial. If n coefficients are given then the polynomial is of degree n - 1.

This function returns a matrix with a row for each root and with the first column containing the real and the second the imaginary part of the root. If there are no roots, e.g. if the polynomial is just a constant, this will return a missing value.

Coefficients
The polynomial coefficients. These can be given either individually or as a series or even a matrix. Whatever is given will be flattened (row first if applicable) and used as polynomial coefficients, as long as the first coefficient is the coefficient of the lowest power and so on.

Example usage

# Calculate roots of 1 + 2x + 3x^2 + 4x^3 + 5x^4
print( polyRoots( 1, 2, 3, 4, 5 ) );

Lag a series of subsequent observations

Category: Data series

Notes

Is used to lag a series of irregular but subsequently observed series, such as daily series.

A daily series often has gaps in it due to weekends and holidays, and instead of using Saturday as observation date of an observation made on Friday, this will move the date to Monday. It will use the observation dates where available, when determining the lagged observation date but, where the lag (or lead) takes it out of sample, it will simply increment (or decrement) the observation index accordingly.

Arguments

This takes two parameters, of which the second is optional.

Series
The series to lag.
(Optional) Number of periods
The amount of periods with which to lag; positive to lag, negative to lead, defaults to 1 if omitted.

Example usage

Xl1 = prev( X, 1 );                    # Same as X(-1) for daily series
Xl1 = prev( X );                       # Same as X(-1) for daily series

print

Print arguments to the log

Category: Output

Notes

Evaluates all the arguments and print them to the log. It will print characters, strings, numbers and series.

If multiple arguments are given, they will be printed on the same line, except for series, which are printed differently. Numbers are formatted according to the current format settings. The format settings can be set through the format function.

Arguments

This function takes any number of arguments. The arguments will be evaluated and then printed to the log one by one.

Example usage

print( "Hallo there." );
print( 'a', 'b', 'c' );
print( 123.45 );
print( 1 / sqrt( pi () ), e(), gamma( 10 ) );
print( X );

py

Percentage change per year

Category: Data series

Notes

Calculates and returns the year on year percentage change in the series it takes as argument.

For a series y( t ) of monthly observations for example, this will calculate

y(t) / y(t-12) - 1

Arguments

This takes a single argument, namely a series.

Example usage

Y = py( X );
Y = X / X(-12) - 1;       # Same if monthly

pyPrev

Annual percentage change in subsequent observations

Category: Data series

Notes

Calculates percentage changes over a year.

This is especially for use when the frequency is daily. Then the simple py does not work well, as it calculates

y(t) / y(t-365) - 1

Arguments

This function takes a single argument:

Series
The series for which to calculate percentage changes.

Example usage

YOY = pyPrev( X );

quarter

Return the quarter of a date index

Category: Date

Notes

This will return the quarter represented by a number. The number is interpreted as a date index using the current frequency. If the interval spans more than a quarter then the quarter of the last date in the interval is returned.

Arguments

This function takes a single argument which is the date index. It returns the quarter in the current frequency represented by the number.

Example usage

di = dateIndex( 1975, 4, 1 )
print( quarter( i ) ); # Prints 2

rand

Draws a random number

Category: Mathematics

Notes

Creates and returns a random number. The number is between 0 (inclusive) and 1 (exclusive) and has a given number of digits.

If called without any arguments this will return a single random number, otherwise it will return a series of random numbers and the arguments determine where the series starts, how many numbers to draw and how many digits to draw per number.

Arguments

If no arguments are given this simply returns a single random number. Otherwise this takes up to three arguments and returns a series of random numbers:

First date
The first date for which to draw a random number.
Amount of numbers
The number of random numbers to draw; the default is 1 or () to draw a single random number.
Digits per number
The number of digits to draw per number; the default is to use the current precision setting.

Example usage

print( rand () );                                     # Single number
print( rand ( dateIndex( 2010, 1, 1 ), 100, 10 ) );   # A series with 100 random numbers each containing up to 10 digits and starting 2010/1/1

randFast

Quickly draws a random number

Category: Mathematics

Notes

This is similar to the rand function, but draws random numbers with less digits. The random number is between 0 (inclusive) and 1 (exclusive) and has only 9 digits, which should suffice in many circumstances.

If the current precision is less than 9 digits, the number of digits is scaled down to roughly half the current precision.

If called without any arguments this will return a single random number, otherwise it will return a series of random numbers and the arguments determine where the series starts and how many numbers to draw.

Arguments

If no arguments are given this simply returns a single random number. Otherwise this function takes up to two arguments and returns a series of random numbers:

First date
The first date for which to draw a random number.
Amount of numbers
The number of random numbers to draw, the default is 1 or () to draw a single random number.

Example usage

print( randFast () );                                 # Single number
print( randFast ( dateIndex( 2010, 1, 1 ), 100 ) );   # A series with 100 random numbers and starting 2010/1/1

randSeed

Seeds the random number generator

Category: Mathematics

Notes

Seeds the currently selected random number generator.

If you select a different random number generator you need to seed it again. If you do not seed it, it will use a seed generated from the current system time and number of ticks.

Arguments

This function takes a single argument:

Seed
The seed to seed the random number generator with.

Example usage

randSeed( 1234567890987654321 );

randType

Select the type of random number generator

Category: Mathematics

Notes

This selects the type of random number generator to use in subsequent calculations. There are two types of generators included in fdm.

MixMax
Random numbers are generated using the mixmax generator, which makes it especially suitable for Monte Carlo type studies - for more information, including links to the source, see https://en.wikipedia.org/wiki/MIXMAX_generator .
Squares
Random numbers are generated using the squares counter based algorithm which is very fast. See https://arxiv.org/abs/2004.06278 for more information.

Note that the default random number generator is the squares one.

Arguments

This function can be called without any arguments, in which case it will report the current generator. It will output a string, either

    mixmax

    squares

based upon which is currently used to generate random numbers with.

Alternatively this can be called with a single string argument which then selects the algorithm to use from now on. The argument must evaluate to one of these strings otherwise an error will be generated.

Example usage

randType( "mixmax" );

repeat

Create a series by repeating a sequence

Category: Data series

Notes

Creates a new series by repeating a given sequency of observation a given number of times.

A sequency can contain any number of values, so to for example repeat the value 3 a hundred times starting in 2010/01/01, use the following

repeat( dateIndex( 2010, 1, 1 ), 100, 3 );

On the other hand, to repeat ( 3, 4, 5 ) a hundred times and return a new series with 300 observations in, use

repeat( dateIndex( 2010, 1, 1 ), 100, 3, 4, 5 );

Note that missing values are also allowed in the sequency.

Arguments

This function takes at least three arguments:

Date
The date assigned to the first observation.
Number of times
The number of times to repeat the sequency.
Sequency
This is the first entry of the repeat sequency and subsequent arguments are used to construct the full repeat sequency.

Example usage

print( repeat( dateIndex( 2010, 1, 1 ), 100, 1, 2, 3 ) );     # Will create a series contain 100 ( 1, 2, 3 )'s

replace

Replace a given value with another value in a series

Category: Data series

Notes

Replaces a given value in a series with another value. Either the value to look for or the value to replace can be a missing value.

Arguments

This function takes three arguments:

Series
A series in which to replace observations.
Value to look for
The value to find and replace with the new value. If this is a missing value, then gaps in the series will be filled in with the replacement value.
Value to replace with
The new value to replace the found value with. If this is a missing value, then observations with the supplied value to look for will be omitted.

Example usage

print( replace( X, 1, 999 ) );

replaceMissing

Replace missing values in a series

Category: Data series

Notes

Evaluates a series and replaces all missing values with a given value. It starts by traversing from the first to the last observation in the series and, if there are any gaps in the data, fill them in with observations with the given value.

Note that only observations between the first and last observations of the data series are filled in. Nothing is changed outside these dates and, if the series is empty, an empty series will be returned.

Arguments

This function takes two arguments:

Series
A series whose missing values between the first and last observation will all be replaced.
Value
The value to replace missing observations with. This must reduce to a number, not a missing value.

Example usage

print( replaceMissing( X, 0 ) );

replaceZero

Replace zero values in a series

Category: Data series

Notes

Evaluates a series and replaces all zero values observation values with a given new value. If the new value is the missing value, it will effectively delete all these observations from the series.

Arguments

This funtion takes two arguments:

Series
A series whose zero valued observation will all be replaced.
Value
The value to replace these observations with. This must be a number of can be the missing value.

Example usage

print( replaceZero( X, 10 ) );

reportAdd

Create a new report and store it into the document

Category: Report

Notes

This is used to create a report and store it back into the document. It offers a variety of report templates and creates a new report based on the selected template and the data added to that template. Note that report names need not be unique in a document. Thus this function will always create and add a new report, even if one with a similar name already exists. It is therefore strongly suggested that this function be preceded by a

reportDelete

call to prevent clutter from developing in the document.

Arguments

This fucntion takes five or more arguments:

The name of the newly created report.
The description of the newly created report.
The summary of the newly created report.
The report template, a case insensitive string value that is one of
- Plain - create a normal table. Each series will have only a level line in the table and plot.
- PlainCycle - same as the plain format but with a cycle indicator taken as the last series added to the report.
- Table - create a normal table. Each series will have a level and accumulation line in the table and the plot.
- TableCycle - same as the table format but with a cycle indicator taken as the last series added to the report.
- AFE - actual, fitted, error table, where the first series is assumed to be an actual value, the next a fitted value and the final a residual or error value.
- AFECycle - actual, fitted, error table with an added downward cycle indicator, where the first series is assumed to be an actual value, the next a fitted value, then a residual or error and finally a cycle indicator value.
The first data series to add to the report.
Any additional data series to add to the report.

The return value is 1 if a "Table" type report was generated, 2 if a "TableCycle", 3 if an "Afe" and 4 if an "AfeCycle" type report was generated. If a "TableCycle" report is requested but only one series is provided, this will generate a "Table" type report and return 1.

Example usage

reportAdd( "CPI", "CPI report", "", "Table", CPI ); # Create a table report containing CPI
fit = ewma( 0.95, GOLDPM );                         # Report on an exponential smoothing model
reportAdd( "Fit", "Exponential smoothing", "", "AFE", GOLD, fit, GOLD - fit );

reportDelete

Delete a report

Category: Report

Notes

This will delete a report with a given name and with frequency the same as that of the calculation context. If multiple reports with that name exist in the frequency, then one is arbitrarily chosen and removed. This returns 1 when a report was deleted and 0 when none with the given name was found in the calculation context's frequency.

Arguments

This function takes one argument which is the name of the report to delete.

Example usage

reportDelete( "CPI" ); # Delete the CPI report if it exists

rezBeta

Regularized incomplete beta function

Category: Mathematics

Notes

Calculates and returns the regularised incomplete beta function.

Arguments

This function takes three arguments, z, a and b, all of which may be either a number or a series.

Example usage

print( rezBeta( 1, 2, 3 ) );

rezGammaLo

Regularized lower gamma function

Category: Mathematics

Notes

Calculates and returns the regularised lower gamma function, often referred to as P.

Arguments

This function takes two arguments, s and x, both of which may be either a number or a series.

Example usage

print( rezGammaLo( 1, 1.23 ) );

rezGammaUp

Regularized upper gamma function

Category: Mathematics

Notes

Calculates and returns the regularised upper gamma function, often referred to as Q.

Arguments

This function takes two arguments, s and x, both of which may be either a number or a series.

Example usage

print( rezGammaUp( 1, 1.23 ) );

right

Return the right part of a string

Category: String

Notes

Extracts and returns a portion of a string. The substring is extracted from the rightmost part.

Arguments

This function takes two arguments:

String
The string from which to extract a substring.
Length
The length of the string to extract. The length of the substring can not be negative or exceed the length of the string. A length of zero will return an empty string. Note that extraction starts from the right hand side.

Example usage

print( right( "abcdef", 2 ) );       # Will print ef

round

Round to nearest integer

Category: Mathematics

Notes

Rounds its argument to the nearest integer.

If the fractional part is one half (0.5) then this will round away from zero, e.g. 0.5 becomes 1.0 and -0.5 becomes -1.0.

Arguments

This function takes a single argument, either a number or a series, which it will round and return.

Example usage

print( round(  0.1 ) ); # Prints  0.0
print( round(  0.5 ) ); # Prints  1.0
print( round(  0.9 ) ); # Prints  1.0
print( round(  1.0 ) ); # Prints  1.0
print( round( -0.1 ) ); # Prints  0.0
print( round( -0.5 ) ); # Prints -1.0
print( round( -0.9 ) ); # Prints -1.0
print( round( -1.0 ) ); # Prints -1.0

rows

Number of rows in a matrix

Category: Matrix

Notes

Returns the number of rows in a matrix. This is equivalent to the longhand matrixRows function.

Arguments

This function takes a single argument, the matrix for which to return the number of rows.

Example usage

print( rows( A ) );

scenariosAdd

Add scenarios to the document

Category: Simulate

Notes

This function creates and adds scenarios to the document. Scenarios, as a document item, can then be viewed the same as other document items. Scenarios can be given a name, such as "Recession", not necessarily unique, and then to this can be added any number of observation matrices. Each matrix contains the outcomes, in columns, of a given variable of interest. The outcomes for variables such as GDP and CPI can be simulated and stored in an observation matrix, with one matrix for each variable of interest. These matrices lumped together then form the scenarios document item.

An observation matrix, in the case of scenarios, holds many different outcomes for a single variable. These outcomes are often simulated using some random variable or using past shocks. The first column of the observation matrix holds the date indices for each row. Then the next column holds the simulated outcomes for the first scenario for the variable of interest, the next column the next scenario and so on. Thus, after the date column, each subsequent column holds the simulated outcome of a given scenario for the variable.

The first column of each observation matrix is used to construct a common date index set and this is then retained for each matrix. Thus rows in a matrix that are not common to all matrices will be discarded. Only rows with date indices common to all matrices will be retained.

Note that this will simply add a new item to the document, even if there is already another one with the same name. The scenariosDelete function can be used to remove an existing item before adding a new one if required.

Arguments

This function two or more parameters.

Name
The name to save the scenarios as.
Variable name or observation matrix
The second and following parameters are the names of and the actual observation matrices. If a parameter evaluates to a string, it will be used to label the next observation matrix with. If a parameter evaluates to a matrix, it will be added to the scenario as the next observation matrix.

Any number of scenario names and observation matrices can be supplied. They are simply appended to the scenario. The return value is the number of observation matrices added.

Example usage

print( scenariosAdd( "Recession 1", "GDP", gdpMatrix, "CPI", cpiMatrix );
print( scenariosAdd( "Recession 2", gdpMatrix, cpiMatrix );

scenariosDelete

Delete scenarios

Category: Simulate

Notes

This will delete a scenarios item with a given name and with frequency the same as that of the calculation context. If multiple scenarios with that name exist in the frequency, then one is arbitrarily chosen and removed. This returns 1 when scenarios was deleted and 0 when none with the given name was found in the calculation context's frequency.

Arguments

This function takes one argument which is the name of the scenarios to delete.

Example usage

scenariosDelete( "Recession" ); # Delete the Recession scenarios if it exists

semester

Return the semester of a date index

Category: Date

Notes

This will return the semester represented by a number. The number is interpreted as a date index using the current frequency. If the interval spans more than a semester then the semester of the last date in the interval is returned.

Arguments

This function takes a single argument which is the date index. It returns the semester in the current frequency represented by the number.

Example usage

di = dateIndex( 1975, 1, 1 )
print( semester( i ) ); # Prints 1

setProperty

Set a series property

Category: Data series

Notes

Sets the property of a given series to a given value.

Series are unique in that they also carry properties, which can be set to various string values. This allows for the setting or deleting of those properties. If a property is set to a value this will return 1. If a property is deleted then -1 is returned. If a property's deletion is requested, and that property does not exist at present for the series, then 0 is returned.

Arguments

This function takes three arguments:

Series name
Note that this must reduce to a string, which is equal to the series name. This is not the series itself.
Property name
This is the name of the property to set. It must also reduce to a string and can not be empty. The property name is case insensitive.
Property value
This is the new property value, which must reduce to a string or a number, depending on the property. If it is the empty string "" or missing numberical value then the property will be deleted, otherwise it will be set to this value.

There are a number of properties, such as 'display name', that influences how series are plotted and reported. For more details, see the getProperty function. Also note that some properties are read only and setting them will result in an error.

Example usage

setProperty( "X", "unit", "Index 2010=100" );

shockAdd

Simulate and add a random shock

Category: Simulate

Notes

This function simulates a random shock given a distribution type and some parameters and then treats that shock as an add factor. The shock is then added to a current value and the adjusted value is returned. The shock percentile can be supplied or it can be drawn randomly between 0 and 1 or between supplied ranges. Although a large number of distributions can be used, only some will work well for generating shocks with. Some distributions only generate positive values for example and these will not work in situations where negative shocks are also possible.

Arguments

This function takes four, five or six arguments, as follows.

Current value
The current value that will be shocked.
Distribution type
The type of distribution used to generate the add factor shock. This is one of the following strings or numbers.
1. 1 or "beta"
  Use the beta distribution to generate the shock. Then the first parameter corresponds to the alpha or shape parameter of the distribution and the second parameter is the beta or shape parameter of the distribution.
2. 2 or "cauchy"
  Use the cauchy distribution to generate the shock. In this case the first parameter is x0 or the mean of the distribution and the second is gamma or the standard error of the distribution.
3. 3 or "chisq"
  Use the chi square distribution to generate the shock. In this case the first parameter is the degrees of freedom of the distribution and the second parameter is ignored.
4. 4 or "exp"
  Use the exponential distribution to generate the shock. Here the first parameter is the lambda or rate (inverse shape) parameter of the distribution. The second parameter is ignored.
5. 5 or "f"
  Use the F distribution to simulate the shock, with the first parameter the first or numerator degrees of freedom and the second parameter the second or denominator degrees of freedom.
6. 6 or "gamma"
  Use the gamma distribution to generate the shock with. The first parameter is the alpha or shape parameter of the distribution and the second the beta or rate parameter of the distribution.
7. 7 or "invgamma"
  Use the inverse gamma distribution to draw the shock from. The first parameter is again alpha or the shape parameter and the second is beta or the rate parameter of the distribution.
8. 8 or "lognorm"
  Use the log normal distribution to generate the add factor with. The first parameter is then the mean and the second the standard error of the distribution.
9. 9 or "norm"
  Use the normal distribution to generate shocks with. Here too, as in the previous case, the first parameter is the mean and the second the standard error of the distribution.
10. 10 or pareto
  Use the pareto distribution to generate the shock with. In this case the first parameter is xm or the scale parameter of the distribution and the second parameter is alpha or the shape parameter of the distribution.
11. 11 or "t"
  Use the t distribution to generate the shock with. Here the first parameter specifies the degrees of freedom of the distribution and the second parameter is ignored.
12. 12 or "uniform"
  Use the uniform distribution to generate the shock with. The first parameter is the minimum of the distribution's range and the second parameter is its maximum.
13. 13 or "weibull"
  Use the weibull distribution to generate the shock with. For this the first parameter specifies lambda or the scale parameter and the second kappa or the shape parameter of the distribution.
First parameter
This numerical value specifies the first parameter of the distribution. Its meaning depends on the distribution selected to generate the shock with and can be found in the list of distributions given above.
Second parameter
The numerical value of the second parameter. As with the first, its meaning depends on the distribution type and it can be found in the list above.
Optional shock magnitude or lower bound
If this parameter is omitted, then the shock magnitude will be drawn randomly and be between 0 and 1 (0 and 100%). The drawn magnitude will then be used to generate the shock with. Alternatively, this parameter can be used to specify a given shock, e.g. 0.999 for a 99.9% shock. If this is followed by another parameter, then this is the lower bound and the next parameter the upper bound, e.g. 0.8 and 0.9, to generate a random shock between 80 and 90% in magnitude.
Optional upper bound
If this parameter is supplied, it specified the upper bound of the shock magnitude. The lower bound and upper bound then together form a range of valid shocks from which a shock is drawn randomly in order to calculate an add factor with.

Example usage

print( shockAdd( 100, "norm", 0, 15 ) );   # Random intelligence
print( shockAdd( 0, "weibull", 1, 1 ) );

shockMul

Simulate and multiply with a random shock

Category: Simulate

Notes

This function simulates a random shock given a distribution type and some parameters and then treats that shock as a multiplier. The shock is first added to a specified constant, such as 1, and then the given value is multiplied with the result and returned. This is similar to the shockAdd function and as there the shock percentile can be supplied or it can be drawn randomly between 0 and 1 or between supplied ranges.

Arguments

This function takes five, six or seven arguments. It is similar to the shockAdd function, but with the added multiplier parameter. The parameters are as follows.

Current value
The current value that will be shocked.
Constant
The generated shock will be added to this constant. Afterwards the current value will be multiplied by this sum and the result returned. Thus if the random shock is r and this is c, and the current value is cv, this function will return
```
cv * ( c + r )
```
Distribution type
The type of distribution used to generate the add factor shock. This is one of the following strings or numbers.
1. 1 or "beta"
  Use the beta distribution to generate the shock. Then the first parameter corresponds to the alpha or shape parameter of the distribution and the second parameter is the beta or shape parameter of the distribution.
2. 2 or "cauchy"
  Use the cauchy distribution to generate the shock. In this case the first parameter is x0 or the mean of the distribution and the second is gamma or the standard error of the distribution.
3. 3 or "chisq"
  Use the chi square distribution to generate the shock. In this case the first parameter is the degrees of freedom of the distribution and the second parameter is ignored.
4. 4 or "exp"
  Use the exponential distribution to generate the shock. Here the first parameter is the lambda or rate (inverse shape) parameter of the distribution. The second parameter is ignored.
5. 5 or "f"
  Use the F distribution to simulate the shock, with the first parameter the first or numerator degrees of freedom and the second parameter the second or denominator degrees of freedom.
6. 6 or "gamma"
  Use the gamma distribution to generate the shock with. The first parameter is the alpha or shape parameter of the distribution and the second the beta or rate parameter of the distribution.
7. 7 or "invgamma"
  Use the inverse gamma distribution to draw the shock from. The first parameter is again alpha or the shape parameter and the second is beta or the rate parameter of the distribution.
8. 8 or "lognorm"
  Use the log normal distribution to generate the shock with. The first parameter is then the mean and the second the standard error of the distribution.
9. 9 or "norm"
  Use the normal distribution to generate shocks with. Here too, as in the previous case, the first parameter is the mean and the second the standard error of the distribution.
10. 10 or pareto
  Use the pareto distribution to generate the shock with. In this case the first parameter is xm or the scale parameter of the distribution and the second parameter is alpha or the shape parameter of the distribution.
11. 11 or "t"
  Use the t distribution to generate the shock with. Here the first parameter specifies the degrees of freedom of the distribution and the second parameter is ignored.
12. 12 or "uniform"
  Use the uniform distribution to generate the shock with. The first parameter is the minimum of the distribution's range and the second parameter is its maximum.
13. 13 or "weibull"
  Use the weibull distribution to generate the shock with. For this the first parameter specifies lambda or the scale parameter and the second kappa or the shape parameter of the distribution.
First parameter
This numerical value specifies the first parameter of the distribution. Its meaning depends on the distribution selected to generate the shock with and can be found in the list of distributions given above.
Second parameter
The numerical value of the second parameter. As with the first, its meaning depends on the distribution type and it can be found in the list above.
Optional shock magnitude or lower bound
If this parameter is omitted, then the shock magnitude will be drawn randomly and be between 0 and 1 (0 and 100%). The drawn magnitude will then be used to generate the shock with. Alternatively, this parameter can be used to specify a given shock, e.g. 0.999 for a 99.9% shock. If this is followed by another parameter, then this is the lower bound and the next parameter the upper bound, e.g. 0.8 and 0.9, to generate a random shock between 80 and 90% in magnitude.
Optional upper bound
If this parameter is supplied, it specified the upper bound of the shock magnitude. The lower bound and upper bound then together form a range of valid shocks from which a shock is drawn randomly in order to simulate with.

Example usage

print( shockMul( 100, 1, "norm", 0, 1 ) );     # 100 * ( 1 + normal random value )
print( shockMul( 100, 0, "weibull", 1, 1 ) );

sign

Signum

Category: Mathematics

Notes

Returns the sign (-1, 0 or 1) of its argument.

Arguments

This function takes a single argument, which is either a number or a series.

Example usage

print( sign(  123.4 ) );
print( sign(    0.0 ) );
print( sign( -123.4 ) );

sin

Sine of angle

Category: Mathematics

Notes

Calculates the sine of the argument, in radians.

Arguments

This function takes a single series or number as argument.

Example usage

print( sin( pi() / 4 ) );  # Print square root of 1/2
print( sin( X ) );         # Element by element sine of series X

sinh

Hyperbolic sine

Category: Mathematics

Notes

Returns, in radians, the hyperbolic sine of the hyperbolic angle.

Arguments

This function takes a single series or number as argument.

Example usage

print( sinh( pi() / 4 ) );
Y = sinh( X ); # Return new series with sinh of X as observations

skew

Sample skewness of a series

Category: Data series

Notes

Calculates and returns the (adjusted) sample skewness the observations in a series.

Arguments

This function takes a single argument, namely the series whose adjusted sample skewness is to be calculated and returned.

Example usage

print( skew( X ) );

sma

Simple moving average

Category: Data series

Notes

Calculates the simple moving average of a series for a given length.

Arguments

This function takes two arguments:

Lenght
The length of the moving average.
Series
The series to smooth.

Example usage

S = sma( 12, X ); # 12 month simple moving average

sort

Sort the observations of a series

Category: Data series

Notes

Sorts the observations of a series on the observed value and returns the sorted series.

Arguments

This function takes a single argument, namely the series to sort.

Example usage

print( sort( X ) );

sortDateIndex

Sort the date indices of a series

Category: Data series

Notes

Sorts the observations of a series on the observed value and returns the date indices of the corresponding sorted value.

After sorting, the expression

X[ firstDate( sortDateIndex( X ) ) ]

will for example return the smallest value in X and

first( sortDateIndex( X ) )

will return the date at which this smallest value is observed.

Arguments

This function takes a single argument, namely the series to sort.

Example usage

print( sortDateIndex( X ) );

sqrt

Square root

Category: Mathematics

Notes

Takes either a series or a number as argument and calculates and returns its square root.

Arguments

This function takes either a series or a number as argument.

Example usage

print( sqrt( 2 ) );
print( sqrt( X ) );

statReport

Generate a diagnostic statistics report for a series

Category: Data series

Notes

Generates and returns a report containing diagnostic statistics calculated for a given series.

Arguments

This function takes a single argument, namely the series whose report is to be calculated and returned.

Optionally, it can also take an argument containing flags and a name that can be used to save results to or to generate a report with.

(Optional) Report name
If the first argument is a string, then this is assumed to be the report name and the statistics will be saved using that name. If the name used is, for example, "s1", as seen below
```
statReport( "s1", x1 );    # Will store results to s1
```
then the median can for example be obtained using
```
med = dataSetValue( "s1", "nMed" );
```
To generate the report without storing back any results, simply omit this first argument, for example
```
statReport( x1 );
```
The report name must be a valid name, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign (+), a minus sign (-), a number sign (#) and an exclamation mark (!).
This command will generate a lot of output in the log but it can be silenced this output by prefixing the name with a minus sign, for example
```
statReport( "-s1", x1 );
```
If a name is provided the results are only stored in memory and not saved to disk as well. Thus the results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the report name, prefix it with a plus sign, e.g.
```
statReport( "+s1", x1 );
```
If the report name is prefixed with a number sign e.g.
```
statReport( "#s1", x1 );
```
then a new report with the name "s1" (excluding the number sign or any other flags) will be created and the results will be stored into that report. The table summary will contain the report and the table itself will contain the series. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
command to reduce clutter.
The report by default use the corrected or adjusted values when calculating the skewness and kurtosis, but it can be set to not correct these values, by using an exclamation mark as flag, as illustrated below
```
statReport( "!", x1 );
```
If results are stored using a report name, the following arguments are available keys to extract results with later:
- nAvg
  The sample average.
- nCV
  The coefficient of variance.
- nIntQntRange
  The inter-quantile range.
- nKurt
  The sample kurtosis.
- nMax
  The largest observation value.
- nMaxDate
  The largest observation date.
- nMed
  The median.
- nMin
  The smallest observation value.
- nMinDate
  The smallest observation date.
- nMode
  The mode if one was found.
- nObs
  The number of observations.
- nObs1
  The first observation value.
- nObsDate1
  The first observation date.
- nObsDaten
  The last observation date.
- nObsn
  The last observation value.
- nQ1
  The first quantile.
- nQ3
  The third quantile.
- nRange
  The sample range.
- nSkew
  The sample skewness.
- nStd
  The sample standard deviation.
- nVar
  The sample variance.
Series
The series to report on.

This function returns a string containing the report.

Example usage

statReport( X );

std

Sample standard deviation of a series

Category: Data series

Notes

Calculates and returns the sample standard deviation of all the observations in a series.

Arguments

This function takes a single argument, namely the series whose sample standard deviation is to be calculated and returned.

Example usage

print( std( X ) );

sum

Sum of a series

Category: Data series

Notes

Calculates and returns the sum of all the observations in a series.

To calculate the sum of a series between say 2010 and 2015, combine this with the limit function, for example

S = sum( limit( dateIndex( 2010, 1, 1 ), dateIndex( 2015, 12, 31 ), X ) );

Arguments

This function takes a single argument, namely the series whose sum is to be calculated and returned.

Example usage

# Calculate the sum of X
S = max( X );

# Calculate the sum between 2010 and 2015
sum( limit( dateIndex( 2010,  1,  1 ),
            dateIndex( 2015, 12, 31 ), X ) );

# Calculate the sum of X between May 2010 and Apr 2011
Y = sum( limit( dateIndex( 2010, 5, 1 ),
                dateIndex( 2011, 4, 1 ), X ) );

tCdf

Student’s t cumulative probability distribution

Category: Statistics

Notes

Returns the Student's t cumulative probability distribution function (cdf).

The returned value is the probability that a random value drawn from this distribution will be lower than the first argument.

Arguments

This function takes two arguments:

x
The value at which to calculate the cdf.
df
The positive degrees of freedom at which to evaluate the cdf.

Example usage

print( tCdf( 2,   3 ) );
print( tCdf( 2, 100 ) );

tPdf

Student’s t probability distribution

Category: Statistics

Notes

Returns the Student's t probability distribution function (pdf).

Arguments

This function takes two arguments:

x
The value at which to calculate the pdf.
df
The positive degrees of freedom at which to evaluate the pdf.

Example usage

print( tPdf( 2,   3 ) );
print( tPdf( 2, 100 ) );

tQnt

Student’s t probability distribution quantiles

Category: Statistics

Notes

Returns quantiles of the Student's t probability distribution.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p and therefore this is also called the inverse cumulative probability distribution.

Arguments

This function takes two arguments:

p
The probability, between 0 and 1, whose quantile is to be solved for.
df
The positive degrees of freedom at which to evaluate the distribution.

Example usage

print( tQnt( 0.01,   1 ) );
print( tQnt( 0.99, 100 ) );

tan

Tangent of angle

Category: Mathematics

Notes

Returns the tangent of a given angle, in radians.

Arguments

This function takes a single series or number as argument.

Example usage

print( tan( pi() / 4 ) );  # Print 1
print( tan( X ) );         # Element by element tangent of series X

tanh

Hyperbolic tangent

Category: Mathematics

Notes

Returns, in radians, the hyperbolic tangent of the hyperbolic angle.

Arguments

This function takes a single series or number as argument.

Example usage

print( tanh( pi() / 4 ) );
Y = tanh( X ); # Return new series with tanh of X as observations

testMeans

Test the equality of means hypothesis given two samples

Category: Statistics

Notes

This will test if the means of two samples are equal. It returns the probability that they are equal using the two-sample t-test.

Arguments

This function takes the two samples as arguments. Alternatively, the averages, variances and number of observations for each sample can be supplied, or any combination of these.

The default test assumes that the samples' variances differ. This can be changed by passing an equals sign (=) as a flag as part of the test name or first argument.

(Optional) Test name
If the first argument is a string, then this is assumed to be the test name and the results of the test will be saved using that name. If the name used is, for example, "t1", as seen below
```
testMeans( "t1", x1, x2 );    # Will store results to t1
```
then the degrees of freedom can for example be obtained using
```
df = dataSetValue( "t1", "nDf" );
```
To estimate the model and not store back any results, simply omit this first argument, for example
```
testMeans( x1, x2 );
```
The test name must be a valid name, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign (+), a minus sign (-), a number sign (#) and an equals sign (=).
When a model is estimated it generates a lot of output in the log. To silence this output, prefix the name with a minus sign, for example
```
testMeans( "-t1", x1, x2 );
```
If a name is provided the results are only stored in memory and not saved to disk as well. Thus the test results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the test name, prefix it with a plus sign, e.g.
```
testMeans( "+t1", x1, x2 );
```
If the test name is prefixed with a number sign e.g.
```
testMeans( "#t1", x1, x2 );
```
then a new report with the name "t1" (excluding the number sign) will be created and the results will be stored into that report. The table summary will contain a formatted overview of the test and the table itself will display the two series. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
command to reduce clutter.
The test by default assumes that the sample variances are different. To change the test by assuming that the variances are equal, pass an equals sign as flag e.g.
```
testMeans( "=", x1, x2 );
```
If results are stored using a test name, the following arguments are available keys to extract results with later:
- nAvg1
  The average of the first sample.
- nAvg2
  The average of the second sample.
- nNum1
  The number of observations in the first sample.
- nNum2
  The number of observations in the second sample.
- nStdPool
  The pooled standard deviation if equal variances are assumed.
- nT
  The T value used in the test.
- nDf
  The degrees of freedom.
- nVar
  The variance used in the test.
- nVar1
  The variance of the first sample.
- nVar2
  The variance of the second sample.
- nProb
  The critical probability calculated by the test.
First sample
The first sample of observations. This must evaluate to a series.
(Alternative) First sample average and variance and number of observations
If in stead of a series, three numbers are found, then these are taken as the first sample's average, variance and number of observations respectively.
Second sample
The second sample of observations, as a series.
(Alternative) Second sample average, variance and number of observations
If in stead of a series, three numbers are found, then, as before, these are assumed to be the average, variance and number of observations of the second sample.

This will return the critical probability calculated by the test. If this probability is low, then the null hypothesis of equal means can be discarded.

Example usage

testMeans( "#t1", x1, x2 ) );
testMeans( 0, 1, 100, x2 ); # First mean 0, var 1 from 100 obs
testMeans( x1, 1, 2, 300 ); # Second mean 1, var 2 from 300 obs

testVariances

Test if the variances from two samples are the same

Category: Statistics

Notes

This will test the variances from two samples and report on the probability that they are equal using the either the Brown–Forsythe or the Levene test.

Arguments

This function takes the two samples as arguments and test if the variances of the two are equal.

The default test uses the sample's median and is called the Brown–Forsythe test. Alternatively a flag can be passed to this to rather use the Levene test that is based on the average in stead.

(Optional) Test name
If the first argument is a string, then this is assumed to be the test name and the results of the test will be saved using that name. If the name used is, for example, "t1", as seen below
```
testVariances( "t1", x1, x2 );    # Will store results to t1
```
then the first degrees of freedom can for example be obtained using
```
df = dataSetValue( "t1", "nDf1" );
```
To estimate the model and not store back any results, simply omit this first argument, for example
```
testVariances( x1, x2 );
```
The test name must be a valid name, but it may be prefixed by any combination of a number of flags. Valid flags are a plus sign (+), a minus sign (-), a number sign (#) and an at sign (@).
When a model is estimated it generates a lot of output in the log. To silence this output, prefix the name with a minus sign, for example
```
testVariances( "-t1", x1, x2 );
```
If a name is provided the results are only stored in memory and not saved to disk as well. Thus the test results are available as long as the calculation is underway but not thereafter. To also store the results to disk, using the test name, prefix it with a plus sign, e.g.
```
testVariances( "+t1", x1, x2 );
```
If the test name is prefixed with a number sign e.g.
```
testVariances( "#t1", x1, x2 );
```
then a new report with the name "t1" (excluding the number sign) will be created and the results will be stored into that report. The table summary will contain a formatted overview of the test and the table itself will display the two series. Since a new report is created each time this is run, it is strongly suggested that this command be preceded by the
```
reportDelete
```
command to reduce clutter.
The test by default will use the median of each sample but to rather use the sample average, pass the at sign (@) as a flag, e.g.
```
testVariances( "@", x1, x2 );
```
If results are stored using a test name, the following arguments are available keys to extract results with later:
- nAvg1
  The average of the first sample.
- nAvg2
  The average of the second sample.
- nMed1
  The median of the first sample.
- nMed2
  The median of the second sample.
- nNum1
  The number of observations in the first sample.
- nNum2
  The number of observations in the second sample.
- nNum
  The number of observations in the combined sample.
- nVar1
  The variance of the first sample.
- nStd1
  The standard deviation of the first sample.
- nVar2
  The variance of the second sample.
- nStd2
  The standard deviation of the second sample.
- nF
  The F value used in the test.
- nDf1
  The first degrees of freedom.
- nDf2
  The second degrees of freedom.
- nProb
  The critical probability calculated by the test.
Note that the median based values above will only be available if the test was carried out using the median.
First sample
The first sample of observations. This must evaluate to a series.
Second sample
The second sample of observations, as a series.

This will return the critical probability calculated by the test. If this probability is low, then the null hypothesis of equal variances can be discarded.

Example usage

testVariances( "#t1", x1, x2 ) ); # Store to report t1
testVariances( x1, x2 );
testVariances( "-@", x1, x2 ); # Test silently using means

today

Date index of today

Category: Date

Notes

This returns the date index for the current date obtained from the local calendar and the current evaluation frequency.

Arguments

This does not take any arguments.

Example usage

print( today() );

uniformCdf

Cumulative uniform probability distribution

Category: Statistics

Notes

Returns the cumulative uniform probability distribution function (cdf).

It returns the probability that a random variable drawn from this distribution will be smaller than the first argument.

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
a
The minimum of the distribution's range.
b
The maximum of the distribution's range.

Example usage

print( uniformCdf(   3,   2,   4 ) );
print( uniformCdf( 110, 100, 200 ) );

uniformPdf

Uniform probability distribution

Category: Statistics

Notes

Returns the uniform probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
a
The minimum of the distribution's range.
b
the maximum of the distribution's range.

Example usage

print( uniformPdf(   3,   2,   4 ) );
print( uniformPdf( 110, 100, 200 ) );

uniformQnt

Uniform probability distribution quantiles

Category: Statistics

Notes

Returns the uniform probability distribution function's quantiles.

For a given probability, which lies between 0 and 1, this returns the critical value x so that CDF( x ) = p and therefore this is also referred to as the inverse cumulative distribution function.

Arguments

This function takes three arguments:

p
The probability, between 0 and 1, for which to return the critical value.
a
The minimum of the distribution's range.
b
The maximum of the distribution's range.

Example usage

print( uniformQnt( 0.001,   2,   4 ) );
print( uniformQnt( 0.999, 100, 200 ) );

upIncGamma

Upper incomplete gamma function

Category: Mathematics

Notes

Calculates and returns the value of the upper incomplete gamma function.

Arguments

This function takes two arguments, s and x, both of which may be either a number or a series.

Example usage

print( upIncGamma( 1, 1.23 ) );
print( exp( -1.23 ) );                 # Same as upIncGamma( 1, 1.23 )
print( upIncGamma( X, 1.23 ) );

upper

Upper case string

Category: String

Notes

Converts a string to an uppercase version of itself.

Arguments

This function takes a single argument, which must reduce to a string. The string is then converted to uppercase and returned.

Example usage

print( upper( "lower" ) );

var

Sample variance of a series

Category: Data series

Notes

Calculates and returns the sample variance of all the observations in a series.

Arguments

This function takes a single argument, namely the series whose sample variance is to be calculated and returned.

Example usage

print( var( X ) );

weibullCdf

Weibull cumulative probability distribution

Category: Statistics

Notes

Returns the Weibull cumulative probability distribution function (cdf).

This returns the probability that a random variable drawn from this distribution is less than the first parameter.

Arguments

This function takes up to three arguments:

x
The value at which to calculate the cdf.
lambda
The lambda or scale parameter of the distribution.
kappa
The kappa or shape parameter of the distribution.

Example usage

print( weibullCdf(   1,   1,  1 ) );
print( weibullCdf( 110, 100, 10 ) );

weibullPdf

Weibull probability distribution

Category: Statistics

Notes

Returns the Weibull probability distribution function (pdf).

Arguments

This function takes three arguments:

x
The value at which to calculate the pdf.
lambda
The lambda or scale parameter of the distribution.
kappa
The kappa or shape parameter of the distribution

Example usage

print( weibullPdf( 2, 1,  1 ) );
print( weibullPdf( 0, 1, 10 ) );

weibullQnt

Weibull probability distribution quantiles

Category: Statistics

Notes

Returns the Weibull probability distribution's quantiles.

For a given probability p, which lies between 0 and 1, this returns the critical value or quantile x so that CDF( x ) = p. This is also referred to as the inverse cumulative probability distribution function.

Arguments

This function takes up three arguments:

p
The probability, between 0 and 1, for which to calculate the quantile.
lambda
The lambda or scale parameter of the distribution.
kappa
The kappa or shape parameter of the distribution.

Example usage

print( weibullQnt( 0.01,  1,  1 ) );
print( weibullQnt( 0.99, 10, 20 ) );

while

While loop

Category: Control

Notes

Implements a while loop. It evaluates the first argument, which must reduce to a number, and if it is zero or missing, will exit immediately. Otherwise all the other arguments are evaluated one by one. Thereafter the first argument or condition is evaluated again and, if this time it is zero or missing, the loop will exit. The final return value is the number of times that the loop's condition was not false.

The basic structure is thus

while( <condition>, a1, a2, ... )

and, as long as the condition is true (not zero or missing), a1, a2 and so on will be evaluated.

A basic example that counts dates from 2010/1/1 to 2020/12/31 is

i = dateIndex( 2010, 1, 1 ); while( i <= dateIndex( 2020, 12, 31 ), ... do some stuff ..., i = i + 1 );

Arguments

This function takes two or more arguments. The first is the condition which will cause the rest to be evaluated as long as it remains true.

Example usage

i = dateIndex( 2010, 1, 1 ); while( i &lt;= dateIndex( 2020, 12, 31 ), print( "... do some stuff ..." ), i = i + 1 );
print( "Number of dates counted", i + 1 - dateIndex( 2010, 1, 1 ) );

xor

Logical xor

Category: Logical

Notes

Evaluates the two arguments and, if both are FALSE or both are TRUE, it will return 0 and if either one is FALSE and the other one is TRUE, will return 1. Here a value is considered FALSE if it is either missing or zero and TRUE otherwise.

Arguments

This function takes two arguments, both of which must reduce to a number. If either is a series, then an element by element xor is performed and a series of results is returned.

Example usage

print( xor( 1, 0 ) );

year

Return the year of a date index

Category: Date

Notes

This will return the year represented by a number. The number is interpreted as a date index using the current frequency. If the interval spans more than a year then the year of the last date in the interval is returned.

Arguments

This function takes a single argument which is the date index. It returns the year in the current frequency represented by the number.

Example usage

di = dateIndex( 1975, 1, 1 )
print( year( i ) ); # Prints 1975

z

Standardise observations

Category: Statistics

Notes

This will return the standardised observations calculated as z = (x-avg)/std.

Arguments

This function takes a single argument which is a series. It will then calculate and return the standard scores as a series.

Example usage

Z = z( x1 )