brownbear

A portfolio analysis tool for screening stocks, building diversified allocations, and measuring risk-adjusted performance.

Brownbear helps you work through a full portfolio workflow in Jupyter: define an investment universe (S&P 500, Dow 30, ETFs, asset classes, and more), compare weighting schemes, visualize allocations and correlations, optionally optimize weights, and size positions using live quotes.

Start with portfolios/sp500/portfolio.ipynb.

What brownbear is good at

• Multi-level portfolios — allocate by asset class, asset subclass, and individual securities
• Correlation-aware analysis — correlations between asset classes and between holdings inform diversification
• Flexible weighting — equal weight, returns, Sharpe ratio, volatility (inverse), or manual percentages
• Pre-built universes — Dow 30, S&P 400/500/600, Nasdaq 100, ETFs, state pension examples, and asset-class galaxies under universe/
• Cached market data — daily prices from Yahoo Finance stored in symbol-cache/
• Portfolio optimizer — optional constrained optimization from a notebook
• Trade sizing — translate target weights into share counts using current quotes

Brownbear complements pinkfish: pinkfish is built for backtesting rule-based strategies on a fixed basket of symbols; brownbear is built for screening, constructing, and analyzing portfolios across a broader investment universe.

Project layout

Path	Purpose
brownbear/	Python package (fetch, analyze, optimize, metrics, symbol cache)
universe/	Investment galaxies — see universe/README.md
portfolios/	Portfolio example notebooks — see portfolios/README.md
strategies/	Per-account rebalance notebooks — see strategies/README.md
symbol-cache/	Cached Yahoo timeseries (working data; see tools/symbol-cache/)
tools/symbol-cache/	Cache maintenance — see tools/symbol-cache/README.md
images/	Project artwork

Installation

Brownbear works on Linux, macOS, and Windows. I recommend a virtual environment.

git clone https://github.com/fja05680/brownbear.git
cd brownbear
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install setuptools
pip install -e .

Dependencies are listed in requirements.txt.

Jupyter

Most workflows are notebooks. After installing brownbear and activating your virtual environment:

cd brownbear
source venv/bin/activate   # Windows: venv\Scripts\activate
jupyter nbclassic

Open portfolios/, choose a portfolio type, and run portfolio.ipynb from top to bottom.

To open a specific example directly:

jupyter nbclassic portfolios/sp500/portfolio.ipynb

If you prefer jupyter notebook or JupyterLab, install the extra packages first: pip install notebook or pip install jupyterlab.

Quick start — portfolio notebook

1. Open a notebook under portfolios/ — for example portfolios/sp500/portfolio.ipynb.
2. Set investment_universe to the galaxy you want (for example ['sp500-galaxy']).
3. Set risk_free_rate if you use Sharpe-based weighting.
4. Choose or define portfolio_option — a dict of symbols and target weights.
5. Run all cells to fetch metrics, analyze the portfolio, and view pie charts.
6. Optionally set run_portfolio_optimizer = True to run the optimizer.

Each portfolio folder may also include investment-options.ipynb for refreshing that universe's data. See universe/README.md and portfolios/README.md.

Updating market data

Maintainers can refresh the full dataset with tools/update-universe.sh:

./tools/update-universe.sh --full      # first run: clean caches, run all steps
./tools/update-universe.sh             # resume after an error

See UPDATE for step details.

Documentation

API reference (generated with pdoc3) lives in docs/html/brownbear/.

Regenerate after API changes:

cd docs
./generate-docs.sh

View locally:

xdg-open docs/html/brownbear/index.html    # Linux
# open docs/html/brownbear/index.html      # macOS
# start docs/html/brownbear/index.html     # Windows

Source modules with docstrings are in brownbear/.