# estimateAssetMoments

Estimate mean and covariance of asset returns from data

Using a `fints` object for the `AssetReturns` argument of `estimateAssetMoments` is not recommended. Use `timetable` instead for financial time series. For more information, see Convert Financial Time Series Objects fints to Timetables.

## Syntax

``obj = estimateAssetMoments(obj,AssetReturns)``
``obj = estimateAssetMoments(___,Name,Value)``

## Description

example

````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.```

example

````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

collapse all

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 ```

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' } ```

Create a `Portfolio` object for three assets.

```AssetMean = [ 0.0101110; 0.0043532; 0.0137058 ]; AssetCovar = [ 0.00324625 0.00022983 0.00420395; 0.00022983 0.00049937 0.00019247; 0.00420395 0.00019247 0.00764097 ]; AssetMean = AssetMean/12 ```
```AssetMean = 3×1 0.0008 0.0004 0.0011 ```
`AssetCovar = AssetCovar/12`
```AssetCovar = 3×3 10-3 × 0.2705 0.0192 0.3503 0.0192 0.0416 0.0160 0.3503 0.0160 0.6367 ```
```X = portsim(AssetMean', AssetCovar, 120); p = Portfolio('AssetMean',AssetMean, 'AssetCovar', AssetCovar); p = setDefaultConstraints(p); ```

Use `setBounds` with semi-continuous constraints to set xi=`0` or `0.02`<=`xi`<=`0.5` for all i=`1`,...`NumAssets.`

`p = setBounds(p, 0.02, 0.5,'BoundType', 'Conditional', 'NumAssets', 3); `

When working with a `Portfolio` object, the `setMinMaxNumAssets` function enables you to set up cardinality constraints for a long-only portfolio. This sets the cardinality constraints for the `Portfolio` object, where the total number of allocated assets satisfying the nonzero semi-continuous constraints are between `MinNumAssets` and `MaxNumAssets`. By setting `MinNumAssets`=`MaxNumAssets`=2, only two of the three assets are invested in the portfolio.

`p = setMinMaxNumAssets(p, 2, 2); `

Use `estimateAssetMoments `to estimate mean and covariance of asset returns from data for a `Portfolio` object.

```p = estimateAssetMoments(p, X); [passetmean, passetcovar] = getAssetMoments(p)```
```passetmean = 3×1 0.0008 0.0004 0.0011 ```
```passetcovar = 3×3 10-3 × 0.2705 0.0192 0.3503 0.0192 0.0416 0.0160 0.3503 0.0160 0.6367 ```

The `estimateAssetMoments` function uses the MINLP solver to solve this problem. Use the `setSolverMINLP` function to configure the `SolverType` and options.

`p.solverOptionsMINLP`
```ans = struct with fields: MaxIterations: 1000 AbsoluteGapTolerance: 1.0000e-07 RelativeGapTolerance: 1.0000e-05 NonlinearScalingFactor: 1000 ObjectiveScalingFactor: 1000 Display: 'off' CutGeneration: 'basic' MaxIterationsInactiveCut: 30 ActiveCutTolerance: 1.0000e-07 IntMasterSolverOptions: [1x1 optim.options.Intlinprog] NumIterationsEarlyIntegerConvergence: 30 ```

## Input Arguments

collapse all

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

Data Types: `object`

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 Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```p = estimateAssetMoments(p,Y,'dataformat','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`

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`

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

collapse all

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

## Tips

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

`obj = obj.estimateAssetMoments(AssetReturns);`

## Version History

Introduced in R2011a