This is bank-buddy.info, produced by makeinfo version 7.1.1 from
bank-buddy.texi.

Copyright © 2025 James Dyer

   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".
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Bank Buddy: (bank-buddy). Enhanced financial analysis for Emacs.
END-INFO-DIR-ENTRY


File: bank-buddy.info,  Node: Top,  Next: Introduction,  Up: (dir)

Bank Buddy
**********

Copyright © 2025 James Dyer

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

* Menu:

* Introduction::                Overview of Bank Buddy
* Installation::                Installing Bank Buddy
* Quick Start::                 Getting started with Bank Buddy
* CSV Format::                  Understanding the required CSV format
* Report Generation::           Creating financial reports
* Report Sections::             Understanding the generated reports
* Transaction Categories::      Customizing and managing categories
* Subscription Detection::      How recurring payments are identified
* Category Management::         Using bank-buddy-cat-mode
* Customizing Visualizations::  Working with gnuplot files
* Customization::               Customizing Bank Buddy
* Key Bindings::                Keyboard shortcuts
* Comparison::                  Comparison with other financial packages
* Troubleshooting::             Solutions to common problems
* Index::                       Complete index


File: bank-buddy.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top

1 Introduction
**************

Bank Buddy is an Emacs package that provides comprehensive financial
analysis and reporting capabilities for your bank statements.  It
processes CSV bank statement data, categorizes transactions using
customizable patterns, and generates detailed reports in Org-mode
format.

Key Features
============

   • *Asynchronous Processing:* Efficiently handles large bank
     statements without blocking Emacs
   • *Smart Transaction Categorization:* Auto-categorizes transactions
     based on customizable regex patterns
   • *Comprehensive Financial Reports:* Generates detailed reports in
     Org-mode with various analysis sections
   • *Interactive Category Management:* Edit and refine categorization
     patterns directly from reports
   • *Data Visualizations:* Generates charts and graphs using external
     gnuplot scripts
   • *Subscription Detection:* Automatically identifies recurring
     payments and estimates monthly costs
   • *CSV-focused Analysis:* Designed specifically for bank statement
     CSV files

Why Bank Buddy?
===============

Bank Buddy was developed to solve specific pain points in analyzing
personal bank statements:

  1. *Automatic Categorization:* Most financial tools require manual
     categorization or complex rules for imports.  Bank Buddy learns and
     improves categorization over time.
  2. *Focus on Insights:* Unlike general accounting systems that focus
     on balancing books, Bank Buddy helps you discover spending patterns
     and optimize your finances.
  3. *Real Bank Statement Analysis:* Designed to work directly with
     actual bank statement CSV exports, not idealized financial data.
  4. *Low Maintenance:* No need to manually enter transactions or
     maintain a complex financial system - just periodically analyze
     your bank statements.
  5. *Emacs Native:* Built entirely within the Emacs ecosystem,
     leveraging Org-mode for rich, interactive reports.
  6. *Flexible Visualization:* Uses external gnuplot scripts for easy
     customization of charts and graphs.


File: bank-buddy.info,  Node: Installation,  Next: Quick Start,  Prev: Introduction,  Up: Top

2 Installation
**************

MELPA
=====

The recommended way to install Bank Buddy is through MELPA:

     M-x package-install RET bank-buddy RET
     (with-eval-after-load 'bank-buddy
       (add-hook 'org-mode-hook 'bank-buddy-cat-maybe-enable))

