Home

Awesome

By Investors, For Investors.

<br> <div align="center"> <img src="https://github.com/user-attachments/assets/470f1d59-09c6-4b95-af7e-f142764d8195"/> <br><br><br><br>

Open In Colab

</div> <br>

Want to read this in Mandarin πŸ‡¨πŸ‡³? Click here

EigenLedger (prev. "Empyrial") is a Python-based open-source quantitative investment library dedicated to financial institutions and retail investors, officially released in March 2021. Already used by thousands of people working in the finance industry, EigenLedger aims to become an all-in-one platform for portfolio management, analysis, and optimization.

EigenLedger empowers portfolio management by bringing the best of performance and risk analysis in an easy-to-understand, flexible and powerful framework.

With EigenLedger, you can easily analyze security or a portfolio in order to get the best insights from it. This is mainly a wrapper of financial analysis libraries such as Quantstats and PyPortfolioOpt.

<br> <br> <div align="center">
Table of Contents πŸ“–
1. Installation
2. Features
3. Documentation
4. Usage example
5. Download the tearsheet
6. Contribution and Issues
7. Contributors
8. Contact
9. License
</div>

Installation

You can install EigenLedger using pip:

pip install empyrial

For a better experience, we advise you to use EigenLedger on a notebook (e.g., Jupyter, Google Colab)

Note: macOS users will need to install Xcode Command Line Tools.

Note: Windows users will need to install C++. (download, install instructions)

Features

<div align="center">
Feature πŸ“°Status
Engine (backtesting + performance analysis):star: Released on May 30, 2021
Optimizer:star: Released on Jun 7, 2021
Rebalancing:star: Released on Jun 27, 2021
Risk manager:star: Released on Jul 5, 2021
Sandbox:star: Released on Jul 17, 2021
Support for custom data:star: Released on Aug 12, 2023
</div>

Documentation

Full documentation (website)

Usage

EigenLedger Engine

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01", 
    portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"], 
    weights = [0.2, 0.2, 0.2, 0.2, 0.2],  # equal weighting is set by default
    benchmark = ["SPY"]  # SPY is set by default
)

empyrial(portfolio)

Use custom data

See doc here to learn how to do this.

Calendar Rebalancing

A portfolio can be rebalanced for either a specific time period or for specific dates using the rebalance option.

Rebalance for Time Period

Time periods available for rebalancing are 2y, 1y, 6mo, quarterly, monthly

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01", 
    portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"], 
    weights = [0.2, 0.2, 0.2, 0.2, 0.2],  # equal weighting is set by default
    benchmark = ["SPY"],  # SPY is set by default
    rebalance = "1y"
)

empyrial(portfolio)

Rebalance for Custom Dates

You can rebalance a portfolio by specifying a list of custom dates.
⚠️ When using custom dates, the first date of the list must correspond with the start_date and the last element should correspond to the end_date which is today's date by default.

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01", 
    portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"], 
    weights = [0.2, 0.2, 0.2, 0.2, 0.2],  # equal weighting is set by default
    benchmark = ["SPY"],  # SPY is set by default
    rebalance = ["2018-06-09", "2019-01-01", "2020-01-01", "2021-01-01"]
)

empyrial(portfolio)

Optimizer

The default optimizer is equal weighting. You can specify custom weights, if desired.

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01",
    portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"], 
    weights = [0.1, 0.3, 0.15, 0.25, 0.2],   # custom weights
    rebalance = "1y"  # rebalance every year
)

empyrial(portfolio)

You can also use the built-in optimizers. There are 4 optimizers available:

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01",
    portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"],
    optimizer = "EF",
    rebalance = "1y"  # rebalance every year
)

portfolio.weights

Output:

[0.0, 0.0, 0.0348, 0.9652, 0.0]

We can see that the allocation has been optimized.

Risk Manager

3 Risk Managers are available:

from empyrial import empyrial, Engine

portfolio = Engine(
    start_date = "2018-08-01",
    portfolio= ["BABA", "PDD", "KO", "AMD","^IXIC"], 
    optimizer = "EF",
    rebalance = "1y",  # rebalance every year
    risk_manager = {"Max Drawdown" : -0.2}  # Stop the investment when the drawdown becomes superior to -20%
)

empyrial(portfolio)

EigenLedger Outputs

<div align="center">

image image image image image image image image image image image

</div>

Download the Tearsheet

You can use the get_report() function of EigenLedger to generate a tearsheet, and then download this as a PDF document.

from empyrial import get_report, Engine

