Brinson: Polars-Powered Performance Attribution Library with Multi-Period Linking & Behavioral Alpha Frontier
An open-source Python library built on Polars implements Brinson performance attribution with single- and multi-period models, multiple linking algorithms, multi-account decision attribution, currency and factor extensions, and a novel Behavioral Alpha Frontier visualization, all with minimal dependencies and comprehensive documentation.
The Brinson package is an MIT-licensed open-source Python library for portfolio performance attribution. Its core computational engine relies exclusively on Polars expressions, with Matplotlib as an optional dependency for plotting. The project provides full Sphinx documentation covering formulas, input constraints, API references, and validation methods.
Core Attribution Features
Single-period Brinson : Implements both BHB (Brinson-Hood-Beebower) and Brinson–Fachler decompositions, breaking excess return into allocation, selection, and interaction effects.
Multi-period linking : Supports five linking algorithms — Cariño, GRAP, Frongello, Menchero, and Geometric — to chain single-period effects across time while preserving arithmetic consistency.
Multi-account decision attribution : Offers Macro→Micro decomposition, value-weighted total portfolio aggregation, and hierarchical decision attribution across accounts.
Currency attribution : Implements the Karnosky–Singer simplified currency split and currency premium analysis.
Factor attribution : Provides Hentschel constrained factor models with interaction adjustments.
Behavioral Alpha Frontier (BAF) : An independently defined method set comprising seven decision categories, a curved zero-value-added boundary, indifference bands plotted by normalized value-added, and a period-over-period change table using the same valid-account cohort. BAF results are not official Essentia scores and the decision values do not sum to Brinson active return.
Tutorials and Visualizations
Executed Jupyter tutorials (available in both Chinese and English) demonstrate each feature:
BAF frontier with indifference bands and account change table (synthetic data).
Single-period excess-return waterfall and multi-period algorithm comparison charts.
Dow Jones 30 sector returns, weights, attribution results, and interactive decision trees from account to sector to security (local Yahoo Finance research snapshot).
Multi-account attribution method comparison.
All tutorial images are rendered from executed notebooks. The BAF and multi-account examples use fictional data; the Dow 30 example uses a local price/sectors workbook.
Installation and Conventions
Requires Python 3.11+.
Weights, returns, and attribution effects use decimal convention: 0.01 represents 1% (100 basis points).
Plotting and tutorial dependencies are optional and can be installed as needed.
API Design
Input column names do not require pre-renaming. Each calculation function accepts mapping parameters such as column_period, column_segment, column_portfolio_weight, etc., and preserves the mapping in the result's column-configuration object.
Two explicit entry points separate single- and multi-period workflows:
calculate_single_periodcalculate_multiple_periodEach Brinson variant and linking algorithm also has its own dedicated function. Full constraints are documented in the Data Contract and API reference.
Method and Data Reference
BHB / Brinson–Fachler : bhb, fachler Cariño / GRAP / Frongello / Menchero / Geometric : Multi-period linking formulas
Multi-account Macro→Micro, value-weighted total portfolio, hierarchical decision attribution : Multi-account documentation
Karnosky–Singer simplified currency split and currency premium : Currency attribution
Hentschel constrained factors and interaction adjustment : Hentschel method
BAF seven decision categories, frontier plot, account change table : BAF formulas
Example Data and Generation Scripts
Sample CSVs located in data/dow30_brinson/, data/multi_account/, and data/baf/.
Regenerate synthetic data with python scripts/generate_multi_account_data.py and python scripts/generate_baf_data.py.
Local price/sector workbook: data/dow30/Dow30_prices_sectors.xlsx.
Attribution workbooks and charts saved to outputs/dow30_brinson/.
License
The project is released under the MIT License (see LICENSE in the repository).
Repository:
https://github.com/bibiparrot/brinsonsSigned-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
