work in progress added

README.rst

@@ -21,7 +21,7 @@ Installation
 Cvxportolio is written in Python and can easily installed in any Python
 environment by simple:
 
-.. code:: console
+.. code:: bash
 
    pip install -U cvxportfolio
 
@@ -43,7 +43,7 @@ Test
 
 After installing you can run our unit test suite in you local environment by
 
-.. code:: console
+.. code:: bash
 
    python -m cvxportfolio.tests
 
@@ -109,8 +109,9 @@ are available in the code repository.
 `The original examples from the paper 
 <https://github.com/cvxgrp/cvxportfolio/tree/0.0.X/examples>`_ 
 are visible in a dedicated branch,
-and are being translated to run with the stable versions (``1.0.*``) of the
-library. 
+and are being translated to run with the stable versions (``1.0.0`` and above) of the
+library. The translations are visible at `this documentation page
+<https://www.cvxportfolio.com/en/latest/examples/paper_examples.html>_`.
 
 We show in the example on `user-provided
 forecasters <https://github.com/cvxgrp/cvxportfolio/blob/master/examples/user_provided_forecasters.py>`__
@@ -156,7 +157,7 @@ repository (or, `fork on
 Github <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__
 and then clone your fork)
 
-.. code:: console
+.. code:: bash
 
    git clone https://github.com/cvxgrp/cvxportfolio.git
    cd cvxportfolio
@@ -166,7 +167,7 @@ Then, you should have a look at our
 and possibly change the ``PYTHON`` variable to match your system’s
 python interpreter. Once you have done that,
 
-.. code:: console
+.. code:: bash
 
    make env
    make test
@@ -178,7 +179,7 @@ test suite.
 You activate the shell environment with one of scripts in ``env/bin``
 (or ``env\Scripts`` on Windows), for example if you use bash on POSIX
 
-.. code:: console
+.. code:: bash
 
    source env/bin/activate
 
@@ -192,7 +193,7 @@ Windows) like we do in the Makefile.
 Additionally, to match our CI/CD pipeline, you may set the following
 `git hooks <https://git-scm.com/docs/githooks>`__
 
-.. code:: console
+.. code:: bash
 
    echo "make lint" > .git/hooks/pre-commit
    chmod +x .git/hooks/pre-commit

docs/examples/paper_examples.rst

@@ -1,6 +1,8 @@
 Original examples from the paper
 ================================
 
+*Work in progress.*
+
 These are the original examples, which were also used to generate plots
 and results in :paper:`chapter 7 of the paper <chapter.7>`. They were
 originally written as IPython notebook, and have been translated into Python

examples/market_neutral.py

@@ -11,19 +11,21 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Market (and dollar) neutral strategy on the SP500 universe.
+"""Market (and dollar) neutral strategy on the NDX100 universe.
 
-We use standard historical means and covariances to build a simple example
-of a market neutral strategy.
+We use standard historical means and factor covariances to build a simple
+example of a market neutral strategy.
 
 We use symbolic hyper-parameters (to be improved, see also
 ``examples.risk_models``) to choose the values that maximize Sharpe ratio
 of the back-test, for illustrative purposes only.
 
 We use all default values for transaction cost (both spread and market impact
-terms) and holding cost (stocks borrow fees) models.
+terms) and holding cost (stocks borrow fees) models. These are used both for
+the optimization and the back-test in
+:class:`cvxportfolio.StockMarketSimulator`.
 
-To improve the Sharpe ratio of such kind of strategies, in practice one would
+To improve the Sharpe ratio of this kind of strategies, in practice, one would
 use returns forecasts produced by some machine learning model. It is very easy
 to plug such forecasts into this strategy, either by providing them as a
 Dataframe or by coding the forecasting logic as a Cvxportfolio native

examples/paper_examples/hello_world.py

@@ -32,7 +32,7 @@
 reproduce exactly the behavior of the early development versions
 of the library.
 
-.. note ::
+.. note::
 
     To run this, you need to install ``yfinance`` and
     ``pandas_datareader``.

examples/paper_examples/multi_period_opt.py

@@ -11,6 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-""""""
+"""*Work in progress.*"""
 
 import cvxportfolio as cvx

examples/paper_examples/rank_and_spo.py

@@ -13,6 +13,8 @@
 # limitations under the License.
 """Ranking vs. SPO example.
 
+*Work in progress.*
+
 This is a close translation of what was done in `this notebook
 <https://github.com/cvxgrp/cvxportfolio/blob/0.0.X/examples/RankAndSPO.ipynb>`_.
 """

examples/paper_examples/real_time_optimization.py

@@ -11,6 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-""""""
+"""*Work in progress.*"""
 
 import cvxportfolio as cvx

examples/paper_examples/single_period_opt.py

@@ -11,6 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-""""""
+"""*Work in progress.*"""
 
 import cvxportfolio as cvx

examples/paper_examples/single_period_opt_lin_tcost.py

@@ -11,6 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-""""""
+"""*Work in progress.*"""
 
 import cvxportfolio as cvx

examples/paper_examples/solution_time.py

@@ -11,6 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-""""""
+"""*Work in progress.*"""
 
 import cvxportfolio as cvx

examples/regression_covariance.py

@@ -19,19 +19,18 @@
 
 .. note::
 
-    The internal interface methods used here **may not be public** 
+    The internal interface methods used here **may not be public**
     and may not covered by the semantic versioning agreement (they might change
     without notice). In general, methods that are shown in the examples are
-    considered public, but for this one it may not be not so.
-
+    considered public, but for this one there is no such guarantee.
 """
 
 import numpy as np
 import pandas as pd
 
 import cvxportfolio as cvx
-
 from cvxportfolio.estimator import Estimator
+
 # from cvxportfolio.forecast import BaseForecast
 
 def _striptime(df):
@@ -61,8 +60,7 @@ def _decorrelate(XtX, obs, gamma):
         obs)
 
 class RegressionBase(Estimator):