portfolio = Engine(
      start_date = "2018-08-01",
      portfolio = ["BABA", "PDD", "KO", "AMD","^IXIC"],
      optimizer = "EF",
      rebalance = "1y", #rebalance every year
      risk_manager = {"Stop Loss" : -0.2}
)

get_report(portfolio)

Output:

image

Stargazers over time

<div align="center">

θΏ½ζ˜Ÿζ—ηš„ζ—Άι—΄

</div>

Contribution and Issues

EigenLedger uses GitHub to host its source code. Learn more about the Github flow.

For larger changes (e.g., new feature request, large refactoring), please open an issue to discuss first.

Smaller improvements (e.g., document improvements, bugfixes) can be handled by the Pull Request process of GitHub: pull requests.

You contributions will be reviewed, potentially modified, and hopefully merged into EigenLedger.

Contributors

Thanks goes to these wonderful people (emoji key):

All Contributors

<table> <tr> <td align="center"><a href="https://github.com/BrendanGlancy"><img src="https://avatars.githubusercontent.com/u/61941978?v=4" width="100px;" alt=""/><br /><sub><b>Brendan Glancy</b></sub></a><br /><a title="Code">πŸ’»</a> <a title="Bug report">πŸ›</a></td> <td align="center"><a href="https://github.com/rslopes"><img src="https://avatars.githubusercontent.com/u/24928343?v=4" width="100px;" alt=""/><br /><sub><b>Renan Lopes</b></sub></a><br /><a title="Code">πŸ’»</a> <a title="Bug report">πŸ›</a></td> <td align="center"><a href="https://github.com/markthebault"><img src="https://avatars.githubusercontent.com/u/3846664?v=4" width="100px;" alt=""/><br /><sub><b>Mark Thebault</b></sub></a><br /><a title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/diegodalvarez"><img src="https://avatars.githubusercontent.com/u/48641554?v=4" width="100px;" alt=""/><br /><sub><b>Diego Alvarez</b></sub></a><br /><a title="Code">πŸ’»πŸ›</a></td> <td align="center"><a href="https://github.com/rakeshbhat9"><img src="https://avatars.githubusercontent.com/u/11472305?v=4" width="100px;" alt=""/><br /><sub><b>Rakesh Bhat</b></sub></a><br /><a title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/Haizzz"><img src="https://avatars.githubusercontent.com/u/5275680?v=4" width="100px;" alt=""/><br /><sub><b>Anh Le</b></sub></a><br /><a title="Bug report">πŸ›</a></td> <td align="center"><a href="https://github.com/TonyZhangkz"><img src="https://avatars.githubusercontent.com/u/65281213?v=4" width="100px;" alt=""/><br /><sub><b>Tony Zhang</b></sub></a><br /><a title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/eltociear"><img src="https://avatars.githubusercontent.com/u/22633385?v=4" width="100px;" alt=""/><br /><sub><b>Ikko Ashimine</b></sub></a><br /><a title="Code">βœ’οΈ</a></td> <td align="center"><a href="https://www.youtube.com/watch?v=-4qx3tbtTgs"><img src="https://avatars.githubusercontent.com/u/50767660?v=4" width="100px;" alt=""/><br /><sub><b>QuantNomad</b></sub></a><br /><a title="Code">πŸ“Ή</a></td> <td align="center"><a href="https://github.com/buckleyc"><img src="https://avatars.githubusercontent.com/u/4175900?v=4" width="100px;" alt=""/><br /><sub><b>Buckley</b></sub></a><br /><a title="Code">βœ’οΈπŸ’»</a></td> <td align="center"><a href="https://github.com/agn35"><img src="https://lh3.googleusercontent.com/a-/AOh14GhXGFHHpVQTL2r23oEXFssH0f7RyoGDihrS_HmT=s48" width="100px;" alt=""/><br /><sub><b>Adam Nelsson</b></sub></a><br /><a title="Code">πŸ’»</a></td> <td align="center"><a href="https://github.com/rgleavenworth"><img src="https://avatars.githubusercontent.com/u/87843950?v=4" width="100px;" alt=""/><br /><sub><b>Ranjan Grover</b></sub></a><br /><a title="Code">πŸ›πŸ’»</a></td> </tr> </table>

This project follows the all-contributors specification. Contributions of any kind are welcome!

Credit

This library has also been made possible because of the work of these incredible people:

Contact

You are welcome to contact us by email at santoshpassoubady@gmail.com or in EigenLedger's discussion space

License

MIT