How quantopian/pyfolio works
Project type and purpose
• pyfolio is a Python library for performance & risk analysis of financial portfolios.
• It consumes time-series data (returns, positions, transactions), processes it, and produces tear-sheet plots.
• Integrates tightly with Zipline (backtester), Jupyter notebooks, and common data science libs (Pandas, NumPy, Matplotlib, Seaborn).
Main components
a. Data ingestion & input
– Raw data sources: equity returns, transaction histories, position snapshots, factor returns (CSV, DataFrame).
– Users import data via Pandas or Zipline APIs.
b. Core analysis modules (pyfolio package)
– timeseries.py: series-level calculations (returns, drawdowns).
– perf_attrib.py & capacity.py: performance attribution, capacity modeling.
– pos.py & txn.py: position and transaction parsing.
– round_trips.py: trade round-trip analysis.
– interesting_periods.py: select significant time windows.
– tears.py: assemble metrics & generate tear-sheet sections.
– plotting.py & _seaborn.py: visualization logic, Matplotlib/Seaborn wrappers.
– utils.py: shared utilities (date handling, configuration).
c. Presentation layer
– Generating figures (Matplotlib Figure objects) and embedding in Jupyter notebook cells.
– PNG/HTML export for reports (via notebooks or direct save).
d. Packaging & tooling
– setup.py / conda/meta.yaml: distribution configuration.
– versioneer.py: version management.
– docs/ & mkdocs.yml: static site generation for docs.
– Travis CI (.travis.yml): continuous integration.
– build_and_deploy_docs.sh, conda/build scripts: automated builds & deployment.
e. Testing
– pyfolio/tests/: unit tests against test_data CSVs.
– Notebook tests: docs/notebooks conversion & execution (mkdocs integration).
Relationships & data flow
– Analysis modules depend on Pandas/NumPy libraries (annotate that dependency).
– Core modules feed their outputs (metrics, DataFrames) into plotting.py.
– Presentation node outputs to Jupyter notebook interface or saved report.
– Packaging & tooling run separately: build scripts pick up source tree → produce PyPI/conda artifacts and docs site.
– Tests run against core modules and notebooks in CI pipeline.
Architectural patterns & design principles
• Modular separation by concern: data ingestion, core analytics, visualization, packaging, testing.
• Extensibility: adding new tear-sheet sections by extending tears.py; adding new plots via _seaborn helper.
• Layered design:
– Bottom layer: data structures & time-series logic.
– Middle layer: analytics & metrics.
– Top layer: visualization & reporting.
• Dependency injection: users supply DataFrames; modules remain agnostic to data source.
[Data Layer]
• CSV / Database / Zipline API → time-series ingestion
[Analytics Layer]
• timeseries.py → raw calculations
• perf_attrib.py → attribution metrics
• capacity.py → capacity modeling
• pos.py / txn.py → position & trade parsing
• round_trips.py → trade cycle analysis
• interesting_periods.py → period selection
[Tear-Sheet Assembly]
• tears.py → orchestrates analytics & plotting calls
[Visualization Layer]
• plotting.py / _seaborn.py → produces Matplotlib Figures
[Presentation]
• Jupyter Notebook / CLI save functions → final output
[Tooling & Packaging]
• setup.py, conda/, versioneer.py → build & distribution
• docs/, mkdocs.yml → documentation website
• .travis.yml, build_and_deploy_docs.sh → CI/CD pipelines
• pyfolio/tests/ → automated testing