NAME

PDL::Primitive - primitive operations for pdl

DESCRIPTION

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.

SYNOPSIS

use PDL::Primitive;

Project via $name to N-1 dimensions

This function reduces the dimensionality of a piddle by one by taking the $name along the 1st dimension.

By using xchg etc. (see PDL::Slices) it is possible to use any dimension.

\$a = $op(\$b);

\$spectrum = $op \$image->xchg(0,1)

$extras

Cumulative $name

This function calculates the cumulative $name along the 1st dimension.

By using xchg etc. (see PDL::Slices) it is possible to use any dimension.

The sum is started so that the first element in the cumulative $name is the first element of the parameter.

\$a = $op(\$b);

\$spectrum = $op \$image->xchg(0,1)

$extras

$op->[0]

Return the $op->[2] of all elements in a piddle

\$x = $op->[0](\$data);

any

Return true if any element in piddle set

Useful in conditional expressions:

if (any $a>15) { print "some values are greater than 15\n" }

all

Return true if all elements in piddle set

Useful in conditional expressions:

if (all $a>15) { print "all values are greater than 15\n" }

minmax

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";

Quicksort a vector into ascending order.

print qsort random(10);

Quicksort a vector and return index of elements in ascending order.

$ix = qsorti $a; print $a->index($ix); # Sorted list

Internal routine

axisvalues is the internal primitive that implements axisvals and alters its argument.

Inner product over one dimension

c = sum_i a_i * b_i

');

defpdl( 'outer', 'a(n); b(m); [o]c(n,m); ', '', 'loop(n,m) %{ $c() = $a() * $b(); %}', <<'EOD' =for ref

outer product over one dimension

Naturally, it is possiblet to achieve the effects of outer product simply by threading over the "*" operator but this function is provided for convenience.

matmult

Signature: matmult(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

Weighted (i.e. triple) inner product

d = sum_i a(i) b(i) c(i)

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.

Inner product over 2 dimensions.

Equivalent to

$c = inner($a->clump(2), $b->clump(2))

' );

defpdl( 'inner2t', 'a(j,n); b(n,m); c(m,k); [t]tmp(n,k); [o]d(j,k));', '', ' loop(n,k) %{ double tmp0 = 0; loop(m) %{ tmp0 += $b() * $c(); %} $tmp() = tmp0; %} loop(j,k) %{ double tmp1 = 0; loop(n) %{ tmp1 += $a() * $tmp(); %} $d() = tmp1; %}',<<'EOD'); =for ref

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.

minimum_ind(a(n),int [o]c()), maximum_ind(a(n),int [o]c())

These functions work like the previous except that they return the index of the maximum element

minimum_n_ind(a(n),int [o]c(m)), maximum_n_ind(a(n),int [o]c(m))

These functions work like the previous except that they return the indices of the m maximum elements.

minmaximum

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.

clip

Clip a piddle by (optional) upper or lower bounds.

$b = $a->clip(0,3);
$c = $a->clip(undef, $x);

wtstat

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)

random

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.

randsym

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.

grandom

Constructor which returns piddle of Gaussian random numbers

$a = grandom([type], $nx, $ny, $nz,...);
$a = grandom $b;

etc. See 'zeroes'

This is generated by summing 12 uniform random distributions for now. Hopefully someone can be inspired to create a better version!

Mean = 0, Stddev = 1

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. EOD

pp_def('interpol', Pars => 'i(); x(n); y(n); [o] ip()', GenericTypes => [F,D], # too restrictive ? Code => 'int carp=0; threadloop %{ long n1 = $SIZE(n)-1; long jl=-1, jh=n1, m; int up = ($x(n => n1) > $x(n => 0)); $GENERIC() d; while (jh-jl > 1) /* binary search */ { m = (jh+jl) >> 1; if ($i() > $x(n => m) == up) jl = m; else jh = m; } if (jl == -1) { if ($i() != $x(n => 0)) carp = 1; jl = 0; } else if (jl == n1) { if ($i() != $x(n => n1)) carp = 1; jl = n1-1; } jh = jl+1; if ((d = $x(n => jh)-$x(n => jl)) == 0) barf("identical abscissas"); d = ($x(n => jh)-$i())/d; $ip() = d*$y(n => jl) + (1-d)*$y(n => jh); %} if (carp) warn("some values had to be extrapolated"); ', Doc=><<'EOD');

routine for 1D linear interpolation

$interpolated_values = interpol($interpol_at, $ordered_abscissas, $yvalues)

'interpol' uses a binary search to find the suspects, er..., interpolation indices and therefore abscissas 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 issues a warning upon completion.

one2nd

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

which

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]

which_both

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]

where

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

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.

EOD );

for({Name => 'histogram', WeightPar => '', HistType => 'int+', HistOp => '++', Doc1 => "", Doc2 => "", Doc3 => "number of\n", Doc4 => "\nUse hist() instead for a high-level interface.\n", Doc5 => "histogram(pdl(1,1,2),1,0,3)\n [0 2 1]"}, {Name => 'whistogram', WeightPar => 'float+ wt(n);', HistType => 'float+', HistOp => '+= $wt()', Doc1 => " from weighted data", Doc2 => "\$weights, ", Doc3 => "sum of the values in \$weights\nthat correspond to ", Doc4 => "", Doc5 => "whistogram(pdl(1,1,2), pdl(0.1,0.1,0.5), 1, 0, 4)\n [0 0.2 0.5 0]"}) { pp_def($_->{Name}, Pars => 'in(n); '.$_->{WeightPar}.$_->{HistType}. '[o] hist(m)', # set outdim by Par! OtherPars => 'double step; double min; int msize => m', Code => 'register int j; register int maxj = $SIZE(m)-1; register double min = $COMP(min); register double step = $COMP(step); threadloop %{ loop(m) %{ $hist() = 0; %} %} threadloop %{ loop(n) %{ j = (int) (($in()-min)/step); if (j<0) j=0; if (j > maxj) j = maxj; ($hist(m => j))'.$_->{HistOp}.'; %} %} ', Doc=><<"EOD");

Calculates a histogram$_->{Doc1} for given stepsize and minimum.

\$h = $_->{Name}(\$data, $_->{Doc2}\$step, \$min, \$numbins);
\$hist = zeroes \$numbins;  # Put histogram in existing piddle.
$_->{Name}(\$data, $_->{Doc2}\$hist, \$step, \$min, \$numbins);

The histogram will contain \$numbins bins starting from \$min, each \$step wide. The value in each bin is the $_->{Doc3}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. $_->{Doc4} =for example

perldl> p $_->{Doc5}

Calculates a 2d histogram$_->{Doc1}.

\$h = $_->{Name}(\$datax, \$datay,$_->{Doc2}
      \$stepx, \$minx, \$nbinx, \$stepy, \$miny, \$nbiny);
\$hist = zeroes \$nbinx, \$nbiny;  # Put histogram in existing piddle.
$_->{Name}(\$datax, \$datay,$_->{Doc2} \$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 $_->{Doc3}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 $_->{Doc5}

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

stats

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.

whichND

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($x,$y,$z,$w)
203

AUTHOR

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.

cpanm PDL

perl -MCPAN -e shell
install PDL