-    """Base for linear regression forecasters.
-    """
+    """Base for linear regression forecasters."""
 
     def __init__(self, regressors, gamma=1e-1):
         """Initialize with regressors.
@@ -108,8 +106,8 @@ def values_in_time(self, t, past_returns, **kwargs):
                 self.regressors.index <= pd.Timestamp(t.date())], copy=True)
 
         # to extend to index
-        used_regressors['intercept'] = past_returns.iloc[:,-1]
-        
+        used_regressors['intercept'] = past_returns.iloc[:, -1]
+
         used_regressors = used_regressors.ffill()
         used_regressors -= used_regressors.mean()
         used_regressors /= np.sqrt((used_regressors**2).mean())
@@ -124,15 +122,14 @@ def values_in_time(self, t, past_returns, **kwargs):
         lhs = _decorrelate(_, used_regressors.iloc[-1], gamma=self.gamma)
         # print('lhs', lhs)
 
-        _ = self._obtain_weighted(used_regressors, 
+        _ = self._obtain_weighted(used_regressors,
             t=t, past_returns=past_returns, **kwargs)
 
         return sum(el * _[i] for i, el in enumerate(lhs))
 
 
 class RegressionCovariance(RegressionBase):
-    """Covariance matrix that is obtained by linear regression.
-    """
+    """Covariance matrix that is obtained by linear regression."""
 
     def _obtain_weighted(self, used_regressors, past_returns, **kwargs):
         """Obtain objects weigthed by the regressors.
@@ -153,8 +150,7 @@ def _obtain_weighted(self, used_regressors, past_returns, **kwargs):
             for col in used_regressors]
 
 class RegressionReturns(RegressionBase):
-    """Returns forecast that is obtained by linear regression.
-    """
+    """Returns forecast that is obtained by linear regression."""
 
     def _obtain_weighted(self, used_regressors, past_returns, **kwargs):
         """Obtain objects weighted by the regressors.
@@ -188,9 +184,9 @@ def example_regressors():
     #wage_change = cvx.Fred('CES0500000003').data.pct_change()
     #gdp_change = cvx.Fred('GDP').data.pct_change()
     base_regressors = {
-        'vix':vix, 
-        'rate':rate, 
-        #'wage_change': wage_change, 
+        'vix': vix,
+        'rate': rate,
+        #'wage_change': wage_change,
         #'gdp_change': gdp_change
         }
     regressors = pd.DataFrame(base_regressors)
@@ -255,7 +251,7 @@ def example_regressors():
         start_time='2010-01-01') # can't do earlier than ~2010
         # because regressor not available,
         # need to add logic to include them after some min_history
-    
+
     result_plain.plot()
     result_covregr.plot()
     # result_retregr.plot()