A merger occurs when two separate companies combine forces to create a new organization. An acquisition refers to the takeover of one company by another. According to Investopedia, both terms have become increasingly blended.
-Exxon Corp. and Mobil Corp. completed their merger in November 1999. Exxon shareholders owned 70 per cent of the new company. Mobil shareholders are left with 30 per cent of the merged group.
-This corporate action could be recorded in PP as an outbound/inbound delivery. Suppose that you owned 10 Exxon and 50 Mobile shares. This will result in (10 x 0.7) + (50 x 0.3) = 7 + 15 or 22 shares of ExxonMobil Corp.
+A merger occurs when two separate companies join forces to form a new organisation, whereas an acquisition involves one company taking over another. As explained by Investopedia, the distinction between these two terms has become increasingly blurred.
+On Saturday, 16 January 2021, the merger between Peugeot S.A. (PSA) and Fiat Chrysler Automobiles N.V. (FCA) was finalised, leading to the creation of Stellantis N.V. (STLA). Figure 1 shows historical price data for the companies involved, downloaded from XETRA via PortfolioReport, with the respective ISIN numbers: FCA (NL0010877643), PSA (FR0000121501), and Stellantis (NL00150001Q9).
+
The compensation for the old shareholders in the Stellantis merger was:
According to Reuters, the Italian financial group Unipol announced on February 16, 2024 an offer to acquire the remaining 14.75% stake in UnipolSAI. Unipol Gruppo is offering 2.7 euros per share to buy out UnipolSAI shareholders, or alternatively, UnipolSAI shareholders can exchange 10 shares of UnipolSAI for 3 shares of Unipol Gruppo.
-From the respective websites (Unipol Gruppo and UnipolSAI) we know that the closing price on February 15 was € 5.74 for Unipol Gruppo and € 2.4/share for UnipolSAI. were:
+As shown in Figure 1, the closing prices of the companies on the day before the Stellantis merger were: FCA at €12.68 and PSA at €22.07. Based on the compensation ratio, the PSA price was expected to be 1.742 × FCA Price, or €12.68 × 1.742 = €22.09, which nearly matches PSA’s closing price of €22.07. Stellantis had a positive debut on European stock markets following the merger, with shares rising by 8% on the first trading day, from €12.68 to around €13.60.
+Recording this merger in Portfolio Performance is straightforward, as it involves creating a new security. To update your portfolio:
+The Portfolio Performance (PP) manual consists of four chapters which are derived from a popular documentation authoring framework. The documentation is structured along two axes: practical versus theoretical knowledge and learning versus doing.
PP is an Eclipse-based desktop application written in Java. This open-source project started in 2012 and has been updated numerous times. With PP, you can:
Why choose yet another application? While you can simulate some of these calculations with Excel or rely on your broker for information, they often provide incorrect results. They are typically based solely on absolute figures at the beginning and end of a reporting period and do not properly include purchases and sales or variable reporting periods. PP calculates performance accurately using True-Time Weighted Rate of Return and Internal Rate of Return, taking into account the purchases and sales at their respective execution date.
"},{"location":"about/#other-information-sources","title":"Other Information Sources","text":"The source code is hosted on GitHub. Examining this code will give you direct access to the inner workings of the program.
There is also an active discussion forum available in both English and German, with an extensive Frequently Asked Questions (FAQ) section.
"},{"location":"about/#license","title":"License","text":"This manual is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The source code of Portfolio Performance is licensed under the Eclipse Public License 1.0.
Thanks to all contributors!
"},{"location":"about/#imprint","title":"Imprint","text":"For more information, please see the Imprint and Privacy Policy.
"},{"location":"concepts/","title":"Basic concepts","text":"In this chapter, you will find a concise but clear explanation of several basic concepts. Portfolio performance is all about numbers. It is easy to completely miscalculate or misinterpret these numbers, if you don't understand the underlying assumptions.
Fundamental concepts such as account, transaction, reporting period, purchase value, and performance are described in a separate chapter (see sidebar). Below is an alphabetical list containing descriptions of all attributes, also referred to as fields or columns, used in various sections within PP.
Absolute performance: a performance measure that assesses the overall gain or loss of an investment over a specific period; = (Market value at end of period + Sell/outbound deliveries + Dividends) - (Taxes + Fees + Initial valuation + Buy/inbound deliveries). Synonym: total return.
Account: Repository or container for storing financial information, such as cash transactions.
Actual # quotes: the number of quotes in the historic prices list of a security.
Amount: The Gross Amount of a transaction or the total amount of money before any taxes and fees.
Buy: transaction resulting in the acquisition of securities, where cash is withdrawn from a deposit account to purchase the desired stock.
Change in Price (period): the difference in historic quotes between the last and first quote of a specified time span, expressed as a percentage. The period may be denoted in years (e.g., 1 year, 2 years, 3 years) or as a date range (From yyyy-mm-dd to yyyy-mm-dd). If the duration is in years, the last date is today, and the first date is today minus x years.
Change on Previous Day (amount) or \u0394 amount: the absolute difference between the latest retrieved quote and the previous one (which is most likely the quote from the previous day).
Change on Previous Day (%) or \u0394 %: the difference between the latest retrieved quote and the previous one (which is most likely the quote from the previous day), expressed as a percentage.
Cash account: A financial account for holding and managing money.
Completeness of historic quotes: the ratio between the actual and expected number of historic quotes of a security, expressed as a percentage.
Currency: the currency for a security chosen at its creation, which becomes immutable after the initial transaction involving this security.
Date: The date of a transaction such as Buy or Sell.
Date of first historical quote: The first date for which you have historical prices of a security.
Date of last historical quote: The last date for which you have historical prices of the security. It's important to note that having these dates does not necessarily mean you have all intermediate historical prices.
Date of latest quote: the most recent date on which the current market value or price of a financial instrument, such as a stock, bond, or commodity, was publicly provided or updated.
Delivery (Inbound): a transaction where shares of a security are acquired without the need for a prior deposit and withdrawal of funds (comparable to a buy without a withdrawal).
Delivery (Outbound): a transaction where shares of a security are removed from the security account without a resulting deposit in a cash account (comparable to a sell without a deposit).
Deposit: Putting money in a deposit or cash account.
Deposit account: Repository or container for storing deposit/withdrawals and balances. Also named Cash account.
Distance to SMA (days): a metric that measures the difference between the current price (quote) of a share and the average price of that share over a specified number of past days (5, 20, 30, 38, 50, 90, 100, or 200 days), expressed as a percentage. The acronym \"SMA\" stands for \"Simple Moving Average\". For example, the average price of security for the last 5 daily quotes is (100 + 98 + 99 + 97 + 96)/5 = 98. The Distance to SMA (5 days) is (100-98)/98 = 2.04%.
Distance to ATH (period): a metric that shows how far the current price is from the highest price in the specified period (1 year, 2 years, 3 years or a date range From yyyy-mm-dd to yyyy-mm-dd). For example, the highest price of a security in the last year was 77.4 EUR. The current price is 71.96 EUR. So the Distance to ATH for a 1 year period is equal to (71.96 - 77.4)/77.4 or -7.03%.
Dividend: the distribution of a company\u2019s earnings to its shareholders.
Exchange: a security may be traded on more than one exchange. For example, the NVIDIA stock is traded on Nasdaq (symbol NVDA, exchange NMS) or XETRA (symbol NVD.DE, exchange GER), and many more exchanges.
Exchange rate: the value of one currency in terms of another currency, determining the rate at which they can be exchanged.
Ex-date: used in stock split; date when a stock exchange first trades the (split) shares at the adjusted price.
Ex-dividend date: shareholders who owned their shares at least one full business day before the ex-dividend date will be entitled to receive a dividend. Sometimes also called the ex-date (see above).
Expected # quotes: given the nature and frequency of a security and the calendar in use, PP calculates the expected number of quotes for the time period between the Date of last and first historical quote. Weekend and holidays are taken into account.
Fees: Costs imposed by a service provider or intermediary for facilitating a transaction.
Gross Amount: Utilized when importing data, indicating the overall worth of a transaction, exclusive of fees and taxes. Gross Amount = shares x quote price or Value - fees - taxes. Also referred to as the Amount within the All Transactions view. This terminology may seem counterintuitive, as traditionally the gross value of an entity (such as your salary) is inclusive of taxes.
Historical prices: collection of closing quotes of a security; mostly daily.
Inactive: A security can be set to active or inactive. If set to inactive, the security will not appear in buy or sell dialogs, and historical prices will not be updated automatically.
Interest: the cost of borrowing money or the return earned on an investment; typically expressed as a percentage of the principal, which is the amount of money borrowed or invested.
Investment plan: An automated method to facilitate periodic transactions, such as deposits, withdrawals, interest payments, or purchases.
ISIN: International Securities Identification Number. This is a unique twelve-digit code that is assigned to every security in the world. Mostly used by European brokers & banks.
Latest Quote: the most recent quote of a security. You can refresh these values to the latest information using the menu option Online > Update Quotes.
Maximum Drawdown: Refers to the largest peak-to-trough decline in the performance of a portfolio or investment over a specific period, typically expressed as a percentage. It measures the extent of loss incurred from the highest point to the lowest point before a new peak is reached.
Maximum Drawdown Duration: The worst or longest amount of time an investment has been between peaks.
Name: the full name of the security according to the data source (see below) from which it is retrieved, e.g. Yahoo Finance.
Net Transaction value: the total sum of costs of a transaction, including the taxes and fees. This terminology may seem counterintuitive, as traditionally the net value of an entity (such as your salary) excludes taxes. (Net) Transaction Value = Gross Amount + Fees + Taxes. Also referred to as Value or Debit Note in the Buy transaction input form.
Note: Each security and transaction can be accompanied by a note for additional information or context.
Offset Account: In the context of buying or selling stock, the offset account is the account that is used to balance the transaction. When a security is purchased, the security account is increased, and the offset account, typically a cash account, is decreased to reflect the outflow of cash. Conversely, when a security is sold, the security account is decreased, and the offset account is increased to reflect the inflow of cash.
Purchase Value: the summed\u00a0transaction value\u00a0of each buy (+) and sell (-) transaction of a security, taken into account the reporting period.
Quote: The most recent price at which a security was traded, also known as the price.
Quote Feed (historic): data source or provider of the historic quotes: Alpha Vantage, Bitfinex Cryptocurrency Exchange, Binance Crypto Exchange, CoinGecko, EOD Historical Data, Finnhub, Inflation rate - Eurostat (HICP), ECB Statistical Data Warehouse, Kraken Cryptocurrency Exchange, PWP Leeway UG, Twelve Data, Quandl, Table on website, VIA/CS Funds, Yahoo Finance, Yahoo Finance (Adjusted Close), JSON, no automatic download.
Quote Feed (latest): data source or provider of the latest quotes (same list as above) or could be set as \"same as historical quotes\".
Rate of return: the percentage change in the value of an asset over a given period of time.
Removal: Also named Withdrawal. Taking money out of a deposit account.
Reporting period: Time period that is used to calculate the performance of a security, account, or portfolio.
Risk: Refers to the possibility of losing some or all of the invested capital or not achieving the expected return from your investment.
Security: A tradable financial asset such as stock, bonds, bitcoin, gold, ...
Security account: Repository or container for storing securities.
Sell: transaction resulting in the removal of securities, and where cash is deposited in a deposit account as the equivalent value of the securities.
Semivariance: The variance of the negative fluctuations of an investment.
Source: data source used in File > New Security Search. Possible source are: Yahoo Finance provides financial news and data including stock quotes, press releases, and financial reports. CoinGecko is a website with real-time information on most cryptocurrencies. Portfolio Report is an open source project that aims to provide centralized portfolio performance data.
Shares: Units of ownership in a company or a financial asset. In the context of PP it refers to the number of shares one owns.
Symbol: the abbreviation (ticker) used by the data source.
Target Currency:
Taxes: Charges imposed by government authorities on certain financial activities.
Trade: The purchase and/or selling of a security. An open trade is created for each buying transaction and converted to a closed trade upon selling.
Transaction: an operation that alters the state of a portfolio.
Transaction type: classification of a transaction based on its nature and purpose within the portfolio, e.g. Buy, Sell, Dividend, ...
Type: In the context of the Security Creation Wizard: Share, Bond, Cryptocurrency, Aktie (German for stock or share), W\u00e4hrung (=German for currency), Futures, etf, fonds (= funds). In the context of the All Transaction table: Buy, Sell, Delivery (Inbound or Outbound), Dividend, Deposit, Removal, Interest, Interest Charge, Fees, Fees Refund, Taxes, and Taxes Refund.
URL (historic quotes): the URL that should be provided, if the choice in Quote Feed is set to Table on website or JSON.
URL (latest quotes): see above but for the latest quote provider.
Value: Utilized when importing data, indicating the overall worth of a transaction, inclusive of fees and taxes. Value = Gross amount + fees + taxes. Also referred to as the Net Transaction Value within the All Transactions view. This terminology may seem counterintuitive, as traditionally the net value of an entity (such as your salary) excludes taxes.
Volatility: Refers to the degree of variability in the returns of a portfolio over time. It is a measure of the risk or uncertainty associated with the portfolio's future performance.
Watchlist: manual grouping of securities.
Widget: A data block comprising a label and a numerical value or diagram, designed for placement on a dashboard.
WKN: Wertpapierkennnummer. A German six-digit alphanumeric code for the identification of a security, now replaced by the ISIN code.
Explaining all financial concepts in this manual would be too far-reaching. However, understanding these concepts is crucial for optimal usage of PP and this manual.
In this page, you can find some reliable weblinks to gain a comprehensive understanding of this terminology. Concepts that are specifically related to PP e.g. account, transaction, purchase value, ... are covered elsewhere in this chapter.
To calculate performance, PP requires two types of historical prices: the historical quotes of securities and in case of foreign investments, the historical exchange rates for currencies.
You can find the historical exchange rates under the menu View > General Data. These exchange rates are retrieved from The European Central Bank (ECB) and go back until the year 1999 when the EUR was introduced on the financial markets. They are in fact reference rates and will probably differ slightly from the real transaction rates that your broker or bank will use.
Securities are traded on exchange markets such as NASDAQ or XETRA, where buyers and sellers agree on a price. Historical quotes are the prices of securities at different points in time. The Close price is the last price of the security at the end of the trading day. Other types are the Open quote, the first price of the security at the start of the trading day, the Low and Highquotes, which are the lowest and highest price of the security during the trading day. The Latest quote is the most recent price of the security available from the exchange market. The latest quote may not be the same as the close price.
Note
PP uses the Close quote in its performance calculations. If there is a Latest quote available, it will be integrated in the Close price. For Bitcoins, the situation is more complex because they are traded 24/24. PP uses midnight (on the users system) to set the Close Quote. So, the historical quotes of a bitcoin could vary between users.
Sometimes, the historical quotes are adjusted to reflect certain events that affect the value of the security, such as stock splits, dividends, or mergers. These are called the Adjusted close quotes. They are useful for comparing the long-term performance of the security, as they account for the changes in the number of shares or the amount of cash paid to the shareholders.
There isn't a shortage of financial services that publish historical prices. However, most of them are rather expensive. Many also offer a so-called free account, but as the saying goes, \"if it is free, you are the customer.\" Finding good (precise, up-to-date) but free data sources for all your historical prices can be challenging. PP suggests, among others, Alpha Vantage, Finnhub, Quandl, which were once excellent solutions but have since changed their offerings and are not as useful anymore as free services. Their terms of use and, most importantly, their commitment in the long run often fall short. In practice, only Portfolio Report and Yahoo Finance could be recommended for now. But see the how-to section for some tips & tricks.
Exchange markets (must) publish the historical quotes of the securities they trade. Several financial services such as Yahoo Finance, Alpha Vantage, and others provide historical quotes for different securities and exchange markets through their websites.
There are two primary methods for obtaining financial data from the web: downloading a csv file, or using an API (Application Programming Interface) to get the data.
Both methods start with a request to the financial service or website. A request is a message that contains the information and parameters needed to access the historical quote feed. A request is sent from the client, which is the user's device or application, to the server, which is the financial service or website. The server processes the request and sends back a response. The response could be a csv file, or a structured text (JSON or XML).
In both cases, PP needs to map its internal fields, such as date and value of the quote, with the data in the response. If successfully, PP can use these fields then in its performance calculation.
Note
In theory, one could scrape webpages that contain tables with historical prices (see for example, Figure 1). PP supports this method; see Import HTML table. However, in practice, nowadays most service providers utilize JavaScript or another technology that hinders this scraping process.
"},{"location":"concepts/purchase-value/","title":"Purchase Value","text":"The Purchase Value of a security is the summed\u00a0value\u00a0of each buy (+) and sell (-) transaction of that security, taken into account the reporting period. The value of a transaction includes the taxes and fees; sometimes also called \u201cNet Transaction Value\u201d.
If the purchase date lies before the beginning of the reporting period, then the value at the beginning of the period is taken. If the purchase date lies within the period, then the value at the purchase date is used. However, if the purchase data is later than the end of the reporting period, then the purchase is not taken into account for the calculation of the purchase value. Purchase Value and Purchase Price are used in Reports > Performance > Securities (see figure 1)
Figure 1. Purchase value of a security
Assume the following scenario. We are now 2023, May, 15th and you have bought 30 shares at different times and quotes (see figure 2). An overview of all buys and their respective quotes is shown in figure.
Figure 2. List of Buy transactions of security example
The reported purchase value of a particular security is dependent upon the selected reporting period. In the Table 1, you can see that the purchase value of this simple transaction, can vary between 3300 EUR and 500 EUR, depending on the selected period.
Table 1: Three reporting periods based on the current day (2023-05-15) Period From \u2026 to \u2026 Purchase Value 1 year 2022, May 15 - 2023, May 15 3300 EUR 2 years 2021, May 15 - 2023, May 15 3000 EUR 3 years 2020, May 15 - 2023, May 15 3050 EUR Custom 2000, Jan 1 - 2020, Jan 01 500 EURThe 1 year period starts at 2022, May 15 and ends today (2023,May 15); sometimes also called YTD (Year To Date). Because all purchases fall before the reporting period, the value for each of them is taken from the beginning of the period. At that time (2022, May 15), the share was valued at a quote of 110 EUR (see graph). So, the total purchase value is 30 shares * 110 = 3300 EUR. This is the beginning situation of the period (also called Statement of Assets). Since, there are no purchases afterwards, this amount is also the purchase value of the 1 year period.
The 2 years period starts at 2021, May 15. Only the third buy falls within the period. So, buy 1 and buy 2 are evaluated at the price from the beginning of the period (= 90 EUR). So, the Statement of Assets equals 1350 EUR. There is one buy afterwards (valued at the buying quote). The total Purchase Value of this 2 year period is therefore (5 + 10) shares at 90 EUR + 15 shares at 110 EUR or 1350 +1650 = 3000 EUR.
The 3 years period start at 2020, May 15. The second and third buy lie within the reporting period and are evaluated at their respective quotes: 10 shares at 90 EUR (= 900 EUR) and 15 shares at 110 EUR (= 1650 EUR). The beginning of the period or Statement of Assets is the result of the first buy (2020, Jan 1) takes the quote from the beginning of the period (2020, May 15) which is the same as the purchase quote (e.g. 100 EUR); resulting in a purchase of 5 * 100 EUR = 500 EUR.
The previous explanation can be seen in the pop-over, when hovering the mouse over the Purchase Value (see Figure 3).
Figure 3. Pop-over panel for Purchase value field.
The custom period (from 2000, Jan 1 (not included) until 2020, Jan 1 (included) has a Purchase Value of 500 EUR because it contains only the first buy (= 5 * 100 EUR). The second and third buy or not taken into account because they occur later than the period end. Things become more complicated -but with the same logic- when there are also sell transactions. Important to remember is that PP use a FIFO (First In, First OUT) method to calculate the result of a sell transaction. Suppose that you did a (rather bad timed) sell at 2021, Jul 1 2020 of 12 shares (see Figure 4).
Figure 4. Overview and graph of all buy and sell transactions.
At that moment there were 15 shares available (5 at 100 EUR and 10 at 90 EUR). Selling 12 of them will first sell the 5 shares of 100 EUR and then another 2 of 90 EUR, leaving 3 shares of 90 EUR available.
Now, let's calculate the Purchase Value for the different periods.
1 year period: The period runs from 2022, May 15 until 2023, May 15. All purchases are done before the beginning of the period; so each of them is valued at the price of 2022, May 15, which is 110 EUR. How many shares are available? 5 + 10 - 12 + 15 = 18 at 110 EUR or 1980 EUR.
2 years period running from 2021, May 15 until 2023, May 15. Only the last buy transaction falls within the period and is evaluated at its current quote (110 EUR). The Statement of Assets consists of 3 shares (15 buy - 12 sell). They are evaluated at the price from the beginning of the period (90 EUR). The Purchase Value for the 2 years period is: 3 * 90 EUR + 15 * 110 EUR = 1920 EUR.
3 years period running from 2020, May 15 until 2023, May 15. The Statement of Assets is 0 EUR because all 5 shares from buy 1 are sold (FIFO) on 2021, Jul 15. From the second buy, only 3 shares are remaining, evaluated at 90 EUR. The third buy is evaluated at 110 EUR. The Purchase Value of the 3 years period is 3 shares * 90 EUR + 15 shares * 110 EUR = 1920 EUR. Longer periods have the same Purchase Value.
The reporting period refers to the specific timeframe used when reporting on the performance of your portfolio. For instance, the performance indicators depicted in Figure 1 are computed over a one-year period, starting from the current date. Other reports and charts, such as those concerning return/volatility and securities performance, also consider this reporting period. It's essential to understand that every performance calculation is based on a reporting period, even if one hasn't been explicitly defined. By default, it is set in PP to one year from the current date.
Figure 1. Drop-down list for selecting the reporting period.
The reporting period can significantly influence performance and can be easily manipulated to support a particular viewpoint. Consider, for instance, the price trend of the Amazon share depicted in Figure 2. Depending on the reporting period, you have a massive loss, a massive gain, or a moderate loss.
Note
Use the equations in Basic Concepts > Performance to calculate the performance indices. If you want to check the numbers in PP, use the Kommer portfolio. Add Amazon as a benchmark to the performance chart and set the appropriate reporting period e.g. 2022. Don't forget to switch the portfolio currency to USD to have the performance calculations in USD.
TTWROR = IRR = (84/166.72)-1 = -49.62%TTWROR = IRR = (151.94/84)-1 = +80.88%TTWROR = IRR = (151.94/166.72)-1 = -8.87% or -4.53% p.a.Figure 2. Historical prices in USD for Amazon (period 2022 - 2023).
You can set the reporting period with the drop-down period in the top-right corner of the window (see Figure 1). The available options are: 1 year, 2 years, 3 years, New ..., and Manage .... With this last option, you can delete or reorder the available periods.
The 1, 2, or 3-year period is always calculated from the current day and extends from the end of the current day to the end of the day one, two, or three years earlier. For instance, if today is July 4, 2024, then a reporting period of 1 year will extend from the closing time of July 4, 2023, to the closing time of July 4, 2024. The market value at the beginning (MVB) of this period reflects the portfolio's status at the end of July 4, 2023, while MVE represents the portfolio's status at the end of July 4, 2024 (see for example Figure 3). Concerning the IRR calculation equation, transactions made on the first date, e.g. July 4, 2023, should not be included in the equation, as they are already accounted for in the MVB of the period. Conversely, transactions on the last day of the period should be included in the equation, as they influence the MVE, even if for a very brief period. In the example mentioned above however, as the year 2022 period extends from December 31, 2021, to December 31, 2022, a purchase made on January 1, 2022, should be regarded as a cash inflow.
With the New submenu, you can create custom periods. The choice options in Figure 3 are rather self-explanatory. You cannot give a custom name to this period as they are predefined and named by PP: for example Last 10 trading days or 2023 for the year 2023.
Figure 3. Possible custom periods for reporting (the current day is July 4, 2024).
Last xxx years yyyy months: From the current day minus the number of years and months. The standard periods of 1`` year, 2 years, 3 years could be recreated with this option. With this syntax, however, you could create a custom period, such as a 1.5 years period.Last xxx days: A day refers to a calendar day. Note that in Figure 3, the last xxx days are already pre-populated. PP recognizes that the current year 2024 is a leap year with February 29 and therefore automatically sets the number of days to 366.Last xxx trading days: A trading day refers to a regular business day on which financial markets are open for trading. Weekends and days from the selected calendar are excluded. The calendar to be utilized can be specified in the Help > Preferences > Calendar menu. Are there 256 trading days in 2024? In Figure 3, the Default calendar was selected, which includes seven holidays: New Year, Easter Monday, Christmas Eve, and four others. In the selected period, there are 262 non-weekend days. Out of the seven holidays, six (excluding Christmas Eve 2023) fall on a weekday. Therefore, there are a total of 256 trading days in the year.From xxx (excl.) until yyy: A period between two dates, whereby the first day is not included (starts at the end of that day).Since xxx (excl): from the given date (excluded) until today (included).Year xxxx: The year always runs from December 31, xxxx until December 31, xxxx+1.Current: Week, Month, Quarter, or Year. A week runs from Sunday or Monday (evening) to the following Sunday or Monday (evening), depending on the country specified in the settings. A quarter comprises three months, e.g. January to March, April to June, and so on. The abbreviation YTD stands for Year-to-date and refers to the period from the beginning of the current year up to the present day.Previous: Day, Trading Day, Week, Month, Quarter, and Year. The Previous Day is not the same as the Last 1 days. As of today, July 4, the Previous Day would be July 3 running from the evening of July 2 to the evening of July 3, whereas the Last 1 Day period would be July 4 (the current day). The Previous Trading Day is similar to the Previous Day but excludes weekends and holidays. The Previous Month runs from the first day of the previous month until the last day of the current month. The First Quarter runs from January 1 until March 31. The Previous Year starts on January 1 of the previous year and ends on December 31 of the previous year.The name PortfolioPerformance (PP) captures its purpose very well: managing an investment portfolio from a performance perspective. This focus contrasts with many proprietary broker apps, which primarily facilitate the technical execution of orders. The following text outlines the principal components. Follow the links to obtain more information about each component.
The portfolio has one Securities Account (broker-A) and two Deposit Accounts (in EUR and USD). The balance of the deposit accounts is the end balance on March 5, 2024. Three shares with their historical prices have been added (All Securities). Only share-1 and share-2 have associated transactions and thus participate in the performance calculation. The historical prices are part of the master security data. The Exchange Rates are provided in View > General Data.
Figure 1. Portfolio Performance components and their relationships.
At the center of the system are the Transactions (All Transactions). There are six transactions involved in this example.
The transaction flow in the deposit accounts is clear to follow (as outlined above). Regarding the final balance of broker-A's securities account (129.13 EUR), on March 5, the account contains 5 shares of share-1, valued at 60 EUR, and 5 shares of share-2, valued at 75 USD. As the securities account's base currency is EUR, the USD value is converted to EUR using an exchange rate of 0.9217 USD/EUR, resulting in 69.13 EUR. This brings the total to EUR 129.13, representing the final balance of the securities account.
Performance is calculated on a daily basis. To compute it, you need the market value of the asset at the beginning (MVB) and end (MVE) of the day, along with the total net amount of incoming and outgoing cash flows. With these values, one can calculate the daily performance using the equation provided in Figure 1 (see also reference > view > reports > performance). These daily performances can then be used to determine the cumulative performance. Let's analyze and compare the performance of share-1, share-2, and the overall portfolio across different days.
The name PortfolioPerformance (PP) captures its purpose very well: managing an investment portfolio from a performance perspective. This focus contrasts with many proprietary broker apps, which primarily facilitate the technical execution of orders. The following text outlines the principal components (see figure 1). Follow the links to obtain more information about each component. An example with a simple portfolio can be found in a separate text.
"},{"location":"concepts/system-overview/#components","title":"Components","text":"Figure 1. System overview with components and relations.
Performance is a multi-layered concept. Not only are there several different methods to calculate it, such as money-weighted (IRR) and time-weighted (TTWROR) rates of return, but you can also calculate performance at various levels: the portfolio as a whole, a security or deposit account, an individual security, or a single trade. In its simplest form, without any transactions, the performance of a portfolio can be represented by the following equation (please refer to the links provided earlier for more detailed information):
$$\\mathrm{r = \\frac{(MVE - MVB)}{MVB} \\quad (Eq 1)}$$
where MVE = the market value of the portfolio at the end of the reporting period, and MVB = the market value of the portfolio at the beginning of the period.
Performance is directly influenced by the reporting period, which is set by default to one year from today. The reporting period determines the value of the portfolio, account, or security at the beginning and end of the period (e.g. MVB and MVE in the performance equations). In the case of the money-weighted rate of return (IRR), it also determines the remaining duration that a cash flow has available to generate a profit or a loss at the end of the reporting period.
Currency exchange rates have a more indirect influence and come into play whenever a transaction involves currency conversion. This includes transfers between different currency cash accounts and transactions such as buys, sells, and dividends in multiple currencies. For example, buying securities that are quoted in USD may require you to convert Euros to USD at a certain exchange rate. Upon selling these securities, you may need to convert the USD back to Euros. Fluctuations in the exchange rate between the time of purchase and the time of sale can result in a profit or a loss, as the value of the USD in terms of Euros may have changed.
Historical prices of securities significantly impact the market value and, consequently, the performance of the portfolio, security accounts, individual securities, and trades. It is clear that when a security's price is higher at the end of a trade compared to its price at the beginning, a profitable trade has been made. This price increase results in a capital gain, which directly contributes to the overall performance and value of the portfolio.
Last but not least, performance is directly dependent on the portfolio and transactions. Without any transactions within the reporting period, the basic performance equation simplifies to IRR = TTWROR = (MVE/MVB) - 1. If the MVE is greater than MVB, a profit has been made, resulting in a positive performance. Conversely, if MVE is less than MVB, the portfolio is worth less at the end of the reporting period than at the beginning, leading to a negative performance.
"},{"location":"concepts/system-overview/#transactions","title":"Transactions","text":"Things become more complicated when transactions occur during the reporting period. There are 13 types of transactions, each generating cash flows into and out of the portfolio, account, or security. Figure 2 illustrates all transaction types between the four major components: the portfolio (represented by a dashed blue line), deposit (cash) accounts in both EUR and USD, three securities (two of which are quoted in USD), and collected into two security accounts (orange and blue dashed lines). Security-2 (USD) is present in both accounts.
Transactions are represented by arrows. They generate cash outflows (red circle) or cash inflows (green circle). The numbers next to the circles represent the magnitude of the cash flow, based on a hypothetical example of a buy or sell of 5 shares at 10 EUR/USD per share, resulting in a capital inflow of 50 EUR/USD. Fees and taxes are always set at 1 and 2 EUR respectively. A dividend of 2 USD is paid per share; an exchange rate of 0.9 EUR/USD is used.
Figure 2. Overview of all transaction types with associated cash flows at portfolio, account and security level.
As can be seen, only four types of transactions generate a cash flow at the portfolio level: deposit, removal (withdrawal), inbound delivery, and outbound delivery. These transactions will thus influence the performance indicator on the dashboard (View > Reports > Performance); which is a portfolio performance indicator.
A deposit transaction generates two cash inflows: one at the portfolio level and one at the deposit account level. This transaction results in an inflow because money is brought into the deposit account, and as such also into the portfolio. On the other hand, a withdrawal creates two cash outflows and removes money from a cash account and the portfolio.
An inbound delivery adds shares to a security; thus increasing the capital of the security (shares x historical price) and the security account. Conversely, an outbound delivery decreases the capital by removing shares from the security, resulting in a cash outflow.
Special attention should be given to fees and taxes. The inbound delivery of 5 shares at 10 EUR per share will increase the capital by 50 EUR, but requires a 53 EUR inflow into the portfolio. However, the cash inflow into the security is 51 EUR, because the 1 EUR fee is only split off after the cashflow at the security boundary. To determine the cash inflow or outflow of a security, one should always incorporate the fees. Fees are considered intrinsic to the transaction, whereas taxes are not considered intrinsic to a security. Collecting taxes varies greatly per country, and the performance of a security should not depend on it. Taxes are by default excluded from the performance calculation at security level. Concerning the security account level, PP offers two possibilities: account performance before or after taxes (default calculation); see menu View > Reports > Chart > configure chart > Add data series ... The default After taxes calculation is shown in Figure 2. Upon crossing the security account border (second green circle), the taxes are already accounted for in the taxes component of the security. The cash inflow of the security account is thus 51 EUR. With the Before taxes calculation, the security account cash inflow is 53 EUR, because 2 EUR taxes are deposited into the taxes entity only after crossing the security account border.
All other transactions are internal to the portfolio; they do not influence the portfolio's performance. For example, the transfer-out transaction is a flow between two deposit accounts and, as such, has no impact on the performance of the portfolio, except when there is a currency conversion as in the example of Figure 2.
Suppose that you transfer 100 EUR at the very beginning of the reporting period at a conversion rate of 1.1 EUR/USD, giving you a deposit of 90.91 USD. The exchange rate changed to 0.9 EUR/USD at the end of the reporting period. Because the performance calculation is done in the currency of the portfolio, e.g., EUR, that 90.91 USD is valued at 81.82 EUR at the period end, resulting in a loss of about 18 EUR due to currency loss.
A buy transaction closely mirrors a delivery inbound, except that the cash flow originates from inside the portfolio rather than from outside. From the perspective of the cash account, this resembles a cash outflow. The security and security account receive a cash inflow. For a discussion about fees and taxes, please refer to the earlier text.
A sell transaction will result in a cash inflow into a deposit account (47 USD) because the 50 USD capital sell is reduced by taxes and fees.
Note
In terms of performance, a Buy/Sell versus Delivery Inbound/Outbound transaction can produce significantly different results. Only when a buy transaction is accompanied by a deposit transaction on the same day and for the same amount, there is no difference in performance between buy versus delivery. However, when a buy transaction is not accompanied by a corresponding deposit transaction, the cash balance in the relevant account will be reduced (and potentially become negative), which can have a negative impact on the market value at the end (MVE) of the account.
A dividend can be viewed as a type of sell transaction. In Figure 2, the capital (5 shares) of security-2 (USD) will provide you with a dividend (gross amount) of 10 USD (5 shares x 2 USD/share). The fees are deducted, resulting in a security and security account outflow of 9 USD. After deducting the taxes and converting the remaining 7 USD to EUR, a +6.3 EUR cash inflow is received by deposit-account-1 (EUR).
The separate fees, fees refund, taxes, and taxes refund transactions follow the same rules as outlined above. Therefore, it makes no difference whether you record taxes and fees as part of one buy, sell, or delivery transaction, or whether you split them off into a separate transaction.
A special case is made by the interest and interest charge transactions. Although they do increase or decrease the cash balance of the deposit account, they do not generate any cash inflow or outflow. Just as the capital of a security can increase or decrease as a result of changing quotes (capital gain or loss), the balance of a deposit account can change due to interest.
"},{"location":"concepts/performance/","title":"Performance Measurement","text":"The measurement of the performance of a financial portfolio is based on the concept of return: the increase or decrease of value over a specific period. For example, your portfolio starts at 100 EUR and grows to 104 EUR by the end of the period, resulting in a performance of + 4%. Equation 1 offers three versions of the base formula; also named the Simple Rate of Return (ROR) or Return on Investment (ROI).
$$\\mathrm{r = \\frac{(MVE - MVB)}{MVB} \\quad \\Leftrightarrow \\quad r = \\frac{MVE}{MVB} -1 \\quad \\Leftrightarrow \\quad MVB \\times (1 + r) = MVE \\quad (Eq 1)}$$
where MVE = the market value of the investment at the end of the reporting period, and MVB = the market value of the investment at the beginning of the period. The Market Value (MV) of a deposit account refers to the total balance of the account on a particular date. For a security or a security account, such as stocks, the MV is calculated by multiplying the number of shares by the closing price. The MV of a portfolio is determined by summing the market values of all accounts on that specific date.
Regarding Eq 1, please note that:
To address the above concerns, PP employs two distinct approaches to calculate the rate of return when additional transactions occur within the reporting period: the money-weighted or time-weighted rate of return. It also differentiates between measuring performance on the portfolio, security, or trade level.
Note
The simple Rate of Return (ROR) isn't adequate for describing the performance of a portfolio when transactions occur in the reporting period. Let's take the example from above. Your portfolio already contains one share valued at 100 EUR at the beginning of the year (MVB=100). Due to the favorable track record of the company issuing the shares, its price has increased to 104 EUR per share by the end of the year. Let's now compare the following scenarios:
The money-weighted rate of return (MWR) employs the Internal Rate of Return (IRR) technique commonly used in project management. This calculation takes into account both the timing (when) and the size (how much) of cash, flowing into or out of the portfolio within the reporting period, effectively weighting the return by the amount of money invested at different times.
The money-weighted rate of return or IRR is the annual interest rate that is necessary to bring the beginning market value of the investment (MVB) and all subsequent cash flows to the end value (MVE). Your portfolio must grow (or shrink) each year by a percentage equal to the IRR to generate the specified cash flows within the given time period.
If you find the concept of IRR challenging, please start by first reading the money-weighted section. The calculation method is thoroughly explained by formulas and numerous examples, ranging from a simple single-share investment to multiple transactions including dividends. The examples are based on our demo portfolio to solidify your understanding.
"},{"location":"concepts/performance/#time-weighted-rate-of-return","title":"Time-weighted Rate of Return","text":"The time-weighted rate of return (TWR) is not influenced by the amount invested. Whether you invest one EUR or 100 EUR, you will achieve the same TWR. The reporting period is divided into several holding periods, and for each holding period, a return value is calculated and then compounded into an overall return. Each period carries equal weight; hence the name time-weighted rate of return. In the True Time-Weighted Rate Of Return methodology (TTWROR), performance is calculated using simple returns without any consideration for the total amount invested.
The TTWOR method is explained in depth in the time-weighted section of this chapter.
A nice video about the calculation and difference between the money-weighted and time-weighted approach is given at the Finance and Risk Corner.
"},{"location":"concepts/performance/money-weighted/","title":"The money-weighted rate of return","text":"The money-weighted rate of return is identical to the Internal Rate of Return (IRR) technique used in project management. This calculation considers both the timing (when) and the size (how much) of the cash flows within the reporting period. A cash flow is any amount of money that is added to or withdrawn from a portfolio. The base formula for the IRR calculation is:
$$\\mathrm{MVB \\times (1 + IRR)^{\\frac{RD}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} = MVE \\qquad \\text{(Eq 1)}}$$
where n = the number of cash flows in the reporting period, CFt = the cash flow at time t, and RDt = the number of remaining days within the period after CFt. For MVB, RD equals the entire period, represented in days. To annualize the return rate, you need to divide the remaining days by 365. To calculate the periodic return rate for the entire period such as 2 years, divide by the number of days of the entire period; e.g. 730 days.
Equation 1 closely resembles the calculation of Future Value. In Figure 1, assuming a 10% interest on your investments, the initial 1000 EUR capital will grow to a future value of 1331 EUR in three years. Additional cashflows of 500 EUR and 1000 EUR in the following years will result in 605 EUR and 1100 EUR respectively. The total Future Value of the investment will then be 3036 EUR in three years.
Figure 1. Visualisation of Future Value calculation.
Calculating IRR is the inverse of calculating the future value (FV) of an investment. You don't know the interest rate or IRR, but you do know the MVB, the MVE, and the intermittent cashflows. According to Equation:
1000 * (1 + IRR)^(3x365/365) + 500 * (1 + IRR)^(2x365/365) + 1000 * (1 + IRR)^(365/365) = 3036
From this point forward, equations will be presented in a spreadsheet-like style, utilizing the asterisk (*) for multiplication and the caret (^) for power. This approach results in more concise equations that can be easily copied and pasted directly into a spreadsheet for verification.
500 * (1 + IRR)^(2x365/365) is thus the expected future value of a cash flow of 500 EUR at time 2025-01-01 by the end of the period (after 2*365 days) with an annual interest rate = IRR. Please note that in the absence of any cash flows, Equation 1 resembles the (annualized) simple return formula MVE = MVB x (1 + r).
The IRR is the annual interest rate that must be applied to the beginning value of the investment (MVB) and all subsequent cash flows for their respective durations to equal the end value (MVE). In other words, the IRR of your portfolio is the annual interest rate that it must grow (or shrink) to get the end value.
Unfortunately, there is no easy way to derive the value of IRR from Equation 1. Software tools such as Excel have functions like IRR and XIRR, that employ a brute-force approach, iteratively solving the equation with various \"guesses\" of IRR until a suitable match is identified. In the examples below we will use the Goal Seek method of Excel to illustrate the solution.
"},{"location":"concepts/performance/money-weighted/#defining-the-cashflows","title":"Defining the cashflows","text":"The concept of cash flows appears to be straightforward: it refers to the cash that flows into or out of a system. However, let's consider the demo-portfolio-03 as an example (see Figure 2).
Figure 2. Overview of transactions - Deposit (3x), Buy (3x), Dividend, and partial Sell and charts of share-1 and share-2.
This portfolio has one deposit account broker-A (EUR), and one security account broker-A, containing two securities share-1 and share-2. Only four types of transactions are made: deposit, buy, dividend, and sell. The question is, what are the relevant cash flows in Equation 1 in this context? For instance, a deposit transaction will transfer money into the portfolio and the deposit account. A sell transaction will withdraw money from a security and security account and move it into a deposit account, but it does not affect the portfolio.
Before defining the relevant cash flows, it is essential to determine the level at which performance calculation is required. Do you need to calculate the performance of the entire portfolio (and for which period), of a specific account or security, or of a particular trade?
From the perspective of the portfolio, cash flows only occur when cash or securities are entering or leaving, the portfolio. Only four transaction types are relevant: deposit, withdrawal, delivery in, and delivery out (refer to Figure 3, on the left and right side). Buy, sell, or dividend transactions do not create a portfolio cash flow. Money is not entering or leaving the portfolio; it is only moving between accounts within the portfolio.
From the perspective of the security or security account only five transactions are relevant: \u00b4Buy\u00b4, Sell, Dividend, and also Delivery In and Delivery Out. These transactions will bring money into or out of the security (account). Some people may find it challenging to recognize that dividends are not portfolio cash flows. It may seem as though money is coming to the portfolio from an external source, similar to a deposit. However, the dividend is paid by a company to its shareholders as a distribution of profits. As a shareholder, you are essentially a partial owner, so the shares are paying the dividend themselves.
From Figure 3, you may notice that the cash flow into or out of a security is represented differently than one entering or leaving the security account or portfolio (square versus circle). Consider the first Buy transaction of share-1. It is clear that the outflow from the deposit account is 155 EUR. This amount is used for raw capital purchase (150 EUR), fees (3 EUR), and taxes (2 EUR). So, how much is the inflow into the security (account)? There are four possibilities
share-1. But, even if the share price increases slightly, the MVE will probably be less than the MVB with a negative performance as result It turns out that PP takes an in-between stance. For the calculation of the performance of the whole portfolio, fees and taxes are included (e.g., 155 EUR). For the performance at the security and security account level, only fees are included, and taxes are left out.
Figure 3. Defining all possible cash flows within a portfolio.
"},{"location":"concepts/performance/money-weighted/#irr-at-portfolio-level","title":"IRR at portfolio level","text":"The following examples will calculate the IRR for an entire portfolio. You can find this performance indicator in the View > Reports > Performance dashboard. The resulting IRR can not be extrapolated to an individual account or security. It's the performance of the whole portfolio. Refer to the following sections to calculate the IRR of a specific security or trade. We use the demo-portfolio-03 for all examples.
Assume that in our demo-portfolio-03 only the first deposit transaction on Jan 15, 2021 has occurred. For a reporting period of three years (2020-06-12 2023-06-12), the MVB of the portfolio is zero. The portfolio is indeed empty on June 12, 2020. On Jan 15, 2021, the deposit account balance increases to 155 EUR and remains at that level until June 12, 2023. The MVE of the portfolio is therefore also 155 EUR. According to Equation 1, the IRR could be derived from:
MVB*(1+IRR)^(RD/365) + CF1*(1+IRR)^(RD1/365) = MVE\n \u2193 \u2193 \u2193\n0*(1+0)^(1095/365) + 155*(1+0)^(878/365) = 155\nIt's clear that IRR=0 will satisfy the equation because one (1+0) to any power equals one. Therefore, the performance of the deposit account, and consequently the portfolio, remains zero, even after multiple deposits. This is because deposits increase both the deposit account and the MVE of the portfolio, ensuring that Equation 1 remains balanced with an IRR = 0.
PP has a specific term for these kinds of cash flows or transfers: Performance Neutral Transfers; see, for example, the Performance Calculation Widget. A deposit is 'Performance Neutral' because the transfer of money affects the MVE and the account by the same amount. A deposit account does not receive any interest or incur any costs. A deposited amount will stay unchanged in the account until the end of the period. The effect on performance (e.g. IRR) is zero.
What will happen if a buy transaction is added, similar to the second transaction in Figure 2? The result is twofold:
share-1 is increased by 10 units, which were worth 150 EUR at the time of purchase. The remaining 5 EUR covered fees (3 EUR) and taxes (2 EUR).Because, we are still focusing on calculating the portfolio performance, the equation from above still holds. Except, at the end of the period, share-1 is quoted at 19.006 EUR/share, giving an MVE of the portfolio of 190.06 EUR.
MVB + CF1 = MVE\n \u2193 \u2193 \u2193\n0*(1+IRR)^(1095/365) + 155*(1+IRR)^(878/365) = 190.06\nAn IRR = 8.85% will solve this equation. In order to generate a MVE of 190.06 EUR, the initial cash flow CF1 of 155 EUR must grow at 8.85% per year for 2.41 years or 878 remaining days.
When dealing with multiple cash flows, deriving the Internal Rate of Return (IRR) becomes much more complex. Take, for example, the three buying transactions from Figure 1. The same logic as mentioned earlier still applies.
An IRR = 15.60% will solve the equation.
MVB CF1 CF2 CF3 MVE\n\u2193 \u2193 \u2193 \u2193 \u2193\n0 + 155*(1+IRR)^(878/365) + 84*(1+IRR)^(514/365) + 67*(1+IRR)^(255/365) = 396.85`\nFigure 5 illustrates the calculation in Excel (download workbook). The initial cash flow of 155 EUR will have grown to 219.68 EUR, if the holding period was 878 days and the yearly interest rate was 15.60%. The second buy will increase from 84 EUR to 103.03 EUR. The profit of share-2 appears smaller due to the smaller amount of holding days. The calculation of IRR can be simulated in Excel using the Data > Goal Seek method (see Figure 4). The method tries to set the value of the calculated MVE (cell F11) to the observed MVE (manual input) by iteratively changing the value of IRR (cell F3), until a match (15.60%) is found.
Please note that the individual calculated end values of the shares do not necessarily correspond with the observed individual end values. Compare for example the expected and observed value of share-2. The observed value (cell J9) is much higher. Only the sum of the whole portfolio match and the same calculated IRR is applied to all shares. PP can - of course- also calculate the IRR for individual securities; see below to calculate the performance of individual securities and trades.
Figure 4. IRR-calculation for three buy-transactions.
"},{"location":"concepts/performance/money-weighted/#example-3-buy-dividend-sell-transactions","title":"Example 3: buy - dividend - sell transactions","text":"In PP, the cash proceeds from a selling transaction are deposited into a cash account. A sell transaction is thus the opposite of a buy transaction. The security (account) will be reduced, while the referenced deposit account is increased by the same amount. Both cash flows will cancel each other out.
When a dividend payment is made, the associated deposit account is also increased by the dividend amount. However, it may seem unclear as to where this money originates. Although it appears to come from an external source, PP treats it as if it is generated by the security itself. Without the security, there would be no dividend. When a company pays a dividend to its shareholders, it essentially means that as a shareholder/owner, you are paying yourself a dividend from the company's earnings or profits. As a result, the value of the company, and your shares decrease accordingly.
However, from the perspective of calculating the portfolio performance, these details are not important. Since no money leaves or enters the portfolio, the performance equation is the same as in Example 2, except that the MVE = 426.82 EUR, including the result of the sell and dividend payment.
MVB CF1 CF2 CF3 MVE\n\u2193 \u2193 \u2193 \u2193 \u2193\n0 + 155*(1+0.2028)^(878/365) + 84*(1+0.2028)^(514/365) + 67*(1+0.2028)^(255/365) = 426.82`\nFigure 5. IRR-calculation for buy-sell-dividend transactions.
However, if the dividend payment or selling transaction is \"consumed\" (you bought yourself a coffee from it), resulting in an external cash flow (withdrawal), this transaction should be recorded in PP. Similarly, if you choose to reinvest the dividend or the proceeds from a sale, it necessitates recording a new transaction in PP.
"},{"location":"concepts/performance/money-weighted/#example-4-mvb-0","title":"Example 4: MVB > 0","text":"In the previous examples, all transactions took place within the reporting period. This isn't always the case. It is very important to distinguish the following cases:
CFt occurs before the beginning of the reporting period (MVB date). PP will calculate the value of CFt through historic quotes at time t. The market value of the investment at time t is used in the calculation, not the purchase value. The holding period is the entire reporting period.
CFt occurs after the beginning but before the end of the reporting period. The value of CFt is known through the transaction data. The holding period is the number of remaining days from time t until the end of the reporting period.
CFt falls after the end of the reporting period. CFt does not contribute to MVE and is omitted from the calculation of IRR for that reporting period.
Consider a scenario where the holding period is only two years (from 2021-06-12 to 2023-06-12), or 730 days. Since the first buy of share-1 occurs outside of this period (item 1 from above), the quoted price of share-1 at the beginning of the period is used rather than the actual buying price.
share-1 at the closing price of 17.794 EUR on June 11, 2021 (= the closing price from the day before the start of the period).The resulting formula with IRR = 17.63% is:
MVB CF2 CF3 MVE\n \u2193 \u2193 \u2193 \u2193\n177.94 x (1+IRR)^(730/365) + 84*(1+IRR)^(514/365) + 67*(1+IRR)^(255/365) = 426.82`\nFigure 6. IRR-calculation for a 2 year holding period (MVB > 0).
"},{"location":"concepts/performance/money-weighted/#irr-at-security-level","title":"IRR at security level","text":"The value of the IRR, calculated at portfolio level, doesn't say much about the performance of a specific security. For example, the IRR of demo-portfolio-03 (3 years reporting period) is 20.28% (see Figure 5). The security IRR of share-2 is 112.53% (see Figure 7 at the top). A quick look at Figure 7 (bottom) should clarify why: the security is acquired at the lowest price throughout the entire period. You can obtain the IRR for each security separately using the menu View > Reports > Securities (see Figure 7).
Figure 7. IRR-calculation for individual securities.
The relevant transactions to consider when calculating the performance of a single security are Buy, Sell, and Dividend (see Figure 3). In this instance, there were no deliveries of securities involved. Please note, that from the perspective of a single security:
Importyant
The cashflow to and from a security is always inclusive of fees. Fees are considered an inherent part of the security and the performance of the security is partly dependent on the the size of the fees.
Taxes are excluded from the calculation of security IRR. This exclusion is justified as taxes are not directly associated with a specific security, they are imposed by the government (sometimes collected at later dates), and are beyond the investor's control. Unlike fees, which can be influenced to some extent, taxes cannot. Therefore, the cash flow to consider for the security IRR calculation is the debit note of the transaction minus taxes.
In contrast to the portfolio IRR, dividend, buy, and sell transactions are treated as cashflows. The money from these transactions will 'enter' or 'leave' the security. This happens at the transaction date. Buying/selling the security (at a good or bad time) and paying dividends will impact the performance of the security. As a side effect, deposit accounts are not included in the Security IRR calculation.
With a multi-transaction security, the purchase price and value can be somewhat tricky to determine. For instance, the remaining 10 shares of share-1 are the outcome of two purchase transactions and one sell transaction. Following the FIFO principle (First In, First Out), these 10 shares consist of the 5 remaining shares from the first buy and the 5 shares from the second buy. This results in an average price of 15.50 EUR (see example 6).
A straightforward example is illustrated by the IRR calculation of share-2. The single buy transaction falls within every holding period (1,2, or 3 years). The total cash flow of the transaction, including fees but not taxes, amounts to 66 EUR.
2023-06-12.Inserting these values into Equation 1 will find a solution with IRR = 112.53%; see also Figure 8.
MVB + CF1 = MVE\n \u2193 \u2193 \u2193\n0 x (1+IRR)^1095/365 + 66 x (1+IRR)^255/365 = 111.76\nAs can be seen in Figure 2, share-1 has multiple transactions, 2x buy, partial sell and dividend. It's important to get the dates and cash flows correct, see Figure 9.
Figure 8. IRR-calculation for individual security with multiple transactions.
The first and second cashflow is rather straightforward. 10 shares at 15 EUR/share + 3 EUR fees and 5 shares at 16 EUR/share plus 3 EUR fees. Assuming an IRR = 18% (see Figure 7), the calculated end value of share-1 = 153 x 1.18^(878/365) = 227.81 EUR.
Please note that dividend payments and sales are recorded as cashflows on the transaction date. This differs from the behavior observed in IRR calculations at the portfolio level.
Inserting these values into Equation 2 gives:
MVB CF1 (buy) CF2 (buy) CF3 (dividend) (sell) MVE\n\u2193 \u2193 \u2193 \u2193 \u2193 \u2193\n0 + 153 x (1+IRR)^(878/365) + 83 x (1+IRR)^(514/365) - 30 x (1+IRR)^(179/365) - 107 x (1 + IRR)^(61/365) = 190.06`\nAs can be seen from Figure 8, an IRR = 18.00% will fit the equation..
A trade is formed by aggregating all buy and sell transactions related to a specific security. A trade can be classified as either \"closed\" or \"open\". A closed trade indicates that no further transactions can be conducted within that trade, whereas an open trade means that additional transactions are possible. The demo-project-03 contains 3 trades (see Report > Performance > Trades; Figure 9). A closed trade starts with a buy of share-1 on 2021-01-15 and ends with a partial sell on 2022-01-14. The remaining shares initiate the second open trade, starting at 2022-01-14 and ending at the current date (e.g. 2023-06-12). The third trade is also open because share-2 hasn't been sold yet.
Important
2023-04-12 correspond to those acquired on 2021-01-15, rather than the ones obtained on 2022-01-14.Figure 9. IRR-calculation for trades.
"},{"location":"concepts/performance/money-weighted/#example-7-irr-calculation-of-a-closed-trade","title":"Example 7: IRR calculation of a closed trade","text":"Five shares of share-1 were sold on April 12, 2023. The historical closing price on that day was 22.40 EUR/share. Fees and taxes were 7 EUR, giving a net transaction value of 105 EUR (see Figure 1) or the Exit value in Figure 10.
Because of the FIFO-principle, these 5 shares were from the 1th buy, meaning that they are purchased for 5 x 15 EUR = 75 EUR. The fees and taxes (5 EUR for 10 shares) are proportionally allocated, in this case, 5/2 = 2.5 EUR. The entry value of this closed trade is thus 77.50 EUR. The securities are held for 817 days (from 2021-01-15 till 2023-04-12). The sell transaction will coincide with the MVE. We could use the simplified equation (without any transactions). An IRR = 14.53% will solve the equation.
MVB x (1 + IRR)^RD/365 = MVE\n\u2193 \u2193\n 0 x (1 + IRR)^817/365 = 105\nImportant
PP will always use the current date to calculate an open trade IRR. If you want to follow the previous example, you can try to change the system date on your computer. Restarting PP isn't necessary.
Assume that today is 2023-06-12. The open trade involving share-2 is rather simple. Referring to Figure 2, these shares were acquired for a net value of 64 EUR + 3 EUR fees and taxes on 2022-09-30, which was 255 days ago, assuming that today's date is June 12, 2023. The current value is 111.76 EUR, resulting in 67 * (1 + IRR)^255/365 = 111.7 or IRR = 108%.
The open trade involving share-1 is a special case. Since it is an open trade, it ends on the current day (2023-06-12). The number of days between the purchase date and today is 696 days. The historical price on this date was 19.006 EUR/share. The exit value is thus 190.06 EUR.
The trade consists of shares that were bought in 2021 and in 2022. Five shares are from 2021. The cash flow of these shares is thus 77.5 EUR (see also paragraph above). Today, they are valuated at 95.03 EUR. The remaining 5 shares are from 2022-01-04 with a cash flow of 5 x 16 EUR/share + 4 EUR fees and taxes (see Figure 1). These 5 shares are also 95.03 EUR worth today (2023-06-12).
This corresponds with PP (see Figure 9 above): the exit value is 190.06 = 2 x 95.03 EUR and the entry value is 77.5 + 84 = 161.50 EUR. Inserting these values in Equation 1 will give a solution with IRR=9.16%:
77.5*(1+IRR)^(878/365) + 84*(1+IRR)^(514/365) = 190.06
The Time-Weighted Rate of Return (TWR) gives each time period equal weight in the calculation of the return rate, regardless of the amount of money invested during those periods. . In contrast, the Money-Weighted Rate of Return (MWROR) method assigns greater weight to periods with more money invested, taking into account the size and timing of cash flows.
"},{"location":"concepts/performance/time-weighted/#general-method","title":"General Method","text":"In most financial management handbooks, calculating the time-weighted rate of return for a reporting period is described as a three-step process:
Divide the reporting period into subperiods based on cash flow dates: A subperiod runs from just before a cash flow until just before the next cash flow or the end of the reporting period. As such, the sub-periods are likely to have unequal durations.
Calculate the sub-period growth rates using Equation 1:
$$\\mathrm{1 + r = \\frac{MVE + CFout}{MVB + CFin} \\qquad \\text{(Eq 1)}}$$
where MVE = the market value of the asset at the end of the holding period, MVB is the market value at the beginning of the holding period (which is the same value as the MVE of the previous holding period). CFin is the incoming cash flow, and CFout is the outgoing cash flow in that period.
Compound the sub-period returns into the overall performance for the reporting period using Equation 2:
$$\\mathrm{r = [(1 + r_1) \\cdots \\times (1 + r_n)] - 1 \\qquad \\text{(Eq 2)}}$$
where n is the number of holding periods and rt is the return rate for holding period t.
Note
Figure 1 depicts a simplified example with three holding periods and known performances (10%, 5%, and 10%), which is, of course, not the case in the real world.
Figure 1. Portfolio with 1 Deposit and 1 Withdrawal (Removal) transaction and thus 3 holding periods.
What is the TWR of this portfolio? According to Equation 2, this should be: [(1+0.1)*(1+0.05)*(1+0.1)]-1 = 27.05%. Please note, that this is not an annualized return but a return for the entire period. The durations of the holding periods could differ but no information about durations is provided. Secondly, the sequence of the returns does not matter; (5%, 10%,10%) gives the same result. Lastly, the size and timing of the cash flows do not impact the result. If there were no cash flows, the intermediate values would be: 100*1.1= 110; 110*1.05= 115.5, and 115.5*1.1= 127.5, or the starting value 100*1.275.
However, since there are cash flows, Equation 1 could be used to calculate the holding period returns (instead of assuming they were given):
(110/100)-1 = 10%.[136.5/(110+20)]-1=5%.[117.15/(136.5-30)]-1.Please note that the formula for the cash outflow is slightly different than the one given in Equation 2 (see TTWROR at security level for an explanation).
In the classical method described above, an asset valuation is required at each cash flow. You need to know the value of the portfolio or asset just before each cash flow. However, there are instances when this isn't feasible, and only monthly or quarterly valuations are available. These valuations may or may not coincide with the cash flows. In such cases, an approximation can be used. However, when a valuation is available just before each cash flow, a True Time-Weighted Rate Of Return (TTWROR) could be calculated. The term is coined to differentiate this method from the approximations mentioned above.
In the past, when computing power was expensive, it made sense to create longer holding periods to ease the computational burden, particularly for the required valuations at each cash flow. Today, this is no longer the case, and software like PP can calculate the market value of investments practically in real time. As an in-between solution,PP creates valuations of the different components on a daily basis, regardless of whether there is a cash flow. Therefore, the holding periods all have equal durations of one day.
With daily valuations, it makes sense to assume that cash inflows occur at the very start of the day. The money is immediately available to invest during the day. Consequently, there will never be a portfolio with an MVB of 0, because cash inflows are added immediately to the portfolio. PP also assumes that cash outflows occur at the very end of the day, just before valuation. Thus, it makes sense to reflect this in Equation 1: inflows are added to the MVB, and outflows are added to the MVE.
"},{"location":"concepts/performance/time-weighted/#ttwror-at-portfolio-level","title":"TTWROR at portfolio level","text":"The relevant cash flows for the performance calculation at portfolio level are: Deposit, Withdrawal (removal), Delivery In, and Delivery Out. Refer to the Defining Cashflows section, and in particular Figure 3 from the chapter about Money-Weighted Rate of Return for detailed information.
Note
Figure 2 displays the necessary info for calculating the TTWROR of demo-portfolio-03.
Figure 2. Overview of transactions - Deposit (3x), Buy (3x), Dividend, and partial Sell and charts of share-1 and share-2.
We will use a 2-year reporting period starting from June 12, 2021 in the following examples. Since the initial purchase of share-1 for 155 EUR occurred outside of this reporting period, there are only two cash flows that impact the performance. By June 12, the market value of share-1 (MVB) was increased to 177.94 EUR; see the first chart in Figure 2.
Figure 3. Portfolio from demo-portfolio-3.xml (2 years reporting period).
If there aren't any cashflows in a holding period such as in HP1, one can use the simple rate of return formula: r = MVE/MVB - 1 = 160.26/177.94 - 1 = - 0.0994 or - 9.94%.
The second holding period however starts just before a cash inflow (+ 84 EUR). The MVE is 264.57 EUR. According to Equation 1 the rate of return r = 264.57 / (160.26 + 84) or 8.31%. By adding the cash inflow to the denominator, the influence of this cash flow on performance is neutralized.
The MVB of the HP3 is the same as the MVE of HP2 or 264.57 EUR. There is a cash inflow of 67 EUR and the MVE = 426.82 EUR. The performance r = 426.82 / (264.57 + 67) or 28.73%.
It's important to emphasize that the timing of the cash flows is not considered in this calculation. It doesn't matter whether HP1 is short or long. Additionally, the performance is calculated independently of the size of the cash flow, with the cash inflow being added to the beginning Market Value of the Portfolio (MVB). This approach contrasts with the money-weighted rate of return calculation, where both timing and size of cash flows are taken into account.
For each period, you need MVB or MVEt-1 and the current MVEt period. Because the market value is determined at the end of the trading day (closing price), MVEt-1 is also the value immediately before the cashflow at the beginning of the day.
Note
One could argue that, as we are required to add the cash flow CFin to MVEt-1 (as per Equation 1), an alternative approach is to consider the market value of MVEt, which already includes this cash flow CFint. However, it's important to note that throughout the day, market forces may cause fluctuations in the original MVEt-1, and these variations should be excluded when determining the market value at the beginning of the day, just before the cash flow.
"},{"location":"concepts/performance/time-weighted/#exporting-data-from-pp","title":"Exporting data from PP","text":"Since computer time is inexpensive nowadays, there's no need to define long holding periods to minimize manual computation. Therefore, PP employs a single day as the holding period. You can easily export a CSV-file with the daily portfolio values. Select the menu View > Reports > Performance > Chart and click the icon (top right) Export Data as CSV. Choose Export Entire Portfolio (see Figure 4 for an abbreviated example). Delta in % corresponds with the computed rate of return r. The Cumulative Performance in % is the cumulative or total TTWROR, compounding all returns from the previous days.
Figure 4. Extract of CSV-file from Export Data as CSV (2 years period - portfolio level).
The calculation is analogous to the explanation of the manual calculation. Note that the majority of rows from the Excel sheet are hidden. The market value of the portfolio on 2021-06-12was 177.94 EUR. At the end of HP1 on 2022-01-13 it has dropped to 160.26 EUR. On June 14, a deposit (and buy of share-2) was made. The market value of the portfolio increases as a result to 264.57 EUR. Due to fees and taxes (see Figure 2), the daily performance is negative. The cumulative performance is calculated according to Equation 2, leading to a total performance of the portfolio of 25.58% for the entire reporting period.
The previous section describes the performance of the whole portfolio, including deposit accounts. Understanding the performance calculation for a single security should not pose any problems by now. The same principles are applied. However, there are quite a few differences qua approach.
In PP you can retrieve the IRR and TTWROR of a security through the menu View > Reports > Performance > Securities. However, these values are not displayed by default and should be made available with the Show or Hide columns icon (top right).
Figure 5. Periodic and annual TTWROR for securities (2 years period).
The chart from the menu View > Reports > Performance > Chart can exhibit multiple time series (click the Gear icon). In Figure 6, the cumulative TTWROR for the entire portfolio is depicted, along with individual graphs for share-1 and share-2 over a 2-year reporting period, starting from June 12, 2021. As share-2 was acquired on September 30, 2022, its performance until that date registers as zero (indicated by the horizontal yellow line). From that point onward, the performance of the portfolio diverges from that of share-1 due to the notably successful yet relatively minor contribution of share-2 within the overall portfolio. As can be seen, the periodic TTWROR of the entire portfolio or the last cumulative performance of the portfolio is 25.58%, as calculated in Figure 4.
Figure 6. Graph of the cumulative performance of portfolio, share-1, and share-2 (2 years period).
For the manual calculation, you need to define the holding periods. This is fairly easy for share-2. One holding period should suffice: from just before the buying date until the end of the reporting period. The MVB of share-2 at the beginning of the holding period (just before the buy) is 0 EUR. The MVE equals 111.76. The buy-transaction cost (taxes excluded) is 66 EUR. The TTWROR is thus equal to 111.76/(0 + 66) = 69.33%. You can see this in Figure 6, where the orange line ends just below 70%.
The manual calculation for share-1 is more complex due to the involvement of multiple transactions, especially outflow transactions such as dividends and sales. The best approach to understanding the problem is to draw a timeline, as depicted in Figure 3 or Figure 8. The table below summarises all the relevant info and is based on the CSV export of the daily data (market value, daily rate of return, and cumulative rate of return) from the graph in Figure 6 (click the up-pointing arrow at the top-right).
Figure 7. Manual calculation of (cumulative) performance of share-1.
Note that Figure 7 illustrates two distinct methods for defining holding periods. The first method, previously discussed, defines a holding period from immediately before a cash flow (or the start of the reporting period) until just before the next cash flow (or the end of the reporting period). In this case, the calculated TTWROR is 19.71%, which is higher than the PP indicator of 14.98% (see Figure 5). However, this method is inappropriate for this particular scenario due to the presence of cash outflows.
The reason is that, as shown in Equation 1, outflows are added to the Market Value End (MVE), while inflows are added to the Market Value Begin (MVB). Figure 8 presents a simplified example for clarification.
The reporting period spans 8 days, with a cash inflow (buy) on D1 and a cash outflow (sell) on D5, resulting in two holding periods. The MVB and MVE are displayed below. Note that MVBt = MVEt-1 and that MVEt = quote x #shares for that day.
Figure 8. Simplified example.
According to Equation 1, 1 + r = (MVE + CFout)/(MVB + CFin) or for day 1: (1000+0)/(0+1000); which results in a performance of zero. Note that, since MVBt = MVEt-1, the terms in the numerator and denominator cancel out, leaving the simplified formula for the return of the first holding period (HP1) as: 1 + r = (1010 / 1000), or r = 10%.
However, this method cannot be applied to HP2, because the cash outflow (510 EUR) is added to the MVE of the selling date. The numerator of day 55 isn't equal to the denominator of day 6. The correct simplified formula for HP2 is thus separating the performance calculation for the transaction date from the following days, as is done in Figure 7 (lower part). If the first method was used, then the cash outflow would be added to the MVE of day 8; which is of course not the selling date.
Transferring this method to Figure 7, the return rate of HP1 is straight-forward. r = [(160.26 + 0)/(177.94 + 0)] - 1 = -9.94%. HP2 contains a cash inflow (buy), which causes no problems: r = [(287.49 + 0)/(160.26 + 83)] - 1 = 6.43%.
HP3 and HP4 are special cases as they contain cash outflows. They are split into the day of the transaction itself and the remaining period. The MVE is increased with the cash outflow to neutralize the effect of this outflow. The MVE date of the third holding period is April 11, 2023, while the dividend is disbursed on December 12, 2022. Although an imperfect solution, one approach could involve modifying the formula to subtract the dividend from the MVB, which is at the correct date. However, remember that PP records inflows at the beginning of the trading day and outflows at the end of the day. While the difference for the dividend payment is relatively minor (e.g., 287.49 versus 283.47), it is more significant for the selling transaction (e.g., 339 versus 224). By splitting the holding period into two sub-periods, this issue is resolved, enabling the retention of the original formula in Equation 1.
"},{"location":"concepts/performance/time-weighted/#ttwror-pa","title":"TTWROR p.a.","text":"Figure 5 displays both the (periodic) TTWROR and the TTWROR p.a. (per annum or Latin for per year). The periodic TTWROR represents the performance for the entire reporting period. You can add the TTWROR p.a. indicator in every table or widget with the icon.
The TTWROR p.a. indicator is calculated by assuming that a year has 365 days.
For example, if the periodic TTWROR is 30% over two years or 730 days, the annualized value would be 14.02% or (1.3 ^ (365/730))-1. This is equivalent to taking the square root of 1.3.
If the TTWOR for the month of January is 2%, the TTWROR p.a. would be calculated as (1.02 ^ (365/31))-1, resulting in 26.26%.
The assumption of 365 days per year may cause a slight discrepancy between the periodic TTWROR and TTWROR p.a. when the reporting period includes February 29th in a leap year. However, for non-leap years like 2023, both values will be identical.
In order for you to be able to track, evaluate and manage your securities, Portfolio Performance needs the basic data about your securities accounts and past transactions. After that, you can immediately make your first evaluations and analyze your portfolio and performance from different angles.
"},{"location":"getting-started/#installation","title":"Installation","text":"You can either use one of the precompiled installation files or compile the complete application by yourself. The application is available for MacOS, Windows and Linux.
"},{"location":"getting-started/#creating-a-portfolio-file","title":"Creating a portfolio file","text":"Your first step - of course - is to create a new portfolio file with your accounts. The portfolio file contains all securities, accounts, custody accounts, bookings, classifications, etc.
"},{"location":"getting-started/#adding-securities","title":"Adding securities","text":"You create the securities that are of interest to you in the list of securities. Master data and historical prices are automatically supplemented and updated by Portfolio Performance.
"},{"location":"getting-started/#manage-your-portfolio","title":"Manage your portfolio","text":"So far you have created your portfolio file with a list of interesting securities. Now, it's time to buy and sell some of those securities, receive dividends, set up a savings plan, receive dividends, ....
"},{"location":"getting-started/#measure-your-portfolios-performance","title":"Measure your portfolio's performance","text":"Performance and risk are crucial. Various views and tools can be used to evaluate your portfolio.
"},{"location":"getting-started/#classifying-your-assets","title":"Classifying your assets","text":"To reduce risk, you probably want to diversify your portfolio by region, type, asset, ... Using taxonomies will help you visualize and calculate the amount of diversification.
"},{"location":"getting-started/#define-portfolio-strategy-and-rebalancing","title":"Define portfolio strategy and rebalancing","text":"You map your own portfolio strategy with target values for different share classes. You can make a target/actual comparison and perform a rebalancing.
"},{"location":"getting-started/#keeping-the-portfolio-up-to-date","title":"Keeping the portfolio up-to-date","text":"You book new purchases, sales, and dividends as well as any costs and taxes incurred. This can be done quickly and easily by importing the bank's PDF statements, or manually.
"},{"location":"getting-started/adding-securities/","title":"Adding securities","text":"Right after the preceding Create portfolio step, your portfolio is still empty. You can check with the left sidebar option Securities > All Securities. This list contains all the securities you are monitoring, not necessarily the ones you have purchased. Currently, the list is empty (see Figure 1).
Note
A security is a financial instrument that holds value and can be traded between parties. Securities can be broadly categorized into: debt securities (e.g., banknotes, bonds, and debentures), equity securities (e.g., common stocks) derivatives (e.g., forwards, futures, options, and swaps) [Source Wikipedia].
Figure 1. Main screen after creating a new portfolio.
The Add new investment instrument button allows you to start adding securities to your portfolio. As you can see in Figure 1, you can add new instruments (stocks, bonds, ...), cryptocurrencies, exchange rates. You can also import securities from a CSV-file or to create a new empty security. You could also use the menu File > New menu (see Figure 1).
Adding new instruments
Suppose you intend to acquire NVIDIA shares. Before proceeding with the purchase, you must first add the specific share to the list of Securities. To achieve this, choose either New > Security from the menu or click on New Instrument... (button). This action will open the following window (refer to Figure 2).
Figure 2. Searching and adding new securities to the All Securities list.
You can type (part of) the security name in the search box, e.g. NVID. After clicking the Search button, the list below will be populated with possible target instruments (see Figure 2).
After selecting the appropriate security, click on the Apply button to move on to the next step. Certain information, such as name, symbol, and historical quotes, will be pre-filled based on the selected data source. You have the flexibility to modify all this information, including the name. In Figure 3, it is evident that the currency for the NVIDIA share is incorrectly set to EUR.
Note
An alternative but very convenient method for securities listed on XETRA is to utilize the Portfolio Report website. Adding a security is as easy as drag & drop a link from that website into PP. See how-to > Using Portfolio Report for more info.
Figure 3. Panel for entering info about the selected security.
In some cases, starting with an empty instrument and manually inputting the information might be more straightforward. While only the name is mandatory, it is advisable to set additional details such as Currency, Symbol, and Historical Quotes Feed.
More information about all these attributes can be found in the Reference Manual > File > New. Finding the correct settings to import the Historical Prices of your security is described in the How-to section.
"},{"location":"getting-started/classify-assets/","title":"Classifying your assets","text":"A golden rule of investment is to diversify your portfolio across different sectors, types, regions, ... This strategy helps to mitigate risk by spreading investments across various areas.
With taxonomies, you can visualise and measure diversification. A taxonomy is a tool for categorising the investments within your portfolio. There are several predefined and well-known existing taxonomies, such as the Global Industry Classification Standard (GICS), developed by MSCI. Alternatively, you can create your own custom taxonomy; see Reference > View > Taxonomies for further information.
Figure 1. Taxonomies view with several predefined and one custom taxonomy.
In Figure 1, several predefined taxonomies (Asset Classes, Asset Allocation, etc.) and one custom taxonomy are added to the Taxonomies view. The main pane displays the definition of the custom taxonomy myTaxonomy. It categorises the securities into a Base Currency (EUR) or Foreign Currency group. Daimler and Mercedes are quoted in EUR, while Amazon and Nvidia are quoted in USD. Please note that most securities (72.02%) are not categorised yet and reside in a group labelled Without Classification.
To add a taxonomy to the Taxonomies view, select the File menu and choose New > Taxonomy, or use the sidebar. Select one of the existing taxonomies or create a new one. Use the context menu to add a new classification (category); see Reference > View > Taxonomies > Managing taxonomies for further information.
There are several ways to add a security to a taxonomy category, the simplest being dragging it from the Without Classification list to the desired category, such as Base currency or Foreign currencies.
Select one of the chart icons on top to visualise the taxonomy and gain a sense of proportion between categories. Click on the tabs below to see an example of each available chart type.
Donut chartPie chartTree mapStacked chartStacked area chartDonut chart "},{"location":"getting-started/create-portfolio/","title":"Creating your portfolio","text":"You can quickly create a PP file using a wizard to guide you through the setup process. There are five steps, but only the first two are mandatory. Start with the menu File > New > File to create a new portfolio file.
Step 1
First, you need to select the default currency for the portfolio (see figure 1). You can always change the currency for individual securities. PP supports almost every possible currency: from AED (United Arab Emirates Dirham) to ZWL (Zimbabwean dollar).
Figure 1. Selecting the default currency for the portfolio.
Step 2
Your portfolio must contain at least one security account and one associated reference (deposit) account.
Figure 2. Adding security and reference accounts to the portfolio.
When at least one security account with a reference account has been created, the Finish button becomes available. Don't worry about the next steps if you don't understand what they are about.
Note
If you have an existing portfolio, PP supports importing CSV files to quickly add securities, buy and sell transactions, and payments. See this tutorial for importing a portfolio and dividends.
Step 3
Sometimes, you need more than one deposit account. You can add these extra cash accounts (e.g., in different currencies) to your portfolio.
Figure 3. Adding additional cash accounts to the portfolio.
Step 4
As part of the creation wizard, you can also add the securities that you want to track in this portfolio. These securities are retrieved from German index trackers such as DAX (Deutscher Aktienindex), tecDax, SDAX, and MDAX. You can also add the index itself or others (e.g., NASDAQ) with Indizes. Of course, you can add securities later on. Your choice is then much larger.
Figure 4. Adding instruments to the portfolio.
Step 5
Taxonomies, such as Asset classes and Regions, are used to classify your securities. This classification can then later on be used in performance analysis (e.g., show me the performance of all securities from region xxx).
Figure 5. Adding taxonomies to the portfolio.
Finish
When the wizard is finished, an unnamed.xml file is created. All data of your portfolio is stored in this XML-file (eXtensible Markup Language). More info on the available file-formats here. Of course, you should save it with a different name and location.
PP is available for MacOS, Windows and Linux. You need to download it and do some installation steps. The easiest way to download and install the latest version of PP is by using one of the installer files at the homepage (see fig 1). A link to the release notes of this latest version is also provided.
Figure 1. Homepage with download links for various packages (2023-09-03)
"},{"location":"getting-started/installation/#windows","title":"Windows","text":"You can download the compressed Zip-file and extract it in a directory at your choice. Even a portable USB-stick (about 250 MB free space) is fine (run from stick).
You can also download the Windows - Installer (setup.exe). On Windows 11, you get a security warning about the dangers of running an exe-file. After that, double clicking on this file, will start the installation. You can change the destination folder. By default, the c:\\user directory is taken. You need about 200 MB of free space (see figure 2).
Figure 2. Windows Installer dialog box.
The preferred option is to install Portfolio Performance on Linux is using from Flathub.
Alternatively, you can install PP manually:
sudo apt install openjdk-17-jre\nThe installer files are in fact stored in the author's github repository. So, you can also download the program from this repository. If you ever should need a previous version, this is also the place to be (click on the version number at the left side).
Figure 3. Github repository for downloading (previous) releases
You can edit and compile the source code; see Contributing to Portfolio Performance.
"},{"location":"getting-started/measure-performance/","title":"Performance Dashboard","text":"To assess your portfolio's performance, start by examining the Dashboard. Key performance and risk indicators for the entire portfolio are summarized in a dashboard, accessible through the menu View > Reports > Performance or via the sidebar (see Figure 1). A comprehensive review of the dashboard is available in the Reference Manual under View > Performance. As always, green values indicate a profit, while red signifies a loss.
Figure 1. Dashboard with key performance indicators - 2-year reporting period.
To follow along with the text and Figure 1, download the demo-portfolio-03 file. Select the 2-year reporting period (top right) from 2021-06-12 \u2192 2023-06-12. This implies that your portfolio already contained some stock by June 12, 2021. We begin by examining the Calculation Widget (on the right side).
share-1 shares valued at 17.79 EUR per share, totaling 177.94 EUR (look here for an overview of all transactions in the demo portfolio). Please note, that the historical price of the stock on that day is taken, not the original buying price.sidebar > Reports > Performance > Calculation and click on the Assets at End heading tab. The deposit account shows 125 EUR from deposit, buy, dividend, and sell transactions. share-1 is valued at 190.06 EUR (10 remaining shares x 19.06), and share-2 at 111.76 (8 shares x 13.97). In total, this sums to 426.62 EUR, representing the Final (market) value of your portfolio on June 12, 2023. share-1), and 67 EUR (share-2) are neutralized by buying both securities. Note that the original deposit and purchase of share-1 (155 EUR) is not included because it fell outside the reporting period.share-1 is somewhat complex due to the additional buy and sale. PP follows the FIFO (First-In-First-out) principle. From the remaining 10 shares, 5 will come from the first purchase and 5 from the second purchase. The historical quote at the first purchase date was 17.794 EUR/share and at the second purchase data 15.962 given an average price of (17.794 + 15.962)/2 = 16.878 EUR. The final market value is 19.006 EUR given a capital gain of 10 x (19.006-16.878) = 21.28 EUR. The value of share-2 has increased from 8 EUR (on 2022-09-30) to 13.97 (on 2023-06-12) or a capital gain of 8 x 5.97 = 47.76 EUR. Added together, this gives a total Capital Gain of 69.04 EUR.2023-04-12, you sold 5 share-1 shares at 22.40 EUR per share. Given the FIFO principle, the buying price was 17.794 EUR per share, producing a Realized Capital Gain of 5 x (22.40 - 17.794) = 23.03 EUR. -Earnings are caused by dividend payments (15 x 2 = 30 EUR), while Fees and Taxes encompass all fees and taxes incurred in the reporting period. Keep in mind that fees and taxes were also paid for the purchase of share-1, outside the reporting period.The first column of the dashboard lists the performance key indicators. We start with the more easily comprehended Absolute change and Delta.
Absolute Change minus the Performance neutral Transfers, resulting in 97.88 EUR. You might be tempted to think that Delta should be equal to the sum of all sub calculations (Capital Gains + Realize Capital Gains + ...). As you may noted however, the numbers in the calculation panel do not add up; e.g. Final value <> Initial value + ... Otherwise, you would have counted some elements twice. For example, the result of the dividend and sale is put on a deposit account and as such already included in both the Realized Capital Gains and Earnings and also in Performance Neutral Transfers.By defining a strategy and goal, investors can avoid emotional reactions to market fluctuations and stay focused on their long-term plans. You can use taxonomies (see also the previous section in this Getting Started chapter) and rebalancing to achieve this.
Rebalancing is a strategy of bringing a portfolio that has deviated away from one's target asset allocation back into line Wikipedia. This target can be set in the rebalancing view of a taxonomy (see Figure 1).
Figure 1. Rebalancing view.
The first step is to set the allocation goal for each category. For example, in Figure 1, the (rather counterintuitive) target allocation for the Foreign Currencies category is set to 70%, leaving 30% for the Base Currency category. You can enter or change the allocation percentage by double-clicking the cell, and the target value will be immediately adjusted.
The Rebalance (Amount) and Rebalance (Shares) columns show the amount and number of shares you need to sell (negative number) or buy (positive number) to reach the target value. Naturally, it isn't always possible to buy or sell a fractional number of shares.
Please note that the sum of the allocation percentages across categories does not need to be 100%, although it is advisable. Colour coding will draw your attention to any discrepancies if the sum isn't 100%.
"},{"location":"getting-started/updating-portfolio/","title":"Keeping the portfolio up-to-date","text":"The synchronisation between your physical and digital (PP) portfolio is crucial for making informed decisions. The status of your physical portfolio \u2014such as market value, balance total, and cash flows\u2014 should mirror your digital (PP) portfolio to ensure accurate decision-making. For instance, the rebalancing feature (see previous section) provides suggestions to buy or sell stocks based on the recorded holdings in your digital portfolio.
After making physical transactions with your broker or bank, you need to update your PP portfolio. This can be done manually or automatically:
Manual Update: You create transactions in PP based on the information from your bank or broker. Refer to Reference > Transaction Menu for details about all available transactions.
Automatic Import: You can import transaction data from your bank automatically. Depending on the format, this can be done using PDF documents or CSV files. It is very important that the structure and format of your data match the required format from the import wizard. For example, your CSV file might use a semicolon as a list separator (common in European countries). The import wizard should match this setting.
Importing a CSV File: Use the menu File > Import > CSV files (comma-separated values) to import historical quotes, accounts, securities, and transactions. See Reference > File > Import for further information.
Importing PDF Documents: Banks and brokers often provide account statements on paper or in PDF format. PP can read PDF documents from more than 90 banks or brokers. To verify if your bank is supported, try to import a PDF document. The import wizard will either recognise it automatically or display an error message listing all the banks/brokers it has tried. You can also search the forum using the term PDF import or PDF import [name-of-your-bank-or-broker] to see if an importer for your institution is available or if there are any issues with it. See Reference > File > Import > PDF Bank Documents for further information, including how to request a new importer for your bank.
If you've been following the steps outlined in the \"Getting Started\" chapter, you'll likely have noticed that your portfolio is still devoid of any securities. As of now, you haven't made any purchases. In the chapter Concepts we have covered the fundamental transactions of Buy, Sell and receive Dividends. Now, let's explore a possible workflow for effectively managing your investment portfolio.
There are three possible scenarios to consider, each with its own approach. The simplest one, of course, is starting from scratch.
Starting from scratch. You're beginning your investment journey with an empty portfolio. Apart from elementary strategic decisions about investment goals, risk tolerance, and time horizon, you need to instruct your broker or bank to acquire some securities. Then, you can enter these transactions into PP.
Reconstructing your current portfolio based on past transactions. You have already made some investments in the (far) past, and you need to reconstruct your current portfolio based on past broker or bank statements. Probably, you also need some financial data, such as historical prices or merger data. Depending on how far you would go back, this can be a very challenging task.
Beginning your portfolio management today with an initial valuation. Starting your portfolio management from today involves assessing your current financial situation. Start with the list of your securities and enter for each of them a buy transaction as of today. Of course, you loose some valuable info and the performance calculations aren't reflecting the real performance of your assets.
A bond is a financial instrument that represents a debt obligation. When an entity, such as a government or corporation, issues a bond, they are borrowing money from investors. In return, they promise to pay back the principal amount along with periodic interest payments over a specified period [1]. Bonds are not well-supported in PP but with a few simple workarounds mentioned in the German forum, you could manage them effectively.
"},{"location":"getting-started/manage-portfolio/bonds/#adding-the-bond-as-a-security","title":"Adding the bond as a security.","text":"Let's assume you've purchased a Volkswagen bond. You received the following banknote as shown in Figure 1.
Figure 1. Banknote of buying a bond.
Before you can add the buying transaction, you must create the security in the Securities account. Searching for the ISIN in PP does not yield any results, and searching by name returns the tradable Volkswagen shares. Therefore, you'll need to create an empty instrument and manually input the information for the bond. Historical bond prices aren't particularly crucial since the bond will ultimately be redeemed at 100% upon maturity. However, -if necessary- they can be downloaded in table format from for example the ariva.de website . It's important to note that bond prices in historical records are typically expressed as percentages, ranging from 0 to 100%, rather than in a specific currency like EUR, as is common for shares.
"},{"location":"getting-started/manage-portfolio/bonds/#recording-the-buy-transaction","title":"Recording the buy transaction","text":"Since historical prices are represented as numbers from 0 to 100, you can use this format also for the buying price. At maturity date, the bond will value 5000 EUR with a price of 100%. In terms of shares and quotes, this means that you will receive the value of 50 shares x 100 EUR. However, you buy the security at 91.76% (see banknote in Figure 1). The Gross Value becomes 50 x 91.76 EUR = 4588 EUR. Fees and taxes can be registered as usual.
The bond depicted in Figure 1 matures on October 1, 2027, with an annual interest rate of 2.25%, payable each year on October 1. Since you acquired the bond on October 27 (value day), there have already been 26 days of accrued interest. At a rate of 2.25%, this amounts to 5000 EUR * 2.25% * 26/365, or 8.01 EUR. You have to pay this accrued interest at the purchase date to the seller, but you will get it back on the first interest payment on October 1, 2023.
To process the accrued interest correctly, there are a few options; (see discussion on forum for a few variants).
Adapt the buying price. In case of the example in Figure 1, the buying price becomes 4596 EUR (=4588 + 8.01). The quote price becomes 91.92 EUR of 91.92% (=4596/50). The disadvantage of this method is that the price evolution and the performance calculation is not correct.
Figure 2. Workaround with adaptation of quote price to incorporate accrued interest.
To maintain a precise record of the purchase price, you could record the accrued interest as an additional tax (see Figure 3). The quote price is correct and the correct amount will be withdrawn from the deposit account. The 'false' taxes could be corrected at the first interest payment with a Tax refund transaction.
Figure 3. Workaround with adding accrued interest to taxes.
The buy transaction of the bond security is recorded without the accrued interest. To handle the accrued interest, you transfer the correct amount (8.01 EUR), from the deposit account associated with the security to a separate deposit account. During the first interest payment, the accrued interest amount then is transferred back to the original deposit account associated with the security.
The Transaction > Interest option is designed for recording interest payments on deposit accounts. While it could be utilized for recording bond interest payments, it lacks the ability to specify the security from which the interest originated. Consequently, the deposit account would aggregate all interest payments, without the ability to attribute a particular interest payment to the performance of a specific security.
A better, albeit somewhat unintuitive, approach is to record the transaction as a Transaction > Dividend. Dividends are tied to a specific security, in this case a bond, ensuring that the performance calculation of the bond remains accurate. Depending on the chosen recording option for the purchase (as discussed earlier), the following three transactions could be made.
The accrued interest is fully booked as a dividend (see Figure 4). The accrued interest (for the seller) on the purchase date (8.01 EUR) has already been accounted for in the recorded purchase price.
Figure 4. Interest payment 2.25% of 5000 EUR.
The interest payment (112.50 EUR) is reduced by the amount that was already recorded as tax on the purchase date (8.01 EUR). With a Tansaction > Tax refund that amount is refunded.
When you receive a notification from your bank or broker detailing a transaction, as shown in Figure 1, you need to record this transaction in PP. If it's on paper, you must do this manually. Otherwise, you can attempt to import the transaction.
"},{"location":"getting-started/manage-portfolio/buy/#transaction-with-one-currency","title":"Transaction with one currency","text":"The transaction in Figure 1 involves only one currency. Both the Security and the Deposit Account use the same currency (EUR). There is no need for currency conversion.
Figure 1. Paper note from your bank regarding your buy transaction.
With this note, you can enter the transaction details into PP. Figure 2 displays the input panel for entering the information. The security (Heidelberg Materials) is quoted in EUR and the transaction is handled with the broker-1 security account and the broker-1 (EUR) deposit account. The example of the sell transaction involves a more complex setup with a security quoted in USD, but the transaction handled through a deposit account in EUR.
Figure 2. Buying a security (EUR) through a deposit account (EUR).
Securities > All SecuritiesHelp > Preferences > Language > Country. For instance, the UK uses a 12-hour clock (with AM and PM), while Belgium uses a 24-hour clock.The above six fields are mandatory for completing the transaction. Most of these fields are pre-filled based on the selected security. The following fields are either calculated or optional.
Gross Value : This is the result of multiplying Shares by Quote. If you later change the Gross Value, the Quote Price will be adjusted accordingly to maintain the equation Shares * Quote.
Fees and Taxes : A purchase transaction typically incurs fees and taxes. These may be in the currency of the security and/or deposit account (see selling for an example).
Debit Note : This is the amount you need to pay as a result of this buying transaction. It is calculated as Shares * Quote + Fees + Taxes. Other terms for this are Value or Net Value.
Note : You can add a textual note to each transaction.
The typical flow for entering this information is likely to be Shares * Quote (price) >> Gross Value + Fees + Taxes >> Debit Note. There are a few nuances if you make changes afterward (see Figure 3).
Figure 3. Calculation flow between Shares and Debit Note.
If you want to purchase shares in a foreign currency, there are two options. Either you have the required amount in the foreign currency in a deposit account. Or, you'll need to make a deposit or convert another currency into the foreign currency first.
Figure 4 displays the bank's paper note regarding the purchase of USD shares. Since taxes and fees need to be settled in EUR (due to it being a European bank), and the portfolio's base currency for reporting is also EUR, the total amount in USD is also converted to EUR.
Figure 4. Paper note of a Buy transaction of a share in a foreign currency.
From the note, it isn't quite clear which deposit account (EUR or USD) is used. Recording this transaction in PP however is quite straightforward. Figure 5 shows the transaction done with a USD deposit account. Figure 6 is a little more complex because a EUR deposit account is used; so a conversion should be made (EUR --> USD).
Figure 5. Buy transaction of a USD security with a USD deposit account.
Figure 6. Buy transaction of a USD security with a EUR deposit account.
The quote price and the USD/EUR exchange rate are automatically filled in based on the entered date. However, please note that real-time prices are not available. The entry form in PP also provides the additional option to record fees and taxes in the foreign currency.
Remember: good practice requires making a deposit beforehand, either in USD (for the transaction in Figure 5) or in EUR (Figure 6). Failing to do so will result in a negative balance.
"},{"location":"getting-started/manage-portfolio/delivery/","title":"Recording a Delivery","text":"A Delivery (Inbound) transaction is akin to a Buy transaction, but it does not involve a decrease from a deposit account. It is as if the securities are acquired by magic, without any prior cash transaction. This could be the case for example when inheriting some securities. You also need a Delivery (Inbound) transaction when setting up your portfolio at a later date than the original purchases, without willing or being able to register all past transactions (see third option in Manage your portfolio). Figure 1 compares a Buy and Delivery transaction for the same acquisition.
Figure 1. Delivery (Inbound) versus Buy transaction.
You can record a transaction in a foreign currency by selecting the relevant currency from the drop-down menu. Additionally, it's feasible to record a transaction in a currency different from the security's default currency. An exchange rate will be suggested.
A Delivery (Outbound) transaction is similar to a Sell transaction, but -again- it does not affect a deposit account. The cash that would typically come back from the Outbound Delivery appears to vanish and isn't accounted for in any deposit account. Figure 2 illustrates a Delivery (Outbound) transaction involving Adobe stock (USD) but recorded in EUR.
Figure 2. Delivery (Outbound) of a USD security in EUR currency.
Although the Value of Outbound Delivery, fees, and taxes are not recorded in a deposit account, they can still impact the performance calculation.
"},{"location":"getting-started/manage-portfolio/deposit/","title":"Making a Deposit","text":"To initiate a deposit in a specific currency, navigate to the Transaction > Deposit menu. Ensure that the chosen account shares the same currency as the deposit. For transferring funds between accounts, whether in the same currency or different currencies (utilizing exchange rates provided by the ECB), employ the Transaction > Transfer between Accounts command.
Recording a deposit is a straightforward process (see Figure 1). Input the deposit account, transaction date, amount, and optionally, an accompanying note.
Figure 1. Making a provision for the Heidelberg buy transaction.
Please be aware that a deposit contributes to certain performance metrics. Additionally, note that each security purchase corresponds to a reduction in a deposit account. If the account balance is insufficient, the deposit account's balance may become negative.
"},{"location":"getting-started/manage-portfolio/deposit/#transfer-between-two-currencies","title":"Transfer between two currencies","text":"You can transfer funds between two accounts, whether they share the same currency or not. In cases where the accounts have different currencies (see Figure 2), PP will automatically suggest an exchange rate based on the ECB website.
Figure 2. Converting from EUR to USD.
"},{"location":"getting-started/manage-portfolio/dividend/","title":"Dividend","text":""},{"location":"getting-started/manage-portfolio/dividend/#dividend-transaction","title":"Dividend transaction","text":"Recording a dividend is similar to recording a buy or sale transaction, except that Quote price is replaced with Dividend payment per shares (see Figure 1). The number of shares is automatically determined based on the entered date.
Figure 1. Recording a dividend (same currency).
There isn't a dedicated function for recording a \"Dividend Investment Plan\" (DRIP). One workaround is to record all dividends in full and then proceed with a purchase of the agreed-upon number of shares.More information at Reinvesting dividends.
"},{"location":"getting-started/manage-portfolio/sell/","title":"Selling Securities","text":"The selling transaction is very similar to the buying transaction. Here as well, you can record the transaction's outcomes in an account with the same currency or a different currency. In the latter scenario (see Figure 1), upon selecting the foreign account (e.g. USD), three new fields become available: exchange rate (XR), USD fees, and USD taxes.
"},{"location":"getting-started/manage-portfolio/sell/#selling-a-single-buy-security","title":"Selling a single buy security","text":"In the demo portfolio, we've purchased the Adobe stock only once (10 shares). All those shares have of course the same price, so it doesn't matter which specific ones are sold in the case of a partial sale.
Figure 1. Selling a USD security through an EUR deposit account.
In Figure 1, the share is quoted in USD, and consequently, the Gross Value is also calculated in USD. However, since you intend to record this transaction in a EUR account, this USD value needs to be converted. As soon as you choose a deposit account with a different currency, the exchange rate field (e.g., 0.9491) is automatically filled with the correct exchange rate for that specific date and currency. This information is obtained from the European Central Bank (ECB) website. You can also consult it through the menu View > Currencies > Currency Converter.
Changing the date afterward will adjust the exchange rate (XR) appropriately, even if you've manually entered an XR. Therefore, it's considered good practice to set the transaction date first.
You have the flexibility to input fees and taxes in both currencies. The foreign fees and taxes are automatically converted using the same exchange rate as above. There isn't a subtotal in the local currency, so the Credit Note amount isn't a simple sum of the numbers above.
The calculation flow remains consistent with Figure 3 in the buying page. For instance, modifying the Credit Note will subsequently adjust the Gross Value in EUR, which, in turn, impacts the Gross Value in USD (XR remains unchanged), and finally, the Quote price.
"},{"location":"getting-started/manage-portfolio/sell/#selling-a-multiple-buy-security","title":"Selling a multiple buy security","text":"In your portfolio, some effects may have been purchased multiple times at different prices (see Figure 2 for an example). What happens when you partially sell that share?
Figure 2. Multiple transaction on the same security.
Do those shares come from the first or second series that you purchased, or from a combination of both? For the actual sale, it doesn't matter. In the example from Figure 2, 40 shares were sold at a price of 72.48 EUR. But how are the remaining shares valued? PP follows the FIFO principle (First In, First Out). So, the 40 shares that are sold come entirely from the first purchase. What remains are 10 shares from the first batch and 30 shares from the second batch. Another possibility would be LIFO (Last In, First Out). In that case, 10 shares from the first batch would remain, and none from the second batch. Does this make a difference? In this particular case, the stock is valued lower in the FIFO approach.
FIFO: average price of the remaining 40 shares = ((10 * 58.82) + (30 * 39.60)) / 40 = 44.05 EUR
LIFO: average price of the remaining 40 shares = ((40 * 58.82) + (00 * 39.60)) / 40 = 58.82 EUR
The how-to section demonstrates the features and functions of the Portfolio Performance program in a real-world context. Check the sidebar (or click the menu if it is collapsed) to view all topics. A brief summary of each topic, listed in alphabetical order, is provided below.
Benchmarking your portfolio: Benchmarking involves comparing your portfolio's performance against financial indexes like the S&P 500. This section explains how to find and add indexes from sources like Yahoo Finance and investing.com. It also covers displaying benchmarks in performance charts and comparing your portfolio's performance to these benchmarks.
Copy securities between portfolios: This page explains how to transfer securities between different portfolios in the Portfolio Performance software. It covers methods like Drag & Drop, Exporting & Importing, and Copy and Paste (with intermediate CSV-file). The page also discusses the complexities of copying between XML files.
Downloading Historical Prices provides various methods and sources for obtaining historical stock prices. Most securities are covered by Portfolio Report or Yahoo Finance. In some cases, more sophisticated methods may be required, such as downloading from a CSV File, utilizing a JSON Quote Feed Provider to fetch data, or scraping a table on a website. There are many other sources such as Alpha Vantage, EODHD, and Morningstar .
Handling Choice Dividends focuses on choice dividends where shareholders can choose between cash or stock payments. It includes practical methods for booking these transactions in Portfolio Performance.
Import GBX Priced Securities is a short guide for importing transactions and securities priced in GBX (pence). It emphasizes creating securities with the correct currency and preparing transaction data for import as CSV files.
Inspecting Source Code provides instructions on examining the Portfolio Performance source code on GitHub to understand calculation methods, such as the volatility indicator.
Recording a Merger, Spin-Off, or Stock Split is quite common in portfolio management. These pages discuss various methods, applied to some real examples such as the Amazon stock split, the Daimler Truck Holding AG spin-off, and the Unipol Gruppo's merger. The section about Insolvency explains how to handle securities of insolvent companies, including disabling automatic quote updates, deleting historical prices, and manually adjusting security values.
Importing PDF-bank notes can be a significant time-saver. Requesting a New PDF Importer provides guidance for specific bank or broker transactions, including how to extract and anonymize PDF text, submit requests on the PP forum, and wait for developer integration.
Retrieving gold and other precious metals prices: This page discusses various methods to invest in gold, including physical gold, ETFs, and shares of gold mining companies. It explains how to download historical gold prices from websites like Ariva.de, LBMA, and Gold.org.
User Interface Overview Describes the elements of the PP user interface, such as the menu bar, sidebar, dual-pane layouts, tables within the main pane, and keyboard shortcuts for essential functions.
Most tips and tricks are initially discussed on the PP forum. Regularly checking this forum will provide you with valuable insights into the PP program. It's worth noting that a significant portion of the information on the forum is in German, but you can use your browser's translation function to understand it in your preferred language.
"},{"location":"how-to/benchmarking/","title":"Benchmarking your portfolio","text":"Benchmarking your portfolio performance against financial indexes is a common practice in investment management. This process involves comparing the returns of your portfolio or individual securities to the returns of a selected benchmark index.
A stock index is a measure of the value of a hypothetical portfolio of investment holdings that represents a segment of the financial market. For example, Standard & Poor\u2019s 500 index measures the performance of 500 large companies listed on stock exchanges in the United States. It is a market capitalization-weighted index, which means that the influence of each company in the index is proportional to its market capitalization. On March 8, 2024, the S&P 500 Index stood at 5,123.69 USD.
"},{"location":"how-to/benchmarking/#finding-an-index","title":"Finding an index","text":"A list of major indexes can be found on several financial websites such as investing.com and Yahoo Finance. In order to use an index for benchmarking your portfolio, you need to add it as a security.
For the indexes listed on Yahoo Finance, simply add a new security and search for the ticker symbol; e.g. ^GSPC. If you want to use the data from investing.com, you have to download the historical prices. Select the correct time period and click the download button to receive a CSV-file (you need a free registration for that). Create a new empty instrument. See the section File > Import and How-to > Downloading Historical Prices for a detailed explanation how to import these historical prices. For appending the future daily prices, you can use the daily updated table from the last month. Set the Quote Feed of the Historical Quotes to Table on website and use the following Feed URL: https://www.investing.com/indices/us-spx-500-historical-data. This Quote Feed will not overwrite the existing prices but will append new ones.
There are plenty of mutual funds or ETF's that replicate an index. For example, both Vanguard 500 Index Fund Admiral and the iShares Core S&P 500 ETF replicate the S&P 500 quite narrowly. So, you could use also one these funds as benchmark.
Figure 1. Benchmark of SP 500 index with two replicating funds.
As depicted in Figure 1, the iShares Core S&P 500 ETF closely mirrors the S&P index. The Vanguard index fund also follows the trend closely but exhibits some deviations.
"},{"location":"how-to/benchmarking/#displaying-the-benchmark","title":"Displaying the benchmark","text":"To display a graph similar to Figure 1, follow these steps:
View > Reports > Performance > Chart.Configure Chart icon, represented by a gear symbol, located in the top right corner of the screen.time series and benchmarks.Please take note that the historical prices for the displayed securities differ notably: roughly 5000 USD for the S&P index, and approximately 500 USD for both the iShares ETF and Vanguard index fund. Despite this discrepancy, the curves overlap, indicating that the vertical value axis of the graph represents the performance (not USD). The chart is indeed a performance chart.
"},{"location":"how-to/benchmarking/#comparing-to-the-benchmark","title":"Comparing to the benchmark","text":"Naturally, you'd want to compare the performance of your portfolio or that of an individual security against one of the benchmarks. You may also wish to evaluate your track record of buying and selling by comparing it with the unbiased historical prices of a specific security.
Figure 2 compares the performance of Share-1 (Benchmark) with the actual Share-1 in the portfolio in the main pane. See above for adding both indices to the performance chart. The information pane contains the chart of share-1 with the buy, dividend, and sell transaction indicated. The reporting period spans 3 years for both panes, commencing from May 5, 2021.
Figure 2. Benchmark of SP 500 index with two replicating funds.
The historical price of share-1 was 16.412 EUR/share on 2021-05-05. Therefore, the Market Value Begin (MVB) for the actual share-1 is 164.12 EUR (10 shares) and for the benchmark, it is 16.412 EUR (1 share). You can always export the performance chart as CSV-file to obtain precise numerical data.
After some initial fluctuation, the quote price dropped to 16.026 EUR/share on 2022-01-13 (the day before the second purchase). Using Equation 1 of the section on Time-Weighted Rate of Return, this results in a performance of - 2.35% for both indices.
From that point onwards, the two indices begin to diverge. The benchmark solely utilizes historical prices, while the performance of the actual Share-1 takes into account both inbound and outbound transfers. For instance, on January 14, 2022 (date of purchase), the quoted price was 15.962 EUR/share. Consequently, the daily performance of the benchmark was calculated as 15.962/16.026 = -0.40%, leading to a cumulative performance of -2.74%. Meanwhile, the daily performance of the actual Share-1 was calculated as follows: MVB = 10 x 16.026 = 160.26 EUR; MVE = 15 x 15.962 = 239.43 EUR. The purchase value of 5 additional shares was 83 EUR (inclusive of 3 EUR in fees). According to Equation 1 of Time-Weighted Rate of Return, the daily performance of the actual share-1 is -1.57% (versus -0.40% for the benchmark), giving a cumulative performance of -3.89%.
The most significant divergence occurs when a dividend is paid on December 15, 2022. The performance of the actual Share-1 benefits from this additional outbound transfer, resulting in a significant increase in the daily performance of around 9%.
As previously mentioned, the numerical values for both indices can be obtained from the CSV file. However, the Securities table under View > Report > Securities does not include information on share-1 (Benchmark) due to the absence of associated transactions. Nevertheless, it is feasible to present the benchmark's performance graph and the TTWROR value as a widget.
Figure 3. Dashboard with performance chart and TTWROR widgets.
"},{"location":"how-to/copy-securities/","title":"Copy securities between portfolios","text":"Sometimes, it is necessary to transfer securities between different portfolios, which involves copying information between physical XML files. However, the challenge lies in the fact that each security has historical pricing data associated with it, along with transactions tied to various cash accounts.
"},{"location":"how-to/copy-securities/#drag-drop","title":"Drag & Drop","text":"After opening two or more portfolios, they are displayed as tabs in the portfolio bar located just below the menu bar. The active portfolio, typically the last one opened, is easily discernible. It appears with a lighter color and an x-mark after the name, allowing you to close the tab. To switch between portfolios, simply select the corresponding tab in the portfolio bar. Only one portfolio can be viewed at a time.
However, for tasks like copying securities between portfolios, it's necessary to have both portfolios visible side by side. Securities cannot be directly dragged and dropped or copied and pasted between portfolios from the tabs in the portfolio bar.
Figure 1. Side-by-side display of two portfolios.
To arrange portfolios side by side, choose one in the portfolio bar, click and hold the mouse to drag it to a new position. With two portfolios, you can position them either horizontally (left to right) or vertically (top to bottom). In Figure 1, the arrangement is left to right. This process can be repeated with multiple portfolios, allowing you to make more than two portfolios visible at the same time. To restore the original arrangement, drag the portfolio into the portfolio bar.
For copying securities between portfolios, both portfolios need to be visible. Then, you can select a security from Portfolio A and drag it to the All Securities option in the side panel of portfolio B. There, you can drop the security to create a copy. Pay attention, as it's feasible to unintentionally create identical securities (e.g. two instances of share-1). You can also drop the security to a Watchlist. It will be added to this list then automatically.
Important
When you copy securities from one portfolio to another with drag-and-drop, the associated transactions will NOT be copied along with them. Only the security master data, including historical price information, will be transferred to the new portfolio. This means that any trades, dividends, or other transactions that were recorded for the security in the original portfolio will not be reflected in the new one. In the relatively rare case you need also the transactions, you can either enter them manually or use the following method.
"},{"location":"how-to/copy-securities/#exporting-importing","title":"Exporting & importing","text":"With the menu File > Export > CSV Files, you can create a list of all securities, historical prices, and transactions. See File > Export for more info. Copying the securities with their historical prices however is much easier with the drag & drop technique, described above.
For example, after dragging share-3 from Figure 1 above to the demo-portfolio-03.xml, you can export the transactions of demo-portfolio-04.xml and import them in demo-portfolio-03.xml. You can either use the import type Accounts transactions or Portfolio transactions. The result of the export however contains ALL transactions of the project, not only those that are linked with share-3.
From this table, in fact, you need only the last row. Please note, that the purchase of share-3 is in USD. Because the main cash account is set to EUR, this will generate an error, unless you change (via the context menu) the cash account to USD for that particular transaction.
As can be seen in Figure 2, all transactions will be imported (green checkmark to the left). You can exclude the first four with the context menu Do not import (see Figure 2). Alternatively, you can delete the unwanted transactions from the original CSV file before importing it.
Figure 2. Importing transactions with change of cash account and exclusion.
A more efficient way to select desired transactions is to begin from the All Transactions view. While this list may be extensive, you can streamline it using the Search function. For instance, entering share-3 will filter the transactions to only display those associated with the security named share-3. Alternatively, you can utilize the Filter function available under View > Accounts > All Transactions. You can further narrow down the list by selecting individual transactions (see following topic).
Once you've refined the list, you can export it as either a CSV or JSON file. Click on the Export Data button (located at the top-right with an up-pointing icon) to export either all the displayed transactions or only the selected ones.
"},{"location":"how-to/copy-securities/#copy-and-paste","title":"Copy and Paste","text":"At times, it may be simpler to manually copy and paste the desired transactions, albeit still requiring a CSV file format to import the data.
This technique will also work in the All Transactions view (see previous topic).
Theoretically, one could also copy the transaction code between the two XML files. However, the XML code is optimized for speed which has a negative impact on the readability. A Buy transaction, for example, is represented by the following code snippet:
<account-transaction>\n <uuid>0e6a94e5-da57-44d4-aeb1-37dc792d40ef</uuid>\n <date>2024-03-14T00:00</date>\n <currencyCode>EUR</currencyCode>\n <amount>19800</amount>\n <security reference=\"../../../../../securities/security[2]\"/>\n <crossEntry class=\"buysell\">\n <portfolio>\n <uuid>c1c03e7d-c320-4167-8737-2f35cfb1a2e0</uuid>\n <name>broker-1</name>\n <isRetired>false</isRetired>\n <referenceAccount reference=\"../../../../..\"/>\n <transactions>\n <portfolio-transaction>\n <uuid>75c79e11-4c3d-4b39-bf91-08ab04fe0088</uuid>\n <date>2024-03-14T00:00</date>\n <currencyCode>EUR</currencyCode>\n <amount>19800</amount>\n <security reference=\"../../../../../../../../../securities/security[2]\"/>\n <crossEntry class=\"buysell\" reference=\"../../../..\"/>\n <shares>9900000000</shares>\n <updatedAt>2024-03-14T10:06:25.707240300Z</updatedAt>\n <type>BUY</type>\n </portfolio-transaction>\n </transactions>\n <attributes>\n <map/>\n </attributes>\n <updatedAt>2024-03-13T18:11:15.593620500Z</updatedAt>\n </portfolio>\n <portfolioTransaction reference=\"../portfolio/transactions/portfolio-transaction\"/>\n <account reference=\"../../../..\"/>\n <accountTransaction reference=\"../..\"/>\n </crossEntry>\n <shares>0</shares>\n <updatedAt>2024-03-14T10:06:25.707240300Z</updatedAt>\n <type>BUY</type>\n</account-transaction>\n<security reference=\"../../../../../../../../../securities/security[2]\"/> -which are the result of the optimization- assume an identical structure between the source and target XML, concerning list of securities. Moreover, this method is -of course- not applicable to binary-coded portfolios."},{"location":"how-to/gold-prices/","title":"Retrieving gold and other precious metals prices","text":"Investing in gold is often chosen in times of economic uncertainty. There are multiple ways to gain exposure to gold. One popular method is investing in physical gold, which involves purchasing gold bullion, coins, or jewelry. Another approach is investing in gold exchange-traded funds (ETFs) or gold trackers, such as Invesco Physical Gold. These financial instruments aim to replicate the performance of the gold price by holding physical gold in a secure vault. A third but indirect method of investing in gold is by purchasing shares of gold mining companies. Gold miners engage in the exploration, extraction, and production of gold, and their stock prices can be influenced by the price of gold.
Investing in gold through ETFs and gold mining company shares can be handled similarly to regular stocks like Apple Inc., offering ease of access, liquidity, and potential income. While physical gold differs from traditional stocks in several aspects (e.g. gold does not provide ownership in a company or entitle the holder to dividends), it can still be considered an investment that can be bought, sold, and managed as part of a well-diversified portfolio. And therefore, it can be handled in PP as a regular security.
The PP forum has a thread Wo kann ich aktuelle und historische Gold- und Silberkurse laden?. This section provides a summary and expands upon the information discussed in the thread.
"},{"location":"how-to/gold-prices/#website-arivade","title":"Website Ariva.de","text":"The ariva.de website has a specific page for commodities such as gold, silver, and others. Downloading the latest gold price is as easy as setting the Quote Feed to a webpage https://www.ariva.de/goldpreis_gold-kurs/kurse/historische-kurse. Unfortunately, this method only provides data for the last 30 days. As time progresses, the data will be updated for future days with this method, gradually accumulating several months of gold price history.
Figure 1. Ariva.de website (translated) with historical gold prices .
You can also replace the Quote Feed URL by one of the previous months (e.g. https://www.ariva.de/goldpreis_gold-kurs/kurse/historische-kurse?go=1&boerse_id=172&month=2024-02-29). When importing the data, PP will ask if you want to keep the existing historical prices. By choosing to keep the previous data, you can maintain a continuous record of gold prices for all the months you have downloaded.
But, perhaps the better method is to use a dynamic data URLs. Replace the month=2024-02-29 in the URL from above in the macro version month={DATE:yyyy-MM-32}. This macro will iterate through all previous months (going back to 2003) and send a request for each month until there is no data available. If you start from scratch, this process can take some time and will put a significant load on the ariva.de web server.
Another option to obtain historical gold prices is to register for a free account. Then you can download the historical prices as a CSV file, which can be imported into Portfolio Performance (PP).
"},{"location":"how-to/gold-prices/#london-bullion-market-association-lbma","title":"London Bullion Market Association (LBMA)","text":"The London Bullion Market is the world's largest and most significant market for trading gold and silver. You can retrieve the prices for gold, silver, platinum and palladium per year, going back to 1968, in USD, GBP, and EUR. There are two auctions per day (AM and PM). The data can be displayed as a graph or table per year.
Unfortunately, this table could not be parsed by PP (as it does not contain the necessary keywords such as Close). However, as User ristretto pointed out, you can retrieve the prices through the JSON Quote Feed (see How-to > Downloading Historical Prices). The Feed URL is https://prices.lbma.org.uk/json/gold_pm.json for the PM auction. The three prices under the \"v\" (value) key represent USD, GBP, and EUR, respectively. Please note that in 1968, there is no price available in EUR.
[\n {\n \"is_cms_locked\": 0,\n \"d\": \"1968-04-01\",\n \"v\": [\n 37.7,\n 15.68,\n 0\n ]\n },\n {\n \"is_cms_locked\": 0,\n \"d\": \"1968-04-02\",\n \"v\": [\n 37.3,\n 37.3,\n 0\n ]\n },\n ...\n]\nYou can discover the JSON Endpoint URL by opening the developers tool panel in the webbrowser, selecting the network tab, and refreshing the chart. The Path to Date is $.*.d and the Date Format is yyyy-MM-dd. The Path to Close is $.*.v[0] for the price in USD.
Figure 2. Gold prices through JSON Quote Feed from London Bullion Market.
"},{"location":"how-to/gold-prices/#website-goldorg","title":"Website Gold.org","text":"The website gold.org offers historical gold prices in different currencies and for various quantities (oz, grams, kg; 1 (troy) ounce = 31.1034768 gr). To access the numerical data, you'll need a workaround. First, open the gold prices graph. The server sends a text file (JSON file) containing the data, which is then used to create the graph locally on your computer. This method is more efficient in terms of time and bandwidth.
To find the URL for the JSON download, follow these steps:
Figure 3. gold.org website with developer tools visible.
The URL should look something like:
https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,1709582076959?cache
Upon entering this URL in your browser, you will see the result displayed below.
{\n \"system\": {\n \"request_time\": \"2024-03-04 20:19:20\",\n \"APIserverHostname\": \"fsapi.gold.org\",\n \"protocol\": \"https\",\n \"uri\": \"https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,1709582076959\",\n \"route\": \"fsapi.gold.org\",\n \"cached\": false,\n \"q\": false,\n \"params\": {},\n \"user\": null,\n \"response_size\": 3318,\n \"time_start\": \"2024-03-04 20:19:21\",\n \"time_stop\": \"2024-03-04 20:19:21\",\n \"mem_start\": 32540152,\n \"time\": \"0.021 secs\",\n \"mem_stop\": 57446376,\n \"mem_used\": \"24322.48 KB\",\n \"size\": \"3.33 KB\"\n },\n \"chartData\": {\n \"USD\": [\n [\n 1693872000000,\n 1926.1\n ],\n [\n 1693958400000,\n 1922.05\n ],\n [\n 1694044800000,\n 1918.35\n ],\n [\n 1694131200000,\n 1927.8\n ],\nYou may remove the ?cache parameter. Keep in mind that the workaround may change if the website updates its structure or data retrieval method.
This URL provides JSON data of gold prices between two dates, expressed as Unix timestamps (number of milliseconds since January 1st, 1970), for example, 1693853240038 and 1709582076959. You can easily convert these timestamps to human-readable dates and vice versa using the Epoch Converter website. Luckily, PP can work natively with these dates.
Of course, you want the gold prices until today, not March 4, 2024. Leaving out the second parameter will do that. So, the following URL will display the gold prices from September 4, 2023 until today (note the comma at the end).
https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,To extract the date and the price, you need the JSON-path (see Figure 4).
Figure 4. Quote Feed JSON Provider with Feed URL and Path to Date and Close.
"},{"location":"how-to/handling-choice-dividend/","title":"Handling choice dividends","text":"A dividend is the payment of a part of the company's profit to its shareholders. With a choice dividend, shareholders are given the option to choose between receiving cash payment (cash dividend) or additional shares of stock (stock dividend).
"},{"location":"how-to/handling-choice-dividend/#example-nn-group","title":"Example NN Group","text":"For example, the Dutch financial services company, NN Group provided its shareholders with the option to receive the interim dividend for 2023 of 1.12 EUR per share, either in cash or in shares. The ex-dividend date was set on August 31, 2023, with the dividend payment scheduled for September 25, 2023. The reference share price was determined at 36.2513 EUR by taking the average of five daily historical prices between 12 and 18 September 2023 on Euronext Amsterdam between 12 and 18 September 2023.
With this reference price the distribution ratio was established at 1-for-32.37 shares. Indeed, to receive one share of 36.2513 EUR, you need 32.37 shares x 1.12 EUR dividend.
Theoretically, the cash and stock dividend options should lead to the same gross result. Otherwise, shareholders would naturally gravitate towards the more advantageous choice. Let's consider a scenario where you hold 100 shares of the NN group at the ex-date. Opting for the cash dividend would yield 100 shares x 1.12 = 112 EUR gross. On the other hand, choosing the stock dividend would grant you approximately 3.09 shares (100 shares / 32.37), valued at 36.2513 EUR per share. This totals around 112.02 EUR gross, which is approximately equivalent to the cash dividend amount. Please note that fractional shares are not always possible; although PP can easily work with them. So a solution for the .09 shares may need to be found.
Of course, your choice will be influenced by your need for immediate liquidity (prompting for cash dividend) and your desire to further invest in this company (stock dividend).
Although theoretically equivalent in terms of the gross value, factors such as fees, taxes, and various fiscal and broker regulations will impact the final net amount of cash retained. In practice the choices do differ. For example, a Belgian (thus, foreign) shareholder with 100 shares will receive 68.12 EUR of cash dividend, while the stock dividend is valued at 72.93 EUR; approximately 7% more. This difference is primarily caused by the elimination of foreign taxes in the case of stock dividend.
Note
If you opt for cash dividend. You receive a Gross Amount of 100 x 1.12 = 112 EUR. The net value depends on the fiscal and broker regulations of your country. For example, as a Belgian shareholder, you pay 10% foreign taxes (=11.2 EUR), 30.24 EUR or 30% domestic taxes on the remaining value (112 - 11.2 = 100.8), 2.44 EUR or 2% broker fees + TVA 21%. The remaining net value is 100.8 - 30.24 - 2.44 = 68.12 EUR.
You choose for stock dividend. The calculation becomes much more complex. Your broker need to solve the fractional share and you have to decide about the valuation of the newly acquired shares.
Certainly, the calculation above applies only for a Belgian shareholder with a particular broker in 2024. The advantage of the stock dividend is primarily due to the foreign tax situation, which may differ significantly for shareholders in other countries, particularly Dutch shareholders.
Important
Note that in the case of cash dividend, you will receive money, while with the stock dividend, you have to invest additional money. Although you receive the shares, you also have to cover the associated taxes and fees.
"},{"location":"how-to/handling-choice-dividend/#recording-the-choice-dividend-in-pp","title":"Recording the choice dividend in PP","text":"There has been a lot of debate about how to book these transactions in PP. Many users suggest considering the choice of dividend as a sequence of receiving the dividend and purchasing the shares. A possible workflow is the following.
Figure 1. Implementation in PP
"},{"location":"how-to/import-gbx/","title":"How to use the CSV Import functions for GBX priced securities","text":"The following how-to is based on a discussion Getting started: Cash vs Deposit/Reference accounts in the English language forum.
"},{"location":"how-to/import-gbx/#introduction","title":"Introduction","text":"Portfolio Performance (PP from now on) supports importing of different currencies when importing transactions and movements on cash/deposit accounts. Before reading this guide, you should refer to the main guide on importing which covers things which we will not duplicate here.
This guide is mainly about the peculiar situations which can arise from the UK market habit of pricing some securities (in particular funds) in pence (GBX in PP language) rather than pounds (GBP). This causes complications because our accounts (Securities accounts where we hold the actual securities and Cash accounts used to show money deposited for purchases and obtained from sales of securities) will be in GBP. GBP and GBX are different currencies in the eyes of PP (and many other portfolio tools). So there is actually a conversion which is treated as a currency exchange by PP that needs to happen -- it's a special case.
The importer does a lot well, but has limitations and is at times more helpful or less helpful when it comes to error messages. The process needed to make this work is not always intuitive. It is also possible to successfully import and then find later that the transactions are not actually correct.
The main guide on importing now helps a great deal. It is possible to figure out how to do it now that that guide exists. This extra information is intended to spell out exactly how to do it and hopefully spare some frustration which can otherwise occur.
"},{"location":"how-to/import-gbx/#the-basics","title":"The Basics","text":"If you have a securities account (and probably an associated cash/deposit account) in pounds (GBP), and you need to import anything which was handled in pence, you are doing a currency conversion during the import. The exchange rate is always the same (i.e. 1 GBP = 100 GBX), but it is still a conversion which PP will not handle automatically unless you tell it the currency and exchange rate.
This is NOT a guide about importing GBP and GBX transactions into accounts operated in another currency (e.g. Euros or USD). Some of this information may still be useful in such cases, but it has been written, checked and tested to cover a specific scenario.
It is worth learning how to prepare your import data in a spreadsheet. The more that is done like this, the easier and more reliable your imports will be. It will be more work up front (especially if you need to learn some spreadsheet tricks), but pays dividends later.
For now, we will cover the import assuming the use of spreadsheets in the right form. To be accurate, we will actually be using comma separated value (CSV) files for the actual importing, but the most likely way to create these will be using a spreadsheet tool (e.g. Excel or Google Sheets). The process will involve:
Special care is needed creating securities when dealing with GBX denominated securities.
It is better to create your Securities FIRST in PP.
If you import transactions where a security does not yet exist, PP will create the security. But it will create it with a currency of GBP if the Securities account is in GBP.
You cannot change the currency of a security once you have imported transactions against it and it also creates other extra work. So this is best avoided.
You can create the securities manually, but here we will cover how to use an import.
"},{"location":"how-to/import-gbx/#preparing-securities-data","title":"Preparing Securities Data","text":"The main guide to import covers how to import Securities so we will focus here on things to watch out for when creating GBX securities.
Quick Version
Create a CSV file for the import with the right headings and information for each security. As the main guide to importing securities explains, there are no mandatory fields for a securities import, but one of the descriptors of the security (Ticker Symbol, ISIN, WKN or Security Name) will be needed or you will be importing nothing.
For the purposes of this guide we will be assuming we want to use Yahoo! Finance (YF from now on) later for our historical quotes (prices) and will focus on that case. If you plan to use a different provider of historical quotes, it will be worth looking into what ticker symbol or other identifier (e.g. ISIN, WKN) that source uses and including it at this stage. The YF ticker symbols are really only used by YF. To make things more complex, YF does use some more generic symbols sometimes. You can see this in the example below for VWRP.L, EQIX and GILG.L.
So the information in this CSV will consist of (at a minimum): Ticker Symbol, Currency.
It is worth adding Security Name while you're at it. Like this:
Figure 1. Securities Import spreadsheet example.
The figure above shows an example of a spreadsheet with a number of securities defined. This can be saved as a comma-separated values (CSV) file for import into PP.
Follow the main Securities Import guide for how to import the file.
Explanation
It is worth getting the list of all the securities you want to use across all Securities Accounts together with the Ticker Symbol of your chosen provider of historical quotes (prices) and the security's currency (e.g. GBP, USD, GBp/GBX). If you will be using YF for your historical prices, it is unlikely your broker export will provide the Yahoo! Ticker symbol so you will need to add this.
YF's portfolio tools can be helpful here as it is possible to create a list of securities by searching for each one and adding it to a portfolio. You can create a view of that portfolio showing the information needed above. See example below:
Figure 2. Example Yahoo! Finance portfolio view.
Unfortunately the YF export function does not respect the view you created. Instead, select the data from your browser and then copy and paste into a spreadsheet. When pasting, select to paste as text only.
If using this route it will be necessary to change YF's symbol for pence (GBp) to PP's symbol (GBX). But a simple (but remember case-sensitive) Find/Replace can do that. In the example below, the column names have been changed to match what is required by PP and GBp has been replaced by GBX.
It is worth reiterating a point made in the main Import guide. The currency column should be named \"Transaction Currency\". This is despite PP calling it \"Currency\" in the Import wizard. If you label the column \"Currency\" it will not be automatically selected for import (you will see that the column is not green in the Import Wizard). It is simple to select the column heading in the Import Wizard however if needed.
The name \"Transaction Currency\" may confuse. When you actually buy and sell, your broker platform will probably do everything in GBP not GBX, so it may seem odd that the Transaction Currency is being defined here in GBX. What is really meant is the denomination of the security for pricing/quotes. PP needs to understand what currency the price/quote it receives from a provider is in.
Figure 3. Example Securities CSV import created from a copy/paste from Yahoo! Finance.
"},{"location":"how-to/import-gbx/#importing","title":"Importing","text":"Follow the main guide to importing Securities.
Make sure that all the columns of your data are highlighted green in PP when you start the Import Wizard. Various issues (such as invisible characters present in the column name of the CSV) can mean that PP will not automatically detect the right column name mapping. If this happens, double click where it says \"Double click here\" and select the correct field name from the dropdown.
As discussed in the main guide, although PP will search for providers of historical quotes (prices) it probably will not find many and will not select YF as the source.
You can select historical pricing providers later manually after importing the securities. You may wish to delay this step until after you have checked and imported some transaction data so that you know you are happy that your Securities have been created correctly.
Now that we have our securities loaded, we can move on to importing transactions against these.
"},{"location":"how-to/import-gbx/#preparing-your-transaction-data","title":"Preparing Your Transaction Data","text":"Quick Version
Create a CSV containing all the transactions you wish to import that looks like the (spreadsheet format) example below and has these column names.
Figure 4. Example Portfolio Transactions import data.
Important - Import using the \"Portfolio Transactions\" type of data in the Import Wizard. Using the default of Account Transactions will not work.
Explanation
In these examples, the transaction currency is GBP. So the Value, Fees and Taxes are in GBP.
The objective here is to ensure that your CSV of portfolio transactions is consistent and has the correct currency units and exchange rates before importing.
It is necessary because data exported from broker platforms is very unlikely to be exactly right for PP import and additional data will be needed.
Figure 5. Example Portfolio Transactions import data.
In the example above we have the following columns:
Date -- the transaction date. Here we have formatted in the PP default date and time format. It can also be just in YYYY-MM-DD format. This can be changed by using a \"Custom\" number format if using Excel and entering YYYY-MM-DD as the format. The date can be in other formats, but then you will need to choose the right format in the import wizard which is slower and is easy to forget leading to incorrect dates being imported. Essential.
Securities Account -- this helps avoid errors from overlooking the selection of the correct Securities Account in the Import Wizard. It is essential if you want to import transactions into more than one account in the same import, otherwise it is optional.
Cash Account -- this is included for the same reasons as Securities Account.
Type -- the type of transaction. Essential.
Value -- the net value of the transaction in the base currency of the securities account (i.e. the number of shares x the price of the transaction in the base currency of the securities account). In this case, all the values here are in GBP (\u00a3s) NOT GBX/pence. Essential.
Currency Gross Amount -- the denominated currency of the security. NOT the transaction amount currency. Where the pricing currency of the security matches the currency of the securities account, this is blank, but is Essential where there is a difference.
Exchange Rate -- the rate to convert from the Value to the denominated currency (GBX) of the security amount by multiplication. Essential where the currency is not the same as the securities account currency -- i.e. essential when you have a GBX or say USD denominated security. Only non- essential when the security is priced in GBP.
Fees and Taxes -- self-explanatory and optional. These need to be in the base currency of the securities account/cash account -- in our case, GBP/\u00a3. Optional.
Shares - the number of units/shares traded. Essential.
Ticker Symbol -- the unique ticker symbol used to identify the security. In this case, this is the YF ticker. One of Ticker Symbol, Security Name, ISIN or WKN is required. When we created the securities (see earlier), we specified the Ticker Symbol and the Security Name only. Either of these will do.
"},{"location":"how-to/import-gbx/#importing_1","title":"Importing","text":"Follow the main guide to importing portfolio transactions.
When you click \"Next\" after the first wizard screen, PP will show you which transactions have loaded (green tick) and which may have failed (white cross in a red circle and struck through) in the \"Status\" column as shown below (Status is abbreviated to S. because of the column width).
Figure 6. Import showing two incorrect transactions and a transaction where no security exists.
In the above example, two transactions are marked as errors. The security (iShares Global Inflation Linked Govt...) is actually priced in GBP, but I changed the currency of the security in PP to GBX before this import to illustrate the error.
Because the import CSV (see earlier) does not have an exchange rate for transactions on this security, PP does not know how to convert from the transaction currency (GBP) to the security currency (GBX).
Also note the last line of this import screen showing a Type of transaction \"Security\". This is there because I did not create this security in PP before importing transactions for it (you will notice it was missing from the Securities import example earlier). PP is smart enough to create the security when you first import a transaction. If it is a GBP security this is helpful and a timesaver.
BUT, if the security is a GBX priced security, this will cause a problem because PP will create the security with GBP as the currency (it defaults to the currency of the Securities account). You should therefore cancel the import and fix the problem by creating the security before re-attempting the import.
If you do not do this, then you will need to delete any transactions for the problem security, delete the security, recreate the security with a currency of GBX and then import again.
You can use the same transactions CSV import file because PP will ignore any transactions already loaded from that file showing these as errors.
Alternatively, delete all transactions and reload everything again. It is not slower and perhaps safer to know you started from a blank slate. That way, any errors shown will be real errors and you avoid the risk of missing real errors because you are expecting some errors for duplicate transactions.
That's it for the transactions. If you want to import cash transactions read on.
"},{"location":"how-to/import-gbx/#importing-dividends","title":"Importing Dividends","text":"Quick Version
Importing cash transactions is also covered in the main guide. Importing GBP dividends for a GBX priced security is an example of a different currency dividend and the import looks like this.
<figure-caption identifier=\"Figure\"class=pp-figure}
Explanation
Some cash transactions are general to the cash account. For example, depositing and withdrawing funds to and from the Cash Account. These are not linked to a particular security so no special process is needed.
Some cash transactions are entered along with buy/sell transactions. These are transaction fees and transaction taxes (stamp duty in the UK). We do not need to concern outselves about those here (they are addressed above and in the main Import guide).
The situation is different for cash transactions which are linked to securities which are priced in GBX. Usually this is only dividends and equalisation payments. Less commonly, corporate actions may result in a release of capital or other payment. Any such payment of a cash amount whilst securities are held will use the Dividend type of transaction.
The main Import guide covers how to handle dividend imports when foreign currency is involved. That process can be followed for dividends on GBX priced securities.
In the example import file below, there are four dividends:
Figure: Figure 8 - Example dividend import data. {class=pp-figure>Importing a GBP dividend to a GBX priced security.
Date, Type, Value, Gross Amount, and Exchange Rate are mandatory. One of Ticker Symbol, Security Name, ISIN or WKN is required to identify which security is involved.
Cash Account is normally optional if all dividends will be applied to the same account (which is specified in the Import Wizard). Here however we are being specific about the Cash Account in order to allow dividends for more than one account to be imported together.
Note is optional.
A rarer type of dividend occurs when the security is priced in GBP, but dividends are received in USD. HMEF.L is an example of such a fund. There does not appear to be a way to handle this situation through import currently.
The options to handle this are:
Insolvency occurs when a company is unable to pay their bills. Investors might see a notice that Administrators or Receivers are appointed, which realistically means your securities are probably worthless.
The value can be depreciated as follows:
Edit the security and set Quote Feed Provider to No automatic quote download.
In the Information pane view Historical quotes, select the prices to be deleted then use the context menu to Delete them.
In the All Securities context menu, Quotes, Create manually, enter a Quote at least 0.00000001.
Once the proceedings are concluded:
While using the PP program, you may sometimes encounter results that you don't fully understand. PP already goes a long way to explain its calculations and results by offering intermediate results, popovers with detailed information, and possibilities to export the data in various forms to further analyze with other tools, such as Excel.
Another possibility is to inspect the source code or the XML-file. The beauty of open-source software like PP is that the source code is readily available. Inspecting the code offers a unique insight into how things are measured and calculated.
"},{"location":"how-to/inspect-source-code/#example-1-how-is-the-volatility-indicator-calculated","title":"Example 1: How is the volatility indicator calculated?","text":"The performance dashboard (View > Reports > Performance) displays several indices of performance and risk, including the volatility indicator. From other sources, such as Investopedia's How Do You Calculate Volatility in Excel?, you know that volatility is often measured by the standard deviation between returns of an investment. A typical Excel formula looks like: = STDEV.S(A1:A100) * SQRT(100), assuming that the daily returns are within the range A1:A100 in Excel.
Upon trying this on your portfolio, you get different results. So, you decide to inspect the source code.
Use the search bar at the very top of the window to search in the repository: portfolio-performance/portfolio. Enter a relevant search term, such as \"volatility,\" to find the source code where this term is mentioned. Scroll through the different modules to get the feeling. It will be rather evident why volatility appears in these modules.
Figure 1. Result of the Search 'Volatility' in the github repo of PP.
The first module (name.abuchen.portfolio/src/name/abuchen/portfolio/math/Risk.java) is most relevant. It is about \"Risk\" within a folder named \"portfolio/math\". Click within the box to see the code.
= STDEV.S(B1:B100) * SQRT(100) where the column B contains the logarithmic values of the returns such as =LN(1 + A1) will provide the exact same volatility from PP.File\n\u251c\u2500\u2500 New\n\u2502 \u251c\u2500\u2500 File\n\u2502 \u251c\u2500\u2500 Security\n\u2502 \u251c\u2500\u2500 Cryptocurrency\n\u2502 \u251c\u2500\u2500 Exchange Rate\n\u2502 \u251c\u2500\u2500 Consumer Price Index\n\u2502 \u251c\u2500\u2500 Taxonomy\n\u2502 \u2514\u2500\u2500 Watchlist\n\u251c\u2500\u2500 Open... Ctrl+O\n\u251c\u2500\u2500 Open Recent\n\u2502 \u251c\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 Clear List\n\u251c\u2500\u2500 Save Ctrl+S\n\u251c\u2500\u2500 Save as... Ctrl+S\n\u2502 \u251c\u2500\u2500 Password protected (AES-256)\n\u2502 \u251c\u2500\u2500 Binary\n\u2502 \u251c\u2500\u2500 XML\n\u251c\u2500\u2500 Save All\n\u251c\u2500\u2500 Currency >\n\u2502 \u251c\u2500\u2500 EUR (Euro)\n\u2502 \u251c\u2500\u2500 USD (United States dollar)\n\u2502 \u251c\u2500\u2500 A - D >\n\u2502 \u2502 \u251c\u2500\u2500 AED (United Arab Emirates dirham)\n\u2502 \u2502 \u251c\u2500\u2500 ...\n\u2502 \u2502 \u251c\u2500\u2500 DZD (Algerian dinar)\n\u2502 \u2514\u2500\u2500 E - I >\n\u2502 \u251c\u2500\u2500 ...\n\u251c\u2500\u2500 Tools \n\u2502 \u251c\u2500\u2500 Sanity Check...\n\u2502 \u251c\u2500\u2500 Fix: Restore ...\n\u251c\u2500\u2500 Import\n\u2502 \u251c\u2500\u2500 PDF Bank Documents\n\u2502 \u251c\u2500\u2500 CSV files (comma-separated values)\n\u2502 \u251c\u2500\u2500 Templates >\n\u2502 \u2502 \u251c\u2500\u2500 comdirect Musterdepot\n\u2502 \u2502 \u251c\u2500\u2500 ...\n\u2502 \u2502 \u251c\u2500\u2500 custom templates\n\u2502 \u251c\u2500\u2500 XML Documents (experimental)\n\u2502 \u251c\u2500\u2500 Interactive Brokers: Activity Flex Query\n\u2502 \u2514\u2500\u2500 Debug: Create text from PDF...\n\u251c\u2500\u2500 Export\n\u2502 \u251c\u2500\u2500 CSV files (comma-separated values) .. Ctrl+Shift+S\n\u2502 \u251c\u2500\u2500 Portfolio Performance XML\n\u251c\u2500\u2500 Close File\n\u2514\u2500\u2500 Quit Ctrl+Q\nView\n\u251c\u2500\u2500 Options\n\u2502 \u251c\u2500\u2500 Always start with 'All transactions' in this part\n\u2502 \u251c\u2500\u2500 Always start with last view\n\u2502 \u251c\u2500\u2500 Hide sidebar ... Ctrl+K\n\u2502 \u251c\u2500\u2500 Hide information pane ... Ctrl+L\n\u2502 \u251c\u2500\u2500 Discreet Mode\n\u251c\u2500\u2500 Securities\n\u251c\u2500\u2500 \u251c\u2500\u2500 All Securities\n\u251c\u2500\u2500 Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Deposit Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Securities Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Investment Plans\n\u251c\u2500\u2500 \u251c\u2500\u2500All transactions\n\u251c\u2500\u2500 Reports\n\u2502 \u251c\u2500\u2500 Statement of Assets\n| | |\u2500\u2500 Chart\n| | \u251c\u2500\u2500 Holdings\n\u2502 \u251c\u2500\u2500 Performance\n\u2502 \u251c\u2500\u2500 Calculation\n\u2502 \u251c\u2500\u2500 Chart\n\u2502 \u251c\u2500\u2500 Return / Volatility\n\u2502 \u251c\u2500\u2500 Securities\n\u2502 \u251c\u2500\u2500 Payments\n\u2502 \u2514\u2500\u2500 Trades\n\u251c\u2500\u2500 Taxonomies\n\u251c\u2500\u2500 General Data\n\u251c\u2500\u2500 \u251c\u2500\u2500 Currencies\n\u2514\u2500\u2500 \u251c\u2500\u2500Settings\nTransaction\n\u251c\u2500\u2500 Buy ...\n\u251c\u2500\u2500 Sell ...\n\u251c\u2500\u2500 Delivery (Inbound) ...\n\u251c\u2500\u2500 Delivery (Outbound) ...\n\u251c\u2500\u2500 Security transfer ...\n\u251c\u2500\u2500 Dividend ...\n\u251c\u2500\u2500 Deposit ...\n\u251c\u2500\u2500 Removal ...\n\u251c\u2500\u2500 Interest ...\n\u251c\u2500\u2500 Interest Charge ...\n\u251c\u2500\u2500 Fees ...\n\u251c\u2500\u2500 Fees Refund ...\n\u251c\u2500\u2500 Taxes ...\n\u251c\u2500\u2500 Taxes Refund ...\n\u2514\u2500\u2500 Transfer between accounts ...\nOnline\n\u251c\u2500\u2500 Update Quotes ... Ctrl+U, K\n\u251c\u2500\u2500 Update Quotes (only active securities) ... Ctrl+U, A\n\u2514\u2500\u2500 Update Quotes (selected security) ... Ctrl+U, T\nHelp\n\u251c\u2500\u2500 About Portfolio Performance\n\u251c\u2500\u2500 Preferences ...\n\u251c\u2500\u2500 Check for Updates ...\n\u251c\u2500\u2500 New & Noteworthy\n\u251c\u2500\u2500 Changelog\n\u251c\u2500\u2500 Welcome\n\u251c\u2500\u2500 Forum\n\u251c\u2500\u2500 Join translation teams\n\u251c\u2500\u2500 Source Code on Github\n\u251c\u2500\u2500 How-Tos\n\u251c\u2500\u2500 FAQ\n\u251c\u2500\u2500 Show Error Log\n\u251c\u2500\u2500 Save Error Log ...\n\u2514\u2500\u2500 Debug: Reset GUI ...\nA merger occurs when two separate companies combine forces to create a new organization. An acquisition refers to the takeover of one company by another. According to Investopedia, both terms have become increasingly blended.
Exxon Corp. and Mobil Corp. completed their merger in November 1999. Exxon shareholders owned 70 per cent of the new company. Mobil shareholders are left with 30 per cent of the merged group.
This corporate action could be recorded in PP as an outbound/inbound delivery. Suppose that you owned 10 Exxon and 50 Mobile shares. This will result in (10 x 0.7) + (50 x 0.3) = 7 + 15 or 22 shares of ExxonMobil Corp.
According to Reuters, the Italian financial group Unipol announced on February 16, 2024 an offer to acquire the remaining 14.75% stake in UnipolSAI. Unipol Gruppo is offering 2.7 euros per share to buy out UnipolSAI shareholders, or alternatively, UnipolSAI shareholders can exchange 10 shares of UnipolSAI for 3 shares of Unipol Gruppo.
From the respective websites (Unipol Gruppo and UnipolSAI) we know that the closing price on February 15 was \u20ac 5.74 for Unipol Gruppo and \u20ac 2.4/share for UnipolSAI. were:
"},{"location":"how-to/recording-spin-off/","title":"Recording a spin-off operation","text":"In the context of stock markets, a spin-off refers to the process by which a company separates or \"spins off\" a portion of its business into a new, independent entity. This new entity becomes a distinct, standalone company with its own management, operations, and often its own publicly traded stock.
The shareholders of the original company may receive shares in the new entity in proportion to their holdings in the parent company. A distribution ratio determines how many shares of the new entity each shareholder receives for every share held in the original company.
On December 10, 2021, Daimler AG successfully executed a spin-off, resulting in the establishment of a new entity known as Daimler Truck Holding AG. Simultaneously, the former Daimler AG underwent a name change to become Mercedes-Benz Group AG. Consequently, the XETRA stock exchange market now encompasses two distinct securities: ISIN DE0007100000 for Mercedes-Benz (formerly Daimler AG) and ISIN DE000DTR0CK8 for Daimler Truck Holding AG. The distribution ratio for this spin-off was 2:1, signifying that for every two shares of Daimler AG, shareholders received one share of Daimler Truck Holding AG.
Figure 1. Quote evolution of the Daimler Truck Holding and Mercedes-Benz Group.
To record a spin-off in Portfolio Performance (PP), a suggested workflow, deduced from an in-depth discussion on the PP forum, involves the following steps:
Change the name of the security Daimler AG into Mercedes-Benz AG and create a new security Daimler Truck Holding AG in your portfolio.
Create a dividend transaction for the Mercedes security on December 10, 2021. The dividend price is set to \u20ac 14/share (see below for an explanation).
Create a buy transaction of n shares of Daimler Truck Holding AG, where n is 1/2 of the number of shares of the old Daimler AG. According to XETRA, the opening price of Daimler Truck Holding AG on December 10, 2021 was 28\u20ac/share (no fees or taxes).
Use the same deposit account for the dividend and buy transaction. This way the result of the fictitious dividend transaction will be cancelled out by the real purchase transaction. The dividend of n shares x 14\u20ac/share = purchase of n/2 shares x 28\u20ac/share.
Figure 2. Recording the spin-off of Daimler AG.
This workflow solves the spin-off problem by simulating a dividend transaction followed by an equivalent purchase for the same amount. However, a drawback is that there is no real dividend, compromising the precision of the dividend overview. Conversely, from a performance standpoint, treating the spin-off as a dividend makes sense. For example, there was a noticeable decline in the share price of the old Daimler AG, dropping from approximately \u20ac90 in mid-November 2021 to \u20ac74 on December 10, 2021, suggesting market anticipation of the impending spin-off.
"},{"location":"how-to/recording-stock-split/","title":"Recording a stock split","text":"A stock split increases the number of shares in a company. For instance, following a 2-for-1 split, each investor will possess double the number of shares, and each share will be valued at half its previous price. A stock split leads to a reduction in the market price of individual shares but does not alter the total market capitalization of the company. Stock splits are frequently executed to make shares more accessible to a broader range of investors and enhance market liquidity. Conversely, a reverse stock split (1-for-5) entails fewer stock shares but at a higher price.
There are essentially two methods for recording a stock split in PP: using the built-in function or a sell-buy-back operation. Each method has its own set of advantages and disadvantages.
"},{"location":"how-to/recording-stock-split/#use-of-the-built-in-stock-split-function","title":"Use of the built-in Stock split-function","text":"PP currently supports stock splits via work-around; see the discussion on the forum. Essentially, it retroactively assumes that the shares have always been split. This ensures the correct number of securities in the portfolio after the split and maintains historically consistent cash flows and valuations, thereby preserving the security's performance. However, the number of shares before the split may not align with the real historical situation, potentially complicating the understanding of the security's history.
This change is destructive. It is not easily undone. If necessary, an improperly executed split can be corrected by executing a split with an inverse ratio. But perhaps a better approach is to create a backup copy of the portfolio file.
In the description of the Stock Split process in the Reference Manual, the example of the Amazon 20-for-1 stock split on June 6, 2022 is used. Please review this section first.
In Figure 1, the share price evolution over the last five years is depicted. Very noticeable, there is a massive drop on between June 3 and 6, 2022. On those dates, the closing prices were $ 2447 and $ 124.79, respectively (but remember, you own 20 times more shares). Assume that you have purchased one (pricy) share on January 3, 2022 for the amount of $ 3408.
Figure 1. Historical Quotes chart of Amazon (unadjusted prices).
Quite some confusion arises when you compare this chart with those from most other financial websites; for example, the 5-year chart from investing.com looks very different.
Figure 2. Historical Quotes chart of Amazon (adjusted prices).
Both charts span an identical five-year period. But, while your purchase price was $ 3408, it appears to be priced around $ 150 around January 2022. This discrepancy arises because financial websites typically \"adjust\" all historical prices after a stock split. This adjustment involves recalculating the historical prices before the split, just as the PP's Stock Split function does.
Figure 3. Historical Quotes chart of Amazon (adjusted prices).
Important
The \"regular\" Yahoo Finance Close Price is already adjusted for splits. The Adjusted close price is en surplus adjusted for splits and dividend and/or capital gain distributions.
Some considerations
The built-in stock split function perfectly mirrors the approach adopted by most financial websites. This results in the Adjusted prices chart (Figure 3) being identical to those displayed on other platforms like investing.com or Yahoo Finance (Figure 2).
It's crucial to recognize that the historical transactions and prices are permanently altered. This means that PP's records of past transactions will no longer accurately reflect the actual transactions as documented in your paper files. Over time, this may complicate the reconstruction of a security's history.
A notable challenge arises when a split results in fractional shares, as seen in the case of Prosus' split announcement on September 14, 2023, with a ratio of 2.1796-for-1. In this scenario, 10 existing shares would be split into 21.796 shares. While PP can handle fractional shares, most brokers or banks cannot. Typically, they would adapt to this particular situation by issuing 21 new shares and providing compensation for the fractional share (0.796 shares in this case). Consequently, after the split, you'll need to record this compensation, which essentially involves executing a sell transaction of the fraction. Managing this process becomes notably more complex if you've made multiple purchases at different prices throughout the security's history.
An alternative method that keeps the historical prices and transactions intact is the following sell-buy-back procedure. At the split date (ex-date)
Let's apply this workflow to the PROSUS split (2.1796-for-1) from above. Assume that you have bought 5 shares on 2022-01-03 on XETRA for 68.60 EUR per share and another 5 on 2023-01-03 for 73.90 EUR. The closing price on XETRA on 2023-09-13 was 64.11 EUR.
Selling old shares:
Purchasing new shares:
Selling the remaining fraction:
In Figure 4 a comparison of the two methods (built-in function vs sell-buy-back) is made. As can be seen, the price range is 15 - 50 for the built-in split and 20 - 100 for the sell-buy-back method. The original buying prices are preserved in the latter case. Of course, the graph wouldn't look as nice for the Amazon 20-for-1 split.
Figure 4. Comparison of the two methods (Prosus example).
Please note that the security performance (top-right) is practically the same for built-in split vs sell-buy-back: IRR is respectively -6.05% vs -6.11%. The small difference is caused by the selling of the fraction (0.796 share) at a bad time (29.41 vs 29.54 EUR) in case of the sell-buy-back method.
The Trades Performance view gives additional info. Because we haven't solved the fractional share problem in the built-in split method, there is only one open trade: purchased 21.796 shares (2 x 10,898) and not sold yet. Remember that in your real bank account, you only have 21 shares. We haven't compensated for the fractional shares, which would be much more difficult in the built-in split method.
Let's compare with the sell-buy-back method. The open trade represents the 21 shares purchased on 2023-09-14. This trade has a positive performance (IRR = 1.03%). Prices have been increased since then. The previous period (the closed trade) however was negative (IRR= -8.40%). This puts the overall negative security performance of -6.11 in perspective. The IRR of the small closed trade of selling the 0.796 fraction is NaN (Not a Number). Because this trade is purchased and sold at the same price on the same day, the performance could not be calculated.
"},{"location":"how-to/requesting-new-importer/","title":"Troubleshooting / Request for a new PDF importer","text":"If Portfolio Performance doesn't have a PDF importer for your bank or broker, or for the specific type of transaction you need, you can request the development of this importer. Since Portfolio Performance developers don't have access to every bank or broker, you \u2014 as a user \u2014 must provide some sample PDF documents with real but anonymised examples of transactions with that specific bank or broker. The following text outlines all the necessary steps. You can also watch the accompanying video at the bottom.
Collect a PDF document of each transaction that you would like to import into your PP portfolio. Probably, you should provide an example of a buy, sell, and dividend transaction. Don't use PDFs that are converted to PDF from a browser or self-scanned paper notes but only the original documents from the bank or broker.
Convert these PDFs to text documents, one by one. Use the parser from PP, which can be found at File > Import > Debug: Extract Text from PDF (see Figure 1).
Figure 1. Menu File > Import.
You can use this sample (fictitious) PDF document for testing. The extracted text will appear in the textbox below the instructions (see Figure 2).
Replace (anonymise) personal information in the extracted text, such as your name, address, and account number. You can do this by double-clicking on a word, e.g., your name. The text will be selected and replaced with random characters.
Personal info can occur at multiple places within the document.
Leave all other information intact, especially amounts, dates, and security names. The following strings cannot be anonymised automatically: currencies (EUR, etc.), ISIN, and text groups containing the following characters: hyphen(-), period(.), comma(,), colon(:), apostrophe('), and slash(/). Do not delete or add anything manually.
Figure 2. Extracted text from testPDF.
Copy the extracted and anonymised text to the clipboard or save the file. You will need it later in the request form of the PP forum.
PDF Import from [your bank or broker]. Otherwise, post a reply in an existing thread, for example PDF import from SelfWealth. Add the extracted text for all transactions, one by one. Ensure that these text fragments are within triple quotes, so that it is formatted as code. If your transaction is in a foreign language, please provide some guidance about the translation of the used terms.Figure 1 illustrates a typical opening screen of Portfolio Performance, featuring two open portfolios: demo-portfolio-03.xml and the built-in kommer portfolio. The active portfolio is kommer, and its contents are currently displayed on the screen.
Figure 1. Typical opening screen of the Portfolio Performance program.
"},{"location":"how-to/user-interface/#components","title":"Components","text":"Figure 1 showcases the user interface elements present upon selecting the All Transactions view, which can be accessed either through the sidebar or the menu option View > All Transactions. In this example, the last Dividend transaction is selected, resulting in the display of a chart showing the historical quotes of Mercedes Benz Group in the information pane.
File, View, Transaction, Online, and Help. This top menu remains identical across all views. However, submenus can be dynamic. For instance, the Transfer between Accounts ... menu item is only available when there is more than one deposit account. An image of all menus and submenus expanded [available here] will provide you with a comprehensive understanding of the program's functionalities.The Sidebar serves as a convenient shortcut for accessing various views within the project. All available options can also be accessed through the View menu. It's important to note that the list in the sidebar mirrors the options available in the View menu, providing a one-to-one translation of the available views. The chosen view dictates the content displayed in the adjacent top and bottom panes. Next to the options Securities and Taxonomies, a very small (green) icon will let you add new elements.
To hide or show the sidebar, you can use the menu option View > Options > Hide/Show Sidebar. Alternatively, you can use the shortcut key Ctrl+K for a more efficient workflow. This allows you to quickly toggle the sidebar visibility as needed.
Dual-pane views: In PP, all views consist of dual-pane layouts, featuring a main pane and an information pane. When you select an item in the main pane, more detailed information about that item will be displayed in the information pane. If you prefer a single-pane view, you can hide the information pane (as described below), creating the illusion of a single pane view as in the Settings view.
All Transactions view. This is a list of all the transactions that you have made with your portfolio, such as deposits, withdrawals, buys, and sells. The default columns, such as date, type, security, ..., are initially visible. However, you have the flexibility to modify them using the Settings (cog) icon located in the top-right corner. Please, note that the data tools icons in the top-right corner are specific to this view and may not necessarily appear in other views.NVIDIA Corp in the main pane of Figure 1 will display the chart of this share in the information pane. You can hide/show the information pane with the menu View > Options > Hide/Show Information Pane. The shortcut key is Ctrl+L.The main pane in Figure 1 consists of a table. The first icon in the data tools lets you filter the rows in the tables, for example displaying only buy transactions. The second icon will let you export the table as displayed as a CSV-file. With the third icon (gear), you can show or hide columns in the table.
Click the column heading to sort the table in ascending (\u2227) or descending (\u2228) order based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column or double click to best fit. You can rename or hide a column with the context menu (right-click on the column header). Adding, removing or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). Clicking the Gear icon will show you all available columns.
"},{"location":"how-to/user-interface/#shortcuts","title":"Shortcuts","text":"Figure 1. Data sources Historical Quotes.
Finding accurate and up-to-date but free data sources for historical prices can be challenging. The list of data sources in PP includes the following options (see Figure 1): Alpha Vantage, EOD Historical Data, Finnhub, Leeway, Twelve Data, Portfolio Report, Quandl, and Yahoo Finance. The remaining alternatives are tailored for bitcoins and other statistical data.
Unfortunately, the terms of use for many of these options have become increasingly restrictive over time. They are included here mainly for compatibility reasons. In practical terms, only Portfolio Report and Yahoo Finance or JSON could be recommended for a typical portfolio.
Some specific use cases are discussed below. Many more are described in the Forum (in German).
"},{"location":"how-to/downloading-historical-prices/#very-old-historical-prices","title":"Very old historical prices","text":"Most financial services typically provide historical prices for a limited time period, such as the last year or since a specific recent date. However, if you happen to be one of the fortunate individuals who purchased Apple stock back in the 1980s, tracking your performance from the very beginning should be nice.
Note
Apple went first public on December 12, 1980, opening at $22 a share. The company was listed on the NASDAQ stock exchange under the ticker symbol AAPL. The share has since split five times, most recently in 2020, so on a split-adjusted basis the IPO share price was $.10.
Choosing Yahoo Finance as the Quote Feed provider will not get you very far: only 3 months of historical quotes are downloaded, starting from today.
Choosing the JSON Quote Provider allows you to specify the desired period for prices. For instance, the following URL attempts to download 30 years of data:
https://query1.finance.yahoo.com/v8/finance/chart/NVDA?interval=1d&range=30y
It's not possible to obtain 30 years, but you do receive data until 1991, or about 25 years of historical prices.
Normally, company websites contain that kind of information. Surprisingly, The Apple website doesn't offer the option to download historical data; you only can look up some prices. On the other hand, you can access dividend and split information. NASDAQ allows you to download a CSV file that extends only 10 years into the past.
Naturally, being a high-profile stock, more extensive data can be found on the web. For instance, Kaggle provides a CSV file of Apple Stock Prices from 1980-2021. You could download this file, import it into the historical prices, and have Yahoo Finance append the missing data.
Suppose that you want to track the Sustainable Health Care Fund (ISIN: lu0114720955) of the European based Fidelity Funds. Yahoo Finance has only the most recent price.
Investing.com does a bit of a better job and provides historical data from the launch of the fund (2000-09-01). You can download these data as CSV file; see section on Downloading historical prices > CSV File.
Of course the most extensive website for mutual funds is Morningstar You need to visit a European website for example https://www.morningstar.co.uk/uk/funds/snapshot/snapshot.aspx?id=F0GBR04EBS&tab=13
"},{"location":"how-to/downloading-historical-prices/#etf-tracker","title":"ETF tracker","text":""},{"location":"how-to/downloading-historical-prices/#bonds","title":"Bonds","text":""},{"location":"how-to/downloading-historical-prices/#gold","title":"Gold","text":""},{"location":"how-to/downloading-historical-prices/alpha-vantage/","title":"Alpha Vantage","text":"Alpha Vantage provides realtime and historical financial prices through data APIs and spreadsheets. You can request a free API key with lifetime access covering the majority of the datasets for up to 25 requests per day. Realtime quotes and some other resources however are premium.
The API documentation is very well written with many examples. These examples can be executed in the browser with a provided demo API-key. If you want to execute your own queries, you need the free API key.
Download the NVIDIA historical prices.
https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=NVDA&apikey=my_API_key
This will return some metadata and the last 100 historical quotes in the browser window. If you want all available historical prices, use the option \"outputsize=full\".
{\n \"Meta Data\": {\n \"1. Information\": \"Daily Prices (open, high, low, close) and Volumes\",\n \"2. Symbol\": \"NVDA\",\n \"3. Last Refreshed\": \"2024-01-25\",\n \"4. Output Size\": \"Compact\",\n \"5. Time Zone\": \"US/Eastern\"\n },\n \"Time Series (Daily)\": {\n \"2024-01-25\": {\n \"1. open\": \"623.5000\",\n \"2. high\": \"627.1900\",\n \"3. low\": \"608.5000\",\n \"4. close\": \"616.1700\",\n \"5. volume\": \"48277684\"\n },\n \"2024-01-24\": {\n \"1. open\": \"603.0400\",\n \"2. high\": \"628.4900\",\n \"3. low\": \"599.3800\",\n \"4. close\": \"613.6200\",\n \"5. volume\": \"55706870\"\n }\n }\n}\nNote
As of January 2024, Alpha Vantage changed some parameters and PP's JSON Quote Feed is no longer functional for this URL. The Path to Date and Path to Close JSON paths below result in an error; even if they are, according to the JSONPath Online Evaluatora valid JSON path.
$.[Time Series (Daily)].*~$.[Time Series (Daily)].[*].[4. close]In PP, importing historical prices from a CSV file is a straightforward process through the menu File > Import > CSV Files. Naturally, you would require a file containing the relevant quotes for this operation.
A csv file is a comma-separated values file, which is a text file that stores tabular data. Each row in the file represents a record, and each column represents a field. For example, a typical historical quotes CSV file will contain two columns (date and quote) and several rows, one for each date with its corresponding historical quote. A csv file can be opened and edited by spreadsheet software and easily imported into PP.
Each website may have a distinct approach for downloading a CSV file of the historical data. Typically, you need to navigate to the desired security and locate the download link on that webpage. Many websites require (free) registration for downloading, Yahoo Finance being an exception.
It's important to note that this method provides a snapshot of historical prices. To obtain the quotes of tomorrow, you should repeat the process. In practice, you need to combine this approach with one of the automatic quote download methods. Remember that you can keep the existing historical quotes in PP, even if you change the quote provider to automatic download. For example, in both scenarios below, after importing the CSV file, you can set the Quote Feed Provider to the Table on Website method for daily updates of historical prices.
"},{"location":"how-to/downloading-historical-prices/csv-file/#yahoo-finance","title":"Yahoo Finance","text":"After navigating to Yahoo Finance, you can enter the name \"NVIDIA\" in the Search box at the top of the screen (see Figure 1). Select the Historical Prices tab in the middle of the screen. From there, you can specify the Time Period and frequency before downloading a CSV file containing historical prices. Import this CSV file into Portfolio Performance using the menu File > Import > CSV Files, choosing the Historical Prices option and assign it to the correct security.
Figure 1. Webpage from finance.yahoo.com to download the historical prices of NVIDIA.
Hovering over the download link, you may have noticed the URL endpoint: https://query1.finance.yahoo.com/v7/finance/download/NVDA?period1=1674359406&period2=1705895406&interval=1d&events=history&includeAdjustedClose=true (see Figure 1 at the bottom of the image).
This is the request you send to the Yahoo server. It contains the ticker symbol of the security (NVDA), the time period expressed as Unix timestamps or the number of seconds that have elapsed since January 1, 1970, the frequency or interval (1d), the type of info you want (events=history), and the Adjusted Close price. The CSV file contains 7 columns: Date, Open, High, Low, Close, Volume, and Adj Close.
You can change this URL to obtain different results. For example, the following URL will retrieve the last three months of prices (same columns):
https://query1.finance.yahoo.com/v7/finance/download/NVDA?range=3mo&interval=1d
Investing.com is a comprehensive financial website providing real-time quotes, financial news, analysis, and tools for investors. You can localize its content for more than 30 countries including several European languages.
Clicking the Search box will display your recent searches and popular ones. You can enter the name, ticker, or ISIN of the security you're interested in. A graphical overview of the quote history (1 month) is presented. Click Historical Data to see the table. For downloading or changing the period, registration with your email address is required (free). All data are available, but there is a limit of 20 years that you can download in one pass.
The EODHD (End of Day Historical Data) website provides comprehensive coverage of all U.S. stocks, ETFs, and mutual funds from their inception. Additionally, the platform encompasses historical data for non-U.S. stock exchanges, primarily dating back to January 3, 2000.
A free API-token can be easily obtained by providing your email address. The token comes with a usage limit of 20 API requests per day. However, only historical quotes from the last year could be retrieved.
You can use the API-token with the automatic Quote Feed of PP from within PP works just fine. Enter the token in the Settings (Help > Preferences > API Keys) and choose EOD Historical Data as Quote Feed Provider.
If you have some special requirements, you can also use the JSON Quote Feed Provider (see API documentation for some use cases). For example, the following request will retrieve the Apple historical prices from the month January 2000.
Feed URL
https://eodhd.com/api/eod/AAPL?from=2000-01-01&to=2000-01-31&period=d&api_token=demo&fmt=json
Path to Date = $[*].date and Path to Close = $[*].close
Entering the URL in a browser will display the following (abbreviated) JSON.
[\n {\n \"date\": \"2000-12-01\",\n \"open\": 17.0016,\n \"high\": 17.5,\n \"low\": 16.8112,\n \"close\": 17.0632,\n \"adjusted_close\": 0.2583,\n \"volume\": 385705600\n },\n {\n \"date\": \"2000-12-04\",\n \"open\": 17.1864,\n \"high\": 17.1864,\n \"low\": 16.436,\n \"close\": 16.688,\n \"adjusted_close\": 0.2526,\n \"volume\": 371520800\n },\n {\n \"date\": \"2000-12-05\",\n \"open\": 16.94,\n \"high\": 17.4384,\n \"low\": 16.3744,\n \"close\": 17.0016,\n \"adjusted_close\": 0.2574,\n \"volume\": 613978400\n }\n]\nThis is an array of objects; accessed from the root with $[*]. The JSON path to the date is formed by $[*].date and to the closing price with $[*].close.
Financial web services commonly expose their data, e.g. historical prices, through an Application Programming Interface (API). To access these historical prices through the API, users can send HTTP requests to specific API endpoints, specifying parameters such as date ranges, stock symbols, and any other relevant filters. The API endpoint (=server) processes these requests, retrieves the requested historical price data from its database, and returns the information in a structured format, often JSON or XML.
For example, the following endpoint URL can be used to request the historical quotes of Apple between 2024-01-15 and 2024-01-17 from the eod historical data website.
https://eodhd.com/api/eod/AAPL?from=2024-01-15&to=2024-01-17&period=d&api_token=demo&fmt=json
As of January, 2024, the demo API token or key provided is still valid. If it ceases to function in the future, kindly apply for a free API key.
[\n {\n \"date\": \"2024-01-16\",\n \"open\": 182.16,\n \"high\": 184.26,\n \"low\": 180.93,\n \"close\": 183.63,\n \"adjusted_close\": 183.63,\n \"volume\": 65603000\n },\n {\n \"date\": \"2024-01-17\",\n \"open\": 181.27,\n \"high\": 182.93,\n \"low\": 180.3,\n \"close\": 182.68,\n \"adjusted_close\": 182.68,\n \"volume\": 47317400\n }\n]\nA JSON response can contain two kinds of elements: lists and objects. A list is an ordered collection of elements between [ ]. These can be accessed by their position. An object is an unordered collection of key-value pairs between { }. A key is a unique identifier for a value, and a value can be any type of data, such as a number, a string, a boolean, a list, or an object. A JSON response is a hierarchical structure, meaning that a list can contain other lists or objects, and an object can contain other lists or objects.
To access a specific value within this hierarchical structure, you need to specify the path from the root to the element. To access an element from a list, you need to use its index, which is a number that indicates its position in the list. The index starts from 0 for the first element. To access an element from an object, you need to use its key, which is a string that indicates its name in the object. The key is enclosed in double quotes \" \".
A query language such as JSONPath (used by PP) represents the root of the JSON response with a $ symbol. To separate the elements in the path, you need to use a dot. For example, to access the close price on the second day, you need to use the path $[1].close. This means that you start from the root $, then go to the second element in the list $[1], which is an object, then go to the value with the key \"close\" in the object $[1].close, which is a number.
You need this JSON path to complete PP's JSON Quote Feed Provider. Use the following parameters to retrieve the historical quotes (see also Figure 1). For an explanation of the meaning of different quote prices, please check Concepts > Historical Prices.
Figure 1. Server response from JSON Quote Feed Provider (EODHD).
https://eodhd.com/api/eod/AAPL?from=2024-01-15&to=2024-01-17&period=d&api_token=demo&fmt=json$[*].date$[*].close$[*].low$[*].high$[*].volumeLet's try a more complicated example. The following endpoint URL enables the retrieval of NVIDIA's two most recent daily quotes from Yahoo Finance (click the following link to see the result).
https://query1.finance.yahoo.com/v8/finance/chart/NVDA?interval=1d&range=5d
The response from the Yahoo server is a lengthy JSON document with all the historical quotes of the last 2 days. The output has been restructured and abbreviated for clarity (scroll down to see the quotes).
{\n \"chart\": {\n \"result\": [\n {\n \"meta\": {\n \"currency\": \"USD\", \n \"symbol\": \"NVDA\"\n },\n \"timestamp\": [1705415400, 1705501800],\n \"indicators\": {\n \"quote\": [\n {\n \"close\": [563.82, 560.53],\n \"open\": [550.17, 563.46],\n \"high\": [568.34, 564.71],\n \"low\": [549, 547.40],\n \"volume\": [44958000, 47439400]\n }\n ],\n \"adjclose\": [\n {\n \"adjclose\": [563.82, 560.53]\n }\n ]\n }\n }\n ],\n \"error\": null\n }\n}\nThe JSON response from above is an object, surrounded by { }. It contains meta data of the security, Unix timestamps from the two retrieved dates, and the different quote prices. You need a JSON path to retrieve the different values:
$.chart.error$.chart.result[0].meta. The result field is an array, even though there is only one element, probably because one can also ask data for multiple securities.$.chart.result[0].meta.symbol$.chart.result[0].timestamp[*]. The * serves as wildcard, facilitating the retrieval of all values.$.chart.result[0].timestamp[1]$.chart.result[0].indicators$.chart.result[0].indicators.quote[0]$.chart.result[0].indicators.quote[0].close$.chart.result[0].indicators.quote[0].close[0]If you want to practice, you can use the JSONPath Online Evaluator. Copy the JSON result from the URL endpoint into the input window. Another practical tool is the JSONPath Finder.
With the above information, it should be easy to provide the JSON Quote Feed provider of PP with the correct input.
Figure 2. JSON Quote Feed provider parameters.
For most services, one needs to register and obtain an API key, which is a unique identifier that authenticates the user and grants access to the service. While numerous financial services provide seemingly free API keys, their terms of use and long-term commitment often prove inadequate. PP has, for compatibility reasons, maintained several of these services in its list of Quote Feed providers; e.g. Alpha Vantage, eodhd, .... Although once considered excellent solutions, they have changed their offerings and are no longer as useful as free services. In practical terms, only Portfolio Report and Yahoo Finance can be recommended for a typical portfolio.
"},{"location":"how-to/downloading-historical-prices/morningstar/","title":"Import fund data from Morningstar","text":"Info
Best answer in forum from SimonFitz!
The website of Morningstar is quite famous for its extensive list of funds. With some magic, you can download historical data for specific funds from this website.
First go to the Chart page for the fund (or trust or EFT) on the Morningstar website; e.g. https://www.morningstar.co.uk/uk/. I will use the Baillie Gifford Positive Change Fund B Accumulation fund (ISIN GB00BYVGKV59) as an example.
Remove any other benchmarks etc. the are charted (this is not necessary, but makes things easier). Open your browser's \"developer tools\" which is F12 in Firefox & Edge and probably other browsers as well. Go to the \"Network\" tab and press the clear button which looks like a bin; again, not necessary but makes things easier. Now press the \"chart settings\" button just above the chart, click \"display options\", and then click the \"percentage\" button - this switches the chart to show the actual fund price, rather than a percentage change, and handily for our purposes causes the Morningstar website to request a link that we can use in Portfolio Performance with a bit of modification. That link should display in the \"network\" screen of the browser's developer tools, so now right-click on the entry that comes from the \"tools.morningstar.co.uk 44\" domain and is of type \"json\" and select the Copy->Copy URL option. The link should be
https://tools.morningstar.co.uk/api/rest.svc/timeseries_price/\nt92wz0sj7c?currencyId=GBP&idtype=Morningstar&frequency=daily&\nstartDate=2011-02-01&priceType=&outputType=COMPACTJSON&\nid=F00000ZB0M]2]0]FOGBR$$ALL&applyTrackRecordExtension=true\nhttps://tools.morningstar.co.uk/api/rest.svc/timeseries_price/\nt92wz0sj7c?currencyId=GBP&idtype=Morningstar&frequency=daily&\noutputType=JSON&startDate=2020-12-31&id=F00000ZB0M]2]0]\nFOGBR$$ALL\nYou can go to this link in your browser if you want to see the data. There are 4 options worth highlighting: frequency which will give you daily prices, outputType gives you a style of JSON that Portfolio Performance can parse, startDate lets you choose how far back to go, and id is the Morningstar reference for the security - so change that value for any other ones you want to use. The order of the options doesn't matter, but I find it easier to put the id at the end for when I'm setting up multiple securities.
Now in Portfolio Performance select JSON as the provider in the \"Historical Quotes\" tab of the security, and use the following values (see also figure 1):
Feed URL = the link just created\nPath to Date = $.TimeSeries.Security[*].HistoryDetail[*].EndDate\nPath to Close = $.TimeSeries.Security[*].HistoryDetail[*].Value\nFigure 1. Example of JSON provider for historical quotes
Always worth double-checking the displayed values against the Morningstar chart.
"},{"location":"how-to/downloading-historical-prices/portfolioreport/","title":"Using Portfolio Report","text":"Portfolio Report (PR) is an open-source project that works closely together with the Portfolio Performance (PP) app. Its primary goal is to enhance PP by providing master data for securities, including name, ISIN, WKN, and ticker symbol, as well as historical prices in various currencies.
PR allows you to look up information about securities, such as symbols, industries, and historical prices. Furthermore, it enables the creation of securities within PP from PR and the provision of historical prices for securities that already exist in PP.
"},{"location":"how-to/downloading-historical-prices/portfolioreport/#looking-up-information","title":"Looking up information","text":"When you navigate to the Portfolio Report website https://www.portfolio-report.net/, you will be presented with the following simple but efficient search form (see Figure 1).
Figure 1. Portfolio Report website.
In the first box of the search form, you can enter the ISIN, WKN, Symbol, or the full name of the security. Please refer to Basic concepts > PP-terminology for a definition of each term. Note that the use of wildcards, such as 'Amaz*', is not permitted for name searches. On the other hand, one word in the name suffices. For example, searching for Group will produce Cimic Group, NN Group, IBI Group, ... Searching for col will show Colruyt and Coca Cola Co.
Specifying the security type (share, fund, crypto, or bond) is not necessary, as the default search setting (blank or *) includes all categories.
When you retrieve the historical prices of a security, you have the option to select the currency in which the quotes are displayed with the Prices dropdown. Please note that the prices are always retrieved from the XETRA (Frankfurt) exchange market and that this price (in EUR) is converted through the exchange rates of the ECB.
Figure 2. Search Result
"},{"location":"how-to/downloading-historical-prices/portfolioreport/#creating-new-securities-in-pp-with-pr","title":"Creating new securities in PP with PR","text":"Utilize the Search box located at the top right (refer to Figure 3) to search for the desired security using its name, ISIN, or WKN.
If the security is in PR's database, the name (e.g Amazon.com Inc.), ISIN (US0231351067), and eventually WKN are displayed, together with a logo of the security (white arrow on blue background) and some extra information such as the trading market (XETRA), the currency (EUR), the ticker symbol on the specified trading market (AMZ), the country (United States of America (US)) and eventually the industry sector of the company. On multiple tabs (1, 2, 3, etc.), you can view the historical prices of the security. By default, only the 10 most recent prices are shown. However, using the drop-down menu on the right, you can adjust the number of prices displayed per page, with options ranging from 10, 30, 100, to 300.
Only securities that are traded on XETRA (Deutsche B\u00f6rse) are available within PR. Historical prices, specifically closing prices after the end of trading, are provided. Current prices, which are prices during trading on a marketplace, are not available.
Drag (= click, hold, and drop) the big blue button Add to Portfolio Performance upon the open window of PP. This is -of course- very easy if the two applications are placed next to each other on the screen (see Figure 2). Otherwise, you need to drag the button upon the PP icon in the taskbar.
Figure 3. Using Portfolio Report to create a security in Portfolio Performance.
You can verify the successful addition of the newly created security by checking the master data tab. A message stating Linked to Portfolio Report should be visible (see Figure 4). Additionally, on the Historical Quotes tab, the Quote Feed should be populated with the correct information.
It's important to note that due to the association with PR, the fields ISIN, and WKN become unmodifiable. If there is a need to update these fields, you must use the \"Unlink\" button to detach the security. Unfortunately, this also removes the Quote Feed of the Historical Quotes.
Figure 4. Master data and historical prices of newly created security.
It's also possible to link an existing security to PR; in particular to gain access to its quote feed of historical prices.
https://www.portfolio-report.net/securities/, followed by an identifier such as 8761e2dd-873a-4f1c-99c5-65939819eed9. This is the internal code that PR assigns to this security. You can find this URL in the address bar or at the bottom of the screen when hovering over the big blue button Add to Portfolio Performance.All Securities list; right-click and choose Link to Portfolio Report. Additionally, you must manually set Portfolio Report as the Quote Feed.Whenever PP initiates an update, such as through the menu Online > Update Quotes a request is sent to the PR website. Portfolio Report only receives information that is technically necessary, including:
This information is temporarily stored in log files on the server. The IP address is stored anonymously. In addition, no storage or evaluation of the data takes place.
The above info is based on a German article by developer Thomas. The source code could be retrieved at Github.
"},{"location":"how-to/downloading-historical-prices/table-website/","title":"Table on Website","text":"Stock exchanges like NASDAQ publish historical and real-time quotations for the shares traded on their platforms. Financial websites such as ariva.de offer a broader range. These historical prices are typically contained in a table with headings such as Date, Open, Close, ...
Scraping this information from the website should be possible. PP offers two methods: automatic and manual scraping.
"},{"location":"how-to/downloading-historical-prices/table-website/#automatic-scraping","title":"Automatic scraping","text":"ARIVA.DE is a German website that provides financial information and news, such as stock prices, market indices, commodities, currencies, funds, certificates, bonds, and more.
Figure 1. Historical prices on ARIVA.DE (English translation)
The URL for the webpage of Figure 1 is: https://www.ariva.de/nvidia-aktie/kurse/historische-kurse. Inputting this URL in the Feed URL field of Figure 2 will result in the quotes of the current month being downloaded. Using this method to append the historical quotes will only be effective when you regularly update the quotes by opening the portfolio or using the Online menu. Please note that you could select a different month, which could be a solution if you skipped one or several months.
Figure 2. Historical prices on ARIVA.DE (English translation)
For some reason, the Volume info isn't retrieved, and neither are the High & Low quote from the Bourserama URL: https://www.boursorama.com/cours/historique/NVDA. Please be aware that this link will provide monthly quotes, even though daily quotes are displayed on the screen.
The above mentioned method doesn't always work. Some websites use JavaScript or other technologies to build the tables on the clients machine. For example, at the Finanzen.net website, the default URL https://www.finanzen.net/historische-kurse/nvidia will only display the current day's quote, requiring input of the start and end date to view other periods. In such cases, manual scraping could be employed to capture this data.
Figure 3. Manual scraping.
Page Source from the context menu.Yahoo Finance provides a wide array of tools and financial resources, including historical and real-time stock quotes, interactive charts, and news updates that cover a diverse range of financial markets.
Figure 1. Yahoo Finance website with historical prices of Deutsche Telekom.
Click on the search box at the top and enter a (partial) name; for instance \"Deu\". Select the correct security, which in this case is Deutsche Telekom (DTE.DE). Navigate to the second menu and click on Historical Prices (see Figure 1). Subsequently, you can adjust the Time Period and Frequency as needed.
Note
The Yahoo (ticker) symbol is visible in parentheses after the security name, as illustrated in Figure 1. The ticker symbol is a series of letters representing a publicly traded company or financial instrument. For example, the ticker symbol for Apple Inc. is AAPL. When there could be confusion as with DTE (there are two companies DTE), the market place is added: DTE.DE to refer to Deutsche Telekom; a security traded on the Deutsche B\u00f6rse or DTE (default): DTE Energy Company, that it is traded on the NASDAQ.
You can download these historical prices as a CSV file by clicking the Download button. Please take note of the URL located at the bottom of Figure 1, as it grants access to this functionality. In the chapter on CSV file, we delve deeper into this topic.
Figure 2. Data sources Historical Quotes.
PP has a predefined Quote Feed provider for Yahoo Finance and Yahoo Finance (Adjusted Close). Please note that the Day's High, Day's Low, and Volume info is not retrieved in both cases.
To retrieve the historical quotes of Deutsche Telekom, enter the ticker symbol in the Security Master Data (see Figure 1, top left) and select Yahoo Finance as the Quote Feed Provider within the Historical Quotes tab. A list of 30 quotes, starting from today will appear.
In the background, PP initiates the following query (becomes visible in the event of an error, for example with ticker symbol DTE.XX).
https://query1.finance.yahoo.com/v8/finance/chart/DTE.DE?range=3mo&interval=1d
If you need a different amount of historical data, data from an alternative period, or you want to include the High, Low, and Volume fields, you can initiate the query manually. This functionality is available through the JSON Quote Feed Provider.
"},{"location":"reference/","title":"Reference Manual","text":"The Reference manual is structured around the User Interface (UI) of the program, probably the easiest and quickest way for users, developers, or contributors to find relevant information. Figure 1 illustrates a typical opening screen of Portfolio Performance, featuring two open portfolios: demo-portfolio-03.xml and the built-in kommer portfolio.
The structure of the Reference part of the manual is mirrored from the menu with top-level sections named File, View, Transaction, ... As can be seen in the sidebar of this page or from the hamburger menu if you are reading this from a small/mobile screen, the File section is subdivided into pages such as New, Save, Import, ...
Figure 1. Typical opening screen of the Portfolio Performance program.
An image of all menus and submenus expanded is [available here].
"},{"location":"reference/online/","title":"Menu Online","text":"To assess the performance of your portfolio, it's essential to have historical prices or quotes for all securities. You can input these manually or, more conveniently, obtain them through a Quote Feed. This could be in the form of a table on a website or another online data source. With the menu Online these historical prices could be updated.
For all securities that are connected to an online quote feed provider, this command will trigger a request to the online service for the latest quotes ranging from the first historical quote to the present day.
Quotes that were previously downloaded but subsequently deleted will be reinstated. However, quotes that have been manually altered after online download or those in the historical prices table that are not available online (e.g., quotes in the distant past) will remain unchanged during this operation.
A message xxx operations remaining will appear briefly in the left bottom corner of the window, indicating the progress of the updating process. This process is conducted in the background and does not affect other operations.
Securities could be set to active or inactive in the Security Master Data tab of the Securities Attributes panel.
Figure 1. Inactive setting in the Security Master Data tab.
This command will update only the active securities.
"},{"location":"reference/online/#update-quotes-selected-security","title":"Update quotes (selected security)","text":"In a table view such as All Securities, one can select one or more securities. For a consecutive selection, click the first row, press Shift, and click the last row. For a non-consecutive selection, use the Ctrl key.
Even though the menu mentions \"selected security\", the update will be performed on all selected securities.
"},{"location":"reference/file/currency/","title":"File \u203a Currency","text":"Figure 1. Currency Picker.
The base currency of the portfolio is established at the time of creation. In reports such as the Statement of Assets, some monetary values are preceded by a currency abbreviation (e.g., USD), while others are not. By default, only monetary values that are not expressed in the base currency are prefixed with the currency abbreviation.
Note
To display the currency code for all monetary values, navigate to the menu Help > Preferences > Presentation and enable the Always display currency code for monetary values option. The change will take effect upon the next startup of PP, and all values will be prefixed with the currency code.
To add or change a base currency, use the menu File > Currency. In Figure 1, the original base currency at the time of portfolio creation was EUR. An alternative base currency, USD, has already been added but is not yet set as the base currency (indicated by the unchecked box). To add AUD as another base currency option:
Once added, you can set AUD as the base currency by checking the box next to it. This will change the base currency for the portfolio and may affect how monetary values are displayed in reports and other parts of the application.
In Figure 2, share-1 and bond-1 are European stocks traded in EUR, while share-2 is an American stock expressed in USD. The Statement of Assets report is generated twice: once with the base currency set to EUR (left panel) and once with the base currency set to USD (right panel). Please note that the quote price remains the same in both panels. However, the market value differs due to the different base currencies.
For example, the total market value in the left panel is 20,833.05 EUR, while in the right panel, it is 22,591.35 USD. According to the Currency Converter, the exchange rate on 2024-03-20 is 1.0844 EUR/USD. Using this exchange rate, you can confirm the conversion: 20,833.05 EUR x 1.0844 = 22,591.35 USD.
Figure 2. The Statement of Assets in two base currencies.
"},{"location":"reference/file/export/","title":"File > Export","text":"The menu File > Export has only two options: CSV files (comma-separated values) and Portfolio Performance XML.
Selecting the \"CSV Files\" option will reveal an additional panel for specifying the type of information to be exported. The exported CSV file utilizes the UTF-8 encoding, a universal and widely used method for converting text to bytes. This encoding can represent any character in the Unicode standard, encompassing over 140,000 characters from various languages and scripts. The importance of the encoding becomes apparent when importing the CSV file. Most programs, such as Excel, can accurately recognize the encoding. However, for PP's Import function, it's crucial to choose the correct encoding.
Figure 1. Export CSV file dialog from demo-portfolio-04.xml.
As you can see, there are two deposit accounts (EUR and USD) and one security account (Broker-A) in Figure 1. The USD deposit account is used for share-3, which is expressed in USD.
If you have securities in a different currency than the portfolio base currency such as in Figure 1, you can convert the historical quotes to the base currency by checking Convert all quotes of securities to portfolio base currency. Please note that this option does not convert the purchase prices, fees, ... that might be expressed in another currency.
For each Deposit account, you can export all transactions (buy, sell, deposit, ...). For each transaction the following fields are exported: Date, Type, Value, Transaction Currency, Taxes, Shares, ISIN, WKN, Ticker Symbol, Security Name, and Note.
It's not possible to select multiple accounts.
"},{"location":"reference/file/export/#securities-account-transactions","title":"Securities Account Transactions","text":"Only the Buy and Sell transactions are exported from the securities account; not dividends. The following fields are exported: Date, Type, Value, Transaction Currency, Gross Amount Currency, Gross Amount, Exchange Rate, Fees, Taxes, Shares, ISIN, WKN, Ticker Symbol, Security Name, and Note. Unfortunately, the date contains the time of day of the transaction (e.g. 2021-01-15T00:00), which makes it a text field in Excel. You can create a custom date format in Excel to handle this kind of dates.
Master Data: For each security in the portfolio, the following fields are exported: ISIN, WKN, Ticker Symbol, Security Name, Currency, and Note.
All historical quotes are organized with a dedicated column for each security, using the ticker symbol as the column heading. Each date containing a historical quote corresponds to a row with the respective price added in the relevant column. In cases where a security has no recorded price for a particular date, the corresponding cell is left empty.
All transactions and dividends: with this option, you can export all buy, sell, and dividend transactions. The exported fields are (in German): Datum, ISIN, Name, Typ, Transaktion, Preis, Anzahl, Kommission, and Steuern. The date format does not contain time of day info.
VINIS-App: The VINIS app is a mobile application for iPhone and Apple Watch that helps users set, track, and achieve their financial goals. The app allows users to create custom goals and key figures, and to link them to external data sources such as Google Sheets, Excel, or Numbers documents. The app also provides visualization, prediction, and reminder features to help users monitor their progress. The following fields are exported: Funds sum, Securities purchase price, Securities market price, Total assets purchase price, Total assets market price, Earnings current year, Earnings last year, Earnings total, Capital gains current year, Capital gains last year, Capital gains total, Realized capital gains current year, Realized capital gains last year, Realized capital gains total.
Similar to the previous description of \"All historical quotes,\" the export includes all available prices for the selected security. The exported data comprises two fields: Date (without the time of day) and Quote.
This command is identical to the File > Save command or the File > Save as menu command with option XML.
With the File > New menu you can create the different assets PP can manage.
Figure 1. File > New submenu.
"},{"location":"reference/file/new/#portfolio-file","title":"Portfolio (File)","text":"The option File > New > File initiates a wizard for creating a new portfolio. Within the wizard, you need to set the base currency of the portfolio, create a security and deposit account (mandatory), add additional deposit accounts, and include securities and taxonomies (optional). A detailed explanation of the wizard can be found in Getting Started > Creating a Portfolio File.
The menu option File > New > Security is self-explaining: it allows you to create a new security. This can also be done at other locations within the UI; for example as part of the portfolio creation wizard (see above), or with the little green icon next to Securities in the sidebar or in the All Securitiesview.
Figure 2. File > New > Security menu.
You can either choose to create a new empty instrument (e.g. security) or to search for an existing one. You can type (part of) the security name in the search box. Choosing from the drop-down box All, you can search for shares or bonds or both. After clicking the Search button, the list below will be populated with possible target instruments. The following fields are displayed for each instrument and will be used upon selecting the security: Name, Symbol, ISIN, WKN, Type, Exchange, Currency, and Source (see Basic concepts > PP-terminology for a definition of each term).
Once the correct security has been selected, proceed to the next step by clicking on the Apply button. Some information such as name, symbol and historical quotes will already be filled in, based on the selected data source. You should always check the info, especially the stock market. All the info can be changed; even the name. Alternatively, one may initiate the process with an empty security (see Figure 3) and manually input the required information.
Figure 3. Input panel for the creation of a security.
While only the name is obligatory, there are several other fields that need attention. They are grouped into 5 sub panels, marked with a yellow line in Figure 3.
This panel is entirely visible in Figure 3. The currency field must correspond to the currency in which the security is traded. Once transactions are recorded with this security, the currency cannot be changed. Clicking the currency box will reveal a drop-down with all available currencies.
The fields ISIN, Symbol, and WKN have been explained earlier. The symbol field is particularly crucial as it is utilized in the Quote Feed for Historical Quotes (further details below).
The Calendar dropdown enables you to choose a specific stock market calendar, such as Euronext, London Stock Exchange, New York Stock Exchange, etc. These calendars contain information about trading days, (bank) holidays, affecting some calculations, the display of price gaps, and the execution of savings plans. A more detailed description is available in the Help > Preferences > Calendar menu.
A security can be set to active or inactive. If set to inactive, the security will not appear in buy or sell dialogs, and historical prices will not be updated automatically.
At the bottom of Figure 3, you can add a personal note for this security.
Besides the attributes from the Security Master Data, you can use other attributes; for example a logo. These additional attributes can be added to tables such as Reports > Performance > Securities. The values of these attributes must be entered manually and cannot be used in calculations.
Additional attributes are defined in (left) Sidebar > General Data > Settings > Attributes : Securities (at the bottom). More info here.
A taxonomy serves as a classification system for your securities. Taxonomies typically group securities based on shared characteristics such as industry, sector, geographical region, market capitalization, or asset class. For instance, the existing Asset Classes taxonomy allows you to classify your securities into categories such as Cash, Equity, Debt, Real Estate, or Commodity.
When you first open the Taxonomies panel (shown in Figure 4) in a new portfolio, it will be empty. To start using taxonomies, you'll need to create one or more for your portfolio. In Figure 4, four taxonomies are visible: Asset Classes, Asset Allocation, Industries (GICS, Sectors), and Regions. These taxonomies also appear under the View menu.
Figure 4. Taxonomies panel.
To assign a security to a taxonomy category, click the New Category button below the taxonomy. A drop-down menu will appear, listing all possible categories along with a weight input box. You can assign a security to multiple taxonomies. It's also possible to assign multiple categories of one taxonomy, as long as the combined weight doesn't exceed 100%. If the weight is not displayed next to the category (see Figure 4), then it is set to 100%. Click the minus button (-) next to the category to remove it from the taxonomy assignment. The above actions can also be done (more easily) in the Taxonomies View.
For detailed instructions on how to create, manage, and use taxonomies, see section Reference > View > Taxonomies in the manual.
"},{"location":"reference/file/new/#historical-quotes","title":"Historical Quotes","text":"For evaluating your portfolio, you need the current & historical prices of the security. In this panel (see Figure 4) you can set the data source of the Quote Feed. As Provider, you can choose between several alternatives: Yahoo Finance, Alpha Vantage, Quandl, ... (see Figure 5). You can even refer to a webpage (e.g. from an investor site) that contains these historical data; an example is given in Import fund data from Morningstar. Or you can create them yourself and import the quotes from a csv-file.
Figure 5. Historical quotes panel.
Depending upon the chosen provider, you may need to input additional information. If the provider is a website, you need to specify a URL. If the provider covers more than one Exchange, you need to select the correct one.
Figure 6. Historical quotes panel.
Downloading historical prices for large-cap (big companies) stocks is relatively straightforward. However, obtaining data for less common stocks, mutual funds, bonds, bitcoin, etc., can sometimes be more challenging. We explore these topics in depth in Downloading Historical Prices in the how-to section.
Note
An alternative, but convenient method for securities listed on XETRA is to utilize the Portfolio Report website. See how-to > Using Portfolio Report for more info.
"},{"location":"reference/file/new/#latest-quote","title":"Latest Quote","text":"The Latest Quote panel is very similar to the Historical Quotes panel. Here, you can configure values for real-time values such as Latest Price, Latest Trade, Day's High, Day's Low, and Volume.
"},{"location":"reference/file/new/#cryptocurrency","title":"Cryptocurrency","text":"Figure 7. Create new crypotocurrency.
A cryptocurrency is a digital asset based on a blockchain system. There are thousands of different cryptocurrencies on the market, the best known of which is Bitcoin. Unlike traditional assets, there is no tangible or intangible value backing a cryptocurrency. Instead, its value is determined solely by market demand and what investors are willing to pay for it.
In PP, cryptocurrencies are treated like any other security, such as stocks. You can buy and sell cryptocurrencies, but you cannot have a deposit account denominated in a cryptocurrency.
The popular CoinGecko website is the source of the cryptocurrencies, listed in Figure 7. You can use the Search box to look-up a specific cryptocurrency in this very long list. If the crypto you need is not listed, you should create a new empty security; remember cryptos are no different from securities in PP. However, you will need to find a way to retrieve historical price data for this new crypto security.
"},{"location":"reference/file/new/#exchange-rate","title":"Exchange Rate","text":"Figure 8. Create new exchange rate.
PP uses exchange rates from the European Central Bank. You can find the list of about 40 available exchange rates under the View > Currencies menu. In some rare cases, you may require an exchange rate that is not included in the available list.
To create a custom exchange rate, use the File > New > Exchange rate menu. You will need to provide a quote provider, such as a JSON source or webpage, for the currency you want to add. Once you've created the custom exchange rate, it will be added to the currencies list with the name Security based exchange rate provider in the Provider column.
Figure 9. Create new consumer price index.
The Harmonised Indices of Consumer Prices (HICP) are retrieved from the Eurostat website and represent the monthly inflation rate of consumer goods and services purchased by households in the euro area. The HICP is \"harmonised\" because all countries in the European Union use the same methodology to calculate it. The baseline of 100 is set for the year 2015.
After selecting the country, a security named [name of country] (HICP) is created with a First of month calendar and the Eurostat - Harmonised Indices of Consumer Prices (HICP) as the Quote Feed provider.
Being an index, however, these data series aren't normally used as a regular security (buy or sell). They can serve as a benchmark for your other investments.
"},{"location":"reference/file/new/#taxonomy","title":"Taxonomy","text":"To create a new taxonomy, select File > New > Taxonomy from the menu. This will open the New Taxonomy input box, where you can name the taxonomy and choose whether to create a new empty structure or use a predefined template, such as Asset Classes or Industries (GICS). For more information on creating and managing taxonomies, see the section on Taxonomies in the Reference manual.
Figure 10. Two watchlists.
A watchlist is a manual grouping of securities. To create a new list, navigate to File > New > Watchlist in the menu. Once created, it will appear under the All Securities heading. You can create an unlimited number of watchlists in PP. For example, Figure 6 shows two watchlists named Asia and Indices, with the latter containing four securities indices such as the DAX and Dow Jones.
Using the context menu (right-click on a list), you can rename, delete, or move (up) the watchlist (refer to Figure 6). Adding securities to the watchlist is a manual process done by dragging one or more securities from the All Securities view to the watchlist. To remove a security from the watchlist, right-click the security and choose 'Remove from Your_Watchlist'.
Watchlists inherit the view from All Securities. Changing the view in one watchlist will also change the view in all other watchlists, including the All Securities view.
Figure 1. File format picker.
With the menu File > Save, you can save your portfolio, using its existing name and file format without any further interference. If the file hasn't been saved before, a Pick the file format dialog box will appear (see Figure 1), presenting three choices. These options will be explained in the subsequent section. After selecting the file format, you can proceed as if you had started with the File > Save As option from the menu.
The File > Save As option offers the three file format choices as submenus. In the subsequent step, you can input the file name and designate the file location. This option allows you to create a new copy of a previously saved file in a different file format and/or with a different name, leaving the original file intact.
If more than one portfolio is open, the aforementioned commands will solely save the active portfolio. Utilize the Save All option to save all open files simultaneously.
Figure 2. Dialog after closing app with two updated portfolios.
Closing a portfolio that has been modified since opening will trigger a dialog 'xxx.xml is modified. Do you want to save the changes?. Closing the application with multiple updated projects will prompt the dialog from Figure 2.
All data of your portfolio is stored in one XML-file (eXtensible Markup Language). This is a human-readable file format. For example, the following xml-file test.xml is a very simple portfolio with one security (share-1) and two transactions (one deposit and one buy). You can view the xml-content by opening this file with a text editor (e.g. Notepad++). Here's a brief description of the main elements:
<securities>: Contains information about securities, including details such as UUID, name, currency code, ticker symbol, feed, historical prices, and attributes. <prices>: Contains historical price information for a security. <latest>: Provides the latest details for a security, including high, low, and volume.
<accounts>: Contains details about client accounts, including UUID, name, currency code, and transactions.
<transactions>: Represents financial transactions within an account, including details such as UUID, date, currency code, amount, and type.
<portfolios>: Contains references to portfolios associated with accounts.
<dashboards>: Contains information about client dashboards, including name, configuration, columns, and widgets.
<properties>: Holds client-specific properties, such as security chart details.
<settings>: Contains various settings, including bookmarks and attribute types.<configurationSets>: Stores configuration sets with specific data.Below you can see the xml code for the buying transaction in Figure 3.
Figure 3. Example of a buying transaction.
This single buying transaction is represented with the following XML code.
<transactions>\n <portfolio-transaction>\n <uuid>72bf2b32-60a5-4c99-ba6d-d3ab695624e5</uuid>\n <date>2023-09-10T00:00</date>\n <currencyCode>USD</currencyCode>\n <amount>174635</amount>\n <security reference=\"../../../../../../../../../securities/security\"/>\n <crossEntry class=\"buysell\" reference=\"../../../..\"/>\n <shares>500000000</shares>\n <note>First buy on advice of ...</note>\n <units>\n <unit type=\"FEE\">\n <amount currency=\"USD\" amount=\"3000\"/>\n </unit>\n <unit type=\"TAX\">\n <amount currency=\"USD\" amount=\"4500\"/>\n </unit>\n </units>\n <updatedAt>2023-09-10T18:43:28.135529700Z</updatedAt>\n <type>BUY</type>\n </portfolio-transaction>\n</transactions>\nThe PortfolioPerformance mobile app, introduced in February 2024, does not support the XML file format.
"},{"location":"reference/file/save/#password-protected-aes-256","title":"Password protected (AES-256)","text":"AES-256 encryption is a method of securing your data by converting it into a code that can only be accessed with a unique key. This encryption technique uses a 256-bit key, which is a string of 256 zeros and ones, to encrypt and decrypt the data. When data is encrypted using AES-256, it is transformed into a random sequence of characters that is unreadable without the key. In order to generate this key, PP needs a password that is at least 6 characters. However, a password that is longer and more complex will have more randomness and unpredictability, which means it is harder to guess.
Figure 4. Saving a portfolio with AES-256 encryption needs a password.
"},{"location":"reference/file/save/#binary","title":"Binary","text":"An XML file is a human-readable file format (see above for an example). A binary format is more compact and efficient and therefore a file can be opened and saved much faster. However, it is no longer human-readable. More info is available in Issue #2363; watch for example the comparison in opening speed of a 720 securities & 1.3 MB historical prices project.
Distinguishing a password-protected or binary file from a regular XML file one is possible by examining the file extension. Encrypted and binary files have the extension .portfolio instead of XML.
"},{"location":"reference/file/import/","title":"Importing documents","text":"In PP you can enter your data (buy, sell, dividends, historical quotes, \u2026 ) manually but you can also import this info from a CSV file (comma-separated values) or from a PDF document. Figure 1 displays the expanded File > Import menu.
There are two primary data sources: PDF documents and CSV files (comma-separated values). Some brokers or banks may present this information in a proprietary format. Templates for major banks or brokers are available.
Figure 1. Menu File > Import.
"},{"location":"reference/file/import/csv-import/","title":"Importing a CSV file","text":"PP employs a wizard to lead you through the import process, consisting of three steps. At each step, you are required to furnish additional information.
Step 1. Start with the menu File > Import > CSV files (comma-separated values), navigate to the correct folder and select the appropriate CSV file. Only files with the extension CSV are displayed.
A CSV file is simply a text file. The first line contains the names of the fields (columns); separated by a marker such as a comma. The second and following lines contain the data, also separated by a marker. The number and type of fields the file should contain, depend on the type of import. The names in the heading can be freely chosen, although they should match PP's internal usage, as it simplifies the mapping process (associating each column with its corresponding field in PP). The printout of a CSV file in Table 1 (see below) comprises two fields or columns and four lines of data that could be utilized for importing historical prices.
Figure 1. Import types.
In step 2 of the wizard, you need to select the appropriate import type or template by clicking on the drop down box (see Figure 3). PP distinguishes between 5 types of import: Account Transactions, Portfolio Transactions, Securities, Historical Quotes, and Securities Account (see Figure 1). These templates are discussed in detail below. You also need to decide about the following options.
UTF-8 or Windows-1250. -> 'Field' in the second row of the output; otherwise, a message Double click here will appear (see Figure 3). To associate a column with an internal PP field, double-click on the second line. You can then choose from the available fields. If you don't want to associate a field, select the --- option. PP will then ignore this column. To change the format of a column, e.g. Date format of a date, double-click on the name in the second line.Figure 2. Saving the mapping configuration.
Built-in configurations will be displayed, such as comDirect, Consorsbank, etc. (see Figure 3). Using the option Save current configuration will save your current mapping configuration as a custom template. This template will be available under User-specific Configurations, for example, test (Account Transactions) (see Figure 2). You can delete, export, and import configurations. The export function uses a JSON format.Step 3: set additional info, depending on the import type such as accounts and check the preview of the import process. Step 3 differs depending on the selected type of import. For the historical quotes import type, only the share name should be additional selected. For the other types, you need to set the security and cash account.
Note
The cash and security account could be set globally for all import rows of the CSV file through the top panel; see for example Figure 6. You can also provide this information as part of the CSV file (include a column Cash account and Securities account). Or you can set the accounts through the context menu. Right-click on a row in the table preview and choose the appropriate account.
"},{"location":"reference/file/import/csv-import/#1-historical-quotes-import","title":"1. Historical Quotes import","text":"To import historical quotes for a security, you only need two columns in the CSV file: one for the date and another for the corresponding quote. These are required fields. No optional fields are allowed. The security's name must be provided in a separate step. You cannot proceed to the next step if any of the required fields are missing.
Table 1: Source data for the import of Historical Quotes.
Date; Price\n2024-01-09; 22,51\n2024-01-08; 22,54\n2024-01-05; 22,43\n2024-01-04; 22,46\nYYYY-MM-DD. By double-clicking on the second row of the output panel; e.g. -> 'Date', you can set the correct date format. January 7th and 6th are not included as these are weekend days (although they could be). In this case, the price information uses a comma as a decimal separator, which is standard in Europe. Therefore, a semicolon (;) is used to separate the fields. The file is saved in Excel with UTF-8 encoding. The heading labels are Date and Price. Figure 3. Importing Historical Quotes (step 2).
In Figure 3, the Next and Finish buttons are greyed out because not all necessary information is available. The message at the top, \"Unmapped required field(s): Quote,\" provides a clue. For this type of import, two fields are required: Date and Quote. However, the CSV file uses the headings Date and Price. The field Price should be mapped to the internal Quote field. Double-click on the column and select the appropriate mapping field, e.g. Quote. The Next and Finish buttons will then become available.
In step 3 of the wizard, you can select the security that the prices will be added to. If the chosen security already has some historical prices, the quotes will be added (no duplicates).
Figure 4. Importing Historical Quotes (step 3).
"},{"location":"reference/file/import/csv-import/#2-securities-import","title":"2. Securities import","text":"Use this type to create new securities from a CSV file. There are no required fields. The optional fields include Ticker Symbol, Security Name, WKN, ISIN, Currency, Date of Quote, Note, and Quote. It is evident that at least one of the first four fields should be mapped. Refer to the glossary for the meaning of these terms. See Table 2 for an example of the CSV-file.
Table 2: Source data for the import of Securities.
Ticker Symbol; ISIN; Security Name ;Currency\nBAS; DE000BASF111; BASF; EUR\nNVDA; ; NVIDIA; USD\nFigure 5. Importing securities (Step 2).
In step 3 (below), you can observe that the status of both securities contains a green check mark, indicating that the import will be successful. If the securities should already exist, nothing will appear. Click Finish.
Figure 6. Importing securities (Step 3).
The securities are now created and appear in the All Securities list. Although the cash and security account options are provided in Figure 6, it does not make sense to add or change the cash or security account here. The securities are only created in the All Securities list, no transactions are yet in place. Please note that several other fields such as Calendar, Additional Attributes, and Taxonomies cannot be added through CSV-import. The Quote Feed for the Historical Prices could partially be added in the following step (see Figure 7).
Figure 7. Importing securities (Step 4).
After the securities are created, an additional step allows you to search for a suitable quote feed. This can also be performed manually by right-clicking on a security and choosing Quotes > Search for providers of historical prices...
Only securities listed on XETRA (Deutsche B\u00f6rse) and analyzed by the Portfolio Report are eligible for an automatic Quote Feed. The BASF security in Figure 7 meets these criteria and can therefore receive an automatic quote feed. However, the NVIDIA security is not listed on XETRA in USD, so automatic quotes should be obtained through another candidate provider e.g. Yahoo Finance.
"},{"location":"reference/file/import/csv-import/#3-securities-account-import","title":"3. Securities Account import","text":"With this import type, you can create a new security (see above), while adding at the same time the first Buy transaction. The required fields are Shares, and Value. The optional fields are Ticker, Symbol, ISIN, WKN, Time, Currency, Note, Date of Quote, Securities Account, Cash Account, Quote, Date of Value, and Security Name. The following CSV file will be imported in Figure 8.
Ticker Symbol; ISIN; Security Name; Currency; shares; value\nBAS; DE000BASF111; BASF; EUR; 20; 900\nNVDA; ; NVIDIA; USD; 10; 5450\nFigure 8. Importing securities (Step 4).
"},{"location":"reference/file/import/csv-import/#4-account-transactions-import","title":"4. Account Transactions import","text":"The Account Transactions import type will be used to register transactions on a deposit or cash account such as deposit, removal, interest, ... It is equivalent with manual recording a transaction with the menu Transaction (third group). The required fields are Date, and Value.
Important
The Account Transactions and Portfolio Transactions import types are quite similar. Internally, an account transaction is reserved to work with cash accounts and their transactions such as deposits. A portfolio transaction works with instruments and their transactions: buy, sell, delivery, ... A buy/sell transaction however has both components: something is added/removed from the securities account and some money is deducted/added to the cash account. In most cases, both types could be used interchangeably.
Use Account Transactions type for deposit, removal, ... and Portfolio Transactions type for buy, sell, ...
The required fields are Date, and Value. Optional fields are Type, Transaction Currency, Security Name, Shares, Securities Account, Exchange Rate, Gross Amount, Currency Gross Amount, Ticker Symbol, Taxes, Note, Cash Account, Fees, ISIN, WKN, Offset Account, and Time.
Acceptable values for the field Type are Deposit, Removal, Buy, Sell, Dividend, Interest, Interest Charge, Fees, Fees Refund, Taxes, Tax Refund, Transfer (Inbound), Transfer (Outbound), Delivery (Inbound), and Delivery (Outbound). The default value for Type is Deposit.
If the Cash and Securities account are not provided in the CSV file, the value from the top panel is used. It's important to note that Fees and Taxes can be included as part of the Buy or Sell transaction through a dedicated column in the CSV file. In this case, the taxes and fees are subtracted from the total value field (Value = Gross Amount + Taxes + Fees). Alternatively, a separate transaction with the type Fees or Taxes can be created, and the amount is then specified in the Value column. In this case, the fees and taxes are added to the value.
Figure 9. Importing account transactions - content CSV file
Figure 9 displays the content of a sample CSV file. Four transactions are described. Note that the Cash account of the first transaction is not provided. The default account from the top panel is taken in that case.
Figure 10. Importing account transactions - step 2.
Figure 11. Importing account transactions - step 3.
"},{"location":"reference/file/import/csv-import/#dividend-transaction","title":"Dividend transaction","text":"It is noteworthy to address the dividend transaction separately, as it presents unique challenges, particularly when dealing with foreign dividends. For instance, complications may arise when dividends are paid in USD but deposited into a cash account denominated in EUR.
To illustrate, let us assume that a USD dividend of 5 USD is paid for three shares, with a hypothetical exchange rate of 0.5 EUR-for-1-USD. For this example, we will use the cash account Broker-A (EUR) denominated in EUR for the deposit.
In this example, the CSV file contains columns for the date, type of transaction (in this case, a dividend), the security name (NVIDIA), the number of shares, the currency in which the dividend was paid (USD), the gross amount of the dividend, the applicable exchange rate, the cash account into which the dividend was deposited broker-A (EUR), and the converted value of the total dividend in EUR.
The raw CSV-file looks like:
Date;Type;Security Name;Shares; Currency Gross Amount; Gross Amount; Exchange Rate; Cash Account; Value\n2024-01-13; Dividend; NVIDIA; 3; USD; 15; 0,5; broker-A (EUR); 7,5\nFigure 12 illustrates the initial step in the import wizard process. As the CSV file incorporates the accurately spelled field names, no mapping adjustments are required. It is crucial to take note of number formatting of the various fields, particularly the exchange rate field, which will likely always contain a decimal separator (comma or point). Also check the date format; YYYY-MM-DD, or DD/MM/YY, or ....
In this instance, we are receiving a dividend payment for three shares, with a Gross Amount of 15 USD. Consequently, the dividend value should be 5 USD per share (see Figure 13). Given the Exchange Rate of 0.5 EUR-for-1-USD, the net Value of the dividend, once deposited into the broker-A (EUR) account, should amount to 7.5 EUR.
Figure 12. Step 1 of the Import wizard: type dividends.
The necessity of the Gross Amount field is not apparent, particularly as it is not utilized in the subsequent section. However, the Portfolio Performance (PP) software verifies the values within this field, ensuring that the following calculation holds true: Gross Amount multiplied by the Exchange Rate equals the Value. If the numbers do not correspond, an error message will be displayed, preventing progression to the next step.
Upon importing the CSV file detailed above and selecting the Account Transactions type, the dividend transaction will be generated as depicted in Figure 13.
Important
Regrettably, the software does not currently support the inclusion of Fees and Taxes, either in the foreign or domestic currency.
Figure 13. Result of import from above.
"},{"location":"reference/file/import/csv-import/#5-portfolio-transactions-import","title":"5. Portfolio Transactions import","text":"Important
If you have transactions with securities in different currencies, it is good practice to explicitly add the Security Account and Cash Account to the CSV-file. As the Date is a required field, pay attention to the default date format (YYYY-MM-DD).
This type of import requires three fields: Shares, Date, Value. The optional fields are the same as above; except that the optional Offset Account field is replaced with Offset Securities Account. The selection of required fields may seem somewhat arbitrary. For transactions like buy and sell, a security identification is essential (such as name, ISIN, etc.). However, for an interest payment, the 'Shares' field is not necessary.
Because the number of shares is a required field, one would assume that simple deposit of removal transactions are not allowed; but they are. The number of shares is then ignored.
The acceptable values for the field Type are: Deposit, Removal, Interest, Interest Charge, Dividend, Fees, Fees Refund, Taxes, Tax Refund, Buy, Sell, Transfer (Inbound), and Transfer (Outbound). The default value of Type is Sell.
Suppose that you wish to import two portfolio transactions: a sell of 2 shares of BASF in EUR and a buy of 3 shares NVIDIA in USD. Since we are using the EUR cash account in both cases, the transaction in USD must be converted into EUR. In this case, PP will handle this automatically because the NVIDIA security is listed in USD and the security account in EUR. Alternatively, you can designate the Currency Gross Amount column as USD. However, a more efficient workflow may involve defining the Cash Account, and eventually the Securities Account. This prevents the import from defaulting to standard accounts, such as broker-A and broker-A (EUR) in this case.
Figure 15 displays the Mapped to Field dialog box is shown (accessible via double-clicking the Value column). It's advisable to confirm that the selected format aligns with your language settings, especially if you use a comma as the decimal point as in this example.
The CSV file should look as follows.
Date;Type;Shares;Security Name;Value;Exchange rate;fees;taxes;Securities Account;Cash Account\n2024-01-04; Sell; 2; BASF; 90; ;5; 3; broker-A; broker-A (EUR)\n2024-01-13; Buy; 3; NVIDIA; 1740,98; 1,0837; 15; 10; broker-A; broker-A (EUR)\n(Net) Value field is required, it makes no sense to add the Gross Value, which will be overwritten anyway (Gross Value = Value + Fees + Taxes). Please note that the Exchange Rate field is empty (or zero) in case of the BASF transaction. Figure 14 displays the result of this import transaction. Figure 14. Result of import from above.
Figure 13 displays the first step of the Import wizard. Be sure that the type Portfolio Transactions is selected in step 1; otherwise an error will occur in step 2.
Figure 15. Result of import from above.
A consistency check is made, for example, to ensure that you don't sell more securities than are available in your portfolio (see Figure 16).
Figure 16. Consitency check.
"},{"location":"reference/file/import/pdf-import/","title":"Importing PDF documents","text":"Banks and brokers often provide transaction statements (buy, sell, dividend, etc.) for your convenience on paper or in PDF format. PP can read PDF documents from more than 90 banks and brokers and import the described transactions. The PDF in Figure 1 describes a (fictitious) buy transaction from an Australian broker. If you want to follow along with the example, you can download the PDF document.
Figure 1. Buy statement from SelfWealth of 25 pcs of Beta SP500 YieldMax.
"},{"location":"reference/file/import/pdf-import/#checking-the-existence-of-the-importer","title":"Checking the Existence of the Importer","text":"PP must \"know\" some details about the PDF document from your bank or broker. For example, the type of transaction in Figure 1 is identified by the title \"Buy Confirmation,\" and the ticker symbol (UMAX) is indicated under the column header \"Security Code.\" PP must recognise these details for each transaction to extract the necessary content from the PDF. Therefore, for each supported bank or broker, PP has developed a specific importer (parser) with knowledge of the different transaction types. To develop these importers, PP relies on information provided by its users (see Requesting a New Importer).
To verify if your bank or broker is supported, try to import a PDF document (see next section). The import wizard will either recognise it automatically or display an error message listing all the banks/brokers it has tried. You can also search the forum using the term PDF import or PDF import [name-of-your-bank-or-broker] to see if an importer for your institution is available or if there are any issues with it. If the importer exists, you can move on to the next section. Otherwise, you need to first request a new importer (see Requesting a New Importer).
Use the menu File > Import > Import PDF Bank Documents or the shortcut key CTRL+I, P, and navigate to the PDF document on your local system. You can select more than one PDF document. If a document is recognised by PP (i.e., an importer exists for the bank or broker of this document), an Import Transaction dialog box, such as in Figure 2, is displayed.
In this particular case, there is a small problem and the import operation could not be fully executed. The error message at the bottom provides an indication: the cash account Call Money Account from the demo Kommer portfolio is used for the cash handling of the transaction, but this deposit account is in EUR while the transaction currency is AUD. Selecting (or creating) an AUD deposit account will fix the problem. Please note that in Figure 2, two operations are scheduled: (1) the buy transaction, and (2) the creation of the security Beta S&P500 Yieldmax. If this security already exists in the portfolio, then the import wizard will use the existing security.
Figure 2. Imported transaction from PDF of Figure 1.
Figure 3. Search for suppliers of historical prices (example available at Portfolio Report).
In case of a new security, a Search for suppliers of historical prices box is displayed. If the security is listed on Portfolio Report, then the historical prices could be automatically added. Otherwise, the security is created, but you will need to manually edit the data source to download the historical prices.
If PP doesn't have a PDF importer for your bank/broker or for the specific type of transaction you need, you can request the development of this importer. More info can be found at How-to > Requesting a new PDF Importer.
"},{"location":"reference/help/about/","title":"Help > About Portfolio Performance","text":"Detailed information about the PP program could be found in the menu Help > About Portfolio Performance. The top panel contains the version, e.g. 0.67.0 from december 2023, the platform and the Java version it runs on. The platform could be Windows (win32, x86_64), Linux, or macOS; see Installation. The PP program is built with the Java programming language. The most recent Long Term Support (LTS) version of the OpenJDK (Java Development Kit) is obtained through Azul.com. From the copyright info, you learn that the author Andreas Buchen started development back in 2012.
Figure 1. The About Portfolio Performance panel.
The bottom panel contains links to the used (open source) software, code contributors, translators, and Writers. There is also a section about Installation Details.
"},{"location":"reference/help/about/#software","title":"Software","text":"Eclipse Foundation: Eclipse is a free and open source software development environment that supports various languages, platforms and plugins. It is a very popular and widely used IDE (Integrated Development Environment). Eclipse allows developers to create, test, debug, and deploy applications using a common framework and a rich set of tools. From a user perspective, the choice of a specific IDE is not important. The development platform e.g. Java SDK however is very much.
Apache Software Foundation: Several libraries are used; for example to extract text and metadata from PDF documents, and to perform HTTP requests and handle responses (e.g. communicate with Portfolio Report).
SWT Chart Project: The Eclipse SWTChart software is used to create the line and pie charts in the app. PP uses the Standard Widget Toolkit (SWT) which is a graphical user interface (GUI) library that allows Java developers to create native-looking applications for different platforms. You enable this library in Help > Preferences > General.
Tree Map Library: Treemaps represent a distinct visualization technique for illustrating hierarchical data by using a series of nested rectangles. This kind of map is used in the Taxonomies menu.
jsoup Java HTML Parser: jsoup is a Java library that simplifies working with real-world HTML and XML. It offers an easy-to-use API for URL fetching, data parsing, extraction, and manipulation using DOM API methods, CSS, and xpath selectors. The library is used for example to fetch the historical prices from a table on a financial website.
JSON.simple: JSON.simple is a simple Java toolkit for JSON. You can use JSON.simple to encode or decode JSON text. This tool is used in the app for downloading historical prices from a JSON data source.
Protobuf: Protocol Buffers (a.k.a., protobuf) are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. The software is used to convert the XML-datastructures of the portfolio file into Java usable data structures.
Guava: The Guava libraries are intended to complement the core java libraries and make working in the Java language more pleasant and more productive.
JsonPath: JsonPath is a query language for JSON. It allows to select and extract a sub-section from a JSON document using a simple syntax that is similar to XPath for XML.
D3.js: D3.js is an abbreviation for Data-Driven Documents and is a JavaScript library to work on data visualization e.g. graphs.
XStream: A Java library that allows you to serialize and deserialize Java objects to and from XML or JSON.
OpenJDK: Running a Java program on for example a Windows machine requires that the Java Development Kit (JDK) is installed on that computer. PP uses the JDK provided by Azul.com.
"},{"location":"reference/help/about/#code-contributors","title":"Code Contributors","text":"A link to the Github pages of each of the 159 contributors is given. A graphical overview of all contributions from 2012 till today can be found at Github.
"},{"location":"reference/help/about/#translators","title":"Translators","text":"PP has been translated into Spanish, Dutch, Portuguese, Brazilian Portuguese, French, Italian, Czech, Russian, Slovak, Polish, Chinese (simplified), Chinese (traditional), and Danish.
"},{"location":"reference/help/about/#writers","title":"Writers","text":"The two main sources of documentation for the program are the Forum (German - English) and the Handbook (German - English).
"},{"location":"reference/help/about/#installation-details","title":"Installation Details","text":"Clicking on this tab will generate a very long and detailed description of the environment PP is running in (OS, Java and Eclipse components, paths to log-files, ...).
"},{"location":"reference/help/check-updates/","title":"Help > Check for Updates ...","text":"After the first installation, you can either check manually for updates or allow the program to check each time it starts.
"},{"location":"reference/help/check-updates/#manual-check-for-updates","title":"Manual check for updates","text":"To manually check for updates, navigate to the menu Help > Check for Updates .... Figure 1 will briefly appear.
Figure 1. Checking for updates.
Either no updates are available; indicating that your version is up-to-date or figure 2 will be shown; the correct version will of course be different in the future.
Figure 2. Checking for updates.
To install the most recent version, click OK. To cancel the update and stay with the old version, click Cancel.
There are three links at the top of the panel. New & Noteworthy provides detailed information about the changes in the latest version but also about all previous releases. The Change Log link leads to the Github page of the project where all (previous) releases are described. The download link takes you to the homepage; where you can download the program for the different operating systems (Linux, Windows, macOS); see Getting Started > Installation.
Below the links, you can find an overview of the changes in the last two releases. At the bottom right, you can enable the automatic check for updates (see below).
"},{"location":"reference/help/check-updates/#automatic-check-for-updates","title":"Automatic check for updates","text":"Automatic checking for updates is enabled by default. You can change this setting in the menu Help > Settings > Updates > Check for updates on start (see figure 3).
Figure: Setting for automatic check for updates.{class=pp-figure}
"},{"location":"reference/help/preferences/","title":"Preferences","text":""},{"location":"reference/help/preferences/#preferences","title":"Preferences","text":"There are two distinct sections within the PP software where you can customize the User Interface (UI) and the overall behavior of the program: the View > Settings menu and the Help > Preferences menu.
Figure 1. The General option of the menu of View > Settings.
The preference settings have system-wide implications and will be applied to all portfolios managed by PP. The Preferences window features a sidebar, as illustrated in Figure 1, which is further divided into six submenus.
"},{"location":"reference/help/preferences/#general","title":"General","text":"By selecting the General menu item in the sidebar of the Preferences dialog box (see Figure 1), you will be presented with four options:
Automatically update quotes after opening a file: Each security can have an external data source assigned for downloading historical quotes. You can start the download process manually through the Online menu or enable the option to automatically download historical quotes upon opening the portfolio.Store Gui settings next to Portfolio Performance file: The Graphical User Interface (GUI) settings influence several aspects of the look and feel of the PP program such as the width of columns or size of windows (e.g. main pane vs information pane) and others. These settings are stored in a separate file, that can be located:
In the same folder as the portfolio file (option is checked). The name of the file is [name-of-portfolio].settings; e.g. demo-portfolio-03.settings.
In a subfolder of the workspace folder of the PP application (option is unchecked). The name is a unique random string with the extension \"txt\", e.g.prf_c4c742f0f7312d48355beadb57dc4a09.txt. This file is invisible by default. The location of the workspace folder is:
~/Library/Application Support/name.abuchen.portfolio.product/workspace%LOCALAPPDATA%\\PortfolioPerformance\\workspace~/. PortfolioPerformance/workspaceYou need to search in the subfolder: .metadata\\.plugins\\name.abuchen.portfolio.ui.
The location of your settings file is critical when transferring your portfolio to another computer. If the settings file is stored adjacent to the portfolio, the process is simplified; you only need to copy both files to the new location. However, if the settings file is stored within the workspace folder, it will not be automatically regenerated when installing the PP application on the new computer. In this case, you must manually copy the file from the old computer and paste it into the corresponding location on the new computer to ensure proper configuration.
Enable experimental features: This feature is only intended for developers or \"bold\" users who wish to test out new experimental features, such as a new file format
SWTChart library for pie charts: In certain operating systems, such as Linux, enabling this option is required to accurately display pie charts.
There is only one preset to configure, which is determining the time value for newly entered data, such as the time of a buying transaction. The default setting is Start of day (= 00:00). Alternatively, you can select Current time, which will use the time from your computer clock for new entries.
Figure 2. Settings for the backup of the data files.
The first option enables an automatic backup of your portfolio, creating a copy just before the previous version is overwritten (saved) with the current one. This serves as a safeguard in case you unintentionally modify elements within your portfolio and need to revert to its previous state.
You have three choices for the backup location:
Next to data file: The backup is saved in the same folder as the original portfolio with the text .backup, appended to the name; for example myPortfolio.backup.xml.Selected directory: The backup is saved in the folder location specified below. This could be a completely different directory or drive.Directory Next to data file: The backup is saved in a folder at the same level as the portfolio file. The name of the folder is specified below (e.g. backups, as shown in Figure 2).Note
In fact, turning on the backup option will create a file such as myPortfolio.backup-after-open.xml right after opening your portfolio. This file will contain the state of your original portfolio.
Autosave copy every X minutes: You can specify the number of minutes in the provided text field. With this option enabled, the current state of the portfolio file will be saved automatically every X minutes. Any existing autosave file will be overwritten. To disable this feature, enter zero (0) minutes. The autosave file will be named [name-of-portfolio].autosave.[extension] and stored in the same folder as the original portfolio.Use indirect quotation for exchange rates: Each portfolio has a single base currency, which is set during the creation of the portfolio and can be modified later in the Statements of Assets view. When conducting a transaction involving a foreign currency (foreign relative to the base currency), an exchange rate must be applied. With indirect quotation, the exchange rate indicates how much of the foreign currency is required to purchase one unit of the base currency. On the other hand, direct quotation specifies how much of the base currency is needed to acquire one unit of the foreign currency.
For instance, if your base currency is EUR, the exchange rate with USD would be represented as follows:
Indirect quotation: 0.9321 USD/EUR (one unit of the base currency requires 0.9321 units of the foreign currency)
Direct quotation: 1.0729 EUR/USD (1.0729 units of the base currency are needed for one unit of the foreign currency)
Always display currency code for monetary values: If this option is unchecked, PP will show the currency code (e.g., USD) only when the currency differs from the base currency, resulting in a cleaner and less cluttered view.
Add \"p.a.\" to annualized return rates: The Internal Rate of Return (IRR) is, by definition, an annualized return rate. The True-Time Weighted Rate of Return (TTWROR) is calculated per reporting period (and thus, possibly unannualized). Enabling this option will consistently append the suffix \"p.a.\" to indicate when the return rate is annualized.Figure 3. Settings for the language, country, and Java Locale.
Using the language drop-down menu, you can modify the user-interface language of the PP software, such as the menus and dialogs.. 13 different languages are available: Deutsch (German), English, Espa\u00f1ol (Spanish), Fran\u00e7ais (French), Italiano (Italian), Nederlands (Dutch), Portugu\u00eas (Portuguese), \u010de\u0161tina (Czech), \u0440\u0443\u0441\u0441\u043a\u0438\u0439 (Russian), Slovensk\u00e1 (Slovak), Polskie (Polish), \u4e2d\u6587 (Chinese), and Dansk (Danish).
The selected language will also affect the available country options. For instance, the Dutch language is spoken in seven countries: Aruba, Belgium, Carribean Netherlands, Curra\u00e7ao, Sint Maarten, and Suriname.
If English is selected as the UI language, several countries, including an option for Europe and World, can be chosen. The combination of language and country determines the Java Locale. For example, selecting the language \"Dutch\" and the country \"Belgium\" will result in the Java locale \"nl_BE\". Choosing \"English\" and \"Europe\" will produce the Java locale \"en_150\".
The Java Locale is responsible for formatting dates, currency, decimal and grouping separators, and the first day of the week. For example, the combination of English and Belgium produces the Java locale \"en_BE\", which in turn displays a date like \"03 Oct 2024 15:49\" (English language but Belgian notation) with Monday as the first day of the week, and a comma (,) as the decimal separator and a dot as the grouping symbol.
On the other hand, the combination of English and the United States (en_US) results in a date format like \"Jul 3, 2024, 3:49 PM\" with Sunday as the first day of the week and a number format like 12,345.67.
"},{"location":"reference/help/preferences/#theme","title":"Theme","text":"Figure 4. Theme Settings - example of Light vs Dark theme.
In the Settings > Theme section, you can select either a Light or Dark theme (refer to Figure 4) or set it to automatic. If you choose the automatic option, your system clock will determine whether the light or dark theme will be applied.
The default font size is set to 9 pixels, but you can adjust it according to your preference, with options ranging from 8 pixels to 20 pixels.
"},{"location":"reference/help/preferences/#formatting","title":"Formatting","text":"In this section, you can adjust the display precision for the number of shares (default is rounded to 1 decimal place) and the display precision for calculated quotes (default=2). Keep in mind that the changes will only be visible with decimal numbers (which need to be rounded to the specified number of digits after the decimal point) in read-only views, such as the Statement of Assets view. On input forms, like a buy-input form, you can still enter a more precise number with additional decimal places.
"},{"location":"reference/help/preferences/#calendar","title":"Calendar","text":"A calendar specifies the holidays (of your stock exchange) or the non-trading days for a selected year. Calendars play an essential role in calculations, certain chart views, and investment plans within PP. For instance, if the start date of a monthly investment plan falls on a holiday, the transaction will be moved to the next working day.
PP offers 13 different stock exchange calendars. These include the Australian Stock Exchange (ASX), Euronext, German stock exchanges (DE), IBOV Sao Paulo Stock Exchange (Brazil), ISE Italian Stock Exchange (ISE), London Stock Exchange (LSE), Moscow Exchange (MICEX-RTS), New York Stock Exchange (NYSE), Swiss Exchange (SIX), Toronto Stock Exchange (TSE), and Vienna Stock Exchange (VSE). There are also 4 more generic calendars:
When you select a calendar from the drop-down list, it will display the corresponding holidays for the chosen calendar and year.
Note
Any changes made to the calendar settings will only take effect after restarting the PP program.
"},{"location":"reference/help/preferences/#api-keys","title":"API keys","text":"An API, or Application Programming Interface, is a set of rules and protocols that allows different software applications to communicate with each other. An API key is a unique identifier used to authenticate a user to an application programming interface (API). API keys are used to track and control how the API is being used, prevent abuse, and provide access to specific services or data; see downloading historical prices for a few examples.
For example, Alpha Vantage is a popular API that provides access to financial data. To use the Alpha Vantage API, you first need to sign up on their website and obtain an API key. Then, you can issue an HTTP request such as https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=AAPL&apikey=your_api_key. To avoid having to enter your API key repeatedly, you can save it in the Settings section.
Downloading historical prices requires accessing an external web server such as Yahoo Finance. Using a proxy server can hide your IP address, making your online activity more anonymous. In a corporate environment, proxies are often used to enforce internet usage policies, monitor employee activity, and ensure compliance with regulatory requirements.
"},{"location":"reference/help/preferences/#updates","title":"Updates","text":"PP is regularly maintained and updated. To manually check for updates, you can visit the homepage. The version number (e.g., 0.69.0) is displayed above the download links. Additionally, you can find the latest release on GitHub.
By enabling the Check for updates on Start option in the Settings section, PP will automatically check, download, and install the latest version (if necessary) upon launch. The update process is carried out from the URL https://updates.portfolio-performance.info/portfolio.
On rare occasions, the PP app may not function properly or even crash. Beneath the Help menu, three options can assist in such instances.
"},{"location":"reference/help/trouble-shooting/#show-error-log","title":"Show Error Log","text":"Every time the program starts, it creates a log-file. You can view this log file from within the PP app in a separate window with the command Help > Show Error Log. Double-clicking the message will display the entire text. If there were no errors, this will be a minimal log (see Figure 1).
Figure 1. Log after successful start-up.
If an error is encountered, the log file will list them sequentially. Figure 2 hints at the error (No quotes found). You can double-click on the message to receive more detailed info.
Figure 2. Log after unsuccessful operation.
A rather large text file will appear when double-clicking the message (see below). If you can open the portfolio, you need to fix the historical prices source of this security. Otherwise, you need to open the XML-file in a text editor and manually remove the offending data source.
Figure 3. Log after unsuccessful operation.
You can copy this text to the clipboard, for example when seeking help on the forum or you can save the file.
"},{"location":"reference/help/trouble-shooting/#save-error-log","title":"Save Error Log ...","text":"As previously mentioned, each time the program starts, it generates a log file. This file is automatically saved in your user directory. For Windows users, it typically resides in: C:\\Users\\Your-name\\AppData\\Local\\PortfolioPerformance\\workspace\\.metadata\\.
To save the latest log to a text file with the extension .log, you should use this command. The text file provides more comprehensive information (see below) than the error window depicted in Figure 3, including details about the operating system, the current Java version, and other relevant data.
!SESSION 2024-02-19 11:47:29.300 -----------------------------------------------\neclipse.buildId=0.67.3.\njava.version=17.0.5\njava.vendor=Azul Systems, Inc.\nBootLoader constants: OS=win32, ARCH=x86_64, WS=win32, NL=en_US\nCommand-line arguments: -os win32 -ws win32 -arch x86_64\n\nThis is a continuation of log file C:\\Users\\your-name\\AppData\\Local\\PortfolioPerformance\\workspace\\.metadata\\.bak_0.log\nCreated Time: 2024-02-19 13:18:06.540\n\n!ENTRY name.abuchen.portfolio 4 0 2024-02-19 13:18:06.540\n!MESSAGE 404 Not Found --> https://query1.finance.yahoo.com/v8/finance/chart/TNET.BR?lang=en-US®ion=US&corsDomain=finance.yahoo.com\n!STACK 0\nname.abuchen.portfolio.util.WebAccess$WebAccessException: 404 Not Found --> https://query1.finance.yahoo.com/v8/finance/chart/TNET.BR?lang=en-US®ion=US&corsDomain=finance.yahoo.com\n at name.abuchen.portfolio.util.WebAccess.executeWith(WebAccess.java:222)\n at name.abuchen.portfolio.util.WebAccess.get(WebAccess.java:182)\n at name.abuchen.portfolio.online.impl.YahooFinanceQuoteFeed.rpcLatestQuote(YahooFinanceQuoteFeed.java:61)\n at name.abuchen.portfolio.online.impl.YahooFinanceQuoteFeed.getLatestQuote(YahooFinanceQuoteFeed.java:69)\n at name.abuchen.portfolio.ui.jobs.UpdateQuotesJob$1.run(UpdateQuotesJob.java:244)\n at org.eclipse.core.internal.jobs.Worker.run(Worker.java:63)\nChoosing this option will simply display the dialog boxes of Figure 1 & 2. As you can see, you need to quit and restart the application after that.
Figure 4. Reset GUI dialog box.
Figure 5. Successful reset of UI.
The Reset UI function will NOT delete any created views or custom reporting periods, nor will it reset the Recent Files list, as these parameters are saved separately.
However, it does reset the position and size of the PP application window on your monitor and does not restore open files from the moment of closing. Additionally, it sets the main and information panes to their initial values. In essence, as the name implies, it resets the Graphical User Interface (GUI/UI).
In the event of unexpected errors, initiating a Reset UI could be your initial troubleshooting step, as it minimally disrupts your workflow.
"},{"location":"reference/help/trouble-shooting/#updating-error","title":"Updating error","text":"If the program is corrupted or some files are missing, automatic updates are not feasible. An error message (see figure 4) is displayed, and the automatic update is no longer possible.
The simplest workaround is to delete the program and reinstall it.
Figure 6. Error message upon manual check for updates.
"},{"location":"reference/transaction/","title":"Transaction","text":"Figure 1. Transaction menu.
In PortfolioPerformance (PP), a transaction represents an operation that alters the state of a portfolio; for example, a deposit will increase a deposit account. As depicted in Figure 1, there are 15 transaction types. Security transfer ... and Transfer between accounts ... deviate slightly from the others and only appear when there is more than one security and/or deposit account. The transactions can be grouped into pairs of operations that have opposite effects:
Note
In theory, PP could suffice with 8 transaction types: trade, delivery, deposit, fees, taxes, interest, transfer, and dividend. Each transaction could be expressed with a positive or negative value, for example: sell or trade(-) and buy or trade (+).
In fact, this is suggested by the fact, that the type of a transaction could be changed in a table such as All Transactions by double clicking on the keyword (e.g. Buy) and choosing the alternative from the drop down (sell, delivery inbound, delivery outbound). This technique doesn't work with fees and taxes.
Figure 2 illustrates the effect of all 15 transaction types on the deposit and securities account. Analyzing Figure 2 will clarify the impact that each transaction type has on a portfolio.
Security accounts are exclusively impacted by buy, sell, delivery (inbound & outbound), and Security Transfer transactions. This likely explains why they are grouped together with a divider line (see figure 1). It's important to note that while a buy/sell transaction affects both deposit and security accounts, delivery and security transfer transactions do not. A delivery is essentially a buy/sell transaction without the involvement of deposits and is represented as originating from outside the portfolio.
All transaction types, except delivery and security transfer (see above), will affect the deposit account. These effects could manifest as inflows (green color) or outflows (red color).
The coloring scheme might be a bit confusing. In the image on the left side of Figure 2, which represents the All Securities view, a buy transaction results in an outflow from the deposit account, yet it's depicted in green. Conversely, a transfer (from one security/deposit account to another) is depicted in red.
With the exception of interest, all transaction types are associated with a specific security, such as a share. Interest, on the other hand, is only linked to a deposit account. One implication of this is that interest on bonds should be recorded as a dividend in PP if you wish to maintain the connection with the bond.
Figure 2. All 15 transaction types with their effect.
"},{"location":"reference/transaction/buy-sell/","title":"Buy or Sell transaction","text":"When buying or selling a security, there are two main scenarios to consider regarding the currency of the deposit account.
In the first scenario, if the security is in the same currency as the deposit account, the transaction is straightforward. The buyer or seller simply pays or receives the equivalent amount corresponding to the value of the security, and the corresponding amount is debited or credited from or to their deposit account.
In the second scenario, if the security is not in the same currency as the deposit account, a currency conversion becomes necessary. This need for currency conversion can also arise if your broker or bank charges you taxes and fees in your local currency, while you're utilizing a deposit account denominated in the foreign currency of the security.
"},{"location":"reference/transaction/buy-sell/#one-currency","title":"One currency","text":"Figure 1. Buy and Sell transaction with one currency.
In Figure 1, both the security and the deposit account are denominated in EUR. Consequently, no currency conversion is required, given that fees and taxes are also in EUR for this particular broker. The fields Security, Securities Account, Deposit Account, Shares, and Debit Note are mandatory. An error message will be displayed at the top until all conditions are fulfilled, as depicted in Figure 1.
You can navigate through these fields using the Tab key on your keyboard or by using the mouse.
Security is normally pre-filled with the first or selected security from the All securities list. You can, of course, select another security from the drop-down. Please note that the currency is automatically set because each security has a reference currency, which is set during creating the security.Help > Preferences > Language > Country. For instance, the UK uses a 12-hour clock (with AM and PM), while Belgium uses a 24-hour clock. By default, the Start of Day, e.g. 00.00 is taken. You can change it to Current time with menu Help > Preferences > General >Presets. The above six fields (+ the calculated Debit Note) are mandatory for completing the transaction. Most of these fields are pre-filled based on the selected security. The following fields are either calculated or optional.
Gross Value : This is the result of multiplying Shares by Quote. If you later change the Gross Value, the Quote Price will be adjusted accordingly to maintain the equation Shares * Quote.
Fees and Taxes : A purchase transaction typically incurs fees and taxes. These may be in the currency of the security and/or deposit account.
Debit Note : This is the amount you need to pay as a result of this buying transaction. It is calculated as Shares * Quote + Fees + Taxes. Other terms for this are Value or Net Value.
Note : You can add a textual note to each transaction.
The typical flow for entering this information is likely to be Shares * Quote (price) >> Gross Value + Fees + Taxes >> Debit Note. There are a few nuances if you make changes afterward (see Figure 3).
Figure 2. Calculation flow between Shares and Debit Note.
Clicking the \"Save\" button will update the portfolio accordingly. If you select \"Save & New,\" it will not only update the portfolio but also prompt a new buy/sell dialog box for further transactions.
"},{"location":"reference/transaction/buy-sell/#two-currencies","title":"Two currencies","text":"Sometimes, the currency of the security may differ from the currency of the deposit account being used. In such cases, an exchange rate is automatically generated for the pre-filled date. This exchange rate is sourced daily from the ECB (European Central Bank) and does not consider the time of day. It's important to note that altering the date afterward will also result in a change in the exchange rate, regardless of whether the exchange rate was retrieved automatically or manually entered.
Figure 3. Buy and Sell transaction with two currencies.
It's important to note that the Quote price and the (first) Gross Amount are always expressed in the currency of the traded security (for example, EUR in Figure 2). On the other hand, the debit note is always expressed in the currency of the deposit (as it represents the actual payment). Fees and taxes, however, can be entered in either the currency of the security (on the left side) or the currency of the deposit account (on the right side), or even in both currencies simultaneously.
"},{"location":"reference/transaction/delivery/","title":"Delivery (Inbound - Outbound)","text":"A delivery involves the addition or removal of securities from a securities account, without requiring a deposit transaction. Drawing a comparison between Inbound and Outbound deliveries and Deposit and Withdrawal (removal) transactions can provide clarity.
Both types of transactions involve the transfer of assets (money), but they impact different types of accounts. Deposit and withdrawal transactions only affect cash accounts. When a deposit is made, the cash account increases, and conversely, it decreases when a withdrawal is made. Similarly, Inbound and Outbound deliveries involve the addition or removal of securities from a securities account. In both cases, whether it's cash or securities, assets are either added to or withdrawn from an account.
Delivery transactions can be particularly useful in the following scenarios:
Portfolio Reconstruction: You're trying to reconstruct a portfolio based on historical data but lack specific transaction details such as prices, fees, or even dates.
Inheritance and gifts: If you inherit securities or receive them as a gift, you may not have all the historic details and probably only has info about the current market price. A delivery at the current date and price could be a solution.
Currency Considerations: If the security is in a currency for which no cash account exists in the portfolio, a delivery transaction can be used to add the security to the portfolio.
Corporate Actions: Certain corporate actions like stock splits, mergers, or acquisitions can sometimes be more easily implemented with deliveries vs buy/sell.
Figure 1. Delivery (Inbound) and Delivery (Outbound) transaction - one currency.
"},{"location":"reference/transaction/delivery/#one-currency","title":"One currency","text":"Each security account is paired with a corresponding cash account, which is automatically added upon creation. Since security-account-1 is linked to a cash account denominated in EUR, EUR is suggested as the default currency in Figure 1. The currency designation in the box (EUR) can be modified; the text to the right provides a description of the currency (Euro).
When the chosen currency for the transaction matches the currency of the security (share-1), no conversion is necessary. All other fields, such as date, shares, quote, etc., remain identical to those in the buy-sell transaction.
"},{"location":"reference/transaction/delivery/#two-currencies","title":"Two currencies","text":"The transaction currency can be changed by choosing another security or security account. However, it's also possible to change the transaction currency directly with a given security and/or security account. To change the currency of the transaction, you can either:
An exchange rate from the ECB will be suggested. However, it's worth noting that fees and taxes are only applicable in the currency of the security, which is different from the setup in the buy-sell transaction.
Important
As depicted in Figure 2, you have the flexibility to select any currency from the list of available currencies for conversion (more than 50 options). There's no requirement for a corresponding cash account in that currency. For instance, in Figure 2, the Chinese yuan is chosen, despite the absence of a cash account in CNY. Nor will a deposit account in that currency be created. It's important to remember that with a delivery transaction, a security seems to appear or disappear \"magically\".
Figure 2. Delivery (Inbound) and Delivery (Outbound) transaction - two currencies.
"},{"location":"reference/transaction/deposit-removal/","title":"Deposit - Removal (withdrawal)","text":"A deposit is the process of adding funds to a deposit account, while a removal (withdrawal) is the process of removing funds from an account. A deposit account is sometimes also called a cash account.
Figure 1. Example of a deposit (in EUR) and removal (withdrawal) in USD.
Figure 1 illustrates a deposit of 15 EUR and a withdrawal of 14 USD. Although the deposit increases (debits) your account balance, it is termed a Credit note because the funds originate from a third party, whose account will be reduced (credited). This resembles a scenario such as returning goods, where you receive a credit note from the company.
The currency of the transaction is determined by the associated cash account. While adding the currency to the names of the deposit accounts may seem redundant, it can be helpful for quick identification when selecting an account from a drop-down menu. Naming them deposit-account-1, deposit-account-2 will force you to remember that account-1 is for EUR and account-2 is for USD.
Implicit deposits or withdrawals can also occur through other transactions, such as a stock purchase, which automatically triggers a withdrawal of the equivalent value from a cash account.
A common mistake for beginners is to record a buy transaction without first ensuring that the necessary deposits are made. This can lead to a negative balance in the deposit account, which affects the market value of the portfolio at the end of the reporting period and consequently impacts the portfolio's performance. This effect is of course not visible in the performance of an individual security or trade.
It is not possible to attach an interest rate to a deposit account as is typically done with banks. As a result, funds placed into a deposit account maintain their exact value until the end of the reporting period (MVE). As a result, deposits and withdrawals on their own have no effect on the portfolio's performance. Assume a portfolio Market Value (MVB) of 100 EUR at the beginning of the reporting period and only one deposit of 50 EUR at the exact mid of the 1 year period (see Concepts > Performance for more info about the calculation).
r = [150/(100 + 50)] - 1 = 0%. 150 = 100 x (1 + IRR)^1 + 50 x (1 + IRR)^1/2 = 0%.To assign an interest to a deposit account, you can use the menu Transaction > Interest.
A dividend is a distribution of profits by a corporation to its shareholders. When the distribution is made in cash, you should use this transaction type. For a choice or stock dividend, refer to Handling choice dividends in the how-to section.
"},{"location":"reference/transaction/dividend/#registering-a-dividend","title":"Registering a dividend","text":"With the Transaction > Dividend menu, you can record the dividend payment in your portfolio. You can also utilize the context menu by right-clicking. If a security was selected, the security field will be pre-filled for your convenience.
Figure 1. Dividend dialog box for same and different currency payments.
Invert button to change the conversion direction, for example, from EUR to USD or vice versa. The gross value in the foreign currency is calculated, and additional fields for fees and taxes are included.The directly visible effect of a dividend registration is the increase in balance of the designated deposit account. Take the following very simple project. Ten pieces of share-1 are purchased on January 1th, 2024 for 10 EUR/share. The reporting period runs to April 1, 2024 at which time share-1 quote has increased to 11 EUR/share.
The balance of the deposit account is zero EUR. The portfolio TTWROR = 10% and IRR = 46.56%. An in-depth explanation of the performance calculation in PP is given in Concepts > Performance.
A dividend is paid on March 1, 2024 at 5 EUR/share. The fees and taxes were each 1 EUR. There are 31 days remaining in the reporting period. At that moment, the balance of the deposit account is increased with (10 x 0.5) - 1 - 1 = 3 EUR. Performance starts to differ between portfolio, security or (open) trade level.
there are two cashflows: CF1 = 100 EUR at 2024-01-01 and CF2 = 3 EUR at 2024-03-01.
Portfolio Security Trade TTWROR IRR TTWROR IRR IRR Without dividend 10% 46.56% 10% 46.56% 46.56% Dividend with fees & taxes (1 + 1 EUR) 13% 63.27% 14% 69.14% 46.56% Dividend with fees (1 EUR) 14% 69.14% 14% 69.14% 46.56% Dividend with taxes (1 EUR) 14% 69.14% 15% 75.17% 46.56%"},{"location":"reference/transaction/fees-taxes/","title":"Fees - Fees refund","text":"Fees and taxes are typically reconciled at the time of purchasing or selling securities. However, there are instances when it may be necessary to record them at a different time. The dialog boxes in Figure 1 demonstrate that the same input data is required: the name of the security, the name of the deposit account, the transaction date, and the amount (debit or credit note).
Figure 1. Fees, Fees Refund, Taxes, and Tax Refund transactions.
You can choose for a deposit account with a currency different from that of the security account. An additional input box for the exchange currency will be displayed (refer to Figure 2).
Figure 2. Using different currencies for securities and deposit account.
"},{"location":"reference/transaction/interest/","title":"Interest - Interest Charge","text":"Interest is the compensation received for lending money, such as depositing funds into a cash account. It reflects a traditional bank arrangement where you may earn monthly or yearly interest on the funds held in the account. The transaction is initiated by the credit note from the bank. Taxes can be withheld from the interest payment. Conversely, an interest charge is a fee incurred for borrowing money. When your (physical) cash account becomes negative (indicating borrowing), you pay a fee, which constitutes a debit operation for the bank.
Figure 1. Interest and Interest Charge transaction.
The result of the interest and interest charge transaction is an increase or decrease of the balance of the selected cash account (see Figure 2).
Figure 2. Result of interest and interest charge transaction on balance.
There could also be an effect on the performance of the portfolio. The net result on both interest transactions of Figure 1 is an earning of 3 EUR. For a reporting period of 1 year (2024) and based on the data from Figure 2, this gives:
r = 603 / 600 = 0.50%603 = 600 x (1 + IRR)^(305/365) for IRR = 0.60%Please note that the 600 EUR deposit is considered by PP as a (performance neutral) cash inflow but the interest and interest charge transactions are not. They only affect the balance of the deposit account and therefore also the MVE of the portfolio.
"},{"location":"reference/transaction/transfer/","title":"Transfer","text":"The Security Transfer and Transfer between Accounts menu options are only visible when there is more than one security account and/or deposit account present.
You can transfer money between deposit accounts of the same currency or different currencies. In Figure 1, for example, 100 EUR is transferred from deposit-account-1 (EUR) to deposit-account-2 (USD). Given the exchange rate of 1.0696 EUR/USD, this will result in a deposit of 106.96 USD in the latter account.
The exchange rate is automatically retrieved from the ECB for the specified date, but it can be manually overridden if necessary.
Figure 1. Transfer between EUR- and USD-deposit account.
"},{"location":"reference/transaction/transfer/#security-transfer","title":"Security Transfer","text":"As the name suggests, this transaction involves transferring a specified number of shares from one security account to another. It is only accessible in the menu when the portfolio includes more than one security account. The topic Reference > View > Accounts > Securities Accounts summarizes some arguments for portfolios with only one security account or multiple accounts.
There are various scenarios where security transfers might be necessary. For instance, if you have multiple brokers each with their respective securities accounts, you might need to transfer a security between them, mirroring real-life scenarios where you move a security from one broker to another.
Another common scenario involves making provisions for the future, such as reserving some of your stocks for your children. While keeping the stocks in your portfolio, you may transfer a portion from the parent account to a child account. This segregation ensures that selling stocks from the parent account doesn't impact the performance of the child account, enabling separate performance tracking.
Figure 2. Security transfer dialog box.
With three drop-down boxes, you can select the security (share-1), as well as the source (security-account-1)and target (security-account-2) security account; see Figure 2. Several checks are conducted; for instance, you cannot transfer a security that is unavailable or insufficiently available in the source account. You also need to provide the date of the transfer, the number of shares, and the quote price.
Although it's technically one transaction, behind the scenes, PP creates two \"virtual\" transactions (refer to Figure 3; information pane). The security transfer is divided into a Transfer (Outbound) of 3 shares from security-account-1, followed by a Transfer (Inbound) into security-account-2. However, both transactions are considered as a single entity. Editing one of them will trigger the Security Transfer dialog. Deleting one transaction will also remove the other.
Figure 3. Result of the Security Transfer transaction.
A consequence of the Security Transfer transaction is the creation of two open trades, as depicted in Figure 4. The second trade covers the remaining 7 shares in security-account-1, while the first trade comprises the four transferred shares in security-account-2. Both trades are recorded as starting from the date of the original security purchase. While it could be argued that the second trade should start from the date of the transfer, this is not the case. Additionally, both trades share the same buying price, although an argument could be made to use the quote price of the transfer instead. It should be noted that the date and quote price entered with the Security Transfer do not appear to be utilized in this process.
Figure 4. Resulting trades from the Security Transfer transaction.
"},{"location":"reference/transaction/transfer/#setting-the-quote-price","title":"Setting the quote price","text":"Why is a quote price required? What price should you enter: the purchase price, the historical price at the transfer date, zero? Why can't you just transfer the shares from one account to another? The short answer is performance tracking.
Considering the scenario from above, transferring 3 shares (see figure 2). The stock is purchased at 10 EUR per share on Jan 1, 2023. The historical price at the time of transfer was 12 EUR/share, although you transferred it at 10 EUR/share (see Figure 3). Today (2024-01-01), the price has risen to 15 EUR per share. What is the performance of both security accounts for the reporting period 2023-01-01 until 2024-01-01? Remember, the reporting period spans from the end of the first day (e.g. 2023-01-01) to the end of the last day.
Figure 5. Absolute performance and IRR of source and target accounts (quote price transfer = 10 EUR).
The formula for absolute performance is: MVE - MVB + CFout - CFin, where MVE = Market Value at the End (of the reporting period), MVB = Market Value at the Beginning, CFout = cash flows out of the account, and CFin = cash flows into the account. The absolute performance of an account is the difference between the beginning and end value of that account, but corrected for the in- and outflows.
If the quote price is set to the purchase price (10 EUR):
Absolute Performance
MVE (7 x 15) - MVB (10 x 10) + CFout (3 x 10) - CFin (0) = 35 EUR.MVE (3 x 15) - MVB (0) + CFout (0) - CFin (3 x 10) = 15 EURIRR [Equation]
(7 x 15 EUR) = (10 x 10 EUR) x (1+46%)^(365/365) - (3 x 10) x (1 + 46%)^(306/365)(7 x 15 EUR) = (0 x 10 EUR) x (1+62%)^(365/365) + (3 x 10) x (1 + 62%)^(306/365). The transfer is executed on March 1, 2023, with 306 remaining days until MVE.If the quote price is set to the historical price at the moment (12 EUR):
(7 x 15) - (10 x 10) + (3 x 12) - 0 = 41 EUR.(3 x 15) - 0 + 0 - (3 x 12) = 9 EUR.If the quote price is set to zero (which is actually not possible in PP; choose 0.1 for testing):
(7 x 15) - (10 x 10) + (3 x 0) - 0 = 5 EUR.(3 x 15) - 0 + 0 - (3 x 0) = 45 EUR.As can be seen, the absolute performance varies a lot: from positive +41 EUR to 5 EUR for the source account. The bad performance is, of course, very understandable. Transferring 3 shares out of the source account for nothing will severely impact the performance.
The performance of the portfolio should be the sum of the account performances, which in all three cases is equal to 40 EUR. The MVE of the portfolio is (7 + 3) * 14 EUR = 140 EUR. The MVB = 10 * 10 EUR = 100 EUR. The absolute performance of the portfolio is thus indeed 40 EUR.
"},{"location":"reference/view/options/","title":"Options","text":"The Options submenu includes various submenus for customizing the program's startup behavior and the visibility of elements on the screen.
Figure 1. View > Options submenu
Always start with 'All transactions' in this part. Choosing this option ensures that this view is always displayed in the top panel on start-up.An account is a collection of transactions. These transactions could include buy and sell transactions of securities (shares, etc.) for a Securities account or withdrawals and deposits of money for a Deposit account. Each account has a default currency attached. As part of the installation process, you have already created at least one Security account and one Deposit account.
Portfolio Performance (PP) has two main types of accounts: Deposit and Securities accounts. They are described quite well in the Guide on Getting Started by Thomas (Contributor); you will need to scroll quite far down. Other related terms are Reference account, Offset account, and Cash account.
Figure 1. Example of Deposit Account.
Figure 2. Example of Security Account.
"},{"location":"reference/view/accounts/#related-terms","title":"Related Terms","text":""},{"location":"reference/view/accounts/#cash-account","title":"Cash Account","text":"The term Cash Account is somewhat inconsistently used. In Figure 1 (main pane; first column) it refers to a Deposit Account; which is in line with the name Cash Account. In Figure 2 (information pane bottom) the Cash Accountcolumn refers to a Security Account (broker-1).
A security account is always associated with a deposit account. This is the deposit account that will be used (if no other is explicitly assigned) for any buy or sell transaction on that security account. This deposit account is called the Reference Account. In Figure 2, the Broker-1 security account has a reference (deposit)account named Broker-1 (EUR).
The Reference account of a Security account must be set when creating this account (see Figure 2 of Creating a Portfolio). You can always change the Reference account by selecting Accounts > Securities Accounts from the left sidebar. Double-click on the relevant Reference account currency and choose a new one from the drop-down menu (see Figure 2; second column).
The offset or counter account, also known as \"Gegenkonto\" in German, is an essential component when dealing with securities transactions. It acts as the counterpart to the securities account. In other words, for every transaction that occurs in the securities account, an equal and opposite entry is recorded in the offset account.
When you perform actions like buying or selling securities within your securities account, these transactions are balanced by corresponding entries in the offset account. For example, when you buy securities, the purchased securities are added to the securities account, and an equivalent amount of cash is withdrawn from the offset account. This ensures that the overall balance of your accounts remains zero or balanced.
However, also the term \"Offset account\" is a relative concept. Compare the bottom panels of Figure 1 and 2. For a Deposit Account(Figure 1), it refers to a Security Account and vice versa.
The All Transactions view displays a table with all the transactions of the portfolio in the main pane, sorted by the transaction's creation time in the portfolio (see Figure 1). The default view presents the columns Date, Type, Security, Shares, Quote, Amount, Fees, Taxes, Net Transaction Value, Cash Account, Offset Account, Note, and Source (see the Glossary for a definition of these terms).
Figure 1. The All Transactions View.
Although it's less useful than in the All Securities view, the information pane at the bottom (not shown in Figure 1) can provide additional details about the security attached to the selected transaction in the main pane.
Figure 2. The Show or Hide columns button (gear).
Click the column heading to sort the table in ascending (\u2227) or descending (\u2228) order based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column or double click to best fit. You can rename or hide a column with the context menu (right-click on the column header). Adding, deleting or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). The default columns are shown in Figure 1; they are also checked in Figure 2. Figure 2 gives a list of all available columns.
As can be seen, all available columns are displayed except ISIN, Symbol, and \u00b4WKN\u00b4, which are typically security related terms (see the Glossary).
In a typical portfolio, the transaction table can contain hundreds of rows. However, you can use the search function to narrow down the displayed rows. This function scans all cells in every column, and if the cell contains the search value, the corresponding transaction (row) will be displayed. For example, entering share-3in the Search box of Figure 1, will narrow the list down to the first row. Entering share (or for that matter sh is enough) will display all transactions with the security column (in fact every column) containing the word share. The function searches through all available columns, whether they are displayed or not. You can not use wildcards such as * or ?, nor limit the search function to one column only.
Figure 3. The Filter Securities button.
Another method to limit the number of transactions is by using the \"Filter Securities\" button located in the top right corner of the interface. Figure 3 showcases all potential options available. By default, transactions from All transaction types of the Entire portfolio are displayed in the table.
There are two major Filter groups: Filter data by transaction type versus Filter data by portfolio and reference account. The first group selects transactions such as all Buys or Sells. The second group selects transactions from a specific security account. The various options are somewhat self-explanatory. The translation Transactions with investment vehicle for the German original Buchungen mit Wertpapier is somewhat unfortunate. A more appropriate term would be Transactions with securities.
The filter operates on an \"either-or\" basis. Choosing one option from a group will replace any previous selection in that group. For example, you can choose \"Buys and Sells\" or \"Buys\" only, or \"Sells\" only.
The Filter command and the search function work together and complement each other. For instance, searching for \"USD\" and filtering for \"Deposits\" will result in displaying only the second row of Figure 1: a USD deposit.
There are some limitations. For example, you can only filter on reference account, not on any cash account such as broker-A (USD). However, with the New option, you can create a filter for whatever (cash) account. Please note, that it seems also not possible to filter for Transactions without taxes or fees.
With the Manageoption, you can rename a (new) custom filter, add elements to it or delete the filter. The Remove entries option will reset the filter to the entire portfolio in the second group.
Figure 4. Export selected rows.
With the Export button located at the top right, you have the option to save the displayed transaction table as a CSV or JSON file. Only the columns and rows currently displayed, including the header row, will be saved.
If you made a selection in the table, the Export button will provide you with four options instead of two (see Figure 4), including the possibility to export only the selected transactions.
Note
The File > Export will always export ALL transactions. If you are only interested in a specific selection, use this option.
"},{"location":"reference/view/accounts/deposit-account/","title":"Deposit accounts","text":"A deposit account serves as a central hub for managing cash flow within the portfolio, allowing users to allocate funds for investment activities and track incoming and outgoing cash transactions. One can visualize it as a list, akin to a shopping list, where transactions such as withdrawals and deposits of digital money are recorded. There can be many deposit accounts within one portfolio, for example, for different currencies that are traded. As part of the installation process, at least one security account and one deposit account have already been created.
Figure 1. Example of Deposit Accounts.
"},{"location":"reference/view/accounts/deposit-account/#main-pane","title":"Main pane","text":"In Figure 1 (main pane), there are four deposit accounts. It may seem unnecessary to include the currency in the name of an account, as the currency is already specified for each deposit account in the third column of Figure 1. However, including the currency in the name of the deposit account can be helpful in situations where you need to select a deposit account from a list, such as when buying a security. In these cases, having the currency clearly displayed in the name of the account can help you quickly and accurately choose the correct one.
You can use different names for accounts depending on your preferences and needs. For example, if you wish to keep your dividends and taxes separate, you could create two accounts named Dividends\" and Taxes.
Figure 2. Add account.
To create a new deposit account, click on the green + icon located at the top right (refer to Figure 2). Then, select the option Add account. Since you're in the Deposit Account view, a new deposit account named No Name will be created with the default currency of the portfolio. To rename the account, simply double-click on the Name field and enter the desired name. Remember also to change the currency if needed by double-clicking on the currency field (e.g., EUR) and selecting another currency from the dropdown menu. While navigating the currency list, you can use the first letter of the desired currency for faster navigation. Initially, the balance of the newly created deposit account will be zero.
A deposit account can be negative. However, good practice requires that you first add a deposit of a large enough sum to cover the subsequent buy transactions, just as you would do with a real broker.
To deactivate an account, right-click on the account and choose Deactivate account from the context menu. The account name will appear greyed out and will no longer be visible in the list of deposit accounts when making a deposit transaction. With the Filter icon (top right), you can hide inactive accounts.
You can delete a deposit account using the context menu. However, it is important to note that you can only delete an account if there are no transactions associated with it.
If you want to delete an account that has transactions, you will need to first delete the transactions that are linked to that account. Once all transactions have been removed, you can then delete the account itself.
Using the Show or Hide columns option (accessible via the gear icon at the top right), you can customize the view by hiding or adding columns. The available columns for display include: Cash account, Balance, Currency, Note, and Attributes. See also How-to > User Interface for more detailed information about handling the table.
The information pane at the bottom displays the transactions of the selected deposit account in the main pane. It consists of two tabs: Transactions and Account balance chart. The Transactions tab displays fields such as date, type, amount, and balance of each transaction. The Account Balance chart provides a graphical representation of the account balance. Due to fewer data points compared to a historical prices graph, the chart may appear more blocked. Figure 3 illustrates the balance of the Broker-1 (EUR) account, where the early spikes are the result from deposits followed by purchases on the next day.
Figure 3. Example of the Account Balance Chart.
The context menu, accessed by right-clicking on the chart, offers the same options as many other charts; for example, you can refer to the chart menu of the All Securities info pane for more information. There are no other configuration settings.
If you notice any discrepancies in a deposit account between the calculated balance of PP and the actual balance of the bank/broker, you can use the context menu to troubleshoot the issue. To do so, right-click on the account in the main pane and select \"Troubleshoot Balance Discrepancy\" from the menu.
This will open a dialog box displaying the calculated monthly balances for the selected deposit account. In the \"Expected balance\" column, you can enter the balance that you expect according to your bank account statement. Portfolio Performance (PP) will then use the calculated difference to try to identify any transactions that may be causing the discrepancy. For example, PP may find transactions that were made to a different account or are dated in the future.
"},{"location":"reference/view/accounts/investment-plans/","title":"Investment Plans","text":"An investment plan is an automated method to facilitate periodic transactions, such as deposits, withdrawals, interest payments, or purchases. It allows you to systematically invest or withdraw funds at regular intervals with minimal manual input.
"},{"location":"reference/view/accounts/investment-plans/#types-of-investment-plans","title":"Types of investment plans","text":"Figure 1. Four investment plans in the main pane and generated transactions of plan-3 in the information pane.
There are four main types of investment plans: deposit, removal (withdrawal), Interest and Security Purchase/Delivery (as illustrated in Figure\u00a01). A deposit and interest plan will increase the balance of a cash account, while a removal plan will decrease it. On the other hand, a Security Purchase/Delivery plan involves both decreasing your deposit account (to fund the purchase of securities) and increasing your security account (as you acquire new securities). To create a new plan, simply click the 'New Plan' button, located at the top right corner of the interface (as shown in Figure 1).
"},{"location":"reference/view/accounts/investment-plans/#deposit-investment-plan","title":"Deposit Investment Plan","text":"Figure 2. Deposit Investment Plan.
With a deposit investment plan, you can regularly deposit a specified amount of money into a designated cash account. To set up a deposit plan, you will need to provide a descriptive name (such as plan-1), the name of the cash account, the amount of money to be deposited, the starting date of the plan, and the frequency (interval) of the deposits (ranging from every month to every 12 months). The starting date could also be in the past or the future.
Once you click the Save button, the information will be added to the main pane of the investment plans (as shown in Figure 1), but the plan will not be executed immediately. No transactions will be performed at this stage. However, if you have checked the Create transactions automatically when opening the file, the plan will be executed automatically the next time you open the file.
Alternatively, you can click the 'Save & New' button to add the plan to the list and reopen the dialog box. This allows you to create multiple deposit plans in quick succession.
"},{"location":"reference/view/accounts/investment-plans/#removal-investment-plan","title":"Removal Investment Plan","text":"Figure 3. Removal Investment Plan.
With a removal investment plan, you can periodically withdraw a specified amount of money from a designated cash account. The process of setting up a withdrawal plan is similar to that of a deposit plan. You will need to provide a descriptive name for the plan, the name of the cash account to be used, the amount of money to be withdrawn, the starting date of the plan, and the frequency of the withdrawals. The same fields that were used to create a deposit plan will be required for a withdrawal plan.
"},{"location":"reference/view/accounts/investment-plans/#security-purchasedelivery-investment-plan","title":"Security Purchase/Delivery Investment Plan","text":"Figure 4. Security Purchase/Delivery Investment Plan.
With a Security Purchase/Delivery investment plan, you can regularly acquire a specified security using funds from a designated cash account. As shown in Figure 4, you will need to provide a descriptive name for the plan (such as plan-3), the name of the security account and the specific security to be acquired, the name of the cash account from which the funds will be withdrawn, the starting date of the plan, the frequency of the purchases, the amount to be invested each time, and any associated fees.
It's important to note the distinction between purchase and delivery when selecting the cash account. If you want to acquire the security through delivery, you should use the (Inbound Delivery) option. On the other hand, if you want to purchase the security, you should use the name of an existing cash account from which the funds will be withdrawn.
The following fields/columns are displayed in the main pane (see Figure 1): Name, Security, Securities Account, Cash Account, Start Date, Last Execution, Next Execution, Interval, Auto-Generate, Amount, and Fees. Most fields are self-explanatory. The Auto-Generate field is automatically set when the Create transactions automatically when opening the file option is selected during the initial creation of the plan. Two additional fields, Notes and Attributes, can be added using the Show or Hide button (gear symbol at the top right). For information on how to manipulate individual columns, please refer to the All Transactions section in the manual.
Figure 5. Interest Plan.
The Interest Plan bears similarity to the Deposit Plan as it also generates a deposit in the specified Cash Account. Moreover, it allows for tax deductions. The transactions under this plan are classified as Interest, ensuring they are not included in cash flows when calculating performance. (see System Overview section)
The main pane of Figure 1 displays a comprehensive list of all investment plans in the portfolio. By using the context menu, which can be accessed by right-clicking a plan, you have the ability to generate transactions, modify the selected investment plan, or remove it entirely.
"},{"location":"reference/view/accounts/investment-plans/#generate-transactions","title":"Generate Transactions","text":"Figure 6. Message box at opening of portfolio.
Create transactions automatically when opening the file was selected during the creation of the plan, the transactions will be automatically generated the next time the file is opened. A message box, similar to the one shown in Figure 6, will be displayed upon opening the portfolio.Generate Transactions command will instantly create all feasible transactions, subject to the specified date constraints. Last Execution column will display the most recent date on which the transaction-generating algorithm was executed. The Next Execution column will indicate the earliest future date on which a transaction is scheduled to occur, based on the frequency and last execution date.Next Execution date, the Generate Transactions command will have no effect.The information pane of the Investment Plans view provides a comprehensive list of all the transactions that have been automatically generated from the selected investment plan in the main pane. It's important to note that this list does not include any manually created purchase transactions on this security. The information pane is specifically designed to display only the generated transactions that result from the implementation of an investment plan, allowing for easy monitoring and analysis of the plan's performance.
You can edit or delete some or all of the generated transactions without affecting the plan itself. For instance, a generated purchase will probably not reflect the actual buying price, as it is based on the closing quote of the day. You may need to modify the details, e.g. the purchase price of a generated transaction after it has been created.
If the most recently generated transaction is deleted, the Last Execution field in the main pane will also be cleared.
The chart menu in the Investment Plans view is identical to the chart menu in the All Securities menu. The same applies to the Historical Prices.
"},{"location":"reference/view/accounts/security-account/","title":"Security Accounts","text":"The Securities Accounts view provides a dual-pane view of all security accounts within the portfolio. The main pane features a list of all securities accounts, while the information pane presents details about the selected account in the upper panel.
Figure 1. Example of Securities Accounts.
"},{"location":"reference/view/accounts/security-account/#main-pane","title":"Main pane","text":"A security account will hold your securities and will be used for trading. Use the data tools icon to add a new account. For each account, the total market value of its assets is displayed as Volume of security deposits. A securities account is most often named after the broker or bank that you use for buying or selling. But other variants are possible. For example, you could collect all your bitcoin investments into a separate account crypto or you can differentiate between your account and that of your partner.
It is worth noting that, although the portfolio has four deposit accounts (see figure 1 in the Deposit Accounts section), only one of them, named Deposit Account, is set as the reference account. This reference account is used for handling trades when no other account is explicitly assigned. The information pane (bottom panel) shows the Statement of Assets view for the selected security account.
The information pane features four tabs: Statement of Assets, Transactions, Chart, and Holdings.
The Statement of Assets tab, depicted in Figure 1, is selected by default. It includes details such as the number of shares, the name and ISIN of the asset, the latest price or Quote, the purchase value, the total market value (computed as shares multiplied by Quote), and the percentage of the asset in the total portfolio. It is the same table as in the menu View > Reports > Statement of Assets but limited to the selected security account.
With the Show or hide columns icon, you can add numerous other fields such as purchase price, dividends, and many more. These fields are described in full detail in View > Reports > Statement of Assets. The Export Data as CSV icon allows you to save the displayed table as a CSV-file.
This section presents a table that lists all transactions related to the chosen Securities Account. The table offers in-depth information about each transaction, such as the date, transaction type, security involved, quantity, price, fees, and other pertinent data. See View > Accounts > All Transactions for more information on the available fields and how to customize the table with the data tools.
"},{"location":"reference/view/accounts/security-account/#chart","title":"Chart","text":"The Chart tab presents a specific line graph, displaying the market value over time of the selected account (e.g. Brokerage Account in Figure 2), the invested capital since the first transaction in this securities account, and the delta (difference) between those two.
Figure 2. Chart from Securities Account (information pane).
Clicking on any point in the chart will reveal the actual data of all three time series. With the data tool, you can also add the Taxes (Accumulated) and Fees (Accumulated) time series to the chart. Please refer to the section on the User Interface for more guidance on customizing the chart.
The Holdings chart from the Securities Account doesn't have any data tools. It's very similar to the portfolio holding chart; see View > Reports > Statement of Assets > Holdings. Clicking any part of the chart will reveal some additional information.
Figure 3. Holdings Chart from Securities Account (information pane). {class=pp-figure}c
"},{"location":"reference/view/accounts/security-account/#one-or-more-security-accounts","title":"One or more security accounts?","text":"Should you create only one security account to hold all your transactions?
Historical exchange rates and a Currency Converter can be found under the menu View > General Data. More than 5O currency combinations such as EUR/AUD (see Figure 1) are provided. These exchange rates are retrieved from The European Central Bank (ECB) and go back until the year 1999 when the EUR was introduced on the financial markets. They are in fact reference rates and will probably differ slightly from the real transaction rates that your broker or bank will use. Only a chart can be displayed; no numerical data. The context menu of the chart is described elsewhere.
Figure 1. Exchange Rates and Currency Converter.
Note
You can download a CSV file with all exchange rates going back to 1999 at Euro foreign exchange reference rates webpage; scroll down to time series.
Figure 2. Currency Converter.
The second tab in Figure 1 displays the Currency Converter (see figure 2). With this tool you can convert any amount from the base currency to a counter (quote or term) currency for a specific date. In the foreign exchange (forex) market, currency pairs are commonly depicted as XXX/YYY where the XXX is the base currency. One unit of the base currency XXX is worth YYY units of the counter currency. For example, on March 20, 2024 the exchange rate EUR/USD = 1.0844 means that 1 EUR is worth 1.0844 USD.
Since EUR/USD = 1.0844, it follows that USD/EUR = 0.9222. Which quotation would you prefer? This depends a bit on your domestic currency (the one you use every day) and your preference for multiplication or division.
As a result, there are two types of quotation: direct (or price) quotation versus indirect (or quantity) quotation. By default, PP assumes the latter one, but you can change the quotation type with the menu Help > Preferences > Presentation menu.
You can display both types by clicking the Switch currencies button located beneath the date field in figure 2.
Settings is a submenu under View > General Data. Five sub-panels or tabs are available.
Most financial websites offer the option to search for a specific security. For instance, by clicking on the search box at https://www.ariva.de/, you can locate a security based on its name, WKN, or ISIN.
Figure 1. Defining additional attributes.
The bookmarks defined in the settings panel serve to streamline this process. You can then Open in Browser any security by right-clicking on that security or transaction. The required attribute for that website will be automatically embedded in the URL, guiding you to the appropriate webpage on the financial site.
The list contains several examples. On the forum, many more are suggested along with some workarounds.
Using the New Bookmark icon (top right), you can add custom bookmarks for your personal situation. A line named \"New Bookmark\" is added to the list with the URL http://example.net/{tickerSymbol}?isin={isin}&wkn={wkn}&name={name} (see Figure 1, last line). Double click name or URL to change the value. You need to inspect the original website to figure out how to form a correct URL. For example, finance.yahoo.com requires a URL like https://finance.yahoo.com/quote/NVDA to retrieve the webpage of NVIDIA. Using the placeholder {tickerSymbol}, the URL will be dynamically populated with the appropriate symbol for the chosen security during runtime.
Figure 2. Context menu of the bookmarks page.
The available placeholders are listed in the context menu (accessible via right-click) on the bookmarks page under the \"Insert replacement\" option (see figure 2): {isin}, {name}, {wkn}, {tickersymbol}, and {tickersymbolprefix}. In the ticker format XXX.YY (for instance, DTE.DE), XXX corresponds to {tickersymbolprefix}, and xxx.YY represents {tickersymbol}. For some websites, you may need only the {tickersymbolprefix}.
With this context menu, you can manage the bookmark list.
All securties view is a better approach. -Move up: moves a bookmark one line up in the list; for example to sort the bookmarks in a particular order.New attributes or fields can be defined for Securities (see Figure 2), Deposit Accounts, Security Accounts, and Investment plans. Besides the attributes which are already defined in the Security Master data such as Name, ISIN, Quote Feed, ..., Figure 2 contains six additional attributes such as logo, Total Expense Ratio, ....
Figure 3. Defining additional attributes.
You can create new custom attributes for yourself with the New Attribute with field type icon (top right). Clicking on it will display a subpanel with the available data types (see Figure 2). For example, the existing \u00c0ctive attribute is probably of type Yes/no, while the name attribute should be of type Text.
These additional attributes can be made will be visible in any table view concerning securities and in the panel Additional Attributes of a Security. These attributes cannot be used in calculations, but you can sort the list with them.
"},{"location":"reference/view/general-data/settings/#attributes-deposit-accounts","title":"Attributes: Deposit Accounts","text":""},{"location":"reference/view/general-data/settings/#attributes-securities-accounts","title":"Attributes: Securities Accounts","text":""},{"location":"reference/view/general-data/settings/#attributes-investment-plans","title":"Attributes: Investment plans","text":""},{"location":"reference/view/reports/performance/","title":"Performance","text":"Key performance and risk indicators are summarized in a dashboard, along with a calculation widget. The dashboard can be accessed through the menu View > Reports > Performance or with the sidebar (see figure 1).
Figure 1. Dashboard with key performance and risk indicators and calculation widget.
Please note that the performance and risk indicators are always calculated for the entire portfolio and for a specific reporting period. By default, this is one year from today. You can change the period by selecting a different one or create a new one in the drop-down (top-right). In Figure 1, the reporting period is from Jun 12, 2020 till Jun 12, 2023. For the performance key indicators, the color green indicates a profit, while red signifies a loss.
The cumulative True Time-Weighted Rate of Return (TTWROR) is the geometric average of the daily returns within the reporting period. For each day within the reporting period, the daily return is calculated using Equation 1. The cumulative return is computed with Equation 2.
$$\\mathrm {r_{daily} = {\\frac{MVE + CF_{out}}{MVB + CF_{in}} - 1 {\\qquad \\text{(Eq 1)}}}}$$
and
$$\\mathrm {r_{cum} = [(1 + r_1) \\times (1 + r_2) \\times ... \\times (1 + r_n)] - 1 {\\qquad \\text{(Eq 2)}}}$$
where MVE = the market value of the asset at the end of day, MVB = the market value at the beginning of the day (or the end of the previous day). CFin and CFout represent the net incoming or outgoing cashflows for the day. When a stock pays a dividend, that's an outgoing cashflow from the stock's perspective. A deposit (for buying the stock) is a cash inflow, as is paying the associated fees.
An in-depth explanation of the TTWOR calculation is given Concepts > Performance > True Time-Weighted Rate of Return. A step-by-step calculation for a very simplified example can be found at View > Reports > Performance > Chart.
"},{"location":"reference/view/reports/performance/#internal-rate-of-return-irr","title":"Internal Rate of Return (IRR)","text":"The money-weighted rate of return or IRR of a reporting period is the annual interest rate that is necessary to bring the market value of the investment at the beginning of the period (MVB) and all subsequent cash flows to the market value (MVE) at the end of the reporting period. To generate the specified cash flows within the given time period, your portfolio must grow each year by a percentage equal to the IRR. The base formula for the IRR calculation is:
$$\\mathrm{MVE = MVB \\times (1 + IRR)^{\\frac{RD_1}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} \\qquad \\text{(Eq 3)}}$$
where n = the number of cash flows in the reporting period, $CF_t$ = cash flow at time t within the period, and $RD_t$ = the number of remaining days within the period. For MVB, the $RD_t$ equals the entire period, representing the period length in years. You can simplify the equation by treating the MVB as the initial cash flow. A cash flow is any amount of money that is added to or withdrawn from an investment. For an in-depth explanation, see Concepts > Performance > Money-Weighted Rate of Return.
"},{"location":"reference/view/reports/performance/#absolute-change","title":"Absolute Change","text":"The absolute Change is the difference between the market value of the portfolio at the end date of the reporting period (MVE) and the market value at the beginning (MVB).
$$\\mathrm{MVE - MVB\\qquad \\text{(Eq 4)}}$$
For example, in Figure 1 (calculation widget), the absolute change equals the Final Value (426.82 EUR) minus the Initial value (0 EUR).
"},{"location":"reference/view/reports/performance/#delta","title":"Delta","text":"The Delta value (for the reporting period) is equal to the Absolute Change (see above) minus the external cash flows that occurred in the period.
$$\\mathrm{(MVE - MVB) + \\sum_{t=1} ^{n}CF_t {\\qquad \\text{(Eq 5)}}}$$
For example, the Delta in Figure 1 is 120.82 EUR. This value represents the actual return of securities in the portfolio. The absolute change in the portfolio is partly caused by external cash inflows (306 EUR to buy the securities). This money comes from an external source and should be subtracted from the Absolute change. They are summarized as Performance neutral Transfers in the calculation panel.
"},{"location":"reference/view/reports/performance/#last-day","title":"Last Day","text":""},{"location":"reference/view/reports/performance/#last-day-true-time-weighted-rate-of-return","title":"Last Day: True Time-Weighted Rate of Return","text":"One would assume that the Last Day is the same as the ending day of the reporting period. Unfortunately, it is not. It is the previous trading day before 'today' as can be seen when hovering over the label. Figure 1 is created on December 8, 2023. The market value of the portfolio was at that time 459.31 EUR. The last trading day before this date is 2023-12-07 with a MV = 455.84 EUR. There are no cashflows on the last day.
The TTWOR for that day is given by Eq. 1 or (459.31 - 155.84)/455.84 = 0.76%.
Equation 3 can be used to calculate the Absolute Change of the last day. It's obvious that the value equals 3.47 EUR = 459.31 EUR - 155.84 EUR.
Risk refers to the possibility of losing some or all of the invested capital or not achieving the expected return from your investment. Several indicators are provided to measure the risk.
"},{"location":"reference/view/reports/performance/#maximum-drawdown","title":"Maximum Drawdown","text":"Maximum drawdown (MDD) refers to the largest peak-to-trough decline in the performance of a portfolio or investment over a specific period, typically expressed as a percentage. It measures the extent of loss incurred from the highest point to the lowest point before a new peak is reached.
With View > Reports > Performance > Chart you can create a graph of the cumulative performance of your portfolio, accounts, or specific securities. Figure 1 displays the portfolio performance for the reporting period 2020 - 2023.
Figure 2. Cumulative performance of portfolio with indication of Maximum Drawdown .
The largest drawdown occurs between August 18, 2021 and March 8, 2022. Cumulative performance dropped from 22.04% to - 4.12% (see Figure 2). The MDD for the reporting period of Jun 12, 2020 till June 12, 2023 is 21.44% (see Figure 1). Hovering with the mouse over the value (the label displays the reporting period) will reveal the dates.
"},{"location":"reference/view/reports/performance/#maximum-drawdown-duration","title":"Maximum Drawdown Duration","text":"The MDD Duration is the worst or longest amount of time an investment has been between peaks. This is 292 days or between August 18, 2021 and June 6, 2022. The longest recovery period (duration from a low to a peak) is 90 days or between March 8, 2022 and June 6, 2022.
"},{"location":"reference/view/reports/performance/#volatility","title":"Volatility","text":"Volatility in portfolio performance refers to the degree of variability in the returns of a portfolio over time. It is a measure of the risk or uncertainty associated with the portfolio's future performance. A portfolio with high volatility will have returns that fluctuate widely over time, while a portfolio with low volatility will have returns that are more consistent.
The volatility shown in Figure 2 is 31.33% (refer to Figure 1). It represents the standard deviation of daily returns during the reporting period. To be precise, it is calculated by taking the natural logarithm of (1 + daily return) and then multiplying it by the square root of the total number of days in the reporting period. Notably, weekends and holidays are excluded from this calculation. An efficient method to obtain all the daily returns is by exporting the return/volatility chart as a CSV file.
"},{"location":"reference/view/reports/performance/#semivariance","title":"Semivariance","text":"The Semivariance exclusively considers the negative fluctuations of an investment. The semivariance value is 22.63% (refer to Figure 1), with weekends and public holidays disregarded. Hovering over this value with the mouse provides additional information.
In instances where negative and positive fluctuations are balanced, the formula Volatility (v) = Semi-variance (s) x sqrt(2) applies. For a dataset evenly distributed as depicted in Figure 2, the semivariance would be calculated as follows: s = v / sqrt(2) = 31.33% / sqrt(2) = 22.15%.
Given that the actual semivariance is slightly lower than the estimated semivariance (22.15% < 22.63%), it suggests that the returns are not symmetrically distributed, and the negative returns slightly outnumber the positive ones.
"},{"location":"reference/view/reports/performance/#configuring-the-dashboard","title":"Configuring the dashboard","text":"By default, the Performance dashboard contains three columns: Key Indicators, Risk Indicators, and Calculation (see Figure 1). Each column can contain several configurable widgets: data blocks comprising a label and a numerical value or diagram; e.g. Absolute Change or a Performance chart. Right mouse click on an empty space in a column lets you manage the widgets, e.g. adding a widget. Right clicking the widget label lets you manage the specific widget; e.g. change the data series or reporting period. (see later).
Figure 3. Yearly Overview dashboard.
Widgets are a very powerful tool to customize the dashboard to your liking. A thorough introduction is given in a YouTube video by Finanzkoch (German spoken but English subtitles are possible). A list of very nice dashboards by fellow investors can be found at the forum.
Figure 4. Creating a new dashboard.
The best way to experiment is by creating a new (empty) dashboard (see Figure 3). Click on the icon New dashboard at the left of the reporting period. You can choose between a blank dashboard, key indicators (= the default dashboard), and Earnings (see Figure 4). To remove a dashboard from the menu, click the arrow next to the name and choose Delete. You can move the dashboard to the first in the list (bring to front), rename the dashboard, or make a duplicate of the selected dashboard.
A dashboard contains one or more columns; the dashboard of Figure 3 contains 6 columns. You cannot see the borders of the column. Delete a column by right-clicking in the area. You can add a new column with the configure dashboard gear icon (top right). If there is already at least one column, you can also right-click in a column area and choose New column on the left, New column on the right, or Duplicate column (see Figure 5). With Column width you can increase or decrease (step wise) the column width of the selected column. Of course, the width of the other columns is affected since the total width of the windows stays the same. With the Option Apply to All, you can set the reporting period and the data series for all widgets in the dashboard.
The New Widget option reveals a submenu featuring six categories of widgets (refer to Figure 5). Below is a description of each widget. Right-clicking on the widget label will reveal a context menu. Most widgets feature options such as Edit label, Delete, and Height. You can drag and drop widgets within and between columns. Press the CTRL key (Windows) to duplicate instead of moving.
Figure 5. New Widget menu with overview of all available widgets.
"},{"location":"reference/view/reports/performance/#common","title":"Common","text":"Current date: The text \"Current Date\", followed by the system date of the computer in the language and format, set in Help > Preferences > Presentation > Language.
Exchange rate: An exchange rate in the format XXX/YYY number. Right-click to choose the specific exchange rate, e.g. EUR/USD.
Trading activity: A graph depicting time (per year and per month) is plotted on the X-axis, while the count of trades is represented on the Y-axis. With the context menu, you can add or remove the Y-axis, change the reporting period (by default the period of the dashboard is taken), or change the trading type (by default buy, sell, delivery inbound, and delivery outbound), and the filter (by default the entire portfolio).
Securities: Limit price exceeded: You can set a limit price per security in the security master data (see how-to). If the current price (as of today; independent of the reporting period) of the security exceeds the limit price, the name of the security, the current price and the limit will be displayed, as well as displaying shares with dates only in the past or only in the future.
Securities: Date reached: As with limit price (see above), you can link a \"special\" date to a security as an additional attribute. This widget will exhibit the text Securities: Date reached (xxx), where xxx represents the count of securities for which today's date exceeds the date set for the security. Additionally, a list of share names and dates will be provided. This list can be sorted from the context menu.
Securities: Latest Price. This is a single line widget with the current price of a security; which can be chosen from the context menu. The label will mention the name of the selected security.
Website: A textbox containing the content of a website; specified by an URL in the context menu. Anchors are allowed; for example https://help.portfolio-performance.info/en/concepts/performance/#the-money-weighted-rate-of-return. The height of the widget can be increased with the context menu.
Security: Distance from ATH: The difference of the current price with the All Time High (ATH) price of the security, measured in %. The security should be specified with the context menu.
Vertical spacer: This widget produces an invisible rectangle that occupies space. It is used to visually separate widgets (vertically). Hovering over the widget with the mouse will reveal its label. With right-click, you can change its height.
All widgets, except the last three, are single line text widgets.
Total: The market Value of the asset at the end of the reporting period. The asset and the reporting period can be specified with the context menu.
Absolute change, Delta (for reporting period), Delta (since first transaction) : see above for definition of these terms.
Performance-neutral transfers: these transfers are explained in View > Reports > Performance > Calculation.
Invested Capital (for reporting period) and Invested Capital (since first transaction): The Invested capital in a portfolio of stocks refers to the total amount of money that has been invested in the portfolio.
Ratio: This widget computes the proportion between two assets; for instance, Share 1 / Entire Portfolio.
Statement of Assets - Chart: This widget produces a mini version of View > Reports > Statement of Assets > Chart. If multiple chart view are defined, they can be selected with the context menu.
Statement of Assets - Holdings: Pie chart which is a mini version of View > Reports > Statement of Assets > Holdings.
Taxonomies: Pie chart illustrating the proportional distribution of the taxonomy categories.
The first three widgets are single line text; representing the common performance indicators.
True Time-Weighted Rate of Return (cumulative), True Time-Weighted Rate of Return (annualized), and Internal Rate of Return (IRR) are the known single line performance indicators. The data series and reporting period can be selected in the context menu.
Performance Calculation: A fully collapsed table, similar to View > Reports > Performance > Calculation; first panel. The categories cannot be expanded.
Performance Chart: This widget produces a mini version of View > Reports > Performance > Chart. With the Aggregation context menu, one could set the level of detail (daily, weekly, monthly, quarterly, or yearly).
Monthly returns in a heat map: A heatmap is a graphical representation of data that uses color-coding to visualize the performance of different stocks in a portfolio. A heatmap typically consists of a table or matrix, with each cell representing the monthly performance of a selected asset. The color of each cell corresponds to the performance of that stock.
Yearly returns in a heatmap: Each cell in the heatmap represents one year.
Portfolio Tax Rate: The ratio of taxes / (realized and unrealized capital gains + earnings - fees).
Portfolio Fee Rate: The ratio of Fees / (realized and unrealized capital gains + earnings).
All five widgets are single line text widgets, representing common risk indicators. See above for an explanation of Maximum Drawdown, Max Drawdown Duration, Volatility, and Semivariance.
Figure 6. Setting the risk-free return from the context menu. The Sharpe ratio is a financial metric that measures the performance of a portfolio compared to a risk-free asset, taking into account the portfolio's risk. It is calculated by subtracting the risk-free return from the portfolio's return, such as the Internal Rate of Return (IRR), and then dividing the result by the standard deviation of the portfolio's return, which is a measure of its volatility.
The risk-free return is set by default to 0%, but this can be adjusted through the context menu to reflect your current risk-free rate. As the ratio is based on volatility, complete historical prices are required. Without complete prices, the calculated volatility may be underestimated.
"},{"location":"reference/view/reports/performance/#earnings","title":"Earnings","text":"Transactions overview: A table displaying the monthly earnings, comprising dividends, interest, or both individually. The year can be adjusted using a spin button located at the top of the widget.
Monthly earnings: A table displaying the monthly earnings. The year should be set with the context menu.
Number of trades with profit/loss: A single-line widget presenting the total number of trades in grey color, along with an upward-pointing green arrow + counter indicating the number of trades with profit, and a downward-pointing red arrow indicating the number of trades with loss.
Trades Profit/loss: The total net value of the trades in the reporting period. Green color used for profits, red for loss. Assets and reporting period could be set with the context menu.
Average holding period: The average holding period is calculated as follows: All trades are included that were in the portfolio at some point within the selected reporting period. The holding period of each security is the difference between the time of purchase and sale. Immediate sales are assumed for positions currently held. The position weight is calculated from the purchase price of the position relative to the total number of all purchase prices. The Average holding period is the sum of the products \"holding period x percentage position weight\" across all positions. The metric could be displayed in days or in years.
Portfolio Turnover Rate: The Portfolio Turnover Rate measures how much (in money) of the portfolio was \"replaced\" throughout the holding period, as a fraction of the average portfolio value. A turnover of 100% means that all money invested in the portfolio is since then replaced.
Monthly investments, Monthly fees, and Monthly taxes: A table illustrating the total amount of investments, fees, or taxes. The rows correspond to the years, while the columns represent the months, making each cell a monthly record within a year.
More detailed information about the performance calculation could be found under the menu View > Reports > Performance > Calculation or in the sidebar. The main pane contains the title bar icons (top right) and seven tabs or panels: Calculation, Assets at Start, Assets at End, Earnings, Earnings by Account, Taxes, and Fees. The information pane displays detailed information about the item that is selected in the main pane.
Figure 1. Calculation panel.
"},{"location":"reference/view/reports/performance/calculation/#main-pane","title":"Main Pane","text":"Figure 2. Filter menu.
The title bar (top right) displays the chosen Reporting period (named 2023in Figure 1 & 2), and some utility icons. The Filter Data by portfolio and Reference account lets you narrow down the info shown for either the whole portfolio or a specific securities account, alone or with its associated deposit account. By default, it's set to Entire portfolio. You can only pick one filter option. You can also make your own New filter by choosing accounts to combine and giving it a name. They are listed below the defaults. The option Manage... lets you edit or delete custom filters. Just select the filter name and use the right-click menu to add additional accounts or delete the filter. Clicking the triangle reveals the chosen accounts, which you can delete individually. The option remove entries will delete all custom filters.
Using the Export Data as CSV icon, you can save each panel as a CSV file. This is useful for performing calculations, such as comparing Assets at Start and Assets at End, in a spreadsheet program. The columns in the CSV file match the headings of the panel, such as Shares, Name, Symbol, Quote, ....
The Configure view icon provides only one option, named Pre tax. A check mark is added when selected.
The calculation panel (see Figure 1) contains the initial and final value of the selected account or portfolio and all the different categories of changes that lead from the former to the latter. You can collapse or expand a single category or all categories at once with the context menu (right-click). A fully collapsed version of this panel is also displayed as a widget in the parent Performance menu.
Initial Value: This represents the balance of the portfolio (or selected account) at the beginning of the reporting period. As can be seen from figure 1 & 2 the reporting period is set to the year 2023. It's important to note that this value is fixed at the end of the day, meaning transactions from the first day are not included. You can verify the Initial Value and its components in the Assets at Start panel (Figure 3). In terms of our performance equations, the MVB symbol (Market Value Begin) refers to this value.
Figure 3. Assets at Start panel.
Between Initial and Final Value are the different categories of changes that lead from the former to the latter: Capital Gains, Earnings, Fees and Taxes, Cash Currency Gains, and Performance Neutral Transfers (see Figure 1).
Capital Gains: A capital gain or loss refers to the increase or decrease in the value of a capital asset, such as stocks, bonds, or real estate, between the time it is purchased and the time it is valued or sold. In the latter case, the term \"Realized Capital Gain\" is used. For each security remaining in the portfolio, the absolute gain or loss is calculated. It is important to stress that the gain or loss is expressed in the portfolio's currency; not the currency of the asset. If the asset is denominated in a foreign currency, any gain or loss due to fluctuations in the exchange rate is accounted for and indicated in the column thereof foreign currency gains. Hovering with the mouse over the value will display a pop-up with a more detailed calculation. For example, take the calculation of share-3 (see Figure 1 - information pane):
However, this loss is exacerbated by the change in the exchange rate. The 100 AUD purchased on Jan 1, 2023, were valued at 63.72 EUR, whereas on December 31, 2023, they were valued at only 61.49 EUR. Thus, quote price remaining unchanged, your investment (expressed in EUR) decreased already by -2.33 EUR due to the difference in the exchange rate. The total capital loss of -17.60 EUR is partly caused to the currency exchange loss of -2.33 EUR.
Realized Capital Gains: refer to the profit or loss that occurs when an investment is sold for a price different from its original purchase price. The hypothetical capital gains or losses, as described above are then realized. There is only one realized capital gain in Figure 1. On April 12, 2023, 5 shares of share-1 are sold for 5 x 22.40 EUR/share = 112 EUR (excluding fees and taxes). At the time of MVB (December 31, 2022), they were valued at 5 x 18.638 EUR/share = 93.19 EUR. The realized capital gain is thus 112 - 93.19 = 18.81 EUR. It's worth noting that share-1 was purchased in two batches: 10 shares on January 15, 2021, at 15 EUR/share and 5 shares on January 14, 2022, at 16 EUR/share. Due to the FIFO principle that PP implements, the 5 shares that were sold are those from the first batch of 10. If we had considered a longer reporting period, thus including the initial purchase, the valuation of the sale would have been determined by the purchase price of the initial acquisition, not the second one.
Earnings: Profit generated by the investment, consisting of dividends and interest. As can be seen in Figure 4, a dividend of 30 EUR (including fees and taxes) was paid for share-1. It was deposited in a cash account. That same cash account earns an interest, paid on July 1, 2023.
Figure 4. Earnings panel.
A summary per account with a breakdown of dividend, interest, total earnings, fees, and taxes is provided by the Earnings by Account panel.
Fees and taxes: Fees are charges imposed by banks, brokerage firms or investment platforms for their services. Taxes are levies imposed by the government on investment income. Fees and taxes are mostly recorded at the transaction itself (buy, sell, dividend, interest) but they can also be booked as a separate transaction. For example, the one euro tax on the separate interest transaction is recorded as Other in Figure 1. The taxes on the purchase and dividend of share-1 are summed as 12 EUR.
Figure 5. Taxes and Fees panel.
Cash Currency Gains: read the following section about Performance neutral transfer first to better understand this topic. Since some deposits and investments are made in a foreign currency, e.g. AUD, cash currency gains or losses could occur. Some of losses are made at sale time. For example, (see above capital gain). There is also a loss on the remaining deposit since Jan 1, 2023 on the AUD cash account. Since only 100 AUD was needed for the purchase, the remaining 400 AUD remains on the cash account. The loss on this deposit was 100 x (0.6372 - 0.6149) = 8.93 EUR
Performance Neutral Transfers: A transfer refers to money that flows into or out of the portfolio; also named cash flow (CFin and CFout) in our performance equations. This could be a deposit or removal (withdrawal) into or out of a deposit account. It could also be a delivery of securities into or out of a securities account. In the example of Figure 1, there is one deposit of 500 AUD at the beginning of 2023. Given an exchange rate of 0.6372 AUD/EUR, this constitutes a neutral transfer of 318.61 EUR.
There was also a delivery of 5 x 20 USD shares on July 1. Given the exchange rate transfer of 0.9203 USD/EUR, this results in a neutral transfer of 92.03 EUR. Taken together, there was a performance neutral transfer of 410.64 EUR in 2023.
Note
The term Neutral transfer stresses the fact that the transfer (of money or stock) on its own doesn't influence the performance. When an investor deposits money into their cash account, they are simply adding to the available cash balance. No profit has been made so far. The other categories (capital gains, earnings, fees & taxes, cash currency gains) are transfers that do impact your profit or performance. They are not neutral to performance.
Final value: The final value represents the valuation of the chosen account or portfolio at the end date of the reporting period. Figure 6 provides a breakdown with the end value of each asset held within the portfolio or account. The final value corresponds with the MVE symbol (Market Value Begin) in our performance equations.
Figure 6. Assets at End panel.
The information pane offers comprehensive details about the selected security in the main pane. It's essentially identical to the information pane in the All securities view, with the only distinction being the absence of the Data quality submenu.
The menu View > Reports > Performance > Payments presents an overview of payments per period. A payment constitutes a transfer of money into an account, encompassing dividends, interest, fees, and taxes. The view is structured as a table with periods arranged in columns, instruments (accounts and securities) in rows, and an aggregated summary payment allocated per cell. Utilizing the primary and secondary menu at the top, you can specify the payment type and the period selection (refer to Figure 1).
All payments are denoted in the default portfolio currency, such as EUR as illustrated in Figure 1. Payments made in a foreign currency undergo automatic conversion using the currency exchange rate applicable on the payment date. For instance, the Interest Charge of 13 AUD on 2023-08-01 is converted to 7.85 EUR utilizing the conversion rate of 0.6040 AUD/EUR.
Figure 1. Payments overview.
"},{"location":"reference/view/reports/performance/payments/#primary-menu","title":"Primary menu","text":"Reporting period: In the primary menu (far right), you can select the overall reporting period. Utilize the drop-down Since xxxx to designate the time period; for instance, since 2023. When combined with the sub-period selection (e.g., Month), this could potentially result in numerous columns in the main pane. Indeed, four years would yield 48 columns.
The filter function operates identically to that in the Performance > Calculation view, allowing you to refine the information displayed for either the entire portfolio or a specific securities account, either alone or in conjunction with its associated deposit account.
The Export Data as CSV function exports the monthly, quarterly, and yearly table view, as well as the transactions view. The chart diagrams cannot be exported.
The Configure icon enables you to reverse the column order (from Jan > Feb > Mar > ... to Mar > Feb > Jan), display only the first year of the list of years since xxxx, and consolidate inactive securities. The consolidation results in a new line \u2211 Retired securities, summarizing (consolidating) the results of all inactive securities into one row. By default, both active and inactive securities are listed.
Type of payment
Interest Charge. If both payments occur in the same period, the net value of (Interest - Interest Charge) is displayed.Taxes,Tax refund, Fees, or Fees refund. If payment and refund occur in the same period; the net value is displayed.dividends + net interest + net fees + net taxes.The secondary menu (below the primary) allows you to adjust the layout of the main pane. The first three options enable you to select a table view per month, quarter, or year; marked with the green line in Figure 1. The following four options will present the same data but in the form of a graph (blue line). The last two options (orange line) provide detailed information. Clicking the header of a column will sort the rows in ascending or descending order.
Since xxxx) is divided into months, with one column per month. The first and last columns contain the names of the instruments, which could be securities and/or deposit accounts. The filter option (see above) allows you to restrict this view to certain accounts. A sum is provided for each column (month) and for each row (instrument). As mentioned before, this view could be exported as a CSV file.Since xxxx) is divided into quarters with one column per quarter. The instrument column is only displayed once.Year/Instrument: Similar to the previous description, but organized by year instead of month. The number of displayed years depends on the selected reporting period (Since xxxx).
Figure 2. Dividend payments per year since 2022.
As can be seen by comparing Figure 1 and Figure 2, the value for the first security in 2023 is the sum of the monthly payments (19.80 = 7.38 + 12.42).
Month: A bar chart of the Month/Instrument view with the months (Jan - Dec) on the X-axis, the payments on the Y-axis, and the years represented by differently colored bars with a corresponding legend. Figure 3 depicts a bar chart illustrating the monthly dividend payments since 2022, derived from the tabular view shown in Figure 1.
Figure 3. Bar chart of monthly dividend payments since 2022.
Quarter and Year: Similar to the monthly bar chart but organized by quarter or year.
Overview: a special kind of 'boxed' view, with a box for each year and month, containing the number of transactions and the total amount of payments in that period (see Figure 4).
Figure 4. Box view of monthly dividend payments since 2022.
Transactions: A list of all transactions related to the selected type of payment in the primary menu. For instance, after choosing the Dividends and Year/Instrument options in the primary and secondary menu, the main pane will display the total dividend payment per year. If you wish to identify the transactions that lead to these dividend payments, you can switch to the \"transactions\" option in the secondary menu.
With the menu View > Reports > Performance > Chart or the sidebar, you can generate a graphical representation of the relative performance of your assets over time.
The x-axis represents time, and you can select the desired time period using the dropdown menu in the top-right corner. By default, the periods of 1 year, 2 years, 3 years, 4 years, 6 years (from today), and the previous day are available. Additionally, you have the option to create a custom time period using the 'New' feature; see Reporting Period for a description.
The y-axis displays the cumulative performance as a percentage from the beginning of the reporting period; indicating how much the asset value has increased or decreased compared to the previous period (daily, weekly, monthly, quarterly, or yearly). For a daily report, the formula could be written as:
$$\\mathrm {r_{daily} = {\\frac{MVE + CF_{out}}{MVB + CF_{in}} - 1 {\\qquad \\text{(Eq 1)}}}}$$
and
$$\\mathrm {r_{cum} = [(1 + r_1) \\times (1 + r_2) \\times ... \\times (1 + r_n)] - 1 {\\qquad \\text{(Eq 2)}}}$$
where MVE = the market value of the asset at the end of day, MVB = the market value at the beginning of the day (or the end of the previous day). CFin and CFout represent the net incoming or outgoing cashflows for the day. When a stock pays a dividend, that's an outgoing cashflow from the stock's perspective. In fact, the MVE should be increased by this amount. Should this stock be sold on the day, you would receive the MVE + dividend! A deposit (for buying the stock) is a cash inflow. Paying the associated fees is also a cash inflow, as they are paid externally to the stock. The MVB, which is initially zero, should be increased by these sums. One does not acquire magically the stock for nothing.
Taxes are usually NOT** considered as cash inflows because they represent a mandatory payment to the government. Investors have little control over taxation and the performance of their investment should ideally remain unaffected by it. In contrast, fees typically represent upfront costs incurred during the buying or selling of stocks. Taxes on investments, however, typically come into play upon selling the investment, exerting their impact on performance more noticeably at the conclusion of the investment cycle.
"},{"location":"reference/view/reports/performance/performance-chart/#calculation-method","title":"Calculation method","text":""},{"location":"reference/view/reports/performance/performance-chart/#simplified-example","title":"Simplified example","text":"Let's start with a very simplified example without cashflows (see Figure 1). You purchased 10 shares on January 1, 2023. The quote of share-1 fluctuates between 9 and 17.
Jan 1: the market value of your asset at the beginning of the day is zero (MVB = 0). You haven't purchased any stock yet. The market value at the end of the day MVE = 90; you have purchased 10 shares a 9 per share. For that, you made a deposit or CFin = 90. There are no fees or other cash flows. According to equation 1, the daily performance = [(0 + 90)/90] - 1 = 0. The cumulative performance is also (1 + 0) - 1 = 0.
From Jan 2 until 1 until March 31, the daily performance remains at zero because there are no incoming or outgoing cashflows and MVB = MVE e.g. (90/90) - 1 = 0. The performance is solely driven by the historical prices.
On April 1, the price increases from 9 to 15 per share. Thus, MVB = 90 and MVE = 150 and the daily performance = (150/90) - 1 = 0.6667 or 66.67%. The cumulative performance from the beginning of the reporting period is also [(1+0) x (1+0) x ... x (1+0.6667)] - 1 = 0.6667 or 67.67%.
On July 1, the price drops to 14 per share. The daily performance for that day is (140/150) - 1 = -0.0667 or -6.67%. The cumulative performance however becomes [(1+0) x (1+0) x ... x (1+0.6667) x (1+0) x ... x (1-0.0667)] - 1 = (1.6667 x 0.933) - 1 = 0.5555 or 55.55%.
Figure 1. Simplified example to calculate the performance (%) without cashflows.
"},{"location":"reference/view/reports/performance/performance-chart/#complex-example","title":"Complex example","text":"Now, let's introduce some complexity as depicted in Figure 2. The initial purchase includes both fees and taxes. On May 1, a dividend is paid. Subsequently, there are additional taxes or fees along with refunds.
Jan 1: the performance drops from 0% on December 31 to -6.25% on Jan 1. As in the previous example, MVB = 0 and MVE = 90. However, there are two CFin: a deposit and a fee payment. Taxes are not taken into account. According to Eq 1, the daily r = [90/(0 + 90 + 6)] - 1 = -0.0625 or 6.25%. The cumulative performance is the same (1 - 0.0625) - 1 = -0.0625
From Jan 2 until 1 until March 31: the daily performance becomes zero and the cumulative performance remains at -6.25% (see above for an explanation).
On April 1, the historical quote increases to 15 per share. There are no additional cashflows. The daily performance = (150/90) - 1 = 0.6667 or 66.67%. The cumulative performance becomes: [(1-0.0625) x (1 - 0) x ... x (1 + 0.6667)] - 1 = 0.5625 or 56.25%.
A dividend is paid on May 1. This represents a CFout. Only the net value of this cashflow (8) is taken into Eq 1, giving the daily performance = [(150 + 8)/(150] - 1 = 0.0533 or 5.26%. Because most daily performances are zero, I will leave them out in the formula for the cumulative performance = [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533)] - 1 = 0.6458 or 64.58%.
July 1, historical price decreases to 14 per share. The daily performance becomes (140/150) - 1 = - 0.06667. The cumulative performance decreases to [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533) x (1 - 0.0667)] - 1 = 0.5360 or 53.60%.
The taxes (50) on Aug 1 have no effect on the daily or cumulative performance, which remains at 53.60%.
The fee or CFin on Sept 1 does have an effect. The daily performance = [140/(140 + 20)] - 1 = - 0.125. The cumulative performance decreases to [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533) x (1 - 0.0667) x (1 - 0.125)] - 1 = 0.3440 or 34.40%.
Figure 2. Simplified example to calculate the performance (%) with cashflows.
"},{"location":"reference/view/reports/performance/performance-chart/#user-interface","title":"User interface","text":"The user interface of View > Reports > Performance > Chart is quite comparable to the chart interface of View > Reports > Statement of Assets > Chart. We cover only the differences in this section; see link above for the common features.
The gear icon (top right) provides an additional type of data series, called Add benchmark ... (see Figure 3). A benchmark is a security from which only the historical prices are taken to calculate the daily and cumulative performance. Figure 3 displays two benchmarks are displayed: the MSCI World index and share-1 (benchmark). For more information on indexes and benchmarking, refer to How-to > Benchmarking your portfolio.
Please note that the share-1 (benchmark) graph is identical to the one in Figure 1, where cash flows such as dividends and fees were not taken into account. Since the daily historical prices of the MSCI World index exhibit slight daily variations, the resulting curve appears somewhat more irregular.
Figure 3. Adding a benchmark to the performance chart.
Figure 4. Export CSV.
In addition to the Export chart data and Save diagram, already available in Statements of Assets chart, the 'Export data as CSV' button, located in the top right corner, enables you to export each data series or benchmark separately as a CSV file. Only the series that are currently displayed on the chart can be exported. For example, to validate the calculations discussed previously, you can display and export the share-1 data series. In the exported CSV file, you will find the numerical daily and cumulative performance values for each day.
Another addition to the Statement of Assets chart, is the 'Interval' drop-down with choices: daily, weekly, monthly, quarterly, or yearly. In the previous examples, we computed the daily (cumulative) performances. Exporting share-1 data series as csv-file with a quarterly time interval will produce the following table.
Date Value Cfin Cfout Daily % Cumulative % 2022-12-31 0 0 0 0 0 2023-03-31 90 96 0 -6.25 -6.25 2023-06-30 150 0 8 75.56 64.58 2023-09-30 140 20 0 -18.33 34.41 2023-12-31 120 0 0 -14.29 15.21 2024-01-01 170 0 0 41.67 63.21To calculate the performance of the second quarter, you need to know the values of MVB, MVE, CFin, and CFout. MVB is the market value of share-1 on March 31, which is 90 (see Figure 1). MVE is the market value on June 30, which is 150. If you look closely at the transaction list of Figure 2, you will notice that there is only one CFout: dividend minus fees on May 1 (8). There are two CFin: deposit and fee on Jan 1 (96) and another fee on September 1 (20). The second quarter only contains the CFin. Following Eq 1, the quarterly performance (of quater 2) is: [(150 + 8)/90] - 1 = 0.7555 or 75.56%. The cumulative performance is[(1 - 0.0625) x (1 + 0.7556)] - 1 = 0.6458 or 64.58%.
Please, refer to View > Reports > Statement of Assets > Chart for a description of the other features such as zooming, adding data series, context menu of the canvas and legend, and others.
"},{"location":"reference/view/reports/performance/securities/","title":"Securities","text":"While the Reports > Performance menu gives you the most important key performance indicators on portfolio level such as IRR and TTWROR, the Reports > Performance > Securities menu provides you with much more detail on security level. However, it's important to understand the difference; especially in terms of cashflows (see section on performance).
Figure 1. Overview of Performance > Reports > Securities.
"},{"location":"reference/view/reports/performance/securities/#main-pane","title":"Main Pane","text":"The Reports > Performance > Securities menu contains a main pane (top) and an information pane (bottom) of the selected security from the main pane. Performance calculation is always dependent on the chosen Reporting Period, which could be set with the drop-down at the top-right.
The first Filter group (top right) allows you to narrow down the securities list to shares \u2260 0 or shares = 0. The latter filter will display only those shares that have been completely sold, where the number of purchased shares has dropped to zero. Without either of these filters, all shares, regardless of quantity, are displayed. The second filter group is also detailed in the Performance > Calculation menu, allowing you to choose either the entire portfolio or specific individual accounts.
The Export as CSV file option will save the current table, including only the visible columns, as a CSV file.
The Show or Hide columns icon provides access to the entire (lengthy) list of available fields that can be displayed.
Purchase value: The small icon preceding the heading name indicates that this concept deviates from the more common Bying price. When hovering over the column heading with the mouse, a small popup will appear, explaining the meaning of the concept. The purchase value of the available shares (at valuation time) is calculated using the FIFO (First-in/First-Out) method and includes transaction fees and taxes. For share-2 in Figure 1, this calculation is relatively straightforward. On September 30, 2022, eight shares were purchased at a quoted price of 16 EUR/share, totaling 67 EUR, which includes 3 EUR of transaction fees and taxes.
Hovering over the purchase value of share-1 will display a transaction history (refer to Figure 2), which is more complex. On January 15, 2021, ten shares were purchased for 155 EUR (including fees and taxes). Of these 10 shares, 5 remain after the sale on April 12, 2023, valued at 77.50 EUR (half of the original 155 EUR). A second purchase of 5 shares was made on January 14, 2022, for 84 EUR, bringing the total purchase value to 161.50 EUR at the time of valuation.
Figure 2. Purchase Value.
Purchase price: As with the Purchase Value, this is the calculated buying price, taking into account multiple purchases and sales. For example, the five remaining shares of share-1 from the first purchase were priced at 15 EUR excluding fees and taxes. The second purchase of 5 shares was priced at 16 EUR (excl fees and taxes). The weighted average purchase price is [(5 x 15) + (5 x 16)]/10 = 15.50 EUR.
share-1.In addition to the default visible columns described above, several other fields can be added (see Figure 3).
Figure 3. Available fields Securities.
Purchase Value (Moving Average): By default, PP employs the FIFO method to value the stock inventory. Under this method, upon sale, the stock that was first purchased will also be the first sold, leaving the more recent purchases as the remaining stock. In a rising market, this means the most expensive shares remain and performance appears to be more favorable, especially when compared to the LIFO method.
In the moving average method, no assumptions are made regarding which securities will be used upon a sale. It could be the first purchased, the last, or some randomly chosen shares. The weighted average price of the stock is calculated. As new stock is purchased, this weighted average moves towards the price of the newly purchased stock.
With a single purchase, such as with share-2, there is no difference between the two methods. The Purchase Value (default column) and Purchase Value (Moving Average) will be the same: 67 EUR. However, the difference becomes evident at the time of sales with a multiple purchase stock, such as share-1. The default FIFO method calculation amounts to 177.50 EUR (refer above for calculation details). The (simple) moving average methodis calculated as follows: initially 10 shares at 15.5 EUR/share (inclusive of fees and taxes) and later 5 shares at 20 EUR/share, resulting in [(10 x 15.5) + (5 x 20)] / (10 + 5) = 17 EUR/share. The remaining 10 shares after the sale are valued at 170 EUR.
ISIN, Symbol, WKN, Note: see Reference > File > New Master data.
Dividends: By default the sum of dividends is displayed.
share-1: 30 / 177.50 = 16.90%.share-1: 30 /170 = 17.65%.share-2 has no dividend payments; so the value is none. And, because, there is only 1 dividend payment for share-1, it is for the time being unknown. If there are multiple payments, the periodicity could be anual, semi-anual, quarterly or monthly.share-1: 190.06 - 177.50 = 12.56 EUR. share-1: 190.06 - 170 = 20.06Capital Gains: for a more detailed explanation of capital gains; see section on Reports > Performance > Calculation.
share-1 is 37 EUR. The five shares are sold for the gross value of 112 EUR; while the purchase value (without fees and taxes) was 75 EUR. The realized gain is thus 37 EUR. () Figure 4. Realized gains for share-1.
share-2 hasn't been changed since the first purchase. So, the realized gains are zero EUR. The share has been purchased on September 2022 for 64 EUR (without taxes and fees). At the end of the reporting period (June 12, 2023) the market value is 11.76 EUR. The unrealized gains are 47.76 EUR. The only cashflows that matter from a portfolio perspective are the deposit/removal transactions on a cash account OR the money value of the Inbound/Outbound Deliveries of securities into a securities account. Only money from these transactions flow into or out of the portfolio.
From a security (account) perspective, the performance of a security is influenced by the value (price) of Buy or Sell transactions or the equivalent Inbound or Outbound Deliveries. The payment of a dividend is considered as a cash inflow into the security (increasing the performance), as are Fees refunds. Paying fees on security transactions however will decrease the performance and will reduce the cash flow as a result of the Buy/Sell or Inbound/Outbound Delivery.
Taxes are an exception. In PP they are considered as performance neutral, when viewed from the security perspective.
Quotation\" generally refers to the price of a single security or commodity at a specific point in time, as quoted on an exchange or by a market maker. In contrast, \"valuation\" refers to the process of determining the overall worth or value of a portfolio of securities or assets, taking into account various factors such as market conditions, financial performance, and future growth prospects.
"},{"location":"reference/view/reports/performance/trades/","title":"Trades","text":"A trade refers to the act of buying or selling a financial security, such as a stock or bond. In PP, this can be executed through buy/sell transactions as well as through Inbound or Outbound Deliveries.
Figure 1. The Reports > Performance > Trades view.
In the Reports > Performance > Trades menu, an open trade is constructed by consolidating all buy/Inbound Delivery transactions associated with a particular security. Hence, an open trade may encompass several buy transactions. Conversely, each sell or outbound delivery transaction generates one individual closed trade. For example, in Figure 1, share-1 is characterized by one sell transaction, depicted by the first closed trade (row 1), and two buy transactions, consolidated into the open trade (row 2).
With the Filter menu, you can limit the list of trades to Only open trades or Only closed trades. If neither is selected in this group, all trades are displayed. In the second group, you can choose between Only profitable trades or Only lossmaking trades; essentially the green colored versus the red colored rows.
The Export as CSV icon contains one export, named Trades which represents the table from Figure 1. Fields added or removed with the Settings icon will also be added or removed in the CSV-file. Most of the available fields are already shown in Figure 1.
(open) if there are still securities left in the portfolio.# transactions: The number of transactions in a trade is typically one (buy) or two (buy + sell). Hovering over the cell near the icon will trigger a pop-up displaying additional information. From Figure 2, it can be deduced that 5 shares of share-1 were sold on April 12, 2023. Hovering over the open trade (row 2) will reveal that 5 shares were purchased on January 15, 2021, and another 5 on January 14, 2022. Here, you can observe the FIFO principle in action. The five sold shares are subtracted from the first purchase, which initially consisted of 10 shares.
Figure 2. Info overlay closed trade share-1.
Shares: The number of shares in the trade.
Entry value: This represents the Net Transaction Value (NTV) of the trade, which includes fees and taxes. For an open trade with a single buy transaction, this is the NTV of the purchase. For example, if 3 shares of share-3 are bought at 413.64 USD per share with 50 USD in fees and taxes, the Net Transaction Value after conversion at a rate of 0.9384 USD/EUR is 1211.40 EUR. For a single buy/sell trade like share-2, the Net Transaction Value of the original purchase (67 EUR) is distributed over the open trade of 5 shares (41.88 EUR = 67/8 * 5) and the closed trade of 3 shares (25.13 EUR).
The situation is more complex with the multiple buy/sell trade of share-1. The entry value (161.50 EUR) of the open trade is formed by 5 shares from the first purchase and 5 from the second, following the FIFO principle. The original Net Transaction Value of the purchase of 10 shares on January 15, 2021, was 155 EUR. The second purchase of 5 shares had a net transaction value of 84 EUR. Combined, 161.50 EUR equals (155/2 + 84).
Entry value (per share): Enable this column by using the Settings (gear) icon. The value can be easily calculated by dividing the Entry value by the number of shares.
share-2 is 12.405 EUR/share. The exit value is 5 x 12.405 = 62.03 EUR. For closed trades, the exit value is the Net Transaction Value of the sale. For instance, if share-2 was sold on April 15, 2024, for 3 shares x 12.48 EUR/share minus fees & taxes (4 EUR), the exit value is 34.46 EUR.Holding period (days): For single purchase closed trades, it equals the number of days between the End and the start date. For open trades, it is the difference between today and the Start date. This calculation does not consider weekends, holidays or any other calendar.
Note
For multiple purchase trades, the holding period is an average, weighted by the number of shares. For example, assuming today is 2024-04-22, then the holding period for the first purchase in Figure 2 is: (2024-04-22 - 2021-01-15) = 1193 days and for the second buy 829 days. The weighted average is [(5 x 1193) + (5 x 829)]/10 = 1011 days.
Latest Trade: Enable this column using the Settings (gear) icon. It typically contains either the End Date for closed trades or the Start date for open trades. An exception is an open trade with multiple buy transactions, in which case the date of the last transaction is used.
Additionally, the following columns can be made visible using the Settings (gear) icon: Securities Account, ISIN, Symbol, and WKN. Explanation of these fields can be found at the description of the master data of the security.
The IRR and Return column represent the performance of the open or closed trade. Please note that you cannot set a Reporting period explicitly. The Reporting period of a trade is always between today and the start date of the trade. The column Holding period (days) gives an indication of the number of days between these two dates.
In the section Reference > Basic concepts > Performance > Money-weighted return an extensive calculation of the IRR of open and closed trades is given (using the same example of share-1 as above).
In summary, given the IRR equation: $\\mathrm{MVE = MVB \\times (1 + IRR)^{\\frac{RD_1}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} \\qquad \\text{(Eq 1)}}$
Closed trade (share-1): 105 EUR = 77.50 EUR x (1 + IRR)^(817/365). An IRR of 14.53% will solve this equation exactly. To reach an Exit value of 105 EUR, it would require an initial Entry value of 77.50 EUR to grow at a compound annual interest rate (IRR) of 14.53%, over a period of 817 days.
Open trade (share-1): The open trade has two cashflows (buy). Hovering over the Transactions cell will reveal the data (see Figure 2). The holding period for the first buy is 1193 days = (2024-04-22 - 2021-01-15) and for the second buy 829 days = (2024-04-22 - 2022-01-14). The IRR equation becomes: 216.10 EUR = 77.50 EUR x (1 + IRR)^(1193/365) + 84 EUR x (1 + IRR)^(829/365) or 11.12%. Please note that the holding periods and Exit value will change upon trying this example on a later date.
The Return column is in fact a simple return or the TTWROR with a single subperiod. It is the result of Exit value/Entry value or Profit/loss/Entry value.
The Statement of Assets report provides a snapshot of your portfolio's assets (securities, accounts) at a specific point in time. The default date is the current day. You can choose a different date with the \"Time machine\"; the calendar icon at the top right. Figure 1 lists all transactions of the demo-portfolio up to October 5, 2023. Figure 2 displays the Statement of Assets report as of this date.
Figure 1. List of All transactions of demo portfolio (2023-10-05)
In addition to the purchase of share-1, share-2, and bond-1, there is also a sale of a portion of share-1. In this latter transaction, no deposit is made, and the proceeds from the sale remain in the deposit account.
Figure 2. Statement of Assets report of demo portfolio (2023-10-05)
The report in Figure 2 displays all the available assets on October 5, 2023, including the deposit account with the result of the sale of share-1. The securities are valued at their market prices based on the closing quotes from the previous day, which is -in this case- October 4, 2023. Share-2 is handled in USD. The conversion to EUR is based on the exchange rate provided by the ECB on October 4, 2023 (closing previous day).
The report displays a total line above and below the assets. With the Presentation option (see Figure 3 bottom), you could add or remove the Total lines. The default setting is above and below. Since no taxonomy has been added to the demo portfolio, all assets are listed as Without classification.
Figure 3. Available columns. The default columns that are displayed are Shares, Name, Symbol, Quote, Market Value, Share in %, and Note. Many more columns/fields are available (see Figure 3). While the column headings are mostly self-explanatory, a few of them may require further clarification. You can customize the default columns using the gear icon located in the top-right corner (see Figure 2).
The abbreviation \"MA\" that follows Purchase Price/Value stands for \"Moving Average\" but in fact it should be better called WA or \"Weighted Average\". As mentioned in the discussion about Purchase Value, PP uses the FIFO (First-in, First-out) method to calculate prices and values. \"Moving/weighted average\", however, is another commonly used method.
The Purchase Price and the Purchase Price (MA) of share-1 are respectively 44.41 EUR and 51.61 EUR; a rather big difference. Why? From Figure 2:
What is the Purchase Price of the remaining 40 shares in the portfolio?
The available fields under Performance and Dividends are discussed in a separate chapter.
With the Attributes option, you can add custom fields to the table. These fields are defined in left sidebar > settings > Attributes: Securities and following panels. You can enter a specific attribute value for a security in the Additional attributes panel of the security (see for example, Figure 3 in Getting started > Adding securities)
The Forex (Foreign Exchange) option allows you to view the currency of the quote for each asset and its exchange rate relative to the base currency of the portfolio. The fields labeled as Market value**, Purchase Price**, and Profit/Loss** retain the same meaning as their counterparts in the base currency, but they are presented in the foreign currency.
For instance, let's consider share-2, which is traded in USD. In the default view, the Market Value is expressed in EUR. If you wish to view that value in USD instead, you can achieve this by adding the Market Value** field.
The Distance to SMA is a metric that measures the difference between the current price of a share and the average price of that share over a specified number of past days. The acronym \"SMA\" presumably represents \"Simple Moving Average.\"
When you choose to include this column, you'll also need to specify a period, such as 5 days, 20 days, 50 days, or 200 days. Suppose that you want to know the \u0394 to SMA5 (Distance to SMA for a 5 days period) of share-1. The last 5 available prices are: 71.96, 72.00, 72.42, 73.52, and 74.50 EUR; including the latest available on October, 5 (= 71.96 EUR). The calculation is carried out as follows:
Distance to ATH (All Time High) is a likewise metric that shows how far the current price is from the highest price in the specified period. For example, the highest price of share-1 in the last year was 77.4 EUR. The current price is 71.96 EUR. So the \u0394 ATH 1 year (Distance to ATH for a 1 year period) is equal to (71.96 - 77.4)/77.4 or -7.03%.
Using the Reset Columns option in Figure 3, you can revert to the default arrangement of columns. It's advisable to keep this layout as the Standard view, which is represented by the first button at the top (see Figure 1). By clicking the triangle icon next to the button, you can access options to rename, duplicate, or delete the current view.
If you find yourself needing a custom layout regularly, you can duplicate the standard view, give it a new name, and customize it to your preferences. Additionally, there is a New View button available to create a new view based on the default setup.
To the right of the New button, there is a currency selection button. It should be labeled with the base currency of the portfolio, but you have the option to choose other currencies. All calculated fields such as Market Value are then converted to the selected currency.
The Filter icon located in the top right corner allows you to filter the assets that will be used in the calculations. You have several options:
Additionally, you have the option to create a custom filter. To do this, you will need to make a selection from all the available assets within the portfolio.
"},{"location":"reference/view/reports/statement/holdings/","title":"Statement of Assets \u203a Holdings","text":"A visual representation of the total value of the portfolio divided into categories such as different accounts is given by the Holdings chart (menu View > Statement of Assets > Holdings or with the sidebar). A doughnut chart displays the proportion of different accounts within the total, with the entire doughnut representing 100%.
Figure 1. Doughnut chart of the total value of portfolio.
Hovering the mouse pointer over a segment of the doughnut chart reveals the following account details: name, percentage, number of shares, current share price, total value in the portfolio currency. In the case of a deposit account, the number of shares is fixed at one (see Figure 1).
Positions with negative values, such as a deposit account with a negative balance, are not displayed. By not displaying positions with negative values, the chart's percentages may be inaccurate. An error message alerts users to this situation.
With the filter icon (top right), you can show the entire portfolio or only a few combinations of accounts; for example broker-1 with or without its associated deposit account broker-1 (EUR). You can create a new filter, rename or remove existing ones.
For a portfolio with a large number of securities, the chart can become unreadable, and it's advisable to implement a filter.
"},{"location":"reference/view/reports/statement/statement-chart/","title":"Statement of Assets \u203a Chart","text":"Using the menu View > Reports > Statement of Assets > Chart or the sidebar, you can generate a graphical representation of the value of your assets over time.
The x-axis represents time. You can select the desired reporting period using the dropdown menu in the top-right corner. By default, the periods of 1 year, 2 years, 3 years, 4 years, 6 years, and the previous day are available. Additionally, you have the option to create a custom time period using the 'New' feature; see Reporting Period for a description. Unlike the performance chart (found under View > Reports > Performance > Chart), you cannot adjust the time interval in this chart, as it is fixed at 1 day.
The y-axis displays the total value of your assets, denominated in the portfolio's default currency. Larger numbers are condensed by adding 'k', where 1k equals 1000 units of the portfolio currency. You can adjust the scale of this axis by scrolling with the middle mouse button. Hold the mouse position at the value (e.g. 4k) where you want to increase or decrease the scale around.
Figure 1. Chart of the Total value of the demo portfolio.
The canvas is a graphical representation of one or more data series. A data series typically comprises a set of paired data points presented in a table format, such as dates and their corresponding values. By default, two data series are displayed: 'Transferals' (primarily deposits) and 'Total' (see below for an explanation of all possible data series). When you left-click the canvas and hold the mouse down on a specific day, for example, March 28, 2022, a dialog box will appear, displaying detailed values for all data series on that day.
Right-clicking on the chart canvas provides additional options (see Figure 1).
Right-clicking on the legend icons (for example, the blue and red squares from Figure 1) will give you access to additional formatting options. For all types of data series and their legend entries, you can modify the Color, Position (Send backwards, Send to back or Bring forward, and Bring to Front), and Sort (A-Z or Z-A). The latter two options will reorganize the legend entries accordingly. In the case of a line-type data series like the Total value, you can also adjust the Line Style (solid, dash, dot, ...), and the Show Area option (which fills the area below the data series). In addition, you have the option to either hide (where the legend entry remains visible, but the data series is not displayed on the chart) or remove the series altogether (both the legend and data series are removed from the chart).
Figure 2. Data series for chart.
Using the gear icon located at the top right, you can reveal additional data series on the chart. Once a data series is added to the chart, it will no longer be visible in the list of Figure 2. Remember that in the demo-portfolio, we have two brokers; where broker-1 has two deposit accounts (EUR and USD). Broker-2 has only one EUR-deposit account.
With the Accounts and Portfolios option, you can choose to display specific combinations of accounts, such as broker-1 along with its USD deposit account. Select the appropriate option and hold Ctrl to add more selections. Once you've added a data series, it will no longer appear in the list of available data series in Figure 2, but you'll find it checked in the gear menu. You can remove a data series from the chart by unchecking it in the gear menu or by deleting it from the legend (as explained above).
The Common option in Figure 2 will display some additional info.
Delta (for reporting period or since first transaction): represents how much the portfolio's value has increased or decreased from the beginning of the reporting period until the end or from the first transaction until the end of the period. This Delta will fluctuate around zero, for example for the first transaction day the delta will be zero. The chapter on Reporting Period explains that the valuation of a portfolio can differ according to the selected Reporting Period.
Dividends, Earnings (= dividends + interests), Fees, Interest, Interest Charge, and Taxes are available in both accumulated and 'instance' versions. For example, an 'instanced' dividend will be represented as a spike, whereas the accumulated version will display a graph that steadily increases as dividends accumulate over time. These fields are described in Transactions and are recorded as part of each transaction.
Invested Capital (for reporting period or since first transaction): the term \"invested capital\" refers to the total amount of money that an investor has used to purchase various securities, such as stocks, bonds, or other financial instruments. It includes the initial purchase price of the securities, additional investments made over time, and other factors such as fees, taxes, ...
Total: the total value of the portfolio valuated over time.
Transferals: each Deposit or Removal is represented by a very small spike (positive or negative) on the day that the transferal was made.
With securities, you can make a graph of each separate or combination of securities in your portfolio, for example share-1 or share-1 + bond-1.
In the default configuration, the Standard view only includes two data series: Total and Transferals. However, you have extensive customization options, as mentioned earlier. Using the dropdown menu, you can Duplicate, Rename, or Delete this view. You can also create a new view by clicking on the New icon, located in the top right corner between the Standard and Period options. Similar to the existing one, you can duplicate, rename, or delete your newly created view. If you wish to have this view as the leftmost view, select the Bring to front option from the dropdown menu.
As the name implies, this list contains all the securities you are monitoring (\u2260 purchased). To view the securities currently in your portfolio accounts, navigate to Reports > Statement of Assets.
Figure 1. View All Securities.
This view contains two panes. The main pane is a list of all available securities. You can select multiple securities, but only one of them can be active. The information pane features a graph of the active security.
"},{"location":"reference/view/securities/all-securities/#main-pane-list-all-securities","title":"Main pane: list All Securities","text":"Figure 2. All available columns.
The main pane represents essentially a table with all the available securities listed. Click the column heading to sort the table based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column. You can rename or hide a column with the context menu (right-click on the column header). Adding, deleting or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). The default columns are shown in Figure 1; they are also checked in Figure 2. Figure 2 gives a list of all available columns.
Refer to the glossary for a definition and short explanation of the columns. Note that the column heading is sometimes different from the field name e.g. \u0394 amount and that several fields are collapsed into a single category e.g. Data Quality.
Figure 1 represents the Standard view. A view keeps a record of the visible columns, their widths, column headings, and the sorting order of the table. By clicking the triangle icon next to the button, you can access options to duplicate, rename, or delete the current view.
If you find yourself needing a custom layout regularly, you can duplicate the standard view, give it a new name, and customize it to your preferences. The newly created view will be placed to the right of the Standard view. Or you can use the New View button (left of the Search box) to create a new view based on the default setup.
With the Search box you can filter the list of visible securities. For example, entering \"DE\" in the Search box will only display share-1 and share-2 because their ticker symbol contains the string \"DE\".
The Filter icon is used as a more categorical filter. Available options are: Only active instruments,Only inactive instruments, Only securities, Only exchange rates, Shares held \u2260 0, Shares held = 0, and Securities: Limit price exceeded. For the latter, you need to create a new attribute of type \u201climit price\u201d in the settings of the portfolio (menu View > Settings). Then you can add this column to the table and enter some values.
The table displayed in the current view can be exported as a CSV file, preserving the number of rows and columns along with their (custom) column headings.
By dragging the divider bar, you can adjust the size of the main pane, making it larger or smaller. You can even extend it to completely occupy the canvas or hide it entirely. The divider bar becomes visible when hovering over with the mouse.
"},{"location":"reference/view/securities/all-securities/#information-pane","title":"Information pane","text":"The information pane showcases by default a graph or chart of the active security, namely the last one selected in the main pane (refer to Figure 3). The graph is updated each time a different security is selected in the main pane.
Figure 3. Graph of active security from main pane.
"},{"location":"reference/view/securities/all-securities/#chart-menu","title":"Chart menu","text":"The Chart menu turns orange when selected and displays a line graph/chart of the active security. To the right of the graph, detailed information about the security is displayed such as ticker symbol, latest price, .... With the vertical divider, you shrink or expand this area to show more or less of the graph. Drag the divider all the way to the right to completely hide this section. The divider bar becomes visible when hovering over with the mouse.
With the reporting period menu, you can set the time frame of the graph; going from 1 month (1M) until 10 years (10Y). This period is always measured from today minus the period. The x-axis of the chart is subdivided into months (1M, 2M, and 6M), quarters (1Y and 2Y), 2 quarters (3Y), or years (5Y and 10Y). You can also select the YTD (Year-to-Date) option; from January 1th of this year until today. The option H stands for the complete holding period of the security (=from the purchasing date until now), while A displays \"All available data\"; from the first until the last historical price.
If you click and hold on the graph, you can view the date and price of the security at that particular moment. If there are additional markers, such as number of shares or a time series like the Simple Moving Average (SMA), they will also be displayed. To sort these entries by value, you can press the Alt key and click.
Clicking on the first icon (crosshair) of the reporting period menu displays a large crosshair above the graph. The origin (0,0) is at the mouse position of the click. The vertical axis will reveal the position on the x-axis or the exact date. The horizontal axis will display the historical price of the security on that day.
With the second icon (Measure distance) you can determine the exact number of days between two points on the chart. It also displays the difference in historical price and the corresponding percentage between the two points.
Figure 4. Context menu of the graph.
Both options can also be accessed by the context menu (right-click on the graph).
Figure 5. Configure chart (gear icon).
With Configuration chart icon (gear at the top right) you set numerous additional data on the graph. Figure 5 displays the collapsed view.
Marking: Additional symbols can be incorporated onto the graph to convey specific information or highlight key data points.
Show limits: before enabling this option, one has to create a new Security Attribute of type Limit Price. You should also add this attribute as an Additional Attribute to your security. Enter as limit for example > 17 (see Figure 6). An orange horizontal bar will appear at the value of 17.
Figure 6. Chart with limit price indication.
Indicator
The Historical Quotes menu in the information pane reveals a two-column table displaying the date and quote of the selected security in the main pane (see Figure 6). Clicking on a column header will sort the table in ascending or descending order based on that column. You can rearrange the columns by dragging the header.
Double-click on the date or the quote to modify its value. Be careful when changing the date, as the new quote will overwrite any quote registered for that date.
Utilize the \"Export data as CSV\" feature (icon to right) to save the entire table as a CSV file. The context menu (right-click) offers various management options.
Figure 7. Context menu of Historical Quotes in the information pane.
Add: This option enables you to input the date and corresponding quote for the security. You can add quotes for any valid date, even in the future.
Delete: To delete one or more rows, make a selection. For a consecutive selection, click the first row, press Shift, and click the last row. For a non-consecutive selection, use the Ctrl key. Utilize the context menu to delete the selected rows.
Delete All: This command removes all historical quotes in the table. Note that this action cannot be undone.
Quotes: this heading conceals several additional options (see Figure 6). Many of these options can also be executed from another context, e.g. menu.
Update quotes online: Shortcut for the menu Online > Update quotes (selected security).
Debug: Show server response: If the security is linked to an online data provider, you can view the HTTP response from that server.
Configure online update ...: this option will display the Securities attributes form with the Historical Quotes tab selected; see File > New.
Search for suppliers of historical prices ...: displays the first step of the File > New wizard.
Import from CSV file ...: This command is equivalent with the File > Import menu. The CSV file must contain at least two columns.
Import HTML table ...: This option lets you import a table with historical Quotes that you can find on a webpage. Some examples are given (see Figure 7). {#import-html-table}
Figure 8. Import HTML table from context menu Historical Quotes.
For example, navigate to https://www.finanzen.net/historische-kurse/nvidia. You could also search for the security at the homepage. Enter a start and end date and a marketplace. NVIDIA is listed on XETRA. Click on Suchen (Search). Right-click the table and select View Page Source in the contaxt menu. Copy and paste everything in the PP. - Create manually: This command is identical with the Add option above.
Export to CSV file ...: This command is identical with the Export button (top right).
Create historical quotes from transactions: If a security has transactions (buy or sell), the quote price associated with these transactions can be included into the historical prices. The transaction price takes precedence and will overwrite any existing historical quote on that date.
Delete latest price:
Round historical prices to X decimal places: When rounding a value like 99.994 to two decimals, the result will be 99.99, whereas the value of 99.995 will round up to 100.00. Keep in mind that it's not possible to round a number to a higher precision than originally available. Attempting to round the previous number to 4 decimal places, for example, will not change the number.
Figure 1. Context menu of a selected security.
The context menu of a security contains several additional options that are not available within the view menu. You can access the context menu by selecting a security or a security view (e.g., securities account) and right-clicking. A pop-up, as shown in Figure 1, will be displayed.
A stock split increases the number of outstanding shares by issuing additional shares to current shareholders. It does not alter the company\u2019s overall value but adjusts share prices thereby making the stock more accessible to investors.
For example, an Amazon share has risen to a value of about \u20ac\u00a02300 at the beginning of 2022. Amazon approved a 20-for-1 stock split; going into effect on June 6, 2022. In a 20-for-1 stock split, every share of the company\u2019s stock will be split into 20 new shares, each of which would be worth one twentieth of the original share value.
PP currently supports stock splits via a trick that is not 100% clean; see the discussion on the forum. Essentially, it retroactively assumes that the shares have always been split. In the aforementioned scenario of a 20-for-1 stock split, the historical share prices before June 6, 2022, are adjusted to 1/20 of their previous value, while the quantity of units in transactions is multiplied by 20. Please, refer to How-to > Recording Stock split for more detailed and background information.
Selecting the Stock Split option will initiate a wizard that will guide you through three steps to execute the split. In Step 1 you define the instrument, the split date, and the split ratio.
You can use the drop-down menu to select the security if it's not already filled in. The Ex-date (execution date) is the date when the stock exchange first trades the split shares at the adjusted price. For instance, in case of the Amazon split, the Ex-date would be June 6, 2022. Additionally, you'll need to specify the split ratio, such as 20-for-1. It's worth noting that these ratios can also be decimal numbers.
Figure 2. Split stock wizard - step 1.
Step 2 will show you the impact of this stock split on each transaction (buy, sell, delivery, dividend). In this case, there was only one buy transaction before the split date. It is not necessary to have a recorded transaction on the security to perform a Stock Split.
You can skip this step and maintain the transactions unchanged by unchecking the Convert transactions option. In this scenario, you can adjust the historical prices in the following step while leaving the quantity of securities unaffected.
Figure 3. Split stock wizard - step 2.
Step 3 will show you the converted historical prices. If you don't want to change the historical prices, uncheck Convert historical quotes. It's important to note that only prices before the split date will be changed; e.g. Quote (new). Prices after the split will naturally be automatically adjusted correctly by the exchange market.
Figure 4. Split stock wizard - step 3.
In the chart view of the historical prices, a small dashed vertical line will indicate the Stock split. With the menu Configure Chart > Marking > Events (Gear icon) you can toggle this line. You can also delete the event in the Events tab in the bottom panel; see Events. This will remove the marker in the chart but will NOT remove the split from the transactions and historical prices.
Figure 5. Result of Split stock wizard (Amazon).
"},{"location":"reference/view/taxonomies/","title":"Taxonomies","text":"Figure 1. Adding taxonomies.
A taxonomy is a tool for categorizing and evaluating the investments within your portfolio. This classification system creates a framework that helps you to better understand the composition of your investments and make informed decisions.
Taxonomies typically group securities based on shared characteristics such as industry, sector, geographical region, market capitalization, or asset class. By organizing your investments in this manner, you can more easily identify risks and opportunities such as overrepresentation or underrepresentation in a specific segment.
PP offers several predefined and widely recognised taxonomies or templates. You can also create your own custom taxonomy.
Asset Classes: The following classes are distinguished: Cash, Equity, Debt, Real Estate, and Commodity.
Industries (GICS): The Global Industry Classification Standard (GICS) was developed by MSCI in collaboration with S&P Dow Jones Indices. It contains 11 Sectors (e.g. Information Technology), 24 Industry Groups (e.g. Software), 69 Industries (e.g. IT Services), and 158 Sub-Industries (e.g. IT Consulting); see website.
Industries (GICS, Sectors): This template covers only the top-level Sectors classification of GICS (see above); not the Industry Groups, ....
Industry: Another Industry classification with sectors such as Construction industry, Biotechnology, Chemistry, Energy, and many more.
Asset Allocation: Classification into Risk Free assets (e.g. Deposit accounts) and Risk based assets. The latter category is further divided into Regions, such as USA, Western Europe, and others.
Regions: Purely geographic classification into Europe, America, Asia, Africa, and Oceania with the individual countries.
Regions (MSCI): The MSCI Regions taxonomy differentiates between Developed markets (Australia, Austria, Belgium, ...), Emerging markets (Brazil, Chile, China, ...), and Frontier and standalone markets (Argentina, Bahrain, Bangladesh, ...)
Type of Security: Differentiates between Stock, Equity Fund, Exchange Traded Fund (ETF), Bond, Stock Option, Index, and Currency.
Each of the taxonomies can be customized to suit your investment needs. To make changes, use the context menu to add or delete entries. Additionally, you can double-click on the name of a category to rename it.
"},{"location":"reference/view/taxonomies/managing-taxonomies/","title":"Managing taxonomies","text":"When creating a new portfolio, initially, no taxonomies are displayed in the sidebar (refer to Figure 1, top left). In theory, there is no restriction on the number of taxonomies that can be added. However, in most cases, two or three taxonomies should be sufficient. These taxonomies will be listed not only in the sidebar but also in the View menu.
Figure 1. Adding taxonomies.
"},{"location":"reference/view/taxonomies/managing-taxonomies/#adding-a-new-taxonomy","title":"Adding a new taxonomy","text":"Click the green plus button or use the File > New > Taxonomy menu to add a new taxonomy to your portfolio. You can then utilize one of the predefined templates or create a new taxonomy (see Figure 1), which can be based on one of the existing templates. Choose Empty taxonomy if you want to start from scratch and define all categories and sub-categories yourself. Give the new taxonomy a descriptive name. Two taxonomies can have the same name, which is, of course, not ideal. Click \"OK\" to add the taxonomy in the sidebar.
The context menu of the taxonomies list allows you to rename, copy, or delete existing taxonomies. You can also rearrange the order of items in the list using the the Move up or Move down options.
Upon selecting a taxonomy from the sidebar list, its structure will be displayed in the main pane (refer to Figure 2). This main pane contains two expandable lists: one for the assigned assets, which typically, but not always, shares the same name as the taxonomy (e.g., \"myTaxonomy\"), and another for the unassigned assets, labeled as Without Classification. The first list contains the categories and subcategories with their assigned assets and could be initially empty. The second list contains an alphabetically sorted list of securities and deposit accounts that have not yet been assigned to a taxonomy category.
Figure 2. Main pane of a taxonomy.
In Figure 2, both lists are expanded. The myTaxonomy list contains two categories Base currency and Foreign currencies with appropriate securities assigned. The list Without Classification contains all unassigned securities. Please note that you can assign a security to more than one category. The weight however should add up to 100%.
Figure 3. Context menu.
If you selected an empty taxonomy, you must first add categories and subcategories before assigning securities to them. Use the Add new classification context menu to create a new classification (see Figure 3). If you select a subcategory, the new classification will be created within it. The categories can be reordered by simply dragging and dropping them to a new location. To delete a selected category or list, use the context menu.
Selected lists can be sorted by: Type and Name, Type and Actual Value, Name, or Actual Value. As shown in Figure 2, each taxonomy category has an assigned color, which can be changed using the context menu.
To expand a category list, click the icon to the left of it, which will change to a icon. Click the downward-pointing caret to collapse the list. To expand or collapse all categories at once, use the context menu and select Expand all or Collapse all.
Taxonomies are created to classify assets into categories, allowing you, as a portfolio manager, to have a clear understanding of your portfolio's structure. To achieve this, securities must be added or assigned to appropriate categories and subcategories, comparable to adding a tag to a document for grouping purposes.
Securities can be assigned to a category in three ways:
Drag & Drop: Select the security from the 'Unclassified' list and drag it to the correct category or subcategory within your taxonomy at the top. If a category is collapsed and thus not visible, dragging the security over the parent category will highlight it with a light blue background and a black line underneath. After a moment, the category will automatically expand. You can then drop the security into the desired category or repeat the process for a deeper categorization. If your taxonomy contains many categories and/or assets, it may be more efficient to expand the entire taxonomy beforehand.
Context menu: Right-click on a category within your taxonomy and select Assign from the context menu. A list of available assets will appear, from which you can choose the appropriate security to assign to that category.
Figure 4. Taxonomies panel in Security Data window.
Without Classification list or even the All Securities view. Choose Edit from the context menu. In the tab Taxonomies, you can add the security to one or more taxonomies. As shown in Figure 4, the Daimler Truck security is added to a few predefined taxonomies, but also to the Base Currency category of our newly created MyTaxonomy. See Reference > File > New for further information.Selecting a taxonomy from the sidebar or the view menu will display the classification in the main pane. The header contains the standard data icons, a search box, the reporting period selector, and seven display options.
Figure 1. Main pane of a taxonomy.
"},{"location":"reference/view/taxonomies/using-taxonomies/#definition-view","title":"Definition view","text":"By default, the definition view displays a table with the five columns:
Weight: The weight represents the proportion or percentage that a security can contribute to its total value. A weight of 100% indicates that all securities are included in calculating the total value. This field is used in the Rebalancing view.
Color: Each category is automatically assigned a colour. You can change the colour using the context menu.
Actual Value: The market value of a security on the current day. For a category, this is the summed market value of all securities assigned to that category. For example, as of 2024-07-08, the market value of Daimler Trucks is 20 shares x 36.36 EUR = 727.20 EUR, and for Mercedes: 10 shares x 65.47 EUR = 654.70 EUR. Thus, the total value for the category is 727.20 EUR + 654.70 EUR = 1381.90 EUR. Please note that there is a significant number of unassigned securities in myTaxonomy.Foreign securities (e.g. Amazon) are calculated in the base currency.
Actual %: The percentage of a security or category, relative to its immediate parent category. For example, 727.20 EUR of Daimler represents 52.62% of the value in its immediate parent category Base Currency. The 1381.90 EUR of the Base Currency category is 27.98% of the highest category myTaxonomy.
Actual % of Total: The percentage of a security or category relative to the total value of the portfolio (including assigned and unassigned securities). For instance, the 1381.90 EUR of the Base Currency category represents only 6.25% of the total portfolio value.
With data icon gear icon, other fields could be added: Category Key, Symbol, ISIN, Note, Forex (Exchange Rate, Actual Value**), Expected return, and Attributes. The Actual Value ** is the value of the security in the original currency without any conversion.
The icon, Export Data as CSV, will save the table displayed on the screen as a CSV file.
By default, the entire portfolio is included in the table. Using the icon, you can limit the result to only securities and categories whose value is not zero or to only the active accounts/securities. The result can also be limited to the available security accounts, with or without their respective reference deposit accounts.
If you have a long table, you can use the search box. For instance, the Regions (MSCI) taxonomy is quite detailed. To find a share from Mexico, you would normally need to expand (double-click) the Emerging Markets > Americas > Mexico category. The search box offers a quicker alternative.
The Definition view provides a snapshot of the current taxonomy status. The Reporting Period (defaulting to 1 year) is therefore greyed out. Only the Stacked and Stacked Area charts utilize the time information from the Reporting Period.
"},{"location":"reference/view/taxonomies/using-taxonomies/#rebalancing-view","title":"Rebalancing view","text":"Rebalancing is a strategy of bringing a portfolio that has deviated away from one's target asset allocation back into line [Wikipedia]. Any taxonomy (such as Industries or Regions) can be used as a basis for target asset allocation. Typically, though, you would use your own classification.
Figure 2. Rebalancing view.
The first step in the rebalancing process involves entering the target Allocation for each category and the Weight of each security.
Without Classification list.The rebalancing process will calculate the target value for each category based on its allocation and the total portfolio value. If the actual value deviates from the target value, the system computes the difference (delta). It then determines how much each security within the category should be increased or decreased based on its weight.
For example, the total value of myTaxonomy is 5292.73 EUR, consisting of 1376.50 EUR from the Base Currency and 3916.23 EUR (!) from the Foreign Currency. However, the Base Currency category should be 30% of the total or 1587.82 EUR. Thus, there is a difference of -211.32 EUR (-13.31%) between the target and the actual value (see Figure 2).
To rebalance this subcategory, you would need to sell securities. For both Daimler and Mercedes, which each have a weight of 100%, you would sell 105.66 EUR worth of each security. This would correspond to approximately 2.9 securities of Daimler and 1.6 securities of Mercedes.
If, for instance, the weight of Mercedes were set to 50%, its actual value would be reduced to 336.95 EUR (instead of 653.90 EUR), and the Base Currency subcategory's actual value would decrease to 1049.55 EUR (instead of 1376.90 EUR). In this scenario, the delta would then be 440.18 EUR. This could be achieved by selling 9.7 securities of Daimler and 2.6 securities of Mercedes, considering that only 50% of Mercedes is available for sale.
"},{"location":"reference/view/taxonomies/using-taxonomies/#pie-chart","title":"Pie Chart","text":"Figure 3. Pie chart of the portfolio + zoomed-in variants.
The pie chart representing the entire portfolio in Figure 3 appears simple and incomplete because not all securities are assigned to categories within myTaxonomy. From Figure 1, it can be inferred that approximately 28% of the securities are assigned, represented by the purple-coloured segment.
By clicking on a segment of the pie chart, you can zoom in on that particular part. The second pie chart displayed in the middle of Figure 3 shows the categories within myTaxonomy, such as Base Currency and Foreign Currencies. The third pie chart specifically focuses on the Base Currency category.
Figure 4. Donut chart of the portfolio.
The donut chart represents the filtered result of the taxonomy. As such, it is the graphical representation of the column Actual % of Total in Figure 1. With the icon, you can choose to include the category Without Classification.
Figure 5. Tree map of the portfolio.
A tree map is a type of chart that uses rectangles to visualize data, where each rectangle represents a category. The size and color of the rectangle correspond to the value of the data. You can zoom in on a specific category by left-clicking on the corresponding rectangle.
Similar to the donut chart, the tree map reflects the content of the data. However, in the tree map, the percentage distribution is represented by the area of the rectangles rather than by segments. Each category is distinguished by a different color. Like the donut chart, you have the option to include the Without classification category.
Figure 6. Stacked chart of the portfolio.
A stacked chart is a type of chart that displays data as a series of coloured lines, where each line represents a category. The position of the line on the y-axis corresponds to cumulative value of the category. The lines are stacked on top of each other to show the total value of all categories combined, which is 100%. By default, the categories are stacked from large to small, with the largest category at the bottom of the chart. The order of stacking can be adjusted using the icon, allowing bars to be stacked based on magnitude or according to their position in the taxonomy list.
Both the stacked and stacked area charts plot time on the X-axis, set by the selected reporting period (default=1 year).
"},{"location":"reference/view/taxonomies/using-taxonomies/#stacked-area-chart","title":"Stacked Area chart","text":"Figure 7. Stacked chart area of the portfolio.
The Y-axis of the stacked area chart represents the actual monetary value of different categories over time. Similar to the stacked chart, it displays the cumulative values of stacked categories. However, unlike the stacked chart where the values add up to 100%, the stacked area chart shows the actual monetary amounts for each category over time.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"The Portfolio Performance (PP) manual consists of four chapters which are derived from a popular documentation authoring framework. The documentation is structured along two axes: practical versus theoretical knowledge and learning versus doing.
PP is an Eclipse-based desktop application written in Java. This open-source project started in 2012 and has been updated numerous times. With PP, you can:
Why choose yet another application? While you can simulate some of these calculations with Excel or rely on your broker for information, they often provide incorrect results. They are typically based solely on absolute figures at the beginning and end of a reporting period and do not properly include purchases and sales or variable reporting periods. PP calculates performance accurately using True-Time Weighted Rate of Return and Internal Rate of Return, taking into account the purchases and sales at their respective execution date.
"},{"location":"about/#other-information-sources","title":"Other Information Sources","text":"The source code is hosted on GitHub. Examining this code will give you direct access to the inner workings of the program.
There is also an active discussion forum available in both English and German, with an extensive Frequently Asked Questions (FAQ) section.
"},{"location":"about/#license","title":"License","text":"This manual is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The source code of Portfolio Performance is licensed under the Eclipse Public License 1.0.
Thanks to all contributors!
"},{"location":"about/#imprint","title":"Imprint","text":"For more information, please see the Imprint and Privacy Policy.
"},{"location":"concepts/","title":"Basic concepts","text":"In this chapter, you will find a concise but clear explanation of several basic concepts. Portfolio performance is all about numbers. It is easy to completely miscalculate or misinterpret these numbers, if you don't understand the underlying assumptions.
Fundamental concepts such as account, transaction, reporting period, purchase value, and performance are described in a separate chapter (see sidebar). Below is an alphabetical list containing descriptions of all attributes, also referred to as fields or columns, used in various sections within PP.
Absolute performance: a performance measure that assesses the overall gain or loss of an investment over a specific period; = (Market value at end of period + Sell/outbound deliveries + Dividends) - (Taxes + Fees + Initial valuation + Buy/inbound deliveries). Synonym: total return.
Account: Repository or container for storing financial information, such as cash transactions.
Actual # quotes: the number of quotes in the historic prices list of a security.
Amount: The Gross Amount of a transaction or the total amount of money before any taxes and fees.
Buy: transaction resulting in the acquisition of securities, where cash is withdrawn from a deposit account to purchase the desired stock.
Change in Price (period): the difference in historic quotes between the last and first quote of a specified time span, expressed as a percentage. The period may be denoted in years (e.g., 1 year, 2 years, 3 years) or as a date range (From yyyy-mm-dd to yyyy-mm-dd). If the duration is in years, the last date is today, and the first date is today minus x years.
Change on Previous Day (amount) or \u0394 amount: the absolute difference between the latest retrieved quote and the previous one (which is most likely the quote from the previous day).
Change on Previous Day (%) or \u0394 %: the difference between the latest retrieved quote and the previous one (which is most likely the quote from the previous day), expressed as a percentage.
Cash account: A financial account for holding and managing money.
Completeness of historic quotes: the ratio between the actual and expected number of historic quotes of a security, expressed as a percentage.
Currency: the currency for a security chosen at its creation, which becomes immutable after the initial transaction involving this security.
Date: The date of a transaction such as Buy or Sell.
Date of first historical quote: The first date for which you have historical prices of a security.
Date of last historical quote: The last date for which you have historical prices of the security. It's important to note that having these dates does not necessarily mean you have all intermediate historical prices.
Date of latest quote: the most recent date on which the current market value or price of a financial instrument, such as a stock, bond, or commodity, was publicly provided or updated.
Delivery (Inbound): a transaction where shares of a security are acquired without the need for a prior deposit and withdrawal of funds (comparable to a buy without a withdrawal).
Delivery (Outbound): a transaction where shares of a security are removed from the security account without a resulting deposit in a cash account (comparable to a sell without a deposit).
Deposit: Putting money in a deposit or cash account.
Deposit account: Repository or container for storing deposit/withdrawals and balances. Also named Cash account.
Distance to SMA (days): a metric that measures the difference between the current price (quote) of a share and the average price of that share over a specified number of past days (5, 20, 30, 38, 50, 90, 100, or 200 days), expressed as a percentage. The acronym \"SMA\" stands for \"Simple Moving Average\". For example, the average price of security for the last 5 daily quotes is (100 + 98 + 99 + 97 + 96)/5 = 98. The Distance to SMA (5 days) is (100-98)/98 = 2.04%.
Distance to ATH (period): a metric that shows how far the current price is from the highest price in the specified period (1 year, 2 years, 3 years or a date range From yyyy-mm-dd to yyyy-mm-dd). For example, the highest price of a security in the last year was 77.4 EUR. The current price is 71.96 EUR. So the Distance to ATH for a 1 year period is equal to (71.96 - 77.4)/77.4 or -7.03%.
Dividend: the distribution of a company\u2019s earnings to its shareholders.
Exchange: a security may be traded on more than one exchange. For example, the NVIDIA stock is traded on Nasdaq (symbol NVDA, exchange NMS) or XETRA (symbol NVD.DE, exchange GER), and many more exchanges.
Exchange rate: the value of one currency in terms of another currency, determining the rate at which they can be exchanged.
Ex-date: used in stock split; date when a stock exchange first trades the (split) shares at the adjusted price.
Ex-dividend date: shareholders who owned their shares at least one full business day before the ex-dividend date will be entitled to receive a dividend. Sometimes also called the ex-date (see above).
Expected # quotes: given the nature and frequency of a security and the calendar in use, PP calculates the expected number of quotes for the time period between the Date of last and first historical quote. Weekend and holidays are taken into account.
Fees: Costs imposed by a service provider or intermediary for facilitating a transaction.
Gross Amount: Utilized when importing data, indicating the overall worth of a transaction, exclusive of fees and taxes. Gross Amount = shares x quote price or Value - fees - taxes. Also referred to as the Amount within the All Transactions view. This terminology may seem counterintuitive, as traditionally the gross value of an entity (such as your salary) is inclusive of taxes.
Historical prices: collection of closing quotes of a security; mostly daily.
Inactive: A security can be set to active or inactive. If set to inactive, the security will not appear in buy or sell dialogs, and historical prices will not be updated automatically.
Interest: the cost of borrowing money or the return earned on an investment; typically expressed as a percentage of the principal, which is the amount of money borrowed or invested.
Investment plan: An automated method to facilitate periodic transactions, such as deposits, withdrawals, interest payments, or purchases.
ISIN: International Securities Identification Number. This is a unique twelve-digit code that is assigned to every security in the world. Mostly used by European brokers & banks.
Latest Quote: the most recent quote of a security. You can refresh these values to the latest information using the menu option Online > Update Quotes.
Maximum Drawdown: Refers to the largest peak-to-trough decline in the performance of a portfolio or investment over a specific period, typically expressed as a percentage. It measures the extent of loss incurred from the highest point to the lowest point before a new peak is reached.
Maximum Drawdown Duration: The worst or longest amount of time an investment has been between peaks.
Name: the full name of the security according to the data source (see below) from which it is retrieved, e.g. Yahoo Finance.
Net Transaction value: the total sum of costs of a transaction, including the taxes and fees. This terminology may seem counterintuitive, as traditionally the net value of an entity (such as your salary) excludes taxes. (Net) Transaction Value = Gross Amount + Fees + Taxes. Also referred to as Value or Debit Note in the Buy transaction input form.
Note: Each security and transaction can be accompanied by a note for additional information or context.
Offset Account: In the context of buying or selling stock, the offset account is the account that is used to balance the transaction. When a security is purchased, the security account is increased, and the offset account, typically a cash account, is decreased to reflect the outflow of cash. Conversely, when a security is sold, the security account is decreased, and the offset account is increased to reflect the inflow of cash.
Purchase Value: the summed\u00a0transaction value\u00a0of each buy (+) and sell (-) transaction of a security, taken into account the reporting period.
Quote: The most recent price at which a security was traded, also known as the price.
Quote Feed (historic): data source or provider of the historic quotes: Alpha Vantage, Bitfinex Cryptocurrency Exchange, Binance Crypto Exchange, CoinGecko, EOD Historical Data, Finnhub, Inflation rate - Eurostat (HICP), ECB Statistical Data Warehouse, Kraken Cryptocurrency Exchange, PWP Leeway UG, Twelve Data, Quandl, Table on website, VIA/CS Funds, Yahoo Finance, Yahoo Finance (Adjusted Close), JSON, no automatic download.
Quote Feed (latest): data source or provider of the latest quotes (same list as above) or could be set as \"same as historical quotes\".
Rate of return: the percentage change in the value of an asset over a given period of time.
Removal: Also named Withdrawal. Taking money out of a deposit account.
Reporting period: Time period that is used to calculate the performance of a security, account, or portfolio.
Risk: Refers to the possibility of losing some or all of the invested capital or not achieving the expected return from your investment.
Security: A tradable financial asset such as stock, bonds, bitcoin, gold, ...
Security account: Repository or container for storing securities.
Sell: transaction resulting in the removal of securities, and where cash is deposited in a deposit account as the equivalent value of the securities.
Semivariance: The variance of the negative fluctuations of an investment.
Source: data source used in File > New Security Search. Possible source are: Yahoo Finance provides financial news and data including stock quotes, press releases, and financial reports. CoinGecko is a website with real-time information on most cryptocurrencies. Portfolio Report is an open source project that aims to provide centralized portfolio performance data.
Shares: Units of ownership in a company or a financial asset. In the context of PP it refers to the number of shares one owns.
Symbol: the abbreviation (ticker) used by the data source.
Target Currency:
Taxes: Charges imposed by government authorities on certain financial activities.
Trade: The purchase and/or selling of a security. An open trade is created for each buying transaction and converted to a closed trade upon selling.
Transaction: an operation that alters the state of a portfolio.
Transaction type: classification of a transaction based on its nature and purpose within the portfolio, e.g. Buy, Sell, Dividend, ...
Type: In the context of the Security Creation Wizard: Share, Bond, Cryptocurrency, Aktie (German for stock or share), W\u00e4hrung (=German for currency), Futures, etf, fonds (= funds). In the context of the All Transaction table: Buy, Sell, Delivery (Inbound or Outbound), Dividend, Deposit, Removal, Interest, Interest Charge, Fees, Fees Refund, Taxes, and Taxes Refund.
URL (historic quotes): the URL that should be provided, if the choice in Quote Feed is set to Table on website or JSON.
URL (latest quotes): see above but for the latest quote provider.
Value: Utilized when importing data, indicating the overall worth of a transaction, inclusive of fees and taxes. Value = Gross amount + fees + taxes. Also referred to as the Net Transaction Value within the All Transactions view. This terminology may seem counterintuitive, as traditionally the net value of an entity (such as your salary) excludes taxes.
Volatility: Refers to the degree of variability in the returns of a portfolio over time. It is a measure of the risk or uncertainty associated with the portfolio's future performance.
Watchlist: manual grouping of securities.
Widget: A data block comprising a label and a numerical value or diagram, designed for placement on a dashboard.
WKN: Wertpapierkennnummer. A German six-digit alphanumeric code for the identification of a security, now replaced by the ISIN code.
Explaining all financial concepts in this manual would be too far-reaching. However, understanding these concepts is crucial for optimal usage of PP and this manual.
In this page, you can find some reliable weblinks to gain a comprehensive understanding of this terminology. Concepts that are specifically related to PP e.g. account, transaction, purchase value, ... are covered elsewhere in this chapter.
To calculate performance, PP requires two types of historical prices: the historical quotes of securities and in case of foreign investments, the historical exchange rates for currencies.
You can find the historical exchange rates under the menu View > General Data. These exchange rates are retrieved from The European Central Bank (ECB) and go back until the year 1999 when the EUR was introduced on the financial markets. They are in fact reference rates and will probably differ slightly from the real transaction rates that your broker or bank will use.
Securities are traded on exchange markets such as NASDAQ or XETRA, where buyers and sellers agree on a price. Historical quotes are the prices of securities at different points in time. The Close price is the last price of the security at the end of the trading day. Other types are the Open quote, the first price of the security at the start of the trading day, the Low and Highquotes, which are the lowest and highest price of the security during the trading day. The Latest quote is the most recent price of the security available from the exchange market. The latest quote may not be the same as the close price.
Note
PP uses the Close quote in its performance calculations. If there is a Latest quote available, it will be integrated in the Close price. For Bitcoins, the situation is more complex because they are traded 24/24. PP uses midnight (on the users system) to set the Close Quote. So, the historical quotes of a bitcoin could vary between users.
Sometimes, the historical quotes are adjusted to reflect certain events that affect the value of the security, such as stock splits, dividends, or mergers. These are called the Adjusted close quotes. They are useful for comparing the long-term performance of the security, as they account for the changes in the number of shares or the amount of cash paid to the shareholders.
There isn't a shortage of financial services that publish historical prices. However, most of them are rather expensive. Many also offer a so-called free account, but as the saying goes, \"if it is free, you are the customer.\" Finding good (precise, up-to-date) but free data sources for all your historical prices can be challenging. PP suggests, among others, Alpha Vantage, Finnhub, Quandl, which were once excellent solutions but have since changed their offerings and are not as useful anymore as free services. Their terms of use and, most importantly, their commitment in the long run often fall short. In practice, only Portfolio Report and Yahoo Finance could be recommended for now. But see the how-to section for some tips & tricks.
Exchange markets (must) publish the historical quotes of the securities they trade. Several financial services such as Yahoo Finance, Alpha Vantage, and others provide historical quotes for different securities and exchange markets through their websites.
There are two primary methods for obtaining financial data from the web: downloading a csv file, or using an API (Application Programming Interface) to get the data.
Both methods start with a request to the financial service or website. A request is a message that contains the information and parameters needed to access the historical quote feed. A request is sent from the client, which is the user's device or application, to the server, which is the financial service or website. The server processes the request and sends back a response. The response could be a csv file, or a structured text (JSON or XML).
In both cases, PP needs to map its internal fields, such as date and value of the quote, with the data in the response. If successfully, PP can use these fields then in its performance calculation.
Note
In theory, one could scrape webpages that contain tables with historical prices (see for example, Figure 1). PP supports this method; see Import HTML table. However, in practice, nowadays most service providers utilize JavaScript or another technology that hinders this scraping process.
"},{"location":"concepts/purchase-value/","title":"Purchase Value","text":"The Purchase Value of a security is the summed\u00a0value\u00a0of each buy (+) and sell (-) transaction of that security, taken into account the reporting period. The value of a transaction includes the taxes and fees; sometimes also called \u201cNet Transaction Value\u201d.
If the purchase date lies before the beginning of the reporting period, then the value at the beginning of the period is taken. If the purchase date lies within the period, then the value at the purchase date is used. However, if the purchase data is later than the end of the reporting period, then the purchase is not taken into account for the calculation of the purchase value. Purchase Value and Purchase Price are used in Reports > Performance > Securities (see figure 1)
Figure 1. Purchase value of a security
Assume the following scenario. We are now 2023, May, 15th and you have bought 30 shares at different times and quotes (see figure 2). An overview of all buys and their respective quotes is shown in figure.
Figure 2. List of Buy transactions of security example
The reported purchase value of a particular security is dependent upon the selected reporting period. In the Table 1, you can see that the purchase value of this simple transaction, can vary between 3300 EUR and 500 EUR, depending on the selected period.
Table 1: Three reporting periods based on the current day (2023-05-15) Period From \u2026 to \u2026 Purchase Value 1 year 2022, May 15 - 2023, May 15 3300 EUR 2 years 2021, May 15 - 2023, May 15 3000 EUR 3 years 2020, May 15 - 2023, May 15 3050 EUR Custom 2000, Jan 1 - 2020, Jan 01 500 EURThe 1 year period starts at 2022, May 15 and ends today (2023,May 15); sometimes also called YTD (Year To Date). Because all purchases fall before the reporting period, the value for each of them is taken from the beginning of the period. At that time (2022, May 15), the share was valued at a quote of 110 EUR (see graph). So, the total purchase value is 30 shares * 110 = 3300 EUR. This is the beginning situation of the period (also called Statement of Assets). Since, there are no purchases afterwards, this amount is also the purchase value of the 1 year period.
The 2 years period starts at 2021, May 15. Only the third buy falls within the period. So, buy 1 and buy 2 are evaluated at the price from the beginning of the period (= 90 EUR). So, the Statement of Assets equals 1350 EUR. There is one buy afterwards (valued at the buying quote). The total Purchase Value of this 2 year period is therefore (5 + 10) shares at 90 EUR + 15 shares at 110 EUR or 1350 +1650 = 3000 EUR.
The 3 years period start at 2020, May 15. The second and third buy lie within the reporting period and are evaluated at their respective quotes: 10 shares at 90 EUR (= 900 EUR) and 15 shares at 110 EUR (= 1650 EUR). The beginning of the period or Statement of Assets is the result of the first buy (2020, Jan 1) takes the quote from the beginning of the period (2020, May 15) which is the same as the purchase quote (e.g. 100 EUR); resulting in a purchase of 5 * 100 EUR = 500 EUR.
The previous explanation can be seen in the pop-over, when hovering the mouse over the Purchase Value (see Figure 3).
Figure 3. Pop-over panel for Purchase value field.
The custom period (from 2000, Jan 1 (not included) until 2020, Jan 1 (included) has a Purchase Value of 500 EUR because it contains only the first buy (= 5 * 100 EUR). The second and third buy or not taken into account because they occur later than the period end. Things become more complicated -but with the same logic- when there are also sell transactions. Important to remember is that PP use a FIFO (First In, First OUT) method to calculate the result of a sell transaction. Suppose that you did a (rather bad timed) sell at 2021, Jul 1 2020 of 12 shares (see Figure 4).
Figure 4. Overview and graph of all buy and sell transactions.
At that moment there were 15 shares available (5 at 100 EUR and 10 at 90 EUR). Selling 12 of them will first sell the 5 shares of 100 EUR and then another 2 of 90 EUR, leaving 3 shares of 90 EUR available.
Now, let's calculate the Purchase Value for the different periods.
1 year period: The period runs from 2022, May 15 until 2023, May 15. All purchases are done before the beginning of the period; so each of them is valued at the price of 2022, May 15, which is 110 EUR. How many shares are available? 5 + 10 - 12 + 15 = 18 at 110 EUR or 1980 EUR.
2 years period running from 2021, May 15 until 2023, May 15. Only the last buy transaction falls within the period and is evaluated at its current quote (110 EUR). The Statement of Assets consists of 3 shares (15 buy - 12 sell). They are evaluated at the price from the beginning of the period (90 EUR). The Purchase Value for the 2 years period is: 3 * 90 EUR + 15 * 110 EUR = 1920 EUR.
3 years period running from 2020, May 15 until 2023, May 15. The Statement of Assets is 0 EUR because all 5 shares from buy 1 are sold (FIFO) on 2021, Jul 15. From the second buy, only 3 shares are remaining, evaluated at 90 EUR. The third buy is evaluated at 110 EUR. The Purchase Value of the 3 years period is 3 shares * 90 EUR + 15 shares * 110 EUR = 1920 EUR. Longer periods have the same Purchase Value.
The reporting period refers to the specific timeframe used when reporting on the performance of your portfolio. For instance, the performance indicators depicted in Figure 1 are computed over a one-year period, starting from the current date. Other reports and charts, such as those concerning return/volatility and securities performance, also consider this reporting period. It's essential to understand that every performance calculation is based on a reporting period, even if one hasn't been explicitly defined. By default, it is set in PP to one year from the current date.
Figure 1. Drop-down list for selecting the reporting period.
The reporting period can significantly influence performance and can be easily manipulated to support a particular viewpoint. Consider, for instance, the price trend of the Amazon share depicted in Figure 2. Depending on the reporting period, you have a massive loss, a massive gain, or a moderate loss.
Note
Use the equations in Basic Concepts > Performance to calculate the performance indices. If you want to check the numbers in PP, use the Kommer portfolio. Add Amazon as a benchmark to the performance chart and set the appropriate reporting period e.g. 2022. Don't forget to switch the portfolio currency to USD to have the performance calculations in USD.
TTWROR = IRR = (84/166.72)-1 = -49.62%TTWROR = IRR = (151.94/84)-1 = +80.88%TTWROR = IRR = (151.94/166.72)-1 = -8.87% or -4.53% p.a.Figure 2. Historical prices in USD for Amazon (period 2022 - 2023).
You can set the reporting period with the drop-down period in the top-right corner of the window (see Figure 1). The available options are: 1 year, 2 years, 3 years, New ..., and Manage .... With this last option, you can delete or reorder the available periods.
The 1, 2, or 3-year period is always calculated from the current day and extends from the end of the current day to the end of the day one, two, or three years earlier. For instance, if today is July 4, 2024, then a reporting period of 1 year will extend from the closing time of July 4, 2023, to the closing time of July 4, 2024. The market value at the beginning (MVB) of this period reflects the portfolio's status at the end of July 4, 2023, while MVE represents the portfolio's status at the end of July 4, 2024 (see for example Figure 3). Concerning the IRR calculation equation, transactions made on the first date, e.g. July 4, 2023, should not be included in the equation, as they are already accounted for in the MVB of the period. Conversely, transactions on the last day of the period should be included in the equation, as they influence the MVE, even if for a very brief period. In the example mentioned above however, as the year 2022 period extends from December 31, 2021, to December 31, 2022, a purchase made on January 1, 2022, should be regarded as a cash inflow.
With the New submenu, you can create custom periods. The choice options in Figure 3 are rather self-explanatory. You cannot give a custom name to this period as they are predefined and named by PP: for example Last 10 trading days or 2023 for the year 2023.
Figure 3. Possible custom periods for reporting (the current day is July 4, 2024).
Last xxx years yyyy months: From the current day minus the number of years and months. The standard periods of 1`` year, 2 years, 3 years could be recreated with this option. With this syntax, however, you could create a custom period, such as a 1.5 years period.Last xxx days: A day refers to a calendar day. Note that in Figure 3, the last xxx days are already pre-populated. PP recognizes that the current year 2024 is a leap year with February 29 and therefore automatically sets the number of days to 366.Last xxx trading days: A trading day refers to a regular business day on which financial markets are open for trading. Weekends and days from the selected calendar are excluded. The calendar to be utilized can be specified in the Help > Preferences > Calendar menu. Are there 256 trading days in 2024? In Figure 3, the Default calendar was selected, which includes seven holidays: New Year, Easter Monday, Christmas Eve, and four others. In the selected period, there are 262 non-weekend days. Out of the seven holidays, six (excluding Christmas Eve 2023) fall on a weekday. Therefore, there are a total of 256 trading days in the year.From xxx (excl.) until yyy: A period between two dates, whereby the first day is not included (starts at the end of that day).Since xxx (excl): from the given date (excluded) until today (included).Year xxxx: The year always runs from December 31, xxxx until December 31, xxxx+1.Current: Week, Month, Quarter, or Year. A week runs from Sunday or Monday (evening) to the following Sunday or Monday (evening), depending on the country specified in the settings. A quarter comprises three months, e.g. January to March, April to June, and so on. The abbreviation YTD stands for Year-to-date and refers to the period from the beginning of the current year up to the present day.Previous: Day, Trading Day, Week, Month, Quarter, and Year. The Previous Day is not the same as the Last 1 days. As of today, July 4, the Previous Day would be July 3 running from the evening of July 2 to the evening of July 3, whereas the Last 1 Day period would be July 4 (the current day). The Previous Trading Day is similar to the Previous Day but excludes weekends and holidays. The Previous Month runs from the first day of the previous month until the last day of the current month. The First Quarter runs from January 1 until March 31. The Previous Year starts on January 1 of the previous year and ends on December 31 of the previous year.The name PortfolioPerformance (PP) captures its purpose very well: managing an investment portfolio from a performance perspective. This focus contrasts with many proprietary broker apps, which primarily facilitate the technical execution of orders. The following text outlines the principal components. Follow the links to obtain more information about each component.
The portfolio has one Securities Account (broker-A) and two Deposit Accounts (in EUR and USD). The balance of the deposit accounts is the end balance on March 5, 2024. Three shares with their historical prices have been added (All Securities). Only share-1 and share-2 have associated transactions and thus participate in the performance calculation. The historical prices are part of the master security data. The Exchange Rates are provided in View > General Data.
Figure 1. Portfolio Performance components and their relationships.
At the center of the system are the Transactions (All Transactions). There are six transactions involved in this example.
The transaction flow in the deposit accounts is clear to follow (as outlined above). Regarding the final balance of broker-A's securities account (129.13 EUR), on March 5, the account contains 5 shares of share-1, valued at 60 EUR, and 5 shares of share-2, valued at 75 USD. As the securities account's base currency is EUR, the USD value is converted to EUR using an exchange rate of 0.9217 USD/EUR, resulting in 69.13 EUR. This brings the total to EUR 129.13, representing the final balance of the securities account.
Performance is calculated on a daily basis. To compute it, you need the market value of the asset at the beginning (MVB) and end (MVE) of the day, along with the total net amount of incoming and outgoing cash flows. With these values, one can calculate the daily performance using the equation provided in Figure 1 (see also reference > view > reports > performance). These daily performances can then be used to determine the cumulative performance. Let's analyze and compare the performance of share-1, share-2, and the overall portfolio across different days.
The name PortfolioPerformance (PP) captures its purpose very well: managing an investment portfolio from a performance perspective. This focus contrasts with many proprietary broker apps, which primarily facilitate the technical execution of orders. The following text outlines the principal components (see figure 1). Follow the links to obtain more information about each component. An example with a simple portfolio can be found in a separate text.
"},{"location":"concepts/system-overview/#components","title":"Components","text":"Figure 1. System overview with components and relations.
Performance is a multi-layered concept. Not only are there several different methods to calculate it, such as money-weighted (IRR) and time-weighted (TTWROR) rates of return, but you can also calculate performance at various levels: the portfolio as a whole, a security or deposit account, an individual security, or a single trade. In its simplest form, without any transactions, the performance of a portfolio can be represented by the following equation (please refer to the links provided earlier for more detailed information):
$$\\mathrm{r = \\frac{(MVE - MVB)}{MVB} \\quad (Eq 1)}$$
where MVE = the market value of the portfolio at the end of the reporting period, and MVB = the market value of the portfolio at the beginning of the period.
Performance is directly influenced by the reporting period, which is set by default to one year from today. The reporting period determines the value of the portfolio, account, or security at the beginning and end of the period (e.g. MVB and MVE in the performance equations). In the case of the money-weighted rate of return (IRR), it also determines the remaining duration that a cash flow has available to generate a profit or a loss at the end of the reporting period.
Currency exchange rates have a more indirect influence and come into play whenever a transaction involves currency conversion. This includes transfers between different currency cash accounts and transactions such as buys, sells, and dividends in multiple currencies. For example, buying securities that are quoted in USD may require you to convert Euros to USD at a certain exchange rate. Upon selling these securities, you may need to convert the USD back to Euros. Fluctuations in the exchange rate between the time of purchase and the time of sale can result in a profit or a loss, as the value of the USD in terms of Euros may have changed.
Historical prices of securities significantly impact the market value and, consequently, the performance of the portfolio, security accounts, individual securities, and trades. It is clear that when a security's price is higher at the end of a trade compared to its price at the beginning, a profitable trade has been made. This price increase results in a capital gain, which directly contributes to the overall performance and value of the portfolio.
Last but not least, performance is directly dependent on the portfolio and transactions. Without any transactions within the reporting period, the basic performance equation simplifies to IRR = TTWROR = (MVE/MVB) - 1. If the MVE is greater than MVB, a profit has been made, resulting in a positive performance. Conversely, if MVE is less than MVB, the portfolio is worth less at the end of the reporting period than at the beginning, leading to a negative performance.
"},{"location":"concepts/system-overview/#transactions","title":"Transactions","text":"Things become more complicated when transactions occur during the reporting period. There are 13 types of transactions, each generating cash flows into and out of the portfolio, account, or security. Figure 2 illustrates all transaction types between the four major components: the portfolio (represented by a dashed blue line), deposit (cash) accounts in both EUR and USD, three securities (two of which are quoted in USD), and collected into two security accounts (orange and blue dashed lines). Security-2 (USD) is present in both accounts.
Transactions are represented by arrows. They generate cash outflows (red circle) or cash inflows (green circle). The numbers next to the circles represent the magnitude of the cash flow, based on a hypothetical example of a buy or sell of 5 shares at 10 EUR/USD per share, resulting in a capital inflow of 50 EUR/USD. Fees and taxes are always set at 1 and 2 EUR respectively. A dividend of 2 USD is paid per share; an exchange rate of 0.9 EUR/USD is used.
Figure 2. Overview of all transaction types with associated cash flows at portfolio, account and security level.
As can be seen, only four types of transactions generate a cash flow at the portfolio level: deposit, removal (withdrawal), inbound delivery, and outbound delivery. These transactions will thus influence the performance indicator on the dashboard (View > Reports > Performance); which is a portfolio performance indicator.
A deposit transaction generates two cash inflows: one at the portfolio level and one at the deposit account level. This transaction results in an inflow because money is brought into the deposit account, and as such also into the portfolio. On the other hand, a withdrawal creates two cash outflows and removes money from a cash account and the portfolio.
An inbound delivery adds shares to a security; thus increasing the capital of the security (shares x historical price) and the security account. Conversely, an outbound delivery decreases the capital by removing shares from the security, resulting in a cash outflow.
Special attention should be given to fees and taxes. The inbound delivery of 5 shares at 10 EUR per share will increase the capital by 50 EUR, but requires a 53 EUR inflow into the portfolio. However, the cash inflow into the security is 51 EUR, because the 1 EUR fee is only split off after the cashflow at the security boundary. To determine the cash inflow or outflow of a security, one should always incorporate the fees. Fees are considered intrinsic to the transaction, whereas taxes are not considered intrinsic to a security. Collecting taxes varies greatly per country, and the performance of a security should not depend on it. Taxes are by default excluded from the performance calculation at security level. Concerning the security account level, PP offers two possibilities: account performance before or after taxes (default calculation); see menu View > Reports > Chart > configure chart > Add data series ... The default After taxes calculation is shown in Figure 2. Upon crossing the security account border (second green circle), the taxes are already accounted for in the taxes component of the security. The cash inflow of the security account is thus 51 EUR. With the Before taxes calculation, the security account cash inflow is 53 EUR, because 2 EUR taxes are deposited into the taxes entity only after crossing the security account border.
All other transactions are internal to the portfolio; they do not influence the portfolio's performance. For example, the transfer-out transaction is a flow between two deposit accounts and, as such, has no impact on the performance of the portfolio, except when there is a currency conversion as in the example of Figure 2.
Suppose that you transfer 100 EUR at the very beginning of the reporting period at a conversion rate of 1.1 EUR/USD, giving you a deposit of 90.91 USD. The exchange rate changed to 0.9 EUR/USD at the end of the reporting period. Because the performance calculation is done in the currency of the portfolio, e.g., EUR, that 90.91 USD is valued at 81.82 EUR at the period end, resulting in a loss of about 18 EUR due to currency loss.
A buy transaction closely mirrors a delivery inbound, except that the cash flow originates from inside the portfolio rather than from outside. From the perspective of the cash account, this resembles a cash outflow. The security and security account receive a cash inflow. For a discussion about fees and taxes, please refer to the earlier text.
A sell transaction will result in a cash inflow into a deposit account (47 USD) because the 50 USD capital sell is reduced by taxes and fees.
Note
In terms of performance, a Buy/Sell versus Delivery Inbound/Outbound transaction can produce significantly different results. Only when a buy transaction is accompanied by a deposit transaction on the same day and for the same amount, there is no difference in performance between buy versus delivery. However, when a buy transaction is not accompanied by a corresponding deposit transaction, the cash balance in the relevant account will be reduced (and potentially become negative), which can have a negative impact on the market value at the end (MVE) of the account.
A dividend can be viewed as a type of sell transaction. In Figure 2, the capital (5 shares) of security-2 (USD) will provide you with a dividend (gross amount) of 10 USD (5 shares x 2 USD/share). The fees are deducted, resulting in a security and security account outflow of 9 USD. After deducting the taxes and converting the remaining 7 USD to EUR, a +6.3 EUR cash inflow is received by deposit-account-1 (EUR).
The separate fees, fees refund, taxes, and taxes refund transactions follow the same rules as outlined above. Therefore, it makes no difference whether you record taxes and fees as part of one buy, sell, or delivery transaction, or whether you split them off into a separate transaction.
A special case is made by the interest and interest charge transactions. Although they do increase or decrease the cash balance of the deposit account, they do not generate any cash inflow or outflow. Just as the capital of a security can increase or decrease as a result of changing quotes (capital gain or loss), the balance of a deposit account can change due to interest.
"},{"location":"concepts/performance/","title":"Performance Measurement","text":"The measurement of the performance of a financial portfolio is based on the concept of return: the increase or decrease of value over a specific period. For example, your portfolio starts at 100 EUR and grows to 104 EUR by the end of the period, resulting in a performance of + 4%. Equation 1 offers three versions of the base formula; also named the Simple Rate of Return (ROR) or Return on Investment (ROI).
$$\\mathrm{r = \\frac{(MVE - MVB)}{MVB} \\quad \\Leftrightarrow \\quad r = \\frac{MVE}{MVB} -1 \\quad \\Leftrightarrow \\quad MVB \\times (1 + r) = MVE \\quad (Eq 1)}$$
where MVE = the market value of the investment at the end of the reporting period, and MVB = the market value of the investment at the beginning of the period. The Market Value (MV) of a deposit account refers to the total balance of the account on a particular date. For a security or a security account, such as stocks, the MV is calculated by multiplying the number of shares by the closing price. The MV of a portfolio is determined by summing the market values of all accounts on that specific date.
Regarding Eq 1, please note that:
To address the above concerns, PP employs two distinct approaches to calculate the rate of return when additional transactions occur within the reporting period: the money-weighted or time-weighted rate of return. It also differentiates between measuring performance on the portfolio, security, or trade level.
Note
The simple Rate of Return (ROR) isn't adequate for describing the performance of a portfolio when transactions occur in the reporting period. Let's take the example from above. Your portfolio already contains one share valued at 100 EUR at the beginning of the year (MVB=100). Due to the favorable track record of the company issuing the shares, its price has increased to 104 EUR per share by the end of the year. Let's now compare the following scenarios:
The money-weighted rate of return (MWR) employs the Internal Rate of Return (IRR) technique commonly used in project management. This calculation takes into account both the timing (when) and the size (how much) of cash, flowing into or out of the portfolio within the reporting period, effectively weighting the return by the amount of money invested at different times.
The money-weighted rate of return or IRR is the annual interest rate that is necessary to bring the beginning market value of the investment (MVB) and all subsequent cash flows to the end value (MVE). Your portfolio must grow (or shrink) each year by a percentage equal to the IRR to generate the specified cash flows within the given time period.
If you find the concept of IRR challenging, please start by first reading the money-weighted section. The calculation method is thoroughly explained by formulas and numerous examples, ranging from a simple single-share investment to multiple transactions including dividends. The examples are based on our demo portfolio to solidify your understanding.
"},{"location":"concepts/performance/#time-weighted-rate-of-return","title":"Time-weighted Rate of Return","text":"The time-weighted rate of return (TWR) is not influenced by the amount invested. Whether you invest one EUR or 100 EUR, you will achieve the same TWR. The reporting period is divided into several holding periods, and for each holding period, a return value is calculated and then compounded into an overall return. Each period carries equal weight; hence the name time-weighted rate of return. In the True Time-Weighted Rate Of Return methodology (TTWROR), performance is calculated using simple returns without any consideration for the total amount invested.
The TTWOR method is explained in depth in the time-weighted section of this chapter.
A nice video about the calculation and difference between the money-weighted and time-weighted approach is given at the Finance and Risk Corner.
"},{"location":"concepts/performance/money-weighted/","title":"The money-weighted rate of return","text":"The money-weighted rate of return is identical to the Internal Rate of Return (IRR) technique used in project management. This calculation considers both the timing (when) and the size (how much) of the cash flows within the reporting period. A cash flow is any amount of money that is added to or withdrawn from a portfolio. The base formula for the IRR calculation is:
$$\\mathrm{MVB \\times (1 + IRR)^{\\frac{RD}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} = MVE \\qquad \\text{(Eq 1)}}$$
where n = the number of cash flows in the reporting period, CFt = the cash flow at time t, and RDt = the number of remaining days within the period after CFt. For MVB, RD equals the entire period, represented in days. To annualize the return rate, you need to divide the remaining days by 365. To calculate the periodic return rate for the entire period such as 2 years, divide by the number of days of the entire period; e.g. 730 days.
Equation 1 closely resembles the calculation of Future Value. In Figure 1, assuming a 10% interest on your investments, the initial 1000 EUR capital will grow to a future value of 1331 EUR in three years. Additional cashflows of 500 EUR and 1000 EUR in the following years will result in 605 EUR and 1100 EUR respectively. The total Future Value of the investment will then be 3036 EUR in three years.
Figure 1. Visualisation of Future Value calculation.
Calculating IRR is the inverse of calculating the future value (FV) of an investment. You don't know the interest rate or IRR, but you do know the MVB, the MVE, and the intermittent cashflows. According to Equation:
1000 * (1 + IRR)^(3x365/365) + 500 * (1 + IRR)^(2x365/365) + 1000 * (1 + IRR)^(365/365) = 3036
From this point forward, equations will be presented in a spreadsheet-like style, utilizing the asterisk (*) for multiplication and the caret (^) for power. This approach results in more concise equations that can be easily copied and pasted directly into a spreadsheet for verification.
500 * (1 + IRR)^(2x365/365) is thus the expected future value of a cash flow of 500 EUR at time 2025-01-01 by the end of the period (after 2*365 days) with an annual interest rate = IRR. Please note that in the absence of any cash flows, Equation 1 resembles the (annualized) simple return formula MVE = MVB x (1 + r).
The IRR is the annual interest rate that must be applied to the beginning value of the investment (MVB) and all subsequent cash flows for their respective durations to equal the end value (MVE). In other words, the IRR of your portfolio is the annual interest rate that it must grow (or shrink) to get the end value.
Unfortunately, there is no easy way to derive the value of IRR from Equation 1. Software tools such as Excel have functions like IRR and XIRR, that employ a brute-force approach, iteratively solving the equation with various \"guesses\" of IRR until a suitable match is identified. In the examples below we will use the Goal Seek method of Excel to illustrate the solution.
"},{"location":"concepts/performance/money-weighted/#defining-the-cashflows","title":"Defining the cashflows","text":"The concept of cash flows appears to be straightforward: it refers to the cash that flows into or out of a system. However, let's consider the demo-portfolio-03 as an example (see Figure 2).
Figure 2. Overview of transactions - Deposit (3x), Buy (3x), Dividend, and partial Sell and charts of share-1 and share-2.
This portfolio has one deposit account broker-A (EUR), and one security account broker-A, containing two securities share-1 and share-2. Only four types of transactions are made: deposit, buy, dividend, and sell. The question is, what are the relevant cash flows in Equation 1 in this context? For instance, a deposit transaction will transfer money into the portfolio and the deposit account. A sell transaction will withdraw money from a security and security account and move it into a deposit account, but it does not affect the portfolio.
Before defining the relevant cash flows, it is essential to determine the level at which performance calculation is required. Do you need to calculate the performance of the entire portfolio (and for which period), of a specific account or security, or of a particular trade?
From the perspective of the portfolio, cash flows only occur when cash or securities are entering or leaving, the portfolio. Only four transaction types are relevant: deposit, withdrawal, delivery in, and delivery out (refer to Figure 3, on the left and right side). Buy, sell, or dividend transactions do not create a portfolio cash flow. Money is not entering or leaving the portfolio; it is only moving between accounts within the portfolio.
From the perspective of the security or security account only five transactions are relevant: \u00b4Buy\u00b4, Sell, Dividend, and also Delivery In and Delivery Out. These transactions will bring money into or out of the security (account). Some people may find it challenging to recognize that dividends are not portfolio cash flows. It may seem as though money is coming to the portfolio from an external source, similar to a deposit. However, the dividend is paid by a company to its shareholders as a distribution of profits. As a shareholder, you are essentially a partial owner, so the shares are paying the dividend themselves.
From Figure 3, you may notice that the cash flow into or out of a security is represented differently than one entering or leaving the security account or portfolio (square versus circle). Consider the first Buy transaction of share-1. It is clear that the outflow from the deposit account is 155 EUR. This amount is used for raw capital purchase (150 EUR), fees (3 EUR), and taxes (2 EUR). So, how much is the inflow into the security (account)? There are four possibilities
share-1. But, even if the share price increases slightly, the MVE will probably be less than the MVB with a negative performance as result It turns out that PP takes an in-between stance. For the calculation of the performance of the whole portfolio, fees and taxes are included (e.g., 155 EUR). For the performance at the security and security account level, only fees are included, and taxes are left out.
Figure 3. Defining all possible cash flows within a portfolio.
"},{"location":"concepts/performance/money-weighted/#irr-at-portfolio-level","title":"IRR at portfolio level","text":"The following examples will calculate the IRR for an entire portfolio. You can find this performance indicator in the View > Reports > Performance dashboard. The resulting IRR can not be extrapolated to an individual account or security. It's the performance of the whole portfolio. Refer to the following sections to calculate the IRR of a specific security or trade. We use the demo-portfolio-03 for all examples.
Assume that in our demo-portfolio-03 only the first deposit transaction on Jan 15, 2021 has occurred. For a reporting period of three years (2020-06-12 2023-06-12), the MVB of the portfolio is zero. The portfolio is indeed empty on June 12, 2020. On Jan 15, 2021, the deposit account balance increases to 155 EUR and remains at that level until June 12, 2023. The MVE of the portfolio is therefore also 155 EUR. According to Equation 1, the IRR could be derived from:
MVB*(1+IRR)^(RD/365) + CF1*(1+IRR)^(RD1/365) = MVE\n \u2193 \u2193 \u2193\n0*(1+0)^(1095/365) + 155*(1+0)^(878/365) = 155\nIt's clear that IRR=0 will satisfy the equation because one (1+0) to any power equals one. Therefore, the performance of the deposit account, and consequently the portfolio, remains zero, even after multiple deposits. This is because deposits increase both the deposit account and the MVE of the portfolio, ensuring that Equation 1 remains balanced with an IRR = 0.
PP has a specific term for these kinds of cash flows or transfers: Performance Neutral Transfers; see, for example, the Performance Calculation Widget. A deposit is 'Performance Neutral' because the transfer of money affects the MVE and the account by the same amount. A deposit account does not receive any interest or incur any costs. A deposited amount will stay unchanged in the account until the end of the period. The effect on performance (e.g. IRR) is zero.
What will happen if a buy transaction is added, similar to the second transaction in Figure 2? The result is twofold:
share-1 is increased by 10 units, which were worth 150 EUR at the time of purchase. The remaining 5 EUR covered fees (3 EUR) and taxes (2 EUR).Because, we are still focusing on calculating the portfolio performance, the equation from above still holds. Except, at the end of the period, share-1 is quoted at 19.006 EUR/share, giving an MVE of the portfolio of 190.06 EUR.
MVB + CF1 = MVE\n \u2193 \u2193 \u2193\n0*(1+IRR)^(1095/365) + 155*(1+IRR)^(878/365) = 190.06\nAn IRR = 8.85% will solve this equation. In order to generate a MVE of 190.06 EUR, the initial cash flow CF1 of 155 EUR must grow at 8.85% per year for 2.41 years or 878 remaining days.
When dealing with multiple cash flows, deriving the Internal Rate of Return (IRR) becomes much more complex. Take, for example, the three buying transactions from Figure 1. The same logic as mentioned earlier still applies.
An IRR = 15.60% will solve the equation.
MVB CF1 CF2 CF3 MVE\n\u2193 \u2193 \u2193 \u2193 \u2193\n0 + 155*(1+IRR)^(878/365) + 84*(1+IRR)^(514/365) + 67*(1+IRR)^(255/365) = 396.85`\nFigure 5 illustrates the calculation in Excel (download workbook). The initial cash flow of 155 EUR will have grown to 219.68 EUR, if the holding period was 878 days and the yearly interest rate was 15.60%. The second buy will increase from 84 EUR to 103.03 EUR. The profit of share-2 appears smaller due to the smaller amount of holding days. The calculation of IRR can be simulated in Excel using the Data > Goal Seek method (see Figure 4). The method tries to set the value of the calculated MVE (cell F11) to the observed MVE (manual input) by iteratively changing the value of IRR (cell F3), until a match (15.60%) is found.
Please note that the individual calculated end values of the shares do not necessarily correspond with the observed individual end values. Compare for example the expected and observed value of share-2. The observed value (cell J9) is much higher. Only the sum of the whole portfolio match and the same calculated IRR is applied to all shares. PP can - of course- also calculate the IRR for individual securities; see below to calculate the performance of individual securities and trades.
Figure 4. IRR-calculation for three buy-transactions.
"},{"location":"concepts/performance/money-weighted/#example-3-buy-dividend-sell-transactions","title":"Example 3: buy - dividend - sell transactions","text":"In PP, the cash proceeds from a selling transaction are deposited into a cash account. A sell transaction is thus the opposite of a buy transaction. The security (account) will be reduced, while the referenced deposit account is increased by the same amount. Both cash flows will cancel each other out.
When a dividend payment is made, the associated deposit account is also increased by the dividend amount. However, it may seem unclear as to where this money originates. Although it appears to come from an external source, PP treats it as if it is generated by the security itself. Without the security, there would be no dividend. When a company pays a dividend to its shareholders, it essentially means that as a shareholder/owner, you are paying yourself a dividend from the company's earnings or profits. As a result, the value of the company, and your shares decrease accordingly.
However, from the perspective of calculating the portfolio performance, these details are not important. Since no money leaves or enters the portfolio, the performance equation is the same as in Example 2, except that the MVE = 426.82 EUR, including the result of the sell and dividend payment.
MVB CF1 CF2 CF3 MVE\n\u2193 \u2193 \u2193 \u2193 \u2193\n0 + 155*(1+0.2028)^(878/365) + 84*(1+0.2028)^(514/365) + 67*(1+0.2028)^(255/365) = 426.82`\nFigure 5. IRR-calculation for buy-sell-dividend transactions.
However, if the dividend payment or selling transaction is \"consumed\" (you bought yourself a coffee from it), resulting in an external cash flow (withdrawal), this transaction should be recorded in PP. Similarly, if you choose to reinvest the dividend or the proceeds from a sale, it necessitates recording a new transaction in PP.
"},{"location":"concepts/performance/money-weighted/#example-4-mvb-0","title":"Example 4: MVB > 0","text":"In the previous examples, all transactions took place within the reporting period. This isn't always the case. It is very important to distinguish the following cases:
CFt occurs before the beginning of the reporting period (MVB date). PP will calculate the value of CFt through historic quotes at time t. The market value of the investment at time t is used in the calculation, not the purchase value. The holding period is the entire reporting period.
CFt occurs after the beginning but before the end of the reporting period. The value of CFt is known through the transaction data. The holding period is the number of remaining days from time t until the end of the reporting period.
CFt falls after the end of the reporting period. CFt does not contribute to MVE and is omitted from the calculation of IRR for that reporting period.
Consider a scenario where the holding period is only two years (from 2021-06-12 to 2023-06-12), or 730 days. Since the first buy of share-1 occurs outside of this period (item 1 from above), the quoted price of share-1 at the beginning of the period is used rather than the actual buying price.
share-1 at the closing price of 17.794 EUR on June 11, 2021 (= the closing price from the day before the start of the period).The resulting formula with IRR = 17.63% is:
MVB CF2 CF3 MVE\n \u2193 \u2193 \u2193 \u2193\n177.94 x (1+IRR)^(730/365) + 84*(1+IRR)^(514/365) + 67*(1+IRR)^(255/365) = 426.82`\nFigure 6. IRR-calculation for a 2 year holding period (MVB > 0).
"},{"location":"concepts/performance/money-weighted/#irr-at-security-level","title":"IRR at security level","text":"The value of the IRR, calculated at portfolio level, doesn't say much about the performance of a specific security. For example, the IRR of demo-portfolio-03 (3 years reporting period) is 20.28% (see Figure 5). The security IRR of share-2 is 112.53% (see Figure 7 at the top). A quick look at Figure 7 (bottom) should clarify why: the security is acquired at the lowest price throughout the entire period. You can obtain the IRR for each security separately using the menu View > Reports > Securities (see Figure 7).
Figure 7. IRR-calculation for individual securities.
The relevant transactions to consider when calculating the performance of a single security are Buy, Sell, and Dividend (see Figure 3). In this instance, there were no deliveries of securities involved. Please note, that from the perspective of a single security:
Importyant
The cashflow to and from a security is always inclusive of fees. Fees are considered an inherent part of the security and the performance of the security is partly dependent on the the size of the fees.
Taxes are excluded from the calculation of security IRR. This exclusion is justified as taxes are not directly associated with a specific security, they are imposed by the government (sometimes collected at later dates), and are beyond the investor's control. Unlike fees, which can be influenced to some extent, taxes cannot. Therefore, the cash flow to consider for the security IRR calculation is the debit note of the transaction minus taxes.
In contrast to the portfolio IRR, dividend, buy, and sell transactions are treated as cashflows. The money from these transactions will 'enter' or 'leave' the security. This happens at the transaction date. Buying/selling the security (at a good or bad time) and paying dividends will impact the performance of the security. As a side effect, deposit accounts are not included in the Security IRR calculation.
With a multi-transaction security, the purchase price and value can be somewhat tricky to determine. For instance, the remaining 10 shares of share-1 are the outcome of two purchase transactions and one sell transaction. Following the FIFO principle (First In, First Out), these 10 shares consist of the 5 remaining shares from the first buy and the 5 shares from the second buy. This results in an average price of 15.50 EUR (see example 6).
A straightforward example is illustrated by the IRR calculation of share-2. The single buy transaction falls within every holding period (1,2, or 3 years). The total cash flow of the transaction, including fees but not taxes, amounts to 66 EUR.
2023-06-12.Inserting these values into Equation 1 will find a solution with IRR = 112.53%; see also Figure 8.
MVB + CF1 = MVE\n \u2193 \u2193 \u2193\n0 x (1+IRR)^1095/365 + 66 x (1+IRR)^255/365 = 111.76\nAs can be seen in Figure 2, share-1 has multiple transactions, 2x buy, partial sell and dividend. It's important to get the dates and cash flows correct, see Figure 9.
Figure 8. IRR-calculation for individual security with multiple transactions.
The first and second cashflow is rather straightforward. 10 shares at 15 EUR/share + 3 EUR fees and 5 shares at 16 EUR/share plus 3 EUR fees. Assuming an IRR = 18% (see Figure 7), the calculated end value of share-1 = 153 x 1.18^(878/365) = 227.81 EUR.
Please note that dividend payments and sales are recorded as cashflows on the transaction date. This differs from the behavior observed in IRR calculations at the portfolio level.
Inserting these values into Equation 2 gives:
MVB CF1 (buy) CF2 (buy) CF3 (dividend) (sell) MVE\n\u2193 \u2193 \u2193 \u2193 \u2193 \u2193\n0 + 153 x (1+IRR)^(878/365) + 83 x (1+IRR)^(514/365) - 30 x (1+IRR)^(179/365) - 107 x (1 + IRR)^(61/365) = 190.06`\nAs can be seen from Figure 8, an IRR = 18.00% will fit the equation..
A trade is formed by aggregating all buy and sell transactions related to a specific security. A trade can be classified as either \"closed\" or \"open\". A closed trade indicates that no further transactions can be conducted within that trade, whereas an open trade means that additional transactions are possible. The demo-project-03 contains 3 trades (see Report > Performance > Trades; Figure 9). A closed trade starts with a buy of share-1 on 2021-01-15 and ends with a partial sell on 2022-01-14. The remaining shares initiate the second open trade, starting at 2022-01-14 and ending at the current date (e.g. 2023-06-12). The third trade is also open because share-2 hasn't been sold yet.
Important
2023-04-12 correspond to those acquired on 2021-01-15, rather than the ones obtained on 2022-01-14.Figure 9. IRR-calculation for trades.
"},{"location":"concepts/performance/money-weighted/#example-7-irr-calculation-of-a-closed-trade","title":"Example 7: IRR calculation of a closed trade","text":"Five shares of share-1 were sold on April 12, 2023. The historical closing price on that day was 22.40 EUR/share. Fees and taxes were 7 EUR, giving a net transaction value of 105 EUR (see Figure 1) or the Exit value in Figure 10.
Because of the FIFO-principle, these 5 shares were from the 1th buy, meaning that they are purchased for 5 x 15 EUR = 75 EUR. The fees and taxes (5 EUR for 10 shares) are proportionally allocated, in this case, 5/2 = 2.5 EUR. The entry value of this closed trade is thus 77.50 EUR. The securities are held for 817 days (from 2021-01-15 till 2023-04-12). The sell transaction will coincide with the MVE. We could use the simplified equation (without any transactions). An IRR = 14.53% will solve the equation.
MVB x (1 + IRR)^RD/365 = MVE\n\u2193 \u2193\n 0 x (1 + IRR)^817/365 = 105\nImportant
PP will always use the current date to calculate an open trade IRR. If you want to follow the previous example, you can try to change the system date on your computer. Restarting PP isn't necessary.
Assume that today is 2023-06-12. The open trade involving share-2 is rather simple. Referring to Figure 2, these shares were acquired for a net value of 64 EUR + 3 EUR fees and taxes on 2022-09-30, which was 255 days ago, assuming that today's date is June 12, 2023. The current value is 111.76 EUR, resulting in 67 * (1 + IRR)^255/365 = 111.7 or IRR = 108%.
The open trade involving share-1 is a special case. Since it is an open trade, it ends on the current day (2023-06-12). The number of days between the purchase date and today is 696 days. The historical price on this date was 19.006 EUR/share. The exit value is thus 190.06 EUR.
The trade consists of shares that were bought in 2021 and in 2022. Five shares are from 2021. The cash flow of these shares is thus 77.5 EUR (see also paragraph above). Today, they are valuated at 95.03 EUR. The remaining 5 shares are from 2022-01-04 with a cash flow of 5 x 16 EUR/share + 4 EUR fees and taxes (see Figure 1). These 5 shares are also 95.03 EUR worth today (2023-06-12).
This corresponds with PP (see Figure 9 above): the exit value is 190.06 = 2 x 95.03 EUR and the entry value is 77.5 + 84 = 161.50 EUR. Inserting these values in Equation 1 will give a solution with IRR=9.16%:
77.5*(1+IRR)^(878/365) + 84*(1+IRR)^(514/365) = 190.06
The Time-Weighted Rate of Return (TWR) gives each time period equal weight in the calculation of the return rate, regardless of the amount of money invested during those periods. . In contrast, the Money-Weighted Rate of Return (MWROR) method assigns greater weight to periods with more money invested, taking into account the size and timing of cash flows.
"},{"location":"concepts/performance/time-weighted/#general-method","title":"General Method","text":"In most financial management handbooks, calculating the time-weighted rate of return for a reporting period is described as a three-step process:
Divide the reporting period into subperiods based on cash flow dates: A subperiod runs from just before a cash flow until just before the next cash flow or the end of the reporting period. As such, the sub-periods are likely to have unequal durations.
Calculate the sub-period growth rates using Equation 1:
$$\\mathrm{1 + r = \\frac{MVE + CFout}{MVB + CFin} \\qquad \\text{(Eq 1)}}$$
where MVE = the market value of the asset at the end of the holding period, MVB is the market value at the beginning of the holding period (which is the same value as the MVE of the previous holding period). CFin is the incoming cash flow, and CFout is the outgoing cash flow in that period.
Compound the sub-period returns into the overall performance for the reporting period using Equation 2:
$$\\mathrm{r = [(1 + r_1) \\cdots \\times (1 + r_n)] - 1 \\qquad \\text{(Eq 2)}}$$
where n is the number of holding periods and rt is the return rate for holding period t.
Note
Figure 1 depicts a simplified example with three holding periods and known performances (10%, 5%, and 10%), which is, of course, not the case in the real world.
Figure 1. Portfolio with 1 Deposit and 1 Withdrawal (Removal) transaction and thus 3 holding periods.
What is the TWR of this portfolio? According to Equation 2, this should be: [(1+0.1)*(1+0.05)*(1+0.1)]-1 = 27.05%. Please note, that this is not an annualized return but a return for the entire period. The durations of the holding periods could differ but no information about durations is provided. Secondly, the sequence of the returns does not matter; (5%, 10%,10%) gives the same result. Lastly, the size and timing of the cash flows do not impact the result. If there were no cash flows, the intermediate values would be: 100*1.1= 110; 110*1.05= 115.5, and 115.5*1.1= 127.5, or the starting value 100*1.275.
However, since there are cash flows, Equation 1 could be used to calculate the holding period returns (instead of assuming they were given):
(110/100)-1 = 10%.[136.5/(110+20)]-1=5%.[117.15/(136.5-30)]-1.Please note that the formula for the cash outflow is slightly different than the one given in Equation 2 (see TTWROR at security level for an explanation).
In the classical method described above, an asset valuation is required at each cash flow. You need to know the value of the portfolio or asset just before each cash flow. However, there are instances when this isn't feasible, and only monthly or quarterly valuations are available. These valuations may or may not coincide with the cash flows. In such cases, an approximation can be used. However, when a valuation is available just before each cash flow, a True Time-Weighted Rate Of Return (TTWROR) could be calculated. The term is coined to differentiate this method from the approximations mentioned above.
In the past, when computing power was expensive, it made sense to create longer holding periods to ease the computational burden, particularly for the required valuations at each cash flow. Today, this is no longer the case, and software like PP can calculate the market value of investments practically in real time. As an in-between solution,PP creates valuations of the different components on a daily basis, regardless of whether there is a cash flow. Therefore, the holding periods all have equal durations of one day.
With daily valuations, it makes sense to assume that cash inflows occur at the very start of the day. The money is immediately available to invest during the day. Consequently, there will never be a portfolio with an MVB of 0, because cash inflows are added immediately to the portfolio. PP also assumes that cash outflows occur at the very end of the day, just before valuation. Thus, it makes sense to reflect this in Equation 1: inflows are added to the MVB, and outflows are added to the MVE.
"},{"location":"concepts/performance/time-weighted/#ttwror-at-portfolio-level","title":"TTWROR at portfolio level","text":"The relevant cash flows for the performance calculation at portfolio level are: Deposit, Withdrawal (removal), Delivery In, and Delivery Out. Refer to the Defining Cashflows section, and in particular Figure 3 from the chapter about Money-Weighted Rate of Return for detailed information.
Note
Figure 2 displays the necessary info for calculating the TTWROR of demo-portfolio-03.
Figure 2. Overview of transactions - Deposit (3x), Buy (3x), Dividend, and partial Sell and charts of share-1 and share-2.
We will use a 2-year reporting period starting from June 12, 2021 in the following examples. Since the initial purchase of share-1 for 155 EUR occurred outside of this reporting period, there are only two cash flows that impact the performance. By June 12, the market value of share-1 (MVB) was increased to 177.94 EUR; see the first chart in Figure 2.
Figure 3. Portfolio from demo-portfolio-3.xml (2 years reporting period).
If there aren't any cashflows in a holding period such as in HP1, one can use the simple rate of return formula: r = MVE/MVB - 1 = 160.26/177.94 - 1 = - 0.0994 or - 9.94%.
The second holding period however starts just before a cash inflow (+ 84 EUR). The MVE is 264.57 EUR. According to Equation 1 the rate of return r = 264.57 / (160.26 + 84) or 8.31%. By adding the cash inflow to the denominator, the influence of this cash flow on performance is neutralized.
The MVB of the HP3 is the same as the MVE of HP2 or 264.57 EUR. There is a cash inflow of 67 EUR and the MVE = 426.82 EUR. The performance r = 426.82 / (264.57 + 67) or 28.73%.
It's important to emphasize that the timing of the cash flows is not considered in this calculation. It doesn't matter whether HP1 is short or long. Additionally, the performance is calculated independently of the size of the cash flow, with the cash inflow being added to the beginning Market Value of the Portfolio (MVB). This approach contrasts with the money-weighted rate of return calculation, where both timing and size of cash flows are taken into account.
For each period, you need MVB or MVEt-1 and the current MVEt period. Because the market value is determined at the end of the trading day (closing price), MVEt-1 is also the value immediately before the cashflow at the beginning of the day.
Note
One could argue that, as we are required to add the cash flow CFin to MVEt-1 (as per Equation 1), an alternative approach is to consider the market value of MVEt, which already includes this cash flow CFint. However, it's important to note that throughout the day, market forces may cause fluctuations in the original MVEt-1, and these variations should be excluded when determining the market value at the beginning of the day, just before the cash flow.
"},{"location":"concepts/performance/time-weighted/#exporting-data-from-pp","title":"Exporting data from PP","text":"Since computer time is inexpensive nowadays, there's no need to define long holding periods to minimize manual computation. Therefore, PP employs a single day as the holding period. You can easily export a CSV-file with the daily portfolio values. Select the menu View > Reports > Performance > Chart and click the icon (top right) Export Data as CSV. Choose Export Entire Portfolio (see Figure 4 for an abbreviated example). Delta in % corresponds with the computed rate of return r. The Cumulative Performance in % is the cumulative or total TTWROR, compounding all returns from the previous days.
Figure 4. Extract of CSV-file from Export Data as CSV (2 years period - portfolio level).
The calculation is analogous to the explanation of the manual calculation. Note that the majority of rows from the Excel sheet are hidden. The market value of the portfolio on 2021-06-12was 177.94 EUR. At the end of HP1 on 2022-01-13 it has dropped to 160.26 EUR. On June 14, a deposit (and buy of share-2) was made. The market value of the portfolio increases as a result to 264.57 EUR. Due to fees and taxes (see Figure 2), the daily performance is negative. The cumulative performance is calculated according to Equation 2, leading to a total performance of the portfolio of 25.58% for the entire reporting period.
The previous section describes the performance of the whole portfolio, including deposit accounts. Understanding the performance calculation for a single security should not pose any problems by now. The same principles are applied. However, there are quite a few differences qua approach.
In PP you can retrieve the IRR and TTWROR of a security through the menu View > Reports > Performance > Securities. However, these values are not displayed by default and should be made available with the Show or Hide columns icon (top right).
Figure 5. Periodic and annual TTWROR for securities (2 years period).
The chart from the menu View > Reports > Performance > Chart can exhibit multiple time series (click the Gear icon). In Figure 6, the cumulative TTWROR for the entire portfolio is depicted, along with individual graphs for share-1 and share-2 over a 2-year reporting period, starting from June 12, 2021. As share-2 was acquired on September 30, 2022, its performance until that date registers as zero (indicated by the horizontal yellow line). From that point onward, the performance of the portfolio diverges from that of share-1 due to the notably successful yet relatively minor contribution of share-2 within the overall portfolio. As can be seen, the periodic TTWROR of the entire portfolio or the last cumulative performance of the portfolio is 25.58%, as calculated in Figure 4.
Figure 6. Graph of the cumulative performance of portfolio, share-1, and share-2 (2 years period).
For the manual calculation, you need to define the holding periods. This is fairly easy for share-2. One holding period should suffice: from just before the buying date until the end of the reporting period. The MVB of share-2 at the beginning of the holding period (just before the buy) is 0 EUR. The MVE equals 111.76. The buy-transaction cost (taxes excluded) is 66 EUR. The TTWROR is thus equal to 111.76/(0 + 66) = 69.33%. You can see this in Figure 6, where the orange line ends just below 70%.
The manual calculation for share-1 is more complex due to the involvement of multiple transactions, especially outflow transactions such as dividends and sales. The best approach to understanding the problem is to draw a timeline, as depicted in Figure 3 or Figure 8. The table below summarises all the relevant info and is based on the CSV export of the daily data (market value, daily rate of return, and cumulative rate of return) from the graph in Figure 6 (click the up-pointing arrow at the top-right).
Figure 7. Manual calculation of (cumulative) performance of share-1.
Note that Figure 7 illustrates two distinct methods for defining holding periods. The first method, previously discussed, defines a holding period from immediately before a cash flow (or the start of the reporting period) until just before the next cash flow (or the end of the reporting period). In this case, the calculated TTWROR is 19.71%, which is higher than the PP indicator of 14.98% (see Figure 5). However, this method is inappropriate for this particular scenario due to the presence of cash outflows.
The reason is that, as shown in Equation 1, outflows are added to the Market Value End (MVE), while inflows are added to the Market Value Begin (MVB). Figure 8 presents a simplified example for clarification.
The reporting period spans 8 days, with a cash inflow (buy) on D1 and a cash outflow (sell) on D5, resulting in two holding periods. The MVB and MVE are displayed below. Note that MVBt = MVEt-1 and that MVEt = quote x #shares for that day.
Figure 8. Simplified example.
According to Equation 1, 1 + r = (MVE + CFout)/(MVB + CFin) or for day 1: (1000+0)/(0+1000); which results in a performance of zero. Note that, since MVBt = MVEt-1, the terms in the numerator and denominator cancel out, leaving the simplified formula for the return of the first holding period (HP1) as: 1 + r = (1010 / 1000), or r = 10%.
However, this method cannot be applied to HP2, because the cash outflow (510 EUR) is added to the MVE of the selling date. The numerator of day 55 isn't equal to the denominator of day 6. The correct simplified formula for HP2 is thus separating the performance calculation for the transaction date from the following days, as is done in Figure 7 (lower part). If the first method was used, then the cash outflow would be added to the MVE of day 8; which is of course not the selling date.
Transferring this method to Figure 7, the return rate of HP1 is straight-forward. r = [(160.26 + 0)/(177.94 + 0)] - 1 = -9.94%. HP2 contains a cash inflow (buy), which causes no problems: r = [(287.49 + 0)/(160.26 + 83)] - 1 = 6.43%.
HP3 and HP4 are special cases as they contain cash outflows. They are split into the day of the transaction itself and the remaining period. The MVE is increased with the cash outflow to neutralize the effect of this outflow. The MVE date of the third holding period is April 11, 2023, while the dividend is disbursed on December 12, 2022. Although an imperfect solution, one approach could involve modifying the formula to subtract the dividend from the MVB, which is at the correct date. However, remember that PP records inflows at the beginning of the trading day and outflows at the end of the day. While the difference for the dividend payment is relatively minor (e.g., 287.49 versus 283.47), it is more significant for the selling transaction (e.g., 339 versus 224). By splitting the holding period into two sub-periods, this issue is resolved, enabling the retention of the original formula in Equation 1.
"},{"location":"concepts/performance/time-weighted/#ttwror-pa","title":"TTWROR p.a.","text":"Figure 5 displays both the (periodic) TTWROR and the TTWROR p.a. (per annum or Latin for per year). The periodic TTWROR represents the performance for the entire reporting period. You can add the TTWROR p.a. indicator in every table or widget with the icon.
The TTWROR p.a. indicator is calculated by assuming that a year has 365 days.
For example, if the periodic TTWROR is 30% over two years or 730 days, the annualized value would be 14.02% or (1.3 ^ (365/730))-1. This is equivalent to taking the square root of 1.3.
If the TTWOR for the month of January is 2%, the TTWROR p.a. would be calculated as (1.02 ^ (365/31))-1, resulting in 26.26%.
The assumption of 365 days per year may cause a slight discrepancy between the periodic TTWROR and TTWROR p.a. when the reporting period includes February 29th in a leap year. However, for non-leap years like 2023, both values will be identical.
In order for you to be able to track, evaluate and manage your securities, Portfolio Performance needs the basic data about your securities accounts and past transactions. After that, you can immediately make your first evaluations and analyze your portfolio and performance from different angles.
"},{"location":"getting-started/#installation","title":"Installation","text":"You can either use one of the precompiled installation files or compile the complete application by yourself. The application is available for MacOS, Windows and Linux.
"},{"location":"getting-started/#creating-a-portfolio-file","title":"Creating a portfolio file","text":"Your first step - of course - is to create a new portfolio file with your accounts. The portfolio file contains all securities, accounts, custody accounts, bookings, classifications, etc.
"},{"location":"getting-started/#adding-securities","title":"Adding securities","text":"You create the securities that are of interest to you in the list of securities. Master data and historical prices are automatically supplemented and updated by Portfolio Performance.
"},{"location":"getting-started/#manage-your-portfolio","title":"Manage your portfolio","text":"So far you have created your portfolio file with a list of interesting securities. Now, it's time to buy and sell some of those securities, receive dividends, set up a savings plan, receive dividends, ....
"},{"location":"getting-started/#measure-your-portfolios-performance","title":"Measure your portfolio's performance","text":"Performance and risk are crucial. Various views and tools can be used to evaluate your portfolio.
"},{"location":"getting-started/#classifying-your-assets","title":"Classifying your assets","text":"To reduce risk, you probably want to diversify your portfolio by region, type, asset, ... Using taxonomies will help you visualize and calculate the amount of diversification.
"},{"location":"getting-started/#define-portfolio-strategy-and-rebalancing","title":"Define portfolio strategy and rebalancing","text":"You map your own portfolio strategy with target values for different share classes. You can make a target/actual comparison and perform a rebalancing.
"},{"location":"getting-started/#keeping-the-portfolio-up-to-date","title":"Keeping the portfolio up-to-date","text":"You book new purchases, sales, and dividends as well as any costs and taxes incurred. This can be done quickly and easily by importing the bank's PDF statements, or manually.
"},{"location":"getting-started/adding-securities/","title":"Adding securities","text":"Right after the preceding Create portfolio step, your portfolio is still empty. You can check with the left sidebar option Securities > All Securities. This list contains all the securities you are monitoring, not necessarily the ones you have purchased. Currently, the list is empty (see Figure 1).
Note
A security is a financial instrument that holds value and can be traded between parties. Securities can be broadly categorized into: debt securities (e.g., banknotes, bonds, and debentures), equity securities (e.g., common stocks) derivatives (e.g., forwards, futures, options, and swaps) [Source Wikipedia].
Figure 1. Main screen after creating a new portfolio.
The Add new investment instrument button allows you to start adding securities to your portfolio. As you can see in Figure 1, you can add new instruments (stocks, bonds, ...), cryptocurrencies, exchange rates. You can also import securities from a CSV-file or to create a new empty security. You could also use the menu File > New menu (see Figure 1).
Adding new instruments
Suppose you intend to acquire NVIDIA shares. Before proceeding with the purchase, you must first add the specific share to the list of Securities. To achieve this, choose either New > Security from the menu or click on New Instrument... (button). This action will open the following window (refer to Figure 2).
Figure 2. Searching and adding new securities to the All Securities list.
You can type (part of) the security name in the search box, e.g. NVID. After clicking the Search button, the list below will be populated with possible target instruments (see Figure 2).
After selecting the appropriate security, click on the Apply button to move on to the next step. Certain information, such as name, symbol, and historical quotes, will be pre-filled based on the selected data source. You have the flexibility to modify all this information, including the name. In Figure 3, it is evident that the currency for the NVIDIA share is incorrectly set to EUR.
Note
An alternative but very convenient method for securities listed on XETRA is to utilize the Portfolio Report website. Adding a security is as easy as drag & drop a link from that website into PP. See how-to > Using Portfolio Report for more info.
Figure 3. Panel for entering info about the selected security.
In some cases, starting with an empty instrument and manually inputting the information might be more straightforward. While only the name is mandatory, it is advisable to set additional details such as Currency, Symbol, and Historical Quotes Feed.
More information about all these attributes can be found in the Reference Manual > File > New. Finding the correct settings to import the Historical Prices of your security is described in the How-to section.
"},{"location":"getting-started/classify-assets/","title":"Classifying your assets","text":"A golden rule of investment is to diversify your portfolio across different sectors, types, regions, ... This strategy helps to mitigate risk by spreading investments across various areas.
With taxonomies, you can visualise and measure diversification. A taxonomy is a tool for categorising the investments within your portfolio. There are several predefined and well-known existing taxonomies, such as the Global Industry Classification Standard (GICS), developed by MSCI. Alternatively, you can create your own custom taxonomy; see Reference > View > Taxonomies for further information.
Figure 1. Taxonomies view with several predefined and one custom taxonomy.
In Figure 1, several predefined taxonomies (Asset Classes, Asset Allocation, etc.) and one custom taxonomy are added to the Taxonomies view. The main pane displays the definition of the custom taxonomy myTaxonomy. It categorises the securities into a Base Currency (EUR) or Foreign Currency group. Daimler and Mercedes are quoted in EUR, while Amazon and Nvidia are quoted in USD. Please note that most securities (72.02%) are not categorised yet and reside in a group labelled Without Classification.
To add a taxonomy to the Taxonomies view, select the File menu and choose New > Taxonomy, or use the sidebar. Select one of the existing taxonomies or create a new one. Use the context menu to add a new classification (category); see Reference > View > Taxonomies > Managing taxonomies for further information.
There are several ways to add a security to a taxonomy category, the simplest being dragging it from the Without Classification list to the desired category, such as Base currency or Foreign currencies.
Select one of the chart icons on top to visualise the taxonomy and gain a sense of proportion between categories. Click on the tabs below to see an example of each available chart type.
Donut chartPie chartTree mapStacked chartStacked area chartDonut chart "},{"location":"getting-started/create-portfolio/","title":"Creating your portfolio","text":"You can quickly create a PP file using a wizard to guide you through the setup process. There are five steps, but only the first two are mandatory. Start with the menu File > New > File to create a new portfolio file.
Step 1
First, you need to select the default currency for the portfolio (see figure 1). You can always change the currency for individual securities. PP supports almost every possible currency: from AED (United Arab Emirates Dirham) to ZWL (Zimbabwean dollar).
Figure 1. Selecting the default currency for the portfolio.
Step 2
Your portfolio must contain at least one security account and one associated reference (deposit) account.
Figure 2. Adding security and reference accounts to the portfolio.
When at least one security account with a reference account has been created, the Finish button becomes available. Don't worry about the next steps if you don't understand what they are about.
Note
If you have an existing portfolio, PP supports importing CSV files to quickly add securities, buy and sell transactions, and payments. See this tutorial for importing a portfolio and dividends.
Step 3
Sometimes, you need more than one deposit account. You can add these extra cash accounts (e.g., in different currencies) to your portfolio.
Figure 3. Adding additional cash accounts to the portfolio.
Step 4
As part of the creation wizard, you can also add the securities that you want to track in this portfolio. These securities are retrieved from German index trackers such as DAX (Deutscher Aktienindex), tecDax, SDAX, and MDAX. You can also add the index itself or others (e.g., NASDAQ) with Indizes. Of course, you can add securities later on. Your choice is then much larger.
Figure 4. Adding instruments to the portfolio.
Step 5
Taxonomies, such as Asset classes and Regions, are used to classify your securities. This classification can then later on be used in performance analysis (e.g., show me the performance of all securities from region xxx).
Figure 5. Adding taxonomies to the portfolio.
Finish
When the wizard is finished, an unnamed.xml file is created. All data of your portfolio is stored in this XML-file (eXtensible Markup Language). More info on the available file-formats here. Of course, you should save it with a different name and location.
PP is available for MacOS, Windows and Linux. You need to download it and do some installation steps. The easiest way to download and install the latest version of PP is by using one of the installer files at the homepage (see fig 1). A link to the release notes of this latest version is also provided.
Figure 1. Homepage with download links for various packages (2023-09-03)
"},{"location":"getting-started/installation/#windows","title":"Windows","text":"You can download the compressed Zip-file and extract it in a directory at your choice. Even a portable USB-stick (about 250 MB free space) is fine (run from stick).
You can also download the Windows - Installer (setup.exe). On Windows 11, you get a security warning about the dangers of running an exe-file. After that, double clicking on this file, will start the installation. You can change the destination folder. By default, the c:\\user directory is taken. You need about 200 MB of free space (see figure 2).
Figure 2. Windows Installer dialog box.
The preferred option is to install Portfolio Performance on Linux is using from Flathub.
Alternatively, you can install PP manually:
sudo apt install openjdk-17-jre\nThe installer files are in fact stored in the author's github repository. So, you can also download the program from this repository. If you ever should need a previous version, this is also the place to be (click on the version number at the left side).
Figure 3. Github repository for downloading (previous) releases
You can edit and compile the source code; see Contributing to Portfolio Performance.
"},{"location":"getting-started/measure-performance/","title":"Performance Dashboard","text":"To assess your portfolio's performance, start by examining the Dashboard. Key performance and risk indicators for the entire portfolio are summarized in a dashboard, accessible through the menu View > Reports > Performance or via the sidebar (see Figure 1). A comprehensive review of the dashboard is available in the Reference Manual under View > Performance. As always, green values indicate a profit, while red signifies a loss.
Figure 1. Dashboard with key performance indicators - 2-year reporting period.
To follow along with the text and Figure 1, download the demo-portfolio-03 file. Select the 2-year reporting period (top right) from 2021-06-12 \u2192 2023-06-12. This implies that your portfolio already contained some stock by June 12, 2021. We begin by examining the Calculation Widget (on the right side).
share-1 shares valued at 17.79 EUR per share, totaling 177.94 EUR (look here for an overview of all transactions in the demo portfolio). Please note, that the historical price of the stock on that day is taken, not the original buying price.sidebar > Reports > Performance > Calculation and click on the Assets at End heading tab. The deposit account shows 125 EUR from deposit, buy, dividend, and sell transactions. share-1 is valued at 190.06 EUR (10 remaining shares x 19.06), and share-2 at 111.76 (8 shares x 13.97). In total, this sums to 426.62 EUR, representing the Final (market) value of your portfolio on June 12, 2023. share-1), and 67 EUR (share-2) are neutralized by buying both securities. Note that the original deposit and purchase of share-1 (155 EUR) is not included because it fell outside the reporting period.share-1 is somewhat complex due to the additional buy and sale. PP follows the FIFO (First-In-First-out) principle. From the remaining 10 shares, 5 will come from the first purchase and 5 from the second purchase. The historical quote at the first purchase date was 17.794 EUR/share and at the second purchase data 15.962 given an average price of (17.794 + 15.962)/2 = 16.878 EUR. The final market value is 19.006 EUR given a capital gain of 10 x (19.006-16.878) = 21.28 EUR. The value of share-2 has increased from 8 EUR (on 2022-09-30) to 13.97 (on 2023-06-12) or a capital gain of 8 x 5.97 = 47.76 EUR. Added together, this gives a total Capital Gain of 69.04 EUR.2023-04-12, you sold 5 share-1 shares at 22.40 EUR per share. Given the FIFO principle, the buying price was 17.794 EUR per share, producing a Realized Capital Gain of 5 x (22.40 - 17.794) = 23.03 EUR. -Earnings are caused by dividend payments (15 x 2 = 30 EUR), while Fees and Taxes encompass all fees and taxes incurred in the reporting period. Keep in mind that fees and taxes were also paid for the purchase of share-1, outside the reporting period.The first column of the dashboard lists the performance key indicators. We start with the more easily comprehended Absolute change and Delta.
Absolute Change minus the Performance neutral Transfers, resulting in 97.88 EUR. You might be tempted to think that Delta should be equal to the sum of all sub calculations (Capital Gains + Realize Capital Gains + ...). As you may noted however, the numbers in the calculation panel do not add up; e.g. Final value <> Initial value + ... Otherwise, you would have counted some elements twice. For example, the result of the dividend and sale is put on a deposit account and as such already included in both the Realized Capital Gains and Earnings and also in Performance Neutral Transfers.By defining a strategy and goal, investors can avoid emotional reactions to market fluctuations and stay focused on their long-term plans. You can use taxonomies (see also the previous section in this Getting Started chapter) and rebalancing to achieve this.
Rebalancing is a strategy of bringing a portfolio that has deviated away from one's target asset allocation back into line Wikipedia. This target can be set in the rebalancing view of a taxonomy (see Figure 1).
Figure 1. Rebalancing view.
The first step is to set the allocation goal for each category. For example, in Figure 1, the (rather counterintuitive) target allocation for the Foreign Currencies category is set to 70%, leaving 30% for the Base Currency category. You can enter or change the allocation percentage by double-clicking the cell, and the target value will be immediately adjusted.
The Rebalance (Amount) and Rebalance (Shares) columns show the amount and number of shares you need to sell (negative number) or buy (positive number) to reach the target value. Naturally, it isn't always possible to buy or sell a fractional number of shares.
Please note that the sum of the allocation percentages across categories does not need to be 100%, although it is advisable. Colour coding will draw your attention to any discrepancies if the sum isn't 100%.
"},{"location":"getting-started/updating-portfolio/","title":"Keeping the portfolio up-to-date","text":"The synchronisation between your physical and digital (PP) portfolio is crucial for making informed decisions. The status of your physical portfolio \u2014such as market value, balance total, and cash flows\u2014 should mirror your digital (PP) portfolio to ensure accurate decision-making. For instance, the rebalancing feature (see previous section) provides suggestions to buy or sell stocks based on the recorded holdings in your digital portfolio.
After making physical transactions with your broker or bank, you need to update your PP portfolio. This can be done manually or automatically:
Manual Update: You create transactions in PP based on the information from your bank or broker. Refer to Reference > Transaction Menu for details about all available transactions.
Automatic Import: You can import transaction data from your bank automatically. Depending on the format, this can be done using PDF documents or CSV files. It is very important that the structure and format of your data match the required format from the import wizard. For example, your CSV file might use a semicolon as a list separator (common in European countries). The import wizard should match this setting.
Importing a CSV File: Use the menu File > Import > CSV files (comma-separated values) to import historical quotes, accounts, securities, and transactions. See Reference > File > Import for further information.
Importing PDF Documents: Banks and brokers often provide account statements on paper or in PDF format. PP can read PDF documents from more than 90 banks or brokers. To verify if your bank is supported, try to import a PDF document. The import wizard will either recognise it automatically or display an error message listing all the banks/brokers it has tried. You can also search the forum using the term PDF import or PDF import [name-of-your-bank-or-broker] to see if an importer for your institution is available or if there are any issues with it. See Reference > File > Import > PDF Bank Documents for further information, including how to request a new importer for your bank.
If you've been following the steps outlined in the \"Getting Started\" chapter, you'll likely have noticed that your portfolio is still devoid of any securities. As of now, you haven't made any purchases. In the chapter Concepts we have covered the fundamental transactions of Buy, Sell and receive Dividends. Now, let's explore a possible workflow for effectively managing your investment portfolio.
There are three possible scenarios to consider, each with its own approach. The simplest one, of course, is starting from scratch.
Starting from scratch. You're beginning your investment journey with an empty portfolio. Apart from elementary strategic decisions about investment goals, risk tolerance, and time horizon, you need to instruct your broker or bank to acquire some securities. Then, you can enter these transactions into PP.
Reconstructing your current portfolio based on past transactions. You have already made some investments in the (far) past, and you need to reconstruct your current portfolio based on past broker or bank statements. Probably, you also need some financial data, such as historical prices or merger data. Depending on how far you would go back, this can be a very challenging task.
Beginning your portfolio management today with an initial valuation. Starting your portfolio management from today involves assessing your current financial situation. Start with the list of your securities and enter for each of them a buy transaction as of today. Of course, you loose some valuable info and the performance calculations aren't reflecting the real performance of your assets.
A bond is a financial instrument that represents a debt obligation. When an entity, such as a government or corporation, issues a bond, they are borrowing money from investors. In return, they promise to pay back the principal amount along with periodic interest payments over a specified period [1]. Bonds are not well-supported in PP but with a few simple workarounds mentioned in the German forum, you could manage them effectively.
"},{"location":"getting-started/manage-portfolio/bonds/#adding-the-bond-as-a-security","title":"Adding the bond as a security.","text":"Let's assume you've purchased a Volkswagen bond. You received the following banknote as shown in Figure 1.
Figure 1. Banknote of buying a bond.
Before you can add the buying transaction, you must create the security in the Securities account. Searching for the ISIN in PP does not yield any results, and searching by name returns the tradable Volkswagen shares. Therefore, you'll need to create an empty instrument and manually input the information for the bond. Historical bond prices aren't particularly crucial since the bond will ultimately be redeemed at 100% upon maturity. However, -if necessary- they can be downloaded in table format from for example the ariva.de website . It's important to note that bond prices in historical records are typically expressed as percentages, ranging from 0 to 100%, rather than in a specific currency like EUR, as is common for shares.
"},{"location":"getting-started/manage-portfolio/bonds/#recording-the-buy-transaction","title":"Recording the buy transaction","text":"Since historical prices are represented as numbers from 0 to 100, you can use this format also for the buying price. At maturity date, the bond will value 5000 EUR with a price of 100%. In terms of shares and quotes, this means that you will receive the value of 50 shares x 100 EUR. However, you buy the security at 91.76% (see banknote in Figure 1). The Gross Value becomes 50 x 91.76 EUR = 4588 EUR. Fees and taxes can be registered as usual.
The bond depicted in Figure 1 matures on October 1, 2027, with an annual interest rate of 2.25%, payable each year on October 1. Since you acquired the bond on October 27 (value day), there have already been 26 days of accrued interest. At a rate of 2.25%, this amounts to 5000 EUR * 2.25% * 26/365, or 8.01 EUR. You have to pay this accrued interest at the purchase date to the seller, but you will get it back on the first interest payment on October 1, 2023.
To process the accrued interest correctly, there are a few options; (see discussion on forum for a few variants).
Adapt the buying price. In case of the example in Figure 1, the buying price becomes 4596 EUR (=4588 + 8.01). The quote price becomes 91.92 EUR of 91.92% (=4596/50). The disadvantage of this method is that the price evolution and the performance calculation is not correct.
Figure 2. Workaround with adaptation of quote price to incorporate accrued interest.
To maintain a precise record of the purchase price, you could record the accrued interest as an additional tax (see Figure 3). The quote price is correct and the correct amount will be withdrawn from the deposit account. The 'false' taxes could be corrected at the first interest payment with a Tax refund transaction.
Figure 3. Workaround with adding accrued interest to taxes.
The buy transaction of the bond security is recorded without the accrued interest. To handle the accrued interest, you transfer the correct amount (8.01 EUR), from the deposit account associated with the security to a separate deposit account. During the first interest payment, the accrued interest amount then is transferred back to the original deposit account associated with the security.
The Transaction > Interest option is designed for recording interest payments on deposit accounts. While it could be utilized for recording bond interest payments, it lacks the ability to specify the security from which the interest originated. Consequently, the deposit account would aggregate all interest payments, without the ability to attribute a particular interest payment to the performance of a specific security.
A better, albeit somewhat unintuitive, approach is to record the transaction as a Transaction > Dividend. Dividends are tied to a specific security, in this case a bond, ensuring that the performance calculation of the bond remains accurate. Depending on the chosen recording option for the purchase (as discussed earlier), the following three transactions could be made.
The accrued interest is fully booked as a dividend (see Figure 4). The accrued interest (for the seller) on the purchase date (8.01 EUR) has already been accounted for in the recorded purchase price.
Figure 4. Interest payment 2.25% of 5000 EUR.
The interest payment (112.50 EUR) is reduced by the amount that was already recorded as tax on the purchase date (8.01 EUR). With a Tansaction > Tax refund that amount is refunded.
When you receive a notification from your bank or broker detailing a transaction, as shown in Figure 1, you need to record this transaction in PP. If it's on paper, you must do this manually. Otherwise, you can attempt to import the transaction.
"},{"location":"getting-started/manage-portfolio/buy/#transaction-with-one-currency","title":"Transaction with one currency","text":"The transaction in Figure 1 involves only one currency. Both the Security and the Deposit Account use the same currency (EUR). There is no need for currency conversion.
Figure 1. Paper note from your bank regarding your buy transaction.
With this note, you can enter the transaction details into PP. Figure 2 displays the input panel for entering the information. The security (Heidelberg Materials) is quoted in EUR and the transaction is handled with the broker-1 security account and the broker-1 (EUR) deposit account. The example of the sell transaction involves a more complex setup with a security quoted in USD, but the transaction handled through a deposit account in EUR.
Figure 2. Buying a security (EUR) through a deposit account (EUR).
Securities > All SecuritiesHelp > Preferences > Language > Country. For instance, the UK uses a 12-hour clock (with AM and PM), while Belgium uses a 24-hour clock.The above six fields are mandatory for completing the transaction. Most of these fields are pre-filled based on the selected security. The following fields are either calculated or optional.
Gross Value : This is the result of multiplying Shares by Quote. If you later change the Gross Value, the Quote Price will be adjusted accordingly to maintain the equation Shares * Quote.
Fees and Taxes : A purchase transaction typically incurs fees and taxes. These may be in the currency of the security and/or deposit account (see selling for an example).
Debit Note : This is the amount you need to pay as a result of this buying transaction. It is calculated as Shares * Quote + Fees + Taxes. Other terms for this are Value or Net Value.
Note : You can add a textual note to each transaction.
The typical flow for entering this information is likely to be Shares * Quote (price) >> Gross Value + Fees + Taxes >> Debit Note. There are a few nuances if you make changes afterward (see Figure 3).
Figure 3. Calculation flow between Shares and Debit Note.
If you want to purchase shares in a foreign currency, there are two options. Either you have the required amount in the foreign currency in a deposit account. Or, you'll need to make a deposit or convert another currency into the foreign currency first.
Figure 4 displays the bank's paper note regarding the purchase of USD shares. Since taxes and fees need to be settled in EUR (due to it being a European bank), and the portfolio's base currency for reporting is also EUR, the total amount in USD is also converted to EUR.
Figure 4. Paper note of a Buy transaction of a share in a foreign currency.
From the note, it isn't quite clear which deposit account (EUR or USD) is used. Recording this transaction in PP however is quite straightforward. Figure 5 shows the transaction done with a USD deposit account. Figure 6 is a little more complex because a EUR deposit account is used; so a conversion should be made (EUR --> USD).
Figure 5. Buy transaction of a USD security with a USD deposit account.
Figure 6. Buy transaction of a USD security with a EUR deposit account.
The quote price and the USD/EUR exchange rate are automatically filled in based on the entered date. However, please note that real-time prices are not available. The entry form in PP also provides the additional option to record fees and taxes in the foreign currency.
Remember: good practice requires making a deposit beforehand, either in USD (for the transaction in Figure 5) or in EUR (Figure 6). Failing to do so will result in a negative balance.
"},{"location":"getting-started/manage-portfolio/delivery/","title":"Recording a Delivery","text":"A Delivery (Inbound) transaction is akin to a Buy transaction, but it does not involve a decrease from a deposit account. It is as if the securities are acquired by magic, without any prior cash transaction. This could be the case for example when inheriting some securities. You also need a Delivery (Inbound) transaction when setting up your portfolio at a later date than the original purchases, without willing or being able to register all past transactions (see third option in Manage your portfolio). Figure 1 compares a Buy and Delivery transaction for the same acquisition.
Figure 1. Delivery (Inbound) versus Buy transaction.
You can record a transaction in a foreign currency by selecting the relevant currency from the drop-down menu. Additionally, it's feasible to record a transaction in a currency different from the security's default currency. An exchange rate will be suggested.
A Delivery (Outbound) transaction is similar to a Sell transaction, but -again- it does not affect a deposit account. The cash that would typically come back from the Outbound Delivery appears to vanish and isn't accounted for in any deposit account. Figure 2 illustrates a Delivery (Outbound) transaction involving Adobe stock (USD) but recorded in EUR.
Figure 2. Delivery (Outbound) of a USD security in EUR currency.
Although the Value of Outbound Delivery, fees, and taxes are not recorded in a deposit account, they can still impact the performance calculation.
"},{"location":"getting-started/manage-portfolio/deposit/","title":"Making a Deposit","text":"To initiate a deposit in a specific currency, navigate to the Transaction > Deposit menu. Ensure that the chosen account shares the same currency as the deposit. For transferring funds between accounts, whether in the same currency or different currencies (utilizing exchange rates provided by the ECB), employ the Transaction > Transfer between Accounts command.
Recording a deposit is a straightforward process (see Figure 1). Input the deposit account, transaction date, amount, and optionally, an accompanying note.
Figure 1. Making a provision for the Heidelberg buy transaction.
Please be aware that a deposit contributes to certain performance metrics. Additionally, note that each security purchase corresponds to a reduction in a deposit account. If the account balance is insufficient, the deposit account's balance may become negative.
"},{"location":"getting-started/manage-portfolio/deposit/#transfer-between-two-currencies","title":"Transfer between two currencies","text":"You can transfer funds between two accounts, whether they share the same currency or not. In cases where the accounts have different currencies (see Figure 2), PP will automatically suggest an exchange rate based on the ECB website.
Figure 2. Converting from EUR to USD.
"},{"location":"getting-started/manage-portfolio/dividend/","title":"Dividend","text":""},{"location":"getting-started/manage-portfolio/dividend/#dividend-transaction","title":"Dividend transaction","text":"Recording a dividend is similar to recording a buy or sale transaction, except that Quote price is replaced with Dividend payment per shares (see Figure 1). The number of shares is automatically determined based on the entered date.
Figure 1. Recording a dividend (same currency).
There isn't a dedicated function for recording a \"Dividend Investment Plan\" (DRIP). One workaround is to record all dividends in full and then proceed with a purchase of the agreed-upon number of shares.More information at Reinvesting dividends.
"},{"location":"getting-started/manage-portfolio/sell/","title":"Selling Securities","text":"The selling transaction is very similar to the buying transaction. Here as well, you can record the transaction's outcomes in an account with the same currency or a different currency. In the latter scenario (see Figure 1), upon selecting the foreign account (e.g. USD), three new fields become available: exchange rate (XR), USD fees, and USD taxes.
"},{"location":"getting-started/manage-portfolio/sell/#selling-a-single-buy-security","title":"Selling a single buy security","text":"In the demo portfolio, we've purchased the Adobe stock only once (10 shares). All those shares have of course the same price, so it doesn't matter which specific ones are sold in the case of a partial sale.
Figure 1. Selling a USD security through an EUR deposit account.
In Figure 1, the share is quoted in USD, and consequently, the Gross Value is also calculated in USD. However, since you intend to record this transaction in a EUR account, this USD value needs to be converted. As soon as you choose a deposit account with a different currency, the exchange rate field (e.g., 0.9491) is automatically filled with the correct exchange rate for that specific date and currency. This information is obtained from the European Central Bank (ECB) website. You can also consult it through the menu View > Currencies > Currency Converter.
Changing the date afterward will adjust the exchange rate (XR) appropriately, even if you've manually entered an XR. Therefore, it's considered good practice to set the transaction date first.
You have the flexibility to input fees and taxes in both currencies. The foreign fees and taxes are automatically converted using the same exchange rate as above. There isn't a subtotal in the local currency, so the Credit Note amount isn't a simple sum of the numbers above.
The calculation flow remains consistent with Figure 3 in the buying page. For instance, modifying the Credit Note will subsequently adjust the Gross Value in EUR, which, in turn, impacts the Gross Value in USD (XR remains unchanged), and finally, the Quote price.
"},{"location":"getting-started/manage-portfolio/sell/#selling-a-multiple-buy-security","title":"Selling a multiple buy security","text":"In your portfolio, some effects may have been purchased multiple times at different prices (see Figure 2 for an example). What happens when you partially sell that share?
Figure 2. Multiple transaction on the same security.
Do those shares come from the first or second series that you purchased, or from a combination of both? For the actual sale, it doesn't matter. In the example from Figure 2, 40 shares were sold at a price of 72.48 EUR. But how are the remaining shares valued? PP follows the FIFO principle (First In, First Out). So, the 40 shares that are sold come entirely from the first purchase. What remains are 10 shares from the first batch and 30 shares from the second batch. Another possibility would be LIFO (Last In, First Out). In that case, 10 shares from the first batch would remain, and none from the second batch. Does this make a difference? In this particular case, the stock is valued lower in the FIFO approach.
FIFO: average price of the remaining 40 shares = ((10 * 58.82) + (30 * 39.60)) / 40 = 44.05 EUR
LIFO: average price of the remaining 40 shares = ((40 * 58.82) + (00 * 39.60)) / 40 = 58.82 EUR
The how-to section demonstrates the features and functions of the Portfolio Performance program in a real-world context. Check the sidebar (or click the menu if it is collapsed) to view all topics. A brief summary of each topic, listed in alphabetical order, is provided below.
Benchmarking your portfolio: Benchmarking involves comparing your portfolio's performance against financial indexes like the S&P 500. This section explains how to find and add indexes from sources like Yahoo Finance and investing.com. It also covers displaying benchmarks in performance charts and comparing your portfolio's performance to these benchmarks.
Copy securities between portfolios: This page explains how to transfer securities between different portfolios in the Portfolio Performance software. It covers methods like Drag & Drop, Exporting & Importing, and Copy and Paste (with intermediate CSV-file). The page also discusses the complexities of copying between XML files.
Downloading Historical Prices provides various methods and sources for obtaining historical stock prices. Most securities are covered by Portfolio Report or Yahoo Finance. In some cases, more sophisticated methods may be required, such as downloading from a CSV File, utilizing a JSON Quote Feed Provider to fetch data, or scraping a table on a website. There are many other sources such as Alpha Vantage, EODHD, and Morningstar .
Handling Choice Dividends focuses on choice dividends where shareholders can choose between cash or stock payments. It includes practical methods for booking these transactions in Portfolio Performance.
Import GBX Priced Securities is a short guide for importing transactions and securities priced in GBX (pence). It emphasizes creating securities with the correct currency and preparing transaction data for import as CSV files.
Inspecting Source Code provides instructions on examining the Portfolio Performance source code on GitHub to understand calculation methods, such as the volatility indicator.
Recording a Merger, Spin-Off, or Stock Split is quite common in portfolio management. These pages discuss various methods, applied to some real examples such as the Amazon stock split, the Daimler Truck Holding AG spin-off, and the Unipol Gruppo's merger. The section about Insolvency explains how to handle securities of insolvent companies, including disabling automatic quote updates, deleting historical prices, and manually adjusting security values.
Importing PDF-bank notes can be a significant time-saver. Requesting a New PDF Importer provides guidance for specific bank or broker transactions, including how to extract and anonymize PDF text, submit requests on the PP forum, and wait for developer integration.
Retrieving gold and other precious metals prices: This page discusses various methods to invest in gold, including physical gold, ETFs, and shares of gold mining companies. It explains how to download historical gold prices from websites like Ariva.de, LBMA, and Gold.org.
User Interface Overview Describes the elements of the PP user interface, such as the menu bar, sidebar, dual-pane layouts, tables within the main pane, and keyboard shortcuts for essential functions.
Most tips and tricks are initially discussed on the PP forum. Regularly checking this forum will provide you with valuable insights into the PP program. It's worth noting that a significant portion of the information on the forum is in German, but you can use your browser's translation function to understand it in your preferred language.
"},{"location":"how-to/benchmarking/","title":"Benchmarking your portfolio","text":"Benchmarking your portfolio performance against financial indexes is a common practice in investment management. This process involves comparing the returns of your portfolio or individual securities to the returns of a selected benchmark index.
A stock index is a measure of the value of a hypothetical portfolio of investment holdings that represents a segment of the financial market. For example, Standard & Poor\u2019s 500 index measures the performance of 500 large companies listed on stock exchanges in the United States. It is a market capitalization-weighted index, which means that the influence of each company in the index is proportional to its market capitalization. On March 8, 2024, the S&P 500 Index stood at 5,123.69 USD.
"},{"location":"how-to/benchmarking/#finding-an-index","title":"Finding an index","text":"A list of major indexes can be found on several financial websites such as investing.com and Yahoo Finance. In order to use an index for benchmarking your portfolio, you need to add it as a security.
For the indexes listed on Yahoo Finance, simply add a new security and search for the ticker symbol; e.g. ^GSPC. If you want to use the data from investing.com, you have to download the historical prices. Select the correct time period and click the download button to receive a CSV-file (you need a free registration for that). Create a new empty instrument. See the section File > Import and How-to > Downloading Historical Prices for a detailed explanation how to import these historical prices. For appending the future daily prices, you can use the daily updated table from the last month. Set the Quote Feed of the Historical Quotes to Table on website and use the following Feed URL: https://www.investing.com/indices/us-spx-500-historical-data. This Quote Feed will not overwrite the existing prices but will append new ones.
There are plenty of mutual funds or ETF's that replicate an index. For example, both Vanguard 500 Index Fund Admiral and the iShares Core S&P 500 ETF replicate the S&P 500 quite narrowly. So, you could use also one these funds as benchmark.
Figure 1. Benchmark of SP 500 index with two replicating funds.
As depicted in Figure 1, the iShares Core S&P 500 ETF closely mirrors the S&P index. The Vanguard index fund also follows the trend closely but exhibits some deviations.
"},{"location":"how-to/benchmarking/#displaying-the-benchmark","title":"Displaying the benchmark","text":"To display a graph similar to Figure 1, follow these steps:
View > Reports > Performance > Chart.Configure Chart icon, represented by a gear symbol, located in the top right corner of the screen.time series and benchmarks.Please take note that the historical prices for the displayed securities differ notably: roughly 5000 USD for the S&P index, and approximately 500 USD for both the iShares ETF and Vanguard index fund. Despite this discrepancy, the curves overlap, indicating that the vertical value axis of the graph represents the performance (not USD). The chart is indeed a performance chart.
"},{"location":"how-to/benchmarking/#comparing-to-the-benchmark","title":"Comparing to the benchmark","text":"Naturally, you'd want to compare the performance of your portfolio or that of an individual security against one of the benchmarks. You may also wish to evaluate your track record of buying and selling by comparing it with the unbiased historical prices of a specific security.
Figure 2 compares the performance of Share-1 (Benchmark) with the actual Share-1 in the portfolio in the main pane. See above for adding both indices to the performance chart. The information pane contains the chart of share-1 with the buy, dividend, and sell transaction indicated. The reporting period spans 3 years for both panes, commencing from May 5, 2021.
Figure 2. Benchmark of SP 500 index with two replicating funds.
The historical price of share-1 was 16.412 EUR/share on 2021-05-05. Therefore, the Market Value Begin (MVB) for the actual share-1 is 164.12 EUR (10 shares) and for the benchmark, it is 16.412 EUR (1 share). You can always export the performance chart as CSV-file to obtain precise numerical data.
After some initial fluctuation, the quote price dropped to 16.026 EUR/share on 2022-01-13 (the day before the second purchase). Using Equation 1 of the section on Time-Weighted Rate of Return, this results in a performance of - 2.35% for both indices.
From that point onwards, the two indices begin to diverge. The benchmark solely utilizes historical prices, while the performance of the actual Share-1 takes into account both inbound and outbound transfers. For instance, on January 14, 2022 (date of purchase), the quoted price was 15.962 EUR/share. Consequently, the daily performance of the benchmark was calculated as 15.962/16.026 = -0.40%, leading to a cumulative performance of -2.74%. Meanwhile, the daily performance of the actual Share-1 was calculated as follows: MVB = 10 x 16.026 = 160.26 EUR; MVE = 15 x 15.962 = 239.43 EUR. The purchase value of 5 additional shares was 83 EUR (inclusive of 3 EUR in fees). According to Equation 1 of Time-Weighted Rate of Return, the daily performance of the actual share-1 is -1.57% (versus -0.40% for the benchmark), giving a cumulative performance of -3.89%.
The most significant divergence occurs when a dividend is paid on December 15, 2022. The performance of the actual Share-1 benefits from this additional outbound transfer, resulting in a significant increase in the daily performance of around 9%.
As previously mentioned, the numerical values for both indices can be obtained from the CSV file. However, the Securities table under View > Report > Securities does not include information on share-1 (Benchmark) due to the absence of associated transactions. Nevertheless, it is feasible to present the benchmark's performance graph and the TTWROR value as a widget.
Figure 3. Dashboard with performance chart and TTWROR widgets.
"},{"location":"how-to/copy-securities/","title":"Copy securities between portfolios","text":"Sometimes, it is necessary to transfer securities between different portfolios, which involves copying information between physical XML files. However, the challenge lies in the fact that each security has historical pricing data associated with it, along with transactions tied to various cash accounts.
"},{"location":"how-to/copy-securities/#drag-drop","title":"Drag & Drop","text":"After opening two or more portfolios, they are displayed as tabs in the portfolio bar located just below the menu bar. The active portfolio, typically the last one opened, is easily discernible. It appears with a lighter color and an x-mark after the name, allowing you to close the tab. To switch between portfolios, simply select the corresponding tab in the portfolio bar. Only one portfolio can be viewed at a time.
However, for tasks like copying securities between portfolios, it's necessary to have both portfolios visible side by side. Securities cannot be directly dragged and dropped or copied and pasted between portfolios from the tabs in the portfolio bar.
Figure 1. Side-by-side display of two portfolios.
To arrange portfolios side by side, choose one in the portfolio bar, click and hold the mouse to drag it to a new position. With two portfolios, you can position them either horizontally (left to right) or vertically (top to bottom). In Figure 1, the arrangement is left to right. This process can be repeated with multiple portfolios, allowing you to make more than two portfolios visible at the same time. To restore the original arrangement, drag the portfolio into the portfolio bar.
For copying securities between portfolios, both portfolios need to be visible. Then, you can select a security from Portfolio A and drag it to the All Securities option in the side panel of portfolio B. There, you can drop the security to create a copy. Pay attention, as it's feasible to unintentionally create identical securities (e.g. two instances of share-1). You can also drop the security to a Watchlist. It will be added to this list then automatically.
Important
When you copy securities from one portfolio to another with drag-and-drop, the associated transactions will NOT be copied along with them. Only the security master data, including historical price information, will be transferred to the new portfolio. This means that any trades, dividends, or other transactions that were recorded for the security in the original portfolio will not be reflected in the new one. In the relatively rare case you need also the transactions, you can either enter them manually or use the following method.
"},{"location":"how-to/copy-securities/#exporting-importing","title":"Exporting & importing","text":"With the menu File > Export > CSV Files, you can create a list of all securities, historical prices, and transactions. See File > Export for more info. Copying the securities with their historical prices however is much easier with the drag & drop technique, described above.
For example, after dragging share-3 from Figure 1 above to the demo-portfolio-03.xml, you can export the transactions of demo-portfolio-04.xml and import them in demo-portfolio-03.xml. You can either use the import type Accounts transactions or Portfolio transactions. The result of the export however contains ALL transactions of the project, not only those that are linked with share-3.
From this table, in fact, you need only the last row. Please note, that the purchase of share-3 is in USD. Because the main cash account is set to EUR, this will generate an error, unless you change (via the context menu) the cash account to USD for that particular transaction.
As can be seen in Figure 2, all transactions will be imported (green checkmark to the left). You can exclude the first four with the context menu Do not import (see Figure 2). Alternatively, you can delete the unwanted transactions from the original CSV file before importing it.
Figure 2. Importing transactions with change of cash account and exclusion.
A more efficient way to select desired transactions is to begin from the All Transactions view. While this list may be extensive, you can streamline it using the Search function. For instance, entering share-3 will filter the transactions to only display those associated with the security named share-3. Alternatively, you can utilize the Filter function available under View > Accounts > All Transactions. You can further narrow down the list by selecting individual transactions (see following topic).
Once you've refined the list, you can export it as either a CSV or JSON file. Click on the Export Data button (located at the top-right with an up-pointing icon) to export either all the displayed transactions or only the selected ones.
"},{"location":"how-to/copy-securities/#copy-and-paste","title":"Copy and Paste","text":"At times, it may be simpler to manually copy and paste the desired transactions, albeit still requiring a CSV file format to import the data.
This technique will also work in the All Transactions view (see previous topic).
Theoretically, one could also copy the transaction code between the two XML files. However, the XML code is optimized for speed which has a negative impact on the readability. A Buy transaction, for example, is represented by the following code snippet:
<account-transaction>\n <uuid>0e6a94e5-da57-44d4-aeb1-37dc792d40ef</uuid>\n <date>2024-03-14T00:00</date>\n <currencyCode>EUR</currencyCode>\n <amount>19800</amount>\n <security reference=\"../../../../../securities/security[2]\"/>\n <crossEntry class=\"buysell\">\n <portfolio>\n <uuid>c1c03e7d-c320-4167-8737-2f35cfb1a2e0</uuid>\n <name>broker-1</name>\n <isRetired>false</isRetired>\n <referenceAccount reference=\"../../../../..\"/>\n <transactions>\n <portfolio-transaction>\n <uuid>75c79e11-4c3d-4b39-bf91-08ab04fe0088</uuid>\n <date>2024-03-14T00:00</date>\n <currencyCode>EUR</currencyCode>\n <amount>19800</amount>\n <security reference=\"../../../../../../../../../securities/security[2]\"/>\n <crossEntry class=\"buysell\" reference=\"../../../..\"/>\n <shares>9900000000</shares>\n <updatedAt>2024-03-14T10:06:25.707240300Z</updatedAt>\n <type>BUY</type>\n </portfolio-transaction>\n </transactions>\n <attributes>\n <map/>\n </attributes>\n <updatedAt>2024-03-13T18:11:15.593620500Z</updatedAt>\n </portfolio>\n <portfolioTransaction reference=\"../portfolio/transactions/portfolio-transaction\"/>\n <account reference=\"../../../..\"/>\n <accountTransaction reference=\"../..\"/>\n </crossEntry>\n <shares>0</shares>\n <updatedAt>2024-03-14T10:06:25.707240300Z</updatedAt>\n <type>BUY</type>\n</account-transaction>\n<security reference=\"../../../../../../../../../securities/security[2]\"/> -which are the result of the optimization- assume an identical structure between the source and target XML, concerning list of securities. Moreover, this method is -of course- not applicable to binary-coded portfolios."},{"location":"how-to/gold-prices/","title":"Retrieving gold and other precious metals prices","text":"Investing in gold is often chosen in times of economic uncertainty. There are multiple ways to gain exposure to gold. One popular method is investing in physical gold, which involves purchasing gold bullion, coins, or jewelry. Another approach is investing in gold exchange-traded funds (ETFs) or gold trackers, such as Invesco Physical Gold. These financial instruments aim to replicate the performance of the gold price by holding physical gold in a secure vault. A third but indirect method of investing in gold is by purchasing shares of gold mining companies. Gold miners engage in the exploration, extraction, and production of gold, and their stock prices can be influenced by the price of gold.
Investing in gold through ETFs and gold mining company shares can be handled similarly to regular stocks like Apple Inc., offering ease of access, liquidity, and potential income. While physical gold differs from traditional stocks in several aspects (e.g. gold does not provide ownership in a company or entitle the holder to dividends), it can still be considered an investment that can be bought, sold, and managed as part of a well-diversified portfolio. And therefore, it can be handled in PP as a regular security.
The PP forum has a thread Wo kann ich aktuelle und historische Gold- und Silberkurse laden?. This section provides a summary and expands upon the information discussed in the thread.
"},{"location":"how-to/gold-prices/#website-arivade","title":"Website Ariva.de","text":"The ariva.de website has a specific page for commodities such as gold, silver, and others. Downloading the latest gold price is as easy as setting the Quote Feed to a webpage https://www.ariva.de/goldpreis_gold-kurs/kurse/historische-kurse. Unfortunately, this method only provides data for the last 30 days. As time progresses, the data will be updated for future days with this method, gradually accumulating several months of gold price history.
Figure 1. Ariva.de website (translated) with historical gold prices .
You can also replace the Quote Feed URL by one of the previous months (e.g. https://www.ariva.de/goldpreis_gold-kurs/kurse/historische-kurse?go=1&boerse_id=172&month=2024-02-29). When importing the data, PP will ask if you want to keep the existing historical prices. By choosing to keep the previous data, you can maintain a continuous record of gold prices for all the months you have downloaded.
But, perhaps the better method is to use a dynamic data URLs. Replace the month=2024-02-29 in the URL from above in the macro version month={DATE:yyyy-MM-32}. This macro will iterate through all previous months (going back to 2003) and send a request for each month until there is no data available. If you start from scratch, this process can take some time and will put a significant load on the ariva.de web server.
Another option to obtain historical gold prices is to register for a free account. Then you can download the historical prices as a CSV file, which can be imported into Portfolio Performance (PP).
"},{"location":"how-to/gold-prices/#london-bullion-market-association-lbma","title":"London Bullion Market Association (LBMA)","text":"The London Bullion Market is the world's largest and most significant market for trading gold and silver. You can retrieve the prices for gold, silver, platinum and palladium per year, going back to 1968, in USD, GBP, and EUR. There are two auctions per day (AM and PM). The data can be displayed as a graph or table per year.
Unfortunately, this table could not be parsed by PP (as it does not contain the necessary keywords such as Close). However, as User ristretto pointed out, you can retrieve the prices through the JSON Quote Feed (see How-to > Downloading Historical Prices). The Feed URL is https://prices.lbma.org.uk/json/gold_pm.json for the PM auction. The three prices under the \"v\" (value) key represent USD, GBP, and EUR, respectively. Please note that in 1968, there is no price available in EUR.
[\n {\n \"is_cms_locked\": 0,\n \"d\": \"1968-04-01\",\n \"v\": [\n 37.7,\n 15.68,\n 0\n ]\n },\n {\n \"is_cms_locked\": 0,\n \"d\": \"1968-04-02\",\n \"v\": [\n 37.3,\n 37.3,\n 0\n ]\n },\n ...\n]\nYou can discover the JSON Endpoint URL by opening the developers tool panel in the webbrowser, selecting the network tab, and refreshing the chart. The Path to Date is $.*.d and the Date Format is yyyy-MM-dd. The Path to Close is $.*.v[0] for the price in USD.
Figure 2. Gold prices through JSON Quote Feed from London Bullion Market.
"},{"location":"how-to/gold-prices/#website-goldorg","title":"Website Gold.org","text":"The website gold.org offers historical gold prices in different currencies and for various quantities (oz, grams, kg; 1 (troy) ounce = 31.1034768 gr). To access the numerical data, you'll need a workaround. First, open the gold prices graph. The server sends a text file (JSON file) containing the data, which is then used to create the graph locally on your computer. This method is more efficient in terms of time and bandwidth.
To find the URL for the JSON download, follow these steps:
Figure 3. gold.org website with developer tools visible.
The URL should look something like:
https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,1709582076959?cache
Upon entering this URL in your browser, you will see the result displayed below.
{\n \"system\": {\n \"request_time\": \"2024-03-04 20:19:20\",\n \"APIserverHostname\": \"fsapi.gold.org\",\n \"protocol\": \"https\",\n \"uri\": \"https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,1709582076959\",\n \"route\": \"fsapi.gold.org\",\n \"cached\": false,\n \"q\": false,\n \"params\": {},\n \"user\": null,\n \"response_size\": 3318,\n \"time_start\": \"2024-03-04 20:19:21\",\n \"time_stop\": \"2024-03-04 20:19:21\",\n \"mem_start\": 32540152,\n \"time\": \"0.021 secs\",\n \"mem_stop\": 57446376,\n \"mem_used\": \"24322.48 KB\",\n \"size\": \"3.33 KB\"\n },\n \"chartData\": {\n \"USD\": [\n [\n 1693872000000,\n 1926.1\n ],\n [\n 1693958400000,\n 1922.05\n ],\n [\n 1694044800000,\n 1918.35\n ],\n [\n 1694131200000,\n 1927.8\n ],\nYou may remove the ?cache parameter. Keep in mind that the workaround may change if the website updates its structure or data retrieval method.
This URL provides JSON data of gold prices between two dates, expressed as Unix timestamps (number of milliseconds since January 1st, 1970), for example, 1693853240038 and 1709582076959. You can easily convert these timestamps to human-readable dates and vice versa using the Epoch Converter website. Luckily, PP can work natively with these dates.
Of course, you want the gold prices until today, not March 4, 2024. Leaving out the second parameter will do that. So, the following URL will display the gold prices from September 4, 2023 until today (note the comma at the end).
https://fsapi.gold.org/api/goldprice/v11/chart/price/usd/oz/1693853240038,To extract the date and the price, you need the JSON-path (see Figure 4).
Figure 4. Quote Feed JSON Provider with Feed URL and Path to Date and Close.
"},{"location":"how-to/handling-choice-dividend/","title":"Handling choice dividends","text":"A dividend is the payment of a part of the company's profit to its shareholders. With a choice dividend, shareholders are given the option to choose between receiving cash payment (cash dividend) or additional shares of stock (stock dividend).
"},{"location":"how-to/handling-choice-dividend/#example-nn-group","title":"Example NN Group","text":"For example, the Dutch financial services company, NN Group provided its shareholders with the option to receive the interim dividend for 2023 of 1.12 EUR per share, either in cash or in shares. The ex-dividend date was set on August 31, 2023, with the dividend payment scheduled for September 25, 2023. The reference share price was determined at 36.2513 EUR by taking the average of five daily historical prices between 12 and 18 September 2023 on Euronext Amsterdam between 12 and 18 September 2023.
With this reference price the distribution ratio was established at 1-for-32.37 shares. Indeed, to receive one share of 36.2513 EUR, you need 32.37 shares x 1.12 EUR dividend.
Theoretically, the cash and stock dividend options should lead to the same gross result. Otherwise, shareholders would naturally gravitate towards the more advantageous choice. Let's consider a scenario where you hold 100 shares of the NN group at the ex-date. Opting for the cash dividend would yield 100 shares x 1.12 = 112 EUR gross. On the other hand, choosing the stock dividend would grant you approximately 3.09 shares (100 shares / 32.37), valued at 36.2513 EUR per share. This totals around 112.02 EUR gross, which is approximately equivalent to the cash dividend amount. Please note that fractional shares are not always possible; although PP can easily work with them. So a solution for the .09 shares may need to be found.
Of course, your choice will be influenced by your need for immediate liquidity (prompting for cash dividend) and your desire to further invest in this company (stock dividend).
Although theoretically equivalent in terms of the gross value, factors such as fees, taxes, and various fiscal and broker regulations will impact the final net amount of cash retained. In practice the choices do differ. For example, a Belgian (thus, foreign) shareholder with 100 shares will receive 68.12 EUR of cash dividend, while the stock dividend is valued at 72.93 EUR; approximately 7% more. This difference is primarily caused by the elimination of foreign taxes in the case of stock dividend.
Note
If you opt for cash dividend. You receive a Gross Amount of 100 x 1.12 = 112 EUR. The net value depends on the fiscal and broker regulations of your country. For example, as a Belgian shareholder, you pay 10% foreign taxes (=11.2 EUR), 30.24 EUR or 30% domestic taxes on the remaining value (112 - 11.2 = 100.8), 2.44 EUR or 2% broker fees + TVA 21%. The remaining net value is 100.8 - 30.24 - 2.44 = 68.12 EUR.
You choose for stock dividend. The calculation becomes much more complex. Your broker need to solve the fractional share and you have to decide about the valuation of the newly acquired shares.
Certainly, the calculation above applies only for a Belgian shareholder with a particular broker in 2024. The advantage of the stock dividend is primarily due to the foreign tax situation, which may differ significantly for shareholders in other countries, particularly Dutch shareholders.
Important
Note that in the case of cash dividend, you will receive money, while with the stock dividend, you have to invest additional money. Although you receive the shares, you also have to cover the associated taxes and fees.
"},{"location":"how-to/handling-choice-dividend/#recording-the-choice-dividend-in-pp","title":"Recording the choice dividend in PP","text":"There has been a lot of debate about how to book these transactions in PP. Many users suggest considering the choice of dividend as a sequence of receiving the dividend and purchasing the shares. A possible workflow is the following.
Figure 1. Implementation in PP
"},{"location":"how-to/import-gbx/","title":"How to use the CSV Import functions for GBX priced securities","text":"The following how-to is based on a discussion Getting started: Cash vs Deposit/Reference accounts in the English language forum.
"},{"location":"how-to/import-gbx/#introduction","title":"Introduction","text":"Portfolio Performance (PP from now on) supports importing of different currencies when importing transactions and movements on cash/deposit accounts. Before reading this guide, you should refer to the main guide on importing which covers things which we will not duplicate here.
This guide is mainly about the peculiar situations which can arise from the UK market habit of pricing some securities (in particular funds) in pence (GBX in PP language) rather than pounds (GBP). This causes complications because our accounts (Securities accounts where we hold the actual securities and Cash accounts used to show money deposited for purchases and obtained from sales of securities) will be in GBP. GBP and GBX are different currencies in the eyes of PP (and many other portfolio tools). So there is actually a conversion which is treated as a currency exchange by PP that needs to happen -- it's a special case.
The importer does a lot well, but has limitations and is at times more helpful or less helpful when it comes to error messages. The process needed to make this work is not always intuitive. It is also possible to successfully import and then find later that the transactions are not actually correct.
The main guide on importing now helps a great deal. It is possible to figure out how to do it now that that guide exists. This extra information is intended to spell out exactly how to do it and hopefully spare some frustration which can otherwise occur.
"},{"location":"how-to/import-gbx/#the-basics","title":"The Basics","text":"If you have a securities account (and probably an associated cash/deposit account) in pounds (GBP), and you need to import anything which was handled in pence, you are doing a currency conversion during the import. The exchange rate is always the same (i.e. 1 GBP = 100 GBX), but it is still a conversion which PP will not handle automatically unless you tell it the currency and exchange rate.
This is NOT a guide about importing GBP and GBX transactions into accounts operated in another currency (e.g. Euros or USD). Some of this information may still be useful in such cases, but it has been written, checked and tested to cover a specific scenario.
It is worth learning how to prepare your import data in a spreadsheet. The more that is done like this, the easier and more reliable your imports will be. It will be more work up front (especially if you need to learn some spreadsheet tricks), but pays dividends later.
For now, we will cover the import assuming the use of spreadsheets in the right form. To be accurate, we will actually be using comma separated value (CSV) files for the actual importing, but the most likely way to create these will be using a spreadsheet tool (e.g. Excel or Google Sheets). The process will involve:
Special care is needed creating securities when dealing with GBX denominated securities.
It is better to create your Securities FIRST in PP.
If you import transactions where a security does not yet exist, PP will create the security. But it will create it with a currency of GBP if the Securities account is in GBP.
You cannot change the currency of a security once you have imported transactions against it and it also creates other extra work. So this is best avoided.
You can create the securities manually, but here we will cover how to use an import.
"},{"location":"how-to/import-gbx/#preparing-securities-data","title":"Preparing Securities Data","text":"The main guide to import covers how to import Securities so we will focus here on things to watch out for when creating GBX securities.
Quick Version
Create a CSV file for the import with the right headings and information for each security. As the main guide to importing securities explains, there are no mandatory fields for a securities import, but one of the descriptors of the security (Ticker Symbol, ISIN, WKN or Security Name) will be needed or you will be importing nothing.
For the purposes of this guide we will be assuming we want to use Yahoo! Finance (YF from now on) later for our historical quotes (prices) and will focus on that case. If you plan to use a different provider of historical quotes, it will be worth looking into what ticker symbol or other identifier (e.g. ISIN, WKN) that source uses and including it at this stage. The YF ticker symbols are really only used by YF. To make things more complex, YF does use some more generic symbols sometimes. You can see this in the example below for VWRP.L, EQIX and GILG.L.
So the information in this CSV will consist of (at a minimum): Ticker Symbol, Currency.
It is worth adding Security Name while you're at it. Like this:
Figure 1. Securities Import spreadsheet example.
The figure above shows an example of a spreadsheet with a number of securities defined. This can be saved as a comma-separated values (CSV) file for import into PP.
Follow the main Securities Import guide for how to import the file.
Explanation
It is worth getting the list of all the securities you want to use across all Securities Accounts together with the Ticker Symbol of your chosen provider of historical quotes (prices) and the security's currency (e.g. GBP, USD, GBp/GBX). If you will be using YF for your historical prices, it is unlikely your broker export will provide the Yahoo! Ticker symbol so you will need to add this.
YF's portfolio tools can be helpful here as it is possible to create a list of securities by searching for each one and adding it to a portfolio. You can create a view of that portfolio showing the information needed above. See example below:
Figure 2. Example Yahoo! Finance portfolio view.
Unfortunately the YF export function does not respect the view you created. Instead, select the data from your browser and then copy and paste into a spreadsheet. When pasting, select to paste as text only.
If using this route it will be necessary to change YF's symbol for pence (GBp) to PP's symbol (GBX). But a simple (but remember case-sensitive) Find/Replace can do that. In the example below, the column names have been changed to match what is required by PP and GBp has been replaced by GBX.
It is worth reiterating a point made in the main Import guide. The currency column should be named \"Transaction Currency\". This is despite PP calling it \"Currency\" in the Import wizard. If you label the column \"Currency\" it will not be automatically selected for import (you will see that the column is not green in the Import Wizard). It is simple to select the column heading in the Import Wizard however if needed.
The name \"Transaction Currency\" may confuse. When you actually buy and sell, your broker platform will probably do everything in GBP not GBX, so it may seem odd that the Transaction Currency is being defined here in GBX. What is really meant is the denomination of the security for pricing/quotes. PP needs to understand what currency the price/quote it receives from a provider is in.
Figure 3. Example Securities CSV import created from a copy/paste from Yahoo! Finance.
"},{"location":"how-to/import-gbx/#importing","title":"Importing","text":"Follow the main guide to importing Securities.
Make sure that all the columns of your data are highlighted green in PP when you start the Import Wizard. Various issues (such as invisible characters present in the column name of the CSV) can mean that PP will not automatically detect the right column name mapping. If this happens, double click where it says \"Double click here\" and select the correct field name from the dropdown.
As discussed in the main guide, although PP will search for providers of historical quotes (prices) it probably will not find many and will not select YF as the source.
You can select historical pricing providers later manually after importing the securities. You may wish to delay this step until after you have checked and imported some transaction data so that you know you are happy that your Securities have been created correctly.
Now that we have our securities loaded, we can move on to importing transactions against these.
"},{"location":"how-to/import-gbx/#preparing-your-transaction-data","title":"Preparing Your Transaction Data","text":"Quick Version
Create a CSV containing all the transactions you wish to import that looks like the (spreadsheet format) example below and has these column names.
Figure 4. Example Portfolio Transactions import data.
Important - Import using the \"Portfolio Transactions\" type of data in the Import Wizard. Using the default of Account Transactions will not work.
Explanation
In these examples, the transaction currency is GBP. So the Value, Fees and Taxes are in GBP.
The objective here is to ensure that your CSV of portfolio transactions is consistent and has the correct currency units and exchange rates before importing.
It is necessary because data exported from broker platforms is very unlikely to be exactly right for PP import and additional data will be needed.
Figure 5. Example Portfolio Transactions import data.
In the example above we have the following columns:
Date -- the transaction date. Here we have formatted in the PP default date and time format. It can also be just in YYYY-MM-DD format. This can be changed by using a \"Custom\" number format if using Excel and entering YYYY-MM-DD as the format. The date can be in other formats, but then you will need to choose the right format in the import wizard which is slower and is easy to forget leading to incorrect dates being imported. Essential.
Securities Account -- this helps avoid errors from overlooking the selection of the correct Securities Account in the Import Wizard. It is essential if you want to import transactions into more than one account in the same import, otherwise it is optional.
Cash Account -- this is included for the same reasons as Securities Account.
Type -- the type of transaction. Essential.
Value -- the net value of the transaction in the base currency of the securities account (i.e. the number of shares x the price of the transaction in the base currency of the securities account). In this case, all the values here are in GBP (\u00a3s) NOT GBX/pence. Essential.
Currency Gross Amount -- the denominated currency of the security. NOT the transaction amount currency. Where the pricing currency of the security matches the currency of the securities account, this is blank, but is Essential where there is a difference.
Exchange Rate -- the rate to convert from the Value to the denominated currency (GBX) of the security amount by multiplication. Essential where the currency is not the same as the securities account currency -- i.e. essential when you have a GBX or say USD denominated security. Only non- essential when the security is priced in GBP.
Fees and Taxes -- self-explanatory and optional. These need to be in the base currency of the securities account/cash account -- in our case, GBP/\u00a3. Optional.
Shares - the number of units/shares traded. Essential.
Ticker Symbol -- the unique ticker symbol used to identify the security. In this case, this is the YF ticker. One of Ticker Symbol, Security Name, ISIN or WKN is required. When we created the securities (see earlier), we specified the Ticker Symbol and the Security Name only. Either of these will do.
"},{"location":"how-to/import-gbx/#importing_1","title":"Importing","text":"Follow the main guide to importing portfolio transactions.
When you click \"Next\" after the first wizard screen, PP will show you which transactions have loaded (green tick) and which may have failed (white cross in a red circle and struck through) in the \"Status\" column as shown below (Status is abbreviated to S. because of the column width).
Figure 6. Import showing two incorrect transactions and a transaction where no security exists.
In the above example, two transactions are marked as errors. The security (iShares Global Inflation Linked Govt...) is actually priced in GBP, but I changed the currency of the security in PP to GBX before this import to illustrate the error.
Because the import CSV (see earlier) does not have an exchange rate for transactions on this security, PP does not know how to convert from the transaction currency (GBP) to the security currency (GBX).
Also note the last line of this import screen showing a Type of transaction \"Security\". This is there because I did not create this security in PP before importing transactions for it (you will notice it was missing from the Securities import example earlier). PP is smart enough to create the security when you first import a transaction. If it is a GBP security this is helpful and a timesaver.
BUT, if the security is a GBX priced security, this will cause a problem because PP will create the security with GBP as the currency (it defaults to the currency of the Securities account). You should therefore cancel the import and fix the problem by creating the security before re-attempting the import.
If you do not do this, then you will need to delete any transactions for the problem security, delete the security, recreate the security with a currency of GBX and then import again.
You can use the same transactions CSV import file because PP will ignore any transactions already loaded from that file showing these as errors.
Alternatively, delete all transactions and reload everything again. It is not slower and perhaps safer to know you started from a blank slate. That way, any errors shown will be real errors and you avoid the risk of missing real errors because you are expecting some errors for duplicate transactions.
That's it for the transactions. If you want to import cash transactions read on.
"},{"location":"how-to/import-gbx/#importing-dividends","title":"Importing Dividends","text":"Quick Version
Importing cash transactions is also covered in the main guide. Importing GBP dividends for a GBX priced security is an example of a different currency dividend and the import looks like this.
<figure-caption identifier=\"Figure\"class=pp-figure}
Explanation
Some cash transactions are general to the cash account. For example, depositing and withdrawing funds to and from the Cash Account. These are not linked to a particular security so no special process is needed.
Some cash transactions are entered along with buy/sell transactions. These are transaction fees and transaction taxes (stamp duty in the UK). We do not need to concern outselves about those here (they are addressed above and in the main Import guide).
The situation is different for cash transactions which are linked to securities which are priced in GBX. Usually this is only dividends and equalisation payments. Less commonly, corporate actions may result in a release of capital or other payment. Any such payment of a cash amount whilst securities are held will use the Dividend type of transaction.
The main Import guide covers how to handle dividend imports when foreign currency is involved. That process can be followed for dividends on GBX priced securities.
In the example import file below, there are four dividends:
Figure: Figure 8 - Example dividend import data. {class=pp-figure>Importing a GBP dividend to a GBX priced security.
Date, Type, Value, Gross Amount, and Exchange Rate are mandatory. One of Ticker Symbol, Security Name, ISIN or WKN is required to identify which security is involved.
Cash Account is normally optional if all dividends will be applied to the same account (which is specified in the Import Wizard). Here however we are being specific about the Cash Account in order to allow dividends for more than one account to be imported together.
Note is optional.
A rarer type of dividend occurs when the security is priced in GBP, but dividends are received in USD. HMEF.L is an example of such a fund. There does not appear to be a way to handle this situation through import currently.
The options to handle this are:
Insolvency occurs when a company is unable to pay their bills. Investors might see a notice that Administrators or Receivers are appointed, which realistically means your securities are probably worthless.
The value can be depreciated as follows:
Edit the security and set Quote Feed Provider to No automatic quote download.
In the Information pane view Historical quotes, select the prices to be deleted then use the context menu to Delete them.
In the All Securities context menu, Quotes, Create manually, enter a Quote at least 0.00000001.
Once the proceedings are concluded:
While using the PP program, you may sometimes encounter results that you don't fully understand. PP already goes a long way to explain its calculations and results by offering intermediate results, popovers with detailed information, and possibilities to export the data in various forms to further analyze with other tools, such as Excel.
Another possibility is to inspect the source code or the XML-file. The beauty of open-source software like PP is that the source code is readily available. Inspecting the code offers a unique insight into how things are measured and calculated.
"},{"location":"how-to/inspect-source-code/#example-1-how-is-the-volatility-indicator-calculated","title":"Example 1: How is the volatility indicator calculated?","text":"The performance dashboard (View > Reports > Performance) displays several indices of performance and risk, including the volatility indicator. From other sources, such as Investopedia's How Do You Calculate Volatility in Excel?, you know that volatility is often measured by the standard deviation between returns of an investment. A typical Excel formula looks like: = STDEV.S(A1:A100) * SQRT(100), assuming that the daily returns are within the range A1:A100 in Excel.
Upon trying this on your portfolio, you get different results. So, you decide to inspect the source code.
Use the search bar at the very top of the window to search in the repository: portfolio-performance/portfolio. Enter a relevant search term, such as \"volatility,\" to find the source code where this term is mentioned. Scroll through the different modules to get the feeling. It will be rather evident why volatility appears in these modules.
Figure 1. Result of the Search 'Volatility' in the github repo of PP.
The first module (name.abuchen.portfolio/src/name/abuchen/portfolio/math/Risk.java) is most relevant. It is about \"Risk\" within a folder named \"portfolio/math\". Click within the box to see the code.
= STDEV.S(B1:B100) * SQRT(100) where the column B contains the logarithmic values of the returns such as =LN(1 + A1) will provide the exact same volatility from PP.File\n\u251c\u2500\u2500 New\n\u2502 \u251c\u2500\u2500 File\n\u2502 \u251c\u2500\u2500 Security\n\u2502 \u251c\u2500\u2500 Cryptocurrency\n\u2502 \u251c\u2500\u2500 Exchange Rate\n\u2502 \u251c\u2500\u2500 Consumer Price Index\n\u2502 \u251c\u2500\u2500 Taxonomy\n\u2502 \u2514\u2500\u2500 Watchlist\n\u251c\u2500\u2500 Open... Ctrl+O\n\u251c\u2500\u2500 Open Recent\n\u2502 \u251c\u2500\u2500 ...\n\u2502 \u251c\u2500\u2500 Clear List\n\u251c\u2500\u2500 Save Ctrl+S\n\u251c\u2500\u2500 Save as... Ctrl+S\n\u2502 \u251c\u2500\u2500 Password protected (AES-256)\n\u2502 \u251c\u2500\u2500 Binary\n\u2502 \u251c\u2500\u2500 XML\n\u251c\u2500\u2500 Save All\n\u251c\u2500\u2500 Currency >\n\u2502 \u251c\u2500\u2500 EUR (Euro)\n\u2502 \u251c\u2500\u2500 USD (United States dollar)\n\u2502 \u251c\u2500\u2500 A - D >\n\u2502 \u2502 \u251c\u2500\u2500 AED (United Arab Emirates dirham)\n\u2502 \u2502 \u251c\u2500\u2500 ...\n\u2502 \u2502 \u251c\u2500\u2500 DZD (Algerian dinar)\n\u2502 \u2514\u2500\u2500 E - I >\n\u2502 \u251c\u2500\u2500 ...\n\u251c\u2500\u2500 Tools \n\u2502 \u251c\u2500\u2500 Sanity Check...\n\u2502 \u251c\u2500\u2500 Fix: Restore ...\n\u251c\u2500\u2500 Import\n\u2502 \u251c\u2500\u2500 PDF Bank Documents\n\u2502 \u251c\u2500\u2500 CSV files (comma-separated values)\n\u2502 \u251c\u2500\u2500 Templates >\n\u2502 \u2502 \u251c\u2500\u2500 comdirect Musterdepot\n\u2502 \u2502 \u251c\u2500\u2500 ...\n\u2502 \u2502 \u251c\u2500\u2500 custom templates\n\u2502 \u251c\u2500\u2500 XML Documents (experimental)\n\u2502 \u251c\u2500\u2500 Interactive Brokers: Activity Flex Query\n\u2502 \u2514\u2500\u2500 Debug: Create text from PDF...\n\u251c\u2500\u2500 Export\n\u2502 \u251c\u2500\u2500 CSV files (comma-separated values) .. Ctrl+Shift+S\n\u2502 \u251c\u2500\u2500 Portfolio Performance XML\n\u251c\u2500\u2500 Close File\n\u2514\u2500\u2500 Quit Ctrl+Q\nView\n\u251c\u2500\u2500 Options\n\u2502 \u251c\u2500\u2500 Always start with 'All transactions' in this part\n\u2502 \u251c\u2500\u2500 Always start with last view\n\u2502 \u251c\u2500\u2500 Hide sidebar ... Ctrl+K\n\u2502 \u251c\u2500\u2500 Hide information pane ... Ctrl+L\n\u2502 \u251c\u2500\u2500 Discreet Mode\n\u251c\u2500\u2500 Securities\n\u251c\u2500\u2500 \u251c\u2500\u2500 All Securities\n\u251c\u2500\u2500 Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Deposit Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Securities Accounts\n\u251c\u2500\u2500 \u251c\u2500\u2500 Investment Plans\n\u251c\u2500\u2500 \u251c\u2500\u2500All transactions\n\u251c\u2500\u2500 Reports\n\u2502 \u251c\u2500\u2500 Statement of Assets\n| | |\u2500\u2500 Chart\n| | \u251c\u2500\u2500 Holdings\n\u2502 \u251c\u2500\u2500 Performance\n\u2502 \u251c\u2500\u2500 Calculation\n\u2502 \u251c\u2500\u2500 Chart\n\u2502 \u251c\u2500\u2500 Return / Volatility\n\u2502 \u251c\u2500\u2500 Securities\n\u2502 \u251c\u2500\u2500 Payments\n\u2502 \u2514\u2500\u2500 Trades\n\u251c\u2500\u2500 Taxonomies\n\u251c\u2500\u2500 General Data\n\u251c\u2500\u2500 \u251c\u2500\u2500 Currencies\n\u2514\u2500\u2500 \u251c\u2500\u2500Settings\nTransaction\n\u251c\u2500\u2500 Buy ...\n\u251c\u2500\u2500 Sell ...\n\u251c\u2500\u2500 Delivery (Inbound) ...\n\u251c\u2500\u2500 Delivery (Outbound) ...\n\u251c\u2500\u2500 Security transfer ...\n\u251c\u2500\u2500 Dividend ...\n\u251c\u2500\u2500 Deposit ...\n\u251c\u2500\u2500 Removal ...\n\u251c\u2500\u2500 Interest ...\n\u251c\u2500\u2500 Interest Charge ...\n\u251c\u2500\u2500 Fees ...\n\u251c\u2500\u2500 Fees Refund ...\n\u251c\u2500\u2500 Taxes ...\n\u251c\u2500\u2500 Taxes Refund ...\n\u2514\u2500\u2500 Transfer between accounts ...\nOnline\n\u251c\u2500\u2500 Update Quotes ... Ctrl+U, K\n\u251c\u2500\u2500 Update Quotes (only active securities) ... Ctrl+U, A\n\u2514\u2500\u2500 Update Quotes (selected security) ... Ctrl+U, T\nHelp\n\u251c\u2500\u2500 About Portfolio Performance\n\u251c\u2500\u2500 Preferences ...\n\u251c\u2500\u2500 Check for Updates ...\n\u251c\u2500\u2500 New & Noteworthy\n\u251c\u2500\u2500 Changelog\n\u251c\u2500\u2500 Welcome\n\u251c\u2500\u2500 Forum\n\u251c\u2500\u2500 Join translation teams\n\u251c\u2500\u2500 Source Code on Github\n\u251c\u2500\u2500 How-Tos\n\u251c\u2500\u2500 FAQ\n\u251c\u2500\u2500 Show Error Log\n\u251c\u2500\u2500 Save Error Log ...\n\u2514\u2500\u2500 Debug: Reset GUI ...\nA merger occurs when two separate companies join forces to form a new organisation, whereas an acquisition involves one company taking over another. As explained by Investopedia, the distinction between these two terms has become increasingly blurred.
On Saturday, 16 January 2021, the merger between Peugeot S.A. (PSA) and Fiat Chrysler Automobiles N.V. (FCA) was finalised, leading to the creation of Stellantis N.V. (STLA). Figure 1 shows historical price data for the companies involved, downloaded from XETRA via PortfolioReport, with the respective ISIN numbers: FCA (NL0010877643), PSA (FR0000121501), and Stellantis (NL00150001Q9).
Figure 1. Historical prices for Fiat, Peugeot, and Stellantis from 2020-07-01 to 2021-07-01.
The compensation for the old shareholders in the Stellantis merger was:
As shown in Figure 1, the closing prices of the companies on the day before the Stellantis merger were: FCA at \u20ac12.68 and PSA at \u20ac22.07. Based on the compensation ratio, the PSA price was expected to be 1.742 \u00d7 FCA Price, or \u20ac12.68 \u00d7 1.742 = \u20ac22.09, which nearly matches PSA\u2019s closing price of \u20ac22.07. Stellantis had a positive debut on European stock markets following the merger, with shares rising by 8% on the first trading day, from \u20ac12.68 to around \u20ac13.60.
Recording this merger in Portfolio Performance is straightforward, as it involves creating a new security. To update your portfolio:
In the context of stock markets, a spin-off refers to the process by which a company separates or \"spins off\" a portion of its business into a new, independent entity. This new entity becomes a distinct, standalone company with its own management, operations, and often its own publicly traded stock.
The shareholders of the original company may receive shares in the new entity in proportion to their holdings in the parent company. A distribution ratio determines how many shares of the new entity each shareholder receives for every share held in the original company.
On December 10, 2021, Daimler AG successfully executed a spin-off, resulting in the establishment of a new entity known as Daimler Truck Holding AG. Simultaneously, the former Daimler AG underwent a name change to become Mercedes-Benz Group AG. Consequently, the XETRA stock exchange market now encompasses two distinct securities: ISIN DE0007100000 for Mercedes-Benz (formerly Daimler AG) and ISIN DE000DTR0CK8 for Daimler Truck Holding AG. The distribution ratio for this spin-off was 2:1, signifying that for every two shares of Daimler AG, shareholders received one share of Daimler Truck Holding AG.
Figure 1. Quote evolution of the Daimler Truck Holding and Mercedes-Benz Group.
To record a spin-off in Portfolio Performance (PP), a suggested workflow, deduced from an in-depth discussion on the PP forum, involves the following steps:
Change the name of the security Daimler AG into Mercedes-Benz AG and create a new security Daimler Truck Holding AG in your portfolio.
Create a dividend transaction for the Mercedes security on December 10, 2021. The dividend price is set to \u20ac 14/share (see below for an explanation).
Create a buy transaction of n shares of Daimler Truck Holding AG, where n is 1/2 of the number of shares of the old Daimler AG. According to XETRA, the opening price of Daimler Truck Holding AG on December 10, 2021 was 28\u20ac/share (no fees or taxes).
Use the same deposit account for the dividend and buy transaction. This way the result of the fictitious dividend transaction will be cancelled out by the real purchase transaction. The dividend of n shares x 14\u20ac/share = purchase of n/2 shares x 28\u20ac/share.
Figure 2. Recording the spin-off of Daimler AG.
This workflow solves the spin-off problem by simulating a dividend transaction followed by an equivalent purchase for the same amount. However, a drawback is that there is no real dividend, compromising the precision of the dividend overview. Conversely, from a performance standpoint, treating the spin-off as a dividend makes sense. For example, there was a noticeable decline in the share price of the old Daimler AG, dropping from approximately \u20ac90 in mid-November 2021 to \u20ac74 on December 10, 2021, suggesting market anticipation of the impending spin-off.
"},{"location":"how-to/recording-stock-split/","title":"Recording a stock split","text":"A stock split increases the number of shares in a company. For instance, following a 2-for-1 split, each investor will possess double the number of shares, and each share will be valued at half its previous price. A stock split leads to a reduction in the market price of individual shares but does not alter the total market capitalization of the company. Stock splits are frequently executed to make shares more accessible to a broader range of investors and enhance market liquidity. Conversely, a reverse stock split (1-for-5) entails fewer stock shares but at a higher price.
There are essentially two methods for recording a stock split in PP: using the built-in function or a sell-buy-back operation. Each method has its own set of advantages and disadvantages.
"},{"location":"how-to/recording-stock-split/#use-of-the-built-in-stock-split-function","title":"Use of the built-in Stock split-function","text":"PP currently supports stock splits via work-around; see the discussion on the forum. Essentially, it retroactively assumes that the shares have always been split. This ensures the correct number of securities in the portfolio after the split and maintains historically consistent cash flows and valuations, thereby preserving the security's performance. However, the number of shares before the split may not align with the real historical situation, potentially complicating the understanding of the security's history.
This change is destructive. It is not easily undone. If necessary, an improperly executed split can be corrected by executing a split with an inverse ratio. But perhaps a better approach is to create a backup copy of the portfolio file.
In the description of the Stock Split process in the Reference Manual, the example of the Amazon 20-for-1 stock split on June 6, 2022 is used. Please review this section first.
In Figure 1, the share price evolution over the last five years is depicted. Very noticeable, there is a massive drop on between June 3 and 6, 2022. On those dates, the closing prices were $ 2447 and $ 124.79, respectively (but remember, you own 20 times more shares). Assume that you have purchased one (pricy) share on January 3, 2022 for the amount of $ 3408.
Figure 1. Historical Quotes chart of Amazon (unadjusted prices).
Quite some confusion arises when you compare this chart with those from most other financial websites; for example, the 5-year chart from investing.com looks very different.
Figure 2. Historical Quotes chart of Amazon (adjusted prices).
Both charts span an identical five-year period. But, while your purchase price was $ 3408, it appears to be priced around $ 150 around January 2022. This discrepancy arises because financial websites typically \"adjust\" all historical prices after a stock split. This adjustment involves recalculating the historical prices before the split, just as the PP's Stock Split function does.
Figure 3. Historical Quotes chart of Amazon (adjusted prices).
Important
The \"regular\" Yahoo Finance Close Price is already adjusted for splits. The Adjusted close price is en surplus adjusted for splits and dividend and/or capital gain distributions.
Some considerations
The built-in stock split function perfectly mirrors the approach adopted by most financial websites. This results in the Adjusted prices chart (Figure 3) being identical to those displayed on other platforms like investing.com or Yahoo Finance (Figure 2).
It's crucial to recognize that the historical transactions and prices are permanently altered. This means that PP's records of past transactions will no longer accurately reflect the actual transactions as documented in your paper files. Over time, this may complicate the reconstruction of a security's history.
A notable challenge arises when a split results in fractional shares, as seen in the case of Prosus' split announcement on September 14, 2023, with a ratio of 2.1796-for-1. In this scenario, 10 existing shares would be split into 21.796 shares. While PP can handle fractional shares, most brokers or banks cannot. Typically, they would adapt to this particular situation by issuing 21 new shares and providing compensation for the fractional share (0.796 shares in this case). Consequently, after the split, you'll need to record this compensation, which essentially involves executing a sell transaction of the fraction. Managing this process becomes notably more complex if you've made multiple purchases at different prices throughout the security's history.
An alternative method that keeps the historical prices and transactions intact is the following sell-buy-back procedure. At the split date (ex-date)
Let's apply this workflow to the PROSUS split (2.1796-for-1) from above. Assume that you have bought 5 shares on 2022-01-03 on XETRA for 68.60 EUR per share and another 5 on 2023-01-03 for 73.90 EUR. The closing price on XETRA on 2023-09-13 was 64.11 EUR.
Selling old shares:
Purchasing new shares:
Selling the remaining fraction:
In Figure 4 a comparison of the two methods (built-in function vs sell-buy-back) is made. As can be seen, the price range is 15 - 50 for the built-in split and 20 - 100 for the sell-buy-back method. The original buying prices are preserved in the latter case. Of course, the graph wouldn't look as nice for the Amazon 20-for-1 split.
Figure 4. Comparison of the two methods (Prosus example).
Please note that the security performance (top-right) is practically the same for built-in split vs sell-buy-back: IRR is respectively -6.05% vs -6.11%. The small difference is caused by the selling of the fraction (0.796 share) at a bad time (29.41 vs 29.54 EUR) in case of the sell-buy-back method.
The Trades Performance view gives additional info. Because we haven't solved the fractional share problem in the built-in split method, there is only one open trade: purchased 21.796 shares (2 x 10,898) and not sold yet. Remember that in your real bank account, you only have 21 shares. We haven't compensated for the fractional shares, which would be much more difficult in the built-in split method.
Let's compare with the sell-buy-back method. The open trade represents the 21 shares purchased on 2023-09-14. This trade has a positive performance (IRR = 1.03%). Prices have been increased since then. The previous period (the closed trade) however was negative (IRR= -8.40%). This puts the overall negative security performance of -6.11 in perspective. The IRR of the small closed trade of selling the 0.796 fraction is NaN (Not a Number). Because this trade is purchased and sold at the same price on the same day, the performance could not be calculated.
"},{"location":"how-to/requesting-new-importer/","title":"Troubleshooting / Request for a new PDF importer","text":"If Portfolio Performance doesn't have a PDF importer for your bank or broker, or for the specific type of transaction you need, you can request the development of this importer. Since Portfolio Performance developers don't have access to every bank or broker, you \u2014 as a user \u2014 must provide some sample PDF documents with real but anonymised examples of transactions with that specific bank or broker. The following text outlines all the necessary steps. You can also watch the accompanying video at the bottom.
Collect a PDF document of each transaction that you would like to import into your PP portfolio. Probably, you should provide an example of a buy, sell, and dividend transaction. Don't use PDFs that are converted to PDF from a browser or self-scanned paper notes but only the original documents from the bank or broker.
Convert these PDFs to text documents, one by one. Use the parser from PP, which can be found at File > Import > Debug: Extract Text from PDF (see Figure 1).
Figure 1. Menu File > Import.
You can use this sample (fictitious) PDF document for testing. The extracted text will appear in the textbox below the instructions (see Figure 2).
Replace (anonymise) personal information in the extracted text, such as your name, address, and account number. You can do this by double-clicking on a word, e.g., your name. The text will be selected and replaced with random characters.
Personal info can occur at multiple places within the document.
Leave all other information intact, especially amounts, dates, and security names. The following strings cannot be anonymised automatically: currencies (EUR, etc.), ISIN, and text groups containing the following characters: hyphen(-), period(.), comma(,), colon(:), apostrophe('), and slash(/). Do not delete or add anything manually.
Figure 2. Extracted text from testPDF.
Copy the extracted and anonymised text to the clipboard or save the file. You will need it later in the request form of the PP forum.
PDF Import from [your bank or broker]. Otherwise, post a reply in an existing thread, for example PDF import from SelfWealth. Add the extracted text for all transactions, one by one. Ensure that these text fragments are within triple quotes, so that it is formatted as code. If your transaction is in a foreign language, please provide some guidance about the translation of the used terms.Figure 1 illustrates a typical opening screen of Portfolio Performance, featuring two open portfolios: demo-portfolio-03.xml and the built-in kommer portfolio. The active portfolio is kommer, and its contents are currently displayed on the screen.
Figure 1. Typical opening screen of the Portfolio Performance program.
"},{"location":"how-to/user-interface/#components","title":"Components","text":"Figure 1 showcases the user interface elements present upon selecting the All Transactions view, which can be accessed either through the sidebar or the menu option View > All Transactions. In this example, the last Dividend transaction is selected, resulting in the display of a chart showing the historical quotes of Mercedes Benz Group in the information pane.
File, View, Transaction, Online, and Help. This top menu remains identical across all views. However, submenus can be dynamic. For instance, the Transfer between Accounts ... menu item is only available when there is more than one deposit account. An image of all menus and submenus expanded [available here] will provide you with a comprehensive understanding of the program's functionalities.The Sidebar serves as a convenient shortcut for accessing various views within the project. All available options can also be accessed through the View menu. It's important to note that the list in the sidebar mirrors the options available in the View menu, providing a one-to-one translation of the available views. The chosen view dictates the content displayed in the adjacent top and bottom panes. Next to the options Securities and Taxonomies, a very small (green) icon will let you add new elements.
To hide or show the sidebar, you can use the menu option View > Options > Hide/Show Sidebar. Alternatively, you can use the shortcut key Ctrl+K for a more efficient workflow. This allows you to quickly toggle the sidebar visibility as needed.
Dual-pane views: In PP, all views consist of dual-pane layouts, featuring a main pane and an information pane. When you select an item in the main pane, more detailed information about that item will be displayed in the information pane. If you prefer a single-pane view, you can hide the information pane (as described below), creating the illusion of a single pane view as in the Settings view.
All Transactions view. This is a list of all the transactions that you have made with your portfolio, such as deposits, withdrawals, buys, and sells. The default columns, such as date, type, security, ..., are initially visible. However, you have the flexibility to modify them using the Settings (cog) icon located in the top-right corner. Please, note that the data tools icons in the top-right corner are specific to this view and may not necessarily appear in other views.NVIDIA Corp in the main pane of Figure 1 will display the chart of this share in the information pane. You can hide/show the information pane with the menu View > Options > Hide/Show Information Pane. The shortcut key is Ctrl+L.The main pane in Figure 1 consists of a table. The first icon in the data tools lets you filter the rows in the tables, for example displaying only buy transactions. The second icon will let you export the table as displayed as a CSV-file. With the third icon (gear), you can show or hide columns in the table.
Click the column heading to sort the table in ascending (\u2227) or descending (\u2228) order based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column or double click to best fit. You can rename or hide a column with the context menu (right-click on the column header). Adding, removing or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). Clicking the Gear icon will show you all available columns.
"},{"location":"how-to/user-interface/#shortcuts","title":"Shortcuts","text":"Figure 1. Data sources Historical Quotes.
Finding accurate and up-to-date but free data sources for historical prices can be challenging. The list of data sources in PP includes the following options (see Figure 1): Alpha Vantage, EOD Historical Data, Finnhub, Leeway, Twelve Data, Portfolio Report, Quandl, and Yahoo Finance. The remaining alternatives are tailored for bitcoins and other statistical data.
Unfortunately, the terms of use for many of these options have become increasingly restrictive over time. They are included here mainly for compatibility reasons. In practical terms, only Portfolio Report and Yahoo Finance or JSON could be recommended for a typical portfolio.
Some specific use cases are discussed below. Many more are described in the Forum (in German).
"},{"location":"how-to/downloading-historical-prices/#very-old-historical-prices","title":"Very old historical prices","text":"Most financial services typically provide historical prices for a limited time period, such as the last year or since a specific recent date. However, if you happen to be one of the fortunate individuals who purchased Apple stock back in the 1980s, tracking your performance from the very beginning should be nice.
Note
Apple went first public on December 12, 1980, opening at $22 a share. The company was listed on the NASDAQ stock exchange under the ticker symbol AAPL. The share has since split five times, most recently in 2020, so on a split-adjusted basis the IPO share price was $.10.
Choosing Yahoo Finance as the Quote Feed provider will not get you very far: only 3 months of historical quotes are downloaded, starting from today.
Choosing the JSON Quote Provider allows you to specify the desired period for prices. For instance, the following URL attempts to download 30 years of data:
https://query1.finance.yahoo.com/v8/finance/chart/NVDA?interval=1d&range=30y
It's not possible to obtain 30 years, but you do receive data until 1991, or about 25 years of historical prices.
Normally, company websites contain that kind of information. Surprisingly, The Apple website doesn't offer the option to download historical data; you only can look up some prices. On the other hand, you can access dividend and split information. NASDAQ allows you to download a CSV file that extends only 10 years into the past.
Naturally, being a high-profile stock, more extensive data can be found on the web. For instance, Kaggle provides a CSV file of Apple Stock Prices from 1980-2021. You could download this file, import it into the historical prices, and have Yahoo Finance append the missing data.
Suppose that you want to track the Sustainable Health Care Fund (ISIN: lu0114720955) of the European based Fidelity Funds. Yahoo Finance has only the most recent price.
Investing.com does a bit of a better job and provides historical data from the launch of the fund (2000-09-01). You can download these data as CSV file; see section on Downloading historical prices > CSV File.
Of course the most extensive website for mutual funds is Morningstar You need to visit a European website for example https://www.morningstar.co.uk/uk/funds/snapshot/snapshot.aspx?id=F0GBR04EBS&tab=13
"},{"location":"how-to/downloading-historical-prices/#etf-tracker","title":"ETF tracker","text":""},{"location":"how-to/downloading-historical-prices/#bonds","title":"Bonds","text":""},{"location":"how-to/downloading-historical-prices/#gold","title":"Gold","text":""},{"location":"how-to/downloading-historical-prices/alpha-vantage/","title":"Alpha Vantage","text":"Alpha Vantage provides realtime and historical financial prices through data APIs and spreadsheets. You can request a free API key with lifetime access covering the majority of the datasets for up to 25 requests per day. Realtime quotes and some other resources however are premium.
The API documentation is very well written with many examples. These examples can be executed in the browser with a provided demo API-key. If you want to execute your own queries, you need the free API key.
Download the NVIDIA historical prices.
https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=NVDA&apikey=my_API_key
This will return some metadata and the last 100 historical quotes in the browser window. If you want all available historical prices, use the option \"outputsize=full\".
{\n \"Meta Data\": {\n \"1. Information\": \"Daily Prices (open, high, low, close) and Volumes\",\n \"2. Symbol\": \"NVDA\",\n \"3. Last Refreshed\": \"2024-01-25\",\n \"4. Output Size\": \"Compact\",\n \"5. Time Zone\": \"US/Eastern\"\n },\n \"Time Series (Daily)\": {\n \"2024-01-25\": {\n \"1. open\": \"623.5000\",\n \"2. high\": \"627.1900\",\n \"3. low\": \"608.5000\",\n \"4. close\": \"616.1700\",\n \"5. volume\": \"48277684\"\n },\n \"2024-01-24\": {\n \"1. open\": \"603.0400\",\n \"2. high\": \"628.4900\",\n \"3. low\": \"599.3800\",\n \"4. close\": \"613.6200\",\n \"5. volume\": \"55706870\"\n }\n }\n}\nNote
As of January 2024, Alpha Vantage changed some parameters and PP's JSON Quote Feed is no longer functional for this URL. The Path to Date and Path to Close JSON paths below result in an error; even if they are, according to the JSONPath Online Evaluatora valid JSON path.
$.[Time Series (Daily)].*~$.[Time Series (Daily)].[*].[4. close]In PP, importing historical prices from a CSV file is a straightforward process through the menu File > Import > CSV Files. Naturally, you would require a file containing the relevant quotes for this operation.
A csv file is a comma-separated values file, which is a text file that stores tabular data. Each row in the file represents a record, and each column represents a field. For example, a typical historical quotes CSV file will contain two columns (date and quote) and several rows, one for each date with its corresponding historical quote. A csv file can be opened and edited by spreadsheet software and easily imported into PP.
Each website may have a distinct approach for downloading a CSV file of the historical data. Typically, you need to navigate to the desired security and locate the download link on that webpage. Many websites require (free) registration for downloading, Yahoo Finance being an exception.
It's important to note that this method provides a snapshot of historical prices. To obtain the quotes of tomorrow, you should repeat the process. In practice, you need to combine this approach with one of the automatic quote download methods. Remember that you can keep the existing historical quotes in PP, even if you change the quote provider to automatic download. For example, in both scenarios below, after importing the CSV file, you can set the Quote Feed Provider to the Table on Website method for daily updates of historical prices.
"},{"location":"how-to/downloading-historical-prices/csv-file/#yahoo-finance","title":"Yahoo Finance","text":"After navigating to Yahoo Finance, you can enter the name \"NVIDIA\" in the Search box at the top of the screen (see Figure 1). Select the Historical Prices tab in the middle of the screen. From there, you can specify the Time Period and frequency before downloading a CSV file containing historical prices. Import this CSV file into Portfolio Performance using the menu File > Import > CSV Files, choosing the Historical Prices option and assign it to the correct security.
Figure 1. Webpage from finance.yahoo.com to download the historical prices of NVIDIA.
Hovering over the download link, you may have noticed the URL endpoint: https://query1.finance.yahoo.com/v7/finance/download/NVDA?period1=1674359406&period2=1705895406&interval=1d&events=history&includeAdjustedClose=true (see Figure 1 at the bottom of the image).
This is the request you send to the Yahoo server. It contains the ticker symbol of the security (NVDA), the time period expressed as Unix timestamps or the number of seconds that have elapsed since January 1, 1970, the frequency or interval (1d), the type of info you want (events=history), and the Adjusted Close price. The CSV file contains 7 columns: Date, Open, High, Low, Close, Volume, and Adj Close.
You can change this URL to obtain different results. For example, the following URL will retrieve the last three months of prices (same columns):
https://query1.finance.yahoo.com/v7/finance/download/NVDA?range=3mo&interval=1d
Investing.com is a comprehensive financial website providing real-time quotes, financial news, analysis, and tools for investors. You can localize its content for more than 30 countries including several European languages.
Clicking the Search box will display your recent searches and popular ones. You can enter the name, ticker, or ISIN of the security you're interested in. A graphical overview of the quote history (1 month) is presented. Click Historical Data to see the table. For downloading or changing the period, registration with your email address is required (free). All data are available, but there is a limit of 20 years that you can download in one pass.
The EODHD (End of Day Historical Data) website provides comprehensive coverage of all U.S. stocks, ETFs, and mutual funds from their inception. Additionally, the platform encompasses historical data for non-U.S. stock exchanges, primarily dating back to January 3, 2000.
A free API-token can be easily obtained by providing your email address. The token comes with a usage limit of 20 API requests per day. However, only historical quotes from the last year could be retrieved.
You can use the API-token with the automatic Quote Feed of PP from within PP works just fine. Enter the token in the Settings (Help > Preferences > API Keys) and choose EOD Historical Data as Quote Feed Provider.
If you have some special requirements, you can also use the JSON Quote Feed Provider (see API documentation for some use cases). For example, the following request will retrieve the Apple historical prices from the month January 2000.
Feed URL
https://eodhd.com/api/eod/AAPL?from=2000-01-01&to=2000-01-31&period=d&api_token=demo&fmt=json
Path to Date = $[*].date and Path to Close = $[*].close
Entering the URL in a browser will display the following (abbreviated) JSON.
[\n {\n \"date\": \"2000-12-01\",\n \"open\": 17.0016,\n \"high\": 17.5,\n \"low\": 16.8112,\n \"close\": 17.0632,\n \"adjusted_close\": 0.2583,\n \"volume\": 385705600\n },\n {\n \"date\": \"2000-12-04\",\n \"open\": 17.1864,\n \"high\": 17.1864,\n \"low\": 16.436,\n \"close\": 16.688,\n \"adjusted_close\": 0.2526,\n \"volume\": 371520800\n },\n {\n \"date\": \"2000-12-05\",\n \"open\": 16.94,\n \"high\": 17.4384,\n \"low\": 16.3744,\n \"close\": 17.0016,\n \"adjusted_close\": 0.2574,\n \"volume\": 613978400\n }\n]\nThis is an array of objects; accessed from the root with $[*]. The JSON path to the date is formed by $[*].date and to the closing price with $[*].close.
Financial web services commonly expose their data, e.g. historical prices, through an Application Programming Interface (API). To access these historical prices through the API, users can send HTTP requests to specific API endpoints, specifying parameters such as date ranges, stock symbols, and any other relevant filters. The API endpoint (=server) processes these requests, retrieves the requested historical price data from its database, and returns the information in a structured format, often JSON or XML.
For example, the following endpoint URL can be used to request the historical quotes of Apple between 2024-01-15 and 2024-01-17 from the eod historical data website.
https://eodhd.com/api/eod/AAPL?from=2024-01-15&to=2024-01-17&period=d&api_token=demo&fmt=json
As of January, 2024, the demo API token or key provided is still valid. If it ceases to function in the future, kindly apply for a free API key.
[\n {\n \"date\": \"2024-01-16\",\n \"open\": 182.16,\n \"high\": 184.26,\n \"low\": 180.93,\n \"close\": 183.63,\n \"adjusted_close\": 183.63,\n \"volume\": 65603000\n },\n {\n \"date\": \"2024-01-17\",\n \"open\": 181.27,\n \"high\": 182.93,\n \"low\": 180.3,\n \"close\": 182.68,\n \"adjusted_close\": 182.68,\n \"volume\": 47317400\n }\n]\nA JSON response can contain two kinds of elements: lists and objects. A list is an ordered collection of elements between [ ]. These can be accessed by their position. An object is an unordered collection of key-value pairs between { }. A key is a unique identifier for a value, and a value can be any type of data, such as a number, a string, a boolean, a list, or an object. A JSON response is a hierarchical structure, meaning that a list can contain other lists or objects, and an object can contain other lists or objects.
To access a specific value within this hierarchical structure, you need to specify the path from the root to the element. To access an element from a list, you need to use its index, which is a number that indicates its position in the list. The index starts from 0 for the first element. To access an element from an object, you need to use its key, which is a string that indicates its name in the object. The key is enclosed in double quotes \" \".
A query language such as JSONPath (used by PP) represents the root of the JSON response with a $ symbol. To separate the elements in the path, you need to use a dot. For example, to access the close price on the second day, you need to use the path $[1].close. This means that you start from the root $, then go to the second element in the list $[1], which is an object, then go to the value with the key \"close\" in the object $[1].close, which is a number.
You need this JSON path to complete PP's JSON Quote Feed Provider. Use the following parameters to retrieve the historical quotes (see also Figure 1). For an explanation of the meaning of different quote prices, please check Concepts > Historical Prices.
Figure 1. Server response from JSON Quote Feed Provider (EODHD).
https://eodhd.com/api/eod/AAPL?from=2024-01-15&to=2024-01-17&period=d&api_token=demo&fmt=json$[*].date$[*].close$[*].low$[*].high$[*].volumeLet's try a more complicated example. The following endpoint URL enables the retrieval of NVIDIA's two most recent daily quotes from Yahoo Finance (click the following link to see the result).
https://query1.finance.yahoo.com/v8/finance/chart/NVDA?interval=1d&range=5d
The response from the Yahoo server is a lengthy JSON document with all the historical quotes of the last 2 days. The output has been restructured and abbreviated for clarity (scroll down to see the quotes).
{\n \"chart\": {\n \"result\": [\n {\n \"meta\": {\n \"currency\": \"USD\", \n \"symbol\": \"NVDA\"\n },\n \"timestamp\": [1705415400, 1705501800],\n \"indicators\": {\n \"quote\": [\n {\n \"close\": [563.82, 560.53],\n \"open\": [550.17, 563.46],\n \"high\": [568.34, 564.71],\n \"low\": [549, 547.40],\n \"volume\": [44958000, 47439400]\n }\n ],\n \"adjclose\": [\n {\n \"adjclose\": [563.82, 560.53]\n }\n ]\n }\n }\n ],\n \"error\": null\n }\n}\nThe JSON response from above is an object, surrounded by { }. It contains meta data of the security, Unix timestamps from the two retrieved dates, and the different quote prices. You need a JSON path to retrieve the different values:
$.chart.error$.chart.result[0].meta. The result field is an array, even though there is only one element, probably because one can also ask data for multiple securities.$.chart.result[0].meta.symbol$.chart.result[0].timestamp[*]. The * serves as wildcard, facilitating the retrieval of all values.$.chart.result[0].timestamp[1]$.chart.result[0].indicators$.chart.result[0].indicators.quote[0]$.chart.result[0].indicators.quote[0].close$.chart.result[0].indicators.quote[0].close[0]If you want to practice, you can use the JSONPath Online Evaluator. Copy the JSON result from the URL endpoint into the input window. Another practical tool is the JSONPath Finder.
With the above information, it should be easy to provide the JSON Quote Feed provider of PP with the correct input.
Figure 2. JSON Quote Feed provider parameters.
For most services, one needs to register and obtain an API key, which is a unique identifier that authenticates the user and grants access to the service. While numerous financial services provide seemingly free API keys, their terms of use and long-term commitment often prove inadequate. PP has, for compatibility reasons, maintained several of these services in its list of Quote Feed providers; e.g. Alpha Vantage, eodhd, .... Although once considered excellent solutions, they have changed their offerings and are no longer as useful as free services. In practical terms, only Portfolio Report and Yahoo Finance can be recommended for a typical portfolio.
"},{"location":"how-to/downloading-historical-prices/morningstar/","title":"Import fund data from Morningstar","text":"Info
Best answer in forum from SimonFitz!
The website of Morningstar is quite famous for its extensive list of funds. With some magic, you can download historical data for specific funds from this website.
First go to the Chart page for the fund (or trust or EFT) on the Morningstar website; e.g. https://www.morningstar.co.uk/uk/. I will use the Baillie Gifford Positive Change Fund B Accumulation fund (ISIN GB00BYVGKV59) as an example.
Remove any other benchmarks etc. the are charted (this is not necessary, but makes things easier). Open your browser's \"developer tools\" which is F12 in Firefox & Edge and probably other browsers as well. Go to the \"Network\" tab and press the clear button which looks like a bin; again, not necessary but makes things easier. Now press the \"chart settings\" button just above the chart, click \"display options\", and then click the \"percentage\" button - this switches the chart to show the actual fund price, rather than a percentage change, and handily for our purposes causes the Morningstar website to request a link that we can use in Portfolio Performance with a bit of modification. That link should display in the \"network\" screen of the browser's developer tools, so now right-click on the entry that comes from the \"tools.morningstar.co.uk 44\" domain and is of type \"json\" and select the Copy->Copy URL option. The link should be
https://tools.morningstar.co.uk/api/rest.svc/timeseries_price/\nt92wz0sj7c?currencyId=GBP&idtype=Morningstar&frequency=daily&\nstartDate=2011-02-01&priceType=&outputType=COMPACTJSON&\nid=F00000ZB0M]2]0]FOGBR$$ALL&applyTrackRecordExtension=true\nhttps://tools.morningstar.co.uk/api/rest.svc/timeseries_price/\nt92wz0sj7c?currencyId=GBP&idtype=Morningstar&frequency=daily&\noutputType=JSON&startDate=2020-12-31&id=F00000ZB0M]2]0]\nFOGBR$$ALL\nYou can go to this link in your browser if you want to see the data. There are 4 options worth highlighting: frequency which will give you daily prices, outputType gives you a style of JSON that Portfolio Performance can parse, startDate lets you choose how far back to go, and id is the Morningstar reference for the security - so change that value for any other ones you want to use. The order of the options doesn't matter, but I find it easier to put the id at the end for when I'm setting up multiple securities.
Now in Portfolio Performance select JSON as the provider in the \"Historical Quotes\" tab of the security, and use the following values (see also figure 1):
Feed URL = the link just created\nPath to Date = $.TimeSeries.Security[*].HistoryDetail[*].EndDate\nPath to Close = $.TimeSeries.Security[*].HistoryDetail[*].Value\nFigure 1. Example of JSON provider for historical quotes
Always worth double-checking the displayed values against the Morningstar chart.
"},{"location":"how-to/downloading-historical-prices/portfolioreport/","title":"Using Portfolio Report","text":"Portfolio Report (PR) is an open-source project that works closely together with the Portfolio Performance (PP) app. Its primary goal is to enhance PP by providing master data for securities, including name, ISIN, WKN, and ticker symbol, as well as historical prices in various currencies.
PR allows you to look up information about securities, such as symbols, industries, and historical prices. Furthermore, it enables the creation of securities within PP from PR and the provision of historical prices for securities that already exist in PP.
"},{"location":"how-to/downloading-historical-prices/portfolioreport/#looking-up-information","title":"Looking up information","text":"When you navigate to the Portfolio Report website https://www.portfolio-report.net/, you will be presented with the following simple but efficient search form (see Figure 1).
Figure 1. Portfolio Report website.
In the first box of the search form, you can enter the ISIN, WKN, Symbol, or the full name of the security. Please refer to Basic concepts > PP-terminology for a definition of each term. Note that the use of wildcards, such as 'Amaz*', is not permitted for name searches. On the other hand, one word in the name suffices. For example, searching for Group will produce Cimic Group, NN Group, IBI Group, ... Searching for col will show Colruyt and Coca Cola Co.
Specifying the security type (share, fund, crypto, or bond) is not necessary, as the default search setting (blank or *) includes all categories.
When you retrieve the historical prices of a security, you have the option to select the currency in which the quotes are displayed with the Prices dropdown. Please note that the prices are always retrieved from the XETRA (Frankfurt) exchange market and that this price (in EUR) is converted through the exchange rates of the ECB.
Figure 2. Search Result
"},{"location":"how-to/downloading-historical-prices/portfolioreport/#creating-new-securities-in-pp-with-pr","title":"Creating new securities in PP with PR","text":"Utilize the Search box located at the top right (refer to Figure 3) to search for the desired security using its name, ISIN, or WKN.
If the security is in PR's database, the name (e.g Amazon.com Inc.), ISIN (US0231351067), and eventually WKN are displayed, together with a logo of the security (white arrow on blue background) and some extra information such as the trading market (XETRA), the currency (EUR), the ticker symbol on the specified trading market (AMZ), the country (United States of America (US)) and eventually the industry sector of the company. On multiple tabs (1, 2, 3, etc.), you can view the historical prices of the security. By default, only the 10 most recent prices are shown. However, using the drop-down menu on the right, you can adjust the number of prices displayed per page, with options ranging from 10, 30, 100, to 300.
Only securities that are traded on XETRA (Deutsche B\u00f6rse) are available within PR. Historical prices, specifically closing prices after the end of trading, are provided. Current prices, which are prices during trading on a marketplace, are not available.
Drag (= click, hold, and drop) the big blue button Add to Portfolio Performance upon the open window of PP. This is -of course- very easy if the two applications are placed next to each other on the screen (see Figure 2). Otherwise, you need to drag the button upon the PP icon in the taskbar.
Figure 3. Using Portfolio Report to create a security in Portfolio Performance.
You can verify the successful addition of the newly created security by checking the master data tab. A message stating Linked to Portfolio Report should be visible (see Figure 4). Additionally, on the Historical Quotes tab, the Quote Feed should be populated with the correct information.
It's important to note that due to the association with PR, the fields ISIN, and WKN become unmodifiable. If there is a need to update these fields, you must use the \"Unlink\" button to detach the security. Unfortunately, this also removes the Quote Feed of the Historical Quotes.
Figure 4. Master data and historical prices of newly created security.
It's also possible to link an existing security to PR; in particular to gain access to its quote feed of historical prices.
https://www.portfolio-report.net/securities/, followed by an identifier such as 8761e2dd-873a-4f1c-99c5-65939819eed9. This is the internal code that PR assigns to this security. You can find this URL in the address bar or at the bottom of the screen when hovering over the big blue button Add to Portfolio Performance.All Securities list; right-click and choose Link to Portfolio Report. Additionally, you must manually set Portfolio Report as the Quote Feed.Whenever PP initiates an update, such as through the menu Online > Update Quotes a request is sent to the PR website. Portfolio Report only receives information that is technically necessary, including:
This information is temporarily stored in log files on the server. The IP address is stored anonymously. In addition, no storage or evaluation of the data takes place.
The above info is based on a German article by developer Thomas. The source code could be retrieved at Github.
"},{"location":"how-to/downloading-historical-prices/table-website/","title":"Table on Website","text":"Stock exchanges like NASDAQ publish historical and real-time quotations for the shares traded on their platforms. Financial websites such as ariva.de offer a broader range. These historical prices are typically contained in a table with headings such as Date, Open, Close, ...
Scraping this information from the website should be possible. PP offers two methods: automatic and manual scraping.
"},{"location":"how-to/downloading-historical-prices/table-website/#automatic-scraping","title":"Automatic scraping","text":"ARIVA.DE is a German website that provides financial information and news, such as stock prices, market indices, commodities, currencies, funds, certificates, bonds, and more.
Figure 1. Historical prices on ARIVA.DE (English translation)
The URL for the webpage of Figure 1 is: https://www.ariva.de/nvidia-aktie/kurse/historische-kurse. Inputting this URL in the Feed URL field of Figure 2 will result in the quotes of the current month being downloaded. Using this method to append the historical quotes will only be effective when you regularly update the quotes by opening the portfolio or using the Online menu. Please note that you could select a different month, which could be a solution if you skipped one or several months.
Figure 2. Historical prices on ARIVA.DE (English translation)
For some reason, the Volume info isn't retrieved, and neither are the High & Low quote from the Bourserama URL: https://www.boursorama.com/cours/historique/NVDA. Please be aware that this link will provide monthly quotes, even though daily quotes are displayed on the screen.
The above mentioned method doesn't always work. Some websites use JavaScript or other technologies to build the tables on the clients machine. For example, at the Finanzen.net website, the default URL https://www.finanzen.net/historische-kurse/nvidia will only display the current day's quote, requiring input of the start and end date to view other periods. In such cases, manual scraping could be employed to capture this data.
Figure 3. Manual scraping.
Page Source from the context menu.Yahoo Finance provides a wide array of tools and financial resources, including historical and real-time stock quotes, interactive charts, and news updates that cover a diverse range of financial markets.
Figure 1. Yahoo Finance website with historical prices of Deutsche Telekom.
Click on the search box at the top and enter a (partial) name; for instance \"Deu\". Select the correct security, which in this case is Deutsche Telekom (DTE.DE). Navigate to the second menu and click on Historical Prices (see Figure 1). Subsequently, you can adjust the Time Period and Frequency as needed.
Note
The Yahoo (ticker) symbol is visible in parentheses after the security name, as illustrated in Figure 1. The ticker symbol is a series of letters representing a publicly traded company or financial instrument. For example, the ticker symbol for Apple Inc. is AAPL. When there could be confusion as with DTE (there are two companies DTE), the market place is added: DTE.DE to refer to Deutsche Telekom; a security traded on the Deutsche B\u00f6rse or DTE (default): DTE Energy Company, that it is traded on the NASDAQ.
You can download these historical prices as a CSV file by clicking the Download button. Please take note of the URL located at the bottom of Figure 1, as it grants access to this functionality. In the chapter on CSV file, we delve deeper into this topic.
Figure 2. Data sources Historical Quotes.
PP has a predefined Quote Feed provider for Yahoo Finance and Yahoo Finance (Adjusted Close). Please note that the Day's High, Day's Low, and Volume info is not retrieved in both cases.
To retrieve the historical quotes of Deutsche Telekom, enter the ticker symbol in the Security Master Data (see Figure 1, top left) and select Yahoo Finance as the Quote Feed Provider within the Historical Quotes tab. A list of 30 quotes, starting from today will appear.
In the background, PP initiates the following query (becomes visible in the event of an error, for example with ticker symbol DTE.XX).
https://query1.finance.yahoo.com/v8/finance/chart/DTE.DE?range=3mo&interval=1d
If you need a different amount of historical data, data from an alternative period, or you want to include the High, Low, and Volume fields, you can initiate the query manually. This functionality is available through the JSON Quote Feed Provider.
"},{"location":"reference/","title":"Reference Manual","text":"The Reference manual is structured around the User Interface (UI) of the program, probably the easiest and quickest way for users, developers, or contributors to find relevant information. Figure 1 illustrates a typical opening screen of Portfolio Performance, featuring two open portfolios: demo-portfolio-03.xml and the built-in kommer portfolio.
The structure of the Reference part of the manual is mirrored from the menu with top-level sections named File, View, Transaction, ... As can be seen in the sidebar of this page or from the hamburger menu if you are reading this from a small/mobile screen, the File section is subdivided into pages such as New, Save, Import, ...
Figure 1. Typical opening screen of the Portfolio Performance program.
An image of all menus and submenus expanded is [available here].
"},{"location":"reference/online/","title":"Menu Online","text":"To assess the performance of your portfolio, it's essential to have historical prices or quotes for all securities. You can input these manually or, more conveniently, obtain them through a Quote Feed. This could be in the form of a table on a website or another online data source. With the menu Online these historical prices could be updated.
For all securities that are connected to an online quote feed provider, this command will trigger a request to the online service for the latest quotes ranging from the first historical quote to the present day.
Quotes that were previously downloaded but subsequently deleted will be reinstated. However, quotes that have been manually altered after online download or those in the historical prices table that are not available online (e.g., quotes in the distant past) will remain unchanged during this operation.
A message xxx operations remaining will appear briefly in the left bottom corner of the window, indicating the progress of the updating process. This process is conducted in the background and does not affect other operations.
Securities could be set to active or inactive in the Security Master Data tab of the Securities Attributes panel.
Figure 1. Inactive setting in the Security Master Data tab.
This command will update only the active securities.
"},{"location":"reference/online/#update-quotes-selected-security","title":"Update quotes (selected security)","text":"In a table view such as All Securities, one can select one or more securities. For a consecutive selection, click the first row, press Shift, and click the last row. For a non-consecutive selection, use the Ctrl key.
Even though the menu mentions \"selected security\", the update will be performed on all selected securities.
"},{"location":"reference/file/currency/","title":"File \u203a Currency","text":"Figure 1. Currency Picker.
The base currency of the portfolio is established at the time of creation. In reports such as the Statement of Assets, some monetary values are preceded by a currency abbreviation (e.g., USD), while others are not. By default, only monetary values that are not expressed in the base currency are prefixed with the currency abbreviation.
Note
To display the currency code for all monetary values, navigate to the menu Help > Preferences > Presentation and enable the Always display currency code for monetary values option. The change will take effect upon the next startup of PP, and all values will be prefixed with the currency code.
To add or change a base currency, use the menu File > Currency. In Figure 1, the original base currency at the time of portfolio creation was EUR. An alternative base currency, USD, has already been added but is not yet set as the base currency (indicated by the unchecked box). To add AUD as another base currency option:
Once added, you can set AUD as the base currency by checking the box next to it. This will change the base currency for the portfolio and may affect how monetary values are displayed in reports and other parts of the application.
In Figure 2, share-1 and bond-1 are European stocks traded in EUR, while share-2 is an American stock expressed in USD. The Statement of Assets report is generated twice: once with the base currency set to EUR (left panel) and once with the base currency set to USD (right panel). Please note that the quote price remains the same in both panels. However, the market value differs due to the different base currencies.
For example, the total market value in the left panel is 20,833.05 EUR, while in the right panel, it is 22,591.35 USD. According to the Currency Converter, the exchange rate on 2024-03-20 is 1.0844 EUR/USD. Using this exchange rate, you can confirm the conversion: 20,833.05 EUR x 1.0844 = 22,591.35 USD.
Figure 2. The Statement of Assets in two base currencies.
"},{"location":"reference/file/export/","title":"File > Export","text":"The menu File > Export has only two options: CSV files (comma-separated values) and Portfolio Performance XML.
Selecting the \"CSV Files\" option will reveal an additional panel for specifying the type of information to be exported. The exported CSV file utilizes the UTF-8 encoding, a universal and widely used method for converting text to bytes. This encoding can represent any character in the Unicode standard, encompassing over 140,000 characters from various languages and scripts. The importance of the encoding becomes apparent when importing the CSV file. Most programs, such as Excel, can accurately recognize the encoding. However, for PP's Import function, it's crucial to choose the correct encoding.
Figure 1. Export CSV file dialog from demo-portfolio-04.xml.
As you can see, there are two deposit accounts (EUR and USD) and one security account (Broker-A) in Figure 1. The USD deposit account is used for share-3, which is expressed in USD.
If you have securities in a different currency than the portfolio base currency such as in Figure 1, you can convert the historical quotes to the base currency by checking Convert all quotes of securities to portfolio base currency. Please note that this option does not convert the purchase prices, fees, ... that might be expressed in another currency.
For each Deposit account, you can export all transactions (buy, sell, deposit, ...). For each transaction the following fields are exported: Date, Type, Value, Transaction Currency, Taxes, Shares, ISIN, WKN, Ticker Symbol, Security Name, and Note.
It's not possible to select multiple accounts.
"},{"location":"reference/file/export/#securities-account-transactions","title":"Securities Account Transactions","text":"Only the Buy and Sell transactions are exported from the securities account; not dividends. The following fields are exported: Date, Type, Value, Transaction Currency, Gross Amount Currency, Gross Amount, Exchange Rate, Fees, Taxes, Shares, ISIN, WKN, Ticker Symbol, Security Name, and Note. Unfortunately, the date contains the time of day of the transaction (e.g. 2021-01-15T00:00), which makes it a text field in Excel. You can create a custom date format in Excel to handle this kind of dates.
Master Data: For each security in the portfolio, the following fields are exported: ISIN, WKN, Ticker Symbol, Security Name, Currency, and Note.
All historical quotes are organized with a dedicated column for each security, using the ticker symbol as the column heading. Each date containing a historical quote corresponds to a row with the respective price added in the relevant column. In cases where a security has no recorded price for a particular date, the corresponding cell is left empty.
All transactions and dividends: with this option, you can export all buy, sell, and dividend transactions. The exported fields are (in German): Datum, ISIN, Name, Typ, Transaktion, Preis, Anzahl, Kommission, and Steuern. The date format does not contain time of day info.
VINIS-App: The VINIS app is a mobile application for iPhone and Apple Watch that helps users set, track, and achieve their financial goals. The app allows users to create custom goals and key figures, and to link them to external data sources such as Google Sheets, Excel, or Numbers documents. The app also provides visualization, prediction, and reminder features to help users monitor their progress. The following fields are exported: Funds sum, Securities purchase price, Securities market price, Total assets purchase price, Total assets market price, Earnings current year, Earnings last year, Earnings total, Capital gains current year, Capital gains last year, Capital gains total, Realized capital gains current year, Realized capital gains last year, Realized capital gains total.
Similar to the previous description of \"All historical quotes,\" the export includes all available prices for the selected security. The exported data comprises two fields: Date (without the time of day) and Quote.
This command is identical to the File > Save command or the File > Save as menu command with option XML.
With the File > New menu you can create the different assets PP can manage.
Figure 1. File > New submenu.
"},{"location":"reference/file/new/#portfolio-file","title":"Portfolio (File)","text":"The option File > New > File initiates a wizard for creating a new portfolio. Within the wizard, you need to set the base currency of the portfolio, create a security and deposit account (mandatory), add additional deposit accounts, and include securities and taxonomies (optional). A detailed explanation of the wizard can be found in Getting Started > Creating a Portfolio File.
The menu option File > New > Security is self-explaining: it allows you to create a new security. This can also be done at other locations within the UI; for example as part of the portfolio creation wizard (see above), or with the little green icon next to Securities in the sidebar or in the All Securitiesview.
Figure 2. File > New > Security menu.
You can either choose to create a new empty instrument (e.g. security) or to search for an existing one. You can type (part of) the security name in the search box. Choosing from the drop-down box All, you can search for shares or bonds or both. After clicking the Search button, the list below will be populated with possible target instruments. The following fields are displayed for each instrument and will be used upon selecting the security: Name, Symbol, ISIN, WKN, Type, Exchange, Currency, and Source (see Basic concepts > PP-terminology for a definition of each term).
Once the correct security has been selected, proceed to the next step by clicking on the Apply button. Some information such as name, symbol and historical quotes will already be filled in, based on the selected data source. You should always check the info, especially the stock market. All the info can be changed; even the name. Alternatively, one may initiate the process with an empty security (see Figure 3) and manually input the required information.
Figure 3. Input panel for the creation of a security.
While only the name is obligatory, there are several other fields that need attention. They are grouped into 5 sub panels, marked with a yellow line in Figure 3.
This panel is entirely visible in Figure 3. The currency field must correspond to the currency in which the security is traded. Once transactions are recorded with this security, the currency cannot be changed. Clicking the currency box will reveal a drop-down with all available currencies.
The fields ISIN, Symbol, and WKN have been explained earlier. The symbol field is particularly crucial as it is utilized in the Quote Feed for Historical Quotes (further details below).
The Calendar dropdown enables you to choose a specific stock market calendar, such as Euronext, London Stock Exchange, New York Stock Exchange, etc. These calendars contain information about trading days, (bank) holidays, affecting some calculations, the display of price gaps, and the execution of savings plans. A more detailed description is available in the Help > Preferences > Calendar menu.
A security can be set to active or inactive. If set to inactive, the security will not appear in buy or sell dialogs, and historical prices will not be updated automatically.
At the bottom of Figure 3, you can add a personal note for this security.
Besides the attributes from the Security Master Data, you can use other attributes; for example a logo. These additional attributes can be added to tables such as Reports > Performance > Securities. The values of these attributes must be entered manually and cannot be used in calculations.
Additional attributes are defined in (left) Sidebar > General Data > Settings > Attributes : Securities (at the bottom). More info here.
A taxonomy serves as a classification system for your securities. Taxonomies typically group securities based on shared characteristics such as industry, sector, geographical region, market capitalization, or asset class. For instance, the existing Asset Classes taxonomy allows you to classify your securities into categories such as Cash, Equity, Debt, Real Estate, or Commodity.
When you first open the Taxonomies panel (shown in Figure 4) in a new portfolio, it will be empty. To start using taxonomies, you'll need to create one or more for your portfolio. In Figure 4, four taxonomies are visible: Asset Classes, Asset Allocation, Industries (GICS, Sectors), and Regions. These taxonomies also appear under the View menu.
Figure 4. Taxonomies panel.
To assign a security to a taxonomy category, click the New Category button below the taxonomy. A drop-down menu will appear, listing all possible categories along with a weight input box. You can assign a security to multiple taxonomies. It's also possible to assign multiple categories of one taxonomy, as long as the combined weight doesn't exceed 100%. If the weight is not displayed next to the category (see Figure 4), then it is set to 100%. Click the minus button (-) next to the category to remove it from the taxonomy assignment. The above actions can also be done (more easily) in the Taxonomies View.
For detailed instructions on how to create, manage, and use taxonomies, see section Reference > View > Taxonomies in the manual.
"},{"location":"reference/file/new/#historical-quotes","title":"Historical Quotes","text":"For evaluating your portfolio, you need the current & historical prices of the security. In this panel (see Figure 4) you can set the data source of the Quote Feed. As Provider, you can choose between several alternatives: Yahoo Finance, Alpha Vantage, Quandl, ... (see Figure 5). You can even refer to a webpage (e.g. from an investor site) that contains these historical data; an example is given in Import fund data from Morningstar. Or you can create them yourself and import the quotes from a csv-file.
Figure 5. Historical quotes panel.
Depending upon the chosen provider, you may need to input additional information. If the provider is a website, you need to specify a URL. If the provider covers more than one Exchange, you need to select the correct one.
Figure 6. Historical quotes panel.
Downloading historical prices for large-cap (big companies) stocks is relatively straightforward. However, obtaining data for less common stocks, mutual funds, bonds, bitcoin, etc., can sometimes be more challenging. We explore these topics in depth in Downloading Historical Prices in the how-to section.
Note
An alternative, but convenient method for securities listed on XETRA is to utilize the Portfolio Report website. See how-to > Using Portfolio Report for more info.
"},{"location":"reference/file/new/#latest-quote","title":"Latest Quote","text":"The Latest Quote panel is very similar to the Historical Quotes panel. Here, you can configure values for real-time values such as Latest Price, Latest Trade, Day's High, Day's Low, and Volume.
"},{"location":"reference/file/new/#cryptocurrency","title":"Cryptocurrency","text":"Figure 7. Create new crypotocurrency.
A cryptocurrency is a digital asset based on a blockchain system. There are thousands of different cryptocurrencies on the market, the best known of which is Bitcoin. Unlike traditional assets, there is no tangible or intangible value backing a cryptocurrency. Instead, its value is determined solely by market demand and what investors are willing to pay for it.
In PP, cryptocurrencies are treated like any other security, such as stocks. You can buy and sell cryptocurrencies, but you cannot have a deposit account denominated in a cryptocurrency.
The popular CoinGecko website is the source of the cryptocurrencies, listed in Figure 7. You can use the Search box to look-up a specific cryptocurrency in this very long list. If the crypto you need is not listed, you should create a new empty security; remember cryptos are no different from securities in PP. However, you will need to find a way to retrieve historical price data for this new crypto security.
"},{"location":"reference/file/new/#exchange-rate","title":"Exchange Rate","text":"Figure 8. Create new exchange rate.
PP uses exchange rates from the European Central Bank. You can find the list of about 40 available exchange rates under the View > Currencies menu. In some rare cases, you may require an exchange rate that is not included in the available list.
To create a custom exchange rate, use the File > New > Exchange rate menu. You will need to provide a quote provider, such as a JSON source or webpage, for the currency you want to add. Once you've created the custom exchange rate, it will be added to the currencies list with the name Security based exchange rate provider in the Provider column.
Figure 9. Create new consumer price index.
The Harmonised Indices of Consumer Prices (HICP) are retrieved from the Eurostat website and represent the monthly inflation rate of consumer goods and services purchased by households in the euro area. The HICP is \"harmonised\" because all countries in the European Union use the same methodology to calculate it. The baseline of 100 is set for the year 2015.
After selecting the country, a security named [name of country] (HICP) is created with a First of month calendar and the Eurostat - Harmonised Indices of Consumer Prices (HICP) as the Quote Feed provider.
Being an index, however, these data series aren't normally used as a regular security (buy or sell). They can serve as a benchmark for your other investments.
"},{"location":"reference/file/new/#taxonomy","title":"Taxonomy","text":"To create a new taxonomy, select File > New > Taxonomy from the menu. This will open the New Taxonomy input box, where you can name the taxonomy and choose whether to create a new empty structure or use a predefined template, such as Asset Classes or Industries (GICS). For more information on creating and managing taxonomies, see the section on Taxonomies in the Reference manual.
Figure 10. Two watchlists.
A watchlist is a manual grouping of securities. To create a new list, navigate to File > New > Watchlist in the menu. Once created, it will appear under the All Securities heading. You can create an unlimited number of watchlists in PP. For example, Figure 6 shows two watchlists named Asia and Indices, with the latter containing four securities indices such as the DAX and Dow Jones.
Using the context menu (right-click on a list), you can rename, delete, or move (up) the watchlist (refer to Figure 6). Adding securities to the watchlist is a manual process done by dragging one or more securities from the All Securities view to the watchlist. To remove a security from the watchlist, right-click the security and choose 'Remove from Your_Watchlist'.
Watchlists inherit the view from All Securities. Changing the view in one watchlist will also change the view in all other watchlists, including the All Securities view.
Figure 1. File format picker.
With the menu File > Save, you can save your portfolio, using its existing name and file format without any further interference. If the file hasn't been saved before, a Pick the file format dialog box will appear (see Figure 1), presenting three choices. These options will be explained in the subsequent section. After selecting the file format, you can proceed as if you had started with the File > Save As option from the menu.
The File > Save As option offers the three file format choices as submenus. In the subsequent step, you can input the file name and designate the file location. This option allows you to create a new copy of a previously saved file in a different file format and/or with a different name, leaving the original file intact.
If more than one portfolio is open, the aforementioned commands will solely save the active portfolio. Utilize the Save All option to save all open files simultaneously.
Figure 2. Dialog after closing app with two updated portfolios.
Closing a portfolio that has been modified since opening will trigger a dialog 'xxx.xml is modified. Do you want to save the changes?. Closing the application with multiple updated projects will prompt the dialog from Figure 2.
All data of your portfolio is stored in one XML-file (eXtensible Markup Language). This is a human-readable file format. For example, the following xml-file test.xml is a very simple portfolio with one security (share-1) and two transactions (one deposit and one buy). You can view the xml-content by opening this file with a text editor (e.g. Notepad++). Here's a brief description of the main elements:
<securities>: Contains information about securities, including details such as UUID, name, currency code, ticker symbol, feed, historical prices, and attributes. <prices>: Contains historical price information for a security. <latest>: Provides the latest details for a security, including high, low, and volume.
<accounts>: Contains details about client accounts, including UUID, name, currency code, and transactions.
<transactions>: Represents financial transactions within an account, including details such as UUID, date, currency code, amount, and type.
<portfolios>: Contains references to portfolios associated with accounts.
<dashboards>: Contains information about client dashboards, including name, configuration, columns, and widgets.
<properties>: Holds client-specific properties, such as security chart details.
<settings>: Contains various settings, including bookmarks and attribute types.<configurationSets>: Stores configuration sets with specific data.Below you can see the xml code for the buying transaction in Figure 3.
Figure 3. Example of a buying transaction.
This single buying transaction is represented with the following XML code.
<transactions>\n <portfolio-transaction>\n <uuid>72bf2b32-60a5-4c99-ba6d-d3ab695624e5</uuid>\n <date>2023-09-10T00:00</date>\n <currencyCode>USD</currencyCode>\n <amount>174635</amount>\n <security reference=\"../../../../../../../../../securities/security\"/>\n <crossEntry class=\"buysell\" reference=\"../../../..\"/>\n <shares>500000000</shares>\n <note>First buy on advice of ...</note>\n <units>\n <unit type=\"FEE\">\n <amount currency=\"USD\" amount=\"3000\"/>\n </unit>\n <unit type=\"TAX\">\n <amount currency=\"USD\" amount=\"4500\"/>\n </unit>\n </units>\n <updatedAt>2023-09-10T18:43:28.135529700Z</updatedAt>\n <type>BUY</type>\n </portfolio-transaction>\n</transactions>\nThe PortfolioPerformance mobile app, introduced in February 2024, does not support the XML file format.
"},{"location":"reference/file/save/#password-protected-aes-256","title":"Password protected (AES-256)","text":"AES-256 encryption is a method of securing your data by converting it into a code that can only be accessed with a unique key. This encryption technique uses a 256-bit key, which is a string of 256 zeros and ones, to encrypt and decrypt the data. When data is encrypted using AES-256, it is transformed into a random sequence of characters that is unreadable without the key. In order to generate this key, PP needs a password that is at least 6 characters. However, a password that is longer and more complex will have more randomness and unpredictability, which means it is harder to guess.
Figure 4. Saving a portfolio with AES-256 encryption needs a password.
"},{"location":"reference/file/save/#binary","title":"Binary","text":"An XML file is a human-readable file format (see above for an example). A binary format is more compact and efficient and therefore a file can be opened and saved much faster. However, it is no longer human-readable. More info is available in Issue #2363; watch for example the comparison in opening speed of a 720 securities & 1.3 MB historical prices project.
Distinguishing a password-protected or binary file from a regular XML file one is possible by examining the file extension. Encrypted and binary files have the extension .portfolio instead of XML.
"},{"location":"reference/file/import/","title":"Importing documents","text":"In PP you can enter your data (buy, sell, dividends, historical quotes, \u2026 ) manually but you can also import this info from a CSV file (comma-separated values) or from a PDF document. Figure 1 displays the expanded File > Import menu.
There are two primary data sources: PDF documents and CSV files (comma-separated values). Some brokers or banks may present this information in a proprietary format. Templates for major banks or brokers are available.
Figure 1. Menu File > Import.
"},{"location":"reference/file/import/csv-import/","title":"Importing a CSV file","text":"PP employs a wizard to lead you through the import process, consisting of three steps. At each step, you are required to furnish additional information.
Step 1. Start with the menu File > Import > CSV files (comma-separated values), navigate to the correct folder and select the appropriate CSV file. Only files with the extension CSV are displayed.
A CSV file is simply a text file. The first line contains the names of the fields (columns); separated by a marker such as a comma. The second and following lines contain the data, also separated by a marker. The number and type of fields the file should contain, depend on the type of import. The names in the heading can be freely chosen, although they should match PP's internal usage, as it simplifies the mapping process (associating each column with its corresponding field in PP). The printout of a CSV file in Table 1 (see below) comprises two fields or columns and four lines of data that could be utilized for importing historical prices.
Figure 1. Import types.
In step 2 of the wizard, you need to select the appropriate import type or template by clicking on the drop down box (see Figure 3). PP distinguishes between 5 types of import: Account Transactions, Portfolio Transactions, Securities, Historical Quotes, and Securities Account (see Figure 1). These templates are discussed in detail below. You also need to decide about the following options.
UTF-8 or Windows-1250. -> 'Field' in the second row of the output; otherwise, a message Double click here will appear (see Figure 3). To associate a column with an internal PP field, double-click on the second line. You can then choose from the available fields. If you don't want to associate a field, select the --- option. PP will then ignore this column. To change the format of a column, e.g. Date format of a date, double-click on the name in the second line.Figure 2. Saving the mapping configuration.
Built-in configurations will be displayed, such as comDirect, Consorsbank, etc. (see Figure 3). Using the option Save current configuration will save your current mapping configuration as a custom template. This template will be available under User-specific Configurations, for example, test (Account Transactions) (see Figure 2). You can delete, export, and import configurations. The export function uses a JSON format.Step 3: set additional info, depending on the import type such as accounts and check the preview of the import process. Step 3 differs depending on the selected type of import. For the historical quotes import type, only the share name should be additional selected. For the other types, you need to set the security and cash account.
Note
The cash and security account could be set globally for all import rows of the CSV file through the top panel; see for example Figure 6. You can also provide this information as part of the CSV file (include a column Cash account and Securities account). Or you can set the accounts through the context menu. Right-click on a row in the table preview and choose the appropriate account.
"},{"location":"reference/file/import/csv-import/#1-historical-quotes-import","title":"1. Historical Quotes import","text":"To import historical quotes for a security, you only need two columns in the CSV file: one for the date and another for the corresponding quote. These are required fields. No optional fields are allowed. The security's name must be provided in a separate step. You cannot proceed to the next step if any of the required fields are missing.
Table 1: Source data for the import of Historical Quotes.
Date; Price\n2024-01-09; 22,51\n2024-01-08; 22,54\n2024-01-05; 22,43\n2024-01-04; 22,46\nYYYY-MM-DD. By double-clicking on the second row of the output panel; e.g. -> 'Date', you can set the correct date format. January 7th and 6th are not included as these are weekend days (although they could be). In this case, the price information uses a comma as a decimal separator, which is standard in Europe. Therefore, a semicolon (;) is used to separate the fields. The file is saved in Excel with UTF-8 encoding. The heading labels are Date and Price. Figure 3. Importing Historical Quotes (step 2).
In Figure 3, the Next and Finish buttons are greyed out because not all necessary information is available. The message at the top, \"Unmapped required field(s): Quote,\" provides a clue. For this type of import, two fields are required: Date and Quote. However, the CSV file uses the headings Date and Price. The field Price should be mapped to the internal Quote field. Double-click on the column and select the appropriate mapping field, e.g. Quote. The Next and Finish buttons will then become available.
In step 3 of the wizard, you can select the security that the prices will be added to. If the chosen security already has some historical prices, the quotes will be added (no duplicates).
Figure 4. Importing Historical Quotes (step 3).
"},{"location":"reference/file/import/csv-import/#2-securities-import","title":"2. Securities import","text":"Use this type to create new securities from a CSV file. There are no required fields. The optional fields include Ticker Symbol, Security Name, WKN, ISIN, Currency, Date of Quote, Note, and Quote. It is evident that at least one of the first four fields should be mapped. Refer to the glossary for the meaning of these terms. See Table 2 for an example of the CSV-file.
Table 2: Source data for the import of Securities.
Ticker Symbol; ISIN; Security Name ;Currency\nBAS; DE000BASF111; BASF; EUR\nNVDA; ; NVIDIA; USD\nFigure 5. Importing securities (Step 2).
In step 3 (below), you can observe that the status of both securities contains a green check mark, indicating that the import will be successful. If the securities should already exist, nothing will appear. Click Finish.
Figure 6. Importing securities (Step 3).
The securities are now created and appear in the All Securities list. Although the cash and security account options are provided in Figure 6, it does not make sense to add or change the cash or security account here. The securities are only created in the All Securities list, no transactions are yet in place. Please note that several other fields such as Calendar, Additional Attributes, and Taxonomies cannot be added through CSV-import. The Quote Feed for the Historical Prices could partially be added in the following step (see Figure 7).
Figure 7. Importing securities (Step 4).
After the securities are created, an additional step allows you to search for a suitable quote feed. This can also be performed manually by right-clicking on a security and choosing Quotes > Search for providers of historical prices...
Only securities listed on XETRA (Deutsche B\u00f6rse) and analyzed by the Portfolio Report are eligible for an automatic Quote Feed. The BASF security in Figure 7 meets these criteria and can therefore receive an automatic quote feed. However, the NVIDIA security is not listed on XETRA in USD, so automatic quotes should be obtained through another candidate provider e.g. Yahoo Finance.
"},{"location":"reference/file/import/csv-import/#3-securities-account-import","title":"3. Securities Account import","text":"With this import type, you can create a new security (see above), while adding at the same time the first Buy transaction. The required fields are Shares, and Value. The optional fields are Ticker, Symbol, ISIN, WKN, Time, Currency, Note, Date of Quote, Securities Account, Cash Account, Quote, Date of Value, and Security Name. The following CSV file will be imported in Figure 8.
Ticker Symbol; ISIN; Security Name; Currency; shares; value\nBAS; DE000BASF111; BASF; EUR; 20; 900\nNVDA; ; NVIDIA; USD; 10; 5450\nFigure 8. Importing securities (Step 4).
"},{"location":"reference/file/import/csv-import/#4-account-transactions-import","title":"4. Account Transactions import","text":"The Account Transactions import type will be used to register transactions on a deposit or cash account such as deposit, removal, interest, ... It is equivalent with manual recording a transaction with the menu Transaction (third group). The required fields are Date, and Value.
Important
The Account Transactions and Portfolio Transactions import types are quite similar. Internally, an account transaction is reserved to work with cash accounts and their transactions such as deposits. A portfolio transaction works with instruments and their transactions: buy, sell, delivery, ... A buy/sell transaction however has both components: something is added/removed from the securities account and some money is deducted/added to the cash account. In most cases, both types could be used interchangeably.
Use Account Transactions type for deposit, removal, ... and Portfolio Transactions type for buy, sell, ...
The required fields are Date, and Value. Optional fields are Type, Transaction Currency, Security Name, Shares, Securities Account, Exchange Rate, Gross Amount, Currency Gross Amount, Ticker Symbol, Taxes, Note, Cash Account, Fees, ISIN, WKN, Offset Account, and Time.
Acceptable values for the field Type are Deposit, Removal, Buy, Sell, Dividend, Interest, Interest Charge, Fees, Fees Refund, Taxes, Tax Refund, Transfer (Inbound), Transfer (Outbound), Delivery (Inbound), and Delivery (Outbound). The default value for Type is Deposit.
If the Cash and Securities account are not provided in the CSV file, the value from the top panel is used. It's important to note that Fees and Taxes can be included as part of the Buy or Sell transaction through a dedicated column in the CSV file. In this case, the taxes and fees are subtracted from the total value field (Value = Gross Amount + Taxes + Fees). Alternatively, a separate transaction with the type Fees or Taxes can be created, and the amount is then specified in the Value column. In this case, the fees and taxes are added to the value.
Figure 9. Importing account transactions - content CSV file
Figure 9 displays the content of a sample CSV file. Four transactions are described. Note that the Cash account of the first transaction is not provided. The default account from the top panel is taken in that case.
Figure 10. Importing account transactions - step 2.
Figure 11. Importing account transactions - step 3.
"},{"location":"reference/file/import/csv-import/#dividend-transaction","title":"Dividend transaction","text":"It is noteworthy to address the dividend transaction separately, as it presents unique challenges, particularly when dealing with foreign dividends. For instance, complications may arise when dividends are paid in USD but deposited into a cash account denominated in EUR.
To illustrate, let us assume that a USD dividend of 5 USD is paid for three shares, with a hypothetical exchange rate of 0.5 EUR-for-1-USD. For this example, we will use the cash account Broker-A (EUR) denominated in EUR for the deposit.
In this example, the CSV file contains columns for the date, type of transaction (in this case, a dividend), the security name (NVIDIA), the number of shares, the currency in which the dividend was paid (USD), the gross amount of the dividend, the applicable exchange rate, the cash account into which the dividend was deposited broker-A (EUR), and the converted value of the total dividend in EUR.
The raw CSV-file looks like:
Date;Type;Security Name;Shares; Currency Gross Amount; Gross Amount; Exchange Rate; Cash Account; Value\n2024-01-13; Dividend; NVIDIA; 3; USD; 15; 0,5; broker-A (EUR); 7,5\nFigure 12 illustrates the initial step in the import wizard process. As the CSV file incorporates the accurately spelled field names, no mapping adjustments are required. It is crucial to take note of number formatting of the various fields, particularly the exchange rate field, which will likely always contain a decimal separator (comma or point). Also check the date format; YYYY-MM-DD, or DD/MM/YY, or ....
In this instance, we are receiving a dividend payment for three shares, with a Gross Amount of 15 USD. Consequently, the dividend value should be 5 USD per share (see Figure 13). Given the Exchange Rate of 0.5 EUR-for-1-USD, the net Value of the dividend, once deposited into the broker-A (EUR) account, should amount to 7.5 EUR.
Figure 12. Step 1 of the Import wizard: type dividends.
The necessity of the Gross Amount field is not apparent, particularly as it is not utilized in the subsequent section. However, the Portfolio Performance (PP) software verifies the values within this field, ensuring that the following calculation holds true: Gross Amount multiplied by the Exchange Rate equals the Value. If the numbers do not correspond, an error message will be displayed, preventing progression to the next step.
Upon importing the CSV file detailed above and selecting the Account Transactions type, the dividend transaction will be generated as depicted in Figure 13.
Important
Regrettably, the software does not currently support the inclusion of Fees and Taxes, either in the foreign or domestic currency.
Figure 13. Result of import from above.
"},{"location":"reference/file/import/csv-import/#5-portfolio-transactions-import","title":"5. Portfolio Transactions import","text":"Important
If you have transactions with securities in different currencies, it is good practice to explicitly add the Security Account and Cash Account to the CSV-file. As the Date is a required field, pay attention to the default date format (YYYY-MM-DD).
This type of import requires three fields: Shares, Date, Value. The optional fields are the same as above; except that the optional Offset Account field is replaced with Offset Securities Account. The selection of required fields may seem somewhat arbitrary. For transactions like buy and sell, a security identification is essential (such as name, ISIN, etc.). However, for an interest payment, the 'Shares' field is not necessary.
Because the number of shares is a required field, one would assume that simple deposit of removal transactions are not allowed; but they are. The number of shares is then ignored.
The acceptable values for the field Type are: Deposit, Removal, Interest, Interest Charge, Dividend, Fees, Fees Refund, Taxes, Tax Refund, Buy, Sell, Transfer (Inbound), and Transfer (Outbound). The default value of Type is Sell.
Suppose that you wish to import two portfolio transactions: a sell of 2 shares of BASF in EUR and a buy of 3 shares NVIDIA in USD. Since we are using the EUR cash account in both cases, the transaction in USD must be converted into EUR. In this case, PP will handle this automatically because the NVIDIA security is listed in USD and the security account in EUR. Alternatively, you can designate the Currency Gross Amount column as USD. However, a more efficient workflow may involve defining the Cash Account, and eventually the Securities Account. This prevents the import from defaulting to standard accounts, such as broker-A and broker-A (EUR) in this case.
Figure 15 displays the Mapped to Field dialog box is shown (accessible via double-clicking the Value column). It's advisable to confirm that the selected format aligns with your language settings, especially if you use a comma as the decimal point as in this example.
The CSV file should look as follows.
Date;Type;Shares;Security Name;Value;Exchange rate;fees;taxes;Securities Account;Cash Account\n2024-01-04; Sell; 2; BASF; 90; ;5; 3; broker-A; broker-A (EUR)\n2024-01-13; Buy; 3; NVIDIA; 1740,98; 1,0837; 15; 10; broker-A; broker-A (EUR)\n(Net) Value field is required, it makes no sense to add the Gross Value, which will be overwritten anyway (Gross Value = Value + Fees + Taxes). Please note that the Exchange Rate field is empty (or zero) in case of the BASF transaction. Figure 14 displays the result of this import transaction. Figure 14. Result of import from above.
Figure 13 displays the first step of the Import wizard. Be sure that the type Portfolio Transactions is selected in step 1; otherwise an error will occur in step 2.
Figure 15. Result of import from above.
A consistency check is made, for example, to ensure that you don't sell more securities than are available in your portfolio (see Figure 16).
Figure 16. Consitency check.
"},{"location":"reference/file/import/pdf-import/","title":"Importing PDF documents","text":"Banks and brokers often provide transaction statements (buy, sell, dividend, etc.) for your convenience on paper or in PDF format. PP can read PDF documents from more than 90 banks and brokers and import the described transactions. The PDF in Figure 1 describes a (fictitious) buy transaction from an Australian broker. If you want to follow along with the example, you can download the PDF document.
Figure 1. Buy statement from SelfWealth of 25 pcs of Beta SP500 YieldMax.
"},{"location":"reference/file/import/pdf-import/#checking-the-existence-of-the-importer","title":"Checking the Existence of the Importer","text":"PP must \"know\" some details about the PDF document from your bank or broker. For example, the type of transaction in Figure 1 is identified by the title \"Buy Confirmation,\" and the ticker symbol (UMAX) is indicated under the column header \"Security Code.\" PP must recognise these details for each transaction to extract the necessary content from the PDF. Therefore, for each supported bank or broker, PP has developed a specific importer (parser) with knowledge of the different transaction types. To develop these importers, PP relies on information provided by its users (see Requesting a New Importer).
To verify if your bank or broker is supported, try to import a PDF document (see next section). The import wizard will either recognise it automatically or display an error message listing all the banks/brokers it has tried. You can also search the forum using the term PDF import or PDF import [name-of-your-bank-or-broker] to see if an importer for your institution is available or if there are any issues with it. If the importer exists, you can move on to the next section. Otherwise, you need to first request a new importer (see Requesting a New Importer).
Use the menu File > Import > Import PDF Bank Documents or the shortcut key CTRL+I, P, and navigate to the PDF document on your local system. You can select more than one PDF document. If a document is recognised by PP (i.e., an importer exists for the bank or broker of this document), an Import Transaction dialog box, such as in Figure 2, is displayed.
In this particular case, there is a small problem and the import operation could not be fully executed. The error message at the bottom provides an indication: the cash account Call Money Account from the demo Kommer portfolio is used for the cash handling of the transaction, but this deposit account is in EUR while the transaction currency is AUD. Selecting (or creating) an AUD deposit account will fix the problem. Please note that in Figure 2, two operations are scheduled: (1) the buy transaction, and (2) the creation of the security Beta S&P500 Yieldmax. If this security already exists in the portfolio, then the import wizard will use the existing security.
Figure 2. Imported transaction from PDF of Figure 1.
Figure 3. Search for suppliers of historical prices (example available at Portfolio Report).
In case of a new security, a Search for suppliers of historical prices box is displayed. If the security is listed on Portfolio Report, then the historical prices could be automatically added. Otherwise, the security is created, but you will need to manually edit the data source to download the historical prices.
If PP doesn't have a PDF importer for your bank/broker or for the specific type of transaction you need, you can request the development of this importer. More info can be found at How-to > Requesting a new PDF Importer.
"},{"location":"reference/help/about/","title":"Help > About Portfolio Performance","text":"Detailed information about the PP program could be found in the menu Help > About Portfolio Performance. The top panel contains the version, e.g. 0.67.0 from december 2023, the platform and the Java version it runs on. The platform could be Windows (win32, x86_64), Linux, or macOS; see Installation. The PP program is built with the Java programming language. The most recent Long Term Support (LTS) version of the OpenJDK (Java Development Kit) is obtained through Azul.com. From the copyright info, you learn that the author Andreas Buchen started development back in 2012.
Figure 1. The About Portfolio Performance panel.
The bottom panel contains links to the used (open source) software, code contributors, translators, and Writers. There is also a section about Installation Details.
"},{"location":"reference/help/about/#software","title":"Software","text":"Eclipse Foundation: Eclipse is a free and open source software development environment that supports various languages, platforms and plugins. It is a very popular and widely used IDE (Integrated Development Environment). Eclipse allows developers to create, test, debug, and deploy applications using a common framework and a rich set of tools. From a user perspective, the choice of a specific IDE is not important. The development platform e.g. Java SDK however is very much.
Apache Software Foundation: Several libraries are used; for example to extract text and metadata from PDF documents, and to perform HTTP requests and handle responses (e.g. communicate with Portfolio Report).
SWT Chart Project: The Eclipse SWTChart software is used to create the line and pie charts in the app. PP uses the Standard Widget Toolkit (SWT) which is a graphical user interface (GUI) library that allows Java developers to create native-looking applications for different platforms. You enable this library in Help > Preferences > General.
Tree Map Library: Treemaps represent a distinct visualization technique for illustrating hierarchical data by using a series of nested rectangles. This kind of map is used in the Taxonomies menu.
jsoup Java HTML Parser: jsoup is a Java library that simplifies working with real-world HTML and XML. It offers an easy-to-use API for URL fetching, data parsing, extraction, and manipulation using DOM API methods, CSS, and xpath selectors. The library is used for example to fetch the historical prices from a table on a financial website.
JSON.simple: JSON.simple is a simple Java toolkit for JSON. You can use JSON.simple to encode or decode JSON text. This tool is used in the app for downloading historical prices from a JSON data source.
Protobuf: Protocol Buffers (a.k.a., protobuf) are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data. The software is used to convert the XML-datastructures of the portfolio file into Java usable data structures.
Guava: The Guava libraries are intended to complement the core java libraries and make working in the Java language more pleasant and more productive.
JsonPath: JsonPath is a query language for JSON. It allows to select and extract a sub-section from a JSON document using a simple syntax that is similar to XPath for XML.
D3.js: D3.js is an abbreviation for Data-Driven Documents and is a JavaScript library to work on data visualization e.g. graphs.
XStream: A Java library that allows you to serialize and deserialize Java objects to and from XML or JSON.
OpenJDK: Running a Java program on for example a Windows machine requires that the Java Development Kit (JDK) is installed on that computer. PP uses the JDK provided by Azul.com.
"},{"location":"reference/help/about/#code-contributors","title":"Code Contributors","text":"A link to the Github pages of each of the 159 contributors is given. A graphical overview of all contributions from 2012 till today can be found at Github.
"},{"location":"reference/help/about/#translators","title":"Translators","text":"PP has been translated into Spanish, Dutch, Portuguese, Brazilian Portuguese, French, Italian, Czech, Russian, Slovak, Polish, Chinese (simplified), Chinese (traditional), and Danish.
"},{"location":"reference/help/about/#writers","title":"Writers","text":"The two main sources of documentation for the program are the Forum (German - English) and the Handbook (German - English).
"},{"location":"reference/help/about/#installation-details","title":"Installation Details","text":"Clicking on this tab will generate a very long and detailed description of the environment PP is running in (OS, Java and Eclipse components, paths to log-files, ...).
"},{"location":"reference/help/check-updates/","title":"Help > Check for Updates ...","text":"After the first installation, you can either check manually for updates or allow the program to check each time it starts.
"},{"location":"reference/help/check-updates/#manual-check-for-updates","title":"Manual check for updates","text":"To manually check for updates, navigate to the menu Help > Check for Updates .... Figure 1 will briefly appear.
Figure 1. Checking for updates.
Either no updates are available; indicating that your version is up-to-date or figure 2 will be shown; the correct version will of course be different in the future.
Figure 2. Checking for updates.
To install the most recent version, click OK. To cancel the update and stay with the old version, click Cancel.
There are three links at the top of the panel. New & Noteworthy provides detailed information about the changes in the latest version but also about all previous releases. The Change Log link leads to the Github page of the project where all (previous) releases are described. The download link takes you to the homepage; where you can download the program for the different operating systems (Linux, Windows, macOS); see Getting Started > Installation.
Below the links, you can find an overview of the changes in the last two releases. At the bottom right, you can enable the automatic check for updates (see below).
"},{"location":"reference/help/check-updates/#automatic-check-for-updates","title":"Automatic check for updates","text":"Automatic checking for updates is enabled by default. You can change this setting in the menu Help > Settings > Updates > Check for updates on start (see figure 3).
Figure: Setting for automatic check for updates.{class=pp-figure}
"},{"location":"reference/help/preferences/","title":"Preferences","text":""},{"location":"reference/help/preferences/#preferences","title":"Preferences","text":"There are two distinct sections within the PP software where you can customize the User Interface (UI) and the overall behavior of the program: the View > Settings menu and the Help > Preferences menu.
Figure 1. The General option of the menu of View > Settings.
The preference settings have system-wide implications and will be applied to all portfolios managed by PP. The Preferences window features a sidebar, as illustrated in Figure 1, which is further divided into six submenus.
"},{"location":"reference/help/preferences/#general","title":"General","text":"By selecting the General menu item in the sidebar of the Preferences dialog box (see Figure 1), you will be presented with four options:
Automatically update quotes after opening a file: Each security can have an external data source assigned for downloading historical quotes. You can start the download process manually through the Online menu or enable the option to automatically download historical quotes upon opening the portfolio.Store Gui settings next to Portfolio Performance file: The Graphical User Interface (GUI) settings influence several aspects of the look and feel of the PP program such as the width of columns or size of windows (e.g. main pane vs information pane) and others. These settings are stored in a separate file, that can be located:
In the same folder as the portfolio file (option is checked). The name of the file is [name-of-portfolio].settings; e.g. demo-portfolio-03.settings.
In a subfolder of the workspace folder of the PP application (option is unchecked). The name is a unique random string with the extension \"txt\", e.g.prf_c4c742f0f7312d48355beadb57dc4a09.txt. This file is invisible by default. The location of the workspace folder is:
~/Library/Application Support/name.abuchen.portfolio.product/workspace%LOCALAPPDATA%\\PortfolioPerformance\\workspace~/. PortfolioPerformance/workspaceYou need to search in the subfolder: .metadata\\.plugins\\name.abuchen.portfolio.ui.
The location of your settings file is critical when transferring your portfolio to another computer. If the settings file is stored adjacent to the portfolio, the process is simplified; you only need to copy both files to the new location. However, if the settings file is stored within the workspace folder, it will not be automatically regenerated when installing the PP application on the new computer. In this case, you must manually copy the file from the old computer and paste it into the corresponding location on the new computer to ensure proper configuration.
Enable experimental features: This feature is only intended for developers or \"bold\" users who wish to test out new experimental features, such as a new file format
SWTChart library for pie charts: In certain operating systems, such as Linux, enabling this option is required to accurately display pie charts.
There is only one preset to configure, which is determining the time value for newly entered data, such as the time of a buying transaction. The default setting is Start of day (= 00:00). Alternatively, you can select Current time, which will use the time from your computer clock for new entries.
Figure 2. Settings for the backup of the data files.
The first option enables an automatic backup of your portfolio, creating a copy just before the previous version is overwritten (saved) with the current one. This serves as a safeguard in case you unintentionally modify elements within your portfolio and need to revert to its previous state.
You have three choices for the backup location:
Next to data file: The backup is saved in the same folder as the original portfolio with the text .backup, appended to the name; for example myPortfolio.backup.xml.Selected directory: The backup is saved in the folder location specified below. This could be a completely different directory or drive.Directory Next to data file: The backup is saved in a folder at the same level as the portfolio file. The name of the folder is specified below (e.g. backups, as shown in Figure 2).Note
In fact, turning on the backup option will create a file such as myPortfolio.backup-after-open.xml right after opening your portfolio. This file will contain the state of your original portfolio.
Autosave copy every X minutes: You can specify the number of minutes in the provided text field. With this option enabled, the current state of the portfolio file will be saved automatically every X minutes. Any existing autosave file will be overwritten. To disable this feature, enter zero (0) minutes. The autosave file will be named [name-of-portfolio].autosave.[extension] and stored in the same folder as the original portfolio.Use indirect quotation for exchange rates: Each portfolio has a single base currency, which is set during the creation of the portfolio and can be modified later in the Statements of Assets view. When conducting a transaction involving a foreign currency (foreign relative to the base currency), an exchange rate must be applied. With indirect quotation, the exchange rate indicates how much of the foreign currency is required to purchase one unit of the base currency. On the other hand, direct quotation specifies how much of the base currency is needed to acquire one unit of the foreign currency.
For instance, if your base currency is EUR, the exchange rate with USD would be represented as follows:
Indirect quotation: 0.9321 USD/EUR (one unit of the base currency requires 0.9321 units of the foreign currency)
Direct quotation: 1.0729 EUR/USD (1.0729 units of the base currency are needed for one unit of the foreign currency)
Always display currency code for monetary values: If this option is unchecked, PP will show the currency code (e.g., USD) only when the currency differs from the base currency, resulting in a cleaner and less cluttered view.
Add \"p.a.\" to annualized return rates: The Internal Rate of Return (IRR) is, by definition, an annualized return rate. The True-Time Weighted Rate of Return (TTWROR) is calculated per reporting period (and thus, possibly unannualized). Enabling this option will consistently append the suffix \"p.a.\" to indicate when the return rate is annualized.Figure 3. Settings for the language, country, and Java Locale.
Using the language drop-down menu, you can modify the user-interface language of the PP software, such as the menus and dialogs.. 13 different languages are available: Deutsch (German), English, Espa\u00f1ol (Spanish), Fran\u00e7ais (French), Italiano (Italian), Nederlands (Dutch), Portugu\u00eas (Portuguese), \u010de\u0161tina (Czech), \u0440\u0443\u0441\u0441\u043a\u0438\u0439 (Russian), Slovensk\u00e1 (Slovak), Polskie (Polish), \u4e2d\u6587 (Chinese), and Dansk (Danish).
The selected language will also affect the available country options. For instance, the Dutch language is spoken in seven countries: Aruba, Belgium, Carribean Netherlands, Curra\u00e7ao, Sint Maarten, and Suriname.
If English is selected as the UI language, several countries, including an option for Europe and World, can be chosen. The combination of language and country determines the Java Locale. For example, selecting the language \"Dutch\" and the country \"Belgium\" will result in the Java locale \"nl_BE\". Choosing \"English\" and \"Europe\" will produce the Java locale \"en_150\".
The Java Locale is responsible for formatting dates, currency, decimal and grouping separators, and the first day of the week. For example, the combination of English and Belgium produces the Java locale \"en_BE\", which in turn displays a date like \"03 Oct 2024 15:49\" (English language but Belgian notation) with Monday as the first day of the week, and a comma (,) as the decimal separator and a dot as the grouping symbol.
On the other hand, the combination of English and the United States (en_US) results in a date format like \"Jul 3, 2024, 3:49 PM\" with Sunday as the first day of the week and a number format like 12,345.67.
"},{"location":"reference/help/preferences/#theme","title":"Theme","text":"Figure 4. Theme Settings - example of Light vs Dark theme.
In the Settings > Theme section, you can select either a Light or Dark theme (refer to Figure 4) or set it to automatic. If you choose the automatic option, your system clock will determine whether the light or dark theme will be applied.
The default font size is set to 9 pixels, but you can adjust it according to your preference, with options ranging from 8 pixels to 20 pixels.
"},{"location":"reference/help/preferences/#formatting","title":"Formatting","text":"In this section, you can adjust the display precision for the number of shares (default is rounded to 1 decimal place) and the display precision for calculated quotes (default=2). Keep in mind that the changes will only be visible with decimal numbers (which need to be rounded to the specified number of digits after the decimal point) in read-only views, such as the Statement of Assets view. On input forms, like a buy-input form, you can still enter a more precise number with additional decimal places.
"},{"location":"reference/help/preferences/#calendar","title":"Calendar","text":"A calendar specifies the holidays (of your stock exchange) or the non-trading days for a selected year. Calendars play an essential role in calculations, certain chart views, and investment plans within PP. For instance, if the start date of a monthly investment plan falls on a holiday, the transaction will be moved to the next working day.
PP offers 13 different stock exchange calendars. These include the Australian Stock Exchange (ASX), Euronext, German stock exchanges (DE), IBOV Sao Paulo Stock Exchange (Brazil), ISE Italian Stock Exchange (ISE), London Stock Exchange (LSE), Moscow Exchange (MICEX-RTS), New York Stock Exchange (NYSE), Swiss Exchange (SIX), Toronto Stock Exchange (TSE), and Vienna Stock Exchange (VSE). There are also 4 more generic calendars:
When you select a calendar from the drop-down list, it will display the corresponding holidays for the chosen calendar and year.
Note
Any changes made to the calendar settings will only take effect after restarting the PP program.
"},{"location":"reference/help/preferences/#api-keys","title":"API keys","text":"An API, or Application Programming Interface, is a set of rules and protocols that allows different software applications to communicate with each other. An API key is a unique identifier used to authenticate a user to an application programming interface (API). API keys are used to track and control how the API is being used, prevent abuse, and provide access to specific services or data; see downloading historical prices for a few examples.
For example, Alpha Vantage is a popular API that provides access to financial data. To use the Alpha Vantage API, you first need to sign up on their website and obtain an API key. Then, you can issue an HTTP request such as https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=AAPL&apikey=your_api_key. To avoid having to enter your API key repeatedly, you can save it in the Settings section.
Downloading historical prices requires accessing an external web server such as Yahoo Finance. Using a proxy server can hide your IP address, making your online activity more anonymous. In a corporate environment, proxies are often used to enforce internet usage policies, monitor employee activity, and ensure compliance with regulatory requirements.
"},{"location":"reference/help/preferences/#updates","title":"Updates","text":"PP is regularly maintained and updated. To manually check for updates, you can visit the homepage. The version number (e.g., 0.69.0) is displayed above the download links. Additionally, you can find the latest release on GitHub.
By enabling the Check for updates on Start option in the Settings section, PP will automatically check, download, and install the latest version (if necessary) upon launch. The update process is carried out from the URL https://updates.portfolio-performance.info/portfolio.
On rare occasions, the PP app may not function properly or even crash. Beneath the Help menu, three options can assist in such instances.
"},{"location":"reference/help/trouble-shooting/#show-error-log","title":"Show Error Log","text":"Every time the program starts, it creates a log-file. You can view this log file from within the PP app in a separate window with the command Help > Show Error Log. Double-clicking the message will display the entire text. If there were no errors, this will be a minimal log (see Figure 1).
Figure 1. Log after successful start-up.
If an error is encountered, the log file will list them sequentially. Figure 2 hints at the error (No quotes found). You can double-click on the message to receive more detailed info.
Figure 2. Log after unsuccessful operation.
A rather large text file will appear when double-clicking the message (see below). If you can open the portfolio, you need to fix the historical prices source of this security. Otherwise, you need to open the XML-file in a text editor and manually remove the offending data source.
Figure 3. Log after unsuccessful operation.
You can copy this text to the clipboard, for example when seeking help on the forum or you can save the file.
"},{"location":"reference/help/trouble-shooting/#save-error-log","title":"Save Error Log ...","text":"As previously mentioned, each time the program starts, it generates a log file. This file is automatically saved in your user directory. For Windows users, it typically resides in: C:\\Users\\Your-name\\AppData\\Local\\PortfolioPerformance\\workspace\\.metadata\\.
To save the latest log to a text file with the extension .log, you should use this command. The text file provides more comprehensive information (see below) than the error window depicted in Figure 3, including details about the operating system, the current Java version, and other relevant data.
!SESSION 2024-02-19 11:47:29.300 -----------------------------------------------\neclipse.buildId=0.67.3.\njava.version=17.0.5\njava.vendor=Azul Systems, Inc.\nBootLoader constants: OS=win32, ARCH=x86_64, WS=win32, NL=en_US\nCommand-line arguments: -os win32 -ws win32 -arch x86_64\n\nThis is a continuation of log file C:\\Users\\your-name\\AppData\\Local\\PortfolioPerformance\\workspace\\.metadata\\.bak_0.log\nCreated Time: 2024-02-19 13:18:06.540\n\n!ENTRY name.abuchen.portfolio 4 0 2024-02-19 13:18:06.540\n!MESSAGE 404 Not Found --> https://query1.finance.yahoo.com/v8/finance/chart/TNET.BR?lang=en-US®ion=US&corsDomain=finance.yahoo.com\n!STACK 0\nname.abuchen.portfolio.util.WebAccess$WebAccessException: 404 Not Found --> https://query1.finance.yahoo.com/v8/finance/chart/TNET.BR?lang=en-US®ion=US&corsDomain=finance.yahoo.com\n at name.abuchen.portfolio.util.WebAccess.executeWith(WebAccess.java:222)\n at name.abuchen.portfolio.util.WebAccess.get(WebAccess.java:182)\n at name.abuchen.portfolio.online.impl.YahooFinanceQuoteFeed.rpcLatestQuote(YahooFinanceQuoteFeed.java:61)\n at name.abuchen.portfolio.online.impl.YahooFinanceQuoteFeed.getLatestQuote(YahooFinanceQuoteFeed.java:69)\n at name.abuchen.portfolio.ui.jobs.UpdateQuotesJob$1.run(UpdateQuotesJob.java:244)\n at org.eclipse.core.internal.jobs.Worker.run(Worker.java:63)\nChoosing this option will simply display the dialog boxes of Figure 1 & 2. As you can see, you need to quit and restart the application after that.
Figure 4. Reset GUI dialog box.
Figure 5. Successful reset of UI.
The Reset UI function will NOT delete any created views or custom reporting periods, nor will it reset the Recent Files list, as these parameters are saved separately.
However, it does reset the position and size of the PP application window on your monitor and does not restore open files from the moment of closing. Additionally, it sets the main and information panes to their initial values. In essence, as the name implies, it resets the Graphical User Interface (GUI/UI).
In the event of unexpected errors, initiating a Reset UI could be your initial troubleshooting step, as it minimally disrupts your workflow.
"},{"location":"reference/help/trouble-shooting/#updating-error","title":"Updating error","text":"If the program is corrupted or some files are missing, automatic updates are not feasible. An error message (see figure 4) is displayed, and the automatic update is no longer possible.
The simplest workaround is to delete the program and reinstall it.
Figure 6. Error message upon manual check for updates.
"},{"location":"reference/transaction/","title":"Transaction","text":"Figure 1. Transaction menu.
In PortfolioPerformance (PP), a transaction represents an operation that alters the state of a portfolio; for example, a deposit will increase a deposit account. As depicted in Figure 1, there are 15 transaction types. Security transfer ... and Transfer between accounts ... deviate slightly from the others and only appear when there is more than one security and/or deposit account. The transactions can be grouped into pairs of operations that have opposite effects:
Note
In theory, PP could suffice with 8 transaction types: trade, delivery, deposit, fees, taxes, interest, transfer, and dividend. Each transaction could be expressed with a positive or negative value, for example: sell or trade(-) and buy or trade (+).
In fact, this is suggested by the fact, that the type of a transaction could be changed in a table such as All Transactions by double clicking on the keyword (e.g. Buy) and choosing the alternative from the drop down (sell, delivery inbound, delivery outbound). This technique doesn't work with fees and taxes.
Figure 2 illustrates the effect of all 15 transaction types on the deposit and securities account. Analyzing Figure 2 will clarify the impact that each transaction type has on a portfolio.
Security accounts are exclusively impacted by buy, sell, delivery (inbound & outbound), and Security Transfer transactions. This likely explains why they are grouped together with a divider line (see figure 1). It's important to note that while a buy/sell transaction affects both deposit and security accounts, delivery and security transfer transactions do not. A delivery is essentially a buy/sell transaction without the involvement of deposits and is represented as originating from outside the portfolio.
All transaction types, except delivery and security transfer (see above), will affect the deposit account. These effects could manifest as inflows (green color) or outflows (red color).
The coloring scheme might be a bit confusing. In the image on the left side of Figure 2, which represents the All Securities view, a buy transaction results in an outflow from the deposit account, yet it's depicted in green. Conversely, a transfer (from one security/deposit account to another) is depicted in red.
With the exception of interest, all transaction types are associated with a specific security, such as a share. Interest, on the other hand, is only linked to a deposit account. One implication of this is that interest on bonds should be recorded as a dividend in PP if you wish to maintain the connection with the bond.
Figure 2. All 15 transaction types with their effect.
"},{"location":"reference/transaction/buy-sell/","title":"Buy or Sell transaction","text":"When buying or selling a security, there are two main scenarios to consider regarding the currency of the deposit account.
In the first scenario, if the security is in the same currency as the deposit account, the transaction is straightforward. The buyer or seller simply pays or receives the equivalent amount corresponding to the value of the security, and the corresponding amount is debited or credited from or to their deposit account.
In the second scenario, if the security is not in the same currency as the deposit account, a currency conversion becomes necessary. This need for currency conversion can also arise if your broker or bank charges you taxes and fees in your local currency, while you're utilizing a deposit account denominated in the foreign currency of the security.
"},{"location":"reference/transaction/buy-sell/#one-currency","title":"One currency","text":"Figure 1. Buy and Sell transaction with one currency.
In Figure 1, both the security and the deposit account are denominated in EUR. Consequently, no currency conversion is required, given that fees and taxes are also in EUR for this particular broker. The fields Security, Securities Account, Deposit Account, Shares, and Debit Note are mandatory. An error message will be displayed at the top until all conditions are fulfilled, as depicted in Figure 1.
You can navigate through these fields using the Tab key on your keyboard or by using the mouse.
Security is normally pre-filled with the first or selected security from the All securities list. You can, of course, select another security from the drop-down. Please note that the currency is automatically set because each security has a reference currency, which is set during creating the security.Help > Preferences > Language > Country. For instance, the UK uses a 12-hour clock (with AM and PM), while Belgium uses a 24-hour clock. By default, the Start of Day, e.g. 00.00 is taken. You can change it to Current time with menu Help > Preferences > General >Presets. The above six fields (+ the calculated Debit Note) are mandatory for completing the transaction. Most of these fields are pre-filled based on the selected security. The following fields are either calculated or optional.
Gross Value : This is the result of multiplying Shares by Quote. If you later change the Gross Value, the Quote Price will be adjusted accordingly to maintain the equation Shares * Quote.
Fees and Taxes : A purchase transaction typically incurs fees and taxes. These may be in the currency of the security and/or deposit account.
Debit Note : This is the amount you need to pay as a result of this buying transaction. It is calculated as Shares * Quote + Fees + Taxes. Other terms for this are Value or Net Value.
Note : You can add a textual note to each transaction.
The typical flow for entering this information is likely to be Shares * Quote (price) >> Gross Value + Fees + Taxes >> Debit Note. There are a few nuances if you make changes afterward (see Figure 3).
Figure 2. Calculation flow between Shares and Debit Note.
Clicking the \"Save\" button will update the portfolio accordingly. If you select \"Save & New,\" it will not only update the portfolio but also prompt a new buy/sell dialog box for further transactions.
"},{"location":"reference/transaction/buy-sell/#two-currencies","title":"Two currencies","text":"Sometimes, the currency of the security may differ from the currency of the deposit account being used. In such cases, an exchange rate is automatically generated for the pre-filled date. This exchange rate is sourced daily from the ECB (European Central Bank) and does not consider the time of day. It's important to note that altering the date afterward will also result in a change in the exchange rate, regardless of whether the exchange rate was retrieved automatically or manually entered.
Figure 3. Buy and Sell transaction with two currencies.
It's important to note that the Quote price and the (first) Gross Amount are always expressed in the currency of the traded security (for example, EUR in Figure 2). On the other hand, the debit note is always expressed in the currency of the deposit (as it represents the actual payment). Fees and taxes, however, can be entered in either the currency of the security (on the left side) or the currency of the deposit account (on the right side), or even in both currencies simultaneously.
"},{"location":"reference/transaction/delivery/","title":"Delivery (Inbound - Outbound)","text":"A delivery involves the addition or removal of securities from a securities account, without requiring a deposit transaction. Drawing a comparison between Inbound and Outbound deliveries and Deposit and Withdrawal (removal) transactions can provide clarity.
Both types of transactions involve the transfer of assets (money), but they impact different types of accounts. Deposit and withdrawal transactions only affect cash accounts. When a deposit is made, the cash account increases, and conversely, it decreases when a withdrawal is made. Similarly, Inbound and Outbound deliveries involve the addition or removal of securities from a securities account. In both cases, whether it's cash or securities, assets are either added to or withdrawn from an account.
Delivery transactions can be particularly useful in the following scenarios:
Portfolio Reconstruction: You're trying to reconstruct a portfolio based on historical data but lack specific transaction details such as prices, fees, or even dates.
Inheritance and gifts: If you inherit securities or receive them as a gift, you may not have all the historic details and probably only has info about the current market price. A delivery at the current date and price could be a solution.
Currency Considerations: If the security is in a currency for which no cash account exists in the portfolio, a delivery transaction can be used to add the security to the portfolio.
Corporate Actions: Certain corporate actions like stock splits, mergers, or acquisitions can sometimes be more easily implemented with deliveries vs buy/sell.
Figure 1. Delivery (Inbound) and Delivery (Outbound) transaction - one currency.
"},{"location":"reference/transaction/delivery/#one-currency","title":"One currency","text":"Each security account is paired with a corresponding cash account, which is automatically added upon creation. Since security-account-1 is linked to a cash account denominated in EUR, EUR is suggested as the default currency in Figure 1. The currency designation in the box (EUR) can be modified; the text to the right provides a description of the currency (Euro).
When the chosen currency for the transaction matches the currency of the security (share-1), no conversion is necessary. All other fields, such as date, shares, quote, etc., remain identical to those in the buy-sell transaction.
"},{"location":"reference/transaction/delivery/#two-currencies","title":"Two currencies","text":"The transaction currency can be changed by choosing another security or security account. However, it's also possible to change the transaction currency directly with a given security and/or security account. To change the currency of the transaction, you can either:
An exchange rate from the ECB will be suggested. However, it's worth noting that fees and taxes are only applicable in the currency of the security, which is different from the setup in the buy-sell transaction.
Important
As depicted in Figure 2, you have the flexibility to select any currency from the list of available currencies for conversion (more than 50 options). There's no requirement for a corresponding cash account in that currency. For instance, in Figure 2, the Chinese yuan is chosen, despite the absence of a cash account in CNY. Nor will a deposit account in that currency be created. It's important to remember that with a delivery transaction, a security seems to appear or disappear \"magically\".
Figure 2. Delivery (Inbound) and Delivery (Outbound) transaction - two currencies.
"},{"location":"reference/transaction/deposit-removal/","title":"Deposit - Removal (withdrawal)","text":"A deposit is the process of adding funds to a deposit account, while a removal (withdrawal) is the process of removing funds from an account. A deposit account is sometimes also called a cash account.
Figure 1. Example of a deposit (in EUR) and removal (withdrawal) in USD.
Figure 1 illustrates a deposit of 15 EUR and a withdrawal of 14 USD. Although the deposit increases (debits) your account balance, it is termed a Credit note because the funds originate from a third party, whose account will be reduced (credited). This resembles a scenario such as returning goods, where you receive a credit note from the company.
The currency of the transaction is determined by the associated cash account. While adding the currency to the names of the deposit accounts may seem redundant, it can be helpful for quick identification when selecting an account from a drop-down menu. Naming them deposit-account-1, deposit-account-2 will force you to remember that account-1 is for EUR and account-2 is for USD.
Implicit deposits or withdrawals can also occur through other transactions, such as a stock purchase, which automatically triggers a withdrawal of the equivalent value from a cash account.
A common mistake for beginners is to record a buy transaction without first ensuring that the necessary deposits are made. This can lead to a negative balance in the deposit account, which affects the market value of the portfolio at the end of the reporting period and consequently impacts the portfolio's performance. This effect is of course not visible in the performance of an individual security or trade.
It is not possible to attach an interest rate to a deposit account as is typically done with banks. As a result, funds placed into a deposit account maintain their exact value until the end of the reporting period (MVE). As a result, deposits and withdrawals on their own have no effect on the portfolio's performance. Assume a portfolio Market Value (MVB) of 100 EUR at the beginning of the reporting period and only one deposit of 50 EUR at the exact mid of the 1 year period (see Concepts > Performance for more info about the calculation).
r = [150/(100 + 50)] - 1 = 0%. 150 = 100 x (1 + IRR)^1 + 50 x (1 + IRR)^1/2 = 0%.To assign an interest to a deposit account, you can use the menu Transaction > Interest.
A dividend is a distribution of profits by a corporation to its shareholders. When the distribution is made in cash, you should use this transaction type. For a choice or stock dividend, refer to Handling choice dividends in the how-to section.
"},{"location":"reference/transaction/dividend/#registering-a-dividend","title":"Registering a dividend","text":"With the Transaction > Dividend menu, you can record the dividend payment in your portfolio. You can also utilize the context menu by right-clicking. If a security was selected, the security field will be pre-filled for your convenience.
Figure 1. Dividend dialog box for same and different currency payments.
Invert button to change the conversion direction, for example, from EUR to USD or vice versa. The gross value in the foreign currency is calculated, and additional fields for fees and taxes are included.The directly visible effect of a dividend registration is the increase in balance of the designated deposit account. Take the following very simple project. Ten pieces of share-1 are purchased on January 1th, 2024 for 10 EUR/share. The reporting period runs to April 1, 2024 at which time share-1 quote has increased to 11 EUR/share.
The balance of the deposit account is zero EUR. The portfolio TTWROR = 10% and IRR = 46.56%. An in-depth explanation of the performance calculation in PP is given in Concepts > Performance.
A dividend is paid on March 1, 2024 at 5 EUR/share. The fees and taxes were each 1 EUR. There are 31 days remaining in the reporting period. At that moment, the balance of the deposit account is increased with (10 x 0.5) - 1 - 1 = 3 EUR. Performance starts to differ between portfolio, security or (open) trade level.
there are two cashflows: CF1 = 100 EUR at 2024-01-01 and CF2 = 3 EUR at 2024-03-01.
Portfolio Security Trade TTWROR IRR TTWROR IRR IRR Without dividend 10% 46.56% 10% 46.56% 46.56% Dividend with fees & taxes (1 + 1 EUR) 13% 63.27% 14% 69.14% 46.56% Dividend with fees (1 EUR) 14% 69.14% 14% 69.14% 46.56% Dividend with taxes (1 EUR) 14% 69.14% 15% 75.17% 46.56%"},{"location":"reference/transaction/fees-taxes/","title":"Fees - Fees refund","text":"Fees and taxes are typically reconciled at the time of purchasing or selling securities. However, there are instances when it may be necessary to record them at a different time. The dialog boxes in Figure 1 demonstrate that the same input data is required: the name of the security, the name of the deposit account, the transaction date, and the amount (debit or credit note).
Figure 1. Fees, Fees Refund, Taxes, and Tax Refund transactions.
You can choose for a deposit account with a currency different from that of the security account. An additional input box for the exchange currency will be displayed (refer to Figure 2).
Figure 2. Using different currencies for securities and deposit account.
"},{"location":"reference/transaction/interest/","title":"Interest - Interest Charge","text":"Interest is the compensation received for lending money, such as depositing funds into a cash account. It reflects a traditional bank arrangement where you may earn monthly or yearly interest on the funds held in the account. The transaction is initiated by the credit note from the bank. Taxes can be withheld from the interest payment. Conversely, an interest charge is a fee incurred for borrowing money. When your (physical) cash account becomes negative (indicating borrowing), you pay a fee, which constitutes a debit operation for the bank.
Figure 1. Interest and Interest Charge transaction.
The result of the interest and interest charge transaction is an increase or decrease of the balance of the selected cash account (see Figure 2).
Figure 2. Result of interest and interest charge transaction on balance.
There could also be an effect on the performance of the portfolio. The net result on both interest transactions of Figure 1 is an earning of 3 EUR. For a reporting period of 1 year (2024) and based on the data from Figure 2, this gives:
r = 603 / 600 = 0.50%603 = 600 x (1 + IRR)^(305/365) for IRR = 0.60%Please note that the 600 EUR deposit is considered by PP as a (performance neutral) cash inflow but the interest and interest charge transactions are not. They only affect the balance of the deposit account and therefore also the MVE of the portfolio.
"},{"location":"reference/transaction/transfer/","title":"Transfer","text":"The Security Transfer and Transfer between Accounts menu options are only visible when there is more than one security account and/or deposit account present.
You can transfer money between deposit accounts of the same currency or different currencies. In Figure 1, for example, 100 EUR is transferred from deposit-account-1 (EUR) to deposit-account-2 (USD). Given the exchange rate of 1.0696 EUR/USD, this will result in a deposit of 106.96 USD in the latter account.
The exchange rate is automatically retrieved from the ECB for the specified date, but it can be manually overridden if necessary.
Figure 1. Transfer between EUR- and USD-deposit account.
"},{"location":"reference/transaction/transfer/#security-transfer","title":"Security Transfer","text":"As the name suggests, this transaction involves transferring a specified number of shares from one security account to another. It is only accessible in the menu when the portfolio includes more than one security account. The topic Reference > View > Accounts > Securities Accounts summarizes some arguments for portfolios with only one security account or multiple accounts.
There are various scenarios where security transfers might be necessary. For instance, if you have multiple brokers each with their respective securities accounts, you might need to transfer a security between them, mirroring real-life scenarios where you move a security from one broker to another.
Another common scenario involves making provisions for the future, such as reserving some of your stocks for your children. While keeping the stocks in your portfolio, you may transfer a portion from the parent account to a child account. This segregation ensures that selling stocks from the parent account doesn't impact the performance of the child account, enabling separate performance tracking.
Figure 2. Security transfer dialog box.
With three drop-down boxes, you can select the security (share-1), as well as the source (security-account-1)and target (security-account-2) security account; see Figure 2. Several checks are conducted; for instance, you cannot transfer a security that is unavailable or insufficiently available in the source account. You also need to provide the date of the transfer, the number of shares, and the quote price.
Although it's technically one transaction, behind the scenes, PP creates two \"virtual\" transactions (refer to Figure 3; information pane). The security transfer is divided into a Transfer (Outbound) of 3 shares from security-account-1, followed by a Transfer (Inbound) into security-account-2. However, both transactions are considered as a single entity. Editing one of them will trigger the Security Transfer dialog. Deleting one transaction will also remove the other.
Figure 3. Result of the Security Transfer transaction.
A consequence of the Security Transfer transaction is the creation of two open trades, as depicted in Figure 4. The second trade covers the remaining 7 shares in security-account-1, while the first trade comprises the four transferred shares in security-account-2. Both trades are recorded as starting from the date of the original security purchase. While it could be argued that the second trade should start from the date of the transfer, this is not the case. Additionally, both trades share the same buying price, although an argument could be made to use the quote price of the transfer instead. It should be noted that the date and quote price entered with the Security Transfer do not appear to be utilized in this process.
Figure 4. Resulting trades from the Security Transfer transaction.
"},{"location":"reference/transaction/transfer/#setting-the-quote-price","title":"Setting the quote price","text":"Why is a quote price required? What price should you enter: the purchase price, the historical price at the transfer date, zero? Why can't you just transfer the shares from one account to another? The short answer is performance tracking.
Considering the scenario from above, transferring 3 shares (see figure 2). The stock is purchased at 10 EUR per share on Jan 1, 2023. The historical price at the time of transfer was 12 EUR/share, although you transferred it at 10 EUR/share (see Figure 3). Today (2024-01-01), the price has risen to 15 EUR per share. What is the performance of both security accounts for the reporting period 2023-01-01 until 2024-01-01? Remember, the reporting period spans from the end of the first day (e.g. 2023-01-01) to the end of the last day.
Figure 5. Absolute performance and IRR of source and target accounts (quote price transfer = 10 EUR).
The formula for absolute performance is: MVE - MVB + CFout - CFin, where MVE = Market Value at the End (of the reporting period), MVB = Market Value at the Beginning, CFout = cash flows out of the account, and CFin = cash flows into the account. The absolute performance of an account is the difference between the beginning and end value of that account, but corrected for the in- and outflows.
If the quote price is set to the purchase price (10 EUR):
Absolute Performance
MVE (7 x 15) - MVB (10 x 10) + CFout (3 x 10) - CFin (0) = 35 EUR.MVE (3 x 15) - MVB (0) + CFout (0) - CFin (3 x 10) = 15 EURIRR [Equation]
(7 x 15 EUR) = (10 x 10 EUR) x (1+46%)^(365/365) - (3 x 10) x (1 + 46%)^(306/365)(7 x 15 EUR) = (0 x 10 EUR) x (1+62%)^(365/365) + (3 x 10) x (1 + 62%)^(306/365). The transfer is executed on March 1, 2023, with 306 remaining days until MVE.If the quote price is set to the historical price at the moment (12 EUR):
(7 x 15) - (10 x 10) + (3 x 12) - 0 = 41 EUR.(3 x 15) - 0 + 0 - (3 x 12) = 9 EUR.If the quote price is set to zero (which is actually not possible in PP; choose 0.1 for testing):
(7 x 15) - (10 x 10) + (3 x 0) - 0 = 5 EUR.(3 x 15) - 0 + 0 - (3 x 0) = 45 EUR.As can be seen, the absolute performance varies a lot: from positive +41 EUR to 5 EUR for the source account. The bad performance is, of course, very understandable. Transferring 3 shares out of the source account for nothing will severely impact the performance.
The performance of the portfolio should be the sum of the account performances, which in all three cases is equal to 40 EUR. The MVE of the portfolio is (7 + 3) * 14 EUR = 140 EUR. The MVB = 10 * 10 EUR = 100 EUR. The absolute performance of the portfolio is thus indeed 40 EUR.
"},{"location":"reference/view/options/","title":"Options","text":"The Options submenu includes various submenus for customizing the program's startup behavior and the visibility of elements on the screen.
Figure 1. View > Options submenu
Always start with 'All transactions' in this part. Choosing this option ensures that this view is always displayed in the top panel on start-up.An account is a collection of transactions. These transactions could include buy and sell transactions of securities (shares, etc.) for a Securities account or withdrawals and deposits of money for a Deposit account. Each account has a default currency attached. As part of the installation process, you have already created at least one Security account and one Deposit account.
Portfolio Performance (PP) has two main types of accounts: Deposit and Securities accounts. They are described quite well in the Guide on Getting Started by Thomas (Contributor); you will need to scroll quite far down. Other related terms are Reference account, Offset account, and Cash account.
Figure 1. Example of Deposit Account.
Figure 2. Example of Security Account.
"},{"location":"reference/view/accounts/#related-terms","title":"Related Terms","text":""},{"location":"reference/view/accounts/#cash-account","title":"Cash Account","text":"The term Cash Account is somewhat inconsistently used. In Figure 1 (main pane; first column) it refers to a Deposit Account; which is in line with the name Cash Account. In Figure 2 (information pane bottom) the Cash Accountcolumn refers to a Security Account (broker-1).
A security account is always associated with a deposit account. This is the deposit account that will be used (if no other is explicitly assigned) for any buy or sell transaction on that security account. This deposit account is called the Reference Account. In Figure 2, the Broker-1 security account has a reference (deposit)account named Broker-1 (EUR).
The Reference account of a Security account must be set when creating this account (see Figure 2 of Creating a Portfolio). You can always change the Reference account by selecting Accounts > Securities Accounts from the left sidebar. Double-click on the relevant Reference account currency and choose a new one from the drop-down menu (see Figure 2; second column).
The offset or counter account, also known as \"Gegenkonto\" in German, is an essential component when dealing with securities transactions. It acts as the counterpart to the securities account. In other words, for every transaction that occurs in the securities account, an equal and opposite entry is recorded in the offset account.
When you perform actions like buying or selling securities within your securities account, these transactions are balanced by corresponding entries in the offset account. For example, when you buy securities, the purchased securities are added to the securities account, and an equivalent amount of cash is withdrawn from the offset account. This ensures that the overall balance of your accounts remains zero or balanced.
However, also the term \"Offset account\" is a relative concept. Compare the bottom panels of Figure 1 and 2. For a Deposit Account(Figure 1), it refers to a Security Account and vice versa.
The All Transactions view displays a table with all the transactions of the portfolio in the main pane, sorted by the transaction's creation time in the portfolio (see Figure 1). The default view presents the columns Date, Type, Security, Shares, Quote, Amount, Fees, Taxes, Net Transaction Value, Cash Account, Offset Account, Note, and Source (see the Glossary for a definition of these terms).
Figure 1. The All Transactions View.
Although it's less useful than in the All Securities view, the information pane at the bottom (not shown in Figure 1) can provide additional details about the security attached to the selected transaction in the main pane.
Figure 2. The Show or Hide columns button (gear).
Click the column heading to sort the table in ascending (\u2227) or descending (\u2228) order based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column or double click to best fit. You can rename or hide a column with the context menu (right-click on the column header). Adding, deleting or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). The default columns are shown in Figure 1; they are also checked in Figure 2. Figure 2 gives a list of all available columns.
As can be seen, all available columns are displayed except ISIN, Symbol, and \u00b4WKN\u00b4, which are typically security related terms (see the Glossary).
In a typical portfolio, the transaction table can contain hundreds of rows. However, you can use the search function to narrow down the displayed rows. This function scans all cells in every column, and if the cell contains the search value, the corresponding transaction (row) will be displayed. For example, entering share-3in the Search box of Figure 1, will narrow the list down to the first row. Entering share (or for that matter sh is enough) will display all transactions with the security column (in fact every column) containing the word share. The function searches through all available columns, whether they are displayed or not. You can not use wildcards such as * or ?, nor limit the search function to one column only.
Figure 3. The Filter Securities button.
Another method to limit the number of transactions is by using the \"Filter Securities\" button located in the top right corner of the interface. Figure 3 showcases all potential options available. By default, transactions from All transaction types of the Entire portfolio are displayed in the table.
There are two major Filter groups: Filter data by transaction type versus Filter data by portfolio and reference account. The first group selects transactions such as all Buys or Sells. The second group selects transactions from a specific security account. The various options are somewhat self-explanatory. The translation Transactions with investment vehicle for the German original Buchungen mit Wertpapier is somewhat unfortunate. A more appropriate term would be Transactions with securities.
The filter operates on an \"either-or\" basis. Choosing one option from a group will replace any previous selection in that group. For example, you can choose \"Buys and Sells\" or \"Buys\" only, or \"Sells\" only.
The Filter command and the search function work together and complement each other. For instance, searching for \"USD\" and filtering for \"Deposits\" will result in displaying only the second row of Figure 1: a USD deposit.
There are some limitations. For example, you can only filter on reference account, not on any cash account such as broker-A (USD). However, with the New option, you can create a filter for whatever (cash) account. Please note, that it seems also not possible to filter for Transactions without taxes or fees.
With the Manageoption, you can rename a (new) custom filter, add elements to it or delete the filter. The Remove entries option will reset the filter to the entire portfolio in the second group.
Figure 4. Export selected rows.
With the Export button located at the top right, you have the option to save the displayed transaction table as a CSV or JSON file. Only the columns and rows currently displayed, including the header row, will be saved.
If you made a selection in the table, the Export button will provide you with four options instead of two (see Figure 4), including the possibility to export only the selected transactions.
Note
The File > Export will always export ALL transactions. If you are only interested in a specific selection, use this option.
"},{"location":"reference/view/accounts/deposit-account/","title":"Deposit accounts","text":"A deposit account serves as a central hub for managing cash flow within the portfolio, allowing users to allocate funds for investment activities and track incoming and outgoing cash transactions. One can visualize it as a list, akin to a shopping list, where transactions such as withdrawals and deposits of digital money are recorded. There can be many deposit accounts within one portfolio, for example, for different currencies that are traded. As part of the installation process, at least one security account and one deposit account have already been created.
Figure 1. Example of Deposit Accounts.
"},{"location":"reference/view/accounts/deposit-account/#main-pane","title":"Main pane","text":"In Figure 1 (main pane), there are four deposit accounts. It may seem unnecessary to include the currency in the name of an account, as the currency is already specified for each deposit account in the third column of Figure 1. However, including the currency in the name of the deposit account can be helpful in situations where you need to select a deposit account from a list, such as when buying a security. In these cases, having the currency clearly displayed in the name of the account can help you quickly and accurately choose the correct one.
You can use different names for accounts depending on your preferences and needs. For example, if you wish to keep your dividends and taxes separate, you could create two accounts named Dividends\" and Taxes.
Figure 2. Add account.
To create a new deposit account, click on the green + icon located at the top right (refer to Figure 2). Then, select the option Add account. Since you're in the Deposit Account view, a new deposit account named No Name will be created with the default currency of the portfolio. To rename the account, simply double-click on the Name field and enter the desired name. Remember also to change the currency if needed by double-clicking on the currency field (e.g., EUR) and selecting another currency from the dropdown menu. While navigating the currency list, you can use the first letter of the desired currency for faster navigation. Initially, the balance of the newly created deposit account will be zero.
A deposit account can be negative. However, good practice requires that you first add a deposit of a large enough sum to cover the subsequent buy transactions, just as you would do with a real broker.
To deactivate an account, right-click on the account and choose Deactivate account from the context menu. The account name will appear greyed out and will no longer be visible in the list of deposit accounts when making a deposit transaction. With the Filter icon (top right), you can hide inactive accounts.
You can delete a deposit account using the context menu. However, it is important to note that you can only delete an account if there are no transactions associated with it.
If you want to delete an account that has transactions, you will need to first delete the transactions that are linked to that account. Once all transactions have been removed, you can then delete the account itself.
Using the Show or Hide columns option (accessible via the gear icon at the top right), you can customize the view by hiding or adding columns. The available columns for display include: Cash account, Balance, Currency, Note, and Attributes. See also How-to > User Interface for more detailed information about handling the table.
The information pane at the bottom displays the transactions of the selected deposit account in the main pane. It consists of two tabs: Transactions and Account balance chart. The Transactions tab displays fields such as date, type, amount, and balance of each transaction. The Account Balance chart provides a graphical representation of the account balance. Due to fewer data points compared to a historical prices graph, the chart may appear more blocked. Figure 3 illustrates the balance of the Broker-1 (EUR) account, where the early spikes are the result from deposits followed by purchases on the next day.
Figure 3. Example of the Account Balance Chart.
The context menu, accessed by right-clicking on the chart, offers the same options as many other charts; for example, you can refer to the chart menu of the All Securities info pane for more information. There are no other configuration settings.
If you notice any discrepancies in a deposit account between the calculated balance of PP and the actual balance of the bank/broker, you can use the context menu to troubleshoot the issue. To do so, right-click on the account in the main pane and select \"Troubleshoot Balance Discrepancy\" from the menu.
This will open a dialog box displaying the calculated monthly balances for the selected deposit account. In the \"Expected balance\" column, you can enter the balance that you expect according to your bank account statement. Portfolio Performance (PP) will then use the calculated difference to try to identify any transactions that may be causing the discrepancy. For example, PP may find transactions that were made to a different account or are dated in the future.
"},{"location":"reference/view/accounts/investment-plans/","title":"Investment Plans","text":"An investment plan is an automated method to facilitate periodic transactions, such as deposits, withdrawals, interest payments, or purchases. It allows you to systematically invest or withdraw funds at regular intervals with minimal manual input.
"},{"location":"reference/view/accounts/investment-plans/#types-of-investment-plans","title":"Types of investment plans","text":"Figure 1. Four investment plans in the main pane and generated transactions of plan-3 in the information pane.
There are four main types of investment plans: deposit, removal (withdrawal), Interest and Security Purchase/Delivery (as illustrated in Figure\u00a01). A deposit and interest plan will increase the balance of a cash account, while a removal plan will decrease it. On the other hand, a Security Purchase/Delivery plan involves both decreasing your deposit account (to fund the purchase of securities) and increasing your security account (as you acquire new securities). To create a new plan, simply click the 'New Plan' button, located at the top right corner of the interface (as shown in Figure 1).
"},{"location":"reference/view/accounts/investment-plans/#deposit-investment-plan","title":"Deposit Investment Plan","text":"Figure 2. Deposit Investment Plan.
With a deposit investment plan, you can regularly deposit a specified amount of money into a designated cash account. To set up a deposit plan, you will need to provide a descriptive name (such as plan-1), the name of the cash account, the amount of money to be deposited, the starting date of the plan, and the frequency (interval) of the deposits (ranging from every month to every 12 months). The starting date could also be in the past or the future.
Once you click the Save button, the information will be added to the main pane of the investment plans (as shown in Figure 1), but the plan will not be executed immediately. No transactions will be performed at this stage. However, if you have checked the Create transactions automatically when opening the file, the plan will be executed automatically the next time you open the file.
Alternatively, you can click the 'Save & New' button to add the plan to the list and reopen the dialog box. This allows you to create multiple deposit plans in quick succession.
"},{"location":"reference/view/accounts/investment-plans/#removal-investment-plan","title":"Removal Investment Plan","text":"Figure 3. Removal Investment Plan.
With a removal investment plan, you can periodically withdraw a specified amount of money from a designated cash account. The process of setting up a withdrawal plan is similar to that of a deposit plan. You will need to provide a descriptive name for the plan, the name of the cash account to be used, the amount of money to be withdrawn, the starting date of the plan, and the frequency of the withdrawals. The same fields that were used to create a deposit plan will be required for a withdrawal plan.
"},{"location":"reference/view/accounts/investment-plans/#security-purchasedelivery-investment-plan","title":"Security Purchase/Delivery Investment Plan","text":"Figure 4. Security Purchase/Delivery Investment Plan.
With a Security Purchase/Delivery investment plan, you can regularly acquire a specified security using funds from a designated cash account. As shown in Figure 4, you will need to provide a descriptive name for the plan (such as plan-3), the name of the security account and the specific security to be acquired, the name of the cash account from which the funds will be withdrawn, the starting date of the plan, the frequency of the purchases, the amount to be invested each time, and any associated fees.
It's important to note the distinction between purchase and delivery when selecting the cash account. If you want to acquire the security through delivery, you should use the (Inbound Delivery) option. On the other hand, if you want to purchase the security, you should use the name of an existing cash account from which the funds will be withdrawn.
The following fields/columns are displayed in the main pane (see Figure 1): Name, Security, Securities Account, Cash Account, Start Date, Last Execution, Next Execution, Interval, Auto-Generate, Amount, and Fees. Most fields are self-explanatory. The Auto-Generate field is automatically set when the Create transactions automatically when opening the file option is selected during the initial creation of the plan. Two additional fields, Notes and Attributes, can be added using the Show or Hide button (gear symbol at the top right). For information on how to manipulate individual columns, please refer to the All Transactions section in the manual.
Figure 5. Interest Plan.
The Interest Plan bears similarity to the Deposit Plan as it also generates a deposit in the specified Cash Account. Moreover, it allows for tax deductions. The transactions under this plan are classified as Interest, ensuring they are not included in cash flows when calculating performance. (see System Overview section)
The main pane of Figure 1 displays a comprehensive list of all investment plans in the portfolio. By using the context menu, which can be accessed by right-clicking a plan, you have the ability to generate transactions, modify the selected investment plan, or remove it entirely.
"},{"location":"reference/view/accounts/investment-plans/#generate-transactions","title":"Generate Transactions","text":"Figure 6. Message box at opening of portfolio.
Create transactions automatically when opening the file was selected during the creation of the plan, the transactions will be automatically generated the next time the file is opened. A message box, similar to the one shown in Figure 6, will be displayed upon opening the portfolio.Generate Transactions command will instantly create all feasible transactions, subject to the specified date constraints. Last Execution column will display the most recent date on which the transaction-generating algorithm was executed. The Next Execution column will indicate the earliest future date on which a transaction is scheduled to occur, based on the frequency and last execution date.Next Execution date, the Generate Transactions command will have no effect.The information pane of the Investment Plans view provides a comprehensive list of all the transactions that have been automatically generated from the selected investment plan in the main pane. It's important to note that this list does not include any manually created purchase transactions on this security. The information pane is specifically designed to display only the generated transactions that result from the implementation of an investment plan, allowing for easy monitoring and analysis of the plan's performance.
You can edit or delete some or all of the generated transactions without affecting the plan itself. For instance, a generated purchase will probably not reflect the actual buying price, as it is based on the closing quote of the day. You may need to modify the details, e.g. the purchase price of a generated transaction after it has been created.
If the most recently generated transaction is deleted, the Last Execution field in the main pane will also be cleared.
The chart menu in the Investment Plans view is identical to the chart menu in the All Securities menu. The same applies to the Historical Prices.
"},{"location":"reference/view/accounts/security-account/","title":"Security Accounts","text":"The Securities Accounts view provides a dual-pane view of all security accounts within the portfolio. The main pane features a list of all securities accounts, while the information pane presents details about the selected account in the upper panel.
Figure 1. Example of Securities Accounts.
"},{"location":"reference/view/accounts/security-account/#main-pane","title":"Main pane","text":"A security account will hold your securities and will be used for trading. Use the data tools icon to add a new account. For each account, the total market value of its assets is displayed as Volume of security deposits. A securities account is most often named after the broker or bank that you use for buying or selling. But other variants are possible. For example, you could collect all your bitcoin investments into a separate account crypto or you can differentiate between your account and that of your partner.
It is worth noting that, although the portfolio has four deposit accounts (see figure 1 in the Deposit Accounts section), only one of them, named Deposit Account, is set as the reference account. This reference account is used for handling trades when no other account is explicitly assigned. The information pane (bottom panel) shows the Statement of Assets view for the selected security account.
The information pane features four tabs: Statement of Assets, Transactions, Chart, and Holdings.
The Statement of Assets tab, depicted in Figure 1, is selected by default. It includes details such as the number of shares, the name and ISIN of the asset, the latest price or Quote, the purchase value, the total market value (computed as shares multiplied by Quote), and the percentage of the asset in the total portfolio. It is the same table as in the menu View > Reports > Statement of Assets but limited to the selected security account.
With the Show or hide columns icon, you can add numerous other fields such as purchase price, dividends, and many more. These fields are described in full detail in View > Reports > Statement of Assets. The Export Data as CSV icon allows you to save the displayed table as a CSV-file.
This section presents a table that lists all transactions related to the chosen Securities Account. The table offers in-depth information about each transaction, such as the date, transaction type, security involved, quantity, price, fees, and other pertinent data. See View > Accounts > All Transactions for more information on the available fields and how to customize the table with the data tools.
"},{"location":"reference/view/accounts/security-account/#chart","title":"Chart","text":"The Chart tab presents a specific line graph, displaying the market value over time of the selected account (e.g. Brokerage Account in Figure 2), the invested capital since the first transaction in this securities account, and the delta (difference) between those two.
Figure 2. Chart from Securities Account (information pane).
Clicking on any point in the chart will reveal the actual data of all three time series. With the data tool, you can also add the Taxes (Accumulated) and Fees (Accumulated) time series to the chart. Please refer to the section on the User Interface for more guidance on customizing the chart.
The Holdings chart from the Securities Account doesn't have any data tools. It's very similar to the portfolio holding chart; see View > Reports > Statement of Assets > Holdings. Clicking any part of the chart will reveal some additional information.
Figure 3. Holdings Chart from Securities Account (information pane). {class=pp-figure}c
"},{"location":"reference/view/accounts/security-account/#one-or-more-security-accounts","title":"One or more security accounts?","text":"Should you create only one security account to hold all your transactions?
Historical exchange rates and a Currency Converter can be found under the menu View > General Data. More than 5O currency combinations such as EUR/AUD (see Figure 1) are provided. These exchange rates are retrieved from The European Central Bank (ECB) and go back until the year 1999 when the EUR was introduced on the financial markets. They are in fact reference rates and will probably differ slightly from the real transaction rates that your broker or bank will use. Only a chart can be displayed; no numerical data. The context menu of the chart is described elsewhere.
Figure 1. Exchange Rates and Currency Converter.
Note
You can download a CSV file with all exchange rates going back to 1999 at Euro foreign exchange reference rates webpage; scroll down to time series.
Figure 2. Currency Converter.
The second tab in Figure 1 displays the Currency Converter (see figure 2). With this tool you can convert any amount from the base currency to a counter (quote or term) currency for a specific date. In the foreign exchange (forex) market, currency pairs are commonly depicted as XXX/YYY where the XXX is the base currency. One unit of the base currency XXX is worth YYY units of the counter currency. For example, on March 20, 2024 the exchange rate EUR/USD = 1.0844 means that 1 EUR is worth 1.0844 USD.
Since EUR/USD = 1.0844, it follows that USD/EUR = 0.9222. Which quotation would you prefer? This depends a bit on your domestic currency (the one you use every day) and your preference for multiplication or division.
As a result, there are two types of quotation: direct (or price) quotation versus indirect (or quantity) quotation. By default, PP assumes the latter one, but you can change the quotation type with the menu Help > Preferences > Presentation menu.
You can display both types by clicking the Switch currencies button located beneath the date field in figure 2.
Settings is a submenu under View > General Data. Five sub-panels or tabs are available.
Most financial websites offer the option to search for a specific security. For instance, by clicking on the search box at https://www.ariva.de/, you can locate a security based on its name, WKN, or ISIN.
Figure 1. Defining additional attributes.
The bookmarks defined in the settings panel serve to streamline this process. You can then Open in Browser any security by right-clicking on that security or transaction. The required attribute for that website will be automatically embedded in the URL, guiding you to the appropriate webpage on the financial site.
The list contains several examples. On the forum, many more are suggested along with some workarounds.
Using the New Bookmark icon (top right), you can add custom bookmarks for your personal situation. A line named \"New Bookmark\" is added to the list with the URL http://example.net/{tickerSymbol}?isin={isin}&wkn={wkn}&name={name} (see Figure 1, last line). Double click name or URL to change the value. You need to inspect the original website to figure out how to form a correct URL. For example, finance.yahoo.com requires a URL like https://finance.yahoo.com/quote/NVDA to retrieve the webpage of NVIDIA. Using the placeholder {tickerSymbol}, the URL will be dynamically populated with the appropriate symbol for the chosen security during runtime.
Figure 2. Context menu of the bookmarks page.
The available placeholders are listed in the context menu (accessible via right-click) on the bookmarks page under the \"Insert replacement\" option (see figure 2): {isin}, {name}, {wkn}, {tickersymbol}, and {tickersymbolprefix}. In the ticker format XXX.YY (for instance, DTE.DE), XXX corresponds to {tickersymbolprefix}, and xxx.YY represents {tickersymbol}. For some websites, you may need only the {tickersymbolprefix}.
With this context menu, you can manage the bookmark list.
All securties view is a better approach. -Move up: moves a bookmark one line up in the list; for example to sort the bookmarks in a particular order.New attributes or fields can be defined for Securities (see Figure 2), Deposit Accounts, Security Accounts, and Investment plans. Besides the attributes which are already defined in the Security Master data such as Name, ISIN, Quote Feed, ..., Figure 2 contains six additional attributes such as logo, Total Expense Ratio, ....
Figure 3. Defining additional attributes.
You can create new custom attributes for yourself with the New Attribute with field type icon (top right). Clicking on it will display a subpanel with the available data types (see Figure 2). For example, the existing \u00c0ctive attribute is probably of type Yes/no, while the name attribute should be of type Text.
These additional attributes can be made will be visible in any table view concerning securities and in the panel Additional Attributes of a Security. These attributes cannot be used in calculations, but you can sort the list with them.
"},{"location":"reference/view/general-data/settings/#attributes-deposit-accounts","title":"Attributes: Deposit Accounts","text":""},{"location":"reference/view/general-data/settings/#attributes-securities-accounts","title":"Attributes: Securities Accounts","text":""},{"location":"reference/view/general-data/settings/#attributes-investment-plans","title":"Attributes: Investment plans","text":""},{"location":"reference/view/reports/performance/","title":"Performance","text":"Key performance and risk indicators are summarized in a dashboard, along with a calculation widget. The dashboard can be accessed through the menu View > Reports > Performance or with the sidebar (see figure 1).
Figure 1. Dashboard with key performance and risk indicators and calculation widget.
Please note that the performance and risk indicators are always calculated for the entire portfolio and for a specific reporting period. By default, this is one year from today. You can change the period by selecting a different one or create a new one in the drop-down (top-right). In Figure 1, the reporting period is from Jun 12, 2020 till Jun 12, 2023. For the performance key indicators, the color green indicates a profit, while red signifies a loss.
The cumulative True Time-Weighted Rate of Return (TTWROR) is the geometric average of the daily returns within the reporting period. For each day within the reporting period, the daily return is calculated using Equation 1. The cumulative return is computed with Equation 2.
$$\\mathrm {r_{daily} = {\\frac{MVE + CF_{out}}{MVB + CF_{in}} - 1 {\\qquad \\text{(Eq 1)}}}}$$
and
$$\\mathrm {r_{cum} = [(1 + r_1) \\times (1 + r_2) \\times ... \\times (1 + r_n)] - 1 {\\qquad \\text{(Eq 2)}}}$$
where MVE = the market value of the asset at the end of day, MVB = the market value at the beginning of the day (or the end of the previous day). CFin and CFout represent the net incoming or outgoing cashflows for the day. When a stock pays a dividend, that's an outgoing cashflow from the stock's perspective. A deposit (for buying the stock) is a cash inflow, as is paying the associated fees.
An in-depth explanation of the TTWOR calculation is given Concepts > Performance > True Time-Weighted Rate of Return. A step-by-step calculation for a very simplified example can be found at View > Reports > Performance > Chart.
"},{"location":"reference/view/reports/performance/#internal-rate-of-return-irr","title":"Internal Rate of Return (IRR)","text":"The money-weighted rate of return or IRR of a reporting period is the annual interest rate that is necessary to bring the market value of the investment at the beginning of the period (MVB) and all subsequent cash flows to the market value (MVE) at the end of the reporting period. To generate the specified cash flows within the given time period, your portfolio must grow each year by a percentage equal to the IRR. The base formula for the IRR calculation is:
$$\\mathrm{MVE = MVB \\times (1 + IRR)^{\\frac{RD_1}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} \\qquad \\text{(Eq 3)}}$$
where n = the number of cash flows in the reporting period, $CF_t$ = cash flow at time t within the period, and $RD_t$ = the number of remaining days within the period. For MVB, the $RD_t$ equals the entire period, representing the period length in years. You can simplify the equation by treating the MVB as the initial cash flow. A cash flow is any amount of money that is added to or withdrawn from an investment. For an in-depth explanation, see Concepts > Performance > Money-Weighted Rate of Return.
"},{"location":"reference/view/reports/performance/#absolute-change","title":"Absolute Change","text":"The absolute Change is the difference between the market value of the portfolio at the end date of the reporting period (MVE) and the market value at the beginning (MVB).
$$\\mathrm{MVE - MVB\\qquad \\text{(Eq 4)}}$$
For example, in Figure 1 (calculation widget), the absolute change equals the Final Value (426.82 EUR) minus the Initial value (0 EUR).
"},{"location":"reference/view/reports/performance/#delta","title":"Delta","text":"The Delta value (for the reporting period) is equal to the Absolute Change (see above) minus the external cash flows that occurred in the period.
$$\\mathrm{(MVE - MVB) + \\sum_{t=1} ^{n}CF_t {\\qquad \\text{(Eq 5)}}}$$
For example, the Delta in Figure 1 is 120.82 EUR. This value represents the actual return of securities in the portfolio. The absolute change in the portfolio is partly caused by external cash inflows (306 EUR to buy the securities). This money comes from an external source and should be subtracted from the Absolute change. They are summarized as Performance neutral Transfers in the calculation panel.
"},{"location":"reference/view/reports/performance/#last-day","title":"Last Day","text":""},{"location":"reference/view/reports/performance/#last-day-true-time-weighted-rate-of-return","title":"Last Day: True Time-Weighted Rate of Return","text":"One would assume that the Last Day is the same as the ending day of the reporting period. Unfortunately, it is not. It is the previous trading day before 'today' as can be seen when hovering over the label. Figure 1 is created on December 8, 2023. The market value of the portfolio was at that time 459.31 EUR. The last trading day before this date is 2023-12-07 with a MV = 455.84 EUR. There are no cashflows on the last day.
The TTWOR for that day is given by Eq. 1 or (459.31 - 155.84)/455.84 = 0.76%.
Equation 3 can be used to calculate the Absolute Change of the last day. It's obvious that the value equals 3.47 EUR = 459.31 EUR - 155.84 EUR.
Risk refers to the possibility of losing some or all of the invested capital or not achieving the expected return from your investment. Several indicators are provided to measure the risk.
"},{"location":"reference/view/reports/performance/#maximum-drawdown","title":"Maximum Drawdown","text":"Maximum drawdown (MDD) refers to the largest peak-to-trough decline in the performance of a portfolio or investment over a specific period, typically expressed as a percentage. It measures the extent of loss incurred from the highest point to the lowest point before a new peak is reached.
With View > Reports > Performance > Chart you can create a graph of the cumulative performance of your portfolio, accounts, or specific securities. Figure 1 displays the portfolio performance for the reporting period 2020 - 2023.
Figure 2. Cumulative performance of portfolio with indication of Maximum Drawdown .
The largest drawdown occurs between August 18, 2021 and March 8, 2022. Cumulative performance dropped from 22.04% to - 4.12% (see Figure 2). The MDD for the reporting period of Jun 12, 2020 till June 12, 2023 is 21.44% (see Figure 1). Hovering with the mouse over the value (the label displays the reporting period) will reveal the dates.
"},{"location":"reference/view/reports/performance/#maximum-drawdown-duration","title":"Maximum Drawdown Duration","text":"The MDD Duration is the worst or longest amount of time an investment has been between peaks. This is 292 days or between August 18, 2021 and June 6, 2022. The longest recovery period (duration from a low to a peak) is 90 days or between March 8, 2022 and June 6, 2022.
"},{"location":"reference/view/reports/performance/#volatility","title":"Volatility","text":"Volatility in portfolio performance refers to the degree of variability in the returns of a portfolio over time. It is a measure of the risk or uncertainty associated with the portfolio's future performance. A portfolio with high volatility will have returns that fluctuate widely over time, while a portfolio with low volatility will have returns that are more consistent.
The volatility shown in Figure 2 is 31.33% (refer to Figure 1). It represents the standard deviation of daily returns during the reporting period. To be precise, it is calculated by taking the natural logarithm of (1 + daily return) and then multiplying it by the square root of the total number of days in the reporting period. Notably, weekends and holidays are excluded from this calculation. An efficient method to obtain all the daily returns is by exporting the return/volatility chart as a CSV file.
"},{"location":"reference/view/reports/performance/#semivariance","title":"Semivariance","text":"The Semivariance exclusively considers the negative fluctuations of an investment. The semivariance value is 22.63% (refer to Figure 1), with weekends and public holidays disregarded. Hovering over this value with the mouse provides additional information.
In instances where negative and positive fluctuations are balanced, the formula Volatility (v) = Semi-variance (s) x sqrt(2) applies. For a dataset evenly distributed as depicted in Figure 2, the semivariance would be calculated as follows: s = v / sqrt(2) = 31.33% / sqrt(2) = 22.15%.
Given that the actual semivariance is slightly lower than the estimated semivariance (22.15% < 22.63%), it suggests that the returns are not symmetrically distributed, and the negative returns slightly outnumber the positive ones.
"},{"location":"reference/view/reports/performance/#configuring-the-dashboard","title":"Configuring the dashboard","text":"By default, the Performance dashboard contains three columns: Key Indicators, Risk Indicators, and Calculation (see Figure 1). Each column can contain several configurable widgets: data blocks comprising a label and a numerical value or diagram; e.g. Absolute Change or a Performance chart. Right mouse click on an empty space in a column lets you manage the widgets, e.g. adding a widget. Right clicking the widget label lets you manage the specific widget; e.g. change the data series or reporting period. (see later).
Figure 3. Yearly Overview dashboard.
Widgets are a very powerful tool to customize the dashboard to your liking. A thorough introduction is given in a YouTube video by Finanzkoch (German spoken but English subtitles are possible). A list of very nice dashboards by fellow investors can be found at the forum.
Figure 4. Creating a new dashboard.
The best way to experiment is by creating a new (empty) dashboard (see Figure 3). Click on the icon New dashboard at the left of the reporting period. You can choose between a blank dashboard, key indicators (= the default dashboard), and Earnings (see Figure 4). To remove a dashboard from the menu, click the arrow next to the name and choose Delete. You can move the dashboard to the first in the list (bring to front), rename the dashboard, or make a duplicate of the selected dashboard.
A dashboard contains one or more columns; the dashboard of Figure 3 contains 6 columns. You cannot see the borders of the column. Delete a column by right-clicking in the area. You can add a new column with the configure dashboard gear icon (top right). If there is already at least one column, you can also right-click in a column area and choose New column on the left, New column on the right, or Duplicate column (see Figure 5). With Column width you can increase or decrease (step wise) the column width of the selected column. Of course, the width of the other columns is affected since the total width of the windows stays the same. With the Option Apply to All, you can set the reporting period and the data series for all widgets in the dashboard.
The New Widget option reveals a submenu featuring six categories of widgets (refer to Figure 5). Below is a description of each widget. Right-clicking on the widget label will reveal a context menu. Most widgets feature options such as Edit label, Delete, and Height. You can drag and drop widgets within and between columns. Press the CTRL key (Windows) to duplicate instead of moving.
Figure 5. New Widget menu with overview of all available widgets.
"},{"location":"reference/view/reports/performance/#common","title":"Common","text":"Current date: The text \"Current Date\", followed by the system date of the computer in the language and format, set in Help > Preferences > Presentation > Language.
Exchange rate: An exchange rate in the format XXX/YYY number. Right-click to choose the specific exchange rate, e.g. EUR/USD.
Trading activity: A graph depicting time (per year and per month) is plotted on the X-axis, while the count of trades is represented on the Y-axis. With the context menu, you can add or remove the Y-axis, change the reporting period (by default the period of the dashboard is taken), or change the trading type (by default buy, sell, delivery inbound, and delivery outbound), and the filter (by default the entire portfolio).
Securities: Limit price exceeded: You can set a limit price per security in the security master data (see how-to). If the current price (as of today; independent of the reporting period) of the security exceeds the limit price, the name of the security, the current price and the limit will be displayed, as well as displaying shares with dates only in the past or only in the future.
Securities: Date reached: As with limit price (see above), you can link a \"special\" date to a security as an additional attribute. This widget will exhibit the text Securities: Date reached (xxx), where xxx represents the count of securities for which today's date exceeds the date set for the security. Additionally, a list of share names and dates will be provided. This list can be sorted from the context menu.
Securities: Latest Price. This is a single line widget with the current price of a security; which can be chosen from the context menu. The label will mention the name of the selected security.
Website: A textbox containing the content of a website; specified by an URL in the context menu. Anchors are allowed; for example https://help.portfolio-performance.info/en/concepts/performance/#the-money-weighted-rate-of-return. The height of the widget can be increased with the context menu.
Security: Distance from ATH: The difference of the current price with the All Time High (ATH) price of the security, measured in %. The security should be specified with the context menu.
Vertical spacer: This widget produces an invisible rectangle that occupies space. It is used to visually separate widgets (vertically). Hovering over the widget with the mouse will reveal its label. With right-click, you can change its height.
All widgets, except the last three, are single line text widgets.
Total: The market Value of the asset at the end of the reporting period. The asset and the reporting period can be specified with the context menu.
Absolute change, Delta (for reporting period), Delta (since first transaction) : see above for definition of these terms.
Performance-neutral transfers: these transfers are explained in View > Reports > Performance > Calculation.
Invested Capital (for reporting period) and Invested Capital (since first transaction): The Invested capital in a portfolio of stocks refers to the total amount of money that has been invested in the portfolio.
Ratio: This widget computes the proportion between two assets; for instance, Share 1 / Entire Portfolio.
Statement of Assets - Chart: This widget produces a mini version of View > Reports > Statement of Assets > Chart. If multiple chart view are defined, they can be selected with the context menu.
Statement of Assets - Holdings: Pie chart which is a mini version of View > Reports > Statement of Assets > Holdings.
Taxonomies: Pie chart illustrating the proportional distribution of the taxonomy categories.
The first three widgets are single line text; representing the common performance indicators.
True Time-Weighted Rate of Return (cumulative), True Time-Weighted Rate of Return (annualized), and Internal Rate of Return (IRR) are the known single line performance indicators. The data series and reporting period can be selected in the context menu.
Performance Calculation: A fully collapsed table, similar to View > Reports > Performance > Calculation; first panel. The categories cannot be expanded.
Performance Chart: This widget produces a mini version of View > Reports > Performance > Chart. With the Aggregation context menu, one could set the level of detail (daily, weekly, monthly, quarterly, or yearly).
Monthly returns in a heat map: A heatmap is a graphical representation of data that uses color-coding to visualize the performance of different stocks in a portfolio. A heatmap typically consists of a table or matrix, with each cell representing the monthly performance of a selected asset. The color of each cell corresponds to the performance of that stock.
Yearly returns in a heatmap: Each cell in the heatmap represents one year.
Portfolio Tax Rate: The ratio of taxes / (realized and unrealized capital gains + earnings - fees).
Portfolio Fee Rate: The ratio of Fees / (realized and unrealized capital gains + earnings).
All five widgets are single line text widgets, representing common risk indicators. See above for an explanation of Maximum Drawdown, Max Drawdown Duration, Volatility, and Semivariance.
Figure 6. Setting the risk-free return from the context menu. The Sharpe ratio is a financial metric that measures the performance of a portfolio compared to a risk-free asset, taking into account the portfolio's risk. It is calculated by subtracting the risk-free return from the portfolio's return, such as the Internal Rate of Return (IRR), and then dividing the result by the standard deviation of the portfolio's return, which is a measure of its volatility.
The risk-free return is set by default to 0%, but this can be adjusted through the context menu to reflect your current risk-free rate. As the ratio is based on volatility, complete historical prices are required. Without complete prices, the calculated volatility may be underestimated.
"},{"location":"reference/view/reports/performance/#earnings","title":"Earnings","text":"Transactions overview: A table displaying the monthly earnings, comprising dividends, interest, or both individually. The year can be adjusted using a spin button located at the top of the widget.
Monthly earnings: A table displaying the monthly earnings. The year should be set with the context menu.
Number of trades with profit/loss: A single-line widget presenting the total number of trades in grey color, along with an upward-pointing green arrow + counter indicating the number of trades with profit, and a downward-pointing red arrow indicating the number of trades with loss.
Trades Profit/loss: The total net value of the trades in the reporting period. Green color used for profits, red for loss. Assets and reporting period could be set with the context menu.
Average holding period: The average holding period is calculated as follows: All trades are included that were in the portfolio at some point within the selected reporting period. The holding period of each security is the difference between the time of purchase and sale. Immediate sales are assumed for positions currently held. The position weight is calculated from the purchase price of the position relative to the total number of all purchase prices. The Average holding period is the sum of the products \"holding period x percentage position weight\" across all positions. The metric could be displayed in days or in years.
Portfolio Turnover Rate: The Portfolio Turnover Rate measures how much (in money) of the portfolio was \"replaced\" throughout the holding period, as a fraction of the average portfolio value. A turnover of 100% means that all money invested in the portfolio is since then replaced.
Monthly investments, Monthly fees, and Monthly taxes: A table illustrating the total amount of investments, fees, or taxes. The rows correspond to the years, while the columns represent the months, making each cell a monthly record within a year.
More detailed information about the performance calculation could be found under the menu View > Reports > Performance > Calculation or in the sidebar. The main pane contains the title bar icons (top right) and seven tabs or panels: Calculation, Assets at Start, Assets at End, Earnings, Earnings by Account, Taxes, and Fees. The information pane displays detailed information about the item that is selected in the main pane.
Figure 1. Calculation panel.
"},{"location":"reference/view/reports/performance/calculation/#main-pane","title":"Main Pane","text":"Figure 2. Filter menu.
The title bar (top right) displays the chosen Reporting period (named 2023in Figure 1 & 2), and some utility icons. The Filter Data by portfolio and Reference account lets you narrow down the info shown for either the whole portfolio or a specific securities account, alone or with its associated deposit account. By default, it's set to Entire portfolio. You can only pick one filter option. You can also make your own New filter by choosing accounts to combine and giving it a name. They are listed below the defaults. The option Manage... lets you edit or delete custom filters. Just select the filter name and use the right-click menu to add additional accounts or delete the filter. Clicking the triangle reveals the chosen accounts, which you can delete individually. The option remove entries will delete all custom filters.
Using the Export Data as CSV icon, you can save each panel as a CSV file. This is useful for performing calculations, such as comparing Assets at Start and Assets at End, in a spreadsheet program. The columns in the CSV file match the headings of the panel, such as Shares, Name, Symbol, Quote, ....
The Configure view icon provides only one option, named Pre tax. A check mark is added when selected.
The calculation panel (see Figure 1) contains the initial and final value of the selected account or portfolio and all the different categories of changes that lead from the former to the latter. You can collapse or expand a single category or all categories at once with the context menu (right-click). A fully collapsed version of this panel is also displayed as a widget in the parent Performance menu.
Initial Value: This represents the balance of the portfolio (or selected account) at the beginning of the reporting period. As can be seen from figure 1 & 2 the reporting period is set to the year 2023. It's important to note that this value is fixed at the end of the day, meaning transactions from the first day are not included. You can verify the Initial Value and its components in the Assets at Start panel (Figure 3). In terms of our performance equations, the MVB symbol (Market Value Begin) refers to this value.
Figure 3. Assets at Start panel.
Between Initial and Final Value are the different categories of changes that lead from the former to the latter: Capital Gains, Earnings, Fees and Taxes, Cash Currency Gains, and Performance Neutral Transfers (see Figure 1).
Capital Gains: A capital gain or loss refers to the increase or decrease in the value of a capital asset, such as stocks, bonds, or real estate, between the time it is purchased and the time it is valued or sold. In the latter case, the term \"Realized Capital Gain\" is used. For each security remaining in the portfolio, the absolute gain or loss is calculated. It is important to stress that the gain or loss is expressed in the portfolio's currency; not the currency of the asset. If the asset is denominated in a foreign currency, any gain or loss due to fluctuations in the exchange rate is accounted for and indicated in the column thereof foreign currency gains. Hovering with the mouse over the value will display a pop-up with a more detailed calculation. For example, take the calculation of share-3 (see Figure 1 - information pane):
However, this loss is exacerbated by the change in the exchange rate. The 100 AUD purchased on Jan 1, 2023, were valued at 63.72 EUR, whereas on December 31, 2023, they were valued at only 61.49 EUR. Thus, quote price remaining unchanged, your investment (expressed in EUR) decreased already by -2.33 EUR due to the difference in the exchange rate. The total capital loss of -17.60 EUR is partly caused to the currency exchange loss of -2.33 EUR.
Realized Capital Gains: refer to the profit or loss that occurs when an investment is sold for a price different from its original purchase price. The hypothetical capital gains or losses, as described above are then realized. There is only one realized capital gain in Figure 1. On April 12, 2023, 5 shares of share-1 are sold for 5 x 22.40 EUR/share = 112 EUR (excluding fees and taxes). At the time of MVB (December 31, 2022), they were valued at 5 x 18.638 EUR/share = 93.19 EUR. The realized capital gain is thus 112 - 93.19 = 18.81 EUR. It's worth noting that share-1 was purchased in two batches: 10 shares on January 15, 2021, at 15 EUR/share and 5 shares on January 14, 2022, at 16 EUR/share. Due to the FIFO principle that PP implements, the 5 shares that were sold are those from the first batch of 10. If we had considered a longer reporting period, thus including the initial purchase, the valuation of the sale would have been determined by the purchase price of the initial acquisition, not the second one.
Earnings: Profit generated by the investment, consisting of dividends and interest. As can be seen in Figure 4, a dividend of 30 EUR (including fees and taxes) was paid for share-1. It was deposited in a cash account. That same cash account earns an interest, paid on July 1, 2023.
Figure 4. Earnings panel.
A summary per account with a breakdown of dividend, interest, total earnings, fees, and taxes is provided by the Earnings by Account panel.
Fees and taxes: Fees are charges imposed by banks, brokerage firms or investment platforms for their services. Taxes are levies imposed by the government on investment income. Fees and taxes are mostly recorded at the transaction itself (buy, sell, dividend, interest) but they can also be booked as a separate transaction. For example, the one euro tax on the separate interest transaction is recorded as Other in Figure 1. The taxes on the purchase and dividend of share-1 are summed as 12 EUR.
Figure 5. Taxes and Fees panel.
Cash Currency Gains: read the following section about Performance neutral transfer first to better understand this topic. Since some deposits and investments are made in a foreign currency, e.g. AUD, cash currency gains or losses could occur. Some of losses are made at sale time. For example, (see above capital gain). There is also a loss on the remaining deposit since Jan 1, 2023 on the AUD cash account. Since only 100 AUD was needed for the purchase, the remaining 400 AUD remains on the cash account. The loss on this deposit was 100 x (0.6372 - 0.6149) = 8.93 EUR
Performance Neutral Transfers: A transfer refers to money that flows into or out of the portfolio; also named cash flow (CFin and CFout) in our performance equations. This could be a deposit or removal (withdrawal) into or out of a deposit account. It could also be a delivery of securities into or out of a securities account. In the example of Figure 1, there is one deposit of 500 AUD at the beginning of 2023. Given an exchange rate of 0.6372 AUD/EUR, this constitutes a neutral transfer of 318.61 EUR.
There was also a delivery of 5 x 20 USD shares on July 1. Given the exchange rate transfer of 0.9203 USD/EUR, this results in a neutral transfer of 92.03 EUR. Taken together, there was a performance neutral transfer of 410.64 EUR in 2023.
Note
The term Neutral transfer stresses the fact that the transfer (of money or stock) on its own doesn't influence the performance. When an investor deposits money into their cash account, they are simply adding to the available cash balance. No profit has been made so far. The other categories (capital gains, earnings, fees & taxes, cash currency gains) are transfers that do impact your profit or performance. They are not neutral to performance.
Final value: The final value represents the valuation of the chosen account or portfolio at the end date of the reporting period. Figure 6 provides a breakdown with the end value of each asset held within the portfolio or account. The final value corresponds with the MVE symbol (Market Value Begin) in our performance equations.
Figure 6. Assets at End panel.
The information pane offers comprehensive details about the selected security in the main pane. It's essentially identical to the information pane in the All securities view, with the only distinction being the absence of the Data quality submenu.
The menu View > Reports > Performance > Payments presents an overview of payments per period. A payment constitutes a transfer of money into an account, encompassing dividends, interest, fees, and taxes. The view is structured as a table with periods arranged in columns, instruments (accounts and securities) in rows, and an aggregated summary payment allocated per cell. Utilizing the primary and secondary menu at the top, you can specify the payment type and the period selection (refer to Figure 1).
All payments are denoted in the default portfolio currency, such as EUR as illustrated in Figure 1. Payments made in a foreign currency undergo automatic conversion using the currency exchange rate applicable on the payment date. For instance, the Interest Charge of 13 AUD on 2023-08-01 is converted to 7.85 EUR utilizing the conversion rate of 0.6040 AUD/EUR.
Figure 1. Payments overview.
"},{"location":"reference/view/reports/performance/payments/#primary-menu","title":"Primary menu","text":"Reporting period: In the primary menu (far right), you can select the overall reporting period. Utilize the drop-down Since xxxx to designate the time period; for instance, since 2023. When combined with the sub-period selection (e.g., Month), this could potentially result in numerous columns in the main pane. Indeed, four years would yield 48 columns.
The filter function operates identically to that in the Performance > Calculation view, allowing you to refine the information displayed for either the entire portfolio or a specific securities account, either alone or in conjunction with its associated deposit account.
The Export Data as CSV function exports the monthly, quarterly, and yearly table view, as well as the transactions view. The chart diagrams cannot be exported.
The Configure icon enables you to reverse the column order (from Jan > Feb > Mar > ... to Mar > Feb > Jan), display only the first year of the list of years since xxxx, and consolidate inactive securities. The consolidation results in a new line \u2211 Retired securities, summarizing (consolidating) the results of all inactive securities into one row. By default, both active and inactive securities are listed.
Type of payment
Interest Charge. If both payments occur in the same period, the net value of (Interest - Interest Charge) is displayed.Taxes,Tax refund, Fees, or Fees refund. If payment and refund occur in the same period; the net value is displayed.dividends + net interest + net fees + net taxes.The secondary menu (below the primary) allows you to adjust the layout of the main pane. The first three options enable you to select a table view per month, quarter, or year; marked with the green line in Figure 1. The following four options will present the same data but in the form of a graph (blue line). The last two options (orange line) provide detailed information. Clicking the header of a column will sort the rows in ascending or descending order.
Since xxxx) is divided into months, with one column per month. The first and last columns contain the names of the instruments, which could be securities and/or deposit accounts. The filter option (see above) allows you to restrict this view to certain accounts. A sum is provided for each column (month) and for each row (instrument). As mentioned before, this view could be exported as a CSV file.Since xxxx) is divided into quarters with one column per quarter. The instrument column is only displayed once.Year/Instrument: Similar to the previous description, but organized by year instead of month. The number of displayed years depends on the selected reporting period (Since xxxx).
Figure 2. Dividend payments per year since 2022.
As can be seen by comparing Figure 1 and Figure 2, the value for the first security in 2023 is the sum of the monthly payments (19.80 = 7.38 + 12.42).
Month: A bar chart of the Month/Instrument view with the months (Jan - Dec) on the X-axis, the payments on the Y-axis, and the years represented by differently colored bars with a corresponding legend. Figure 3 depicts a bar chart illustrating the monthly dividend payments since 2022, derived from the tabular view shown in Figure 1.
Figure 3. Bar chart of monthly dividend payments since 2022.
Quarter and Year: Similar to the monthly bar chart but organized by quarter or year.
Overview: a special kind of 'boxed' view, with a box for each year and month, containing the number of transactions and the total amount of payments in that period (see Figure 4).
Figure 4. Box view of monthly dividend payments since 2022.
Transactions: A list of all transactions related to the selected type of payment in the primary menu. For instance, after choosing the Dividends and Year/Instrument options in the primary and secondary menu, the main pane will display the total dividend payment per year. If you wish to identify the transactions that lead to these dividend payments, you can switch to the \"transactions\" option in the secondary menu.
With the menu View > Reports > Performance > Chart or the sidebar, you can generate a graphical representation of the relative performance of your assets over time.
The x-axis represents time, and you can select the desired time period using the dropdown menu in the top-right corner. By default, the periods of 1 year, 2 years, 3 years, 4 years, 6 years (from today), and the previous day are available. Additionally, you have the option to create a custom time period using the 'New' feature; see Reporting Period for a description.
The y-axis displays the cumulative performance as a percentage from the beginning of the reporting period; indicating how much the asset value has increased or decreased compared to the previous period (daily, weekly, monthly, quarterly, or yearly). For a daily report, the formula could be written as:
$$\\mathrm {r_{daily} = {\\frac{MVE + CF_{out}}{MVB + CF_{in}} - 1 {\\qquad \\text{(Eq 1)}}}}$$
and
$$\\mathrm {r_{cum} = [(1 + r_1) \\times (1 + r_2) \\times ... \\times (1 + r_n)] - 1 {\\qquad \\text{(Eq 2)}}}$$
where MVE = the market value of the asset at the end of day, MVB = the market value at the beginning of the day (or the end of the previous day). CFin and CFout represent the net incoming or outgoing cashflows for the day. When a stock pays a dividend, that's an outgoing cashflow from the stock's perspective. In fact, the MVE should be increased by this amount. Should this stock be sold on the day, you would receive the MVE + dividend! A deposit (for buying the stock) is a cash inflow. Paying the associated fees is also a cash inflow, as they are paid externally to the stock. The MVB, which is initially zero, should be increased by these sums. One does not acquire magically the stock for nothing.
Taxes are usually NOT** considered as cash inflows because they represent a mandatory payment to the government. Investors have little control over taxation and the performance of their investment should ideally remain unaffected by it. In contrast, fees typically represent upfront costs incurred during the buying or selling of stocks. Taxes on investments, however, typically come into play upon selling the investment, exerting their impact on performance more noticeably at the conclusion of the investment cycle.
"},{"location":"reference/view/reports/performance/performance-chart/#calculation-method","title":"Calculation method","text":""},{"location":"reference/view/reports/performance/performance-chart/#simplified-example","title":"Simplified example","text":"Let's start with a very simplified example without cashflows (see Figure 1). You purchased 10 shares on January 1, 2023. The quote of share-1 fluctuates between 9 and 17.
Jan 1: the market value of your asset at the beginning of the day is zero (MVB = 0). You haven't purchased any stock yet. The market value at the end of the day MVE = 90; you have purchased 10 shares a 9 per share. For that, you made a deposit or CFin = 90. There are no fees or other cash flows. According to equation 1, the daily performance = [(0 + 90)/90] - 1 = 0. The cumulative performance is also (1 + 0) - 1 = 0.
From Jan 2 until 1 until March 31, the daily performance remains at zero because there are no incoming or outgoing cashflows and MVB = MVE e.g. (90/90) - 1 = 0. The performance is solely driven by the historical prices.
On April 1, the price increases from 9 to 15 per share. Thus, MVB = 90 and MVE = 150 and the daily performance = (150/90) - 1 = 0.6667 or 66.67%. The cumulative performance from the beginning of the reporting period is also [(1+0) x (1+0) x ... x (1+0.6667)] - 1 = 0.6667 or 67.67%.
On July 1, the price drops to 14 per share. The daily performance for that day is (140/150) - 1 = -0.0667 or -6.67%. The cumulative performance however becomes [(1+0) x (1+0) x ... x (1+0.6667) x (1+0) x ... x (1-0.0667)] - 1 = (1.6667 x 0.933) - 1 = 0.5555 or 55.55%.
Figure 1. Simplified example to calculate the performance (%) without cashflows.
"},{"location":"reference/view/reports/performance/performance-chart/#complex-example","title":"Complex example","text":"Now, let's introduce some complexity as depicted in Figure 2. The initial purchase includes both fees and taxes. On May 1, a dividend is paid. Subsequently, there are additional taxes or fees along with refunds.
Jan 1: the performance drops from 0% on December 31 to -6.25% on Jan 1. As in the previous example, MVB = 0 and MVE = 90. However, there are two CFin: a deposit and a fee payment. Taxes are not taken into account. According to Eq 1, the daily r = [90/(0 + 90 + 6)] - 1 = -0.0625 or 6.25%. The cumulative performance is the same (1 - 0.0625) - 1 = -0.0625
From Jan 2 until 1 until March 31: the daily performance becomes zero and the cumulative performance remains at -6.25% (see above for an explanation).
On April 1, the historical quote increases to 15 per share. There are no additional cashflows. The daily performance = (150/90) - 1 = 0.6667 or 66.67%. The cumulative performance becomes: [(1-0.0625) x (1 - 0) x ... x (1 + 0.6667)] - 1 = 0.5625 or 56.25%.
A dividend is paid on May 1. This represents a CFout. Only the net value of this cashflow (8) is taken into Eq 1, giving the daily performance = [(150 + 8)/(150] - 1 = 0.0533 or 5.26%. Because most daily performances are zero, I will leave them out in the formula for the cumulative performance = [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533)] - 1 = 0.6458 or 64.58%.
July 1, historical price decreases to 14 per share. The daily performance becomes (140/150) - 1 = - 0.06667. The cumulative performance decreases to [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533) x (1 - 0.0667)] - 1 = 0.5360 or 53.60%.
The taxes (50) on Aug 1 have no effect on the daily or cumulative performance, which remains at 53.60%.
The fee or CFin on Sept 1 does have an effect. The daily performance = [140/(140 + 20)] - 1 = - 0.125. The cumulative performance decreases to [(1-0.0625) x (1 + 0.6667) x (1 + 0.0533) x (1 - 0.0667) x (1 - 0.125)] - 1 = 0.3440 or 34.40%.
Figure 2. Simplified example to calculate the performance (%) with cashflows.
"},{"location":"reference/view/reports/performance/performance-chart/#user-interface","title":"User interface","text":"The user interface of View > Reports > Performance > Chart is quite comparable to the chart interface of View > Reports > Statement of Assets > Chart. We cover only the differences in this section; see link above for the common features.
The gear icon (top right) provides an additional type of data series, called Add benchmark ... (see Figure 3). A benchmark is a security from which only the historical prices are taken to calculate the daily and cumulative performance. Figure 3 displays two benchmarks are displayed: the MSCI World index and share-1 (benchmark). For more information on indexes and benchmarking, refer to How-to > Benchmarking your portfolio.
Please note that the share-1 (benchmark) graph is identical to the one in Figure 1, where cash flows such as dividends and fees were not taken into account. Since the daily historical prices of the MSCI World index exhibit slight daily variations, the resulting curve appears somewhat more irregular.
Figure 3. Adding a benchmark to the performance chart.
Figure 4. Export CSV.
In addition to the Export chart data and Save diagram, already available in Statements of Assets chart, the 'Export data as CSV' button, located in the top right corner, enables you to export each data series or benchmark separately as a CSV file. Only the series that are currently displayed on the chart can be exported. For example, to validate the calculations discussed previously, you can display and export the share-1 data series. In the exported CSV file, you will find the numerical daily and cumulative performance values for each day.
Another addition to the Statement of Assets chart, is the 'Interval' drop-down with choices: daily, weekly, monthly, quarterly, or yearly. In the previous examples, we computed the daily (cumulative) performances. Exporting share-1 data series as csv-file with a quarterly time interval will produce the following table.
Date Value Cfin Cfout Daily % Cumulative % 2022-12-31 0 0 0 0 0 2023-03-31 90 96 0 -6.25 -6.25 2023-06-30 150 0 8 75.56 64.58 2023-09-30 140 20 0 -18.33 34.41 2023-12-31 120 0 0 -14.29 15.21 2024-01-01 170 0 0 41.67 63.21To calculate the performance of the second quarter, you need to know the values of MVB, MVE, CFin, and CFout. MVB is the market value of share-1 on March 31, which is 90 (see Figure 1). MVE is the market value on June 30, which is 150. If you look closely at the transaction list of Figure 2, you will notice that there is only one CFout: dividend minus fees on May 1 (8). There are two CFin: deposit and fee on Jan 1 (96) and another fee on September 1 (20). The second quarter only contains the CFin. Following Eq 1, the quarterly performance (of quater 2) is: [(150 + 8)/90] - 1 = 0.7555 or 75.56%. The cumulative performance is[(1 - 0.0625) x (1 + 0.7556)] - 1 = 0.6458 or 64.58%.
Please, refer to View > Reports > Statement of Assets > Chart for a description of the other features such as zooming, adding data series, context menu of the canvas and legend, and others.
"},{"location":"reference/view/reports/performance/securities/","title":"Securities","text":"While the Reports > Performance menu gives you the most important key performance indicators on portfolio level such as IRR and TTWROR, the Reports > Performance > Securities menu provides you with much more detail on security level. However, it's important to understand the difference; especially in terms of cashflows (see section on performance).
Figure 1. Overview of Performance > Reports > Securities.
"},{"location":"reference/view/reports/performance/securities/#main-pane","title":"Main Pane","text":"The Reports > Performance > Securities menu contains a main pane (top) and an information pane (bottom) of the selected security from the main pane. Performance calculation is always dependent on the chosen Reporting Period, which could be set with the drop-down at the top-right.
The first Filter group (top right) allows you to narrow down the securities list to shares \u2260 0 or shares = 0. The latter filter will display only those shares that have been completely sold, where the number of purchased shares has dropped to zero. Without either of these filters, all shares, regardless of quantity, are displayed. The second filter group is also detailed in the Performance > Calculation menu, allowing you to choose either the entire portfolio or specific individual accounts.
The Export as CSV file option will save the current table, including only the visible columns, as a CSV file.
The Show or Hide columns icon provides access to the entire (lengthy) list of available fields that can be displayed.
Purchase value: The small icon preceding the heading name indicates that this concept deviates from the more common Bying price. When hovering over the column heading with the mouse, a small popup will appear, explaining the meaning of the concept. The purchase value of the available shares (at valuation time) is calculated using the FIFO (First-in/First-Out) method and includes transaction fees and taxes. For share-2 in Figure 1, this calculation is relatively straightforward. On September 30, 2022, eight shares were purchased at a quoted price of 16 EUR/share, totaling 67 EUR, which includes 3 EUR of transaction fees and taxes.
Hovering over the purchase value of share-1 will display a transaction history (refer to Figure 2), which is more complex. On January 15, 2021, ten shares were purchased for 155 EUR (including fees and taxes). Of these 10 shares, 5 remain after the sale on April 12, 2023, valued at 77.50 EUR (half of the original 155 EUR). A second purchase of 5 shares was made on January 14, 2022, for 84 EUR, bringing the total purchase value to 161.50 EUR at the time of valuation.
Figure 2. Purchase Value.
Purchase price: As with the Purchase Value, this is the calculated buying price, taking into account multiple purchases and sales. For example, the five remaining shares of share-1 from the first purchase were priced at 15 EUR excluding fees and taxes. The second purchase of 5 shares was priced at 16 EUR (excl fees and taxes). The weighted average purchase price is [(5 x 15) + (5 x 16)]/10 = 15.50 EUR.
share-1.In addition to the default visible columns described above, several other fields can be added (see Figure 3).
Figure 3. Available fields Securities.
Purchase Value (Moving Average): By default, PP employs the FIFO method to value the stock inventory. Under this method, upon sale, the stock that was first purchased will also be the first sold, leaving the more recent purchases as the remaining stock. In a rising market, this means the most expensive shares remain and performance appears to be more favorable, especially when compared to the LIFO method.
In the moving average method, no assumptions are made regarding which securities will be used upon a sale. It could be the first purchased, the last, or some randomly chosen shares. The weighted average price of the stock is calculated. As new stock is purchased, this weighted average moves towards the price of the newly purchased stock.
With a single purchase, such as with share-2, there is no difference between the two methods. The Purchase Value (default column) and Purchase Value (Moving Average) will be the same: 67 EUR. However, the difference becomes evident at the time of sales with a multiple purchase stock, such as share-1. The default FIFO method calculation amounts to 177.50 EUR (refer above for calculation details). The (simple) moving average methodis calculated as follows: initially 10 shares at 15.5 EUR/share (inclusive of fees and taxes) and later 5 shares at 20 EUR/share, resulting in [(10 x 15.5) + (5 x 20)] / (10 + 5) = 17 EUR/share. The remaining 10 shares after the sale are valued at 170 EUR.
ISIN, Symbol, WKN, Note: see Reference > File > New Master data.
Dividends: By default the sum of dividends is displayed.
share-1: 30 / 177.50 = 16.90%.share-1: 30 /170 = 17.65%.share-2 has no dividend payments; so the value is none. And, because, there is only 1 dividend payment for share-1, it is for the time being unknown. If there are multiple payments, the periodicity could be anual, semi-anual, quarterly or monthly.share-1: 190.06 - 177.50 = 12.56 EUR. share-1: 190.06 - 170 = 20.06Capital Gains: for a more detailed explanation of capital gains; see section on Reports > Performance > Calculation.
share-1 is 37 EUR. The five shares are sold for the gross value of 112 EUR; while the purchase value (without fees and taxes) was 75 EUR. The realized gain is thus 37 EUR. () Figure 4. Realized gains for share-1.
share-2 hasn't been changed since the first purchase. So, the realized gains are zero EUR. The share has been purchased on September 2022 for 64 EUR (without taxes and fees). At the end of the reporting period (June 12, 2023) the market value is 11.76 EUR. The unrealized gains are 47.76 EUR. The only cashflows that matter from a portfolio perspective are the deposit/removal transactions on a cash account OR the money value of the Inbound/Outbound Deliveries of securities into a securities account. Only money from these transactions flow into or out of the portfolio.
From a security (account) perspective, the performance of a security is influenced by the value (price) of Buy or Sell transactions or the equivalent Inbound or Outbound Deliveries. The payment of a dividend is considered as a cash inflow into the security (increasing the performance), as are Fees refunds. Paying fees on security transactions however will decrease the performance and will reduce the cash flow as a result of the Buy/Sell or Inbound/Outbound Delivery.
Taxes are an exception. In PP they are considered as performance neutral, when viewed from the security perspective.
Quotation\" generally refers to the price of a single security or commodity at a specific point in time, as quoted on an exchange or by a market maker. In contrast, \"valuation\" refers to the process of determining the overall worth or value of a portfolio of securities or assets, taking into account various factors such as market conditions, financial performance, and future growth prospects.
"},{"location":"reference/view/reports/performance/trades/","title":"Trades","text":"A trade refers to the act of buying or selling a financial security, such as a stock or bond. In PP, this can be executed through buy/sell transactions as well as through Inbound or Outbound Deliveries.
Figure 1. The Reports > Performance > Trades view.
In the Reports > Performance > Trades menu, an open trade is constructed by consolidating all buy/Inbound Delivery transactions associated with a particular security. Hence, an open trade may encompass several buy transactions. Conversely, each sell or outbound delivery transaction generates one individual closed trade. For example, in Figure 1, share-1 is characterized by one sell transaction, depicted by the first closed trade (row 1), and two buy transactions, consolidated into the open trade (row 2).
With the Filter menu, you can limit the list of trades to Only open trades or Only closed trades. If neither is selected in this group, all trades are displayed. In the second group, you can choose between Only profitable trades or Only lossmaking trades; essentially the green colored versus the red colored rows.
The Export as CSV icon contains one export, named Trades which represents the table from Figure 1. Fields added or removed with the Settings icon will also be added or removed in the CSV-file. Most of the available fields are already shown in Figure 1.
(open) if there are still securities left in the portfolio.# transactions: The number of transactions in a trade is typically one (buy) or two (buy + sell). Hovering over the cell near the icon will trigger a pop-up displaying additional information. From Figure 2, it can be deduced that 5 shares of share-1 were sold on April 12, 2023. Hovering over the open trade (row 2) will reveal that 5 shares were purchased on January 15, 2021, and another 5 on January 14, 2022. Here, you can observe the FIFO principle in action. The five sold shares are subtracted from the first purchase, which initially consisted of 10 shares.
Figure 2. Info overlay closed trade share-1.
Shares: The number of shares in the trade.
Entry value: This represents the Net Transaction Value (NTV) of the trade, which includes fees and taxes. For an open trade with a single buy transaction, this is the NTV of the purchase. For example, if 3 shares of share-3 are bought at 413.64 USD per share with 50 USD in fees and taxes, the Net Transaction Value after conversion at a rate of 0.9384 USD/EUR is 1211.40 EUR. For a single buy/sell trade like share-2, the Net Transaction Value of the original purchase (67 EUR) is distributed over the open trade of 5 shares (41.88 EUR = 67/8 * 5) and the closed trade of 3 shares (25.13 EUR).
The situation is more complex with the multiple buy/sell trade of share-1. The entry value (161.50 EUR) of the open trade is formed by 5 shares from the first purchase and 5 from the second, following the FIFO principle. The original Net Transaction Value of the purchase of 10 shares on January 15, 2021, was 155 EUR. The second purchase of 5 shares had a net transaction value of 84 EUR. Combined, 161.50 EUR equals (155/2 + 84).
Entry value (per share): Enable this column by using the Settings (gear) icon. The value can be easily calculated by dividing the Entry value by the number of shares.
share-2 is 12.405 EUR/share. The exit value is 5 x 12.405 = 62.03 EUR. For closed trades, the exit value is the Net Transaction Value of the sale. For instance, if share-2 was sold on April 15, 2024, for 3 shares x 12.48 EUR/share minus fees & taxes (4 EUR), the exit value is 34.46 EUR.Holding period (days): For single purchase closed trades, it equals the number of days between the End and the start date. For open trades, it is the difference between today and the Start date. This calculation does not consider weekends, holidays or any other calendar.
Note
For multiple purchase trades, the holding period is an average, weighted by the number of shares. For example, assuming today is 2024-04-22, then the holding period for the first purchase in Figure 2 is: (2024-04-22 - 2021-01-15) = 1193 days and for the second buy 829 days. The weighted average is [(5 x 1193) + (5 x 829)]/10 = 1011 days.
Latest Trade: Enable this column using the Settings (gear) icon. It typically contains either the End Date for closed trades or the Start date for open trades. An exception is an open trade with multiple buy transactions, in which case the date of the last transaction is used.
Additionally, the following columns can be made visible using the Settings (gear) icon: Securities Account, ISIN, Symbol, and WKN. Explanation of these fields can be found at the description of the master data of the security.
The IRR and Return column represent the performance of the open or closed trade. Please note that you cannot set a Reporting period explicitly. The Reporting period of a trade is always between today and the start date of the trade. The column Holding period (days) gives an indication of the number of days between these two dates.
In the section Reference > Basic concepts > Performance > Money-weighted return an extensive calculation of the IRR of open and closed trades is given (using the same example of share-1 as above).
In summary, given the IRR equation: $\\mathrm{MVE = MVB \\times (1 + IRR)^{\\frac{RD_1}{365}} + \\sum_{t=1} ^{n}CF_t \\times (1+IRR)^{\\frac{RD_t}{365}} \\qquad \\text{(Eq 1)}}$
Closed trade (share-1): 105 EUR = 77.50 EUR x (1 + IRR)^(817/365). An IRR of 14.53% will solve this equation exactly. To reach an Exit value of 105 EUR, it would require an initial Entry value of 77.50 EUR to grow at a compound annual interest rate (IRR) of 14.53%, over a period of 817 days.
Open trade (share-1): The open trade has two cashflows (buy). Hovering over the Transactions cell will reveal the data (see Figure 2). The holding period for the first buy is 1193 days = (2024-04-22 - 2021-01-15) and for the second buy 829 days = (2024-04-22 - 2022-01-14). The IRR equation becomes: 216.10 EUR = 77.50 EUR x (1 + IRR)^(1193/365) + 84 EUR x (1 + IRR)^(829/365) or 11.12%. Please note that the holding periods and Exit value will change upon trying this example on a later date.
The Return column is in fact a simple return or the TTWROR with a single subperiod. It is the result of Exit value/Entry value or Profit/loss/Entry value.
The Statement of Assets report provides a snapshot of your portfolio's assets (securities, accounts) at a specific point in time. The default date is the current day. You can choose a different date with the \"Time machine\"; the calendar icon at the top right. Figure 1 lists all transactions of the demo-portfolio up to October 5, 2023. Figure 2 displays the Statement of Assets report as of this date.
Figure 1. List of All transactions of demo portfolio (2023-10-05)
In addition to the purchase of share-1, share-2, and bond-1, there is also a sale of a portion of share-1. In this latter transaction, no deposit is made, and the proceeds from the sale remain in the deposit account.
Figure 2. Statement of Assets report of demo portfolio (2023-10-05)
The report in Figure 2 displays all the available assets on October 5, 2023, including the deposit account with the result of the sale of share-1. The securities are valued at their market prices based on the closing quotes from the previous day, which is -in this case- October 4, 2023. Share-2 is handled in USD. The conversion to EUR is based on the exchange rate provided by the ECB on October 4, 2023 (closing previous day).
The report displays a total line above and below the assets. With the Presentation option (see Figure 3 bottom), you could add or remove the Total lines. The default setting is above and below. Since no taxonomy has been added to the demo portfolio, all assets are listed as Without classification.
Figure 3. Available columns. The default columns that are displayed are Shares, Name, Symbol, Quote, Market Value, Share in %, and Note. Many more columns/fields are available (see Figure 3). While the column headings are mostly self-explanatory, a few of them may require further clarification. You can customize the default columns using the gear icon located in the top-right corner (see Figure 2).
The abbreviation \"MA\" that follows Purchase Price/Value stands for \"Moving Average\" but in fact it should be better called WA or \"Weighted Average\". As mentioned in the discussion about Purchase Value, PP uses the FIFO (First-in, First-out) method to calculate prices and values. \"Moving/weighted average\", however, is another commonly used method.
The Purchase Price and the Purchase Price (MA) of share-1 are respectively 44.41 EUR and 51.61 EUR; a rather big difference. Why? From Figure 2:
What is the Purchase Price of the remaining 40 shares in the portfolio?
The available fields under Performance and Dividends are discussed in a separate chapter.
With the Attributes option, you can add custom fields to the table. These fields are defined in left sidebar > settings > Attributes: Securities and following panels. You can enter a specific attribute value for a security in the Additional attributes panel of the security (see for example, Figure 3 in Getting started > Adding securities)
The Forex (Foreign Exchange) option allows you to view the currency of the quote for each asset and its exchange rate relative to the base currency of the portfolio. The fields labeled as Market value**, Purchase Price**, and Profit/Loss** retain the same meaning as their counterparts in the base currency, but they are presented in the foreign currency.
For instance, let's consider share-2, which is traded in USD. In the default view, the Market Value is expressed in EUR. If you wish to view that value in USD instead, you can achieve this by adding the Market Value** field.
The Distance to SMA is a metric that measures the difference between the current price of a share and the average price of that share over a specified number of past days. The acronym \"SMA\" presumably represents \"Simple Moving Average.\"
When you choose to include this column, you'll also need to specify a period, such as 5 days, 20 days, 50 days, or 200 days. Suppose that you want to know the \u0394 to SMA5 (Distance to SMA for a 5 days period) of share-1. The last 5 available prices are: 71.96, 72.00, 72.42, 73.52, and 74.50 EUR; including the latest available on October, 5 (= 71.96 EUR). The calculation is carried out as follows:
Distance to ATH (All Time High) is a likewise metric that shows how far the current price is from the highest price in the specified period. For example, the highest price of share-1 in the last year was 77.4 EUR. The current price is 71.96 EUR. So the \u0394 ATH 1 year (Distance to ATH for a 1 year period) is equal to (71.96 - 77.4)/77.4 or -7.03%.
Using the Reset Columns option in Figure 3, you can revert to the default arrangement of columns. It's advisable to keep this layout as the Standard view, which is represented by the first button at the top (see Figure 1). By clicking the triangle icon next to the button, you can access options to rename, duplicate, or delete the current view.
If you find yourself needing a custom layout regularly, you can duplicate the standard view, give it a new name, and customize it to your preferences. Additionally, there is a New View button available to create a new view based on the default setup.
To the right of the New button, there is a currency selection button. It should be labeled with the base currency of the portfolio, but you have the option to choose other currencies. All calculated fields such as Market Value are then converted to the selected currency.
The Filter icon located in the top right corner allows you to filter the assets that will be used in the calculations. You have several options:
Additionally, you have the option to create a custom filter. To do this, you will need to make a selection from all the available assets within the portfolio.
"},{"location":"reference/view/reports/statement/holdings/","title":"Statement of Assets \u203a Holdings","text":"A visual representation of the total value of the portfolio divided into categories such as different accounts is given by the Holdings chart (menu View > Statement of Assets > Holdings or with the sidebar). A doughnut chart displays the proportion of different accounts within the total, with the entire doughnut representing 100%.
Figure 1. Doughnut chart of the total value of portfolio.
Hovering the mouse pointer over a segment of the doughnut chart reveals the following account details: name, percentage, number of shares, current share price, total value in the portfolio currency. In the case of a deposit account, the number of shares is fixed at one (see Figure 1).
Positions with negative values, such as a deposit account with a negative balance, are not displayed. By not displaying positions with negative values, the chart's percentages may be inaccurate. An error message alerts users to this situation.
With the filter icon (top right), you can show the entire portfolio or only a few combinations of accounts; for example broker-1 with or without its associated deposit account broker-1 (EUR). You can create a new filter, rename or remove existing ones.
For a portfolio with a large number of securities, the chart can become unreadable, and it's advisable to implement a filter.
"},{"location":"reference/view/reports/statement/statement-chart/","title":"Statement of Assets \u203a Chart","text":"Using the menu View > Reports > Statement of Assets > Chart or the sidebar, you can generate a graphical representation of the value of your assets over time.
The x-axis represents time. You can select the desired reporting period using the dropdown menu in the top-right corner. By default, the periods of 1 year, 2 years, 3 years, 4 years, 6 years, and the previous day are available. Additionally, you have the option to create a custom time period using the 'New' feature; see Reporting Period for a description. Unlike the performance chart (found under View > Reports > Performance > Chart), you cannot adjust the time interval in this chart, as it is fixed at 1 day.
The y-axis displays the total value of your assets, denominated in the portfolio's default currency. Larger numbers are condensed by adding 'k', where 1k equals 1000 units of the portfolio currency. You can adjust the scale of this axis by scrolling with the middle mouse button. Hold the mouse position at the value (e.g. 4k) where you want to increase or decrease the scale around.
Figure 1. Chart of the Total value of the demo portfolio.
The canvas is a graphical representation of one or more data series. A data series typically comprises a set of paired data points presented in a table format, such as dates and their corresponding values. By default, two data series are displayed: 'Transferals' (primarily deposits) and 'Total' (see below for an explanation of all possible data series). When you left-click the canvas and hold the mouse down on a specific day, for example, March 28, 2022, a dialog box will appear, displaying detailed values for all data series on that day.
Right-clicking on the chart canvas provides additional options (see Figure 1).
Right-clicking on the legend icons (for example, the blue and red squares from Figure 1) will give you access to additional formatting options. For all types of data series and their legend entries, you can modify the Color, Position (Send backwards, Send to back or Bring forward, and Bring to Front), and Sort (A-Z or Z-A). The latter two options will reorganize the legend entries accordingly. In the case of a line-type data series like the Total value, you can also adjust the Line Style (solid, dash, dot, ...), and the Show Area option (which fills the area below the data series). In addition, you have the option to either hide (where the legend entry remains visible, but the data series is not displayed on the chart) or remove the series altogether (both the legend and data series are removed from the chart).
Figure 2. Data series for chart.
Using the gear icon located at the top right, you can reveal additional data series on the chart. Once a data series is added to the chart, it will no longer be visible in the list of Figure 2. Remember that in the demo-portfolio, we have two brokers; where broker-1 has two deposit accounts (EUR and USD). Broker-2 has only one EUR-deposit account.
With the Accounts and Portfolios option, you can choose to display specific combinations of accounts, such as broker-1 along with its USD deposit account. Select the appropriate option and hold Ctrl to add more selections. Once you've added a data series, it will no longer appear in the list of available data series in Figure 2, but you'll find it checked in the gear menu. You can remove a data series from the chart by unchecking it in the gear menu or by deleting it from the legend (as explained above).
The Common option in Figure 2 will display some additional info.
Delta (for reporting period or since first transaction): represents how much the portfolio's value has increased or decreased from the beginning of the reporting period until the end or from the first transaction until the end of the period. This Delta will fluctuate around zero, for example for the first transaction day the delta will be zero. The chapter on Reporting Period explains that the valuation of a portfolio can differ according to the selected Reporting Period.
Dividends, Earnings (= dividends + interests), Fees, Interest, Interest Charge, and Taxes are available in both accumulated and 'instance' versions. For example, an 'instanced' dividend will be represented as a spike, whereas the accumulated version will display a graph that steadily increases as dividends accumulate over time. These fields are described in Transactions and are recorded as part of each transaction.
Invested Capital (for reporting period or since first transaction): the term \"invested capital\" refers to the total amount of money that an investor has used to purchase various securities, such as stocks, bonds, or other financial instruments. It includes the initial purchase price of the securities, additional investments made over time, and other factors such as fees, taxes, ...
Total: the total value of the portfolio valuated over time.
Transferals: each Deposit or Removal is represented by a very small spike (positive or negative) on the day that the transferal was made.
With securities, you can make a graph of each separate or combination of securities in your portfolio, for example share-1 or share-1 + bond-1.
In the default configuration, the Standard view only includes two data series: Total and Transferals. However, you have extensive customization options, as mentioned earlier. Using the dropdown menu, you can Duplicate, Rename, or Delete this view. You can also create a new view by clicking on the New icon, located in the top right corner between the Standard and Period options. Similar to the existing one, you can duplicate, rename, or delete your newly created view. If you wish to have this view as the leftmost view, select the Bring to front option from the dropdown menu.
As the name implies, this list contains all the securities you are monitoring (\u2260 purchased). To view the securities currently in your portfolio accounts, navigate to Reports > Statement of Assets.
Figure 1. View All Securities.
This view contains two panes. The main pane is a list of all available securities. You can select multiple securities, but only one of them can be active. The information pane features a graph of the active security.
"},{"location":"reference/view/securities/all-securities/#main-pane-list-all-securities","title":"Main pane: list All Securities","text":"Figure 2. All available columns.
The main pane represents essentially a table with all the available securities listed. Click the column heading to sort the table based on that column. You can rearrange any column by dragging its header. Drag the divider line between two columns to adjust the with of the left column. You can rename or hide a column with the context menu (right-click on the column header). Adding, deleting or resetting the columns to their original layout is done with the Show or hide columns icon (gear symbol top right). The default columns are shown in Figure 1; they are also checked in Figure 2. Figure 2 gives a list of all available columns.
Refer to the glossary for a definition and short explanation of the columns. Note that the column heading is sometimes different from the field name e.g. \u0394 amount and that several fields are collapsed into a single category e.g. Data Quality.
Figure 1 represents the Standard view. A view keeps a record of the visible columns, their widths, column headings, and the sorting order of the table. By clicking the triangle icon next to the button, you can access options to duplicate, rename, or delete the current view.
If you find yourself needing a custom layout regularly, you can duplicate the standard view, give it a new name, and customize it to your preferences. The newly created view will be placed to the right of the Standard view. Or you can use the New View button (left of the Search box) to create a new view based on the default setup.
With the Search box you can filter the list of visible securities. For example, entering \"DE\" in the Search box will only display share-1 and share-2 because their ticker symbol contains the string \"DE\".
The Filter icon is used as a more categorical filter. Available options are: Only active instruments,Only inactive instruments, Only securities, Only exchange rates, Shares held \u2260 0, Shares held = 0, and Securities: Limit price exceeded. For the latter, you need to create a new attribute of type \u201climit price\u201d in the settings of the portfolio (menu View > Settings). Then you can add this column to the table and enter some values.
The table displayed in the current view can be exported as a CSV file, preserving the number of rows and columns along with their (custom) column headings.
By dragging the divider bar, you can adjust the size of the main pane, making it larger or smaller. You can even extend it to completely occupy the canvas or hide it entirely. The divider bar becomes visible when hovering over with the mouse.
"},{"location":"reference/view/securities/all-securities/#information-pane","title":"Information pane","text":"The information pane showcases by default a graph or chart of the active security, namely the last one selected in the main pane (refer to Figure 3). The graph is updated each time a different security is selected in the main pane.
Figure 3. Graph of active security from main pane.
"},{"location":"reference/view/securities/all-securities/#chart-menu","title":"Chart menu","text":"The Chart menu turns orange when selected and displays a line graph/chart of the active security. To the right of the graph, detailed information about the security is displayed such as ticker symbol, latest price, .... With the vertical divider, you shrink or expand this area to show more or less of the graph. Drag the divider all the way to the right to completely hide this section. The divider bar becomes visible when hovering over with the mouse.
With the reporting period menu, you can set the time frame of the graph; going from 1 month (1M) until 10 years (10Y). This period is always measured from today minus the period. The x-axis of the chart is subdivided into months (1M, 2M, and 6M), quarters (1Y and 2Y), 2 quarters (3Y), or years (5Y and 10Y). You can also select the YTD (Year-to-Date) option; from January 1th of this year until today. The option H stands for the complete holding period of the security (=from the purchasing date until now), while A displays \"All available data\"; from the first until the last historical price.
If you click and hold on the graph, you can view the date and price of the security at that particular moment. If there are additional markers, such as number of shares or a time series like the Simple Moving Average (SMA), they will also be displayed. To sort these entries by value, you can press the Alt key and click.
Clicking on the first icon (crosshair) of the reporting period menu displays a large crosshair above the graph. The origin (0,0) is at the mouse position of the click. The vertical axis will reveal the position on the x-axis or the exact date. The horizontal axis will display the historical price of the security on that day.
With the second icon (Measure distance) you can determine the exact number of days between two points on the chart. It also displays the difference in historical price and the corresponding percentage between the two points.
Figure 4. Context menu of the graph.
Both options can also be accessed by the context menu (right-click on the graph).
Figure 5. Configure chart (gear icon).
With Configuration chart icon (gear at the top right) you set numerous additional data on the graph. Figure 5 displays the collapsed view.
Marking: Additional symbols can be incorporated onto the graph to convey specific information or highlight key data points.
Show limits: before enabling this option, one has to create a new Security Attribute of type Limit Price. You should also add this attribute as an Additional Attribute to your security. Enter as limit for example > 17 (see Figure 6). An orange horizontal bar will appear at the value of 17.
Figure 6. Chart with limit price indication.
Indicator
The Historical Quotes menu in the information pane reveals a two-column table displaying the date and quote of the selected security in the main pane (see Figure 6). Clicking on a column header will sort the table in ascending or descending order based on that column. You can rearrange the columns by dragging the header.
Double-click on the date or the quote to modify its value. Be careful when changing the date, as the new quote will overwrite any quote registered for that date.
Utilize the \"Export data as CSV\" feature (icon to right) to save the entire table as a CSV file. The context menu (right-click) offers various management options.
Figure 7. Context menu of Historical Quotes in the information pane.
Add: This option enables you to input the date and corresponding quote for the security. You can add quotes for any valid date, even in the future.
Delete: To delete one or more rows, make a selection. For a consecutive selection, click the first row, press Shift, and click the last row. For a non-consecutive selection, use the Ctrl key. Utilize the context menu to delete the selected rows.
Delete All: This command removes all historical quotes in the table. Note that this action cannot be undone.
Quotes: this heading conceals several additional options (see Figure 6). Many of these options can also be executed from another context, e.g. menu.
Update quotes online: Shortcut for the menu Online > Update quotes (selected security).
Debug: Show server response: If the security is linked to an online data provider, you can view the HTTP response from that server.
Configure online update ...: this option will display the Securities attributes form with the Historical Quotes tab selected; see File > New.
Search for suppliers of historical prices ...: displays the first step of the File > New wizard.
Import from CSV file ...: This command is equivalent with the File > Import menu. The CSV file must contain at least two columns.
Import HTML table ...: This option lets you import a table with historical Quotes that you can find on a webpage. Some examples are given (see Figure 7). {#import-html-table}
Figure 8. Import HTML table from context menu Historical Quotes.
For example, navigate to https://www.finanzen.net/historische-kurse/nvidia. You could also search for the security at the homepage. Enter a start and end date and a marketplace. NVIDIA is listed on XETRA. Click on Suchen (Search). Right-click the table and select View Page Source in the contaxt menu. Copy and paste everything in the PP. - Create manually: This command is identical with the Add option above.
Export to CSV file ...: This command is identical with the Export button (top right).
Create historical quotes from transactions: If a security has transactions (buy or sell), the quote price associated with these transactions can be included into the historical prices. The transaction price takes precedence and will overwrite any existing historical quote on that date.
Delete latest price:
Round historical prices to X decimal places: When rounding a value like 99.994 to two decimals, the result will be 99.99, whereas the value of 99.995 will round up to 100.00. Keep in mind that it's not possible to round a number to a higher precision than originally available. Attempting to round the previous number to 4 decimal places, for example, will not change the number.
Figure 1. Context menu of a selected security.
The context menu of a security contains several additional options that are not available within the view menu. You can access the context menu by selecting a security or a security view (e.g., securities account) and right-clicking. A pop-up, as shown in Figure 1, will be displayed.
A stock split increases the number of outstanding shares by issuing additional shares to current shareholders. It does not alter the company\u2019s overall value but adjusts share prices thereby making the stock more accessible to investors.
For example, an Amazon share has risen to a value of about \u20ac\u00a02300 at the beginning of 2022. Amazon approved a 20-for-1 stock split; going into effect on June 6, 2022. In a 20-for-1 stock split, every share of the company\u2019s stock will be split into 20 new shares, each of which would be worth one twentieth of the original share value.
PP currently supports stock splits via a trick that is not 100% clean; see the discussion on the forum. Essentially, it retroactively assumes that the shares have always been split. In the aforementioned scenario of a 20-for-1 stock split, the historical share prices before June 6, 2022, are adjusted to 1/20 of their previous value, while the quantity of units in transactions is multiplied by 20. Please, refer to How-to > Recording Stock split for more detailed and background information.
Selecting the Stock Split option will initiate a wizard that will guide you through three steps to execute the split. In Step 1 you define the instrument, the split date, and the split ratio.
You can use the drop-down menu to select the security if it's not already filled in. The Ex-date (execution date) is the date when the stock exchange first trades the split shares at the adjusted price. For instance, in case of the Amazon split, the Ex-date would be June 6, 2022. Additionally, you'll need to specify the split ratio, such as 20-for-1. It's worth noting that these ratios can also be decimal numbers.
Figure 2. Split stock wizard - step 1.
Step 2 will show you the impact of this stock split on each transaction (buy, sell, delivery, dividend). In this case, there was only one buy transaction before the split date. It is not necessary to have a recorded transaction on the security to perform a Stock Split.
You can skip this step and maintain the transactions unchanged by unchecking the Convert transactions option. In this scenario, you can adjust the historical prices in the following step while leaving the quantity of securities unaffected.
Figure 3. Split stock wizard - step 2.
Step 3 will show you the converted historical prices. If you don't want to change the historical prices, uncheck Convert historical quotes. It's important to note that only prices before the split date will be changed; e.g. Quote (new). Prices after the split will naturally be automatically adjusted correctly by the exchange market.
Figure 4. Split stock wizard - step 3.
In the chart view of the historical prices, a small dashed vertical line will indicate the Stock split. With the menu Configure Chart > Marking > Events (Gear icon) you can toggle this line. You can also delete the event in the Events tab in the bottom panel; see Events. This will remove the marker in the chart but will NOT remove the split from the transactions and historical prices.
Figure 5. Result of Split stock wizard (Amazon).
"},{"location":"reference/view/taxonomies/","title":"Taxonomies","text":"Figure 1. Adding taxonomies.
A taxonomy is a tool for categorizing and evaluating the investments within your portfolio. This classification system creates a framework that helps you to better understand the composition of your investments and make informed decisions.
Taxonomies typically group securities based on shared characteristics such as industry, sector, geographical region, market capitalization, or asset class. By organizing your investments in this manner, you can more easily identify risks and opportunities such as overrepresentation or underrepresentation in a specific segment.
PP offers several predefined and widely recognised taxonomies or templates. You can also create your own custom taxonomy.
Asset Classes: The following classes are distinguished: Cash, Equity, Debt, Real Estate, and Commodity.
Industries (GICS): The Global Industry Classification Standard (GICS) was developed by MSCI in collaboration with S&P Dow Jones Indices. It contains 11 Sectors (e.g. Information Technology), 24 Industry Groups (e.g. Software), 69 Industries (e.g. IT Services), and 158 Sub-Industries (e.g. IT Consulting); see website.
Industries (GICS, Sectors): This template covers only the top-level Sectors classification of GICS (see above); not the Industry Groups, ....
Industry: Another Industry classification with sectors such as Construction industry, Biotechnology, Chemistry, Energy, and many more.
Asset Allocation: Classification into Risk Free assets (e.g. Deposit accounts) and Risk based assets. The latter category is further divided into Regions, such as USA, Western Europe, and others.
Regions: Purely geographic classification into Europe, America, Asia, Africa, and Oceania with the individual countries.
Regions (MSCI): The MSCI Regions taxonomy differentiates between Developed markets (Australia, Austria, Belgium, ...), Emerging markets (Brazil, Chile, China, ...), and Frontier and standalone markets (Argentina, Bahrain, Bangladesh, ...)
Type of Security: Differentiates between Stock, Equity Fund, Exchange Traded Fund (ETF), Bond, Stock Option, Index, and Currency.
Each of the taxonomies can be customized to suit your investment needs. To make changes, use the context menu to add or delete entries. Additionally, you can double-click on the name of a category to rename it.
"},{"location":"reference/view/taxonomies/managing-taxonomies/","title":"Managing taxonomies","text":"When creating a new portfolio, initially, no taxonomies are displayed in the sidebar (refer to Figure 1, top left). In theory, there is no restriction on the number of taxonomies that can be added. However, in most cases, two or three taxonomies should be sufficient. These taxonomies will be listed not only in the sidebar but also in the View menu.
Figure 1. Adding taxonomies.
"},{"location":"reference/view/taxonomies/managing-taxonomies/#adding-a-new-taxonomy","title":"Adding a new taxonomy","text":"Click the green plus button or use the File > New > Taxonomy menu to add a new taxonomy to your portfolio. You can then utilize one of the predefined templates or create a new taxonomy (see Figure 1), which can be based on one of the existing templates. Choose Empty taxonomy if you want to start from scratch and define all categories and sub-categories yourself. Give the new taxonomy a descriptive name. Two taxonomies can have the same name, which is, of course, not ideal. Click \"OK\" to add the taxonomy in the sidebar.
The context menu of the taxonomies list allows you to rename, copy, or delete existing taxonomies. You can also rearrange the order of items in the list using the the Move up or Move down options.
Upon selecting a taxonomy from the sidebar list, its structure will be displayed in the main pane (refer to Figure 2). This main pane contains two expandable lists: one for the assigned assets, which typically, but not always, shares the same name as the taxonomy (e.g., \"myTaxonomy\"), and another for the unassigned assets, labeled as Without Classification. The first list contains the categories and subcategories with their assigned assets and could be initially empty. The second list contains an alphabetically sorted list of securities and deposit accounts that have not yet been assigned to a taxonomy category.
Figure 2. Main pane of a taxonomy.
In Figure 2, both lists are expanded. The myTaxonomy list contains two categories Base currency and Foreign currencies with appropriate securities assigned. The list Without Classification contains all unassigned securities. Please note that you can assign a security to more than one category. The weight however should add up to 100%.
Figure 3. Context menu.
If you selected an empty taxonomy, you must first add categories and subcategories before assigning securities to them. Use the Add new classification context menu to create a new classification (see Figure 3). If you select a subcategory, the new classification will be created within it. The categories can be reordered by simply dragging and dropping them to a new location. To delete a selected category or list, use the context menu.
Selected lists can be sorted by: Type and Name, Type and Actual Value, Name, or Actual Value. As shown in Figure 2, each taxonomy category has an assigned color, which can be changed using the context menu.
To expand a category list, click the icon to the left of it, which will change to a icon. Click the downward-pointing caret to collapse the list. To expand or collapse all categories at once, use the context menu and select Expand all or Collapse all.
Taxonomies are created to classify assets into categories, allowing you, as a portfolio manager, to have a clear understanding of your portfolio's structure. To achieve this, securities must be added or assigned to appropriate categories and subcategories, comparable to adding a tag to a document for grouping purposes.
Securities can be assigned to a category in three ways:
Drag & Drop: Select the security from the 'Unclassified' list and drag it to the correct category or subcategory within your taxonomy at the top. If a category is collapsed and thus not visible, dragging the security over the parent category will highlight it with a light blue background and a black line underneath. After a moment, the category will automatically expand. You can then drop the security into the desired category or repeat the process for a deeper categorization. If your taxonomy contains many categories and/or assets, it may be more efficient to expand the entire taxonomy beforehand.
Context menu: Right-click on a category within your taxonomy and select Assign from the context menu. A list of available assets will appear, from which you can choose the appropriate security to assign to that category.
Figure 4. Taxonomies panel in Security Data window.
Without Classification list or even the All Securities view. Choose Edit from the context menu. In the tab Taxonomies, you can add the security to one or more taxonomies. As shown in Figure 4, the Daimler Truck security is added to a few predefined taxonomies, but also to the Base Currency category of our newly created MyTaxonomy. See Reference > File > New for further information.Selecting a taxonomy from the sidebar or the view menu will display the classification in the main pane. The header contains the standard data icons, a search box, the reporting period selector, and seven display options.
Figure 1. Main pane of a taxonomy.
"},{"location":"reference/view/taxonomies/using-taxonomies/#definition-view","title":"Definition view","text":"By default, the definition view displays a table with the five columns:
Weight: The weight represents the proportion or percentage that a security can contribute to its total value. A weight of 100% indicates that all securities are included in calculating the total value. This field is used in the Rebalancing view.
Color: Each category is automatically assigned a colour. You can change the colour using the context menu.
Actual Value: The market value of a security on the current day. For a category, this is the summed market value of all securities assigned to that category. For example, as of 2024-07-08, the market value of Daimler Trucks is 20 shares x 36.36 EUR = 727.20 EUR, and for Mercedes: 10 shares x 65.47 EUR = 654.70 EUR. Thus, the total value for the category is 727.20 EUR + 654.70 EUR = 1381.90 EUR. Please note that there is a significant number of unassigned securities in myTaxonomy.Foreign securities (e.g. Amazon) are calculated in the base currency.
Actual %: The percentage of a security or category, relative to its immediate parent category. For example, 727.20 EUR of Daimler represents 52.62% of the value in its immediate parent category Base Currency. The 1381.90 EUR of the Base Currency category is 27.98% of the highest category myTaxonomy.
Actual % of Total: The percentage of a security or category relative to the total value of the portfolio (including assigned and unassigned securities). For instance, the 1381.90 EUR of the Base Currency category represents only 6.25% of the total portfolio value.
With data icon gear icon, other fields could be added: Category Key, Symbol, ISIN, Note, Forex (Exchange Rate, Actual Value**), Expected return, and Attributes. The Actual Value ** is the value of the security in the original currency without any conversion.
The icon, Export Data as CSV, will save the table displayed on the screen as a CSV file.
By default, the entire portfolio is included in the table. Using the icon, you can limit the result to only securities and categories whose value is not zero or to only the active accounts/securities. The result can also be limited to the available security accounts, with or without their respective reference deposit accounts.
If you have a long table, you can use the search box. For instance, the Regions (MSCI) taxonomy is quite detailed. To find a share from Mexico, you would normally need to expand (double-click) the Emerging Markets > Americas > Mexico category. The search box offers a quicker alternative.
The Definition view provides a snapshot of the current taxonomy status. The Reporting Period (defaulting to 1 year) is therefore greyed out. Only the Stacked and Stacked Area charts utilize the time information from the Reporting Period.
"},{"location":"reference/view/taxonomies/using-taxonomies/#rebalancing-view","title":"Rebalancing view","text":"Rebalancing is a strategy of bringing a portfolio that has deviated away from one's target asset allocation back into line [Wikipedia]. Any taxonomy (such as Industries or Regions) can be used as a basis for target asset allocation. Typically, though, you would use your own classification.
Figure 2. Rebalancing view.
The first step in the rebalancing process involves entering the target Allocation for each category and the Weight of each security.
Without Classification list.The rebalancing process will calculate the target value for each category based on its allocation and the total portfolio value. If the actual value deviates from the target value, the system computes the difference (delta). It then determines how much each security within the category should be increased or decreased based on its weight.
For example, the total value of myTaxonomy is 5292.73 EUR, consisting of 1376.50 EUR from the Base Currency and 3916.23 EUR (!) from the Foreign Currency. However, the Base Currency category should be 30% of the total or 1587.82 EUR. Thus, there is a difference of -211.32 EUR (-13.31%) between the target and the actual value (see Figure 2).
To rebalance this subcategory, you would need to sell securities. For both Daimler and Mercedes, which each have a weight of 100%, you would sell 105.66 EUR worth of each security. This would correspond to approximately 2.9 securities of Daimler and 1.6 securities of Mercedes.
If, for instance, the weight of Mercedes were set to 50%, its actual value would be reduced to 336.95 EUR (instead of 653.90 EUR), and the Base Currency subcategory's actual value would decrease to 1049.55 EUR (instead of 1376.90 EUR). In this scenario, the delta would then be 440.18 EUR. This could be achieved by selling 9.7 securities of Daimler and 2.6 securities of Mercedes, considering that only 50% of Mercedes is available for sale.
"},{"location":"reference/view/taxonomies/using-taxonomies/#pie-chart","title":"Pie Chart","text":"Figure 3. Pie chart of the portfolio + zoomed-in variants.
The pie chart representing the entire portfolio in Figure 3 appears simple and incomplete because not all securities are assigned to categories within myTaxonomy. From Figure 1, it can be inferred that approximately 28% of the securities are assigned, represented by the purple-coloured segment.
By clicking on a segment of the pie chart, you can zoom in on that particular part. The second pie chart displayed in the middle of Figure 3 shows the categories within myTaxonomy, such as Base Currency and Foreign Currencies. The third pie chart specifically focuses on the Base Currency category.
Figure 4. Donut chart of the portfolio.
The donut chart represents the filtered result of the taxonomy. As such, it is the graphical representation of the column Actual % of Total in Figure 1. With the icon, you can choose to include the category Without Classification.
Figure 5. Tree map of the portfolio.
A tree map is a type of chart that uses rectangles to visualize data, where each rectangle represents a category. The size and color of the rectangle correspond to the value of the data. You can zoom in on a specific category by left-clicking on the corresponding rectangle.
Similar to the donut chart, the tree map reflects the content of the data. However, in the tree map, the percentage distribution is represented by the area of the rectangles rather than by segments. Each category is distinguished by a different color. Like the donut chart, you have the option to include the Without classification category.
Figure 6. Stacked chart of the portfolio.
A stacked chart is a type of chart that displays data as a series of coloured lines, where each line represents a category. The position of the line on the y-axis corresponds to cumulative value of the category. The lines are stacked on top of each other to show the total value of all categories combined, which is 100%. By default, the categories are stacked from large to small, with the largest category at the bottom of the chart. The order of stacking can be adjusted using the icon, allowing bars to be stacked based on magnitude or according to their position in the taxonomy list.
Both the stacked and stacked area charts plot time on the X-axis, set by the selected reporting period (default=1 year).
"},{"location":"reference/view/taxonomies/using-taxonomies/#stacked-area-chart","title":"Stacked Area chart","text":"Figure 7. Stacked chart area of the portfolio.
The Y-axis of the stacked area chart represents the actual monetary value of different categories over time. Similar to the stacked chart, it displays the cumulative values of stacked categories. However, unlike the stacked chart where the values add up to 100%, the stacked area chart shows the actual monetary amounts for each category over time.
"}]} \ No newline at end of file diff --git a/en/sitemap.xml b/en/sitemap.xml index 60d129cf..afe2f36b 100644 --- a/en/sitemap.xml +++ b/en/sitemap.xml @@ -2,472 +2,472 @@