Manual Installation
===================

  1. Download the repository or clone it:
          git clone https://github.com/captainflasmr/bank-buddy.git

  2. Add the directory to your load path and require the package:
          (add-to-list 'load-path "/path/to/bank-buddy")
          (require 'bank-buddy)
          (with-eval-after-load 'bank-buddy
            (add-hook 'org-mode-hook 'bank-buddy-cat-maybe-enable))

Dependencies
============

   • Emacs 26.1 or later
   • async.el
   • org-mode (for reports)
   • gnuplot (system installation for visualizations)

Installing Gnuplot
==================

Bank Buddy uses gnuplot for creating visualizations.  You need to have
gnuplot installed on your system:

   • Linux: ‘sudo apt install gnuplot’ (or equivalent for your
     distribution)
   • macOS: ‘brew install gnuplot’
   • Windows: Download from http://www.gnuplot.info/


File: bank-buddy.info,  Node: Quick Start,  Next: CSV Format,  Prev: Installation,  Up: Top

3 Quick Start
*************

  1. Export your bank statement as a CSV file
  2. Run: ‘M-x bank-buddy-generate-report’
  3. Select your CSV file
  4. Choose where to save the Org-mode report
  5. Open the generated report

   Note: Bank Buddy will create external gnuplot script files (.gp) and
data files (.dat) alongside your report.  These can be edited for
customization.


File: bank-buddy.info,  Node: CSV Format,  Next: Report Generation,  Prev: Quick Start,  Up: Top

4 CSV Format
************

Bank Buddy expects CSV files with at least the following columns:
   • Transaction date
   • Transaction description
   • Debit amount

   Different banks format their CSV exports differently.  You may need
to preprocess your CSV to match this format.

   For optimal results, your CSV should include:

Date format
     YYYY-MM-DD format is preferred
Description
     The merchant name or transaction description
Amount
     Positive values for debits (money spent)


File: bank-buddy.info,  Node: Report Generation,  Next: Report Sections,  Prev: CSV Format,  Up: Top

5 Report Generation
*******************

To generate a financial report:

     M-x bank-buddy-generate-report

   You'll be prompted to select an input CSV file and specify the output
Org file.

   The package processes the data asynchronously, so Emacs remains
responsive even with large CSV files.  When processing is complete,
you'll be asked if you want to open the generated report.

Generated Files
===============

Bank Buddy creates several files during report generation:

   • The main .org report file
   • Gnuplot script files (.gp) for each visualization
   • Data files (.dat) containing the raw data for plots
   • PNG image files for the generated charts

   All these files are preserved for later customization or
regeneration.

Command Options
===============

‘bank-buddy-generate-report’
     Generate a financial report from a CSV file


File: bank-buddy.info,  Node: Report Sections,  Next: Transaction Categories,  Prev: Report Generation,  Up: Top

6 Report Sections
*****************

The generated report is an Org-mode file with the following sections:

Summary Overview
================

Shows transaction count, date range, total spending, and average
spending metrics.

     * Summary Overview

     - *Total Transactions Analyzed:* 137
     - *Date Range:* 2024-01-01 to 2024-03-31 (91 days)
     - *Total Spending:* £4,235.78
     - *Average Daily Spending:* £46.55
     - *Average Weekly Spending:* £325.83

Top Spending Categories
=======================

Lists the highest spending categories with percentages and averages.

     * Top Spending Categories

     1. /hse/ *Housing:* £1,200.00 (28.3%)
        - Monthly avg: £400.00, Yearly avg: £4,800.00
     2. /fod/ *Food:* £875.50 (20.7%)
        - Monthly avg: £291.83, Yearly avg: £3,502.00
     3. /utl/ *Utilities:* £432.25 (10.2%)
        - Monthly avg: £144.08, Yearly avg: £1,729.00

     #+ATTR_ORG: :width 600
     [[file:financial-report--top-spending-categories.png]]

     Generated from gnuplot script: [[file:top-spending-categories.gp]]
     Data file: [[file:top-spending-categories.dat]]

Monthly Spending Patterns
=========================

Displays spending over time with a visual category breakdown.

     * Monthly Spending Patterns

     - *Highest Month:* 2024-02 (£1,576.32)
     - *Lowest Month:* 2024-01 (£1,245.78)
     - *Average Monthly Spending:* £1,411.93

     Each bar shows spending by category. The 3-letter codes represent categories,
     with consistent ordering by overall spending (highest to lowest) across all months.
     The length of each segment is proportional to its share of that month's spending.

     #+begin_verse
     2024-01 *£1246* /hse_____/fod___/utl_/str/
     2024-02 *£1576* /hse_____/fod____/utl__/shp_/
     2024-03 *£1414* /hse_____/fod___/utl__/str/web/
     #+end_verse

Monthly Spending Visualization
==============================

Visual representations of monthly spending patterns.

     *** Monthly Spending Visualization (Stacked Categories)

     #+ATTR_ORG: :width 800
     [[file:financial-report--monthly-spending-stacked.png]]

     Generated from gnuplot script: [[file:monthly-categories-stacked.gp]]
     Data file: [[file:monthly-categories-stacked.dat]]

     *** Monthly Spending with Individual Categories

     #+ATTR_ORG: :width 800
     [[file:financial-report--monthly-spending-categories.png]]

     Generated from gnuplot script: [[file:monthly-categories-lines.gp]]
     Data file: [[file:monthly-categories-lines.dat]]

Top Merchants
=============

Lists merchants where you spend the most money.

     * Top Merchants

     - *Total merchant spending:* £4,235.78
     - *Monthly average (all merchants):* £1,411.93
     - *Yearly average (all merchants):* £16,943.12

     1. *RENT-PAYMENT:* £1,200.00 (28.3%)
        - Monthly avg: £400.00, Yearly avg: £4,800.00
     2. *SAINSBURYS:* £345.67 (8.2%)
        - Monthly avg: £115.22, Yearly avg: £1,382.68

     #+ATTR_ORG: :width 600
     [[file:financial-report--top-merchants.png]]

     Generated from gnuplot script: [[file:top-merchants.gp]]
     Data file: [[file:top-merchants.dat]]

Recurring Subscriptions
=======================

Identifies and estimates costs of regular payments.

     * Recurring Subscriptions (Detected)

     Estimated monthly cost from detected recurring payments: *£45.97*
     (Note: Detection is based on pattern matching and frequency analysis)

     1. *Netflix:* £9.99/month
     2. *Spotify:* £9.99/month
     3. *Amazon Prime:* £7.99/month

Transaction Size Distribution
=============================

Shows the distribution of transaction amounts.

     * Transaction Size Distribution

     - *Under £10:* 42 transactions (30.7%)
     - *£10 to £50:* 65 transactions (47.4%)
     - *£50 to £100:* 23 transactions (16.8%)
     - *Over £100:* 7 transactions (5.1%)

Unmatched Transactions
======================

Lists transactions that weren't matched by specific patterns.

     * Unmatched Transactions

     The following transactions were only matched by the catch-all pattern (".*").
     You may want to add specific patterns for these in `bank-buddy-cat-list-defines`

     #+begin_src text
     CORNER-SHOP
     PARKING-FEE-LONDON
     JOHN-HARDWARE-STORE
     #+end_src

Data Visualizations
===================

Charts and graphs of your financial data using external gnuplot scripts.


File: bank-buddy.info,  Node: Transaction Categories,  Next: Subscription Detection,  Prev: Report Sections,  Up: Top

7 Transaction Categories
************************

Bank Buddy uses regular expression patterns to categorize transactions.
These are defined in the variable ‘bank-buddy-cat-list-defines’.

Default Categories
==================

Bank Buddy comes with predefined categories including:

Category Code   Description   Example Patterns
-------------------------------------------------
kat             Personal      katherine,
                (Katherine)   lucinda, kate
trn             Transport     railw, railway,
                              selfserve, train
pay             PayPal        paypal
utl             Utilities     virgin-media,
                              insurance,
                              electric, water
bet             Betting       sky-betting,
                              b365, races,
                              bet365
pen             Pension       stakeholde,
                              widows
sav             Savings       nsibill, vines,
                              ns&i, saver
txi             Taxi          uber, aqua
fod             Food          sainsburys,
                              waitrose, tesco,
                              domino,
                              deliveroo
shp             Shopping      ebay, asos,
                              next, argos,
                              amazon
o               Other         .* (catch-all)

Category Format
===============

Categories are defined as patterns in the form:

     (REGEX-PATTERN CATEGORY-CODE)

   Where:
   • ‘REGEX-PATTERN’ is a regular expression that matches transaction
     descriptions
   • ‘CATEGORY-CODE’ is a short code representing the category (e.g.,
     "fod" for food)

   Example:
     ("amazon\\|amz" "amz")  ; Amazon purchases
     ("netflix\\|spotify\\|youtube" "str")  ; Streaming services

Customizing Categories
======================

You can customize the category patterns by setting
‘bank-buddy-cat-list-defines’:

     (customize-set-variable 'bank-buddy-cat-list-defines
       '(("amazon\\|amz" "amz")
         ("netflix\\|spotify" "str")
         ("uber\\|lyft" "txi")
         ("sainsburys\\|tesco\\|asda" "fod")
         ;; Add your own patterns here
         (".*" "o")))  ; Catch-all pattern should be last

Customizing Category Names
==========================

Category codes are mapped to human-readable names via
‘bank-buddy-category-names’:

     (customize-set-variable 'bank-buddy-category-names
       '(("amz" . "Amazon")
         ("str" . "Streaming Services")
         ("txi" . "Taxi & Rideshare")
         ("fod" . "Groceries")
         ;; Add your own mappings here
         ("o" . "Other")))


