Frugal user's guide // Home
Rev. 2010-04-18:1
Copyright (C) 2009-2011 Thomas Larsson.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This document is part of the Frugal Users Documentation. The document is released under the GNU Free Documentation License.

Welcome to the User's Guide. This guide is available online from http://www.samoht.se/frugal (find the link to the User's Guide). The document will be updated and expanded, so please download the latest version from that source.

This guide is compatible with Frugal version 0.14 or later. It is currently not updated for 0.16, which adds the stock portfolio plug-in. Additional updates have been made for 0.21.

Known bugs

Note: Frugal version 0.15 and 0.16 does not show the "Update" menu when a new version of Frugal is available. This bug is under investigation and seems to be related to the webbrowser module. Please use the "Search for updates.." function available in the About menu to find new updates.

Contents

  1. Introduction
  2. Features
  3. Installation Instructions
  4. Getting Started
  5. Plug-ins
  6. Use cases


Introduction
Frugal is a simple yet powerful personal finance and stock portfolio management application. It provides quick on-line stock quote and currency rate updates and easy to understand graphical and textual views of your financial situation.

Frugal is quite dynamic and can without change be used in a number of scenarios,

  • Simple personal finance program
    By entering your income and expenses, Frugal will show you your current account balance and cash-flow, i.e. how much money you have left during and at the end of the month. Frugal also shows you how much money you spent on housing, travel, entertainment, food etc to help you manage your spendings. It will also show you the sources of your income and how your financies change over time.

  • Stock portfolio management program
    If you have a stock account or accounts with one or several brokerage firms, easily mirror these accounts in Frugal. Frugal will then give an overview of your total investments and cash. Buy and sell stocks in Frugal to follow the transactions you make with the brokerage firms and let Frugal automatically update the stock quotes and currency rate changes. Then see your investments in relation to cash, view how the portfolio changes over time and always have a complete and up-to-date view of your current assets.

  • Complete financial application
    Get the full view of your complete financial situation - easily. Let Frugal track your income, expenses and your investments. Then mirror your loans, add the house you own and your car. You will see all your assets and liabilities in relation to each other. Again, track where your income is coming from, where you spend your money, your net worth and plot it in details or over time.

The project has its beginning in my need of a simple personal finance program to track my monthly expenses. The software available online at the time of Frugal's birth was more complex than what I needed, and yet too trivial in its presentation. So I decided to write my own program. The origins can be traced back to 2004 when I set up an SQL database to store my income and expense transactions. I parsed the database with the help of PHP and Apache to generate color-coded web pages. In 2006 my needs had moved beyond what web-page generation could offer and I wrote a program in Python to handle the data (now stored as xml). This version of Frugal survived until 2008 when I did a complete refactoring of the software and joined Sourceforge. Frugal is since then delivered by the "frugal" project at Sourceforge.net.

Frugal is developed in the programming language Python. Python is a cross-platform programming language that allows Frugal to work on almost any computer. Including Windows, Linux and MacOS.

The program Frugal is free software as defined by the GNU General Public License. It basically means that you, as the user, are allowed to use and copy the program - but not to sell it. Please refer to full the license text for details.


Features

Internet security/share price update

Update May 2010, due to an update online outside the control of Frugal, the ISIN update has stopped working. Please update to version 0.24 (or later) of Frugal and instead of ISIN use the Morningstar ticker. Find the Morningstar ticker for any given fund on Morningstar's web site or Google for the fund name and the word "Morningstar". The ticker is a 10 character alpha numeric string.

Frugal versions prior to 0.19 support online prices updates for stocks and mutual funds through Yahoo! Finance using ticker symbols. For example Google Inc has the ticker symbol GOOG. By adding a share to your Frugal project called "GOOG", Frugal can update GOOG's share price when you ask the program to. Frugal will at the same time update GOOG's company name to "Google Inc." and show that name instead of "GOOG" in your project.

Please see note above, ISIN currently not working! This feature has been expanded in version 0.19 to also support ISIN numbers. An ISIN number is not the same as the ticker symbol as the ISIN is unique to a security, but is not connected to the market the security is traded on. So for example Google might be traded on several markets, and the ticker symbol will then be different on each of those markets, but the ISIN for Google will be the same on every market. Therefore the ISIN number is not as useful to find the share price as the unique ticker symbol. However, every security and mutual fund that is not traded on a stock market also has an ISIN number. This ISIN number can be used to find the off-market price of those securities. In practice, it is most useful for mutual funds. Enter the ISIN number for your mutual funds in Frugal, and Frugal will download the latest price when you update the ordinary share prices. After update, the ISIN is exchanged with the full security name in the program.

