stockspec

Create stock structure

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.

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

Examples

Create a StockSpec for Stocks With Cash Dividends

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.

Create a StockSpec for Stocks With Cash and Continuous Dividends

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

Sigma — Annual price volatility of underlying security

decimal

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

Data Types: double

AssetPrice — Underlying asset price values at time 0

vector

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

Data Types: double

DividendType — Stock dividend type

cell array of date character vectors

(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

DividendAmounts — Dividend amounts

matrix | vector

(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

ExDividendDates — Ex-dividend dates

datetime array | string array | date character vector

(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

StockSpec — Properties of stock structure

structure

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

Version History

Introduced before R2006a

R2022b: Serial date numbers not recommended

Although stockspec supports serial date numbers, datetime values are recommended instead. The datetime data type provides flexible date and time formats, storage out to nanosecond precision, and properties to account for time zones and daylight saving time.

To convert serial date numbers or text to datetime values, use the datetime function. For example:

t = datetime(738427.656845093,"ConvertFrom","datenum");
y = year(t)

y =

        2021

There are no plans to remove support for serial date number inputs.