Portfolio-Lab is a web-based portfolio analytics application built with Streamlit.
It is designed to help investors reconstruct, evaluate, and understand their portfolios through a professional-grade performance and risk analytics pipeline.
This version of the platform focuses on Jamaica Stock Exchange (JSE) listed equities.
Users manually input transactions, and the system rebuilds holdings, valuations, performance, attribution, and risk metrics from first principles.
At this stage, Portfolio-Lab does not persist user data and is intended as an analytics laboratory rather than a brokerage or trading platform.
Portfolio-Lab was built to explore how institutional-grade portfolio analytics can be made transparent, interpretable, and accessible.
Rather than emphasizing trading, the app is centered on:
- understanding portfolio construction
- measuring performance correctly
- identifying sources of return (alpha)
- evaluating portfolio risk and diversification
- diagnosing exposure to market, currency, and structural factors
- building financial intuition through structure
This project treats portfolios not as tickers, but as evolving financial systems.
- Transaction-based holdings reconstruction
- Corporate-action aware quantity roll-forward
- Cost basis tracking
- Multi-currency normalization into JMD
- Historical valuation snapshots
- Simple returns
- Time-Weighted Rate of Return (TWRR)
- Money-Weighted Rate of Return (MWRR / IRR)
- CFA-aligned TWRR logic (non-annualized sub-year periods)
- Portfolio valuation history builder
- Asset-level attribution
- Sector-level attribution
- Brinson-Hood-Beebower (BHB) model
- Brinson-Fachler (BF) model
- Allocation, selection, and interaction effects
Designed to evaluate where returns came from — not only how much.
- Volatility analysis
- Correlation heatmap
- Diversification ratio
- Sharpe ratio
- Value-at-Risk (95% and 99%)
- Marginal, incremental, and component VaR
- Asset and sector risk attribution
Built to explore how portfolio structure influences risk.
- Excess return regression against market indices
- FX sensitivity analysis (USD/JMD)
- Index-relative beta estimation
- Portfolio alpha diagnostics
- Statistical significance testing (t-stats, p-values)
- Model integrity checks (R², Durbin–Watson, condition number)
- Residual analysis and attribution reconciliation
This module is designed to explore why a portfolio behaves the way it does relative to the market, not to optimize or predict returns.
Portfolio-Lab is structured as a set of independent but connected financial engines:
- valuation_engine.py → portfolio valuation logic
- holdings_engine.py → transaction → holdings reconstruction
- returns_engine.py → TWRR / MWRR / performance metrics
- sector_engine.py → sector aggregation & attribution
- attribution_engine.py → BF / BHB performance attribution
- risk_engine.py → risk & VaR analytics
- exposure_engine.py → market, FX, and factor exposure modeling
- ui_components.py → shared UI primitives, tables, charts, and diagnostics
The Streamlit app orchestrates these engines into interactive workflows:
- 1_Transactions.py
- 2_Holdings.py
- 3_Performance_Attribution.py
- 4_Risk_Attribution.py
- 5_Market_Exposure.py
This modular structure allows each financial problem domain to remain isolated, testable, and extensible.
Portfolio-Lab differs from typical “portfolio trackers” in that it is built as a multi-engine financial infrastructure rather than a dashboard wrapper.
It reconstructs portfolios from raw transactions and evaluates them across:
- valuation
- performance
- attribution
- risk
- and market exposure
using academically grounded and industry-standard models.
The emphasis is not on visualizing prices, but on explaining portfolio behavior.
This project addresses several technically and conceptually complex domains:
- transaction-driven portfolio reconstruction
- cash-flow-neutral performance measurement
- benchmark-relative attribution modeling
- historical valuation pipelines
- decomposed portfolio risk
- and market exposure
Each engine required aligning financial theory, accounting identities, and software design into a consistent system.
Portfolio-Lab represents an applied attempt to translate institutional portfolio analytics into an interpretable, user-facing platform.
portfolio-analytics-dashboard/
│
├── app.py
├── pages/
│ ├── 1_Transactions.py
│ ├── 2_Holdings.py
│ ├── 3_Performance_Attribution.py
│ ├── 4_Risk_Attribution.py
│ └── 5_Market_Exposure.py
│
├── attribution_engine.py
├── holdings_engine.py
├── returns_engine.py
├── risk_engine.py
├── sector_engine.py
├── valuation_engine.py
├── exposure_engine.py
├── simulation_engine.py
├── ui_components.py
├── docs/
│ ├── app_screenshots/
│ ├── documentation.md
│ ├── howtouse.md
│ ├── howtoreadmarketexposure.md
│ ├── glossaryofterms.md
│ └── security.md
└──This application is deployed via Streamlit Cloud and is not distributed as open-source software.
Authorized users can access the live dashboard here:
No local installation is required.
The mathematical framework underlying this system is documented in the /docs directory.
Source code is private, but the computational methodology is fully documented for academic transparency.
-
No user authentication
-
No persistent database
-
Manual transaction input only
-
JSE equity focus
-
Not intended for live trading or investment advice
-
Brinson Attribution Sensitivity: The Brinson-Fachler (BF) and Brinson-Hood-Beebower (BHB) models in this lab assume fixed beginning-of-period weights.
Note: Large intra-period capital flows (buys/sells) can distort attribution results. If significant trading occurs mid-period, the attribution effects may not fully reconcile with the Portfolio's total return. -
Portfolio-Lab is currently an analytics sandbox and research platform.
- Portfolio simulation engine
- Optimization framework
- Automated data ingestion
- User profiles and storage
- Scenario and stress-testing modules
- Development Philosophy
This project is not positioned as a finished financial product.
Reference data is stored in an AES-256 encrypted volume and decrypted in-memory during session initialization to ensure data integrity. We take data privacy seriously. Portfolio-Lab does not persist user data. * All uploaded transactions are processed in-memory and destroyed when the session ends.
- Technical details on our encryption and data handling can be found in our Security & Privacy Documentation.
It is an evolving collaboration between human design, financial theory, and artificial intelligence — built to explore how portfolio intelligence tools can be constructed, validated, and eventually democratized.
Portfolio-Lab is an experiment in learning, architecture, and applied finance.
- 🙋♂️ Have a question? Join our GitHub Discussions
- 💡 Have an idea? Submit a Feature Request
- 🗺️ See what's coming next: View our Project Roadmap
- 🛠️ Track our progress: See what bugs we're squashing in the Issues Management Board