tktax-histogram

A Rust library that provides a robust method to construct, display, and analyze histograms of transaction distributions in conjunction with the tktax_account, tktax_money, tktax_transaction, and tktax_3p crates. The name Histogram is derived from the ancient Greek ῾ἱστός᾽ (histós), signifying something upright or a web’s warp, now used to depict the frequency distribution of numerical data.

This crate defines data structures for creating monthly binned data via user-specified price (monetary) bins and includes multiple strategies for rendering the histogram. It is especially useful for accounting or financial analysis applications, thanks to its integration with specialized monetary types from tktax_money. Its design is amenable to advanced usage scenarios where resourcefulness and comprehensive error handling are crucial.

Features

1. AccountHistogram
   Aggregates all transactions from an account into a month-based histogram, providing both a high-level overview of transaction volume and deeper transactional detail.

2. Multiple Histogram Display Strategies

   • Short
     Minimal textual output, intended for quick inspection.
   • ShowTransactionsInBinsWithManyItems
     Displays detailed transaction listings in particularly populous bins.
   • ShowHeavyTransactionsBasedOnPrice
     Allows an optional price threshold to reveal high-value or influential transactions.

3. Bins
   Customizable bin edges (Vec<MonetaryAmount>) to accurately categorize transactions into discrete intervals, emulating a partitioned distribution (Latin: distributio) of monetary amounts (Latin: monetarius).

4. Monthly Granularity
   Each transaction is grouped by its date into a HistogramMonth, which enforces strict month numbering (1 through 12) and ensures correctness with an assertion.

5. Production-Ready Error Handling

   • No panics within typical usage paths (all invariants are handled or asserted).
   • Ensures transaction amounts fit the determined bin intervals.

Quick Example

Below is a concise illustration of how to employ the histogram functionality. For an Account populated with transactions, the following snippet constructs and prints a full histogram to stdout:

use tktax_histogram::*;
use tktax_account::Account;
use tktax_money::MonetaryAmount;
use tktax_transaction::Transaction;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Suppose 'my_account' is constructed with a known set of transactions
    let my_account = Account::new("My Checking Account");

    // Example: build and push some transactions (pseudo-code)
    // for each TX, we set transaction date, amount, description, etc.
    // my_account.add_transaction(...);

    // Create a strategy: show all transactions in the histogram
    let strategy = HistogramDisplayStrategy::show_full_histogram();
    
    // Generate a histogram with the default bin edges used in 'CreateAccountHistogram'
    let histogram = my_account.histogram(&strategy);

    // Print the histogram
    println!("{}", histogram);

    Ok(())
}

The library also exposes further customization options (e.g., HistogramDisplayStrategy::with_price_threshold(123.45)) for advanced applications. Simply select a strategy and generate the histogram from your Account object. You can then utilize fmt::Display to produce textual output.

Typical Use Cases

• Financial Analysis
  Visual inspection of distributions of cash flows and transactions.
• Accounting Tools
  Enhanced statement reports for any month or year-end summaries.
• Budgeting & Planning
  Quick detection of high-value expenses or abnormally large numbers of small transactions.

Additional Notes

• This crate makes extensive use of the specialized MonetaryAmount type for safety and clarity.
• A variety of sophisticated transaction strategies can be implemented by customizing bin edges, months, and displayed transactional data.
• Integrated with the rest of the TKTAX ecosystem, it relies on the well-defined domain abstractions from tktax_money, tktax_transaction, tktax_account, and tktax_3p for robust financial data handling.

Minimum Supported Rust Version (MSRV)

Rust 1.60 or higher is recommended, matching the dependencies of the TKTAX suite.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for improvements or bug fixes.