File: bank-buddy.info,  Node: Subscription Detection,  Next: Category Management,  Prev: Transaction Categories,  Up: Top

8 Subscription Detection
************************

Bank Buddy can automatically detect recurring payments like
subscriptions or regular bills.  This is especially useful for
identifying forgotten or unnecessary recurring charges.

How It Works
============

Bank Buddy looks for transactions that:

   • Appear multiple times (configurable via
     ‘bank-buddy-subscription-min-occurrences’)
   • Have the same or very similar amounts
   • Occur at regular intervals (weekly, bi-weekly, monthly, or
     annually)

Subscription Patterns
=====================

Define specific subscription patterns for better detection:

     (customize-set-variable 'bank-buddy-subscription-patterns
       '(("NETFLIX" . "Netflix")
         ("SPOTIFY" . "Spotify")
         ("AMAZON PRIME" . "Amazon Prime")
         ;; Add your own patterns here
         ))

Frequency Analysis
==================

Bank Buddy estimates the frequency of subscriptions:

‘Weekly’
     Transactions occurring approximately every 5-10 days
‘Bi-weekly’
     Transactions occurring approximately every 11-20 days
‘Monthly’
     Transactions occurring approximately every 25-35 days
‘Annual’
     Transactions occurring approximately every 350-380 days