Internet currency rate update

Frugal supports download of currency rates from the European Central Bank. This adds updates of many common currencies, USD, JPY, all European currencies and more. Any of the supported currencies can be used for new projects and more can be activated later.


Installation Instructions
Installing Frugal is simple, follow the steps below to install the program on your computer.

Windows Vista/XP

Prerequisites

If you choose to use the Windows executable package, you may skip this section and go straight to Download and install Frugal below.

Frugal depends on Python. Please follow the steps to download and install the required packages.

  • Download Python(x,y) web edition (xyweb) from http://www.pythonxy.com/download.php
  • Start the installation by running the downloaded xyweb-[version].exe file
    1. Choose Full Edition and click Download
    2. Click Yes when asked if the installer should start
    3. In the "Choose Components" window, select Minimum as the "type of install" and then expand the "Python" branch in the "optional components window" and select components "wxPython", "NumPy" and "Matplotlib" (package "Nose" will be automatically selected when "NumPy" in selected)
    4. Finish the installation.

Download and install Frugal

  • Download Frugal from http://www.samoht.se/frugal/ or directly from Frugal project's Sourceforge.net page. The project's package is a single zip file.
  • Unzip the file into C:\Programs (a sub-folder called "frugal" will be created).
  • If you use the Windows executable package, double-click on the file frugal.exe inside "C:\Programs\frugal\exe".
    If you installed Python and run Frugal from source code, double-click on the file frugal.py located inside "C:\Programs\frugal\src" to start the program.

Mac OS X

Frugal is (starting with version 0.24) delivered with a Mac OS X application. Please download the Frugal "macosx" package and run the application from within the exe directory.

Limitation: The bundled version of wxPython does not support unicode characters. If you need to use unicode characters (non-US characters) in Frugal, please follow the instructions for "Other operating systems" and run Frugal from source code. Please note that you need to use the python version 2.5, i.e. start Frugal with the command "python2.5 frugal.py" from the frugal/src directory.

Linux

Prerequisites

Frugal has successfully been run on Ubuntu 8.10, 9.04 and 9.10 with the following additional packages installed. Install the packages using System->Administration->Synaptic Package Manager.
  • python-numpy
  • python-wxversion
  • python-matplotlib

For other Linux distributions than Ubuntu, the procedure will be similar. For example in Debian please use the APT package manager to install the above mentioned packages.

Download and install the Frugal package

  • Download Frugal from http://www.samoht.se/frugal/ or directly from Frugal project's Sourceforge.net page. The project's package is a single zip file (or .tar.gz).
  • Unzip the file into your "home", it will create a sub-directory called "frugal".
  • Double-click on the file frugal.py located in the directory "[home]/frugal/src".

Other operating systems

Prerequisites

The prerequisites are similar to those above. Please find more detailed information from the following web pages to download the required software packages.

Download and install the Frugal package

The Frugal program package contains Python source code that is platform-independent. Download Frugal from http://www.samoht.se/frugal/ or directly from Frugal project's Sourceforge.net page. The project's package is a single zip file (or .tar.gz). Unzip the file and run "python frugal.py" in the "src/" directory.


Getting started
Frugal is at its core a double-entry accounting program. That means that every transaction has a source and a destination. It makes sense, money does not appear out of nowhere. It always has a source. A practical example is when you are paid salary from a company. The source of the transaction is your employer and the destination of the transaction is your bank account. The same is true when you buy a product in a store, the source is your bank account and the destination is the store. Money flows between sources and destinations in financials, it flows the same way in companies and it flows in that way also in your personal accounts. Frugal will help you keep track of those flows!

More information and background about debits and credits in double-entry accounting is available from Wikipedia at http://en.wikipedia.org/wiki/Debits_and_credits.

A tour of Frugal

At this point you should have started the program and see the following window on your computer monitor. It may look a little bit different depending on your operating system. The screen-shots in this guide are all from Ubuntu.

The menu bar

There are four menus on the menubar File - View - Project - About. The left-hand part of the window (locate the text "Frugal") is the navigation tree that will activate when a project is opened or created. The right-hand part of the window is the information area. This is where all information will be displayed.

Familiarize yourself with the menubar. The File menu contains functionality for New, Open and Save project, and an Exit item to exit the program. The View menu is a radio button menu where the preferred way of viewing information in the right-hand information area is set. There are three time perspectives, "Detailed" is the current status as of now. "Monthly" and "Yearly" historical views show the information over time. The first three menu items are textual views and the last three are graphical views. The Project menu collects actions that can be done to the open project. The first item will download the current stock quotes from Yahoo! and currency rates from the ECB. The information is automatically stored in the program. The second item will trigger a re-calculation of the whole project. This is necessary when new data is added. Because the calculation may take a few seconds it has to be manually triggered in order to save time when many transactions or data are added. The About menu includes information about Frugal and the option to search online for updates.

