DBCOLHISTO(1)

📦
version 3.9 · 3 versions
, in epel 9

💅 DBCOLHISTO(1) — the dbcolhisto era ✨

okay bestie, so this is the manual page for dbcolhisto, a lil Perl situation from the User Contributed Perl Documentation corner of the universe, and honestly? it's giving "I count things in buckets" and I'm obsessed. let's get into it 🎀

🌸 NAME 🌸

dbcolhisto — literally computes a histogram over a column of Fsdb data. that's the whole vibe. no cap.

✨ SYNOPSIS ✨

dbcolhisto [-ag] [-W BucketWidth] [-S BucketStart] [-E BucketEnd] [-N
NumberOfBuckets] column

🦋 DESCRIPTION 🦋

so this program computes a histogram over a column of data. records containing non-numeric data are considered null and do not contribute to the stats — but optionally they can be treated as zeros instead, which is a whole different vibe, iykyk.

it defaults to 10 buckets over the exact range of data. up to three parameters (number of buckets, start, end, and width) can be specified, and the rest default accordingly. 💫

buckets range from a value (given the low column) to just below the next low value, and buckets are equal width. if necessary, extra "<min" and ">max" buckets get created. by default, the last bucket includes max (and is thus infinitesimally larger than the other buckets). this irregularity can be removed with the -I option. main character bucket energy only 🙈

this program requires O(number of buckets) memory and O(size of data) temporary disk space. efficiency queen 👑

💖 OPTIONS 💖

  • -W or --width N — gives with width of each bucket, in data units. default is whatever gives 10 buckets over the whole range of data.
  • -S or --start N — buckets start at value N, in data units. default is the minimum data value.
  • -E or --end N — buckets end at value N, in data units. default is the maximum data value.
  • -N or --number N — create N buckets. the default is 10 buckets.
  • -g or --graphical — generate a graphical histogram (with asterisks). default is numeric. asterisks are honestly so retro-cute 💅
  • -I or --last-inclusive — make the last bucket non-inclusive of the last value.
  • -a — compute stats over all records (treat non-numeric records as zero rather than just ignoring them). default is non-numeric records are ignored.
  • -e EmptyValue or --empty — specify the value any null bins get. (Default: -.)

🌈 the standard fsdb options (this module supports these too, slay) 🌈

  • -d — enable debugging output.
  • -i or --input InputSource — read from InputSource, typically a file name, or "-" for standard input, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
  • -o or --output OutputDestination — write to OutputDestination, typically a file name, or "-" for standard output, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
  • --autorun or --noautorun — by default, programs process automatically, but Fsdb::Filter objects in Perl do not run until you invoke the run() method. the "--(no)autorun" option controls that behavior within Perl.
  • --help — show help. 🫶
  • --man — show full manual. (you're literally reading it rn 😭)

⭐ SAMPLE USAGE ⭐

🍓 Input:

#fsdb name id test1
a 1 80
b 2 70
c 3 65
d 4 90
e 5 70
f 6 90

🧚 Command:

cat DATA/grades.fsdb | dbcolhisto -S 0 -E 100 -N 10 test1

🔥 Output:

#fsdb low histogram:q
0       0
10      0
20      0
30      0
40      0
50      0
60      1
70      2
80      1
90      2
#  | dbcolhisto -S 0 -E 100 -N 10 test1

ate. no crumbs. 👑

👀 SEE ALSO 👀

Fsdb, dbcolpercentile, dbcolstats — go read those too, bestie, they're lowkey iconic.

💀 BUGS 💀

this program could run in constant memory with no external storage when the buckets are pre-specified. that optimization is not implemented. so close to perfection and yet… 🙈

Copyright (C) 1991-2022 by John Heidemann <johnh@isi.edu>

this program is distributed under terms of the GNU general public license, version 2. see the file COPYING with the distribution for details.

and that's the whole page, bestie 💖 this was perl v5.32.1, dated 2024-08-02 — mwah, go compute some gorgeous little buckets for me 🎀✨

📦 where this page comes from