‘Irregular’
     Transactions that occur multiple times but not at regular intervals


File: bank-buddy.info,  Node: Category Management,  Next: Customizing Visualizations,  Prev: Subscription Detection,  Up: Top

9 Category Management
*********************

Bank Buddy includes an interactive mode for managing transaction
categories: ‘bank-buddy-cat-mode’.

Enabling bank-buddy-cat-mode
============================

When viewing a Bank Buddy report, the mode is automatically enabled.
You can also enable it manually:

     M-x bank-buddy-cat-mode

Adding New Categories
=====================

To add a transaction to a category:

  1. Navigate to an unmatched transaction (in the "Unmatched
     Transactions" section)
  2. Press ‘C-c C-a’ (‘bank-buddy-cat-add-pattern’)
  3. Choose an existing category or create a new one
  4. Optionally save the updated category definitions to your init file
  5. Regenerate the report to see the changes

Regenerating Reports
====================

After modifying categories, regenerate the report:

     C-c C-r (bank-buddy-cat-regenerate-report)

Viewing Unmatched Transactions
==============================

To quickly view and manage unmatched transactions:

     M-x bank-buddy-view-unmatched-transactions

Saving Category Definitions
===========================

When adding a new category pattern, you'll be asked if you want to save
the updated definitions to your init file.


File: bank-buddy.info,  Node: Customizing Visualizations,  Next: Customization,  Prev: Category Management,  Up: Top

10 Customizing Visualizations
*****************************

Since version 0.2.0, Bank Buddy generates external gnuplot scripts
rather than using Org Babel blocks.  This provides more flexibility for
customizing visualizations.

Understanding Generated Files
=============================

Each visualization consists of:

   • A gnuplot script file (.gp) - Contains the plotting instructions
   • A data file (.dat) - Contains the raw data for the plot
   • The resulting image file (.png) - The generated visualization

Customizing Plots
=================

To customize a plot:

  1. Open the .gp file linked in the report
  2. Edit the gnuplot script using standard gnuplot syntax
  3. Regenerate the plot using: ‘gnuplot filename.gp’
  4. The report will automatically show the updated image

Common Customizations
=====================

     # Change colors
     set style line 1 lc rgb '#0072BD'  # Change bar color

     # Adjust text size
     set terminal png size 1000,800 font 'Verdana,12'

     # Change plot style
     set style data linespoints    # Instead of bars
     set style fill pattern       # Use patterns instead of solid fill

     # Adjust axis labels
     set ylabel 'Spending (GBP)'  # Change currency symbol
     set xtics rotate by -60      # Rotate labels more

     # Add a grid
     set grid ytics

Regenerating All Plots
======================

If you want to regenerate all plots after making global changes:

     cd report-directory
     for f in *.gp; do gnuplot "$f"; done


File: bank-buddy.info,  Node: Customization,  Next: Key Bindings,  Prev: Customizing Visualizations,  Up: Top

11 Customization
****************

Core Settings
=============

     ;; Exclude large transactions from analysis
     (setq bank-buddy-exclude-large-txns t)
     (setq bank-buddy-large-txn-threshold 2000)

     ;; Number of occurrences to detect subscriptions
     (setq bank-buddy-subscription-min-occurrences 3)

     ;; Number of top items to display
     (setq bank-buddy-top-spending-categories 5)
     (setq bank-buddy-top-merchants 5)

All Customizable Variables
==========================

Variable   Default   Description
-----------------------------------
bank-buddy-exclude-large-txnstWhether to
                     exclude
                     large
                     transactions
bank-buddy-large-txn-threshold2000Threshold
                     for large
                     transactions
                     (in
                     currency
                     units)
bank-buddy-subscription-min-occurrences3Minimum
                     occurrences
                     for
                     subscription
                     detection
bank-buddy-top-spending-categories5Number of
                     top
                     spending
                     categories
                     displayed
bank-buddy-top-merchants5Number of
                     top
                     merchants
                     displayed
bank-buddy-cat-list-defines(list...)Categorization
                     patterns
                     for
                     transactions
bank-buddy-category-names(list...)Human-readable
                     category
                     names for
                     reporting
bank-buddy-subscription-patterns(list...)Patterns to
                     identify
                     specific
                     subscriptions


File: bank-buddy.info,  Node: Key Bindings,  Next: Comparison,  Prev: Customization,  Up: Top

12 Key Bindings
***************

Global Bindings
===============

Key   Command   Description
------------------------------
None  bank-buddy-generate-reportGenerate a
                new
                financial
                report
None  bank-buddy-view-unmatched-transactionsView
                transactions
                that
                weren't
                matched by
                specific
                patterns

bank-buddy-cat-mode Bindings
============================

Key   Command   Description
------------------------------
C-c   bank-buddy-cat-add-patternAdd the
C-a             transaction
                at point to
                a category
C-c   bank-buddy-cat-regenerate-reportRegenerate
C-r             the report
                with
                current
                category
                definitions


File: bank-buddy.info,  Node: Comparison,  Next: Troubleshooting,  Prev: Key Bindings,  Up: Top

13 Comparison
*************

Bank Buddy can be compared to several other Emacs packages for financial
management.

Ledger-mode
===========

Ledger-mode is an Emacs interface to the command-line Ledger accounting
system.

   • Ledger is a complete double-entry accounting system; Bank Buddy is
     focused on bank statement analysis
   • Ledger requires manual transaction entry or carefully formatted
     imports; Bank Buddy automates categorization
   • Ledger offers more comprehensive accounting features; Bank Buddy
     focuses on spending insights
   • Bank Buddy provides visual spending breakdowns and charts

   *When to use Ledger:* For complete personal finance tracking,
investments, budgeting, and double-entry accounting.  *When to use Bank
Buddy:* For quick analysis of bank statements and visualizing spending
patterns.

Beancount-mode
==============

Beancount-mode is an Emacs mode for Beancount, another plain-text
accounting system.

   • Beancount, like Ledger, is a full double-entry accounting system
   • Beancount has stricter syntax requirements than Ledger
   • Bank Buddy offers automatic categorization and reporting
   • Beancount generates sophisticated reports, but requires more setup

   *When to use Beancount:* For precise, auditable personal accounting
with strict validation.  *When to use Bank Buddy:* For simple spending
analysis without learning accounting principles.

Money
=====

Money is a simple package for tracking expenses in Org-mode.

   • Money uses simple org-mode tables for basic expense tracking
   • Money is designed for manual entry of expenses
   • Bank Buddy focuses on automated analysis of bank-provided data
   • Bank Buddy provides more sophisticated visualization

   *When to use Money:* For simple manual expense tracking in Org.
*When to use Bank Buddy:* For analyzing historical bank data and
discovering spending patterns.

csv-mode and orgtbl-mode
========================

Some users analyze financial CSV data using built-in Emacs packages.

   • These are general-purpose tools requiring manual customization
   • Bank Buddy provides specialized, financial-specific analysis
   • Bank Buddy automatically categorizes transactions
   • Bank Buddy generates comprehensive reports automatically

   *When to use csv/orgtbl-mode:* For custom, one-off analysis of
financial data.  *When to use Bank Buddy:* For consistent, repeatable
analysis of bank statements.


File: bank-buddy.info,  Node: Troubleshooting,  Next: Index,  Prev: Comparison,  Up: Top

14 Troubleshooting
******************

CSV Parsing Issues
==================

If your bank's CSV format is not recognized:

   • Check that your CSV has columns for date, description, and debit
     amount
   • Pre-process the CSV if necessary to match the expected format
   • Check for encoding issues if you see garbled text in reports

Performance Considerations
==========================

Bank Buddy processes CSV files asynchronously to avoid blocking Emacs.
However, with very large files:

   • Initial parsing may take longer
   • Generated reports might be large
   • Consider filtering or pre-processing very large CSV files

Visualization Issues
====================

If plots are not generating correctly:

   • Ensure gnuplot is installed and available in your PATH
   • Check that the .gp and .dat files were created correctly
   • Look for error messages when running gnuplot manually
   • Verify that the data file contains the expected format

Common Issues
=============

Unmatched Transactions
     Review and add patterns for your common merchants using the
     category management mode
Duplicate Categories
     Check for overlapping regex patterns in your category definitions
Date Format Issues
     Ensure dates are in YYYY-MM-DD format for best results
Category Mistakes
     If transactions are being assigned to the wrong categories, review
     your regex patterns, particularly those that might be too broad
Plot Customization Problems
     If edits to gnuplot scripts aren't reflected, ensure you're editing
     the right file and running gnuplot to regenerate


File: bank-buddy.info,  Node: Index,  Prev: Troubleshooting,  Up: Top

Index
*****



Tag Table:
Node: Top616
Node: Introduction2034
Node: Installation4213
Node: Quick Start5469
Node: CSV Format5944
Node: Report Generation6544
Node: Report Sections7519
Node: Transaction Categories12069
Node: Subscription Detection14871
Node: Category Management16327
Node: Customizing Visualizations17682
Node: Customization19325
Node: Key Bindings21214
Node: Comparison22165
Node: Troubleshooting24732
Node: Index26440

End Tag Table


Local Variables:
coding: utf-8
End:
