InvestOrderly

About InvestOrderly

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

InvestOrderly has been written to provide the features that investors need to invest successfully. Below are the main reasons why investors need this program.

Visibility

This program provides visibility by calculating important metrics. It allows you to see important figures such as the evolution of the value of your investments over time, so you can see the impact of your investment decisions and market conditions on your wealth. You may be investing to achieve specific goals, such as accumulating a deposit to buy your home, being able to generate incomes that cover all your regular expenses, or financing your retirement. This program helps you track your progress on the journey to achieve such goals.

Core concepts

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

To be able to use this program and to invest effectively, it is important to understand some core concepts. These are essential, but relatively simple and just involve very basic maths that anyone can understand. These key concepts will allow you to understand what the different types of numbers are and how this program uses these numbers. The following sections give you an overview of these concepts with some concrete examples.

Download

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Here are the download links for InvestOrderly. This program is free to use and available for all major platforms, so you just need to download the version of the program that matches your operating system and architecture. You will also find a link to download the example data files, as these files are required if this is the first time you use this program.

Main software

Platform	InvestOrderly version 0.1.0
Windows amd64	investorderly-0.1.0-windows-amd64.zip
Windows arm64	investorderly-0.1.0-windows-arm64.zip
Linux amd64	investorderly-0.1.0-linux-amd64.tar.gz
Linux arm64	investorderly-0.1.0-linux-arm64.tar.gz
MacOS amd64	investorderly-0.1.0-darwin-amd64.tar.gz
MacOS arm64	investorderly-0.1.0-darwin-arm64.tar.gz

Example data files

Description	Example data files for version 0.1.0
Example data	investorderly-examples-20250112.zip

Licence

This software is provided “as is”, without warranty of any kind, express or implied. In no event shall the authors or its contributors be held liable for any direct, indirect, incidental, special or consequential damages arising out of the use of or inability to use this software. Permission is granted to anyone to use this software for any purpose, subject to the above disclaimer. This software cannot be redistributed without the explicit written permission from its authors.

Structure of the data files

Mon, 01 Jan 0001 00:00:00 +0000

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.

Structure of the reports

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The purpose of this program is to generate a report based on the raw data contained in the data files. The report is a collection of tables which contain calculated numbers.

Each time you run the program, it creates a new folder based on the current date, and it writes reports in this new folder. The reports are in plain text format, hence you can read these using any text editor such as Notepad++. The reports contains both the a copy of the raw data (the data as found in the input files), as well as numbers which have been calculated from the raw input data.

ChangeLog

Mon, 01 Jan 0001 00:00:00 +0000

0.1.0) 2025-01-12:
- First public version

Creating data files

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The main thing you have to do to use this program effectively is creating and maintaining good records of your transactions when you invest. This page gives you an overview of this process. Maintaining these records takes some time and effort, depending on how complicated your situation is. The good news is you do not have to have lots of investments and lots of transactions to invest effectively. For example, investing in stocks using a single low-cost global index fund is more effective than investing in multiple individual companies. A good investment strategy can be made of just a few investments, such as one ETF for each asset class you want to own. For example you just need two investments if you only want to invest in stocks and bonds, or stocks and gold. Hence keeping good records of your transactions will not be hard if you use a simple strategy.

Features

Mon, 01 Jan 0001 00:00:00 +0000

Features

Here is a description of specific features that are available in the current version of this program.

Valuations

This program allows you to know the value of your investments at various points in time based on the market prices. You may want to follow the evolution of your investments on a weekly, monthly, quarterly, or annual basis. This program allows you to know the value of your investments at various points in time, at intervals you decide.

Overview of the data files

Mon, 01 Jan 0001 00:00:00 +0000

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++.

Editing data files

Mon, 01 Jan 0001 00:00:00 +0000

Format of the data files

The data files are in the CSV (Comma Separate Values) format. This is a well know file format for spreadsheets. All popular spreadsheet software should be able to work with these files. This file format is also much easier to understand than some obscure formats. It means you will always be able to use these data files in the future, even if the software that you currently use is not maintained in the long term.

Status

Mon, 01 Jan 0001 00:00:00 +0000

