User Guide : Concepts

General Workflow

The general workflow in UnderBudget is as follows:

1. Create a budget
   1. Define estimates
   2. Define assignment rules
2. Import transactions
   1. Transactions are assigned, via rules, to estimates
   2. Ending balances are calculated
3. View analysis results
   1. Assignments
   2. Estimate progress
   3. Balance impact

Budget

The primary concept or idea in UnderBudget is a budget. A budget is a list of estimated incomes and expenses to occur over a specific period of time.

A few things about budgets:

• UnderBudget operates on budgets individually.

  That is, a single budget is opened and analyzed. If another budget is to be analyzed, it must be opened and analyzed within its own context, or session. UnderBudget does not perform any kind of rollover from one budget to another.

• Each budget is stored in its own file/location.

  The type of file may vary according to the user's choice when saving a budget. Currently supported file types are xml and encrypted.

• Budgeting periods can cover any range of dates.

  Supported period types include:

  • literal month (1st of month to the end of the month)
  • literal year (1st of the year to the end of the year)
  • paydate month (1st payday of the month to the day before the 1st payday of the next month)
  • custom (specified start date to specified end date)

• The initial balance (that is, the amount of money possessed at the beginning of the budgeting period) must be specified manually.

  Since UnderBudget will only know the sum of increases and decreases, based on estimates and imported transactions, it needs the initial balance to be able to calculate the ending balances.

Estimates

An estimate is a currency value specified in advance, indicating an expected or planned income, expense, or transfer.

There are three types of estimates, and the type must be defined when creating an estimate.

• Income estimates : represent a planned increase of funds (e.g., salary/paycheck, gift)
• Expense estimates : represent a planned decrease of funds (e.g., utility bill, groceries)
• Transfer estimates : represent a planned transfer of funds from one account to another in a way that does not impact the amount of available funds (e.g., ATM withdrawal, credit card payment) (see [Transfer Estimates Best Practices](Best Practices %3a Transfer Estimates))

Estimates can be grouped or categorized. Estimates that represent groups or categories do not have any impact on budget analysis. They are used solely for estimate organization.

When a transaction is assigned to an estimate, the value of the transaction (or sum of assigned transaction values) is considered the actual amount, as opposed to the estimated amount (which is specified by the user). The expected amount of an estimate is either the estimated or the actual amount, depending their values when compared against each other. The expected amounts are used to calculate the expected ending balance, which may differ from the estimated ending balance and the actual (or current) ending balance. For example, when only $25 has been spent on a $100 expense estimate, UnderBudget still considers $100 to be the expected expense and subsequently decreases the balance by $100. However if $125 has been spent on a $100 expense estimate, UnderBudget decreases the balance by $125 to reflect the overbudget expense. (see Ending Balances below for more information)

Estimates can be defined with a due date (such as a utility bill). UnderBudget will then give an indication if the due date is approaching, or if it is past-due and it has no imported transactions assigned to it (i.e., the utility bill has not been paid).

UnderBudget allows for estimates to be marked as final, or complete. This allows the user to indicate that all expected activity against the estimate is finished, and UnderBudget can alter the ending balance accordingly. For example, an expense estimate was created for $100. Only $75 was spent. By marking the estimate as complete, UnderBudget will raise the expected ending balance by $25 dollars, since that part of the estimate was not used. Conversely, if an income estimate was created for $500 and only $400 was earned, the expected ending balance is lowered by $100 if the estimate is completed. If the budgeting period occurs in the past (i.e., the budget is being analyzed retrospectively), all estimates are automatically considered final/complete.

Assignment Rules

In order for UnderBudget to be able to assign imported transactions to estimates, it must know the criteria to use. An assignment rule specifies transaction conditions and the estimate to which matching transactions will be assigned. When multiple conditions are defined for a single rule, all conditions must be met for the transaction to be assigned by that rule. In order to create an either-or type of rule, two separate rules must be defined.

The following transaction fields can be used in rule conditions: transaction payee, transaction memo, withdrawal account name, and deposit account name.

Each condition requires an evaluation operation and . Supported operations include: begins with, ends with, equals (case sensitive), equals (case insensitive), and contains.