An automatic update search is triggered when Frugal is started and will run in the background. If a new version of Frugal is found, an additional menu called "Update" will be shown on the menubar. Currently its only item will show information about the new version.

Starting in version 0.15, the about menu has an item called User's Guide (web). It opens a web browser to show this page.

Open the demo project

From the File menu, choose "Open project...". Locate the "demo" directory (In Windows it is located in "C:\Programs\frugal\demo" or in Linux it is located in "[home]/frugal/demo"). The navigation tree will update and show all installed plug-ins.

The default plug-ins in Frugal 0.14 are "Balance Sheet", "Income Statement", "Add Transactions", "Add Data" and "Raw Data". To activate a plug-in, click on its name. To see the functions inside a plug-in, click on the small triangle (as in the screen shot) or the plus sign (in Windows) next to the plug-in name.

Open the "Balance Sheet" plug-in and click on the triangle next to its name. The functions are shown in the tree. Click on a function and see the information being updated in the information area. Go to the menubar and change the View. Click on different functions again and familiarize yourself with the viewing options. Do the same with the "Income Statement" plug-in. Both of these plug-ins are for viewing data only and will not allow any user changes.

Now let us shift focus to the "Add Transactions", "Add Data" and "Raw Data" plug-ins.

"Add Transactions" is a plug-in to add simple transactions to the current Frugal project. This is the plug-in most often used to add data. "Add Data" is a plug-in to add data - other than transactions - to the project. This includes new bank accounts, assets such as a car or a house, stocks, mutual funds and so forth. The "Raw Data" plug-in is to view and change data stored in the project. "Raw Data" is for advanced changes and will not be mentioned more in the tour.

Add data to the demo project

To demonstrate some of the functionality of Frugal the demo-tour will now do a common use case. The goal will be to create a new bank account from January 15, add a transaction from the savings account to the new account in March. Add a new share in April that will be bought in April. In the end of April we will sell half of the shares we bought. And at last, we will update the project with the latest share quotes and currency rates found online.

Add the bank account

Click on the small triangle next to "Add Data" to show the functions of the "Add Data" plug-in. Select "Add Bank Account" to show the new account information.

Type Account name "Mars Banking Society savings", select Account currency as "EUR", Opening balance "2000" and Opening date "20090115" which translates to January 15th, 2009. Click Add and then OK.

The account has now been added to the demo project. It will not yet be displayed in the balance sheet or on the income statement. This is due to that the new account is stored in the program's memory, but has not been used in the result calculations. Frugal does not automatically re-calculate the results when new data is added because such calculations can take several seconds.

Now, open the menubar menu "Project" and click on "Re-calculate result". The program calculates the new data and returns. Click on "Balance Sheet" and then "Current Assets". The account has appeared in the detailed list view (change view from the menubar item "View" and then "Details").

Transfer money to the new account

The balance sheet shows that the savings account holds 2500 EUR. Let us transfer 500 EUR to the new bank account in the middle of March. Expand the "Add Transaction" plug-in and select "Transfer Money".

Change the date to "20090312". Write description "Transfer 500 EUR to Mars". Select "Savings Account" as the account to transfer money from and "Mars Banking Society savings" and the account to transfer money to. Enter the amount 500 and click Add and then OK. Re-calculate result as described in the previous step.

Open the balance sheet and verify that the money has been transferred from the Savings account to the Mars Banking Society. The balance of the Savings account should show as 2000 EUR and the Mars Banking Society's account as 2500 EUR.

Add a share

The Mars Banking Society has suggested that the demo person (us) should buy the Airbus parent EAD on the open market. On http://uk.finance.yahoo.com we find that EADS is sold on the German stock market (XETRA) as symbol EAD.DE.

On Yahoo! Finance, view the historical prices for EAD.DE. On April 21st, EAD.DE closed at 9.60 EUR. As we will buy the share on the 22nd, we use April 21st as the initial date to have one day "buffer".

Type share symbol "EAD.DE". Click on "Get latest price from Yahoo!" and the "Initial price" should update with todays price. Select share type "Stocks", share currency "EUR", initial date "20090421" and initial price "9.60". Click Add and then OK.

The EAD share is now stored in memory but can not be used until the project result is re-calculated. Re-calculate the project (menubar item "Project").

