Structure of the data files

Locations of the data files

By default, the program attempts to find data files in the directory from which it is run. In other words, you should place the data files in the same folder as the program file so your data files can be found.

Object definitions

The data used by the program are stored in multiple CSV files. The data are made of multiple tables, to define objects such as accounts, assets, prices, transactions, etc. Each type of data contains records. The different types of objects must be defined in separate CSV files, as they are structured differently. For example the records that define your transactions and distributions cannot be stored in the same files as transactions and distributions are different types of objects.

Names of the data files

The data files must follow a specific naming convention so the program can find the files. For example all records that define all your transactions must be stored in one or multiple files names after the following pattern: *transactions*.csv, where the wildcards can be replaced with anything you like. So it is possible to define all transactions in a single file named such as investorderly-data-410-transactions.csv but it is equially possible to define transaction in multiple files to have one file for each type of investment:

  • investorderly-data-410-transactions-category1-asset1.csv
  • investorderly-data-410-transactions-category1-asset2.csv
  • investorderly-data-410-transactions-category2-asset3.csv
  • investorderly-data-410-transactions-category2-asset4.csv

It is recommended to follow the naming convention that has been used with the example data files provided on the download page. A single file has been used for object that are expected to contain a small number of records. For example most investor should just have a small number of accounts, assets, taxscopes.

Other objects such as rates, prices, transactions and distributions are expected to have many records over time. It makes sense to store records for these types of objects into separate files, so each file contains the records for one specific type of records. For examples, files that contains asset prices could be split so each file contains all the price for just a single asset at multiple points in time. Using this strategy is easier to maintain and also makes it easier to spot errors, as all records for a particular context will be grouped together.

The example data files all start with the same prefix investorderly-data and are then followed by a three-digit number. This number has no significance. These numbers have been used so the files are naturally sorted in a tidy way. The files with a small number at the stop define general structures which do not change very often. The files with larger numbers at the bottom define records which can grow a lot and have been divided into multiple files.

investorderly-data-110-settings.csv
investorderly-data-120-accounts.csv
investorderly-data-130-taxscopes.csv
investorderly-data-140-assets.csv
investorderly-data-210-snapshots.csv
investorderly-data-220-taxyears.csv
investorderly-data-310-expect.csv
investorderly-data-320-rates-gbp-eur.csv
investorderly-data-320-rates-gbp-usd.csv
investorderly-data-330-prices-metals-gold.csv
investorderly-data-330-prices-metals-phgp.csv
investorderly-data-330-prices-shares-veve.csv
investorderly-data-330-prices-shares-vhyl.csv
investorderly-data-330-prices-shares-vwrd.csv
investorderly-data-410-transactions-gbuln-gold.csv
investorderly-data-410-transactions-gsipp-phgp.csv
investorderly-data-410-transactions-gsipp-vhyl.csv
investorderly-data-410-transactions-gsipp-vwrd.csv
investorderly-data-410-transactions-sigia-veve.csv
investorderly-data-410-transactions-siisa-vhyl.csv
investorderly-data-420-distributions-gsipp-vhyl.csv
investorderly-data-420-distributions-gsipp-vwrd.csv
investorderly-data-420-distributions-sigia-veve.csv
investorderly-data-420-distributions-siisa-vhyl.csv

Empty data files

Most types of objects are essential in the data. For example the program cannot operate without having any account of asset defined. But some objects are optional. For example you may not need to define any exchanage rates if you do not use any foreign currency. In this case, you must still have at least one file that provides the definitions of this object. The CSV file will just contain the column headers but it will contain no record.

Naming of identifiers

The data files provide definitions for objects such as accounts, assets, etc. These objects have a short name which is then used as identifiers so other records can refer to these objects. For example your assets file may define the following two investments:

ID   , Description                                                  , Category , SubCat , Currency , Hidden
VWRD , Vanguard FTSE All-World Global Stocks ETF (USD Distributing) , Stocks   , Growth , FALSE    , FALSE
GOLD , Physical Gold in the Vault (one unit is one gram of gold)    , Metals   , Gold   , FALSE    , FALSE

Here we have decided to define two assets which are identified as VWRD and GOLD respectively. Other objects such as transactions will use these identifiers to refer to these two assets, here is an example of such transactions:

ID          , Account , Asset , Date       , Units , Amount  , CurA , Fee  , CurF , Tax , CurT , Comments
SIPPVWRD001 , GSIPP   , VWRD  , 2024-01-08 , 34    , 3986.16 , USD  , 2.99 , GBP  , 0   , GBP  , Bought VWRD
SIPPVWRD002 , GSIPP   , VWRD  , 2024-02-07 , 32    , 3898.24 , USD  , 2.99 , GBP  , 0   , GBP  , Bought VWRD

You can see the Asset column in the transactions records refer to the assets defined above. Hence it is really important to be consistent and rigorous with the name of assign to your objects. It is recommended to use short names with uppercase letters for all your identifiers to avoid typos and confusion.