estimateAssetMoments

Estimate mean and covariance of asset returns from data

estimateAssetMoments has been partially removed and will no longer accept a fints object for the AssetReturns argument. Use timetable instead for financial time series.

Use fts2timetable to convert a fints object to a timetable object.

Syntax

obj = estimateAssetMoments(obj,AssetReturns)

obj = estimateAssetMoments(___,Name,Value)

Description

obj = estimateAssetMoments(obj,AssetReturns) estimates mean and covariance of asset returns from data for a Portfolio object. For details on the workflow, see Portfolio Object Workflow.

obj = estimateAssetMoments(___,Name,Value) estimates mean and covariance of asset returns from data for a Portfolio object with additional options for one or more Name,Value pair arguments.

Examples

Estimate Mean and Covariance of Asset Returns from Data for a Portfolio Object

To illustrate using the estimateAssetMoments function, generate random samples of 120 observations of asset returns for four assets from the mean and covariance of asset returns in the variables m and C with the portsim function. The default behavior portsim creates simulated data with estimated mean and covariance identical to the input moments m and C. In addition to a return series created by the portsim function in the variable X, a price series is created in the variable Y:

m = [ 0.05; 0.1; 0.12; 0.18 ];
C = [ 0.0064 0.00408 0.00192 0; 
      0.00408 0.0289 0.0204 0.0119;
      0.00192 0.0204 0.0576 0.0336;
      0 0.0119 0.0336 0.1225 ];
