BeanCounter(3pm)

📦 version 0.8.11, in ubuntu jammy

💖 BeanCounter — the perl module page, but make it a group chat 💖

okay bestie, so this is Finance::BeanCounter, a page from the User Contributed Perl Documentation (that's the 3pm section of the manual, iykyk). Sit down, grab a boba, we're doing stock portfolio math together 🫶

✨ NAME ✨

Finance::BeanCounter — the module for stock portfolio performance functions. that's it, that's the whole name. short, iconic, no notes 💅

🌸 SYNOPSIS 🌸

use Finance::BeanCounter;

literally just that. one line and you're in, bestie ✨

🦋 DESCRIPTION 🦋

Finance::BeanCounter hands you functions to download, store and analyse stock market data. the whole glow-up pipeline, basically.

So the downloads? You can pull current price and company data — and when I say "current", bestie, I mean rather 15 or 20 minute-delayed, let's be real 🙈 — and you can also pull historical price data. Both of those forms can get stored in an SQL database. By default we go with PostgreSQL, though MySQL is supported too, and honestly any database you can reach through an ODBC connection should work as well. so many options, we love to see it 💜

Then the analysis. Right now it's performance and risk analysis:

  • Performance reports — these include a profit-and-loss report, aka the 'p/l' report in the lingo, and you can run it over arbitrary time intervals, like --prevdate 'friday six months ago' --date 'yesterday'. and like… whatever the wonderful Date::Manip module understands, fr fr. there's also dayendreport, which defaults to the changes in the last trading day. periodt.
  • Risk reports — these show you parametric and non-parametric value-at-risk (VaR) estimates. scary math, slay execution 🔥

Most of the functionality is also available in the reference implementation called beancounter, which is a super convenient command-line script. chef's kiss.

⚠️ heads up bestie: the API might change and evolve over time. that low version number is really just trying to say the code isn't in its final form yet — but it's been in use for well over four years. so like, it's chaotic but it WORKS 💀

More documentation lives in the Perl source code. go read it, i believe in you 🎀

👑 DATABASE LAYOUT 👑

The easiest way to see the table design is to peek at the content of the setup_beancounter script. It creates the five tables: stockinfo, stockprices, fxprices, portfolio and indices. Also important: it supports creating the database for both PostgreSQL and MySQL. versatile queen ✨

🍓 THE STOCKINFO TABLE

The stockinfo table holds general (non-price) information and is indexed by symbol:

symbol              varchar(12) not null,
name                varchar(64) not null,
exchange            varchar(16) not null,
capitalisation      float4,
low_52weeks         float4,
high_52weeks        float4,
earnings            float4,
dividend            float4,
p_e_ratio           float4,
avg_volume          int4

This table gets updated by overwriting the previous content. no hoarding old data here, we move on 💅

🧚 THE STOCKPRICES TABLE

The stockprices table holds (daily) price and volume information. It's indexed by both date and symbol:

symbol              varchar(12) not null,
date                date,
previous_close      float4,
day_open            float4,
day_low             float4,
day_high            float4,
day_close           float4,
day_change          float4,
bid                 float4,
ask                 float4,
volume              int4

During updates, information is appended to this table. it just keeps growing, main character energy 🌱

🌈 THE FXPRICES TABLE

The fxprices table holds (daily) foreign exchange rates. You can use it to calculate home market values of foreign stocks. so useful honestly:

currency            varchar(12) not null,
date                date,
previous_close      float4,
day_open            float4,
day_low             float4,
day_high            float4,
day_close           float4,
day_change          float4

Similar to the stockprices table, it is indexed on date and symbol. twinsies 🫶

💜 THE STOCKPORTFOLIO TABLE

The portfolio table contains the holdings information:

symbol              varchar(16) not null,
shares              float4,
currency            varchar(12),
type                varchar(16),
owner               varchar(16),
cost                float(4),
date                date

It is indexed on symbol,owner,date. the trio, the moment, the iconique grouping ⭐

🎀 THE INDICES TABLE

The indices table links a stock symbol with one or several market indices:

symbol              varchar(12) not null,
stockindex          varchar(12) not null

💀 BUGS 💀

Finance::BeanCounter and beancounter are so fresh that there are only missing features :) like… that's the bug report. features, but make them absent. we're thriving.

On a more serious note, this code (or its earlier predecessors) has been in use since the fall of 1998. so it's an elder, respect the elders 🫡

Known bugs or limitations are documented in the TODO file in the source package. go check it if you're curious, bestie.

🔥 SEE ALSO 🔥

  • beancounter.1
  • smtm.1
  • Finance::YahooQuote.3pm
  • LWP.3pm
  • Date::Manip.3pm
Finance::BeanCounter.pm  (c) 2000 -- 2006 by Dirk Eddelbuettel
<edd@debian.org>

Updates to this program might appear at http://eddelbuettel.com/dirk/code/beancounter.html.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. There is NO warranty whatsoever. none. zero. niente 🫠

⚠️ also important: the information that you obtain with this program may be copyrighted by Yahoo! Inc., and is governed by their usage license. See http://www.yahoo.com/docs/info/gen_disclaimer.html for more information. don't get yourself in trouble bestie 🙈

🌸 ACKNOWLEDGEMENTS 🌸

The Finance::YahooQuote module by Dj Padzensky (on the web at http://www.padz.net/~djpadz/YahooQuote/) served as the backbone for data retrieval, and a guideline for the extension to the non-North American quotes — which was already very useful for the real-time ticker http://eddelbuettel.com/dirk/code/smtm.html. giving credit where credit is due, always 💖

and that's the whole page, bestie!! this one's from perl v5.32.1, dated 2021-11-10, and it lives in the manual as BeanCounter(3pm). now go analyse a portfolio or something, you've got this 👑💅✨

📦 where this page comes from