NAME
PDL::VectorValued::Utils - Low-level utilities for vector-valued PDLs
SYNOPSIS
use PDL;
use PDL::VectorValued::Utils;
##---------------------------------------------------------------------
## ... stuff happens
FUNCTIONS
Vector-Based Run-Length Encoding and Decoding
rlevec
Signature: (c(M,N); int [o]a(N); [o]b(M,N))
Run-length encode a set of vectors.
Higher-order rle(), for use with qsortvec().
Given set of vectors $c, generate a vector $a with the number of occurrences of each element (where an "element" is a vector of length $M ocurring in $c), and a set of vectors $b containing the unique values. As for rle(), only the elements up to the first instance of 0 in $a should be considered.
Can be used together with clump() to run-length encode "values" of arbitrary dimensions. Can be used together with rotate(), cat(), append(), and qsortvec() to count N-grams over a 1d PDL.
See also: PDL::Slices::rle, PDL::Ufunc::qsortvec, PDL::Primitive::uniqvec
rlevec does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
rldvec
Signature: (int a(N); b(M,N); [o]c(M,N))
Run-length decode a set of vectors, akin to a higher-order rld().
Given a vector $a() of the number of occurrences of each row, and a set $c() of row-vectors each of length $M, run-length decode to $c().
Can be used together with clump() to run-length decode "values" of arbitrary dimensions.
See also: PDL::Slices::rld.
rldvec does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
enumvec
Signature: (v(M,N); int [o]k(N))
Enumerate a list of vectors with locally unique keys.
Given a sorted list of vectors $v, generate a vector $k containing locally unique keys for the elements of $v (where an "element" is a vector of length $M ocurring in $v).
enumvec does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
vsearchvec
Signature: (find(M); which(M,N); int [o]found())
Routine for searching N-dimensional values - akin to vsearch() for vectors.
$found = ccs_vsearchvec($find, $which);
$nearest = $which->dice_axis(1,$found);
Returns for each row-vector in $find
the index along dimension N of the least row vector of $which
greater or equal to it. $which
should be sorted in increasing order. If the value of $find
is larger than any member of $which
, the index to the last element of $which
is returned.
See also: PDL::Primitive::vsearch().
vsearchvec does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
Vector-Valued Sorting and Comparison
The following functions are provided for lexicographic sorting of vectors, rsp. axis indices. Note that vv_qsortvec() is functionally identical to the builtin PDL function qsortvec(), but also that the latter is broken in the stock PDL-2.4.3 distribution. The version included here includes Chris Marshall's "uniqsortvec" patch, which is available here:
http://sourceforge.net/tracker/index.php?func=detail&aid=1548824&group_id=612&atid=300612
cmpvec
Signature: (a(N); b(N); int [o]cmp())
Lexicographically compare a pair of vectors.
cmpvec does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
vv_qsortvec
Signature: (a(n,m); [o]b(n,m))
Drop-in replacement for qsortvec(), which is broken in the stock PDL-2.4.3 release. See PDL::Ufunc::qsortvec.
Vectors with bad components should be moved to the end of the array.
vv_qsortveci
Signature: (a(n,m); int [o]ix(m))
Get lexicographic sort order of a matrix $a() viewed as a list of vectors.
Vectors with bad components should be treated as last in the lexicographic order.
Vector-Valued Set Operations
The following functions are provided for set operations on sorted vector-valued PDLs.
vv_union
Signature: (a(M,NA); b(M,NB); [o]c(M,NC); int [o]nc())
Union of two vector-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the union.
In scalar context, slices $c() to the actual number of elements in the union and returns the sliced PDL.
vv_union does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
vv_intersect
Signature: (a(M,NA); b(M,NB); [o]c(M,NC); int [o]nc())
Intersection of two vector-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the intersection.
In scalar context, slices $c() to the actual number of elements in the intersection and returns the sliced PDL.
vv_intersect does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
vv_setdiff
Signature: (a(M,NA); b(M,NB); [o]c(M,NC); int [o]nc())
Set-difference ($a() \ $b()) of two vector-valued PDLs. Input PDLs $a() and $b() MUST be sorted in lexicographic order. On return, $nc() holds the actual number of vector-values in the computed vector set.
In scalar context, slices $c() to the actual number of elements in the output vector set and returns the sliced PDL.
vv_setdiff does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.
ACKNOWLEDGEMENTS
Perl by Larry Wall
PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.
Code for rlevec() and rldvec() derived from the PDL builtin functions rle() and rld() in $PDL_SRC_ROOT/Basic/Slices/slices.pd
Code for vv_qsortvec() copied nearly verbatim from the builtin PDL functions in $PDL_SRC_ROOT/Basic/Ufunc/ufunc.pd, with Chris Marshall's "uniqsortvec" patch. Code for vv_qsortveci() based on the same.
KNOWN BUGS
Probably many.
AUTHOR
Bryan Jurish <moocow@cpan.org>
COPYRIGHT
Code for qsortvec() copyright (C) Tuomas J. Lukka 1997. Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.
All other parts copyright (c) 2007, 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)