| Name | manchero-method JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Menchero multiperiod performance attribution calculations at a sector and stock level |
| upload_time | 2025-02-04 13:50:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2025 differentialcapital Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
menchero
performance
finance
attribution
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Menchero Method Performance Attribution
**Menchero Method Performance Attribution** is a Python package for performing single- and multi-period performance attribution using the [Menchero multiperiod smoothing](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=574762) method, with support for both **sector-level** and **stock-level** breakdowns. Stock level attributions are calculated using our own internally developed adjustments descibed [here](https://www.differential.co.za/stock-level-extensions-to-mencheros-method-for-portfolio-attributions/)
This library provides:
- **Menchero smoothing** for accurate multi-period attribution of returns.
- **Quality assurance checks** to compare calculated attributions vs. actual active returns.
- **PnL (Profit & Loss) handling** at both sector and stock levels.
- Flexible, **pandas DataFrame**-based interface for integration with Python analytics workflows.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quickstart Example](#quickstart-example)
- [Usage](#usage)
- [Sector-Level Attributions](#sector-level-attributions)
- [Stock-Level Attributions](#stock-level-attributions)
- [How It Works](#how-it-works)
- [Validation and Testing](#validation-and-testing)
- [Contributing](#contributing)
- [License](#license)
---
## Features
- **Menchero multiperiod** smoothing approach to handle multi-day or multi-month performance attribution.
- **Sector-level** vs. **stock-level** breakdowns:
- *Sector-level*: See which sectors drove active performance over time.
- *Stock-level*: Drill down to individual stock attributions, with optional re-allocation logic.
- **PnL inclusion**: Decide whether to include profit-and-loss percentages in your allocation effect.
- **Flexible QA checks**: Compare the summed selection/allocation to the final cumulative active return.
- **Verbose** logging mode for debugging and demonstration.
---
## Installation
You can install this package via pip:
```bash
pip install menchero-method
```
---
## Quickstart Example
```python
import pandas as pd
from menchero_method import sectorAttributions, stockAttributions
# Example: create or load your data as a pandas DataFrame
data = pd.DataFrame({
'date': [...], # Python 'date' objects or Timestamps
'sector': [...], # Sector names (str)
'stock': [...], # Stock names (str), optional for sector-level
'portfolio_weight': [...],
'benchmark_weight': [...],
'stock_return': [...],
'pnl_pct': [...]
})
# Sector-level attributions
sector_output = sectorAttributions(
raw=data,
pnl=True, # include PnL in calculations
check=False, # skip QA checks for brevity
verbose=False # no debug printing
)
# Stock-level attributions
stock_output = stockAttributions(
raw=data,
pnl=True,
check=True, # perform QA checks
verbose=True # print debug info
)
print(sector_output.head())
print(stock_output[0].head()) # if check=True, returns (stock_output, qa_checks)
```
---
## Usage
### Sector-Level Attributions
```python
from menchero_method import sectorAttributions
# Example DataFrame 'df' with columns:
# date, sector, portfolio_weight, benchmark_weight, stock_return, pnl_pct
sector_result = sectorAttributions(
raw=df,
pnl=True, # include or exclude PnL in your calculation
check=False, # set True to return QA checks
verbose=True # optional logging
)
```
- If ```check=True```, returns a tuple ```(sector_result, qa_checks)```.
- The returned DataFrame (or first element of the tuple) is in a “long” format, with columns like ```[date, sector, variable, variable_value]```.
### Stock-Level Attributions
```python
from menchero_method import stockAttributions
# Example DataFrame 'df' with columns:
# date, sector, stock, portfolio_weight, benchmark_weight, stock_return, pnl_pct
stock_result = stockAttributions(
raw=df,
pnl=False, # do not include PnL
check=True,
verbose=False
)
```
- If ```check=True```, returns ```(stock_output, qa_checks)```. Otherwise, returns only ```stock_output```.
- The DataFrame(s) have columns like ```[date, sector, stock, variable, variable_value]```.
- Internally, ```stockAttributions``` calculates sector-level attributions first, then modifies them at the stock level via ```_attributionModify```.
---
## How It Works
1) Input Validation – The library checks that your input DataFrame has the required columns, correct data types, and that weights sum to approximately 1.
2) Menchero Method – The core _menchero function calculates:
- Allocation, Selection, Interaction effects.
- Cumulative returns and active return.
- Menchero smoothing via multiplicative and corrective factors to properly handle compounding.
3) QA Checks (optional) – Sums allocation/selection across dates and compares to the final cumulative active return to ensure correctness.
4) Stock-Level Adjustments – For stock-level attributions, we apply _attributionModify to adjust the final allocation/selection by sector-level results.
---
## Validation and Testing
We maintain a comprehensive test suite that includes:
- **Unit tests** for internal functions (```_menchero```, ```_attributionCheck```, ```_attributionModify```, ```_validateInputData```).
- **Integration tests** for ```sectorAttributions``` and ```stockAttributions.
- **Golden tests** with small, hand-verified datasets to confirm exact numeric results match expected Menchero smoothing outcomes.
To run the tests locally, clone this repository and run:
```python
pytest
```
*(You may need to install development dependencies like ```pytest```.)*
---
## Contributing
Contributions, bug reports, and feature requests are welcome! Please:
1) [Open an issue](https://github.com/differentialcapital/menchero-multiperiod-attributions/issues) describing the problem or suggestion.
2) Fork the repo and create a new branch for your contribution.
3) Submit a pull request with your changes and relevant tests.
We’ll review your pull request as soon as we can.
---
## License
This project is released under the [MIT License](https://opensource.org/license/MIT). Feel free to use it in commercial and private projects. See the [LICENSE](https://github.com/differentialcapital/dev-menchero-smoothing/blob/main/LICENSE) file for details.
---
**Thank you for using the Menchero Method Performance Attribution Package!** If you have any questions or feedback, please open an issue or submit a pull request. Contributions are always welcome.
Raw data
{
"_id": null,
"home_page": null,
"name": "manchero-method",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "menchero, performance, finance, attribution",
"author": null,
"author_email": "Differential Capital Data Science Team <info@differential.co.za>",
"download_url": "https://files.pythonhosted.org/packages/88/b8/1973b6738787954f81292848770568e6df3cea695de5d9107d0014dd103f/manchero_method-0.1.1.tar.gz",
"platform": null,
"description": "# Menchero Method Performance Attribution\r\n\r\n**Menchero Method Performance Attribution** is a Python package for performing single- and multi-period performance attribution using the [Menchero multiperiod smoothing](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=574762) method, with support for both **sector-level** and **stock-level** breakdowns. Stock level attributions are calculated using our own internally developed adjustments descibed [here](https://www.differential.co.za/stock-level-extensions-to-mencheros-method-for-portfolio-attributions/)\r\n\r\nThis library provides:\r\n- **Menchero smoothing** for accurate multi-period attribution of returns.\r\n- **Quality assurance checks** to compare calculated attributions vs. actual active returns.\r\n- **PnL (Profit & Loss) handling** at both sector and stock levels.\r\n- Flexible, **pandas DataFrame**-based interface for integration with Python analytics workflows.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [Features](#features) \r\n- [Installation](#installation) \r\n- [Quickstart Example](#quickstart-example) \r\n- [Usage](#usage) \r\n - [Sector-Level Attributions](#sector-level-attributions) \r\n - [Stock-Level Attributions](#stock-level-attributions) \r\n- [How It Works](#how-it-works) \r\n- [Validation and Testing](#validation-and-testing) \r\n- [Contributing](#contributing) \r\n- [License](#license) \r\n\r\n---\r\n\r\n## Features\r\n\r\n- **Menchero multiperiod** smoothing approach to handle multi-day or multi-month performance attribution. \r\n- **Sector-level** vs. **stock-level** breakdowns: \r\n - *Sector-level*: See which sectors drove active performance over time. \r\n - *Stock-level*: Drill down to individual stock attributions, with optional re-allocation logic. \r\n- **PnL inclusion**: Decide whether to include profit-and-loss percentages in your allocation effect. \r\n- **Flexible QA checks**: Compare the summed selection/allocation to the final cumulative active return. \r\n- **Verbose** logging mode for debugging and demonstration. \r\n\r\n---\r\n\r\n## Installation\r\n\r\nYou can install this package via pip:\r\n\r\n```bash\r\npip install menchero-method\r\n```\r\n\r\n---\r\n\r\n## Quickstart Example\r\n\r\n```python\r\nimport pandas as pd\r\nfrom menchero_method import sectorAttributions, stockAttributions\r\n\r\n# Example: create or load your data as a pandas DataFrame\r\ndata = pd.DataFrame({\r\n 'date': [...], # Python 'date' objects or Timestamps\r\n 'sector': [...], # Sector names (str)\r\n 'stock': [...], # Stock names (str), optional for sector-level\r\n 'portfolio_weight': [...],\r\n 'benchmark_weight': [...],\r\n 'stock_return': [...],\r\n 'pnl_pct': [...]\r\n})\r\n\r\n# Sector-level attributions\r\nsector_output = sectorAttributions(\r\n raw=data, \r\n pnl=True, # include PnL in calculations\r\n check=False, # skip QA checks for brevity\r\n verbose=False # no debug printing\r\n)\r\n\r\n# Stock-level attributions\r\nstock_output = stockAttributions(\r\n raw=data, \r\n pnl=True,\r\n check=True, # perform QA checks \r\n verbose=True # print debug info\r\n)\r\n\r\nprint(sector_output.head())\r\nprint(stock_output[0].head()) # if check=True, returns (stock_output, qa_checks)\r\n```\r\n\r\n---\r\n\r\n## Usage\r\n\r\n### Sector-Level Attributions\r\n\r\n```python\r\nfrom menchero_method import sectorAttributions\r\n\r\n# Example DataFrame 'df' with columns: \r\n# date, sector, portfolio_weight, benchmark_weight, stock_return, pnl_pct\r\nsector_result = sectorAttributions(\r\n raw=df,\r\n pnl=True, # include or exclude PnL in your calculation\r\n check=False, # set True to return QA checks\r\n verbose=True # optional logging\r\n)\r\n```\r\n\r\n- If ```check=True```, returns a tuple ```(sector_result, qa_checks)```.\r\n- The returned DataFrame (or first element of the tuple) is in a \u201clong\u201d format, with columns like ```[date, sector, variable, variable_value]```.\r\n\r\n### Stock-Level Attributions\r\n\r\n```python\r\nfrom menchero_method import stockAttributions\r\n\r\n# Example DataFrame 'df' with columns: \r\n# date, sector, stock, portfolio_weight, benchmark_weight, stock_return, pnl_pct\r\nstock_result = stockAttributions(\r\n raw=df,\r\n pnl=False, # do not include PnL\r\n check=True,\r\n verbose=False\r\n)\r\n```\r\n\r\n- If ```check=True```, returns ```(stock_output, qa_checks)```. Otherwise, returns only ```stock_output```.\r\n- The DataFrame(s) have columns like ```[date, sector, stock, variable, variable_value]```.\r\n- Internally, ```stockAttributions``` calculates sector-level attributions first, then modifies them at the stock level via ```_attributionModify```.\r\n\r\n---\r\n\r\n## How It Works\r\n\r\n1) Input Validation \u2013 The library checks that your input DataFrame has the required columns, correct data types, and that weights sum to approximately 1.\r\n2) Menchero Method \u2013 The core _menchero function calculates:\r\n - Allocation, Selection, Interaction effects.\r\n - Cumulative returns and active return.\r\n - Menchero smoothing via multiplicative and corrective factors to properly handle compounding.\r\n3) QA Checks (optional) \u2013 Sums allocation/selection across dates and compares to the final cumulative active return to ensure correctness.\r\n4) Stock-Level Adjustments \u2013 For stock-level attributions, we apply _attributionModify to adjust the final allocation/selection by sector-level results.\r\n\r\n---\r\n\r\n## Validation and Testing\r\n\r\nWe maintain a comprehensive test suite that includes:\r\n\r\n- **Unit tests** for internal functions (```_menchero```, ```_attributionCheck```, ```_attributionModify```, ```_validateInputData```).\r\n- **Integration tests** for ```sectorAttributions``` and ```stockAttributions.\r\n- **Golden tests** with small, hand-verified datasets to confirm exact numeric results match expected Menchero smoothing outcomes.\r\nTo run the tests locally, clone this repository and run:\r\n\r\n```python\r\npytest\r\n```\r\n\r\n*(You may need to install development dependencies like ```pytest```.)*\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions, bug reports, and feature requests are welcome! Please:\r\n\r\n1) [Open an issue](https://github.com/differentialcapital/menchero-multiperiod-attributions/issues) describing the problem or suggestion.\r\n2) Fork the repo and create a new branch for your contribution.\r\n3) Submit a pull request with your changes and relevant tests.\r\nWe\u2019ll review your pull request as soon as we can.\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is released under the [MIT License](https://opensource.org/license/MIT). Feel free to use it in commercial and private projects. See the [LICENSE](https://github.com/differentialcapital/dev-menchero-smoothing/blob/main/LICENSE) file for details.\r\n\r\n---\r\n\r\n**Thank you for using the Menchero Method Performance Attribution Package!** If you have any questions or feedback, please open an issue or submit a pull request. Contributions are always welcome.\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 differentialcapital Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Menchero multiperiod performance attribution calculations at a sector and stock level",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/differentialcapital/menchero-multiperiod-attributions/blob/main/README.md",
"Source Code": "https://github.com/differentialcapital/menchero-multiperiod-attributions"
},
"split_keywords": [
"menchero",
" performance",
" finance",
" attribution"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8fda4a77b13ff3e3c016f536ff94a4c4c0eb8d92106bad4de19404c60e8dc833",
"md5": "aee35934f680acf2b9be8e8c5692dce5",
"sha256": "616b0b132a7adf51a7ea2b26360991473dba1edb9c1e7aad22511962bc60626c"
},
"downloads": -1,
"filename": "manchero_method-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aee35934f680acf2b9be8e8c5692dce5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10253,
"upload_time": "2025-02-04T13:50:09",
"upload_time_iso_8601": "2025-02-04T13:50:09.332822Z",
"url": "https://files.pythonhosted.org/packages/8f/da/4a77b13ff3e3c016f536ff94a4c4c0eb8d92106bad4de19404c60e8dc833/manchero_method-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "88b81973b6738787954f81292848770568e6df3cea695de5d9107d0014dd103f",
"md5": "dc26ccb36c9855e5fd016734505d327d",
"sha256": "07f2ec000e0a36f7f1f3f02ea4d7c6357a12b3545b431c3b293342ad104f322a"
},
"downloads": -1,
"filename": "manchero_method-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "dc26ccb36c9855e5fd016734505d327d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16013,
"upload_time": "2025-02-04T13:50:12",
"upload_time_iso_8601": "2025-02-04T13:50:12.151767Z",
"url": "https://files.pythonhosted.org/packages/88/b8/1973b6738787954f81292848770568e6df3cea695de5d9107d0014dd103f/manchero_method-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-04 13:50:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "differentialcapital",
"github_project": "menchero-multiperiod-attributions",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "manchero-method"
}
