Simple covariance

The covariance is an important measure of risk used in portfolio selection and performance analysis. The classic Markowitz [4] portfolio uses the portfolio variance as its risk measure, which is computed from the covariance matrix and portfolio weights. Here we define the most basic covariance/correlation estimator.

General covariance

PortfolioOptimisers.GeneralCovariance Type

struct GeneralCovariance{__T_ce, __T_w} <: AbstractCovarianceEstimator

A simple wrapper around a StatsBase.CovarianceEstimator, optional StatsBase.AbstractWeights, and an optional index. It uses ideas from SCIML to simplify the standard API of StatsBase.cov.

Fields

• ce: Covariance estimator.

• w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.

Constructors

GeneralCovariance(;
    ce::StatsBase.CovarianceEstimator = StatsBase.SimpleCovariance(;
        corrected = true),
    w::Option{<:ObsWeights} = nothing
) -> GeneralCovariance

Keywords correspond to the struct's fields.

Validation

• If w is not nothing, !isempty(w).

Details

• ce can be used to specify any subtype of StatsBase.CovarianceEstimator. This allows users to leverage packages such as CovarianceEstimation.jl, which implement custom covariance estimators.

Examples

julia> GeneralCovariance()
GeneralCovariance
  ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
   w ┴ nothing

julia> GeneralCovariance(; w = StatsBase.Weights([0.1, 0.2, 0.7]))
GeneralCovariance
  ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
   w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.1, 0.2, 0.7]

Related

• AbstractCovarianceEstimator

• Option

• StatsBase.CovarianceEstimator

• StatsBase.AbstractWeights

• cov(ce::GeneralCovariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...)

source

PortfolioOptimisers.factory Method

factory(
    ce::GeneralCovariance,
    w::ObsWeights
) -> GeneralCovariance

Return a new GeneralCovariance estimator with observation weights w.

Arguments

• ce: Covariance estimator.

• w: Observation weights vector observations × 1.

Returns

• ce: New covariance estimator of the same type as the argument, with the new weights applied.

Examples

julia> ce = GeneralCovariance()
GeneralCovariance
  ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
   w ┴ nothing

julia> factory(ce, StatsBase.Weights([0.1, 0.2, 0.7]))
GeneralCovariance
  ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
   w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.1, 0.2, 0.7]

Related

• GeneralCovariance

• StatsBase.AbstractWeights

• factory

source

Statistics.cov Method

Statistics.cov(
    ce::GeneralCovariance,
    X::MatNum;
    dims::Int = 1,
    mean = nothing,
    kwargs...
) -> MatNum

Compute the covariance matrix using a GeneralCovariance estimator.

This method dispatches to the appropriate robust_cov depending on ce.w, which computes the covariance matrix using ce.ce.

Arguments

• ce: Covariance estimator.

• X: Data matrix observations × features if the dims keyword does not exist or dims = 1, features × observations when dims = 2.

• dims: Dimension along which to perform the computation.

• mean: Optional mean value to use for centering.

• kwargs...: Additional keyword arguments passed to robust_cov.

Returns

• sigma::MatNum: Covariance matrix features x features.

Details

• Calls robust_cov with the appropriate covariance estimator.

Related

• MatNum

• GeneralCovariance

• robust_cov

• cor(ce::GeneralCovariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...)

Examples

julia> X = [0.01 0.02; 0.03 0.04; 0.02 0.03];

julia> cov(GeneralCovariance(), X)
2×2 Matrix{Float64}:
 0.0001  0.0001
 0.0001  0.0001

source

Statistics.cor Method

Statistics.cor(
    ce::GeneralCovariance,
    X::MatNum;
    dims::Int = 1,
    mean = nothing,
    kwargs...
) -> MatNum

Compute the correlation matrix using a GeneralCovariance estimator.

This method dispatches to the appropriate robust_cor depending on ce.w, which computes the correlation matrix using ce.ce.

Arguments

• ce: Covariance estimator.

• X: Data matrix observations × features if the dims keyword does not exist or dims = 1, features × observations when dims = 2.

• dims: Dimension along which to perform the computation.

• mean: Optional mean value to use for centering.

• kwargs...: Additional keyword arguments passed to robust_cor.

Returns

• rho::MatNum: Correlation matrix features x features.

Details

• Calls robust_cor with the appropriate covariance estimator.

Related

• MatNum

• GeneralCovariance

• robust_cor

• cov(ce::GeneralCovariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...)

Examples

julia> X = [0.01 0.02; 0.03 0.04; 0.02 0.03];

julia> cor(GeneralCovariance(), X)
2×2 Matrix{Float64}:
 1.0  1.0
 1.0  1.0

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    ce::GeneralCovariance,
    i,
    args...
) -> GeneralCovariance{<:CovarianceEstimator}

Gets the view of the covariance estimator for the i-th element(s).

Arguments

• ce: Covariance estimator.

• i: Index or indices to view.

Returns

• ce: New covariance estimator of the same type as the argument, for the new view.

Related

• GeneralCovariance

source

Covariance

PortfolioOptimisers.Covariance Type

struct Covariance{__T_me, __T_ce, __T_alg} <: AbstractCovarianceEstimator

A flexible container type for covariance estimation in PortfolioOptimisers.jl.

Covariance encapsulates all components required for estimating the covariance matrix of asset returns, including the expected returns estimator for centering the data, the covariance estimator, and the moment algorithm.

Fields

• me: Expected returns estimator.

• ce: Covariance estimator.

• alg: Moment algorithm.

Constructors

Covariance(;
    me::AbstractExpectedReturnsEstimator = SimpleExpectedReturns(),
    ce::StatsBase.CovarianceEstimator = GeneralCovariance(),
    alg::AbstractMomentAlgorithm = Full()
) -> Covariance

Keywords correspond to the struct's fields.

Examples

julia> Covariance()
Covariance
   me ┼ SimpleExpectedReturns
      │   w ┴ nothing
   ce ┼ GeneralCovariance
      │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
      │    w ┴ nothing
  alg ┴ Full()

Related

• AbstractCovarianceEstimator

• GeneralCovariance

• SimpleExpectedReturns

• Full

• Semi

source

PortfolioOptimisers.factory Method

factory(
    ce::Covariance,
    w::ObsWeights
) -> Covariance

Return a new Covariance estimator with observation weights w applied to both the expected returns and covariance estimators.

Arguments

• ce: Covariance estimator.

• w: Observation weights vector observations × 1.

Returns

• ce: New covariance estimator of the same type as the argument, with the new weights applied.

Details

• Calls factory(ce.me, w) and factory(ce.ce, w) to propagate the weights to the mean and covariance estimators.

• Preserves the moment algorithm ce.alg from the original estimator.

• Enables weighted estimation for both mean and covariance in portfolio workflows.

Examples

julia> ce = Covariance()
Covariance
   me ┼ SimpleExpectedReturns
      │   w ┴ nothing
   ce ┼ GeneralCovariance
      │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
      │    w ┴ nothing
  alg ┴ Full()

julia> ce_w = factory(ce, StatsBase.Weights([0.2, 0.3, 0.5]))
Covariance
   me ┼ SimpleExpectedReturns
      │   w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.2, 0.3, 0.5]
   ce ┼ GeneralCovariance
      │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
      │    w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.2, 0.3, 0.5]
  alg ┴ Full()

Related

• Covariance

• StatsBase.AbstractWeights

• factory

source

Statistics.cov Method

Statistics.cov(
    ce::Covariance,
    X::MatNum;
    dims::Int = 1,
    mean = nothing,
    kwargs...
) -> MatNum

Compute the covariance matrix using a Covariance estimator.

Mathematical definition

Full covariance:

$$\begin{array}{rl}{\hat{\mathbf{\Sigma }}}_{ij}& =\frac{1}{T-1}\sum _{t=1}^T(r_{ti}-{\hat{\mu }}_i)(r_{tj}-{\hat{\mu }}_j).\end{array}$$

Where:

• ${\hat{\mathbf{\Sigma }}}_{ij}$: Estimated covariance between assets $i$ and $j$.

• $r_{ti}$: Return of asset $i$ at time $t$.

• ${\hat{\mu }}_i$: Estimated mean of asset $i$.

• $T$: Number of observations.

Semi (downside) covariance — clip de-meaned returns to zero before computing:

$$\begin{array}{rl}{\tilde{r}}_{tj}& =min(r_{tj}-{\hat{\mu }}_j,0).\end{array}$$

Where:

• ${\tilde{r}}_{tj}$: Clipped de-meaned return of asset $j$ at time $t$.

• $r_{tj}$: Return of asset $j$ at time $t$.

• ${\hat{\mu }}_j$: Estimated mean of asset $j$.

$$\begin{array}{rl}{\hat{\mathbf{\Sigma }}}_{ij}^{\text{semi}}& =\frac{1}{T-1}\sum _{t=1}^T{\tilde{r}}_{ti}{\tilde{r}}_{tj}.\end{array}$$

Where:

• ${\hat{\mathbf{\Sigma }}}_{ij}^{\text{semi}}$: Estimated semi-covariance between assets $i$ and $j$.

• ${\tilde{r}}_{ti}$, ${\tilde{r}}_{tj}$: Clipped de-meaned returns of assets $i$ and $j$.

• $T$: Number of observations.

Arguments

• ce: Covariance estimator.

  • ce::Covariance{<:Any, <:Any, <:Full}: Covariance estimator with Full moment algorithm.

  • ce::Covariance{<:Any, <:Any, <:Semi}: Covariance estimator with Semi moment algorithm.

• X: Data matrix observations × features if the dims keyword does not exist or dims = 1, features × observations when dims = 2.

• dims: Dimension along which to perform the computation.

• mean: Optional mean value to use for centering. If not provided, computed using ce.me.

• kwargs...: Additional keyword arguments passed to the underlying covariance estimator.

Returns

• sigma::MatNum: Covariance matrix features x features.

Related

• Covariance

• AbstractCovarianceEstimator

• GeneralCovariance

• Full

• Semi

• cor(ce::Covariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...)

Examples

julia> X = [0.01 0.02; 0.03 0.04; 0.02 0.03];

julia> cov(Covariance(), X)
2×2 Matrix{Float64}:
 0.0001  0.0001
 0.0001  0.0001

source

Statistics.cov Method

cov(
    ce::Covariance{<:Any, <:Any, <:Semi},
    X::AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}};
    dims,
    mean,
    kwargs...
) -> Any

Semi variant of cov(ce::Covariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...). Clips de-meaned returns to zero before computing the covariance matrix, capturing only downside co-movements.

source

Statistics.cor Method

Statistics.cor(
    ce::Covariance,
    X::MatNum;
    dims::Int = 1,
    mean = nothing,
    kwargs...
) -> MatNum

Compute the correlation matrix using a Covariance estimator.

Mathematical definition

$$\begin{array}{rl}{\hat{\mathbf{P}}}_{ij}& =\frac{{\hat{\mathbf{\Sigma }}}_{ij}}{{\hat{\sigma }}_i{\hat{\sigma }}_j}.\end{array}$$

Where:

• ${\hat{\mathbf{P}}}_{ij}$: Estimated correlation between assets $i$ and $j$.

• ${\hat{\mathbf{\Sigma }}}_{ij}$: Estimated covariance between assets $i$ and $j$.

• ${\hat{\sigma }}_i$: Estimated standard deviation of asset $i$.

Arguments

• ce: Covariance estimator.

  • ce::Covariance{<:Any, <:Any, <:Full}: Covariance estimator with Full moment algorithm.

  • ce::Covariance{<:Any, <:Any, <:Semi}: Covariance estimator with Semi moment algorithm.

• X: Data matrix observations × features if the dims keyword does not exist or dims = 1, features × observations when dims = 2.

• dims: Dimension along which to perform the computation.

• mean: Optional mean value to use for centering. If not provided, computed using ce.me.

• kwargs...: Additional keyword arguments passed to the underlying correlation estimator.

Returns

• rho::MatNum: Correlation matrix features x features.

Related

• Covariance

• AbstractCovarianceEstimator

• GeneralCovariance

• Full

• Semi

• cov(ce::Covariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...)

Examples

julia> X = [0.01 0.02; 0.03 0.04; 0.02 0.03];

julia> cor(Covariance(), X)
2×2 Matrix{Float64}:
 1.0  1.0
 1.0  1.0

source

Statistics.cor Method

cor(
    ce::Covariance{<:Any, <:Any, <:Semi},
    X::AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}};
    dims,
    mean,
    kwargs...
) -> Any

Semi variant of cor(ce::Covariance, X::MatNum; dims::Int = 1, mean = nothing, kwargs...). Clips de-meaned returns to zero before computing the correlation matrix, capturing only downside co-movements.

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    ce::Covariance,
    i,
    args...
) -> Covariance{<:AbstractExpectedReturnsEstimator, <:CovarianceEstimator, <:AbstractMomentAlgorithm}

Gets the view of the covariance estimator for the i-th element(s).

Arguments

• ce: Covariance estimator.

• i: Index or indices to view.

Returns

• ce: New covariance estimator of the same type as the argument, for the new view.

Related

• Covariance

source