Using Input and Output Arguments with Functions

Input Arguments

Vector and Matrix Input

By design, MATLAB^® software can efficiently perform repeated operations on collections of data stored in vectors and matrices. MATLAB code that is written to operate simultaneously on different arrays is said to be vectorized. Vectorized code is not only clean and concise, but is also efficiently processed by MATLAB.

Because MATLAB is optimized for processing vectorized code, many Financial Toolbox™ functions accept either vector or matrix input arguments, rather than single (scalar) values.

One example of such a function is the irr function, which computes the internal rate of return of a cash flow stream. If you input a vector of cash flows from a single cash flow stream, then irr returns a scalar rate of return. If you input a matrix of cash flows from multiple cash flow streams, where each matrix column represents a different stream, then irr returns a vector of internal rates of return, where the columns correspond to the columns of the input matrix. Many other Financial Toolbox functions work similarly.

As an example, suppose that you make an initial investment of $100, from which you then receive by a series of annual cash receipts of $10, $20, $30, $40, and $50. This cash flow stream is stored in a vector

CashFlows = [-100 10 20 30 40 50]'

CashFlows =
  -100
    10
    20
    30
    40
    50

Use the irr function to compute the internal rate of return of the cash flow stream.

Rate = irr(CashFlows)

Rate =

    0.1201

For the single cash flow stream CashFlows, the function returns a scalar rate of return of 0.1201, or 12.01%.

Now, use the irr function to compute internal rates of return for multiple cash flow streams.

Rate = irr([CashFlows CashFlows CashFlows])

Rate =

    0.1201    0.1201    0.1201

MATLAB performs the same computation on all the assets at once. For the three cash flow streams, the irr function returns a vector of three internal rates of return.

In the Financial Toolbox context, vectorized programming is useful in portfolio management. You can organize multiple assets into a single collection by placing data for each asset in a different matrix column or row, then pass the matrix to a Financial Toolbox function.

Character Vector Input

Enter MATLAB character vectors surrounded by single quotes ('character vector').

A character vector is stored as a character array, one ASCII character per element. Thus, the date character vector is

DateCharacterVector = '9/16/2017'

This date character vector is actually a 1-by-9 vector. If you create a vector or matrix of character vectors, each character vector must have the same length. Using a column vector to create a vector of character vectors can allow you to visually check that all character vectors are the same length. If your character vectors are not the same length, use spaces or zeros to make them the same length, as in the following code.

DateFields = ['01/12/2017'
              '02/14/2017'
              '03/03/2017'
              '06/14/2017'
              '12/01/2017'];

DateFields is a 5-by-10 array of character vectors.

You cannot mix numbers and character vectors in a vector or matrix. If you input a vector or matrix that contains a mix of numbers and character vectors, MATLAB treats every entry as a character. As an example, input the following code

Item = [83  90  99 '14-Sep-1999']

Item =

SZc14-Sep-1999

The software understands the input not as a 1-by-4 vector, but as a 1-by-14 character array with the value SZc14-Sep-1999.

Output Arguments

Some functions return no arguments, some return just one, and some return multiple arguments. Functions that return multiple arguments use the syntax

[A, B, C] = function(input_arguments...)

to return arguments A, B, and C. If you omit all but one, the function returns the first argument. Thus, for this example if you use the syntax

X = function(input_arguments...)

the function returns a value for A, but not for B or C.

Some functions that return vectors accept only scalars as arguments. Such functions cannot accept vectors as arguments and return matrices, where each column in the output matrix corresponds to an entry in the input. Output vectors can be variable length.

For example, most functions that require asset life as an input, and return values corresponding to different periods over the asset life, cannot handle vectors or matrices as input arguments. These functions include amortize, depfixdb, depgendb, and depsoyd. For example, consider a car for which you want to compute the depreciation schedule. Use the depfixdb function to compute a stream of declining-balance depreciation values for the asset. Set the initial value of the asset and the lifetime of the asset. Note that in the returned vector, the asset lifetime determines the number of rows. Now consider a collection of cars with different lifetimes. Because depfixdb cannot output a matrix with an unequal number of rows in each column, depfixdb cannot accept a single input vector with values for each asset in the collection.

Related Examples

Matrices and Arrays