Main Content

stockspec

Create stock structure

collapse all in page

Syntax

StockSpec = stockspec(Sigma,AssetPrice)
StockSpec = stockspec(___,DividendType,DividendAmounts,ExDividendDates)

Description

StockSpec = stockspec(Sigma,AssetPrice) creates a MATLAB® structure containing the properties of a stock.

Note

StockSpec handles other types of underliers when pricing instruments other than equities.

example

StockSpec = stockspec(___,DividendType,DividendAmounts,ExDividendDates) adds optional arguments for DividendType, DividendAmounts, and ExDividendDates.

example

Examples

collapse all

Open Live Script

Consider a stock that provides four cash dividends of $0.50 on January 3, 2008, April 1, 2008, July 5, 2008 and October 1, 2008. The stock is trading at $50, and has a volatility of 20% per annum. Using this data, create the structure StockSpec: 

AssetPrice = 50;
Sigma = 0.20;

DividendType = {'cash'};
DividendAmounts = [0.50, 0.50, 0.50, 0.50];
ExDividendDates = [datetime(2008,1,3) , datetime(2008,4,1) , datetime(2008,7,5) , datetime(2008,10,1)];
 
StockSpec = stockspec(Sigma, AssetPrice, DividendType, DividendAmounts, ExDividendDates)
StockSpec = struct with fields:
             FinObj: 'StockSpec'
              Sigma: 0.2000
         AssetPrice: 50
       DividendType: {'cash'}
    DividendAmounts: [0.5000 0.5000 0.5000 0.5000]
    ExDividendDates: [733410 733499 733594 733682]

Examine the StockSpec structure. 

datedisp(StockSpec.ExDividendDates)
03-Jan-2008   01-Apr-2008   05-Jul-2008   01-Oct-2008   

StockSpec.DividendType
ans = 1x1 cell array
    {'cash'}

The StockSpec structure encapsulates the information of the stock and its four cash dividends.

Open Live Script

Consider two stocks that are trading at $40 and $35. The first one provides two cash dividends of $0.25 on March 1, 2008 and June 1, 2008. The second stock provides a continuous dividend yield of 3%. The stocks have a volatility of 30% per annum. Using this data, create the structure StockSpec: 

AssetPrice = [40; 35];
Sigma = .30;

DividendType = {'cash'; 'continuous'};
DividendAmount = [0.25, 0.25 ; 0.03 NaN];

DividendDate1 = datetime(2008,3,1);
DividendDate2 = datetime(2008,6,1);

StockSpec = stockspec(Sigma, AssetPrice, DividendType, DividendAmount,...
{ DividendDate1, DividendDate2 ; NaN NaN})
StockSpec = struct with fields:
             FinObj: 'StockSpec'
              Sigma: [2x1 double]
         AssetPrice: [2x1 double]
       DividendType: {2x1 cell}
    DividendAmounts: [2x2 double]
    ExDividendDates: [2x2 double]

Examine the StockSpec structure. 

datedisp(StockSpec.ExDividendDates)
01-Mar-2008   01-Jun-2008   
   NaN           NaN        

StockSpec.DividendType
ans = 2x1 cell
    {'cash'      }
    {'continuous'}

The StockSpec structure encapsulates the information of the two stocks and their dividends.

Input Arguments

collapse all

Annual price volatility of underlying security, specified as a NINST-by-1 decimal.

Data Types: double

Underlying asset price values at time 0, specified as a NINST-by-1 vector.

Data Types: double

(Optional) Stock dividend type, specified as a NINST-by-1 cell array of character vectors.

Dividend type must be either cash for actual dollar dividends, constant for constant dividend yield, or continuous for continuous dividend yield. This function does not handle stock option dividends.

Note

Dividends are assumed to be paid in cash. Noncash dividends (stock) are not allowed. When combining two or more types of dividends, shorter rows should be padded with the value NaN.

Data Types: char | cell

(Optional) Dividend amounts, specified as a NINST-by-NDIV matrix of cash dividends or NINST-by-1 vector representing a constant or continuous annualized dividend yield.

Data Types: double

(Optional) Ex-dividend dates, specified as a NINST-by-NDIV matrix of ex-dividend dates for a cash DividendType or a NINST-by-1 vector of ex-dividend dates for constant DividendType. For dates, use a datetime array, string array, or date character vectors. For a continuous DividendType, this argument should be ignored.

To support existing code, stockspec also accepts serial date numbers as inputs, but they are not recommended.

Output Arguments

collapse all

Properties of stock structure, returned as a structure encapsulating the properties of a stock.

References

[1] Hull, John C. Options, Futures, and Other Derivatives. 5th Edition, Prentice Hall, 2003.

Version History

Introduced before R2006a

expand all

See Also

| | | | | | | | | | |

Topics