The Scorecard

Why a portfolio can go down in a year when most of the shares in it went up.

Every holding here is priced in a currency that isn’t mine. Adidas trades in euros, Richemont in Swiss francs, PVH in dollars. I think in pounds. So when I ask “what did Adidas do for me this year”, two completely separate things have moved: the share price, in euros, and the euro itself, against the pound. Either one can be up while the other is down.

That’s the whole reason this project exists. A client sees one number and asks why it’s negative when the news says their companies did well. The answer is usually that the number is two answers added together, and nobody separated them.

Getting a pound rate out of a dollar rate

The FX data comes back based on the dollar — how many euros a dollar buys, how many pounds, how many francs. What I need is euros to pounds. That’s just division:

EUR_to_GBP = FX_GBP / FX_EUR

If a dollar buys 0.857 euros and 0.733 pounds, then a euro buys 0.733 / 0.857 = 0.855 pounds. The thing worth noticing is that both numbers come from the same daily snapshot, so they can’t disagree with each other. Pulling the euro rate from one source and the pound rate from another would leave a gap that isn’t a real market movement, just two providers rounding differently.

Three components, not two

The obvious split is “asset” and “currency”. But they multiply rather than add — a share that gains 10 % in a currency that gains 10 % doesn’t give you 20 %, it gives you 21 %. That extra 1 % is real money and it belongs to neither leg on its own:

(1 + total) = (1 + local) × (1 + fx)

total = local + fx + cross_term

I report that leftover as its own cross-term rather than quietly folding it into the currency figure. Folding it in is easier to explain and slightly dishonest: it makes the currency look like it did more than it did. This year the cross-term stayed under 0.35 % for every holding, because neither leg was large. In a year where a currency moves 20 % it stops being a rounding detail.

The crash on the first run

Checking it three ways, because one of them proves nothing

The function checks its own work: it asserts that total equals local + fx + cross_term. That assertion can never fail. It’s an algebraic identity — rearrange the definitions and it’s the same statement on both sides. It confirms the arithmetic and is completely blind to a wrong input.

So I checked it two more ways that can fail:

• Recomputed all three components independently, straight from the raw price and FX columns, without touching the function. Every holding matched.
• Ran it in other base currencies. With USD as the base, PVH — a dollar-listed holding — came back with fx_return = 0.0 and total == local, which is exactly right: hold something in your own currency and you have no currency exposure to it. With EUR, the three euro holdings collapsed to zero the same way and the Swiss and American ones stayed live. That proves the function isn’t quietly hard-wired to pounds.

The results, once it ran: currency movement was small and remarkably uniform — sterling weakened about 0.99 % against the euro, 0.68 % against the franc and 1.76 % against the dollar. The interesting spread was entirely in the shares themselves: Puma +33.7 %, Mercedes-Benz −13.1 %, a 47-point gap between two holdings in the same country and the same currency.

Five separate answers are not a portfolio. Combining them takes a decision I had no information for.

Section 01 gives a return per holding. To get one number for the whole portfolio I need to know how much of each is held — and I don’t. I have no idea how George Russell’s money is actually allocated, and inventing plausible-looking weights would be claiming knowledge I don’t have.

So: equal weights, 20 % each. It’s simple, it’s transparent, and it’s honest about what is and isn’t known. If someone asks why, the answer is a good one rather than an awkward one.

The portfolio is £20,000,000, and that figure is illustrative — not a claim about anyone’s real finances. I picked a large round number deliberately so the resulting profit and loss is something you can say out loud. “Down 1 % on currency” is easy to wave away. “Currency cost this book £199,847” is not.

What the weights function will and won’t accept

normalise_weights() takes weights as percentages, as unit counts, or as market values, and turns any of them into fractions that sum to one. It refuses an unknown ticker, a missing holding, a negative weight, a NaN, or a set that sums to zero. Refusing loudly matters more than it sounds: every one of those would otherwise produce a believable-looking number that is quietly wrong.

One simplification, stated rather than hidden: the weights are fixed for the whole period. Real weights drift as prices move — a holding that gains 40 % becomes a bigger share of the portfolio without anyone buying more of it. Capturing that needs the day-by-day series rather than one figure for the year, which is on the list for version 2.

The one part of this project where I deliberately kept the model out, and wrote down why in the file itself.

A hedging flag says: this holding’s currency exposure has moved past what this client signed up for, and somebody should look at it. It’s a small piece of code and a slightly serious one, because it’s the bit a person might actually act on.

The rule is a threshold. This client’s risk band is “growth”, and the currency limit is −1.5 %. Any holding whose currency leg falls below that gets flagged, with a message naming the holding, the figure, how far past the line it went, and three things that could be done about it.

Three decisions, each with a reason

• Thresholds are decimals, not percentages. You pass -0.015, not -1.5. Passing -1.5 raises an error saying it would mean −150 %. Percent-versus-decimal is the easiest possible mistake to make here and the hardest to notice, because both look reasonable. A positive threshold raises too — this is a downside limit by definition.
• A breach is strictly below the line. A holding sitting exactly on its limit is not flagged. That’s a real decision, not an accident of writing < instead of <=, and there is a test that sits a holding precisely on the boundary to prove it.
• It looks only at the currency leg, and ignores whether the holding made money. Richemont was up 39 % and would still be flagged if its currency leg breached. Whether to hedge a currency and whether you like the investment are two different questions, and mixing them is how you end up not hedging something because it happens to be doing well.

Against the real figures, nothing breaches at −1.5 %. That is the honest result and I kept it. Move the line to −1.0 % and four of the five light up — which is in the test output deliberately, as proof the logic fires, without having to invent a currency crisis to demonstrate it.

