PDL::Primitive - primitive operations for pdl
This module provides some primitive and useful functions defined using PDL::PP and able to use the new indexing tricks.
See PDL::Indexing for how to use indices creatively. For explanation of the signature format, see PDL::PP.
use PDL::Primitive;
Signature: (a(n); int+ [o]b())
Project via sum to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the sum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = sumover($b);
$spectrum = sumover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via != 0 to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the != 0 along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = zcover($b);
$spectrum = zcover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via and to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the and along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = andover($b);
$spectrum = andover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via bitwise and to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the bitwise and along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = bandover($b);
$spectrum = bandover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via or to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the or along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = orover($b);
$spectrum = orover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via bitwise or to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the bitwise or along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = borover($b);
$spectrum = borover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via integral to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the integral along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = intover($b);
$spectrum = intover $image->xchg(0,1)
Notes:
For n > 3
, these are all O(h^4)
(like Simpson's rule), but are
integrals between the end points assuming the pdl gives values just at
these centres: for such `functions', sumover is correct to O(h)
, but
is the natural (and correct) choice for binned data, of course.
Signature: (a(n); int+ [o]b(n))
Cumulative sum
This function calculates the cumulative sum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative sum is the first element of the parameter.
$a = cumusumover($b);
$spectrum = cumusumover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via product to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the product along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = prodover($b);
$spectrum = prodover $image->xchg(0,1)
Signature: (a(n); int+ [o]b(n))
Cumulative product
This function calculates the cumulative product along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
The sum is started so that the first element in the cumulative product is the first element of the parameter.
$a = cumuprodover($b);
$spectrum = cumuprodover $image->xchg(0,1)
Signature: (a(n); int+ [o]b())
Project via average to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the average along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = average($b);
$spectrum = average $image->xchg(0,1)
Signature: (a(n); [o]b(); [t]tmp(n))
Project via median to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the median along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = medover($b);
$spectrum = medover $image->xchg(0,1)
Signature: (a(n); [o]b(); [t]tmp(n))
Project via oddmedian to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the oddmedian along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = oddmedover($b);
$spectrum = oddmedover $image->xchg(0,1)
The median is sometimes not a good choice as if the array has an even number of elements it lies half-way between the two middle values - thus it does not always correspond to a data value. The lower-odd median is just the lower of these two values and so it ALWAYS sits on an actual data value which is useful in some circumstances.
Return the average of all elements in a piddle
$x = avg($data);
Return the sum of all elements in a piddle
$x = sum($data);
Return the check for zero of all elements in a piddle
$x = zcheck($data);
Return the logical and of all elements in a piddle
$x = and($data);
Return the bitwise and of all elements in a piddle
$x = band($data);
Return the logical or of all elements in a piddle
$x = or($data);
Return the bitwise or of all elements in a piddle
$x = bor($data);
Return the minimum of all elements in a piddle
$x = min($data);
Return the maximum of all elements in a piddle
$x = max($data);
Return the median of all elements in a piddle
$x = median($data);
Return the oddmedian of all elements in a piddle
$x = oddmedian($data);
Return true if any element in piddle set
Useful in conditional expressions:
if (any $a>15) { print "some values are greater than 15\n" }
Return true if all elements in piddle set
Useful in conditional expressions:
if (all $a>15) { print "all values are greater than 15\n" }
Returns an array with minimum, maximum of a piddle.
($mn, $mx) = minmax($pdl);
Return $mn
as minimum, $mx
as maximum, $mn_ind
as the index of minimum and
$mx_ind
as the index of the maximum.
perldl> $x = pdl [1,-2,3,5,0] perldl> ($min, $max) = minmax($x); perldl> p "$min $max\n"; -2 5
Signature: (a(n); [o]b(n))
Quicksort a vector into ascending order.
print qsort random(10);
Signature: (a(n); int [o]indx(n))
Quicksort a vector and return index of elements in ascending order.
$ix = qsorti $a; print $a->index($ix); # Sorted list
Signature: ([o,nc]a(n))
Internal routine
axisvalues
is the internal primitive that implements
axisvals
and alters its argument.
Signature: (a(n); b(n); [o]c(); )
Inner product over one dimension
c = sum_i a_i * b_i
Signature: (a(n); b(m); [o]c(n,m); )
outer product over one dimension
Naturally, it is possible to achieve the effects of outer
product simply by threading over the ``*
''
operator but this function is provided for convenience.
Signature: (a(x,y),b(y,z),[o]c(x,z))
Matrix multiplication
We peruse the inner product to define matrix multiplication via a threaded inner product
Signature: (a(n); b(n); c(n); [o]d(); )
Weighted (i.e. triple) inner product
d = sum_i a(i) b(i) c(i)
Signature: (a(n); b(n,m); c(m); [o]d())
Inner product of two vectors and a matrix
d = sum_ij a(i) b(i,j) c(j)
Note that you should probably not thread over a
and c
since that would be
very wasteful. Instead, you should use a temporary for b*c
.
Signature: (a(n,m); b(n,m); [o]c())
Inner product over 2 dimensions.
Equivalent to
$c = inner($a->clump(2), $b->clump(2))
Signature: (a(j,n); b(n,m); c(m,k); [t]tmp(n,k); [o]d(j,k)))
Efficient Triple matrix product a*b*c
Efficiency comes from by using the temporary tmp
. This operation only scales as
N**3
whereas threading using inner2 would scale as N**4
.
The reason for having this routine is that you do not need to
have the same thread-dimensions for tmp
as for the other arguments,
which in case of large numbers of matrices makes this much more
memory-efficient.
It is hoped that things like this could be taken care of as a kind of closures at some point.
Signature: (a(n); [o]c())
Project via minimum to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the minimum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = minimum($b);
$spectrum = minimum $image->xchg(0,1)
Signature: (a(n); int[o]c())
Like minimum but returns the index rather than the value
Signature: (a(n); int[o]c(m))
Returns the index of m
minimum elements
Signature: (a(n); [o]c())
Project via maximum to N-1 dimensions
This function reduces the dimensionality of a piddle by one by taking the maximum along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = maximum($b);
$spectrum = maximum $image->xchg(0,1)
Signature: (a(n); int[o]c())
Like maximum but returns the index rather than the value
Signature: (a(n); int[o]c(m))
Returns the index of m
maximum elements
Find minimum and maximum and their indices for a given piddle;
perldl> $a=pdl [[-2,3,4],[1,0,3]] perldl> ($min, $max, $min_ind, $max_ind)=minmaximum($a) perldl> p $min, $max, $min_ind, $max_ind [-2 0] [4 3] [0 1] [2 2]
See also minmax, which clumps the piddle together.
Signature: (a(n); [o]cmin(); [o] cmax(); int [o]cmin_ind(); int [o]cmax_ind())
info not available
Signature: (a(); b(); [o] c())
clip $a
by $b
($b
is upper bound)
Signature: (a(); b(); [o] c())
clip $a
by $b
($b
is lower bound)
Clip a piddle by (optional) upper or lower bounds.
$b = $a->clip(0,3); $c = $a->clip(undef, $x);
Signature: (a(n); wt(n); avg(); [o]b(); int deg)
Weighted statistical moment of given degree
This calculates a weighted statistic over the vector a
.
The formula is
b() = (sum_i wt_i * (a_i ** degree - avg)) / (sum_i wt_i)
Constructor which returns piddle of random numbers
$a = random([type], $nx, $ny, $nz,...); $a = random $b;
etc (see zeroes).
This is the uniform distribution between 0 and 1 (assumedly
excluding 1 itself). The arguments are the same as zeroes
(q.v.) - i.e. one can specify dimensions, types or give
a template.
Constructor which returns piddle of random numbers
$a = randsym([type], $nx, $ny, $nz,...); $a = randsym $b;
etc (see zeroes).
This is the uniform distribution between 0 and 1 (excluding both 0 and
1, cf random). The arguments are the same as zeroes
(q.v.) -
i.e. one can specify dimensions, types or give a template.
Constructor which returns piddle of Gaussian random numbers
$a = grandom([type], $nx, $ny, $nz,...); $a = grandom $b;
etc (see zeroes).
This is generated using the math library routine ndtri
.
Mean = 0, Stddev = 1
Signature: (a(); [o]b())
Plain numerical assignment. This is used to implement the ``.='' operator
Signature: (i(); x(n); int [o]ip())
routine for searching 1D values i.e. step-function interpolation.
$inds = vsearch($vals, $xs);
Returns for each value of $val
the index of the least larger member
of $xs
(which need to be in increasing order). If the value is larger
than any member of $xs
, the index to the last element of $xs
is
returned.
This function is useful e.g. when you have a list of probabilities for events and want to generate indices to events:
$a = pdl(.01,.86,.93,1); # Barnsley IFS probabilities cumulatively $b = random 20; $c = vsearch($b, $a); # Now, $c will have the appropriate distr.
It is possible to use the cumusumover function to obtain cumulative probabilities from absolute probabilities.
Signature: (xi(); x(n); y(n); [o] yi(); int [o] err())
routine for 1D linear interpolation
( $yi, $err ) = interpolate($xi, $x, $y)
Given a set of points ($x,$y)
, use linear interpolation
to find the values $yi
at a set of points $xi
.
interpolate
uses a binary search to find the suspects, er...,
interpolation indices and therefore abscissas (ie $x
)
have to be strictly ordered (increasing or decreasing).
For interpolation at lots of
closely spaced abscissas an approach that uses the last index found as
a start for the next search can be faster (compare Numerical Recipes
hunt
routine). Feel free to implement that on top of the binary
search if you like. For out of bounds values it just does a linear
extrapolation and sets the corresponding element of $err
to 1,
which is otherwise 0.
See also interpol, which uses the same routine, differing only in the handling of extrapolation - an error message is printed rather than returning an error piddle.
Signature: (xi(); x(n); y(n); [o] yi())
routine for 1D linear interpolation
$yi = interpol($xi, $x, $y)
interpol
uses the same search method as interpolate,
hence $x
must be strictly ordered (either increasing or decreasing).
The difference occurs in the handling of out-of-bounds values; here
an error message is printed.
Converts a one dimensional index piddle to a set of ND coordinates
@coords=one2nd($a, $indices)
returns an array of piddles containing the ND indexes corresponding to
the one dimensional list indices. The indices are assumed to correspond
to array $a
clumped using clump(-1)
. This routine is used in
whichND,
but is useful on its own occasionally.
perldl> $a=pdl [[[1,2],[-1,1]], [[0,-3],[3,2]]]; $c=$a->clump(-1) perldl> $maxind=maximum_ind($c); p $maxind; 6 perldl> print one2nd($a, maximum_ind($c)) 0 1 1 perldl> p $a->at(0,1,1) 3
Signature: (mask(n); int [o] inds(m))
Returns piddle of indices of non-zero values.
$i = which($mask);
returns a pdl with indices for all those elements that are
nonzero in the mask. Note that mask really has to be 1-D (use clump(-1)
if you need to work with ND-images)
If you want to return both the indices of non-zero values and the complement, use the function which_both.
perldl> $x = sequence(10); p $x [0 1 2 3 4 5 6 7 8 9] perldl> $indx = which($x>6); p $indx [7 8 9]
Signature: (mask(n); int [o] inds(m); int [o]notinds(q))
Returns piddle of indices of non-zero values and their complement
($i, $c_i) = which_both($mask);
This works just as which, but the complement of $i
will be in $c_i
.
perldl> $x = sequence(10); p $x [0 1 2 3 4 5 6 7 8 9] perldl> ($small, $big) = which_both ($x >= 5); p "$small\n $big" [5 6 7 8 9] [0 1 2 3 4]
Returns indices to non-zero values or those values from another piddle.
$i = $x->where($x+5 > 0); # $i contains elements of $x # where mask ($x+5 > 0) is 1
Note: $i
is always 1-D, even if $x
is >1-D. The first argument
(the values) and the second argument (the mask) currently have to have
the same initial dimensions (or horrible things happen).
It is also possible to use the same mask for several piddles with the same call:
($i,$j,$k) = where($x,$y,$z, $x+5>0);
There is also the following syntax, retained only for compatibility with PDL versions < 1.99. This use is deprecated, and will be removed in the future. Use which instead.
$i = where($x > 0); # indices to $x, equivalent to 'which()'
Note: the mask has to be 1-D. See the documentation for which
Signature: (a(n); b(m); [o] c(mn))
append two piddles by concantening along their respective first dimensions
$a = ones(2,4,7); $b = sequence 5; $c = $a->append($b); # size of $c is now (7,4,7) (a jumbo-piddle ;)
append
appends two piddles along their first dims. Rest of the dimensions
must be compatible in the threading sense. Resulting size of first dim is
sum of sizes of the two argument piddles' first dims.
Signature: (in(n); int+[o] hist(m); double step; double min; int msize => m)
Calculates a histogram for given stepsize and minimum.
$h = histogram($data, $step, $min, $numbins); $hist = zeroes $numbins; # Put histogram in existing piddle. histogram($data, $hist, $step, $min, $numbins);
The histogram will contain $numbins
bins starting from $min
, each
$step
wide. The value in each bin is the number of
values in $data
that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
The output is reset in a different threadloop so that you
can take a histogram of $a(10,12)
into $b(15)
and get the result
you want.
Use hist instead for a high-level interface.
perldl> p histogram(pdl(1,1,2),1,0,3) [0 2 1]
Signature: (in(n); float+ wt(n);float+[o] hist(m); double step; double min; int msize => m)
Calculates a histogram from weighted data for given stepsize and minimum.
$h = whistogram($data, $weights, $step, $min, $numbins); $hist = zeroes $numbins; # Put histogram in existing piddle. whistogram($data, $weights, $hist, $step, $min, $numbins);
The histogram will contain $numbins
bins starting from $min
, each
$step
wide. The value in each bin is the sum of the values in $weights
that correspond to values in $data
that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
The output is reset in a different threadloop so that you
can take a histogram of $a(10,12)
into $b(15)
and get the result
you want.
perldl> p whistogram(pdl(1,1,2), pdl(0.1,0.1,0.5), 1, 0, 4) [0 0.2 0.5 0]
Signature: (ina(n); inb(n); int+[o] hist(ma,mb); double stepa; double mina; int masize => ma; double stepb; double minb; int mbsize => mb;)
Calculates a 2d histogram.
$h = histogram2d($datax, $datay, $stepx, $minx, $nbinx, $stepy, $miny, $nbiny); $hist = zeroes $nbinx, $nbiny; # Put histogram in existing piddle. histogram2d($datax, $datay, $hist, $stepx, $minx, $nbinx, $stepy, $miny, $nbiny);
The histogram will contain $nbinx
x $nbiny
bins, with the lower
limits of the first one at ($minx, $miny)
, and with bin size
($stepx, $stepy)
.
The value in each bin is the number of
values in $datax
and $datay
that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
perldl> p histogram2d(pdl(1,1,1,2,2),pdl(2,1,1,1,1),1,0,3,1,0,3) [ [0 0 0] [0 2 2] [0 1 0] ]
Signature: (ina(n); inb(n); float+ wt(n);float+[o] hist(ma,mb); double stepa; double mina; int masize => ma; double stepb; double minb; int mbsize => mb;)
Calculates a 2d histogram from weighted data.
$h = whistogram2d($datax, $datay, $weights, $stepx, $minx, $nbinx, $stepy, $miny, $nbiny); $hist = zeroes $nbinx, $nbiny; # Put histogram in existing piddle. whistogram2d($datax, $datay, $weights, $hist, $stepx, $minx, $nbinx, $stepy, $miny, $nbiny);
The histogram will contain $nbinx
x $nbiny
bins, with the lower
limits of the first one at ($minx, $miny)
, and with bin size
($stepx, $stepy)
.
The value in each bin is the sum of the values in
$weights
that correspond to values in $datax
and $datay
that lie within the bin limits.
Data below the lower limit is put in the first bin, and data above the upper limit is put in the last bin.
perldl> p whistogram2d(pdl(1,1,1,2,2),pdl(2,1,1,1,1),pdl(0.1,0.2,0.3,0.4,0.5),1,0,3,1,0,3) [ [ 0 0 0] [ 0 0.5 0.9] [ 0 0.1 0] ]
Signature: (a(tri=3); b(tri); [o] c(tri))
Cross product of two 3D vectors
After
$c = crossp $a, $b
the inner product $c*$a
and $c*$b
will be zero, i.e. $c
is
orthogonal to $a
and $b
Signature: (vec(n); [o] norm(n))
Normalises a vector to unit Euclidean length
Calculates useful statistics on a piddle
($mean,$rms,$median,$min,$max) = stats($piddle,[$weights]);
This utility calculates all the most useful quantities in one call.
Note: The RMS value that this function returns in the RMS deviation from the mean, also known as the population standard- deviation.
Returns the coordinates for non-zero values
@coords=whichND($mask);
returns an array of piddles containing the coordinates of the elements
that are non-zero in $mask
.
perldl> $a=sequence(10,10,3,4) perldl> ($x, $y, $z, $w)=whichND($a == 203); p $x, $y, $z, $w [3] [0] [2] [0] perldl> print $a->at(list(cat($x,$y,$z,$w))) 203
Signature: ([o]x(n))
Constructor - a vector with Fibonacci's sequence
Signature: (a(); int ind(); [o] sum(m))
Threaded Index Add: Add a
to the ind
element of sum
, i.e:
sum(ind) += a
Simple Example:
$a = 2; $ind = 3; $sum = zeroes(10); indadd($a,$ind, $sum); print $sum #Result: ( 2 added to element 3 of $sum) # [0 0 0 2 0 0 0 0 0 0]
Threaded Example:
$a = pdl( 1,2,3); $ind = pdl( 1,4,6); $sum = zeroes(10); indadd($a,$ind, $sum); print $sum."\n"; #Result: ( 1, 2, and 3 added to elements 1,4,6 $sum) # [0 1 0 0 2 0 3 0 0 0]
Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu) 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.