Buy shares

Buying and selling shares is done from the same plug-in function. Go to the plug-in "Add Transactions" and select the function "Buy / Sell Share". The screen should look as above.

Looking back on Yahoo! Finance we see that EAD.DE closed at 9.93 EUR on April 22nd. For simplicity we will use that price as the price we bought the shares for. In reality you will of course use the price at which your order was closed at and not that sessions closing price.

Change date to "20090422" and description to "Bought EADS recommended by MBS". Select transaction type "Buy" and account "Mars Banking Society savings". The bank account will be the account that is debited when the shares are bought. Choose share "EAD.DE", type share price "9.93", number of shares "200" and commission "10". Commission is the cost of buying the shares. A share transaction always costs something, usually around 10 EUR. The amount will be drawn from the selected account (additionally to the 200 * 9.93 EUR). Click Add and then OK.

Again re-calculate the result.

Go to the balance sheet and view the current assets. Notice that you now own 200 EAD.DE shares at 9.60 EUR per share. Notice also that the Mars Banking Society account has 504 EUR left. In the menubar, choose "View" and then "Detailed plot". In the tree, click on "Balance Sheet" and then "Current Assets". Look at the pie chart.

Sell shares

On the 29th of April the demo person sold 100 of the EAD.DE shares at 11.32 EUR per share. The same function of the "Add Transaction" plug-in is used for selling as buying, i.e. "Buy / Sell Share".

Type in date as "20090429" and description "Sold half of EAD.DE". Select transaction type "Sell" and for account choose the "Mars Bank Society savings". Select share "EAD.DE". The share price on the 29th was "11.32", number of shares sold was "100" and for commission we use "10" EUR as in the previous example. Click Add and then OK.

Re-calculate the project's result.

Go back to the balance sheet to verify that the transaction took place.

Update share quotes and currency rates

For the last part of the tour we will take a closer look at the online update of stock prices and currency rates. As you have probably noticed stocks are stored with symbols instead of with full company names. That is the reason for that the EADS share was stored under its stock symbol "EAD.DE" instead of "EADS" in the earlier part of the tour. The reason for this is to allow Frugal to find the latest share price online. If another name was used the automatic update fails for that particular share.

Frugal supports stock symbols or ISIN names for shares that should update prices online.

Go to the balance sheet and look at the current assets. The demo project has four shares (five including EAD.DE) listed as symbols. If your PC is connected to the internet, go to the menubar item "Project" and choose "Download online quotes". When Frugal is done after a few seconds, click on "Balance Sheet" and then again on "Current Assets".

Notice that the share symbols have change to the full company names. Notice also that the share prices have updated. Behind the scenes the currency rates have also updated so the USD-EUR exchange rate was updated to the most current rate.

Stock quotes and currency rates can be added manually. The manual plug-in can also be used to view the latest quotes and their dates. Go to the plug-in "Add Data" and click on "Add Stock Quotes". Notice that the latest column shows the latest quotes and dates. Change function by clicking on "Add Currency Rates" and notice the latest column again.

End of the tour

This concludes the demo tour of Frugal. You have seen how to register a new bank account, transfer money between accounts, add a new share, buy a share, sell a share and update stock quotes online. Good luck!


Frugal plug-ins
Frugal is delivered with five standard plug-ins. A plug-in in Frugal is a group of functions which the user can use to either view or change the open project's data. The plug-in concept allows for addition and removal of plug-ins which means that later versions of Frugal will have additional plug-ins.

All loaded plug-ins are shown in the left-hand side tree. Each header represents one plug-in and each plug-in can be expanded in the tree to reveal its functionality. The five standard plug-ins are visible in the image below.

Balance Sheet

The balance sheet displays your net worth. That is the assets that you own minus the liabilities that you have to other people and/or banks. The main plug-in view is a summarized balance sheet stating your net worth and showing how your money is divided into current assets, non-current assets and liabilities.

The detailed views, as available through the plug-in's sub-functions, display each asset group in detail. For example all current assets and their worth.

The balance sheet's detailed views support all textual and graphical views. The summary supports on the textual view.

The purpose of the balance sheet is to see your net worth. If your net worth is zero, you own nothing (you may drive a car, but it is not owned by you..). If it is less than zero, you are in a very bad financial shape. Then you have liabilities (loans) that are not covered by your assets and you may face a liquidity crises and bankruptcy.

Your minimal financial goal is to have a large enough net worth to survive bad times and possible job losses. What that minimum amount is, is hard to say. Many people state that at least six months of salary is necessary to cover most unforseen expenses.

