## Asset Returns and Moments of Asset Returns Using Portfolio Object

Since mean-variance portfolio optimization problems require estimates for the mean and covariance of asset returns, the `Portfolio` object has several ways to set and get the properties `AssetMean` (for the mean) and `AssetCovar` (for the covariance). In addition, the return for a riskless asset is kept in the property `RiskFreeRate` so that all assets in `AssetMean` and `AssetCovar` are risky assets. For information on the workflow when using `Portfolio` objects, see Portfolio Object Workflow.

### Assignment Using the Portfolio Function

Suppose that you have a mean and covariance of asset returns in variables `m` and `C`. The properties for the moments of asset returns are set using the `Portfolio` object:

```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; p = Portfolio('AssetMean', m, 'AssetCovar', C); disp(p.NumAssets); disp(p.AssetMean); disp(p.AssetCovar);```
``` 4 0.0042 0.0083 0.0100 0.0150 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```
Notice that the Portfolio object determines the number of assets in `NumAssets` from the moments. The `Portfolio` object enables separate initialization of the moments, for example:
```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; p = Portfolio; p = Portfolio(p, 'AssetMean', m); p = Portfolio(p, 'AssetCovar', C); [assetmean, assetcovar] = p.getAssetMoments```
```assetmean = 0.0042 0.0083 0.0100 0.0150 assetcovar = 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```
The `getAssetMoments` function lets you get the values for `AssetMean` and `AssetCovar` properties at the same time.

### Assignment Using the `setAssetMoments` Function

You can also set asset moment properties using the `setAssetMoments` function. For example, given the mean and covariance of asset returns in the variables `m` and `C`, the asset moment properties can be set:

```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; p = Portfolio; p = setAssetMoments(p, m, C); [assetmean, assetcovar] = getAssetMoments(p)```
```assetmean = 0.0042 0.0083 0.0100 0.0150 assetcovar = 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```

### Scalar Expansion of Arguments

Both the `Portfolio` object and the `setAssetMoments` function perform scalar expansion on arguments for the moments of asset returns. When using the `Portfolio` object, the number of assets must be already specified in the variable `NumAssets`. If `NumAssets` has not already been set, a scalar argument is interpreted as a scalar with `NumAssets` set to `1`. `setAssetMoments` provides an additional optional argument to specify the number of assets so that scalar expansion works with the correct number of assets. In addition, if either a scalar or vector is input for the covariance of asset returns, a diagonal matrix is formed such that a scalar expands along the diagonal and a vector becomes the diagonal. This example demonstrates scalar expansion for four jointly independent assets with a common mean `0.1` and common variance `0.03`:

```p = Portfolio; p = setAssetMoments(p, 0.1, 0.03, 4); [assetmean, assetcovar] = getAssetMoments(p)```
```assetmean = 0.1000 0.1000 0.1000 0.1000 assetcovar = 0.0300 0 0 0 0 0.0300 0 0 0 0 0.0300 0 0 0 0 0.0300```
If at least one argument is properly dimensioned, you do not need to include the additional `NumAssets` argument. This example illustrates a constant-diagonal covariance matrix and a mean of asset returns for four assets:
```p = Portfolio; p = setAssetMoments(p, [ 0.05; 0.06; 0.04; 0.03 ], 0.03); [assetmean, assetcovar] = getAssetMoments(p)```
```assetmean = 0.0500 0.0600 0.0400 0.0300 assetcovar = 0.0300 0 0 0 0 0.0300 0 0 0 0 0.0300 0 0 0 0 0.0300```
In addition, scalar expansion works with the `Portfolio` object if `NumAssets` is known, or is deduced from the inputs.

### Estimating Asset Moments from Prices or Returns

Another way to set the moments of asset returns is to use the `estimateAssetMoments` function which accepts either prices or returns and estimates the mean and covariance of asset returns. Either prices or returns are stored as matrices with samples going down the rows and assets going across the columns. In addition, prices or returns can be stored in a `table` or `timetable` (see Estimating Asset Moments from Time Series Data). To illustrate using `estimateAssetMoments`, 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 `portsim`. The default behavior of `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 `portsim` 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);```

### Note

Portfolio optimization requires that you use total returns and not just price returns. So, "returns" should be total returns and "prices" should be total return prices.

Given asset returns and prices in variables `X` and `Y` from above, this sequence of examples demonstrates 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 `estimateAssetMoments`:

```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) [qassetmean, qassetcovar] = getAssetMoments(q)```
```passetmean = 0.0042 0.0083 0.0100 0.0150 passetcovar = 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 = 0.0042 0.0083 0.0100 0.0150 qassetcovar = 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 has the same moments. The default behavior of `estimateAssetMoments` is to work with asset returns. If, instead, you have asset prices in the variable `Y`, `estimateAssetMoments` accepts a name-value pair argument name `'DataFormat'` with a corresponding value set to `'prices'` to indicate that the input to the function is in the form of asset prices and not returns (the default value for the `'DataFormat'` argument is `'returns'`). This 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) [qassetmean, qassetcovar] = getAssetMoments(q)```
```passetmean = 0.0042 0.0083 0.0100 0.0150 passetcovar = 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 = 0.0042 0.0083 0.0100 0.0150 qassetcovar = 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```

