DBCOLPERCENTILE(1)

📦
version 3.9 · 3 versions
, in epel 9

🎀 DBCOLPERCENTILE(1) 🎀

the one from User Contributed Perl Documentation, bestie

okay so picture this: it's late, you've got a numeric column, and you need to know where each value sits in the grand scheme of things. That's literally this whole page. Pull up a chair. 💅

✨ NAME ✨

dbcolpercentile — compute percentiles or ranks for an existing numeric column. That's it. That's the gig. 🫶

🌸 SYNOPSIS 🌸

dbcolpercentile [-rplhS] [--mode MODE] [--value WEIGHT_COL] column

🦋 DESCRIPTION 🦋

So what does it actually do? It computes a percentile, a ranking, or a weighted percentile of a column of numbers. Iconic behaviour, no notes. ✨

The new column gets named percentile:d or rank:q or weighted:d — which one you get depends on the mode you picked, iykyk.

Ordering is given by the specifed column. (Yes, that's how it's spelled in the source, we don't fix things around here, we respect the original. 💀)

In weighted mode, by default the same column as ordering is used for weighting. But if you want to be different about it, hand over a whole separate column for weighting with -v. Main character energy, honestly. 👑

Non-numeric values are ignored. Like, they're just not invited to the party. 🙈

Now for the storage tea ☕: if the data is pre-sorted and only a rank is requested, no extra storage is required — zero, nada, stunning. In all other cases, a full copy of data is buffered on disk. So don't come crying to me about disk space, that's the deal, periodt. Output will be sorted by COLUMN.

💖 OPTIONS 💖

  • -p, --percentile, --mode percentile — Show percentile (default). Percentile is the fraction of the cumulative values at or lower than the current value, relative to the total count. This is the vibe you get if you don't ask for anything else. ⭐
  • -P, --rank, --nopercentile, --mode rank — Compute ranks instead of percentiles. Different flavour, same energy. 🔥
  • -w WEIGHT_COL, --weighted WEIGHT_COL, --mode weighted — Compute the weighted percentile. Here values define not only the ordering, but the fraction of the total sum, and percentile is the fraction of sum of cumulative values in the weighting column (relative to their sum), for all ranking colums at or lower than the current ranking column. (And yes, "colums" — again, we're not touching the original wording, we love her exactly as she is. 😭) If the weight column is not specified (with --mode weighted), it is the same as the ranking column.
  • -a, --include-non-numeric — Compute stats over all records (treat non-numeric records as zero rather than just ignoring them). So generous of you, honestly. 🫶
  • -S, --pre-sorted — Assume data is already sorted. With one -S, we check and confirm this precondition. When repeated, we skip the check. Trust but verify, then just trust. 💅
  • -N NAME, --new-name NAME — Give the NAME of the new column. (If no type is specifed, a type will be assigned based on the mode.) Naming rights, babes. 🎀
  • -f FORMAT, --format FORMAT — Specify a printf(3)-style format for output statistics. Defaults to "%.5g". Pretty-printing, but make it nerdy. ✨
  • -T TmpDir — where to put tmp files. Also uses environment variable TMPDIR, if -T is not specified. Default is /tmp.
  • -e EmptyValue, --empty — Specify the value any non-numeric rows get, if in weighted mode.

This module also supports the standard fsdb options:

  • -d — Enable debugging output. For when you need to see the receipts. 🔍
  • -i, --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, --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, --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, bestie, full circle. 🌈)

🍓 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 | dbcolpercentile test1

Output:

#fsdb name id test1 percentile
d       4       90      1
f       6       90      1
a       1       80      0.66667
b       2       70      0.5
e       5       70      0.5
c       3       65      0.16667
#  | dbsort -n test1
#   | dbcolpercentile test1

Command 2:

cat DATA/grades.fsdb | dbcolpercentile --rank test1

Output 2:

#fsdb name id test1 rank
d       4       90      1
f       6       90      1
a       1       80      3
b       2       70      4
e       5       70      4
c       3       65      6
#  | dbsort -n test1
#   | dbcolpercentile --rank test1

🌟 SEE ALSO 🌟

Fsdb. dbcolhisto. Go read those too, they're also icons. 💜

Copyright (C) 1997-2024 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 — signed off with perl v5.32.1, dated 2024-08-02, and yes we kept the manual name DBCOLPERCENTILE(1) up top because branding matters. mwah. 💋✨

📦 where this page comes from