Income Statement

The income statement displays the current year's net result. The detailed views of the sub-functions display your income and costs in detail.

The income statement's detailed views support all textual and graphical views. The summary supports detailed text view.

The purpose of the income statement is to show you your net result. The net result is your income minus your expenses. That is, if you have a negative net result you spend more money than you earn. In time this means that you will run out of money. Your result must be zero or positive if you want to survive financially.

Many suggest that you should have at least a 10% net result to secure long term financial survival.

Add Transactions

The Add Transactions plug-in is the primary plug-in for adding data to Frugal. It covers most use cases divided into different sub-functions in order to only ask the user for the relevant data.

Add Data

The Add Data plug-in is used to add bank accounts, stocks, liabilities, stock quotes and currency rates to the current project. Stock quotes and currency rates are better added automatically with the online update functionality (menubar->Project), but this plug-in supports manual additions of stock quotes and currency rates if the automatic update fails.

New feature in Frugal 0.19; From version 0.19 of Frugal, mutual funds and stocks written as ISIN are supported for automatic price updates online. That means that either use the Yahoo! ticker symbol or the full ISIN number (the ISIN is necessary to support mutual fund price updates).

Please note: "Add bank account", "Add share" (0.20 and later) and "Add asset / liability" has input boxes called "Opening balance" and "Initial balance". These boxes give the possibility to add an inital balance to an account or share held. That is, if you for example want to define your stock portfolio starting January 1st, 2010 - that has 5000 USD of cash and 100 shares of GOOG, you;
  • In "Add share" write the symbol "GOOG", type "Share", currency "USD", date "20091231", intial price what your average cost per share is and "Initial balance" 100.
  • In "Add bank account" write account name, currency "USD", opening balance 5000 and opening date "20091231".

These two transactions are now "invisible" in Frugal. That is, you have not created any income or expense. Per definition this shall be impossible to do in a double accounting program. But is possible in Frugal in these three cases in order not to give an "incorrect" income statement for the previous year (in this case 2009). Please only use "Initial balance" and "Opening balance" not equal to "0" for years that are not part of your economical scope.

Raw Data

The Raw Data plug-in displays all data that is part of the project. The data consists of transactions, quotes, currencies and accounts. All data in the project can be edited from within this plug-in (but no data can be deleted). Please use this functionality with care as there is no consistency check of the changed data and an incorrect change may break the project. Please use the Add Transaction or Add Data plug-ins to change the project data.


Use cases

Brief guide of how to setup of your project

Basic strategy

If possible, start from the beginning of the year. That is, at the time of writing this sentence it is January 2010 and therefore I want my portfolio to be complete and exist on January 1st, 2010. In order for the portfolio to be "complete" on January 1st this year, I will define all assets on December 30st, 2009. And I will define all share quotes on December 31st, 2009. (calculation reasons to why the assets shall be defined one day before the share quotes) That way the creation of the assets took place on the last day last year, which means they exist on the first day this year - and no transactions took place on this side of the year.

If you choose to start on any month, follow the same strategy. (i.e. to define assets two days before the 1st, and share prices one day before.)

Basic tools

Create your project from File->New project. Create and select a new directory for the project, and choose your base currency. Click OK.
  1. Now it is time to define your assets. First go to Add Data->Add Bank Account. Write the account name and select the currency. As I want to account balance to be what I had on the account January 1st, 2010, I add that amount to "Opening balance". Opening date shall be "20091230" as that is the day before I want the portfolio to be created.

    Repeat for every account.

  2. Then continue with your shares. Go to Add data->Add share. Write the share symbol (ticker symbol) or ISIN number (if it is a mutual fund) to support automatic updates of share prices, or any name (will not support online updates). Select share type and share currency. Initial date shall be "20091230" and initial balance the number of shares that you owned on January 1st, 2010. Initial price is the average price you paid for those shares. Remember to include the commission in that calculation (i.e. if you bought 10 shares at 5 EUR, and paid 5 EUR commission the total amount paid was 10 * 5 EUR + 5 EUR = 55 EUR, equal to an intial price per share of 5.50 EUR).

    Repeat for every share you owned on January 1st, 2010.

    Go to the menu bar, Project->Re-calculate result.

  3. Go to Add Data->Add Stock Quotes. Update the "Date" column with "20091231" for all shares. Find the share price for those assets on December 31st, 2009, and add the price. Click "Add".

    Go to the menu bar, Project->Re-calculate result. Then File->Save project.

    Done.

End of document.

Get Frugal at SourceForge.net. Fast, secure and Free Open Source software downloads