Some example rule conditions:

• Payee equals (case insensitive)
• Deposit ends with "Groceries"
• Deposit ends with "Dining" and memo contains "anniversary"

Each rule is associated with one, and only one, estimate. However, an estimate may have many rules associated with it.

When assigning a transaction, it is evaluated against the defined rules in the order in which they are defined. When a matching rule is found, the transaction is assigned and the next transaction is assigned. Rules can be reordered by the user. This allows for a generic rule to be created and placed towards the end of the list, with a more specific rule (associated with a different estimate) placed towards the beginning of the list to catch particular transactions.

Transactions

Transactions represent a transfer of funds from one account to another. Depending on the withdrawal and deposit accounts, a transfer may represent...

• an income (i.e., income account to an asset account)
• an expense (i.e., asset account or liability account to an expense account)
• a refund (i.e., expense account to an asset or liability account)
• a loan payment (i.e., asset account to a liability account)
• a transfer (i.e., asset account to another asset account)
• a loan (i.e., liability account to an asset account)

UnderBudget does not have any means for defining transactions. Instead, transactions are obtained by importing from an external source. This may be a checkbook/ledger application like GnuCash, Quicken, etc. or an online source like mint.com, bank websites, etc. The following data types are supported:

• GnuCash uncompressed XML files
• CSV (comma separated values) files (such as those exported from mint.com and bank websites)

Future support is planned for importing from QIF and OFX files, and from relational databases (SQL).

Balances

In contrast to the initial balance (the sum of funds available at the beginning of a budgeting period), an ending balance represents the sum of funds available at the end of a budgeting period. UnderBudget calculates three types of ending balances: estimated ending balance, actual (or current) ending balance, and expected ending balance.

Estimated Ending Balance

The estimated ending balance is calculated by increasing the initial balance value by the sum of all income estimates and decreasing by the sum of all expense estimates.

Actual Ending Balance

The actual ending balance uses the values of assigned transactions to increase and decrease the initial balance value. Note, transactions that do not get assigned (don't match any assignment rule) will not be included in the actual balance. This will result in the calculated actual balance not matching the real sum of available funds (which may mean a missing or incorrect assignment rule).

When calculated within the budgeting period, the actual ending balance represents the current, to-date balance, which may greatly differ from the estimated or expected ending balances. When calculated after the budgeting period, the actual ending balance is the actual ending balance. As a sanity check (to make sure that all estimates and rules are set up correctly), the actual ending balance should be continuously compared against the real sum of available funds as they should always be exactly the same.

Expected Ending Balance

The expected ending balance is the key component in UnderBudget's analysis results. Before the budgeting period starts, the estimated and expected ending balances are identical. After the budgeting period ends, the actual and expected ending balances are identical. During the budgeting period, the expected ending balance represents the ending balance that is expected as a result of to-date progress on each estimate. That is, over-budget expense estimates decrease the expected ending balance while under-estimated incomes increase the expected ending balance.

Putting it all together, consider the following set of estimates and each of their affect on the ending balances, given an initial balance of $100.

Estimate Type	Est. Amt.	Act. Amt.	Exp. Amt.	Est. Balance	Act. Balance	Exp. Balance
Income (under)	$100	$50	$100 (still expects $100)	$200	$150	$200 (still expects $100+$100)
Income (over)	$100	$125	$125 (now expects $125)	$200	$225	$225 (now expects $100+$125)
Income (final)	$100	$75	$75 (knows it is $75)	$200	$175	$175 (knows it is $100+$75)
Expense (under)	$50	$25	$50 (still expects $50)	$50	$75	$50 (still expects $100-$50)
Expense (over)	$50	$75	$75 (now expects $75)	$50	$25	$25 (now expects $100-$75)
Expense (final)	$50	$20	$20 (knows it is $20)	$50	$80	$80 (knows it is $100-$20)
Transfer (under)	$50	$45	$50	$100	$100	$100 (no impact from transfers)
Transfer (over)	$50	$55	$55	$100	$100	$100 (no impact from transfers)
Transfer (final)	$50	$40	$40	$100	$100	$100 (no impact from transfers)