1Core(3) User Contributed Perl Documentation Core(3)
2
6 PDL::Core - fundamental PDL functionality
7
9 Methods and functions for type conversions, PDL creation, type
10 conversion, threading etc.
11
13 use PDL::Core; # Normal routines
14 use PDL::Core ':Internal'; # Hairy routines
15
17 pdl
18 piddle constructor - creates new piddle from perl scalars/arrays and
19 piddles
20 $a = pdl(SCALAR|ARRAY REFERENCE|ARRAY);
22 $a = pdl [1..10]; # 1D array
24 $a = pdl ([1..10]); # 1D array
25 $a = pdl (1,2,3,4); # Ditto
26 $b = pdl [[1,2,3],[4,5,6]]; # 2D 3x2 array
27 $b = pdl 42 # 0-dimensional scalar
28 $c = pdl $a; # Make a new copy
29 $a = pdl([1,2,3],[4,5,6]); # 2D
30 $a = pdl([[1,2,3],[4,5,6]]); # 2D
31 Note the last two are equivalent - a list is automatically converted to
33 a list reference for syntactic convenience. i.e. you can omit the outer
34 "[]"
35 You can mix and match arrays, array refs, and PDLs in your argument
37 list, and "pdl" will sort them out. You get back a PDL whose last
38 (slowest running) dim runs across the top level of the list you hand
39 in, and whose first (fastest running) dim runs across the deepest level
40 that you supply.
41 Throwing a PDL into the mix has the same effect as throwing in a list
43 ref:
44 pdl(pdl(1,2),[3,4])
46 is the same as
48 pdl([1,2],[3,4]).
50 All of the dimensions in the list are "padded-out" with undefval to
52 meet the widest dim in the list, so (e.g.)
53 $a = pdl([[1,2,3],[2]])
55 gives you the same answer as
57 $a = pdl([[1,2,3],[2,undef,undef]]);
59 "pdl()" is a functional synonym for the 'new' constructor, e.g.:
61 $x = new PDL [1..10];
63 In order to control how undefs are handled in converting from perl
65 lists to PDLs, one can set the variable $PDL::undefval. For example:
66 $foo = [[1,2,undef],[undef,3,4]];
68 $PDL::undefval = -999;
69 $f = pdl $foo;
70 print $f
71 [
72 [ 1 2 -999]
73 [-999 3 4]
74 ]
75 $PDL::undefval defaults to zero.
77 null
79 Returns a 'null' piddle.
80 $x = null;
82 "null()" has a special meaning to PDL::PP. It is used to flag a special
84 kind of empty piddle, which can grow to appropriate dimensions to store
85 a result (as opposed to storing a result in an existing piddle).
86 perldl> sumover sequence(10,10), $ans=null;p $ans
88 [45 145 245 345 445 545 645 745 845 945]
89 nullcreate
91 Returns a 'null' piddle.
92 $x = PDL->nullcreate($arg)
94 This is an routine used by many of the threading primitives (i.e.
96 sumover, minimum, etc.) to generate a null piddle for the function's
97 output that will behave properly for derived (or subclassed) PDL
98 objects.
99 For the above usage: If $arg is a PDL, or a derived PDL, then
101 "$arg->null" is returned. If $arg is a scalar (i.e. a zero-dimensional
102 PDL) then "$PDL->null" is returned.
103 PDL::Derived->nullcreate(10)
105 returns PDL::Derived->null.
106 PDL->nullcreate($pdlderived)
107 returns $pdlderived->null.
108 nelem
110 Return the number of elements in a piddle
111 $n = nelem($piddle); $n = $piddle->nelem;
113 $mean = sum($data)/nelem($data);
115 dims
117 Return piddle dimensions as a perl list
118 @dims = $piddle->dims; @dims = dims($piddle);
120 perldl> p @tmp = dims zeroes 10,3,22
122 10 3 22
123 ndims
125 Returns the number of dimensions in a piddle. Alias for getndims.
126 getndims
128 Returns the number of dimensions in a piddle
129 $ndims = $piddle->getndims;
131 perldl> p zeroes(10,3,22)->getndims
133 3
134 dim
136 Returns the size of the given dimension of a piddle. Alias for getdim.
137 getdim
139 Returns the size of the given dimension.
140 $dim0 = $piddle->getdim(0);
142 perldl> p zeroes(10,3,22)->getdim(1)
144 3
145 Negative indices count from the end of the dims array. Indices beyond
147 the end will return a size of 1. This reflects the idea that any pdl is
148 equivalent to an infinitely dimensional array in which only a finite
149 number of dimensions have a size different from one. For example, in
150 that sense a 3D piddle of shape [3,5,2] is equivalent to a
151 [3,5,2,1,1,1,1,1,....] piddle. Accordingly,
152 print $a->getdim(10000);
154 will print 1 for most practically encountered piddles.
156 topdl
158 alternate piddle constructor - ensures arg is a piddle
159 $a = topdl(SCALAR|ARRAY REFERENCE|ARRAY);
161 The difference between pdl() and "topdl()" is that the latter will just
163 'fall through' if the argument is already a piddle. It will return a
164 reference and NOT a new copy.
165 This is particulary useful if you are writing a function which is doing
167 some fiddling with internals and assumes a piddle argument (e.g. for
168 method calls). Using "topdl()" will ensure nothing breaks if passed
169 with '2'.
170 Note that "topdl()" is not exported by default (see example below for
172 usage).
173 use PDL::Core ':Internal'; # use the internal routines of
175 # the Core module
176 $a = topdl 43; # $a is piddle with value '43'
178 $b = topdl $piddle; # fall through
179 $a = topdl (1,2,3,4); # Convert 1D array
180 PDL::get_datatype
182 Internal: Return the numeric value identifying the piddle datatype
183 $x = $piddle->get_datatype;
185 Mainly used for internal routines.
187 NOTE: get_datatype returns 'just a number' not any special type object,
189 unlike type.
190 howbig
192 Returns the size of a piddle datatype in bytes.
193 Note that "howbig()" is not exported by default (see example below for
195 usage).
196 use PDL::Core ':Internal'; # use the internal routines of
198 # the Core module
199 $size = howbig($piddle->get_datatype);
201 Mainly used for internal routines.
203 NOTE: NOT a method! This is because get_datatype returns 'just a
205 number' not any special object.
206 perldl> p howbig(ushort([1..10])->get_datatype)
208 2
209 get_dataref
211 Return the internal data for a piddle, as a perl SCALAR ref.
212 Most piddles hold their internal data in a packed perl string, to take
214 advantage of perl's memory management. This gives you direct access to
215 the string, which is handy when you need to manipulate the binary data
216 directly (e.g. for file I/O). If you modify the string, you'll need to
217 call upd_data afterward, to make sure that the piddle points to the new
218 location of the underlying perl variable.
219 You shouldn't mess with the SV unless you've called make_physical or
221 something similar. You definitely don't want to do anything to the SV
222 to truncate or deallocate the string, unless you correspondingly call
223 reshape to make the PDL match its new data dimension.
224 You definitely don't want to use get_dataref unless you know what you
226 are doing (or are trying to find out): you can end up scrozzling memory
227 if you shrink or eliminate the string representation of the variable.
228 Here be dragons.
229 upd_data
231 Update the data pointer in a piddle to match its perl SV.
232 This is useful if you've been monkeying with the packed string
234 representation of the PDL, which you probably shouldn't be doing
235 anyway. (see get_dataref.)
236 PDL::threadids
238 Returns the piddle thread IDs as a perl list
239 Note that "threadids()" is not exported by default (see example below
241 for usage).
242 use PDL::Core ':Internal'; # use the internal routines of
244 # the Core module
245 @ids = threadids $piddle;
247 doflow
249 Turn on/off dataflow
250 $x->doflow; doflow($x);
252 flows
254 Whether or not a piddle is indulging in dataflow
255 something if $x->flows; $hmm = flows($x);
257 PDL::new
259 new piddle constructor method
260 $x = PDL->new(SCALAR|ARRAY|ARRAY REF);
262 $x = PDL->new(42);
264 $y = new PDL [1..10];
265 Constructs piddle from perl numbers and lists.
267 copy
269 Make a physical copy of a piddle
270 $new = $old->copy;
272 Since "$new = $old" just makes a new reference, the "copy" method is
274 provided to allow real independent copies to be made.
275 PDL::hdr_copy
277 Return an explicit copy of the header of a PDL.
278 hdr_copy is just a wrapper for the internal routine _hdr_copy, which
280 takes the hash ref itself. That is the routine which is used to make
281 copies of the header during normal operations if the hdrcpy() flag of a
282 PDL is set.
283 General-purpose deep copies are expensive in perl, so some simple
285 optimization happens:
286 If the header is a tied array or a blessed hash ref with an associated
288 method called "copy", then that ->copy method is called. Otherwise,
289 all elements of the hash are explicitly copied. References are
290 recursively deep copied.
291 This routine seems to leak memory.
293 PDL::unwind
295 Return a piddle which is the same as the argument except that all
296 threadids have been removed.
297 $y = $x->unwind;
299 PDL::make_physical
301 Make sure the data portion of a piddle can be accessed from XS code.
302 $a->make_physical;
304 $a->call_my_xs_method;
305 Ensures that a piddle gets its own allocated copy of data. This
307 obviously implies that there are certain piddles which do not have
308 their own data. These are so called virtual piddles that make use of
309 the vaffine optimisation (see PDL::Indexing). They do not have their
310 own copy of data but instead store only access information to some (or
311 all) of another piddle's data.
312 Note: this function should not be used unless absolutely neccessary
314 since otherwise memory requirements might be severly increased. Instead
315 of writing your own XS code with the need to call "make_physical" you
316 might want to consider using the PDL preprocessor (see PDL::PP) which
317 can be used to transparently access virtual piddles without the need to
318 physicalise them (though there are exceptions).
319 dummy
321 Insert a 'dummy dimension' of given length (defaults to 1)
322 No relation to the 'Dungeon Dimensions' in Discworld!
324 Negative positions specify relative to last dimension, i.e. "dummy(-1)"
326 appends one dimension at end, "dummy(-2)" inserts a dummy dimension in
327 front of the last dim, etc.
328 If you specify a dimension position larger than the existing dimension
330 list of your PDL, the PDL gets automagically padded with extra dummy
331 dimensions so that you get the dim you asked for, in the slot you asked
332 for. This could cause you trouble if, for example, you ask for
333 $a->dummy(5000,1) because $a will get 5,000 dimensions, each of rank 1.
334 Because padding at the beginning of the dimension list moves existing
336 dimensions from slot to slot, it's considered unsafe, so automagic
337 padding doesn't work for large negative indices -- only for large
338 positive indices.
339 $y = $x->dummy($position[,$dimsize]);
341 perldl> p sequence(3)->dummy(0,3)
343 [
344 [0 0 0]
345 [1 1 1]
346 [2 2 2]
347 ]
348 perldl> p sequence(3)->dummy(3,2)
350 [
351 [
352 [0 1 2]
353 ]
354 [
355 [0 1 2]
356 ]
357 ]
358 perldl> p sequence(3)->dummy(-3,2)
360 For safety, <pos> < -(dims+1) is not allowed in dummy, allowed min=-2.
361 clump
363 "clumps" several dimensions into one large dimension
364 If called with one argument $n clumps the first $n dimensions into one.
366 For example, if $a has dimensions "(5,3,4)" then after
367 $b = $a->clump(2); # Clump 2 first dimensions
369 the variable $b will have dimensions "(15,4)" and the element
371 "$b->at(7,3)" refers to the element "$a->at(1,2,3)".
372 Use "clump(-1)" to flatten a piddle. The method flat is provided as a
374 convenient alias.
375 Clumping with a negative dimension in general leaves that many
377 dimensions behind -- e.g. clump(-2) clumps all of the first few
378 dimensions into a single one, leaving a 2-D piddle.
379 If "clump" is called with an index list with more than one element it
381 is treated as a list of dimensions that should be clumped together into
382 one. The resulting clumped dim is placed at the position of the lowest
383 index in the list. This convention ensures that "clump" does the
384 expected thing in the usual cases. The following example demonstrates
385 typical usage:
386 $a = sequence 2,3,3,3,5; # 5D piddle
388 $c = $a->clump(1..3); # clump all the dims 1 to 3 into one
389 print $c->info; # resulting 3D piddle has clumped dim at pos 1
390 PDL: Double D [2,27,5]
391 thread_define
393 define functions that support threading at the perl level
394 thread_define 'tline(a(n);b(n))', over {
396 line $_[0], $_[1]; # make line compliant with threading
397 };
398 "thread_define" provides some support for threading (see PDL::Indexing)
400 at the perl level. It allows you to do things for which you normally
401 would have resorted to PDL::PP (see PDL::PP); however, it is most
402 useful to wrap existing perl functions so that the new routine supports
403 PDL threading.
404 "thread_define" is used to define new threading aware functions. Its
406 first argument is a symbolic repesentation of the new function to be
407 defined. The string is composed of the name of the new function
408 followed by its signature (see PDL::Indexing and PDL::PP) in
409 parentheses. The second argument is a subroutine that will be called
410 with the slices of the actual runtime arguments as specified by its
411 signature. Correct dimension sizes and minimal number of dimensions for
412 all arguments will be checked (assuming the rules of PDL threading, see
413 PDL::Indexing).
414 The actual work is done by the "signature" class which parses the
416 signature string, does runtime dimension checks and the routine
417 "threadover" that generates the loop over all appropriate slices of pdl
418 arguments and creates pdls as needed.
419 Similar to "pp_def" and its "OtherPars" option it is possible to define
421 the new function so that it accepts normal perl args as well as
422 piddles. You do this by using the "NOtherPars" parameter in the
423 signature. The number of "NOtherPars" specified will be passed
424 unaltered into the subroutine given as the second argument of
425 "thread_define". Let's illustrate this with an example:
426 PDL::thread_define 'triangles(inda();indb();indc()), NOtherPars => 2',
428 PDL::over {
429 ${$_[3]} .= $_[4].join(',',map {$_->at} @_[0..2]).",-1,\n";
430 };
431 This defines a function "triangles" that takes 3 piddles as input plus
433 2 arguments which are passed into the routine unaltered. This routine
434 is used to collect lists of indices into a perl scalar that is passed
435 by reference. Each line is preceded by a prefix passed as $_[4]. Here
436 is typical usage:
437 $txt = '';
439 triangles(pdl(1,2,3),pdl(1),pdl(0),\$txt," "x10);
440 print $txt;
441 resulting in the following output
443 1,1,0,-1,
445 2,1,0,-1,
446 3,1,0,-1,
447 which is used in PDL::Graphics::TriD::VRML to generate VRML output.
449 Currently, this is probably not much more than a POP (proof of
451 principle) but is hoped to be useful enough for some real life work.
452 Check PDL::PP for the format of the signature. Currently, the "[t]"
454 qualifier and all type qualifiers are ignored.
455 PDL::thread
457 Use explicit threading over specified dimensions (see also
458 PDL::Indexing)
459 $b = $a->thread($dim,[$dim1,...])
461 $a = zeroes 3,4,5;
463 $b = $a->thread(2,0);
464 Same as PDL::thread1, i.e. uses thread id 1.
466 diagonal
468 Returns the multidimensional diagonal over the specified dimensions.
469 $d = $x->diagonal(dim1, dim2,...)
471 perldl> $a = zeroes(3,3,3);
473 perldl> ($b = $a->diagonal(0,1))++;
474 perldl> p $a
475 [
476 [
477 [1 0 0]
478 [0 1 0]
479 [0 0 1]
480 ]
481 [
482 [1 0 0]
483 [0 1 0]
484 [0 0 1]
485 ]
486 [
487 [1 0 0]
488 [0 1 0]
489 [0 0 1]
490 ]
491 ]
492 PDL::thread1
494 Explicit threading over specified dims using thread id 1.
495 $xx = $x->thread1(3,1)
497 Wibble
499 Convenience function interfacing to PDL::Slices::threadI.
501 PDL::thread2
503 Explicit threading over specified dims using thread id 2.
504 $xx = $x->thread2(3,1)
506 Wibble
508 Convenience function interfacing to PDL::Slices::threadI.
510 PDL::thread3
512 Explicit threading over specified dims using thread id 3.
513 $xx = $x->thread3(3,1)
515 Wibble
517 Convenience function interfacing to PDL::Slices::threadI.
519 sever
521 sever any links of this piddle to parent piddles
522 In PDL it is possible for a piddle to be just another view into another
524 piddle's data. In that case we call this piddle a virtual piddle and
525 the original piddle owning the data its parent. In other languages
526 these alternate views sometimes run by names such as alias or smart
527 reference.
528 Typical functions that return such piddles are "slice", "xchg",
530 "index", etc. Sometimes, however, you would like to separate the
531 virtual piddle from its parent's data and just give it a life of its
532 own (so that manipulation of its data doesn't change the parent). This
533 is simply achieved by using "sever". For example,
534 $a = $pdl->index(pdl(0,3,7))->sever;
536 $a++; # important: $pdl is not modified!
537 In many (but not all) circumstances it acts therefore similar to copy.
539 However, in general performance is better with "sever" and secondly,
540 "sever" doesn't lead to futile copying when used on piddles that
541 already have their own data. On the other hand, if you really want to
542 make sure to work on a copy of a piddle use copy.
543 $a = zeroes(20);
545 $a->sever; # NOOP since $a is already its own boss!
546 Again note: "sever" is not the same as copy! For example,
548 $a = zeroes(1); # $a does not have a parent, i.e. it is not a slice etc
550 $b = $a->sever; # $b is now pointing to the same piddle as $a
551 $b++;
552 print $a;
553 [1]
554 but
556 $a = zeroes(1);
558 $b = $a->copy; # $b is now pointing to a new piddle
559 $b++;
560 print $a;
561 [0]
562 PDL::info
564 Return formatted information about a piddle.
565 $x->info($format_string);
567 print $x->info("Type: %T Dim: %-15D State: %S");
569 Returns a string with info about a piddle. Takes an optional argument
571 to specify the format of information a la sprintf. Format specifiers
572 are in the form "%<width><letter>" where the width is optional and the
573 letter is one of
574 T Type
576 D Formatted Dimensions
578 F Dataflow status
580 S Some internal flags (P=physical,V=Vaffine,C=changed,B=may
582 contain bad data)
583 C Class of this piddle, i.e. "ref $pdl"
585 A Address of the piddle struct as a unique identifier
587 M Calculated memory consumption of this piddle's data area
589 approx
591 test for approximately equal values (relaxed "==")
592 # ok if all corresponding values in
594 # piddles are within 1e-8 of each other
595 print "ok\n" if all approx $a, $b, 1e-8;
596 "approx" is a relaxed form of the "==" operator and often more
598 appropriate for floating point types ("float" and "double").
599 Usage:
601 $res = approx $a, $b [, $eps]
603 The optional parameter $eps is remembered across invocations and
605 initially set to 1e-6, e.g.
606 approx $a, $b; # last $eps used (1e-6 initially)
608 approx $a, $b, 1e-10; # 1e-10
609 approx $a, $b; # also 1e-10
610 mslice
612 Convenience interface to slice, allowing easier inclusion of dimensions
613 in perl code.
614 $a = $x->mslice(...);
616 # below is the same as $x->slice("5:7,:,3:4:2")
618 $a = $x->mslice([5,7],X,[3,4,2]);
619 nslice
621 Internally used interface to slice and dice that is the runtime part of
622 the PDL::NiceSlice implementation.
623 $a = $x->nslice(...);
625 # below is the same as $x->slice("5:7,:,3:4:2")
627 $a = $x->nslice([5,7],X,[3,4,2]);
628 It implements a superset of mslice's features. Should probably not be
630 used in your scripts. Rather resort to the PDL::NiceSlice interface.
631 inplace
633 Flag a piddle so that the next operation is done 'in place'
634 somefunc($x->inplace); somefunc(inplace $x);
636 In most cases one likes to use the syntax "$y = f($x)", however in many
638 case the operation "f()" can be done correctly 'in place', i.e. without
639 making a new copy of the data for output. To make it easy to use this,
640 we write "f()" in such a way that it operates in-place, and use
641 "inplace" to hint that a new copy should be disabled. This also makes
642 for clear syntax.
643 Obviously this will not work for all functions, and if in doubt see the
645 function's documentation. However one can assume this is true for all
646 elemental functions (i.e. those which just operate array element by
647 array element like "log10").
648 perldl> $x = xvals zeroes 10;
650 perldl> log10(inplace $x)
651 perldl> p $x
652 [ -Inf 0 0.30103 0.47712125 0.60205999 0.69897
653 0.77815125 0.84509804 0.90308999 0.95424251]
654 is_inplace
656 Test the in-place flag on a piddle
657 $out = ($in->is_inplace) ? $in : zeroes($in);
659 $in->set_inplace(0)
660 Provides access to the inplace hint flag, within the perl millieu.
662 That way functions you write can be inplace aware... If given an
663 argument the inplace flag will be set or unset depending on the value
664 at the same time. Can be used for shortcut tests that delete the
665 inplace flag while testing:
666 $out = ($in->is_inplace(0)) ? $in : zeroes($in); # test & unset!
668 set_inplace
670 Set the in-place flag on a piddle
671 $out = ($in->is_inplace) ? $in : zeroes($in);
673 $in->set_inplace(0);
674 Provides access to the inplace hint flag, within the perl millieu.
676 Useful mainly for turning it OFF, as inplace turns it ON more
677 conveniently.
678 new_or_inplace
680 $a = new_or_inplace(shift());
681 $a = new_or_inplace(shift(),$preferred_type);
682 Return back either the argument pdl or a copy of it depending on
684 whether it be flagged in-place or no. Handy for building inplace-aware
685 functions.
686 PDL::new_from_specification
688 Internal method: create piddle by specification
689 This is the argument processing method called by zeroes and some other
691 functions which constructs piddles from argument lists of the form:
692 [type], $nx, $ny, $nz,...
694 For $nx, $ny, etc. 0 and 1D piddles are allowed. Giving those has the
696 same effect as if saying "$arg->list", e.g.
697 1, pdl(5,2), 4
699 is equivalent to
701 1, 5, 2, 4
703 Note, however, that in all functions using "new_from_specification"
705 calling "func $piddle" will probably not do what you want. So to play
706 safe use (e.g. with zeroes)
707 $pdl = zeroes $dimpdl->list;
709 Calling
711 $pdl = zeroes $dimpdl;
713 will rather be equivalent to
715 $pdl = zeroes $dimpdl->dims;
717 However,
719 $pdl = zeroes ushort, $dimpdl;
721 will again do what you intended since it is interpreted as if you had
723 said
724 $pdl = zeroes ushort, $dimpdl->list;
726 This is unfortunate and confusing but no good solution seems obvious
728 that would not break existing scripts.
729 isempty
731 Test whether a piddle is empty
732 print "The piddle has zero dimension\n" if $pdl->isempty;
734 This function returns 1 if the piddle has zero elements. This is useful
736 in particular when using the indexing function which. In the case of no
737 match to a specified criterion, the returned piddle has zero dimension.
738 perldl> $a=sequence(10)
740 perldl> $i=which($a < -1)
741 perldl> print "I found no matches!\n" if ($a->isempty);
742 Note that having zero elements is rather different from the concept of
744 being a null piddle, see the PDL::FAQ and PDL::Indexing manpages for
745 discussions of this.
746 zeroes
748 construct a zero filled piddle from dimension list or template piddle.
749 Various forms of usage,
751 (i) by specification or (ii) by template piddle:
753 # usage type (i):
755 $a = zeroes([type], $nx, $ny, $nz,...);
756 $a = PDL->zeroes([type], $nx, $ny, $nz,...);
757 $a = $pdl->zeroes([type], $nx, $ny, $nz,...);
758 # usage type (ii):
759 $a = zeroes $b;
760 $a = $b->zeroes
761 zeroes inplace $a; # Equivalent to $a .= 0;
762 $a->inplace->zeroes; # ""
763 perldl> $z = zeroes 4,3
765 perldl> p $z
766 [
767 [0 0 0 0]
768 [0 0 0 0]
769 [0 0 0 0]
770 ]
771 perldl> $z = zeroes ushort, 3,2 # Create ushort array
772 [ushort() etc. with no arg returns a PDL::Types token]
773 See also new_from_specification for details on using piddles in the
775 dimensions list.
776 zeros
778 construct a zero filled piddle (see zeroes for usage)
779 ones
781 construct a one filled piddle
782 $a = ones([type], $nx, $ny, $nz,...);
784 etc. (see 'zeroes')
785 see zeroes() and add one
787 See also new_from_specification for details on using piddles in the
789 dimensions list.
790 reshape
792 Change the shape (i.e. dimensions) of a piddle, preserving contents.
793 $x->reshape(NEWDIMS); reshape($x, NEWDIMS);
795 The data elements are preserved, obviously they will wrap differently
797 and get truncated if the new array is shorter. If the new array is
798 longer it will be zero-padded.
799 ***Potential incompatibility with earlier versions of PDL**** If the
801 list of "NEWDIMS" is empty "reshape" will just drop all dimensions of
802 size 1 (preserving the number of elements):
803 $a = sequence(3,4,5);
805 $b = $a(1,3);
806 $b->reshape();
807 print $b->info;
808 PDL: Double D [5]
809 Dimensions of size 1 will also be dropped if "reshape" is invoked with
811 the argument -1:
812 $b = $a->reshape(-1);
814 As opposed to "reshape" without arguments, "reshape(-1)" preserves
816 dataflow:
817 $a = ones(2,1,2);
819 $b = $a(0)->reshape(-1);
820 $b++;
821 print $a;
822 [
823 [
824 [2 1]
825 ]
826 [
827 [2 1]
828 ]
829 ]
830 Note: an explicit copy of slices is generally forced - this is the only
832 way (for now) of stopping a crash if $x is a slice. Important:
833 Physical piddles are changed inplace!
834 perldl> $x = sequence(10)
836 perldl> reshape $x,3,4; p $x
837 [
838 [0 1 2]
839 [3 4 5]
840 [6 7 8]
841 [9 0 0]
842 ]
843 perldl> reshape $x,5; p $x
844 [0 1 2 3 4]
845 squeeze
847 eliminate all singleton dimensions (dims of size 1)
848 $b = $a(0,0)->squeeze;
850 Alias for "reshape(-1)". Removes all singleton dimensions and preserves
852 dataflow. A more concise interface is provided by PDL::NiceSlice via
853 modifiers:
854 use PDL::NiceSlice;
856 $b = $a(0,0;-); # same as $a(0,0)->squeeze
857 flat
859 flatten a piddle (alias for "$pdl-"clump(-1)>)
860 $srt = $pdl->flat->qsort;
862 Useful method to make a 1D piddle from an arbitrarily sized input
864 piddle. Data flows back and forth as usual with slicing routines.
865 Falls through if argument already <= 1D.
866 convert
868 Generic datatype conversion function
869 $y = convert($x, $newtype);
871 $y = convert $x, long
873 $y = convert $x, ushort
874 $newtype is a type number, for convenience they are returned by
876 "long()" etc when called without arguments.
877 Datatype_conversions
879 byte|short|ushort|long|longlong|float|double convert shorthands
880 $y = double $x; $y = ushort [1..10];
882 # all of byte|short|ushort|long|float|double behave similarly
883 When called with a piddle argument, they convert to the specific
885 datatype.
886 When called with a numeric or list / listref argument they construct a
888 new piddle. This is a convenience to avoid having to be long-winded and
889 say "$x = long(pdl(42))"
890 Thus one can say:
892 $a = float(1,2,3,4); # 1D
894 $a = float([1,2,3],[4,5,6]); # 2D
895 $a = float([[1,2,3],[4,5,6]]); # 2D
896 Note the last two are equivalent - a list is automatically converted to
898 a list reference for syntactic convenience. i.e. you can omit the outer
899 "[]"
900 When called with no arguments return a special type token. This allows
902 syntactical sugar like:
903 $x = ones byte, 1000,1000;
905 This example creates a large piddle directly as byte datatype in order
907 to save memory.
908 In order to control how undefs are handled in converting from perl
910 lists to PDLs, one can set the variable $PDL::undefval; see the
911 function pdl() for more details.
912 perldl> p $x=sqrt float [1..10]
914 [1 1.41421 1.73205 2 2.23607 2.44949 2.64575 2.82843 3 3.16228]
915 perldl> p byte $x
916 [1 1 1 2 2 2 2 2 3 3]
917 byte
919 Convert to byte datatype - see 'Datatype_conversions'
920 short
922 Convert to short datatype - see 'Datatype_conversions'
923 ushort
925 Convert to ushort datatype - see 'Datatype_conversions'
926 long
928 Convert to long datatype - see 'Datatype_conversions'
929 longlong
931 Convert to longlong datatype - see 'Datatype_conversions'
932 float
934 Convert to float datatype - see 'Datatype_conversions'
935 double
937 Convert to double datatype - see 'Datatype_conversions'
938 type
940 return the type of a piddle as a blessed type object
941 A convenience function for use with the piddle constructors, e.g.
943 $b = PDL->zeroes($a->type,$a->dims,3);
945 die "must be float" unless $a->type == float;
946 See also the discussion of the "PDL::Type" class in PDL::Types. Note
948 that the "PDL::Type" objects have overloaded comparison and stringify
949 operators so that you can compare and print types:
950 $a = $a->float if $a->type < float;
952 $t = $a->type; print "Type is $t\";
953 list
955 Convert piddle to perl list
956 @tmp = list $x;
958 Obviously this is grossly inefficient for the large datasets PDL is
960 designed to handle. This was provided as a get out while PDL matured.
961 It should now be mostly superseded by superior constructs, such as
962 PP/threading. However it is still occasionally useful and is provied
963 for backwards compatibility.
964 for (list $x) {
966 # Do something on each value...
967 }
968 list converts any bad values into the string 'BAD'.
970 listindices
972 Convert piddle indices to perl list
973 @tmp = listindices $x;
975 @tmp now contains the values "0..nelem($x)".
977 Obviously this is grossly inefficient for the large datasets PDL is
979 designed to handle. This was provided as a get out while PDL matured.
980 It should now be mostly superseded by superior constructs, such as
981 PP/threading. However it is still occasionally useful and is provied
982 for backwards compatibility.
983 for $i (listindices $x) {
985 # Do something on each value...
986 }
987 set
989 Set a single value inside a piddle
990 set $piddle, @position, $value
992 @position is a coordinate list, of size equal to the number of
994 dimensions in the piddle. Occasionally useful, mainly provided for
995 backwards compatibility as superseded by use of slice and assigment
996 operator ".=".
997 perldl> $x = sequence 3,4
999 perldl> set $x, 2,1,99
1000 perldl> p $x
1001 [
1002 [ 0 1 2]
1003 [ 3 4 99]
1004 [ 6 7 8]
1005 [ 9 10 11]
1006 ]
1007 at
1009 Returns a single value inside a piddle as perl scalar.
1010 $z = at($piddle, @position); $z=$piddle->at(@position);
1012 @position is a coordinate list, of size equal to the number of
1014 dimensions in the piddle. Occasionally useful in a general context,
1015 quite useful too inside PDL internals.
1016 perldl> $x = sequence 3,4
1018 perldl> p $x->at(1,2)
1019 7
1020 at converts any bad values into the string 'BAD'.
1022 sclr
1024 return a single value from a piddle as a scalar
1025 $val = $a(10)->sclr;
1027 $val = sclr inner($a,$b);
1028 The "sclr" method is useful to turn a piddle into a normal Perl scalar.
1030 Its main advantage over using "at" for this purpose is the fact that
1031 you do not need to worry if the piddle is 0D, 1D or higher dimensional.
1032 Using "at" you have to supply the correct number of zeroes, e.g.
1033 $a = sequence(10);
1035 $b = $a->slice('4');
1036 print $b->sclr; # no problem
1037 print $b->at(); # error: needs at least one zero
1038 "sclr" is generally used when a Perl scalar is required instead of a
1040 one-element piddle. If the input is a multielement piddle the first
1041 value is returned as a Perl scalar. You can optionally switch on checks
1042 to ensure that the input piddle has only one element:
1043 PDL->sclr({Check => 'warn'}); # carp if called with multi-el pdls
1045 PDL->sclr({Check => 'barf'}); # croak if called with multi-el pdls
1046 are the commands to switch on warnings or raise an error if a
1048 multielement piddle is passed as input. Note that these options can
1049 only be set when "sclr" is called as a class method (see example
1050 above). Use
1051 PDL->sclr({Check=>0});
1053 to switch these checks off again (default setting); When called as a
1055 class method the resulting check mode is returned (0: no checking, 1:
1056 warn, 2: barf).
1057 cat
1059 concatenate piddles to N+1 dimensional piddle
1060 Takes a list of N piddles of same shape as argument, returns a single
1062 piddle of dimension N+1
1063 perldl> $x = cat ones(3,3),zeroes(3,3),rvals(3,3); p $x
1065 [
1066 [
1067 [1 1 1]
1068 [1 1 1]
1069 [1 1 1]
1070 ]
1071 [
1072 [0 0 0]
1073 [0 0 0]
1074 [0 0 0]
1075 ]
1076 [
1077 [1 1 1]
1078 [1 0 1]
1079 [1 1 1]
1080 ]
1081 ]
1082 The output piddle is set bad if any input piddles have their bad flag
1084 set.
1085 dog
1087 Opposite of 'cat' :). Split N dim piddle to list of N-1 dim piddles
1088 Takes a single N-dimensional piddle and splits it into a list of N-1
1090 dimensional piddles. The breakup is done along the last dimension.
1091 Note the dataflown connection is still preserved by default, e.g.:
1092 perldl> $p = ones 3,3,3
1094 perldl> ($a,$b,$c) = dog $p
1095 perldl> $b++; p $p
1096 [
1097 [
1098 [1 1 1]
1099 [1 1 1]
1100 [1 1 1]
1101 ]
1102 [
1103 [2 2 2]
1104 [2 2 2]
1105 [2 2 2]
1106 ]
1107 [
1108 [1 1 1]
1109 [1 1 1]
1110 [1 1 1]
1111 ]
1112 ]
1113 Break => 1 Break dataflow connection (new copy)
1115 The output piddles are set bad if the original piddle has its bad flag
1117 set.
1118 barf
1120 Standard error reporting routine for PDL.
1121 "barf()" is the routine PDL modules should call to report errors. This
1123 is because "barf()" will report the error as coming from the correct
1124 line in the module user's script rather than in the PDL module.
1125 It does this magic by unwinding the stack frames until it reaches a
1127 package NOT beginning with "PDL::". If you DO want it to report errors
1128 in some module PDL::Foo (e.g. when debugging PDL::Foo) then set the
1129 variable "$PDL::Foo::Debugging=1".
1130 Additionally if you set the variable "$PDL::Debugging=1" you will get a
1132 COMPLETE stack trace back up to the top level package.
1133 Finally "barf()" will try and report usage information from the PDL
1135 documentation database if the error message is of the form 'Usage:
1136 func'.
1137 Remember "barf()" is your friend. *Use* it!
1139 At the perl level:
1141 barf("User has too low an IQ!");
1143 In C or XS code:
1145 barf("You have made %d errors", count);
1147 Note: this is one of the few functions ALWAYS exported by PDL::Core
1149 gethdr
1151 Retrieve header information from a piddle
1152 $pdl=rfits('file.fits');
1154 $h=$pdl->gethdr;
1155 print "Number of pixels in the X-direction=$$h{NAXIS1}\n";
1156 The "gethdr" function retrieves whatever header information is
1158 contained within a piddle. The header can be set with sethdr and is
1159 always a hash reference or undef.
1160 "gethdr" returns undef if the piddle has not yet had a header defined;
1162 compare with "hdr" and "fhdr", which are guaranteed to return a defined
1163 value.
1164 Note that gethdr() works by reference: you can modify the header in-
1166 place once it has been retrieved:
1167 $a = rfits($filename);
1169 $ah = $a->gethdr();
1170 $ah->{FILENAME} = $filename;
1171 It is also important to realise that in most cases the header is not
1173 automatically copied when you copy the piddle. See hdrcpy to enable
1174 automatic header copying.
1175 Here's another example: a wrapper around rcols that allows your piddle
1177 to remember the file it was read from and the columns could be easily
1178 written (here assuming that no regexp is needed, extensions are left as
1179 an exercise for the reader)
1180 sub ext_rcols {
1182 my ($file, @columns)=@_;
1183 my $header={};
1184 $$header{File}=$file;
1185 $$header{Columns}=\@columns;
1186 @piddles=rcols $file, @columns;
1188 foreach (@piddles) { $_->sethdr($header); }
1189 return @piddles;
1190 }
1191 hdr
1193 Retrieve or set header information from a piddle
1194 $pdl->hdr->{CDELT1} = 1;
1196 The "hdr" function allows convenient access to the header of a piddle.
1198 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1199 use it in a hash dereference as in the example. If the header does not
1200 yet exist, it gets autogenerated as an empty hash.
1201 Note that this is usually -- but not always -- What You Want. If you
1203 want to use a tied Astro::FITS::Header hash, for example, you should
1204 either construct it yourself and use "sethdr" to put it into the
1205 piddle, or use fhdr instead. (Note that you should be able to write
1206 out the FITS file successfully regardless of whether your PDL has a
1207 tied FITS header object or a vanilla hash).
1208 fhdr
1210 Retrieve or set FITS header information from a piddle
1211 $pdl->fhdr->{CDELT1} = 1;
1213 The "fhdr" function allows convenient access to the header of a piddle.
1215 Unlike "gethdr" it is guaranteed to return a defined value, so you can
1216 use it in a hash dereference as in the example. If the header does not
1217 yet exist, it gets autogenerated as a tied Astro::FITS::Header hash.
1218 Astro::FITS::Header tied hashes are better at matching the behavior of
1220 FITS headers than are regular hashes. In particular, the hash keys are
1221 CAsE INsEnSItiVE, unlike normal hash keys. See Astro::FITS::Header for
1222 details.
1223 If you do not have Astro::FITS::Header installed, you get back a normal
1225 hash instead of a tied object.
1226 sethdr
1228 Set header information of a piddle
1229 $pdl = zeroes(100,100);
1231 $h = {NAXIS=>2, NAXIS1=>100, NAXIS=>100, COMMENT=>"Sample FITS-style header"};
1232 # add a FILENAME field to the header
1233 $$h{FILENAME} = 'file.fits';
1234 $pdl->sethdr( $h );
1235 The "sethdr" function sets the header information for a piddle. You
1237 must feed in a hash ref or undef, and the header field of the PDL is
1238 set to be a new ref to the same hash (or undefined).
1239 The hash ref requirement is a speed bump put in place since the normal
1241 use of headers is to store fits header information and the like. Of
1242 course, if you want you can hang whatever ugly old data structure you
1243 want off of the header, but that makes life more complex.
1244 Remember that the hash is not copied -- the header is made into a ref
1246 that points to the same underlying data. To get a real copy without
1247 making any assumptions about the underlying data structure, you can use
1248 one of the following:
1249 use PDL::IO::Dumper;
1251 $pdl->sethdr( deep_copy($h) );
1252 (which is slow but general), or
1254 $pdl->sethdr( PDL::_hdr_copy($h) )
1256 (which uses the built-in sleazy deep copier), or (if you know that all
1258 the elements happen to be scalars):
1259 { my %a = %$h;
1261 $pdl->sethdr(\%a);
1262 }
1263 which is considerably faster but just copies the top level.
1265 The "sethdr" function must be given a hash reference or undef. For
1267 further information on the header, see gethdr, hdr, fhdr and hdrcpy.
1268 hdrcpy
1270 switch on/off/examine automatic header copying
1271 print "hdrs will be copied" if $a->hdrcpy;
1273 $a->hdrcpy(1); # switch on automatic header copying
1274 $b = $a->sumover; # and $b will inherit $a's hdr
1275 $a->hdrcpy(0); # and now make $a non-infectious again
1276 "hdrcpy" without an argument just returns the current setting of the
1278 flag. See also "hcpy" which returns its PDL argument (and so is useful
1279 in method-call pipelines).
1280 Normally, the optional header of a piddle is not copied automatically
1282 in pdl operations. Switching on the hdrcpy flag using the "hdrcpy"
1283 method will enable automatic hdr copying. Note that an actual deep copy
1284 gets made, which is rather processor-inefficient -- so avoid using
1285 header copying in tight loops!
1286 Most PDLs have the "hdrcpy" flag cleared by default; however, some
1288 routines (notably rfits) set it by default where that makes more sense.
1289 The "hdrcpy" flag is viral: if you set it for a PDL, then derived PDLs
1291 will get copies of the header and will also have their "hdrcpy" flags
1292 set. For example:
1293 $a = xvals(50,50);
1295 $a->hdrcpy(1);
1296 $a->hdr->{FOO} = "bar";
1297 $b = $a++;
1298 $c = $b++;
1299 print $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1300 $b->hdr->{FOO} = "baz";
1301 print $a->hdr->{FOO}, " - ", $b->hdr->{FOO}, " - ", $c->hdr->{FOO}, "\n";
1302 will print:
1304 bar - bar
1306 bar - baz - bar
1307 hcpy
1309 Switch on/off automatic header copying, with PDL pass-through
1310 $a = rfits('foo.fits')->hcpy(0);
1312 $a = rfits('foo.fits')->hcpy(1);
1313 "hcpy" sets or clears the hdrcpy flag of a PDL, and returns the PDL
1315 itself. That makes it convenient for inline use in expressions.
1316
1318 Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka,
1319 (lukka@husc.harvard.edu) and Christian Soeller
1320 (c.soeller@auckland.ac.nz) 1997. Modified, Craig DeForest
1321 (deforest@boulder.swri.edu) 2002. All rights reserved. There is no
1322 warranty. You are allowed to redistribute this software / documentation
1323 under certain conditions. For details, see the file COPYING in the PDL
1324 distribution. If this file is separated from the PDL distribution, the
1325 copyright notice should be included in the file.
1326perl v5.12.3 2011-03-31 Core(3)