1Slices(3) User Contributed Perl Documentation Slices(3)
2
6 PDL::Slices -- Indexing, slicing, and dicing
7
9 use PDL;
10 $a = ones(3,3);
11 $b = $a->slice('-1:0,(1)');
12 $c = $a->dummy(2);
13
15 This package provides many of the powerful PerlDL core index
16 manipulation routines. These routines mostly allow two-way data flow,
17 so you can modify your data in the most convenient representation. For
18 example, you can make a 1000x1000 unit matrix with
19 $a = zeroes(1000,1000);
21 $a->diagonal(0,1) ++;
22 which is quite efficient. See PDL::Indexing and PDL::Tips for more
24 examples.
25 Slicing is so central to the PDL language that a special compile-time
27 syntax has been introduced to handle it compactly; see PDL::NiceSlice
28 for details.
29 PDL indexing and slicing functions usually include two-way data flow,
31 so that you can separate the actions of reshaping your data structures
32 and modifying the data themselves. Two special methods, copy and
33 sever, help you control the data flow connection between related
34 variables.
35 $b = $a->slice("1:3"); # Slice maintains a link between $a and $b.
37 $b += 5; # $a is changed!
38 If you want to force a physical copy and no data flow, you can copy or
40 sever the slice expression:
41 $b = $a->slice("1:3")->copy;
43 $b += 5; # $a is not changed.
44 $b = $a->slice("1:3")->sever;
46 $b += 5; # $a is not changed.
47 The difference between "sever" and "copy" is that sever acts on (and
49 returns) its argument, while copy produces a disconnected copy. If you
50 say
51 $b = $a->slice("1:3");
53 $c = $b->sever;
54 then the variables $b and $c point to the same object but with "->copy"
56 they would not.
57
59 For the moment, you can't slice the empty piddle. This should probably
60 change: slices of the empty piddle should probably return the empty
61 piddle.
62 Many types of index errors are reported far from the indexing operation
64 that caused them. This is caused by the underlying architecture:
65 slice() sets up a mapping between variables, but that mapping isn't
66 tested for correctness until it is used (potentially much later).
67
69 s_identity
70 Signature: (P(); C())
71 Internal vaffine identity function.
73 s_identity does handle bad values. It will set the bad-value flag of
75 all output piddles if the flag is set for any of the input piddles.
76 index
78 Signature: (a(n); int ind(); [oca] c())
79 "index" and "index2d" provide rudimentary index indirection.
81 $c = index($source,$ind);
83 $c = index2d($source2,$ind1,$ind2);
84 use the $ind variables as indices to look up values in $source.
86 "index2d" uses separate piddles for X and Y coordinates. For more
87 general N-dimensional indexing, see PDL::Slices or the PDL::NiceSlice
88 syntax.
89 These functions are two-way, i.e. after
91 $c = $a->index(pdl[0,5,8]);
93 $c .= pdl [0,2,4];
94 the changes in $c will flow back to $a.
96 "index" provids simple threading: multiple-dimensioned arrays are
98 treated as collections of 1-D arrays, so that
99 $a = xvals(10,10)+10*yvals(10,10);
101 $b = $a->index(3);
102 $c = $a->index(9-xvals(10));
103 puts a single column from $a into $b, and puts a single element from
105 each column of $a into $c. If you want to extract multiple columns
106 from an array in one operation, see dice or indexND.
107 index barfs if any of the index values are bad.
109 index2d
111 Signature: (a(na,nb); int inda(); int indb(); [oca] c())
112 "index" and "index2d" provide rudimentary index indirection.
114 $c = index($source,$ind);
116 $c = index2d($source2,$ind1,$ind2);
117 use the $ind variables as indices to look up values in $source.
119 "index2d" uses separate piddles for X and Y coordinates. For more
120 general N-dimensional indexing, see PDL::Slices or the PDL::NiceSlice
121 syntax.
122 These functions are two-way, i.e. after
124 $c = $a->index(pdl[0,5,8]);
126 $c .= pdl [0,2,4];
127 the changes in $c will flow back to $a.
129 "index" provids simple threading: multiple-dimensioned arrays are
131 treated as collections of 1-D arrays, so that
132 $a = xvals(10,10)+10*yvals(10,10);
134 $b = $a->index(3);
135 $c = $a->index(9-xvals(10));
136 puts a single column from $a into $b, and puts a single element from
138 each column of $a into $c. If you want to extract multiple columns
139 from an array in one operation, see dice or indexND.
140 index2d barfs if either of the index values are bad.
142 indexNDb
144 Backwards-compatibility alias for indexND
145 indexND
147 Find selected elements in an N-D piddle, with optional boundary handling
148 $out = $source->indexND( $index, [$method] )
150 $source = 10*xvals(10,10) + yvals(10,10);
152 $index = pdl([[2,3],[4,5]],[[6,7],[8,9]]);
153 print $source->indexND( $index );
154 [
156 [23 45]
157 [67 89]
158 ]
159 IndexND collapses $index by lookup into $source. The 0th dimension of
161 $index is treated as coordinates in $source, and the return value has
162 the same dimensions as the rest of $index. The returned elements are
163 looked up from $source. Dataflow works -- propagated assignment flows
164 back into $source.
165 IndexND and IndexNDb were originally separate routines but they are
167 both now implemented as a call to range, and have identical syntax to
168 one another.
169 rangeb
171 Signature: (P(); C(); SV *index; SV *size; SV *boundary)
172 Engine for range
174 Same calling convention as range, but you must supply all parameters.
176 "rangeb" is marginally faster as it makes a direct PP call, avoiding
177 the perl argument-parsing step.
178 range
180 Extract selected chunks from a source piddle, with boundary conditions
181 $out = $source->range($index,[$size,[$boundary]])
183 Returns elements or rectangular slices of the original piddle, indexed
185 by the $index piddle. $source is an N-dimensional piddle, and $index
186 is a piddle whose first dimension has size up to N. Each row of $index
187 is treated as coordinates of a single value or chunk from $source,
188 specifying the location(s) to extract.
189 If you specify a single index location, then range is essentially an
191 expensive slice, with controllable boundary conditions.
192 INPUTS
194 $index and $size can be piddles or array refs such as you would feed to
196 zeroes and its ilk. If $index's 0th dimension has size higher than the
197 number of dimensions in $source, then $source is treated as though it
198 had trivial dummy dimensions of size 1, up to the required size to be
199 indexed by $index -- so if your source array is 1-D and your index
200 array is a list of 3-vectors, you get two dummy dimensions of size 1 on
201 the end of your source array.
202 You can extract single elements or N-D rectangular ranges from $source,
204 by setting $size. If $size is undef or zero, then you get a single
205 sample for each row of $index. This behavior is similar to indexNDb,
206 which is in fact implemented as a call to range.
207 If $size is positive then you get a range of values from $source at
209 each location, and the output has extra dimensions allocated for them.
210 $size can be a scalar, in which case it applies to all dimensions, or
211 an N-vector, in which case each element is applied independently to the
212 corresponding dimension in $source. See below for details.
213 $boundary is a number, string, or list ref indicating the type of
215 boundary conditions to use when ranges reach the edge of $source. If
216 you specify no boundary conditions the default is to forbid boundary
217 violations on all axes. If you specify exactly one boundary condition,
218 it applies to all axes. If you specify more (as elements of a list
219 ref, or as a packed string, see below), then they apply to dimensions
220 in the order in which they appear, and the last one applies to all
221 subsequent dimensions. (This is less difficult than it sounds; see the
222 examples below).
223 0 (synonyms: 'f','forbid') (default)
225 Ranges are not allowed to cross the boundary of the original PDL.
226 Disallowed ranges throw an error. The errors are thrown at
227 evaluation time, not at the time of the range call (this is the same
228 behavior as slice).
229 1 (synonyms: 't','truncate')
231 Values outside the original piddle get BAD if you've got bad value
232 support compiled into your PDL and set the badflag for the source
233 PDL; or 0 if you haven't (you must set the badflag if you want BADs
234 for out of bound values, otherwise you get 0). Reverse dataflow
235 works OK for the portion of the child that is in-bounds. The out-
236 of-bounds part of the child is reset to (BAD|0) during each dataflow
237 operation, but execution continues.
238 2 (synonyms: 'e','x','extend')
240 Values that would be outside the original piddle point instead to
241 the nearest allowed value within the piddle. See the CAVEAT below
242 on mappings that are not single valued.
243 3 (synonyms: 'p','periodic')
245 Periodic boundary conditions apply: the numbers in $index are
246 applied, strict-modulo the corresponding dimensions of $source.
247 This is equivalent to duplicating the $source piddle throughout N-D
248 space. See the CAVEAT below about mappings that are not single
249 valued.
250 4 (synonyms: 'm','mirror')
252 Mirror-reflection periodic boundary conditions apply. See the
253 CAVEAT below about mappings that are not single valued.
254 The boundary condition identifiers all begin with unique characters, so
256 you can feed in multiple boundary conditions as either a list ref or a
257 packed string. (The packed string is marginally faster to run). For
258 example, the four expressions [0,1], ['forbid','truncate'], ['f','t'],
259 and 'ft' all specify that violating the boundary in the 0th dimension
260 throws an error, and all other dimensions get truncated.
261 If you feed in a single string, it is interpreted as a packed boundary
263 array if all of its characters are valid boundary specifiers (e.g.
264 'pet'), but as a single word-style specifier if they are not (e.g.
265 'forbid').
266 OUTPUT
268 The output threads over both $index and $source. Because implicit
270 threading can happen in a couple of ways, a little thought is needed.
271 The returned dimension list is stacked up like this:
272 (index thread dims), (index dims (size)), (source thread dims)
274 The first few dims of the output correspond to the extra dims of $index
276 (beyond the 0 dim). They allow you to pick out individual ranges from a
277 large, threaded collection.
278 The middle few dims of the output correspond to the size dims specified
280 in $size, and contain the range of values that is extracted at each
281 location in $source. Every nonzero element of $size is copied to the
282 dimension list here, so that if you feed in (for example) "$size =
283 [2,0,1]" you get an index dim list of "(2,1)".
284 The last few dims of the output correspond to extra dims of $source
286 beyond the number of dims indexed by $index. These dims act like
287 ordinary thread dims, because adding more dims to $source just tacks
288 extra dims on the end of the output. Each source thread dim ranges
289 over the entire corresponding dim of $source.
290 Dataflow: Dataflow is bidirectional.
292 Examples: Here are basic examples of "range" operation, showing how to
294 get ranges out of a small matrix. The first few examples show
295 extraction and selection of individual chunks. The last example shows
296 how to mark loci in the original matrix (using dataflow).
297 perldl> $src = 10*xvals(10,5)+yvals(10,5)
299 perldl> print $src->range([2,3]) # Cut out a single element
300 23
301 perldl> print $src->range([2,3],1) # Cut out a single 1x1 block
302 [
303 [23]
304 ]
305 perldl> print $src->range([2,3], [2,1]) # Cut a 2x1 chunk
306 [
307 [23 33]
308 ]
309 perldl> print $src->range([[2,3]],[2,1]) # Trivial list of 1 chunk
310 [
311 [
312 [23]
313 [33]
314 ]
315 ]
316 perldl> print $src->range([[2,3],[0,1]], [2,1]) # two 2x1 chunks
317 [
318 [
319 [23 1]
320 [33 11]
321 ]
322 ]
323 perldl> # A 2x2 collection of 2x1 chunks
324 perldl> print $src->range([[[1,1],[2,2]],[[2,3],[0,1]]],[2,1])
325 [
326 [
327 [
328 [11 22]
329 [23 1]
330 ]
331 [
332 [21 32]
333 [33 11]
334 ]
335 ]
336 ]
337 perldl> $src = xvals(5,3)*10+yvals(5,3)
338 perldl> print $src->range(3,1) # Thread over y dimension in $src
339 [
340 [30]
341 [31]
342 [32]
343 ]
344 perldl> $src = zeroes(5,4);
346 perldl> $src->range(pdl([2,3],[0,1]),pdl(2,1)) .= xvals(2,2,1) + 1
347 perldl> print $src
348 [
349 [0 0 0 0 0]
350 [2 2 0 0 0]
351 [0 0 0 0 0]
352 [0 0 1 1 0]
353 ]
354 CAVEAT: It's quite possible to select multiple ranges that intersect.
356 In that case, modifying the ranges doesn't have a guaranteed result in
357 the original PDL -- the result is an arbitrary choice among the valid
358 values. For some things that's OK; but for others it's not. In
359 particular, this doesn't work:
360 perldl> $photon_list = new PDL::RandVar->sample(500)->reshape(2,250)*10
362 perldl> histogram = zeroes(10,10)
363 perldl> histogram->range($photon_list,1)++; #not what you wanted
364 The reason is that if two photons land in the same bin, then that bin
366 doesn't get incremented twice. (That may get fixed in a later
367 version...)
368 PERMISSIVE RANGING: If $index has too many dimensions compared to
370 $source, then $source is treated as though it had dummy dimensions of
371 size 1, up to the required number of dimensions. These virtual dummy
372 dimensions have the usual boundary conditions applied to them.
373 If the 0 dimension of $index is ludicrously large (if its size is more
375 than 5 greater than the number of dims in the source PDL) then range
376 will insist that you specify a size in every dimension, to make sure
377 that you know what you're doing. That catches a common error with
378 range usage: confusing the initial dim (which is usually small) with
379 another index dim (perhaps of size 1000).
380 EFFICIENCY: Because "range" isn't an affine transformation (it involves
382 lookup into a list of N-D indices), it is somewhat memory-inefficient
383 for long lists of ranges, and keeping dataflow open is much slower than
384 for affine transformations (which don't have to copy data around).
385 Doing operations on small subfields of a large range is inefficient
387 because the engine must flow the entire range back into the original
388 PDL with every atomic perl operation, even if you only touch a single
389 element. One way to speed up such code is to sever your range, so that
390 PDL doesn't have to copy the data with each operation, then copy the
391 elements explicitly at the end of your loop. Here's an example that
392 labels each region in a range sequentially, using many small operations
393 rather than a single xvals assignment:
394 ### How to make a collection of small ops run fast with range...
396 $a = $data->range($index, $sizes, $bound)->sever;
397 $aa = $data->range($index, $sizes, $bound);
398 map { $a($_ - 1) .= $_; } (1..$a->nelem); # Lots of little ops
399 $aa .= $a;
400 "range" is a perl front-end to a PP function, "rangeb". Calling
402 "rangeb" is marginally faster but requires that you include all
403 arguments.
404 DEVEL NOTES
406 * index thread dimensions are effectively clumped internally. This
408 makes it easier to loop over the index array but a little more brain-
409 bending to tease out the algorithm.
410 * Currently the index threads really do run fastest in memory; this is
412 probably the wrong direction to thread, for fastest behavior --
413 modifying the appropriate dimincs in RedoDims ought to take care of it.
414 rangeb does handle bad values. It will set the bad-value flag of all
416 output piddles if the flag is set for any of the input piddles.
417 rld
419 Signature: (int a(n); b(n); [o]c(m))
420 Run-length decode a vector
422 Given a vector $a of the numbers of instances of values $b, run-length
424 decode to $c.
425 rld($a,$b,$c=null);
427 rld does not process bad values. It will set the bad-value flag of all
429 output piddles if the flag is set for any of the input piddles.
430 rle
432 Signature: (c(n); int [o]a(n); [o]b(n))
433 Run-length encode a vector
435 Given vector $c, generate a vector $a with the number of each element,
437 and a vector $b of the unique values. Only the elements up to the
438 first instance of 0 in $a should be considered.
439 rle($c,$a=null,$b=null);
441 rle does not process bad values. It will set the bad-value flag of all
443 output piddles if the flag is set for any of the input piddles.
444 xchg
446 Signature: (P(); C(); int n1; int n2)
447 exchange two dimensions
449 Negative dimension indices count from the end.
451 The command
453 $b = $a->xchg(2,3);
455 creates $b to be like $a except that the dimensions 2 and 3 are
457 exchanged with each other i.e.
458 $b->at(5,3,2,8) == $a->at(5,3,8,2)
460 xchg does not process bad values. It will set the bad-value flag of
462 all output piddles if the flag is set for any of the input piddles.
463 reorder
465 Re-orders the dimensions of a PDL based on the supplied list.
466 Similar to the xchg method, this method re-orders the dimensions of a
468 PDL. While the xchg method swaps the position of two dimensions, the
469 reorder method can change the positions of many dimensions at once.
470 # Completely reverse the dimension order of a 6-Dim array.
472 $reOrderedPDL = $pdl->reorder(5,4,3,2,1,0);
473 The argument to reorder is an array representing where the current
475 dimensions should go in the new array. In the above usage, the argument
476 to reorder "(5,4,3,2,1,0)" indicates that the old dimensions ($pdl's
477 dims) should be re-arranged to make the new pdl ($reOrderPDL) according
478 to the following:
479 Old Position New Position
481 ------------ ------------
482 5 0
483 4 1
484 3 2
485 2 3
486 1 4
487 0 5
488 You do not need to specify all dimensions, only a complete set starting
490 at position 0. (Extra dimensions are left where they are). This
491 means, for example, that you can reorder() the X and Y dimensions of an
492 image, and not care whether it is an RGB image with a third dimension
493 running across color plane.
494 Example:
496 perldl> $a = sequence(5,3,2); # Create a 3-d Array
498 perldl> p $a
499 [
500 [
501 [ 0 1 2 3 4]
502 [ 5 6 7 8 9]
503 [10 11 12 13 14]
504 ]
505 [
506 [15 16 17 18 19]
507 [20 21 22 23 24]
508 [25 26 27 28 29]
509 ]
510 ]
511 perldl> p $a->reorder(2,1,0); # Reverse the order of the 3-D PDL
512 [
513 [
514 [ 0 15]
515 [ 5 20]
516 [10 25]
517 ]
518 [
519 [ 1 16]
520 [ 6 21]
521 [11 26]
522 ]
523 [
524 [ 2 17]
525 [ 7 22]
526 [12 27]
527 ]
528 [
529 [ 3 18]
530 [ 8 23]
531 [13 28]
532 ]
533 [
534 [ 4 19]
535 [ 9 24]
536 [14 29]
537 ]
538 ]
539 The above is a simple example that could be duplicated by calling
541 "$a->xchg(0,2)", but it demonstrates the basic functionality of
542 reorder.
543 As this is an index function, any modifications to the result PDL will
545 change the parent.
546 mv
548 Signature: (P(); C(); int n1; int n2)
549 move a dimension to another position
551 The command
553 $b = $a->mv(4,1);
555 creates $b to be like $a except that the dimension 4 is moved to the
557 place 1, so:
558 $b->at(1,2,3,4,5,6) == $a->at(1,5,2,3,4,6);
560 The other dimensions are moved accordingly. Negative dimension indices
562 count from the end.
563 mv does not process bad values. It will set the bad-value flag of all
565 output piddles if the flag is set for any of the input piddles.
566 oneslice
568 Signature: (P(); C(); int nth; int from; int step; int nsteps)
569 experimental function - not for public use
571 $a = oneslice();
573 This is not for public use currently. See the source if you have to.
575 This function can be used to accomplish run-time changing of
576 transformations i.e. changing the size of some piddle at run-time.
577 However, the mechanism is not yet finalized and this is just a
579 demonstration.
580 oneslice does not process bad values. It will set the bad-value flag
582 of all output piddles if the flag is set for any of the input piddles.
583 slice
585 Signature: (P(); C(); char* str)
586 Extract a rectangular slice of a piddle, from a string specifier.
588 "slice" was the original Swiss-army-knife PDL indexing routine, but is
590 largely superseded by the NiceSlice source prefilter and its associated
591 nslice method. It is still used as the basic underlying slicing engine
592 for nslice, and is especially useful in particular niche applications.
593 $a->slice('1:3'); # return the second to fourth elements of $a
595 $a->slice('3:1'); # reverse the above
596 $a->slice('-2:1'); # return last-but-one to second elements of $a
597 The argument string is a comma-separated list of what to do for each
599 dimension. The current formats include the following, where a, b and c
600 are integers and can take legal array index values (including -1 etc):
601 : takes the whole dimension intact.
603 '' (nothing) is a synonym for ":" (This means that
605 "$a->slice(':,3')" is equal to "$a->slice(',3')").
606 a slices only this value out of the corresponding dimension.
608 (a) means the same as "a" by itself except that the resulting
610 dimension of length one is deleted (so if $a has dims "(3,4,5)"
611 then "$a->slice(':,(2),:')" has dimensions "(3,5)" whereas
612 "$a->slice(':,2,:')" has dimensions "(3,1,5))".
613 a:b slices the range a to b inclusive out of the dimension.
615 a:b:c slices the range a to b, with step c (i.e. "3:7:2" gives the
617 indices "(3,5,7)"). This may be confusing to Matlab users but
618 several other packages already use this syntax.
619 '*' inserts an extra dimension of width 1 and
621 '*a' inserts an extra (dummy) dimension of width a.
623 An extension is planned for a later stage allowing
625 "$a->slice('(=1),(=1|5:8),3:6(=1),4:6')" to express a multidimensional
626 diagonal of $a.
627 Trivial out-of-bounds slicing is allowed: if you slice a source
629 dimension that doesn't exist, but only index the 0th element, then
630 "slice" treats the source as if there were a dummy dimension there.
631 The following are all equivalent:
632 xvals(5)->dummy(1,1)->slice('(2),0') # Add dummy dim, then slice
634 xvals(5)->slice('(2),0') # Out-of-bounds slice adds dim.
635 xvals(5)->slice((2),0) # NiceSlice syntax
636 xvals(5)->((2))->dummy(0,1) # NiceSlice syntax
637 This is an error:
639 xvals(5)->slice('(2),1') # nontrivial out-of-bounds slice dies
641 Because slicing doesn't directly manipulate the source and destination
643 pdl -- it just sets up a transformation between them -- indexing errors
644 often aren't reported until later. This is either a bug or a feature,
645 depending on whether you prefer error-reporting clarity or speed of
646 execution.
647 slice does not process bad values. It will set the bad-value flag of
649 all output piddles if the flag is set for any of the input piddles.
650 using
652 Returns array of column numbers requested
653 line $pdl->using(1,2);
655 Plot, as a line, column 1 of $pdl vs. column 2
657 perldl> $pdl = rcols("file");
659 perldl> line $pdl->using(1,2);
660 diagonalI
662 Signature: (P(); C(); SV *list)
663 Returns the multidimensional diagonal over the specified dimensions.
665 The diagonal is placed at the first (by number) dimension that is
667 diagonalized. The other diagonalized dimensions are removed. So if $a
668 has dimensions "(5,3,5,4,6,5)" then after
669 $b = $a->diagonal(0,2,5);
671 the piddle $b has dimensions "(5,3,4,6)" and "$b->at(2,1,0,1)" refers
673 to "$a->at(2,1,2,0,1,2)".
674 NOTE: diagonal doesn't handle threadids correctly. XXX FIX
676 diagonalI does not process bad values. It will set the bad-value flag
678 of all output piddles if the flag is set for any of the input piddles.
679 lags
681 Signature: (P(); C(); int nthdim; int step; int n)
682 Returns a piddle of lags to parent.
684 Usage:
686 $lags = $a->lags($nthdim,$step,$nlags);
688 I.e. if $a contains
690 [0,1,2,3,4,5,6,7]
692 then
694 $b = $a->lags(0,2,2);
696 is a (5,2) matrix
698 [2,3,4,5,6,7]
700 [0,1,2,3,4,5]
701 This order of returned indices is kept because the function is called
703 "lags" i.e. the nth lag is n steps behind the original.
704 $step and $nlags must be positive. $nthdim can be negative and will
706 then be counted from the last dim backwards in the usual way (-1 = last
707 dim).
708 lags does not process bad values. It will set the bad-value flag of
710 all output piddles if the flag is set for any of the input piddles.
711 splitdim
713 Signature: (P(); C(); int nthdim; int nsp)
714 Splits a dimension in the parent piddle (opposite of clump)
716 After
718 $b = $a->splitdim(2,3);
720 the expression
722 $b->at(6,4,x,y,3,6) == $a->at(6,4,x+3*y)
724 is always true ("x" has to be less than 3).
726 splitdim does not process bad values. It will set the bad-value flag
728 of all output piddles if the flag is set for any of the input piddles.
729 rotate
731 Signature: (x(n); int shift(); [oca]y(n))
732 Shift vector elements along with wrap. Flows data back&forth.
734 rotate does not process bad values. It will set the bad-value flag of
736 all output piddles if the flag is set for any of the input piddles.
737 threadI
739 Signature: (P(); C(); int id; SV *list)
740 internal
742 Put some dimensions to a threadid.
744 $b = $a->threadI(0,1,5); # thread over dims 1,5 in id 1
746 threadI does not process bad values. It will set the bad-value flag of
748 all output piddles if the flag is set for any of the input piddles.
749 identvaff
751 Signature: (P(); C())
752 A vaffine identity transformation (includes thread_id copying).
754 Mainly for internal use.
756 identvaff does not process bad values. It will set the bad-value flag
758 of all output piddles if the flag is set for any of the input piddles.
759 unthread
761 Signature: (P(); C(); int atind)
762 All threaded dimensions are made real again.
764 See [TBD Doc] for details and examples.
766 unthread does not process bad values. It will set the bad-value flag
768 of all output piddles if the flag is set for any of the input piddles.
769 dice
771 Dice rows/columns/planes out of a PDL using indexes for each dimension.
772 This function can be used to extract irregular subsets along many
774 dimension of a PDL, e.g. only certain rows in an image, or planes in a
775 cube. This can of course be done with the usual dimension tricks but
776 this saves having to figure it out each time!
777 This method is similar in functionality to the slice method, but slice
779 requires that contiguous ranges or ranges with constant offset be
780 extracted. ( i.e. slice requires ranges of the form "1,2,3,4,5" or
781 "2,4,6,8,10"). Because of this restriction, slice is more memory
782 efficient and slightly faster than dice
783 $slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
785 The arguments to dice are arrays (or 1D PDLs) for each dimension in the
787 PDL. These arrays are used as indexes to which rows/columns/cubes,etc
788 to dice-out (or extract) from the $data PDL.
789 Use "X" to select all indices along a given dimension (compare also
791 mslice). As usual (in slicing methods) trailing dimensions can be
792 omitted implying "X"'es for those.
793 perldl> $a = sequence(10,4)
795 perldl> p $a
796 [
797 [ 0 1 2 3 4 5 6 7 8 9]
798 [10 11 12 13 14 15 16 17 18 19]
799 [20 21 22 23 24 25 26 27 28 29]
800 [30 31 32 33 34 35 36 37 38 39]
801 ]
802 perldl> p $a->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3
803 [
804 [ 1 2]
805 [31 32]
806 ]
807 perldl> p $a->dice(X,[0,3])
808 [
809 [ 0 1 2 3 4 5 6 7 8 9]
810 [30 31 32 33 34 35 36 37 38 39]
811 ]
812 perldl> p $a->dice([0,2,5])
813 [
814 [ 0 2 5]
815 [10 12 15]
816 [20 22 25]
817 [30 32 35]
818 ]
819 As this is an index function, any modifications to the slice change the
821 parent (use the ".=" operator).
822 dice_axis
824 Dice rows/columns/planes from a single PDL axis (dimension) using index
825 along a specified axis
826 This function can be used to extract irregular subsets along any
828 dimension, e.g. only certain rows in an image, or planes in a cube.
829 This can of course be done with the usual dimension tricks but this
830 saves having to figure it out each time!
831 $slice = $data->dice_axis($axis,$index);
833 perldl> $a = sequence(10,4)
835 perldl> $idx = pdl(1,2)
836 perldl> p $a->dice_axis(0,$idx) # Select columns
837 [
838 [ 1 2]
839 [11 12]
840 [21 22]
841 [31 32]
842 ]
843 perldl> $t = $a->dice_axis(1,$idx) # Select rows
844 perldl> $t.=0
845 perldl> p $a
846 [
847 [ 0 1 2 3 4 5 6 7 8 9]
848 [ 0 0 0 0 0 0 0 0 0 0]
849 [ 0 0 0 0 0 0 0 0 0 0]
850 [30 31 32 33 34 35 36 37 38 39]
851 ]
852 The trick to using this is that the index selects elements along the
854 dimensions specified, so if you have a 2D image "axis=0" will select
855 certain "X" values - i.e. extract columns
856 As this is an index function, any modifications to the slice change the
858 parent.
859
861 Copyright (C) 1997 Tuomas J. Lukka. Contributions by Craig DeForest,
862 deforest@boulder.swri.edu. All rights reserved. There is no warranty.
863 You are allowed to redistribute this software / documentation under
864 certain conditions. For details, see the file COPYING in the PDL
865 distribution. If this file is separated from the PDL distribution, the
866 copyright notice should be included in the file.
867perl v5.12.3 2011-03-31 Slices(3)