Improve mathematical descriptions in docs. Add power norm x at risk measure, add scenario weights to drawdown risk measures. Add distributionally robust drawdown at risk measure. (#53)

* Docs up to Fees.

* Correctness fix to drawdowns auxiliary function used for plotting.

* Remove side effects from Y X at Risk risk measure families.

* Add distributionally robust conditional drawdown at risk.

* Add Power Norm X at Risk measures.

* Implement Power X at Risk measures.

* Implement Distributionally Robust Drawdown at Risk measure.

* Enable Drawdown at Risk for non-clustering optimisation.

* Add scenario weights to Y Drawdown at Risk measures.

Author: dcelisgarza

.github/workflows/Copier.yml

@@ -44,7 +44,7 @@ jobs:
           pre-commit run -a || true # Ignore pre-commit errors
       - name: Create Pull Request
         id: cpr
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           token: ${{ secrets.COPIER_PAT }}
           commit-message: ":robot: BestieTemplate.jl update"

.github/workflows/PreCommitUpdate.yml

@@ -27,7 +27,7 @@ jobs:
           pre-commit autoupdate || true
       - name: Create Pull Request
         id: cpr
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           commit-message: "chore: :robot: pre-commit update"
           title: "[AUTO] pre-commit update"

.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.46.0
+    rev: v0.47.0
     hooks:
       - id: markdownlint-fix
   - repo: https://github.com/citation-file-format/cffconvert

Project.toml

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

docs/src/api/15_Turnover.md

@@ -1,6 +1,6 @@
-# Turnover
+# Asset turnover
 
-The turnover is used to measure the absolute weight change between the current weights and benchmark weights. They can be used to compute fees, or as a constraint. It can also be used as a risk measure, but we will detail that use in [Risk Measures](./18_RiskMeasures/17_TurnoverRiskMeasure.md)
+The turnover is used to measure the absolute weight change between the current weights and benchmark weights. They can be used to compute fees, or as a constraint. It can also be used as a risk measure, but we will detail that use in [Risk Measures](./19_RiskMeasures/17_TurnoverRiskMeasure.md)
 
 ```@docs
 TurnoverEstimator

docs/src/api/16_Fees.md

@@ -0,0 +1,15 @@
+# Portfolio and asset fees
+
+In active, and small quantity investing, fees can be a non-negligible factor that affects portfolio returns. `PortfolioOptimisers.jl` has the capability of including a variety of fees.
+
+```@docs
+FeesEstimator
+Fees
+FeesE_Fees
+fees_constraints
+fees_view
+calc_fees
+calc_fixed_fees
+calc_asset_fees
+calc_asset_fixed_fees
+```

docs/src/api/16_Portfolio_Returns.md

@@ -0,0 +1,10 @@
+# Net returns and drawdowns
+
+Net returns and drawdowns are two of the performance metrics of a portfolio. Here we define functions used to compute portfolio returns and related quantities.
+
+```@docs
+calc_net_returns
+calc_net_asset_returns
+cumulative_returns
+drawdowns
+```