Merge pull request #11 from mbk-dev/dev

feat: several improvements to Portoflio and AssetList classes, CONTRIBUTING.md

Author: chilango74

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to Okama
+
+Thank you for your interest in _okama_ and wanting to contribute. Your help is much appreciated.
+
+Here are some guidelines for contributing.
+
+Please refer to the [RoadMap](https://github.com/mbk-dev/okama/blob/master/README.md#roadmap) for a list of areas where _okama_ could benefit
+from. In addition, the following is always welcome:
+
+- Report bugs using [Issues](https://github.com/mbk-dev/okama/issues)
+- Request new functionality and enhancement in [Discussions](https://github.com/mbk-dev/okama/discussions)
+- Improve performance of existing code
+- Help us to write tests. If you learn about quantitative finance and/or unit testing in python it's a good place to start. Test coverage of _okama_ could be verified at [Coveralls](https://coveralls.io/github/mbk-dev/okama?branch=dev).
+
+## Guidelines
+
+### Seek early feedback
+
+Before you start coding your contribution, it may be wise to raise an issue on GitHub to discuss whether the contribution is appropriate for the project.
+
+### Create a fork
+First off, you should create a fork. Within your fork, create a new branch. Depending on what you want to do, choose one of the following prefixes for your branch:
+- fix: <name of your fix> to be used for bug fixes
+- feat: <name of new feature> to be used for adding a new feature
+
+### Commit your changes
+Make your changes to the code, and write sensible commit messages.
+
+In general [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) is recommended for the commits.
+
+### Code style
+
+To keep everything consistent, please use [Black](https://github.com/psf/black) with default settings.
+
+### Testing
+
+Any contributions **must** be accompanied by unit tests (written with `pytest`). These are very simple to write. Just find the relevant test file (or create a new one), and write some `assert` statements. If you need a data presets please use [tests/conftests.py](tests/conftests.py) fixtures. Tests should cover core functionality, warnings/errors (check that they are raised as expected), and limiting behaviour or edge cases.
+
+### Documentation
+
+We would appreciate if changes are accompanied by relevant documentation.
+
+Inline comments (and docstrings!) are great when needed, but don't go overboard. A lot of the explanation can and should be offloaded to ReadTheDocs. Docstrings should follow [PEP257](https://stackoverflow.com/questions/2557110/what-to-put-in-a-python-module-docstring) semantically. Okama uses `sphinx` and "numpy" style generate Documentation automatically from docstrings.
+
+### Create a Pull Request
+Create a new [Pull Request](https://github.com/mbk-dev/okama/pulls). Describe what your changes are in the Pull Request. If your contribution fixes a bug, or adds a features listed under [issues](https://github.com/mbk-dev/okama/issues) as "#12", please add "fixes #12" or "closes #12". 
+
+## Questions
+
+If you have any questions related to the project, it is probably easiest to ask it in [Discussions](https://github.com/mbk-dev/okama/discussions).
+
+## Bugs/issues
+
+If you find any bugs, feel free to [raise an issue](https://github.com/mbk-dev/okama/issues) include as many details as possible and follow the following guidelines:
+
+- Descriptive title so that other users can see the existing issues
+- Operating system, python version, and python distribution (optional)
+- _okama_ version you are using
+- Minimal example for reproducing the issue
+- What you expected to happen
+- What actually happened
+- error messages if applicable

README.md

@@ -4,7 +4,7 @@
         <img src="https://img.shields.io/badge/python-v3-brightgreen.svg"
             alt="python"></a> &nbsp;
     <a href="https://pypi.org/project/okama/">
-        <img src="https://img.shields.io/badge/pypi-v0.98-brightgreen.svg"
+        <img src="https://img.shields.io/badge/pypi-v0.99-brightgreen.svg"
             alt="pypi"></a> &nbsp;
     <a href='https://coveralls.io/github/mbk-dev/okama?branch=master'>
         <img src='https://coveralls.io/repos/github/mbk-dev/okama/badge.svg?branch=master' 
@@ -24,10 +24,24 @@ The package is supplied with **free** «end of day» historical stock markets da
 >...entities should not be multiplied without necessity
 >
 > -- <cite>William of Ockham (c. 1287–1347)</cite>
+
+## Table of contents
+
+- [Okama main features](#okama-main-features)
+- [Financial data and macroeconomic indicators](#financial-data-and-macroeconomic-indicators)
+  - [End of day historical data](#end-of-day-historical-data)
+  - [Macroeconomic indicators](#macroeconomic-indicators)
+  - [Other historical data](#other-historical-data)
+- [Installation](#installation)
+- [Getting started](#getting-started)
+- [RoadMap](#roadmap)
+- [Contributing to okama](#contributing-to-okama)
+- [Communication](#communication)
+
 ## Okama main features
 
 - Investment portfolio constrained Markowitz Mean-Variance Analysis (MVA) and optimization
-- Rebalanced portfolio optimization
+- Rebalanced portfolio optimization with constraints (multi-period Efficient Frontier)
 - Monte Carlo Simulations for financial assets and investment portfolios
 - Popular risk metrics: VAR, CVaR, semi-deviation, variance and drawdowns
 - Forecasting models according to normal and lognormal distribution
@@ -50,7 +64,7 @@ The package is supplied with **free** «end of day» historical stock markets da
 
 ### Macroeconomic indicators
 
-- Inflation
+- Inflation for many countries (USA, United Kingdom, European Union, Russia etc.)
 - Central bank rates
 
 ### Other historical data
@@ -62,9 +76,10 @@ The package is supplied with **free** «end of day» historical stock markets da
 
 `pip install okama`
 
-or:
+The latest development version can be installed directly from GitHub:
+
+`pip install git+https://github.com/mbk-dev/okama@dev`
 
-`pip install git+https://github.com/mbk-dev/okama`
 
 ## Getting started
 
@@ -139,17 +154,29 @@ map = ok.Plots(ls, ccy='USD').plot_transition_map(cagr=False)
 
 More examples are available in [Jupyter Notebooks](https://github.com/mbk-dev/okama/tree/master/notebooks).
 
-## Communication
+## RoadMap
 
-For basic usage questions (e.g., "_Is XXX currency supported by okama?_") and for sharing ideas please use [GitHub Discussions](https://github.com/mbk-dev/okama/discussions/3).
-Russian language community is available at [okama.io forums](https://community.okama.io/c/python-okama).
-## Issues
+The plan for _okama_ is to add more functions that will be useful to investors and asset managers.
 
-We encourage you to report issues using the [Github tracker](https://github.com/mbk-dev/okama/issues). We welcome all kinds of issues, especially those related to correctness, documentation, performance, and feature requests.
+- Make documentation for the package. Finish docstrings for modules, classes, methods and functions.
+- Add Sharpe, Sortino and Diversification ratios to EfficientFrontier, EfficientFrontierReb and Portfolio classes.
+- Make rebalancing period an attribute of Portfolio class.
+- Add withdrawals as an attribute of Portfolio class.
+- Make AssetList class accept Portfolio instances in a list of assets
+- Add Black-Litterman asset allocation 
+- Accelerate optimization for multi-period Efficient Frontier: minimize_risk and maximize_risk methods of EfficientFrontierReb class.
+- Make a single EfficientFrontier class for all optimizations: single-period or multu-period with rebalancing period as a parameter.
+- Add different utility functions for optimizers: semi-deviation, VaR, CVaR, drawdowns etc.
+- Add more functions based on suggestion of users.
 
 ## Contributing to okama
 
-All contributions, bug reports, bug fixes, documentation improvements, enhancements, frontend implementation and ideas are welcome.
+Contributions are *most welcome*. Have a look at the [Contribution Guide](https://github.com/mbk-dev/okama/blob/master/CONTRIBUTING.md) for more.
+
+## Communication
+
+For basic usage questions (e.g., "_Is XXX currency supported by okama?_") and for sharing ideas please use [GitHub Discussions](https://github.com/mbk-dev/okama/discussions/3).
+Russian language community is available at [okama.io forums](https://community.okama.io/c/python-okama).
 
 ## License
 

main.py

@@ -1,4 +1,3 @@
 import okama as ok
 
-x = ok.AssetList()
-print(x.get_cumulative_return(period=0))
+lse = ok.AssetList(['INRG.LSE'], ccy='GBP')

notebooks/01 howto.ipynb

@@ -807,9 +807,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "py38",
+   "display_name": "py39",
    "language": "python",
-   "name": "py38"
+   "name": "py39"
   },
   "language_info": {
    "codemirror_mode": {
@@ -821,7 +821,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.9.1"
   }
  },
  "nbformat": 4,

notebooks/02 index funds perfomance.ipynb

@@ -38,4 +38,4 @@
 from okama.common.helpers import Float, Frame, Rebalance, Date
 import okama.settings
 
-__version__ = "0.98"
+__version__ = "0.99"

notebooks/03 efficient frontier single period.ipynb

@@ -6,8 +6,8 @@
 class API:
     """
     Set of methods to data from API.
-    TODO: introduce 'from' & 'to' for dates.
     """
+    # TODO: introduce 'from' & 'to' for dates.
 
     api_url = "http://185.63.191.70:5000"