Portfolio Performance Documentation

The GitHub - portfolio-performance/portfolio-help: Help pages for Portfolio Performance (Deutsch) community project is moving along, and you can visit the English version at About this manual - Portfolio Performance Manual. Feel free to comment or contribute directly to the documentation or discussion.

This topic is an English discussion on the documentation for those that prefer not to use Erste Schritte mit Portfolio Performance im Handbuch dokumentieren (in German).


What should the introductory part of the documentation cover? A new user has likely visited Portfolio Performance and decided they are interested to know more. Some will install the software, perhaps browse the example files, and use the documentation to set it up. Others will browse the documentation to understand more about the software before deciding to try it. The documentation needs to work for any of these approaches.

Anyone looking for Portfolio Performance software almost certainly has an existing portfolio. Creating a portfolio is the first hurdle and they would undoubtably be more interested in importing the portfolio rather than each transaction, and certainly not rekeying each transaction manually.

Navexa, commercial portfolio tracking software, gets users up to speed quickly (btw it offers both a free plan and free trial). While PP does not offer conversion from competitors products, the csv import or create from transactions process is equivalent. I’d like to see PP documentation presented similarly with importing before rekeying so new users quickly realise their portfolio can be created quickly and efficiently.

How-To Link: Import CSV file


@hug-sch How-to - Portfolio Performance Manual has some good guidance for company transformations.

How about mergers and takeovers? I’m thinking one stock becomes another and there may be an adjustment amount.

The docs now contain info about spin-off, split, and insolvency. Does anyone know of a good (recent) example of a merger or take-over that could be used as an illustration in the how-to section of the docs?

@Sn1kk3r5 @Jo92 @Performer @flywire @stuartb3502 @Laura

Hi, I was glad to hear from @Laura that a team has been set up to tackle the German manual. :+1: . Would it be possible to use the team as a sounding board for any suggestions, questions and issues regarding the documentation? I don’t know if a mixed-language thread is possible; so, I started it in the English forum. Is that OK?

To kickstart, one of the many :slight_smile: things I’ve been struggling with lately was the following.

The performance indicators (IRR and TTWROR) can be calculated at the portfolio level (via Reports > Performance) or at the Security level (Reports > Performance > Securities). As far as I understand, in the calculation at the portfolio level, fees and taxes are included in the definition of the cash flow, while only fees are considered in the calculation at the security level. Is there a financial or economic reasoning behind this? In the English docs, I try to give some arguments, but they don’t seem really convincing to me. Any suggestions?


Hi @hug-sch,

Yes absolutely.

To be honest, I don’t know. Personally I have no problem with english, but I can’t speak for others. The only thing I usually experience, discussions and deepdive in foreign languages are mostly not as detailed as in mother tongue.

What makes it even a little harder from a gut feeling perspective is the fact PP sometimes uses a non financially terminology, which isn’t common practise in the english speaking community.

First of all my answer represents my opinion as I wasn’t part when it was developed.

Your observation is completely correct.

The portfolio view holds various different assets, with a given value. Depending on the bookings this is the only possibility were PP could create a “real” big picture. Everything together so to say.
While on security perspective a wide spread of tax laws can apply it’s easier to make use of the things which are similar all over the world. Purchasement price and fees in case they apply.
For example, stocks bought in Germany before 2009 are free of tax when selling with a profit.


1 Like


A purchase means that the amount of money is debited from an account and the securities portfolio in a securities account increases. Each purchase is booked with an offsetting entry in an account.

If the associated account is not to be held in Portfolio Performance, the offsetting entry is not required. In this case, it is advisable to make a delivery instead of a purchase. A delivery only increases the securities portfolio in the custody account without reducing the corresponding account.

A purchase can later be converted into a delivery by right-clicking on the purchase entry under Securities accountsTransactions and selecting → Convert to delivery. The offsetting entry in the account is then cancelled.

It is also possible to convert a delivery into a purchase by right-clicking on the delivery and selecting → Convert to purchase entry. The offsetting entry in the account is created automatically.

The same applies to sales and deliveries - conversion is possible in both directions.

You can also make these changes under All securities by selecting the desired security, clicking on → Transactions and then right-clicking on the booking to change the type between Purchase/Delivery or Sale/Outbound delivery.

Cheers, Laura

Hello @hug-sh, very great manual, thanks a lot !
Can we use this thread for comment ?
One remark on the market trend definition for Security chart :

  • Market trend: An additional horizontal axis is displayed.
    • Market trend: In addition to the standard horizontal axis that displays historical prices of the security, there is an extra horizontal axis intersecting the y-axis. This additional axis is positioned at the average market price for the selected reporting period. It provides a reference point, allowing you to compare individual prices on the graph to the average market price during the specified period.
    • Market trend vs. Purchase Value: The additional horizontal axis intersects at the level of the purchase price of this security.

Is this really the average ? It looks to me that the comparison is made vs the first quote of the reporting period.

Yes Sir.

It says: average market price during the specified period

So this means the period you set for the graph. In other words, your understanding is correct, the description is just using a different wording.


