Overview of the data files

Introduction

To be able to use this program successfully, you need to understand how the data are structured. If is recommended to refer to the quick start page to get started by using example data files. Also it is highly recommended to look at the example data files provided on the download page while reading this documentation so you can make sense of it.

Overview of the data files

The program requires a set of input data files to be provided so it can operate. All input data files are plain text CSV files, ans these can be edited using either spreadsheet programs such as Libre Office, or plain text editors such as Notepad++.

The following input types are required:

• Accounts: the various types of accounts where the assets are held
• Assets: the various types of assets such as shares or funds held in any account
• Rates: exchanges rates between the currencies used and the primany currency
• Transactions: the details of each transactions affecting assets including the purchase or disposal
• Distributions: payments for incomes from investments such as dividends, interests, or property income distribution
• Prices: the market price of each asset you own at specific dates
• Tax-years: when the financial years start and end, as this is not identical in all countries
• Expectations: defines the expected amount of income each investments are expected to produce

Each type of input record can be provided in either a single CSV file or a set of multiple CSV files, so you are free to split the data in multiple files, so it is more convenient to maintain. The recommended approach is to have a single CSV file to define simple structures, such as all accounts, and to use multiple CSV file with the records of the transactions and distributions. Ideally, these last two types of records should be split so there is one CSV file for each combination of platform and asset. This allows to keep all similar transactions together, and it makes it easier to keep track of each holding and avoid either omissions or duplicate transactions.

If the records of the past transactions have been lost, it is possible to write a fake BUY transaction for each asset corresponding to the current quantities you own for a particular asset, with the purchase price corresponding to the total price you paid for it, or an estimation of this figure. But please keep the program will not be able to provide accurate information such as capital gains calculation without the exact purchase price of each asset being known.

Expected format of the data

You must provide valid contents in the data files so the program is able to read the data and make sense of it. You can look at the example data files to figure out what kind of format is being used. For example columns that contain dates must be formatted as YYYY-MM-DD and contain a valid date.

Files such as transaction and distribution files contains prices for events such as the purchase of assets, and these are expressed in terms of currencies. Please note the number and the name of the currencies involved must be written in two separate columns. This program does not allow numbers with currency symbols such as “$750.00”. Instead there is a column for the number such as “750.00” and another column for the currency such as “USD”. Columns where numbers are expected must only contain integer or decimal numbers and the dot character must be used for separating decimals. Columns where currencies are expected must contain currency names based on the ISO 4217 convention (ie: “USD”, “EUR”, “GBP”, etc). The exception to this rule is for columns which contain free-text comments. You are free to write things such as “Paid $750.00” in the comments, as the program is not processing the comments.

Many columns contain free form text. Example of such columns include the identifiers (ID columns), descriptions. Also there is a column for the type of income in the distributions. This is free form text, and it is meant to be used with terms such as dividend or interest for example. But the program is not going to check that these values are valid. There can be many different types of incomes in different countries that are not very common. For example incomes from rents paid by REITs in the United Kingdom are paid as “Property Income Distributions” (PID) and these are different from regular dividends and these incomes are taxed differently. Hence there is no restriction on what values you can use in this column. The user of the program is responsible for making sure the values provided are meaningful (regarding the laws of your country) and consistent across the data files.