This program is quite new and under active development. Hence many aspects of the program and the structure of the data are likely to change to allow new features to be implemented, base on new ideas and the feed back of the users. Such changes will be required to either simplify the program or make things more consistent. Hence you should be aware that the structure of the data may have to change in future versions. For example new columns may have to be added in the input files, or columns may have to be renamed, etc

Who this is for

Mon, 01 Jan 0001 00:00:00 +0000

Who might like this program

This program should match your needs if you meet some of the following conditions:

You want to own your data instead of giving these away to a third party company
You buy and hold investments for the long term hence you rarely sell any investment
You own a small number of investment types and you diversify through funds such as ETFs
You generate a small number of transactions, for example you invest once a month
You are happy to maintain the records for all your investment transactions on a regular basis
You own investments through multiple platforms and you want to have a consolidated view

Who might not like this program

This program will probably not match your needs if you meet the following conditions:

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Requirements

This program uses input data files provided by the user to generate the report. Just as for any accounting software, it is essential that the user provides accurate records. Hence it is really important that the user creates accurate records with the details of all historical transactions, and then keeps the input data up to date over time. It can take some effort, but it is worth it so you can get accurate reports with insights about your investments.

Working with currencies

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This program is able to work on investments involving multiple currencies. Some users will only use one currency. For example if you are based in the United States and buy index funds which are traded in USD, you will probably not have to worry about currencies. But most users will have investments involving foreigh currencies, in which case you need to understand how to deal with this situation.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Overview

It is highly recommended to start by downloading both the software for your computer as well as the example data files to see what reports the program produces based on dummy data files. This will allow you to quickly get an overview of what this program can achieve and how the input data files are structured. Based on these, you can determine if this program provides the features you need and works in a way you like.

Settings

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Settings files are used to define general settings to determine how the program should behave. Each entry contains an identifier, a value, and a free form description. The identifier needs to match exactly what the program expects, and the value needs to be in a valid format. At this stage there are very few settings, hence this is simple. Please refer to the details below for each expected setting.

Valuation

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The report contains a section with the valuation of your investments. This section shows the state of your investments at different points in time as defined in the snapshots.

Number of units

First you will find a table which shows you how many units of each investment you own. These numbers are calculated based on the transactions where you declare how many units of an asset you have bought and sold over time:

Accounts

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Accounts are logical wrappers for grouping assets such as investments. This is a structure designed to reproduce the structure of your investments in real life. Most investments are held within accounts provided by investments platforms such as banks and stock brokers. You can often have multiple accounts held with the same investment platform. For example, it is possible to have both a General Investment Account (GIA) as well as accounts for retirement with a single financial institution.

Asset allocation

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This section of the report shows you the asset allocations of your investments at various points in time as defined in the snapshots. You can use this analysis to determine if your current allocation is still in line with you target allocation. If not you can take action, either by rebalacing your portfolio or by changing the amounts your invest in each type of asset, to move towards your desired allocation.

Assets

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The assets are the investments you own, such as shares in a particular company, a fund such as an ETF, precious metals such as gold and silver, or a buy to let property. It is recommended to use the official short name for stocks (such as “AMZN” for shares in Amazon, or “VWRD” to represent the corresponding ETF). You can create your own name for investments which are not traded on a stock market. For example you can create an investment named “GOLD” that represents physical gold you have purchased with a company which sells precious metals. If you own two buy to let properties, you could decide to names these “BTL1” and “BTL2”. Also you must decide what units you use the define quantities. For example you could decide that 1 unit of gold represents either 1 gram, or 1 ounce, and you can use decimal numbers when you own fractions of units of a particular asset (such as fractional shares).

Capital gains

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

This section of the report provides information about capital gains and losses. It shows the state of your investments at different points in time as defined in the snapshots.

Warning

There are multiple ways to calculate capital gains or losses. In general users own shares that they have bought at different prices over time. There are different rules in different countries to determine which shares are considered to be sold when you dispose of shares of an investment:

Tax scopes

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A tax scope corresponds either to either a single account or to a group of accounts, which are taxed in the same way. For example, you may have multiple General Investment Accounts (GIA) for which capital gains and incomes are taxable.

