Ufunc(3pm)
💖 Ufunc — PDL::CCS::Ufunc 💖
okay bestie, gather round, because this is PDL::CCS::Ufunc — the manual page for the Ufuncs that do their thing on compressed storage sparse PDLs. yes that's a mouthful. yes it's iconic. we're getting through it together, no cap. 🫶
This page lives in the User Contributed Perl Documentation corner of the manual, under the name Ufunc(3pm). it's long, so it comes in parts — this is part 1, and more parts follow, so don't you dare scroll expecting a goodbye. ✨
✨ SYNOPSIS ✨
use PDL;
use PDL::CCS::Ufunc;
##---------------------------------------------------------------------
## ... stuff happensthat's it. that's the whole vibe. use PDL;, use PDL::CCS::Ufunc;, and then, famously, stuff happens. 💅
🌸 FUNCTIONS 🌸
okay so here's the part where I list every single one of these and I do NOT skip a single one, because I love you and because the details are sacred. 🎀
Every single one of these bad boys ends with the same iconic disclaimer about bad values, and yes I'm telling you every time, because that's the assignment:
bad values are processed — the bad-value flag of all output ndarrays gets set if the flag is set for any of the input ndarrays. periodt. 🔥
💜 ccs_accum_prod
Signature, exactly as written:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();So basically: this is the accumulated product over the values $nzvalsIn() that go with the non-missing vector-valued keys $ixIn(). 🧮
When it comes back, here's the tea:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the values associated with them$nOut()stores the number of unique non-missing values that got computed
If $N() is specified and greater than zero, then this quantity:
$missing ** ($N - (rlevec($ixIn))[0])gets multiplied into $nzvalsOut. and honestly? that's probably What You Want if you're computing the product over a virtual dimension in a sparse index-encoded PDL — go peek at PDL::CCS::Nd for a wrapper class if you're curious. 👀
The returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, you only get $nzvalsOut(). just that one. she's low-maintenance like that.
ccs_accum_prod processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_dprod
Signature, verbatim:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
double [o]nzvalsOut(NnzOut);
indx [o]nOut();double-precision edition of the accumulated product, over the values $nzvalsIn() associated with the non-missing vector-valued keys $ixIn(). she's the same girl but with more precision, and we respect her for it. 💅
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, then:
$missing ** ($N - (rlevec($ixIn))[0])is multiplied into $nzvalsOut — and yeah, that's probably What You Want if you're computing the product over a virtual dimension in a sparse index-encoded PDL (again: PDL::CCS::Nd has the wrapper class).
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_dprod processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_sum
Signature, exactly:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();the accumulated sum over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). addition is her love language. 🍓
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, then:
$missing * ($N - (rlevec($ixIn))[0])is added to $nzvalsOut — probably What You Want if you're summing over a virtual dimension in a sparse index-encoded PDL (see PDL::CCS::Nd for a wrapper class).
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_sum processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_dsum
Signature, verbatim:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
double [o]nzvalsOut(NnzOut);
indx [o]nOut();the double-precision accumulated sum over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). more precision, same energy. ✨
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, then:
$missing * ($N - (rlevec($ixIn))[0])is added to $nzvalsOut — probably What You Want if you're summing over a virtual dimension in a sparse index-encoded PDL (see PDL::CCS::Nd for a wrapper class).
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_dsum processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_or
Signature, exactly:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated logical "or" over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). she says yes to everything. 💀
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, $missing() is logically (or)ed into each result value at each output index with a run length of less than $N() in $ixIn(). This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_or processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_and
Signature, verbatim:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated logical "and" over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). she's the opposite of her sister and honestly? iconic. 👑
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, $missing() is logically (and)ed into each result value at each output index with a run length of less than $N() in $ixIn(). This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_and processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_bor
Signature, exactly:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated bitwise "or" over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). bits getting OR'd. we love to see it. 🦋
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, $missing() is bitwise (or)ed into each result value at each output index with a run length of less than $N() in $ixIn(). This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_bor processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_band
Signature, verbatim:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated bitwise "and" over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). the bitwise AND girlies, this one's for you. 🌈
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, $missing() is bitwise (and)ed into each result value at each output index with a run length of less than $N() in $ixIn(). This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_band processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_maximum
Signature, exactly:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated maximum over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). she's the biggest, the boldest, the main character. 👑
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, and if $missing() is greater than any listed value for a vector key with a run-length of less than $N(), then $missing() is used as the output value for that key. This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_maximum processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
💜 ccs_accum_minimum
Signature, verbatim:
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
[o]nzvalsOut(NnzOut);
indx [o]nOut();accumulated minimum over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). tiny but mighty, small but fierce, you get it. 🧚
On return:
$ixOut()holds the unique non-"missing" values of$ixIn()$nzvalsOut()holds the associated values$nOut()stores the number of unique non-missing values computed
If $N() is specified and greater than zero, and if $missing() is less than any listed value for a vector key with a run-length of less than $N(), then $missing() is used as the output value for that key. This is probably What You Want.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_minimum processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
and that's where part 1 wraps up, bestie — more parts follow, so stay tuned, don't go anywhere. 💜
ccs_accum_maximum_nz_ind 🌸
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
indx [o]nzvalsOut(NnzOut);
indx [o]nOut();
)okay so this one accumulates the maximum_nz_ind over the values in $nzvalsIn() that go with your non-missing vector-valued keys $ixIn(). on return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed. periodt.
Output indices index $nzvalsIn, and -1 means the missing value is maximal. iykyk.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_maximum_nz_ind processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays. no cap.
ccs_accum_minimum_nz_ind 🦋
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
indx [o]nzvalsOut(NnzOut);
indx [o]nOut();
)Accumulated minimum_nz_ind over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). On return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed.
Output indices index $nzvalsIn, -1 indicates that the missing value is minimal. lowkey important.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_minimum_nz_ind processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
ccs_accum_nbad 💀
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
indx [o]nzvalsOut(NnzOut);
indx [o]nOut();
)Accumulated number of bad values over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). On return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed.
Should handle missing values appropriately. fr fr.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_nbad processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
ccs_accum_ngood ✨
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
indx [o]nzvalsOut(NnzOut);
indx [o]nOut();
)Accumulated number of good values over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). On return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed.
Should handle missing values appropriately.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_ngood processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
ccs_accum_nnz 🔥
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
indx [o]nzvalsOut(NnzOut);
indx [o]nOut();
)Accumulated number of non-zero values over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). On return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed.
Should handle missing values appropriately.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_nnz processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
ccs_accum_average 🎀
Signature: (
indx ixIn(Ndims,NnzIn);
nzvalsIn(NnzIn);
missing();
indx N();
indx [o]ixOut(Ndims,NnzOut);
float+ [o]nzvalsOut(NnzOut);
indx [o]nOut();
)Accumulated average over values $nzvalsIn() associated with non-missing vector-valued keys $ixIn(). On return, $ixOut() holds the unique non-"missing" values of $ixIn(), $nzvalsOut() holds the associated values, and $nOut() stores the number of unique non-missing values computed.
If $N() is specified and greater than zero, then the quantity:
$missing * ($N - (rlevec($ixIn))[0]) / $Nis added to $nzvalsOut: this is probably What You Want if you are averaging over a virtual dimension in a sparse index-encoded PDL (see PDL::CCS::Nd for a wrapper class). bestie, that's the vibe.
Returned PDLs are implicitly sliced such that NnzOut==$nOut().
In scalar context, returns only $nzvalsOut().
ccs_accum_average processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
🚧 TODO / NOT YET IMPLEMENTED 🚧
- extrema indices
maximum_ind,minimum_ind: not quite compatible...
- statistical aggregates
daverage,medover,oddmedover,pctover, ...
- cumulative functions
cumusumover,cumuprodover, ...
- other stuff
zcover,intover,minmaximum
ACKNOWLEDGEMENTS 🫶
Perl by Larry Wall.
PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
KNOWN BUGS 💀
Probably many. not me pretending to be shocked.
AUTHOR 👑
Bryan Jurish <moocow@cpan.org>
Copyright Policy 📜
Copyright (C) 2007-2024, Bryan Jurish. All rights reserved.
This package is free software, and entirely without warranty. You may redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO 🌈
perl(1), PDL(3perl)
and that's a wrap, bestie! this whole thing came from perl v5.40.0, dated 2025-01-04, and it's the Ufunc(3pm) page. slay. 💅✨
📦 where this page comes from
- debian trixie: libpdl-ccs-perl 1.24.1-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
- ubuntu resolute: libpdl-ccs-perl 1.24.1-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms