Finish interfaces gerber covariance

Author: dcelisgarza

src/08_Moments/01_Base_Moments.jl

@@ -54,7 +54,7 @@ In order to implement a new covariance estimator which will work seamlessly with
 
 ## Factory
 
-  - `factory(ce::AbstractCovarianceEstimator, w::StatsBase.AbstractWeights) -> AbstractCovarianceEstimator`: Factory method for creating instances of the estimator with new observation weights.
+  - `PortfolioOptimisers.factory(ce::AbstractCovarianceEstimator, w::StatsBase.AbstractWeights) -> AbstractCovarianceEstimator`: Factory method for creating instances of the estimator with new observation weights.
 
 ### Arguments
 
@@ -86,10 +86,9 @@ julia> function MyCovarianceEstimator(;
        end
 MyCovarianceEstimator
 
-julia> function factory(::MyCovarianceEstimator, w::StatsBase.AbstractWeights)
+julia> function PortfolioOptimisers.factory(::MyCovarianceEstimator, w::StatsBase.AbstractWeights)
            return MyCovarianceEstimator(; w = w)
        end
-factory (generic function with 1 method)
 
 julia> function Statistics.cov(est::MyCovarianceEstimator, X::PortfolioOptimisers.MatNum;
                                dims::Int = 1, kwargs...)
@@ -132,6 +131,10 @@ julia> cor(MyCovarianceEstimator(), [1.0 2.0; 0.3 0.7; 0.5 1.1])
  1.0       0.998274  0.999315
  0.998274  1.0       0.999764
  0.999315  0.999764  1.0
+
+julia> PortfolioOptimisers.factory(MyCovarianceEstimator(), StatsBase.Weights([1, 2, 3]))
+MyCovarianceEstimator
+  w ┴ StatsBase.Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
 ```
 
 # Related
@@ -181,7 +184,7 @@ In order to implement a new covariance estimator which will work seamlessly with
 
 ## Factory
 
-  - `factory(ve::AbstractVarianceEstimator, w::StatsBase.AbstractWeights) -> AbstractVarianceEstimator`: Factory method for creating instances of the estimator with new observation weights.
+  - `PortfolioOptimisers.factory(ve::AbstractVarianceEstimator, w::StatsBase.AbstractWeights) -> AbstractVarianceEstimator`: Factory method for creating instances of the estimator with new observation weights.
 
 ### Arguments
 
@@ -213,10 +216,9 @@ julia> function MyVarianceEstimator(;
        end
 MyVarianceEstimator
 
-julia> function factory(::MyVarianceEstimator, w::StatsBase.AbstractWeights)
+julia> function PortfolioOptimisers.factory(::MyVarianceEstimator, w::StatsBase.AbstractWeights)
            return MyVarianceEstimator(; w = w)
        end
-factory (generic function with 1 method)
 
 julia> function Statistics.var(est::MyVarianceEstimator, X::PortfolioOptimisers.MatNum;
                                dims::Int = 1, kwargs...)
@@ -265,6 +267,10 @@ julia> var(MyVarianceEstimator(), [1.0 2.0; 0.3 0.7; 0.5 1.1])
 julia> std(MyVarianceEstimator(), [1.0 2.0; 0.3 0.7; 0.5 1.1])
 1×3 Matrix{Float64}:
  2.23607  0.761577  1.2083
+
+julia> PortfolioOptimisers.factory(MyVarianceEstimator(), StatsBase.Weights([1, 2, 3]))
+MyVarianceEstimator
+  w ┴ StatsBase.Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
 ```
 
 # Related
@@ -300,7 +306,7 @@ In order to implement a new expected returns estimator which will work seamlessl
 
 ## Factory
 
-  - `factory(me::AbstractExpectedReturnsEstimator, w::StatsBase.AbstractWeights) -> AbstractExpectedReturnsEstimator`: Factory method for creating instances of the estimator with new observation weights.
+  - `PortfolioOptimisers.factory(me::AbstractExpectedReturnsEstimator, w::StatsBase.AbstractWeights) -> AbstractExpectedReturnsEstimator`: Factory method for creating instances of the estimator with new observation weights.
 
 ### Arguments
 
@@ -331,10 +337,10 @@ julia> function MyExpectedReturnsEstimator(;
        end
 MyExpectedReturnsEstimator
 
-julia> function factory(::MyExpectedReturnsEstimator, w::StatsBase.AbstractWeights)
+julia> function PortfolioOptimisers.factory(::MyExpectedReturnsEstimator,
+                                            w::StatsBase.AbstractWeights)
            return MyExpectedReturnsEstimator(; w = w)
        end
-factory (generic function with 1 method)
 
 julia> function Statistics.mean(est::MyExpectedReturnsEstimator, X::PortfolioOptimisers.MatNum;
                                 dims::Int = 1, kwargs...)
@@ -355,6 +361,10 @@ julia> mean(MyExpectedReturnsEstimator(), [1.0 2.0; 0.3 0.7; 0.5 1.1]; dims = 2)
  1.5
  0.5
  0.8
+
+julia> PortfolioOptimisers.factory(MyExpectedReturnsEstimator(), StatsBase.Weights([1, 2, 3]))
+MyExpectedReturnsEstimator
+  w ┴ StatsBase.Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
 ```
 
 # Related

src/08_Moments/03_Covariance.jl

@@ -301,7 +301,7 @@ Return a new `Covariance` estimator with observation weights `w` applied to both
 
 # Details
 
-  - Applies weights to both the expected returns estimator `ce.me` and the covariance estimator `ce.ce`.
+  - 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.
 

src/08_Moments/04_SimpleVariance.jl

@@ -361,8 +361,8 @@ Return a new `SimpleVariance` estimator with the specified observation weights.
 
 # Details
 
-  - Constructs a new `SimpleVariance` estimator with updated weights.
   - The mean estimator is updated using `factory(ve.me, w)` for consistency.
+  - Sets `w` to the new weights.
   - The bias correction flag is preserved from the original estimator.
 
 # Examples

src/08_Moments/05_GerberCovariance.jl

@@ -5,6 +5,10 @@ Abstract supertype for all Gerber covariance estimators in `PortfolioOptimisers.
 
 All concrete and/or abstract types implementing Gerber covariance estimation algorithms should be subtypes of `BaseGerberCovariance`.
 
+# Interfaces
+
+If moving away from the already established Gerber covariance algorithms, you must follow [`AbstractCovarianceEstimator`](@ref) to implement the entire chain.
+
 # Related
 
   - [`GerberCovariance`](@ref)
@@ -24,6 +28,10 @@ All concrete and/or abstract types implementing specific Gerber covariance algor
 
 These types are used to specify the algorithm when constructing a [`GerberCovariance`](@ref) estimator.
 
+# Interfaces
+
+If moving away from the already established Gerber covariance algorithms, you must follow [`AbstractCovarianceEstimator`](@ref) to implement the entire chain. Else you can follow the instructions and examples in [`UnstandardisedGerberCovarianceAlgorithm`](@ref) and [`StandardisedGerberCovarianceAlgorithm`](@ref).
+
 # Related
 
   - [`BaseGerberCovariance`](@ref)
@@ -43,6 +51,104 @@ Abstract supertype for all unstandardised Gerber covariance algorithm types.
 
 Concrete types implementing unstandardised Gerber covariance algorithms should subtype `UnstandardisedGerberCovarianceAlgorithm`.
 
+# Interfaces
+
+In order to implement a new Gerber algorithm which will work seamlessly with the library, subtype `UnstandardisedGerberCovarianceAlgorithm` with all necessary parameters as part of the struct, and implement the following methods:
+
+## Gerber correlation
+
+  - `PortfolioOptimisers.gerber(ce::GerberCovariance{<:Any, <:Any, <:Any, <:UnstandardisedGerberCovarianceAlgorithm}, X::MatNum, sd::ArrNum) -> MatNum`: Unstandardised Gerber correlation matrix.
+
+### Arguments
+
+  - $(arg_dict[:gerbce]). Configured with the custom `UnstandardisedGerberCovarianceAlgorithm` algorithm.
+  - $(arg_dict[:X])
+  - $(arg_dict[:stdarr])
+
+### Returns
+
+  - $(ret_dict[:rho])
+
+## Factory (if algorithm uses observation weights)
+
+If the algorithm uses observation weights, the `factory` method will update the algorithm with the new weights.
+
+  - `PortfolioOptimisers.factory(alg::UnstandardisedGerberCovarianceAlgorithm, w::StatsBase.AbstractWeights) -> UnstandardisedGerberCovarianceAlgorithm`: Updates the algorithm with the new weights.
+
+### Arguments
+
+  - $(arg_dict[:gerbalg])
+  - $(arg_dict[:ow])
+
+### Returns
+
+  - $(ret_dict[:algw])
+
+## Examples
+
+We can create a dummy unstandardised Gerber covariance algorithm as follows:
+
+```jldoctest
+julia> struct MyUnstandardisedGerberCovarianceAlg{T} <:
+              PortfolioOptimisers.UnstandardisedGerberCovarianceAlgorithm
+           w::T
+           function MyUnstandardisedGerberCovarianceAlg(w::PortfolioOptimisers.Option{<:StatsBase.AbstractWeights})
+               if !isnothing(w)
+                   @assert(!isempty(w))
+               end
+               return new{typeof(w)}(w)
+           end
+       end
+
+julia> function MyUnstandardisedGerberCovarianceAlg(;
+                                                    w::PortfolioOptimisers.Option{<:StatsBase.AbstractWeights} = nothing)
+           return MyUnstandardisedGerberCovarianceAlg(w)
+       end
+MyUnstandardisedGerberCovarianceAlg
+
+julia> function PortfolioOptimisers.gerber(ce::GerberCovariance{<:Any, <:Any, <:Any,
+                                                                <:MyUnstandardisedGerberCovarianceAlg},
+                                           X::PortfolioOptimisers.MatNum,
+                                           sd::PortfolioOptimisers.ArrNum)
+           rho = rand(StableRNGs.StableRNG(420), size(X, 2), size(X, 2))
+           rho = rho * rho'
+           return StatsBase.cov2cor!(rho)
+       end
+
+julia> function PortfolioOptimisers.factory(alg::MyUnstandardisedGerberCovarianceAlg,
+                                            w::StatsBase.AbstractWeights)
+           return MyUnstandardisedGerberCovarianceAlg(; w = w)
+       end
+
+julia> cor(GerberCovariance(; alg = MyUnstandardisedGerberCovarianceAlg()),
+           [1.0 2.0; 0.3 0.7; 0.5 1.1])
+2×2 Matrix{Float64}:
+ 1.0      0.64112
+ 0.64112  1.0
+
+julia> cov(GerberCovariance(; alg = MyUnstandardisedGerberCovarianceAlg()),
+           [1.0 2.0; 0.3 0.7; 0.5 1.1])
+2×2 Matrix{Float64}:
+ 0.13      0.153913
+ 0.153913  0.443333
+
+julia> PortfolioOptimisers.factory(GerberCovariance(; alg = MyUnstandardisedGerberCovarianceAlg()),
+                                   StatsBase.Weights([1, 2, 3]))
+GerberCovariance
+   ve ┼ SimpleVariance
+      │          me ┼ SimpleExpectedReturns
+      │             │     w ┼ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+      │             │   idx ┴ nothing
+      │           w ┼ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+      │   corrected ┴ Bool: true
+  pdm ┼ Posdef
+      │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton
+      │   kwargs ┴ @NamedTuple{}: NamedTuple()
+    t ┼ Float64: 0.5
+  alg ┼ MyUnstandardisedGerberCovarianceAlg
+      │   w ┴ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+```
+
 # Related
 
   - [`GerberCovarianceAlgorithm`](@ref)
@@ -63,6 +169,103 @@ Abstract supertype for all standardised Gerber covariance algorithm types. These
 
 Concrete types implementing standardised Gerber covariance algorithms should subtype `StandardisedGerberCovarianceAlgorithm`.
 
+# Interfaces
+
+In order to implement a new Gerber algorithm which will work seamlessly with the library, subtype `StandardisedGerberCovarianceAlgorithm` with all necessary parameters as part of the struct, and implement the following methods:
+
+## Gerber correlation
+
+  - `PortfolioOptimisers.gerber(ce::GerberCovariance{<:Any, <:Any, <:Any, <:StandardisedGerberCovarianceAlgorithm}, X::MatNum, sd::ArrNum) -> MatNum`: Unstandardised Gerber correlation matrix.
+
+### Arguments
+
+  - $(arg_dict[:gerbce]). Configured with the custom `StandardisedGerberCovarianceAlgorithm` algorithm.
+  - $(arg_dict[:X])
+  - $(arg_dict[:stdarr])
+
+### Returns
+
+  - $(ret_dict[:rho])
+
+## Factory (if algorithm uses observation weights)
+
+If the algorithm uses observation weights, the `factory` method will update the algorithm with the new weights.
+
+  - `PortfolioOptimisers.factory(alg::StandardisedGerberCovarianceAlgorithm, w::StatsBase.AbstractWeights) -> StandardisedGerberCovarianceAlgorithm`: Updates the algorithm with the new weights.
+
+### Arguments
+
+  - $(arg_dict[:gerbalg])
+  - $(arg_dict[:ow])
+
+### Returns
+
+  - $(ret_dict[:algw])
+
+## Examples
+
+We can create a dummy standardised Gerber covariance algorithm as follows:
+
+```jldoctest
+julia> struct MyStandardisedGerberCovarianceAlg{T} <:
+              PortfolioOptimisers.StandardisedGerberCovarianceAlgorithm
+           w::T
+           function MyStandardisedGerberCovarianceAlg(w::PortfolioOptimisers.Option{<:StatsBase.AbstractWeights})
+               if !isnothing(w)
+                   @assert(!isempty(w))
+               end
+               return new{typeof(w)}(w)
+           end
+       end
+
+julia> function MyStandardisedGerberCovarianceAlg(;
+                                                  w::PortfolioOptimisers.Option{<:StatsBase.AbstractWeights} = nothing)
+           return MyStandardisedGerberCovarianceAlg(w)
+       end
+MyStandardisedGerberCovarianceAlg
+
+julia> function PortfolioOptimisers.gerber(ce::GerberCovariance{<:Any, <:Any, <:Any,
+                                                                <:MyStandardisedGerberCovarianceAlg},
+                                           X::PortfolioOptimisers.MatNum)
+           rho = rand(StableRNGs.StableRNG(420), size(X, 2), size(X, 2))
+           rho = rho * rho'
+           return StatsBase.cov2cor!(rho)
+       end
+
+julia> function PortfolioOptimisers.factory(alg::MyStandardisedGerberCovarianceAlg,
+                                            w::StatsBase.AbstractWeights)
+           return MyStandardisedGerberCovarianceAlg(; w = w)
+       end
+
+julia> cor(GerberCovariance(; alg = MyStandardisedGerberCovarianceAlg()),
+           [1.0 2.0; 0.3 0.7; 0.5 1.1])
+2×2 Matrix{Float64}:
+ 1.0      0.64112
+ 0.64112  1.0
+
+julia> cov(GerberCovariance(; alg = MyStandardisedGerberCovarianceAlg()),
+           [1.0 2.0; 0.3 0.7; 0.5 1.1])
+2×2 Matrix{Float64}:
+ 0.13      0.153913
+ 0.153913  0.443333
+
+julia> PortfolioOptimisers.factory(GerberCovariance(; alg = MyStandardisedGerberCovarianceAlg()),
+                                   StatsBase.Weights([1, 2, 3]))
+GerberCovariance
+   ve ┼ SimpleVariance
+      │          me ┼ SimpleExpectedReturns
+      │             │     w ┼ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+      │             │   idx ┴ nothing
+      │           w ┼ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+      │   corrected ┴ Bool: true
+  pdm ┼ Posdef
+      │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton
+      │   kwargs ┴ @NamedTuple{}: NamedTuple()
+    t ┼ Float64: 0.5
+  alg ┼ MyStandardisedGerberCovarianceAlg
+      │   w ┴ Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]
+```
+
 # Related
 
   - [`GerberCovarianceAlgorithm`](@ref)
@@ -498,7 +701,7 @@ The algorithm proceeds as follows:
       + `D`: Entries where `X .<= -ce.t * sd`.
   - Compute the signed indicator matrix `UmD = U - D`.
   - Compute the raw Gerber2 matrix `H = UmD' * UmD`.
-  - Normalize: `rho = H ⊘ (h * h')`, where `h = sqrt.(LinearAlgebra.diag(H))`.
+  - Normalise `rho = H ⊘ (h * h')`, where `h = sqrt.(LinearAlgebra.diag(H))`.
   - The result is projected to the nearest positive definite matrix using `posdef!`.
 
 # Related
@@ -554,7 +757,7 @@ The algorithm proceeds as follows:
       + `D`: Entries where `X .<= -ce.t`.
   - Compute the signed indicator matrix `UmD = U - D`.
   - Compute the raw Gerber2 matrix `H = UmD' * UmD`.
-  - Normalize: `rho = H ⊘ (h * h')`, where `h = sqrt.(LinearAlgebra.diag(H))`.
+  - Normalise `rho = H ⊘ (h * h')`, where `h = sqrt.(LinearAlgebra.diag(H))`.
   - The result is projected to the nearest positive definite matrix using `posdef!`.
 
 # Related
@@ -744,7 +947,8 @@ Return a new `GerberCovariance` estimator with the specified observation weights
 
 # Details
 
-  - Applies `factory(ce.ve, w)` to update the variance estimator.
+  - Calls `factory(ce.alg, w)` to update the algorithm (current algorithms do not use weights, this for future proofing).
+  - Calls `factory(ce.ve, w)` to update the variance estimator.
   - Preserves the other fields of the original estimator.
 
 # Examples
@@ -786,7 +990,8 @@ GerberCovariance
   - [`factory`](@ref)
 """
 function factory(ce::GerberCovariance, w::StatsBase.AbstractWeights)
-    return GerberCovariance(; alg = ce.alg, ve = factory(ce.ve, w), pdm = ce.pdm, t = ce.t)
+    return GerberCovariance(; alg = factory(ce.alg, w), ve = factory(ce.ve, w),
+                            pdm = ce.pdm, t = ce.t)
 end
 
 export GerberCovariance, Gerber0, Gerber1, Gerber2, StandardisedGerber0,