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 the PDL/Indexing manpage for how to use indices creatively.

For explanation of the signature format, see the PDL/PP manpage.


SYNOPSIS

 use PDL::Primitive;


FUNCTIONS


sumover

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = sumover($b);

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


intover

  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. (see the PDL/Slices manpage) 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.


cumusumover

  Signature: (a(n); int+ [o]b(n))

Cumulative sum

This function calculates the cumulative sum along the 1st dimension.

By using xchg etc. (see the PDL/Slices manpage) 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)


prodover

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = prodover($b);

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


cumuprodover

  Signature: (a(n); int+ [o]b(n))

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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = prodover($b);

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


average

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = average($b);

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


medover

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = medover($b);

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


oddmedover

  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. (see the PDL/Slices manpage) 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.


avg

Return the average of all elements in a piddle

$x = avg($data);


sum

Return the sum of all elements in a piddle

$x = sum($data);


min

Return the minimum of all elements in a piddle

$x = min($data);


max

Return the maximum of all elements in a piddle

$x = max($data);


median

Return the median of all elements in a piddle

$x = median($data);


oddmedian

Return the oddmedian of all elements in a piddle

$x = oddmedian($data);


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


qsort

  Signature: (a(n); [o]b(n))

Quicksort a vector into ascending order.

print qsort random(10);


qsorti

  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


axisvalues

  Signature: ([o,nc]a(n))

Internal routine

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


inner

  Signature: (a(n); b(n); [o]c(); )

Inner product over one dimension

        c = sum_i a_i * b_i


outer

  Signature: (a(n); b(m); [o]c(n,m); )

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


innerwt

  Signature: (a(n); b(n); c(n); [o]d(); )

Weighted (i.e. triple) inner product

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


inner2

  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.


inner2d

  Signature: (a(n,m); b(n,m); [o]c())

Inner product over 2 dimensions.

Equivalent to

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


inner2t

  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.


minimum

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = minimum($b);

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


minimum_ind

  Signature: (a(n); int[o]c())

Like minimum but returns the index rather than the value


minimum_n_ind

  Signature: (a(n); int[o]c(m))

Returns the index of m minimum elements


maximum

  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. (see the PDL/Slices manpage) it is possible to use any dimension.

    $a = maximum($b);

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


maximum_ind

  Signature: (a(n); int[o]c())

Like maximum but returns the index rather than the value


maximum_n_ind

  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.


minmaximum

  Signature: (a(n); [o]cmin(); [o] cmax(); int [o]cmin_ind(); int [o]cmax_ind())

info not available


hclip

  Signature: (a(); b(); [o] c())

clip $a by $b ($b is upper bound)


lclip

  Signature: (a(); b(); [o] c())

clip $a by $b ($b is lower bound)


clip

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

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


wtstat

  Signature: (a(n); wt(n); avg(); [o]b(); int deg)


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


assgn

  Signature: (a(); [o]b())

Plain numerical assignment. This is used to implement the ``.='' operator


vsearch

  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.


interpol

  Signature: (i(); x(n); y(n); [o] ip())

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]


which

  Signature: (mask(n); int [o] inds(m))

info not available


which_both

  Signature: (mask(n); int [o] inds(m); int [o]notinds(q))

info not available


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

  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.


histogram

  Signature: (in(n); int+[o] hist(m); double step; double min; int msize => m)

Calculates a histogram for given stepsize and minimum.

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.

XXX: needs some more explanation (relation to hist()) etc. and examples!!!


whistogram

  Signature: (in(n); float+ wt();float+[o] hist(m); double step; double min; int msize => m)

Calculates a histogram for given stepsize and minimum.

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.

XXX: needs some more explanation (relation to hist()) etc. and examples!!!


histogram2d

  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.

XXX: needs some more explanation (relation to hist()) etc. and examples!!!


whistogram2d

  Signature: (ina(n); inb(n); float+ wt();float+[o] hist(ma,mb); double stepa; double mina; int masize => ma;
                      double stepb; double minb; int mbsize => mb;)

Calculates a 2d histogram.

XXX: needs some more explanation (relation to hist()) etc. and examples!!!


crossp

  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


norm

  Signature: (vec(n); [o] norm(n))

Normalises a vector to unit Euclidean length


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.


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
=cut

*whichND = \&PDL::whichND; sub PDL::whichND { my $mask = shift; my $ind=($mask->clump(-1))->which;

  return $mask->one2nd($ind);
}


fibonacci

  Signature: ([o]x(n))

Constructor - a vector with Fibonacci's sequence


AUTHOR

Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu). Contributions by Christian Soeller (csoelle@sghms.ac.uk) 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.