3.8 testing, some docs

.github/workflows/test.yml

@@ -40,7 +40,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
 
     steps:
 
@@ -55,9 +55,16 @@ jobs:
       # ~ Q4 2023 for python 3.11
       # ~ Q4 2022 for python 3.10
       # ~ Q4 2021 for python 3.9
+      # ~ Q4 2020 for python 3.8
+      # we find those by browsing release histories on https://pypi.org/
+      # we skip packages releases that were current for short times
       # we only install the base packages here,
       # then pip below figures out the others
 
+      - name: If running on python 3.8 install some old dependencies
+        if: ${{ matrix.python-version == '3.8'}}
+        run: python -m pip install numpy==1.19.3 scipy==1.5.3 cvxpy==1.1.5 pandas==1.1.2 osqp==0.6.1 ecos==2.0.7.post1 scs==2.1.2
+
       - name: If running on python 3.9 install some old dependencies
         if: ${{ matrix.python-version == '3.9'}}
         run: python -m pip install numpy==1.21.5 scipy==1.7.3 cvxpy==1.1.17 pandas==1.4.0 osqp==0.6.2.post0 ecos==2.0.11 scs==2.1.4

Makefile

@@ -8,7 +8,7 @@ TESTS         = $(PROJECT)/tests
 BUILDDIR      = build
 ENVDIR        = env
 BINDIR        = $(ENVDIR)/bin
-EXTRA_SCRIPTS = bumpversion.py run_examples.py
+EXTRA_SCRIPTS = bumpversion.py
 EXAMPLES      = examples/*.py
 
 ifeq ($(OS), Windows_NT)

docs/forecasts.rst

@@ -0,0 +1,21 @@
+Forecasters
+===========
+
+*Work in progress.*
+
+.. automodule:: cvxportfolio.forecast
+
+.. py:module:: cvxportfolio.forecast
+     :noindex:
+
+.. autoclass:: HistoricalMeanReturn
+
+.. autoclass:: HistoricalVariance
+
+.. autoclass:: HistoricalStandardDeviation
+
+.. autoclass:: HistoricalMeanError
+
+.. autoclass:: HistoricalLowRankCovarianceSVD
+
+.. autoclass:: HistoricalFactorizedCovariance

docs/index.rst

@@ -113,12 +113,14 @@ Table of Contents
    :maxdepth: 2
 
    hello_world
+   quickstart
    manual
    policies
    simulator
    objective_terms
    constraints
    result
    data
+   forecasts
    examples
 

docs/manual.rst

@@ -10,6 +10,8 @@ to know. The code blocks in this document assume the following imports
     import numpy as np
     import pandas as pd
 
+.. _passing-data:
+
 Passing Data
 ------------
 

docs/quickstart.rst

@@ -0,0 +1,52 @@
+Quickstart
+==========
+
+Cvxportfolio is designed for ease of use and extension. With it, you can
+quickly experiment with financial trading strategies and develop new ones.
+
+For example, a classic Markowitz optimization strategy 
+
+.. math::
+
+    \begin{array}{ll}
+         \text{maximize} & w^T \mathbf{E}[r] - \frac{1}{2} w^T \mathbf{Var}[r] w \\
+         \text{subject to} & w \geq 0, w^T \mathbf{1} <= 1
+    \end{array}
+
+is specified as follows
+
+.. code-block:: python
+    
+    import cvxportfolio as cvx
+    
+    objective = cvx.ReturnsForecast() - 0.5 * cvx.FullCovariance()
+    constraints = [cvx.LongOnly(), cvx.LeverageLimit(1)]
+    
+    strategy = cvx.SinglePeriodOptimization(objective, constraints)
+    
+Here we instantiated an :ref:`optimization-based trading policy <optimization-policies-page>`.
+Cvxportfolio defines two (the other is a simple extension of this). 
+Optimization-based policies are defined by an objective function, which is 
+maximized, and a list of constraints, that are imposed on the solution.
+The objective function is specified as a linear combination of simple
+terms, :doc:`we provide many <objective_terms>`, and it's easy to define new ones.
+We provide as well :doc:`many constraints <constraints>` to choose from, and
+it's even easier to define new ones.
+
+Where are the assets' names?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cvxportfolio policies are symbolic, they only define the logic of a trading 
+strategy. They work with any selection of assets. 
+The two objective terms defined above, however, need to know the values of
+the expected returns and the covariance matrix. 
+You can :ref:`pass Pandas dataframes <passing-data>` for those, and in that
+case your dataframes should contain the assets' names you want to trade. 
+Or, if you want, or you can rely on :doc:`forecasters <forecasts>` to compute those
+(iteratively, in back-testing) using past data. That is what happens in the 
+code shown above, the default parameters of :class:`cvxportfolio.ReturnsForecast`
+and :class:`cvxportfolio.FullCovariance` are forecasters that compute historical
+means and historical covariances respectively, at each point in time if running in a back-test
+or once, if running live, by using the policy's :meth:`execute` method.
+
+*To be continued.*