Fix API bug in prices_to_returns when using a benchmark. Add more docs. (#48)

* Update pre-commit.

*  Fix bug in prices_to_returns when using a benchmark.

* Docs up to `03_Preprocessing`.

Author: dcelisgarza

.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
       - id: check-merge-conflict
         args: [--assume-in-merge]
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.45.0
+    rev: v0.46.0
     hooks:
       - id: markdownlint-fix
   - repo: https://github.com/citation-file-format/cffconvert
@@ -42,7 +42,7 @@ repos:
     hooks:
       - id: yamllint
   - repo: https://github.com/ericphanson/ExplicitImports.jl
-    rev: v1.13.2
+    rev: v1.14.0
     hooks:
       - id: explicit-imports
         name: ExplicitImports checks

Project.toml

@@ -1,6 +1,6 @@
 name = "PortfolioOptimisers"
 uuid = "e0036ec9-05e5-505d-a6a9-07af41c94861"
-version = "0.11.0"
+version = "0.11.1"
 authors = ["Daniel Celis Garza <daniel.celis.garza@gmail.com>"]
 
 [deps]

docs/make.jl

@@ -2,10 +2,11 @@ using PortfolioOptimisers
 using Documenter, DocumenterTools, DocumenterCitations, Literate, StatsPlots, GraphRecipes,
       Handcalcs, StatsBase, DocumenterVitepress
 
-exported = names(PortfolioOptimisers)
+exported_symbols = names(PortfolioOptimisers)
 all_symbols = names(PortfolioOptimisers; all = true)
 filter!(x -> !contains(string(x), r"#|^eval$|^include$"), all_symbols)
-for sym in setdiff!(all_symbols, exported)
+private_symbols = setdiff(all_symbols, exported_symbols)
+for sym in private_symbols
     eval(quote
              import PortfolioOptimisers: $(sym)
          end)

docs/src/References.bib

@@ -1,3 +1,14 @@
+@article{brinson_attribution,
+  title     = {Measuring non-US. equity portfolio performance},
+  author    = {Brinson, Gary P and Fachler, Nimrod},
+  journal   = {The Journal of Portfolio Management},
+  volume    = {11},
+  number    = {3},
+  pages     = {73--76},
+  year      = {1985},
+  publisher = {Portfolio Management Research}
+}
+
 @article{DBHTs,
   title     = {Hierarchical information clustering by means of topologically embedded graphs},
   author    = {Song, Won-Min and Di Matteo, Tiziana and Aste, Tomaso},

docs/src/api/01_Base.md

@@ -34,6 +34,14 @@ IsEmptyError
 IsNonFiniteError
 ```
 
+## Utility types
+
+Custom types are the bread and butter of `PorfolioOptimisers.jl`, the following types non-specific and used throughout the library.
+
+```@docs
+VecScalar
+```
+
 ## Base type aliases
 
 `PortfolioOptimisers.jl` heavily relies on `Julia`'s dispatch and type system to ensure data validity. Many custom types and functions/methods can accept different data types. These can be represented as type unions, many of which are used throughout the library. The following type aliases centralise these union definitions, as well as improving correctness and maintainability.
@@ -66,4 +74,6 @@ VecDate
 Dict_Vec
 Sym_Str
 Str_Vec
+Num_VecNum_VecScalar
+Num_ArrNum_VecScalar
 ```

docs/src/api/02_Tools.md

@@ -1,35 +1,49 @@
 # Tools
 
-## Public
+`PorfolioOptimisers.jl` is a complex codebase which uses a variety of general purpose tools including functions, constants and types.
+
+## Utility functions
+
+We strive to be as type-stable, inferrable, and immutable as possible in order to improve robustness, performance, and correctness. These functions help us achieve these goals.
 
 ```@docs
-VecScalar
-brinson_attribution
 traverse_concrete_subtypes
 concrete_typed_array
 factory(::Nothing, args...; kwargs...)
 ```
 
-## Private
+## Assertions
+
+In order to increase correctness, robustness, and safety, we make extensive use of [defensive programming](https://en.wikipedia.org/wiki/Defensive_programming). The following functions perform some of these validations and are usually called at variable instantiation.
 
 ```@docs
-AbstractReturnsResult
-Num_VecNum_VecScalar
-Num_ArrNum_VecScalar
 assert_nonempty_nonneg_finite_val
+assert_nonempty_gt0_finite_val
 assert_nonempty_finite_val
-assert_nonempty_geq0_finite_val
 assert_matrix_issquare
+```
+
+## Mathematical functions
+
+`PortfolioOptimisers.jl` makes use of various mathematical operators, some of which are generic to support the variety of inputs supported by the library.
+
+```@docs
 :⊗
 :⊙
 :⊘
 :⊕
 :⊖
 dot_scalar
+```
+
+## View functions
+
+[`NestedClustered`](@ref) optimisations need to index the asset universe in order to produce the inner optimisations. These indexing operations are implemented as views, indexing, and custom index generators.
+
+```@docs
 nothing_scalar_array_view
 nothing_scalar_array_view_odd_order
 nothing_scalar_array_getindex
 nothing_scalar_array_getindex_odd_order
-nothing_asset_sets_view
 fourth_moment_index_generator
 ```

docs/src/api/03_Preprocessing.md

@@ -1,16 +1,21 @@
 # Preprocessing
 
-## Public
+## Prices to returns
+
+Other than [`FiniteAllocationOptimisationEstimator`](@ref), all optimisations work based off returns data rather than price data. These functions and types are involved in computing returns.
 
 ```@docs
+AbstractReturnsResult
 ReturnsResult
-drop_incomplete
+_check_names_and_returns_matrix
 prices_to_returns
-select_k_extremes
 ```
 
-## Private
+## Pre-filtering
+
+Price data is often incomplete or noisy, so it can be worthwhile having some pre-filtering steps to remove data that does not contribute meaningful information and may pollute calculations.
 
 ```@docs
-_check_names_and_returns_matrix
+find_complete_indices
+select_k_extremes
 ```

docs/src/api/08_Moments/12_PortfolioOptimisersCovariance.md

@@ -4,5 +4,5 @@
 PortfolioOptimisersCovariance
 cov(ce::PortfolioOptimisersCovariance, X::MatNum; dims = 1, kwargs...)
 cor(ce::PortfolioOptimisersCovariance, X::MatNum; dims = 1, kwargs...)
-drop_correlated
+find_correlated_indices
 ```

docs/src/api/13_ConstraintGeneration/2_LinearConstraintGeneration.md

@@ -25,4 +25,5 @@ _collect_terms!
 _collect_terms
 _eval_numeric_functions
 asset_sets_matrix_view
+nothing_asset_sets_view
 ```

docs/src/api/20_Optimisation/19_Base_FiniteAllocation.md

@@ -0,0 +1,5 @@
+# Base finite allocation
+
+```@docs
+FiniteAllocationOptimisationEstimator
+```