Yes, you are right. I’ve corrected it in the docs. Thanks for pointing that out. Don’t hesitate to inform us about other errors or suggestions to improve the text.

1 Like

and first quoted price is vice versa of different wording. In my case if the chart start at 1 and the average during the reporting period is 10, the second horizontal indicator remains at 1?! Or do I something wrong…

Thanks ! General question : is there a way to link to specific chapter / subchapter of the manual ? So far I only managed to link the full page, but sometimes a direct link to a subchapter is more efficient to point to a specific info. In the Readme in github which are also in markdown, it is possible to link to subchapter for example, accessible by simply clicking on the subsection title.

If you want to link to an item of the table of contents of a page, that’s possible with the anchor notation (adding #name-of-item to the URL) . For example, linking to Example 5 of figure below is done with


1 Like

@Sn1kk3r5 @Laura
I’m trying to create a conceptual model of the transactions in PP in terms of cashflows (or transfers in PP terminology), something like the following (not finished yet):

But I don’t understand a few things. So, I created a portfolio xml-file with all possible transactions in a very small time period and with limited quote history.

Then, I exported the Performance chart as CSV for the different levels: portfolio, security, security account (before & after taxes), cash account. A summary is in the following Excel screenshot (the yellow colored cells are the in- and outbound transfers).


  1. On portfolio level, the only cashflows that occur are with the deposit, removal, IN/OUT delivery. So, for example the IRR calculation is (see [Equation 1]( Money weighted rate of return - Portfolio Performance Manual (portfolio-performance.info)):

MVE = 514 = =0 + 600*(1+irr)^(12/365) - 100*(1+irr)^(11/365)+202*(1+irr)^(8/365) - 199*(1+irr)^(7/365) for IRR = + 87.44%, which corresponds with the performance calculation in PP.

The other “cash flows” such as dividend occur on security level and are taken into account in the endvalue, which comprises the cash accounts. Is this a correct reasoning? If so, then in the figure above, the deposit arrow starts outside the portfolio and in the cash account (?)

  1. The CF at security level are buy/sell (arrows between cash and sesurity), in/out delivery (arrows as above), and dividend (arrow between security and cash account. Correct? Why are fees included in the amount, while taxes are not? Why is fee considered as a IN transfer?

  2. Security account: why is for example a buy transaction an IN transfer for security account (after taxes) and a OUT for security account (before taxes).

  3. Interests increase the cash account but they are not considered as a IN Transfer for a cash account. However, they are added to the balance (see arrow in the first image).

If you have any clarifying ideas or suggestions, please let me know.



Hi @hug-sch,

let me get some more brains into this. Just to get this waterproofed.

@chirlu, @ProgFriese, @Jo92, @Nirus,

Yes correct.

For a deposit, the figure is right. In terms of dividends, you need to distinguish between Ex date (Capital Gain Loss while Cash Account doesn’t have the dividend yet) and Payment date (Money received on the Cash account)


To the best of my knowledge both are included. The IN or OUT topic depends on your view. At least this is my understanding on the mechanics about accounting with PP.

When I’m not misstaken this is a historical thing which led to some confusion.
We always must consider the age of PP while @AndreasB intention by the time was not to grow PP this big.

To my understanding, they are considered. The same applies for interest charge.
Report → Performance → Payments

In terms of reporting via widget, the corresponding cash account must be added as well. Maybe that’s where your confusion is coming from.


1 Like

Hey @hug-sch,

what a great idea, I really appreciate all your good prepared input! I am just on my mobile actually and only had a quick look. Will have a deeper one the day after tomorrow on the public holiday.

  1. The arrow for the delivery outbound is in the wrong direction.

  2. Are fees and taxes not following the PP logic correct on the left side (cash account). They just have a connection to a security, but in the value evaluation they are represented on the cash account.

Edit: I actually also saw that my second point connects to your second point. From my point of view the reason is, because taxes and fees are in case of performance measurement connected to the security. But the first principle of PP is the bookkeeping principle and therefore these are represented on the cash account, because they have the effect there.

Could you explain that one again in other words? I think it will be a in transfer, because it is coming from the cash account (if you just filter on the security account). Did you may had any filters activated during your check?

Why are you wondering about that? In my opinion it is the case because the interests are earned “internally” by the cash account itself. If they would come from the outside, then that would be performance neutral actions and that would be wrong.

  • Interest Earned is input
  • Interest Charged is output

The two are not joined.

My view is while cost basis does not affect the portfolio performance it is a real part of ETFs affecting the security and can be modelled with the above hack (effectively redeeming the security and reaquiring it with a cash deposit/removal to adjusted cost base).

Thanks, I can see it now. Thus, for a cash account, Interest (Earned) is as capital gain for a security account and Interest (Charged) is like capital loss. But, it’s still not very clear to me how to draw it.

The fee itself is internal. However, for the fee to be paid, money must flow in from the outside.

I’m not sure I understand the question. A buy transaction always means money is flowing in. Any taxes are taxes, which is a special type of outflow in the normal case and a regular outflow when taxes are filtered.