m = m/12;
C = C/12;
X = portsim(m', C, 120);
Y = ret2tick(X);

Given asset returns and prices in the variables X and Y from above, the following examples demonstrate equivalent ways to estimate asset moments for the Portfolio object. A Portfolio object is created in p with the moments of asset returns set directly in the Portfolio object and a second Portfolio object is created in q to obtain the mean and covariance of asset returns from asset return data in X using the estimateAssetMoments function.

m = [ 0.05; 0.1; 0.12; 0.18 ];
C = [ 0.0064 0.00408 0.00192 0; 
      0.00408 0.0289 0.0204 0.0119;
      0.00192 0.0204 0.0576 0.0336;
      0 0.0119 0.0336 0.1225 ];
m = m/12;
C = C/12;
 
X = portsim(m', C, 120);
p = Portfolio('mean',m,'covar',C);
q = Portfolio;
q = estimateAssetMoments(q, X);
 
[passetmean, passetcovar] = getAssetMoments(p)

passetmean = 4×1

    0.0042
    0.0083
    0.0100
    0.0150

passetcovar = 4×4

    0.0005    0.0003    0.0002         0
    0.0003    0.0024    0.0017    0.0010
    0.0002    0.0017    0.0048    0.0028
         0    0.0010    0.0028    0.0102

[qassetmean, qassetcovar] = getAssetMoments(q)

qassetmean = 4×1

    0.0042
    0.0083
    0.0100
    0.0150

qassetcovar = 4×4

    0.0005    0.0003    0.0002   -0.0000
    0.0003    0.0024    0.0017    0.0010
    0.0002    0.0017    0.0048    0.0028
   -0.0000    0.0010    0.0028    0.0102

Notice how either approach yields the same moments. The default behavior of the estimateAssetMoments function is to work with asset returns. If, instead, you have asset prices, such as in the variable Y, the estimateAssetMoments function accepts a parameter name 'DataFormat' with a corresponding value set to 'prices' to indicate that the input to the method is in the form of asset prices and not returns (the default parameter value for 'DataFormat' is 'returns'). The following example compares direct assignment of moments in the Portfolio object p with estimated moments from asset price data in Y in the Portfolio object q:

m = [ 0.05; 0.1; 0.12; 0.18 ];
C = [ 0.0064 0.00408 0.00192 0; 
      0.00408 0.0289 0.0204 0.0119;
      0.00192 0.0204 0.0576 0.0336;
      0 0.0119 0.0336 0.1225 ];
m = m/12;
C = C/12;
 
X = portsim(m', C, 120);
Y = ret2tick(X);

p = Portfolio('mean',m,'covar',C);
        
q = Portfolio;
q = estimateAssetMoments(q, Y, 'dataformat', 'prices');
 
[passetmean, passetcovar] = getAssetMoments(p)

passetmean = 4×1

    0.0042
    0.0083
    0.0100
    0.0150

passetcovar = 4×4

    0.0005    0.0003    0.0002         0
    0.0003    0.0024    0.0017    0.0010
    0.0002    0.0017    0.0048    0.0028
         0    0.0010    0.0028    0.0102

[qassetmean, qassetcovar] = getAssetMoments(q)

qassetmean = 4×1

    0.0042
    0.0083
    0.0100
    0.0150

qassetcovar = 4×4

    0.0005    0.0003    0.0002   -0.0000
    0.0003    0.0024    0.0017    0.0010
    0.0002    0.0017    0.0048    0.0028
   -0.0000    0.0010    0.0028    0.0102

Estimate Mean and Covariance of Asset Returns from Timetable Data for a Portfolio Object

To illustrate using the estimateAssetMoments function with AssetReturns data continued in a timetable object, use the CAPMuniverse.mat which contains a timetable object (AssetTimeTable) for returns data.

load CAPMuniverse
AssetsTimeTable.Properties;
head(AssetsTimeTable,5)

ans=5×14 timetable
       Time          AAPL         AMZN         CSCO         DELL         EBAY       GOOG       HPQ          IBM         INTC         MSFT         ORCL         YHOO        MARKET         CASH   
    ___________    _________    _________    _________    _________    _________    ____    _________    _________    _________    _________    _________    _________    _________    __________

    03-Jan-2000     0.088805       0.1742     0.008775    -0.002353      0.12829    NaN       0.03244     0.075368      0.05698    -0.001627     0.054078     0.097784    -0.012143    0.00020522
    04-Jan-2000    -0.084331     -0.08324     -0.05608     -0.08353    -0.093805    NaN     -0.075613    -0.033966    -0.046667    -0.033802      -0.0883    -0.067368     -0.03166    0.00020339
    05-Jan-2000     0.014634     -0.14877    -0.003039     0.070984     0.066875    NaN     -0.006356      0.03516     0.008199     0.010567    -0.052837    -0.073363     0.011443    0.00020376
    06-Jan-2000    -0.086538    -0.060072    -0.016619    -0.038847    -0.012302    NaN     -0.063688    -0.017241     -0.05824    -0.033477    -0.058824     -0.10307     0.011743    0.00020266
    07-Jan-2000     0.047368     0.061013       0.0587    -0.037708    -0.000964    NaN      0.028416    -0.004386      0.04127     0.013091     0.076771      0.10609      0.02393    0.00020157

Notice that GOOG has missing data (NaN), because it was not listed before Aug 2004. The estimateAssetMoments function has a name-value pair argument 'MissingData' that indicates with a Boolean value whether to use the missing data capabilities of Financial Toolbox™ software. The default value for 'MissingData' is false which removes all samples with NaN values. If, however, 'MissingData' is set to true, estimateAssetMoments uses the ECM algorithm to estimate asset moments.

r = Portfolio;
r = estimateAssetMoments(r,AssetsTimeTable,'dataformat','returns','missingdata',true);

In addition, the estimateAssetMoments function also extracts asset names or identifiers from a timetable object when the name-value argument 'GetAssetList' set to true (its default value is false). If the 'GetAssetList' value is true, the timetable column identifiers are used to set the AssetList property of the Portfolio object. To show this, the formation of the Portfolio object r is repeated with the 'GetAssetList' flag set to true.

r = estimateAssetMoments(r,AssetsTimeTable,'GetAssetList',true);
disp(r.AssetList')

    {'AAPL'  }
    {'AMZN'  }
    {'CSCO'  }
    {'DELL'  }
    {'EBAY'  }
    {'GOOG'  }
    {'HPQ'   }
    {'IBM'   }
    {'INTC'  }
    {'MSFT'  }
    {'ORCL'  }
    {'YHOO'  }
    {'MARKET'}
    {'CASH'  }

Input Arguments

obj — Object for portfolio

object

Object for portfolio, specified using a Portfolio object. For more information on creating a portfolio object, see

• Portfolio

Data Types: object

AssetReturns — Matrix, table, or timetable that contains asset price data that can be converted to asset returns

matrix | table | table

Matrix, table, or timetable that contains asset price data that can be converted to asset returns, specified by a NumSamples-by-NumAssets matrix.

AssetReturns data can be:

• NumSamples-by-NumAssets matrix.

• Table of NumSamples prices or returns at a given periodicity for a collection of NumAssets assets

• Timetable object with NumSamples observations and NumAssets time series

Use the optional DataFormat argument to convert AssetReturns input data that is asset prices into asset returns. Be careful when using asset price data because portfolio optimization usually requires total returns and not simply price returns.

Data Types: double | table | timetable

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: p = estimateAssetMoments(p,Y,'dataformat','prices')

'DataFormat' — Flag to convert input data as prices into returns

'Returns' (default) | character vector with values 'Returns' or 'Prices'

Flag to convert input data as prices into returns, specified as the comma-separated pair consisting of 'DataFormat' and a character vector with the values:

• 'Returns' — Data in AssetReturns contains asset total returns.

• 'Prices' — Data in AssetReturns contains asset total return prices.

Data Types: char

'MissingData' — Flag indicating whether to use ECM algorithm or exclude samples with NaN values

false (default) | logical with value true or false

Flag indicating whether to use ECM algorithm or excludes samples with NaN values, specified as the comma-separated pair consisting of 'MissingData' and a logical with a value of true or false.

To handle time series with missing data (indicated with NaN values), the MissingData flag either uses the ECM algorithm to obtain maximum likelihood estimates in the presences of NaN values or excludes samples with NaN values. Since the default is false, it is necessary to specify MissingData as true to use the ECM algorithm.

Acceptable values for MissingData are:

• false — Do not use ECM algorithm to handle NaN values (exclude NaN values).

• true — Use ECM algorithm to handle NaN values.

For more information on the ECM algorithm, see ecmnmle and Multivariate Normal Regression.

Data Types: logical

'GetAssetList' — Flag indicating which asset names to use for asset list

false (default) | logical with value true or false

Flag indicating which asset names to use for the asset list, specified as the comma-separated pair consisting of 'GetAssetList' and a logical with a value of true or false. Acceptable values for GetAssetList are:

• false — Do not extract or create asset names.

• true — Extract or create asset names from a table or timetable object.

If a table or timetable is passed into this function using the AssetReturns argument and the GetAssetList flag is true, the column names from the table or timetable object are used as asset names in obj.AssetList.

If a matrix is passed and the GetAssetList flag is true, default asset names are created based on the AbstractPortfolio property defaultforAssetList, which is 'Asset'.

If the GetAssetList flag is false, no action occurs, which is the default behavior.

Data Types: logical

Output Arguments

obj — Updated portfolio object

object for portfolio

Updated portfolio object, returned as a Portfolio object. For more information on creating a portfolio object, see

• Portfolio

Tips

You can also use dot notation to estimate the mean and covariance of asset returns from data.

obj = obj.estimateAssetMoments(AssetReturns);