Two test layers that fail for two different reasons, and the reason neither one checks a market number.

Everything so far ends in one file. build_summary() runs the whole chain — returns, then portfolio, then the hedging check — and assembles a single dictionary: who the client is, the risk band, the base currency, the date range, every holding with all its components and its profit and loss, the portfolio totals, the hedging results, and a generated_at timestamp. It goes to output/portfolio_summary.json.

That file is committed to git, unlike the cached data underneath it. Issue 07 covers why those two folders are treated differently (what belongs in a cache filename); the short version is that data/ can be rebuilt by asking the API again, and this can’t — it’s the finished thing a dashboard reads.

Layer one: made-up numbers, exact answers

The first layer uses a small table I wrote by hand: four holdings, one breaching badly, one breaching by a hair, one sitting exactly on the limit, and one comfortably safe. Because I chose the inputs, I know the exact output, so the test compares the generated message character for character.

That sounds excessive until you notice what it buys: reword the message and a test goes red. Nobody can casually reword a compliance-facing sentence without being told they just did. Which is exactly what happened later — see section 06.

Layer two: real numbers, no expected answers

The second layer runs the real pipeline on cached data, and asserts nothing about the values. It checks the shape: one flag per breaching holding, all six fields present in each, the per-holding booleans agreeing with the flags list, the closest-to-the-line calculation correct in both directions, and a full round-trip through JSON to prove no NumPy types leak into the output.

Proving the test can fail

A test that has only ever passed hasn’t been shown to work. So I broke the message on purpose and watched the character-for-character check go red, then put it back. Thirty-four checks across the two layers, and I know at least one of them has teeth because I saw it bite.

Roughly one man in twelve can’t reliably separate red from green, so a chart that says it in colour alone says it to eleven of them.

The dashboard is a single static HTML file. It fetches the JSON from section 04 and draws a header, three summary cards, the holdings table, a bar chart and the hedging status. No backend — the numbers were already calculated, so there is nothing left to compute at the moment somebody looks.

Why the bars are blue and red rather than green and red

The chart’s job is “above or below zero”, so the sign is what colour should carry. The instinct is green for up and red for down. I used blue and red instead, and the panel below is why.

What actually happens is more interesting than “green and red look the same”, which is the version everyone repeats. Under deuteranopia both red and green collapse towards the same yellow-olive axis. They don’t become identical — but the only thing left separating them is lightness, which is a property nobody chose on purpose. With the green and red most spreadsheets reach for by default, that lightness gap shrinks from 24.9 to 8.7 and the overall colour difference drops by nearly half. Whether your chart survives becomes luck.

Blue and red keep a genuine difference in hue: the blue goes violet, the red goes olive. Measured, the two are further apart under deuteranopia than they are with typical vision. That’s why blue and red is the standard recommendation for a chart built around a baseline, and it isn’t a matter of taste.

Two smaller decisions in the same spirit. There is no legend, because there is only one measure and it’s named in the heading — a legend for a single series is furniture. And dark mode is its own palette, checked separately, not the light one inverted; inverting a palette moves every colour somewhere its contrast was never measured.

Checking a web page from a machine with no browser

The server this was built on has no screen. So the page was verified in pieces: serve it over HTTP and confirm the page, the JSON and the chart library all return 200; then run the page’s own render function directly in Node against the real JSON — 24 checks — and 8 more against a deliberately doctored file where a holding does breach, confirming the flag blocks appear only when they should.

What that cannot check is what it looks like: spacing, wrapping, labels colliding. I wrote that limitation down rather than implying the page was verified, and then looked at it properly in a real browser over an SSH tunnel, where it rendered correctly and matched every number in the pipeline.

Two things I had written down about my own server were wrong, and I only found out by trying to use them.

The dashboard worked on the machine it was built on. Getting it somewhere other people could see it had an obvious-looking answer — open the port — and a better one. Opening a port would mean asking for a change to the router so the whole internet could reach a plain development server with no authentication on it. There was already a perfectly good website running on this box with a certificate and a proper front door, so the dashboard went there instead. No new exposure, no infrastructure change, no conversation needed.

Two corrections

• The service serving my site is not the one I thought. My notes said hello-web.service. That unit is dead and disabled — it was replaced months ago. The real one is guestbook.service, a Python app that answers its own API routes first and then serves the site files for everything else. I had the folder right and the service name wrong, which is the kind of error that survives indefinitely until you try to restart something.
• There is no build step, and I went looking for one. The site is served straight off the disk, so copying the file in is the deployment — live the moment the copy finishes. There is a build.py on that server and it was tempting, but it belongs to a completely unrelated project (a travel itinerary generator). Running it would have done nothing for the dashboard and republished somebody’s holiday cards. Issue 03 covers how the serving actually works: how this gets to be on the internet.

Two small things came out of doing it. The bare folder address didn’t work at first, because a directory only resolves if it contains an index.html. And copying files by hand is how a published site quietly drifts away from the code that produced it, so it became a script:

$ cp dashboard.html index.html "$SITE/portfolio/"
$ cp output/portfolio_summary.json "$SITE/portfolio/output/"

The relative path is preserved on purpose, so the page’s fetch("output/portfolio_summary.json") resolves in exactly the same way in both places and no code has to change between the repository and the live site.

I want to be straight about that one, because it is easy to write up as a neat anecdote. It was a real error in shipped, public-facing text, and the thing that caught it was not a clever test or a review. It was writing an explanation carefully enough that the sentence had to make sense.