NAME

PDL::Slices -- Stupid index tricks


SYNOPSIS

  use PDL;
  $a = ones(3,3);
  $b = $a->slice('-1:0,(1)');
  $c = $a->dummy(2);


DESCRIPTION

This package provides many of the powerful PerlDL core index manipulation routines. These routines are usually two-way so you can get a unit matrix by

        $a = zeroes(1000,1000);
        $a->diagonal(0,1) ++;

which is usually fairly efficient. See pdlindexing and pdltips for more examples.

These functions are usually two-way:

        $b = $a->slice("1:3");
        $b += 5;                # $a is changed!

If you want to force a copy and no ``flow'' backwards, you need

        $b = $a->slice("1:3")->copy;
        $b += 5;                # $a is not changed.

alternatively, you can use

        $b = $a->slice("1:3")->sever;

which doesn't copy the struct but beware that after

        $b = $a->slice("1:3");
        $c = $b->sever;

the variables $b and $c point to the same object but with ->copy they do not.

The fact that there is this kind of flow makes PDL a very powerful language in many ways: since you can alter the original data by altering some easier-to-use representation of it, many things are much easier to accomplish, just like making the above unit matrix.


FUNCTIONS


affineinternal

  Signature: (P(); C())

internal


identity

  Signature: (P(); C())

internal


index

  Signature: (a(n); int ind(); [oca] c())

These functions provide rudimentary index indirection.

        c = a(ind());
        c = a(ind1(),ind2());

It would be useful to have a more complete function for this at some point, or at least a perl wrapper, that allows

        $c = $a->islice("1:2",$ind1,"3:4",$ind2");

with many dimensions.

This function is two-way, i.e. after

        $c = $a->index(pdl[0,5,8]);
        $c .= pdl [0,2,4];

the changes in $c will flow back to $a.


index2d

  Signature: (a(na,nb); int inda(); int indb(); [oca] c())

These functions provide rudimentary index indirection.

        c = a(ind());
        c = a(ind1(),ind2());

It would be useful to have a more complete function for this at some point, or at least a perl wrapper, that allows

        $c = $a->islice("1:2",$ind1,"3:4",$ind2");

with many dimensions.

This function is two-way, i.e. after

        $c = $a->index(pdl[0,5,8]);
        $c .= pdl [0,2,4];

the changes in $c will flow back to $a.


flowconvert

  Signature: (PARENT(); [oca]CHILD(); int totype)

internal


converttypei

  Signature: (P(); C(); int totype)

internal


clump

  Signature: (P(); C(); int n)

``clumps'' the first n dimensions into one large dimension

If, for example, $a has dimensions (5,3,4) then after

        $b = $a->clump(2);   # Clump 2 first dimensions

the variable $b will have dimensions (15,4) and the element $b->at(7,3) refers to the element $a->at(1,2,3).


xchg

  Signature: (P(); C(); int n1; int n2)

exchange two dimensions

The command

        $b = $a->xchg(2,3);

creates $b to be like $a except that the dimensions 2 and 3 are exchanged with each other i.e.

        $b->at(5,3,2,8) == $a->at(5,3,8,2)


mv

  Signature: (P(); C(); int n1; int n2)

move a dimension to another position

The command

        $b = $a->mv(4,1);

creates $b to be like $a except that the dimension 4 is moved to the place 1:

        $b->at(1,2,3,4,5,6) == $a->at(1,5,2,3,4,6);

The other dimensions are moved accordingly.


oneslice

  Signature: (P(); C(); int nth; int from; int step; int nsteps)

experimental function - not for public use

  $a = oneslice();

This is not for public use currently. See the source if you have to. This function can be used to accomplish run-time changing of transformations i.e. changing the size of some piddle at run-time.

However, the mechanism is not yet finalized and this is just a demonstration.


slice

  Signature: (P(); C(); char* str)

Returns a rectangular slice of the original piddle

  $a->slice('1:3'); #  return the second to fourth elements of $a

The argument string is a comma-separated list of what to do for each dimension. The current formats include the following (a,b and c are integers):

":"
takes the whole dimension intact.

""
(nothing) is a synonym for ``:'' (This means that $a->slice(':,3') is equal to $a->slice(',3')).

"n"
slices only this value out of the corresponding dimension

"(n)"
means the same as ``n'' by itself except that the resulting dimension of length one is deleted (so if $a has dims (3,4,5) then $a->slice(':,(2),:') has dimensions (3,5) whereas $a->slice(':,2,:') has dimensions (3,1,5)).

"a:b"
slices the range a to b inclusive out of the dimension

"a:b:c"
slices the range a to b, with step c (i.e. 3:7:2 gives the indices (3,5,7)). This may be confusing to Matlab users but several other packages already use this syntax.

"*"
inserts an extra dimension of width 1 and

"*a"
inserts an extra (dummy) dimension of width a.

An extension is planned for a later stage allowing $a->slice('(=1),(=1|5:8),3:6(=1),4:6') to express a multidimensional diagonal of $a.


affine

  Signature: (P(); C(); int offspar; SV *dimlist; SV *inclist)

internal


diagonalI

  Signature: (P(); C(); SV *list)

Returns the multidimensional diagonal over the specified dimensions.

The diagonal is placed at the first (by number) dimension that is diagonalized. The other diagonalized dimensions are removed. So if $a has dimensions (5,3,5,4,6,5) then after

        $b = $a->diagonal(0,2,5);

the piddle $b has dimensions (5,3,4,6) and $b->at(2,1,0,1) refers to $a->at(2,1,2,0,1,2).

NOTE: diagonal doesn't handle threadids correctly. XXX FIX


lags

  Signature: (P(); C(); int nthdim; int step; int n)

Returns a piddle of lags to parent.

I.e. if $a contains

       [0,1,2,3,4,5,6,7]

then

        $b = $a->lags(0,2,2);

 is a (5,2) matrix

       [2,3,4,5,6,7]
       [0,1,2,3,4,5]

This order of returned indices is kept because the function is called ``lags'' i.e. the nth lag is n steps behind the original.


splitdim

  Signature: (P(); C(); int nthdim; int nsp)

Splits a dimension in the parent piddle (opposite of clump)

After

        $b = $a->splitdim(2,3);

the expression

        $b->at(6,4,x,y,3,6) == $a->at(6,4,x+3*y)

is always true (x has to be less than 3).


threadI

  Signature: (P(); C(); int id; SV *list)

internal

Put some dimensions to a threadid.

        $b = $a->threadI(0,1,5); # thread over dims 1,5 in id 1


identvaff

  Signature: (P(); C())

A vaffine identity transformation (includes thread_id copying).

Mainly for internal use.


unthread

  Signature: (P(); C(); int atind)

All threaded dimensions are made real again.

See XXX for details and examples.


AUTHOR

Copyright (C) 1997 Tuomas J. Lukka. 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.