### Estimating Asset Moments with Missing Data

Often when working with multiple assets, you have missing data indicated by `NaN` values in your return or price data. Although Multivariate Normal Regression goes into detail about regression with missing data, the `estimateAssetMoments` function has a name-value pair argument name `'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. This example illustrates how this works on price data with missing values:

```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); Y(1:20,1) = NaN; Y(1:12,4) = NaN; p = Portfolio('mean',m,'covar',C); q = Portfolio; q = estimateAssetMoments(q, Y, 'dataformat', 'prices'); r = Portfolio; r = estimateAssetMoments(r, Y, 'dataformat', 'prices', 'missingdata', true); [passetmean, passetcovar] = getAssetMoments(p) [qassetmean, qassetcovar] = getAssetMoments(q) [rassetmean, rassetcovar] = getAssetMoments(r)```
```passetmean = 0.0042 0.0083 0.0100 0.0150 passetcovar = 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 = 0.0045 0.0082 0.0101 0.0091 qassetcovar = 0.0006 0.0003 0.0001 -0.0000 0.0003 0.0023 0.0017 0.0011 0.0001 0.0017 0.0048 0.0029 -0.0000 0.0011 0.0029 0.0112 rassetmean = 0.0045 0.0083 0.0100 0.0113 rassetcovar = 0.0008 0.0005 0.0001 -0.0001 0.0005 0.0032 0.0022 0.0015 0.0001 0.0022 0.0063 0.0040 -0.0001 0.0015 0.0040 0.0144```
The `Portfolio` object `p` contains raw moments, the object `q` contains estimated moments in which `NaN` values are discarded, and the object `r` contains raw moments that accommodate missing values. Each time you run this example, you will get different estimates for the moments in `q` and `r`, and these will also differ from the moments in `p`.

### Estimating Asset Moments from Time Series Data

The `estimateAssetMoments` function also accepts asset returns or prices stored in a `table` or `timetable`. `estimateAssetMoments` implicitly works with matrices of data or data in a table or timetable object using the same rules for whether the data are returns or prices.

To illustrate the use of a table and timetable, use `array2timetable` and `array2timetable` to create a `table` and a `timetable` that contain asset returns generated with `portsim` (see Estimating Asset Moments from Prices or Returns). Two portfolio objects are then created with the `AssetReturns` based on a table and a timetable object.

```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; assetRetnScenarios = portsim(m', C, 120); dates = datetime(datenum(2001,1:120,31), 'ConvertFrom', 'datenum'); assetsName = {'Bonds', 'LargeCap', 'SmallCap', 'Emerging'}; assetRetnTimeTable = array2timetable(assetRetnScenarios,'RowTimes',dates, 'VariableNames', assetsName); assetRetnTable = array2table(assetRetnScenarios, 'VariableNames', assetsName); % Create two Portfolio objects: % p with predefined mean and covar: q with asset return scenarios to estimate mean and covar. p = Portfolio('mean', m, 'covar', C); q = Portfolio; % estimate asset moments with timetable q = estimateAssetMoments(q, assetRetnTimeTable); [passetmean, passetcovar] = getAssetMoments(p) [qassetmean, qassetcovar] = getAssetMoments(q) % estimate asset moments with table q = estimateAssetMoments(q, assetRetnTable); [passetmean, passetcovar] = getAssetMoments(p) [qassetmean, qassetcovar] = getAssetMoments(q) ```
```passetmean = 0.0042 0.0083 0.0100 0.0150 passetcovar = 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 = 0.0042 0.0083 0.0100 0.0150 qassetcovar = 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 passetmean = 0.0042 0.0083 0.0100 0.0150 passetcovar = 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 = 0.0042 0.0083 0.0100 0.0150 qassetcovar = 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```
As you can see, the moments match between th two portfolios. In addition, `estimateAssetMoments` also extracts asset names or identifiers from a `table` or `timetable` when the argument name `'GetAssetList'` set to `true` (its default value is `false`). If the `'GetAssetList'` value is `true`, the identifiers are used to set the `AssetList` property of the object. To show this, the formation of the `Portfolio` object `q` is repeated from the previous example with the `'GetAssetList'` flag set to `true` extracts the column labels from a table or timetable object:
```q = estimateAssetMoments(q,assetRetnTable,'GetAssetList',true); disp(q.AssetList)```
`'Bonds' 'LargeCap' 'SmallCap' 'Emerging'`
Note if you set the `'GetAssetList'` flag set to `true` and your input data is in a matrix, `estimateAssetMoments` uses the default labeling scheme from `setAssetList` described in Setting Up a List of Asset Identifiers.