VecStat(3pm)

VecStat(3pm) — straight out of the User Contributed Perl Documentation corner of the perl-verse, and bestie, it's a whole vibe. This is the manual for Math::VecStat, and we are going through every single bit of it together. No skimming, no skipping, we're reading the whole thing. 🫶

---

🌸 NAME 🌸

Math::VecStat — Some basic numeric stats on vectors

🦋 SYNOPSIS 🦋

okay so first, you gotta import the squad:

use Math::VecStat qw(max min maxabs minabs sum average);

then the min/max/maxabs/minabs girlies, in every calling convention they come in (scalar, list, and ref, plus the array-context two-value returns):

$max=max(@vector);
$max=max(\@vector);
($max,$imax)=max(@vector);
($max,$imax)=max(\@vector);
$min=min(@vector);
$min=min(\@vector);
($max,$imin)=min(@vector);
($max,$imin)=min(\@vector);
$max=maxabs(@vector);
$max=maxabs(\@vector);
($max,$imax)=maxabs(@vector);
($max,$imax)=maxabs(\@vector);
$min=minabs(@vector);
$min=minabs(\@vector);
($max,$imin)=minabs(@vector);
($max,$imin)=minabs(\@vector);

then the math-y ones:

$sum=sum($v1,$v2,...);
$sum=sum(@vector);
$sum=sum(\@vector);
$average=average($v1,$v2,...);
$av=average(@vector);
$av=average(\@vector);

the single-vector extra credit:

$ref=vecprod($scalar,\@vector);
$ok=ordered(@vector);
$ok=ordered(\@vector);

and finally the two-vector duo energy:

$ref=sumbyelement(\@vector1,\@vector2);
$ref=diffbyelement(\@vector1,\@vector2);
$ok=allequal(\@vector1,\@vector2);
$ref=convolute(\@vector1,\@vector2);

👀 psst — notice median is not in that qw(...) import list up top. That's why the example further down calls it the long way, as Math::VecStat::median.

💅 DESCRIPTION 💅

so this package provides some basic statistics on numerical vectors. that's the whole premise, bestie, and it eats. 🔥

Here's the thing that makes it iconic: all the subroutines can take a reference to the vector to be operated on. You can hand over a copy of the vector in some cases, but it is not recommended for efficiency — passing the ref is the move, fr fr.

---

🍓 max(@vector), max(\@vector)

returns the maximum value of the given values or vector. In an array context it returns the value and the index in the array where it occurs. 👑

🍓 min(@vector), min(\@vector)

returns the minimum value of the given values or vector. In an array context it returns the value and the index in the array where it occurs.

💀 okay and yes, if you peep the synopsis, the array-context min example literally names the value $max. We do not touch it. We are faithful to the text. ($max,$imin)=min(@vector); periodt.

🍓 maxabs(@vector), maxabs(\@vector)

returns the maximum value of the absolute of the given values or vector. In an array context it returns the value and the index in the array where it occurs.

🍓 minabs(@vector), minabs(\@vector)

returns the minimum value of the absolute of the given values or vector. In an array context it returns the value and the index in the array where it occurs.

🍓 sum($v1,$v2,...), sum(@vector), sum(\@vector)

returns the sum of the given values or vector. cute, simple, does exactly what it says. ✨

🍓 average($v1,$v2,..), average(@vector), average(\@vector)

returns the average of the given values or vector.

🍓 vecprod($a,$v1,$v2,..), vecprod($a,@vector), vecprod( $a, \@vector )

returns a vector built by multiplying the scalar $a by each element of the @vector. it's giving glow-up, but make it multiplication. 🌈

🍓 ordered($v1,$v2,..), ordered(@vector), ordered(\@vector)

returns nonzero iff the vector is nondecreasing with respect to its index. The intended usage is:

if( ordered( $lowBound, $value, $highBound ) ){

instead of the (slightly) more clumsy:

if( ($lowBound <= $value) && ($value <= $highBound) ) {

lowkey a serve. less typing, same energy. 🎀

🍓 sumbyelement( \@array1, \@array2 ), diffbyelement(\@array1,\@array2)

return the element-by-element sum or difference of two identically-sized vectors. Given:

$s = sumbyelement( [10,20,30], [1,2,3] );
$d = diffbyelement( [10,20,30], [1,2,3] );

$s will be "[11,22,33]", and $d will be "[9,18,27]". math is mathing. 🔥

🍓 allequal( \@array1, \@array2 )

returns true if and only if the two arrays are numerically identical. no cap. 💯

🍓 convolute( \@array1, \@array2 )

return a reference to an array containing the element-by-element product of the two input arrays. I.e.,

$r = convolute( [1,2,3], [-1,2,1] );

returns a reference to

[-1,4,3]

🍓 median

evaluates the median, i.e. an element which separates the population in two halves. It returns a reference to a list whose first element is the median value and the second element is the index of the median element in the original vector.

$a = Math::VecStat::median( [9,8,7,6,5,4,3,2,1] );

returns the list reference

[ 5, 4 ]

i.e. the median value is 5 and it is found at position 4 of the original array.

Now here's the tie-breaker rule, and you need to know it: if there are several elements of the array having the median value, e.g. [1,3,3,3,5], then in this case we choose always the first element in the original vector which is a median. In the example, we return [3,1].

---

📜 HISTORY 📜

the receipts, bestie. 🧾

$Log: VecStat.pm,v $

• Revision 1.9 — 2003/04/20 00:49:00 — spinellia@acm.org: Perl 5.8 broke test 36, exposing an inconsistency in median. Fixed, thanks to david@jamesgang.com.
• Revision 1.8 — 2001/01/26 11:10:00 — spinellia@acm.org: Added function median. Fixed test, thanks to Andreas Marcel Riechert <riechert@pobox.com>.
• Revision 1.7 — 2000/10/24 15:28:00 — spinellia@acm.org: Added functions allequal diffbyelement. Created a reasonable test suite.
• Revision 1.6 — 2000/06/29 16:06:37 — spinellia@acm.org: Added functions vecprod, convolute, sumbyelement.
• Revision 1.5 — 1997/02/26 17:20:37 — willijar: Added a line before the pod header so pod2man installs the man page correctly.
• Revision 1.4 — 1996/02/20 07:53:10 — willijar: Added the ability to return the index in array context to the max and min functions. Added the minabs and maxabs functions. Thanks to Mark Borges <mdb@cdc.noaa.gov> for these suggestions.
• Revision 1.3 — 1996/01/06 11:03:30 — willijar: Fixed a stupid bug that crept into the looping in the min and max functions.
• Revision 1.2 — 1995/12/26 09:56:38 — willijar: Oops — removed xy data functions.
• Revision 1.1 — 1995/12/26 09:39:07 — willijar: Initial revision.

🐛 BUGS 🐛

found something broken? let me know, bestie — I welcome any appropriate additions for this package. 🫶

👑 AUTHORS 👑

• John A.R. Williams <J.A.R.Williams@aston.ac.uk>
• Andrea Spinelli <spinellia@acm.org>

---

and that's the whole page, angel 💖 this man page is perl v5.36.0, dated 2022-11-20, and it's filed as VecStat(3pm). go forth and compute your little vectors, you absolute main character ✨🦋