Many countries also provide accounts in which investments are either not taxed or where a lower rate of tax applies. For example the United Kingdom has ISA accounts (Individual Savings Accounts) in which investments are not subject to taxes on incomes or capital gains. In this case you would create a tax scope name “ISA” and all your ISA accounts would belong to this tax scope.

Income history

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The report contains a section with the total amounts of incomes produced by your investments at different points in time as defined in the snapshots. This section focuses on the income amounts you have actually received.

Total taxable distributions per year

This table shows the total amount of taxable distributions you have received during each tax year. This section only includes the figures from taxable accounts, as these are the numbers that must be delcared in annual tax returns. The totals are per categories of incomes, as most countries often tax different types of incomes differently, and hence the totals for each type of income have to be declared in different sections of the tax return.

Expected income

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

The report contains a section which shows the estimated amount of incomes your investments are expected to produce on a regular basis, based on the number of units of each asset your currently own. This section is relevant if you invest to produce an income with the intention of being able to cover your monthly expenses. These numbers allow you to see your progress. The figures are based on the number of units you currently own for each asset so you do not have to wait for a full year before you can see the impact of your latest investiments on your future expected income.

Snapshots

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Snapshots are a list of dates for which you want the valuations, asset allocations, and total net-worth to be calculated. This depends on the granularity you want to have on the time scale. For example you may want to track your investments on a monthly, quarterly, or annual basis. Or you may want a combination, such as annually for the past 10 years and monthly for the past 12 months. You may decide to use the first or the last day of each period, such as the first day of each month, or the last day of each month, or any other day.

Expectations

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Many assets such as shares, bonds and properties pay incomes as dividends, interests, or rents. Other assets such as precious metals do not pay any income. You can provide the expected annual income for one unit of each relevant asset so the program can calculate the expected monthly average income your asset should provide based on the number of units you currently own for each asset. It allows you to know how much income your investment would produce if you stopped investing today.

Exchange rates

Mon, 01 Jan 0001 00:00:00 +0000

Overview

These files provide exchange rates between the trading currencies and the primary currency. Your primary currency is normally the currency of the country in which you live, and which you use to pay your taxes and bills. The trading currencies are the currencies in which you buy and sell each investment. The program needs to know the exchange rates between these two types of currencies, if you have bought or sold investments in currencies other than your primary currency, so it can convert the amounts automatically. Please refer to the page about currencies to learn more about the different types of currencies.

Prices

Mon, 01 Jan 0001 00:00:00 +0000

Overview

These files provide the market price of one unit of each asset you own at different points in time. You have to provide the market price of each asset for each snapshot so the program is able to determine the valuations of your assets, as well as the latent capital gains or losses. The program is currently not able to automatically retrieve these prices hence these have to be provided manually. The prices should be expressed in the currency in which the investments are bought and sold. For stocks and funds, this is the trading currency. In other words, you should provide the price using the currency which you used to buy and sell each asset. The program will use the exchange rates provided to automatically convert the trading currency into the primary currency.

Transactions

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The program uses transactions in the data files to determine the number of units of an asset held in an account, and to calculate the total cost of ownership, including the purchase price, platform fees, and taxes.

Transactions must be recorded for any event that changes either the number of units held for a particular holding, or the cost for having this holding, or both. For example a transaction can be the purchase of a stock. This increases the number of units held for an holding, and the price paid to have this holding. A transaction can be the disposal of stocks. This reduces the number of units held, and decreases the price of ownership of the remaining units. Some platform apply custody fees for having a particular asset in a particular account. In that case a transaction can correspond to a monthly fee. This event does not affect the number of units held, but it increases the cost of ownership of the asset. A stock split increases the number of units held without affecting the cost of ownership.

Distributions

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Distributions are events corresponding to the payment of an income based on the ownership of an asset. There are different types of distributions: dividend payment, property income distributions (for REITs), interests, etc. The type of each distribution is important and different types of incomes are treated differently for tax purposes. For example dividends, interests, and property income distributions can be taxed differently, hence it is important that the program is able to determine the total incomes for each of these categories.