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 manipula‐
16 tion routines. These routines mostly allow two-way data flow, so you
17 can modify your data in the most convenient representation. For exam‐
18 ple, 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 vari‐
34 ables.
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())
72 Internal vaffine identity function.
74 index
76 Signature: (a(n); int ind(); [oca] c())
78 "index" and "index2d" provide rudimentary index indirection.
80 $c = index($source,$ind);
82 $c = index2d($source2,$ind1,$ind2);
83 use the $ind variables as indices to look up values in $source.
85 "index2d" uses separate piddles for X and Y coordinates. For more gen‐
86 eral N-dimensional indexing, see PDL::Slices or the PDL::NiceSlice syn‐
87 tax.
88 These functions are two-way, i.e. after
90 $c = $a->index(pdl[0,5,8]);
92 $c .= pdl [0,2,4];
93 the changes in $c will flow back to $a.
95 "index" provids simple threading: multiple-dimensioned arrays are
97 treated as collections of 1-D arrays, so that
98 $a = xvals(10,10)+10*yvals(10,10);
100 $b = $a->index(3);
101 $c = $a->index(9-xvals(10));
102 puts a single column from $a into $b, and puts a single element from
104 each column of $a into $c. If you want to extract multiple columns
105 from an array in one operation, see dice or indexND.
106 index2d
108 Signature: (a(na,nb); int inda(); int indb(); [oca] c())
110 "index" and "index2d" provide rudimentary index indirection.
112 $c = index($source,$ind);
114 $c = index2d($source2,$ind1,$ind2);
115 use the $ind variables as indices to look up values in $source.
117 "index2d" uses separate piddles for X and Y coordinates. For more gen‐
118 eral N-dimensional indexing, see PDL::Slices or the PDL::NiceSlice syn‐
119 tax.
120 These functions are two-way, i.e. after
122 $c = $a->index(pdl[0,5,8]);
124 $c .= pdl [0,2,4];
125 the changes in $c will flow back to $a.
127 "index" provids simple threading: multiple-dimensioned arrays are
129 treated as collections of 1-D arrays, so that
130 $a = xvals(10,10)+10*yvals(10,10);
132 $b = $a->index(3);
133 $c = $a->index(9-xvals(10));
134 puts a single column from $a into $b, and puts a single element from
136 each column of $a into $c. If you want to extract multiple columns
137 from an array in one operation, see dice or indexND.
138 indexNDb
140 Backwards-compatibility alias for indexND
142 indexND
144 Find selected elements in an N-D piddle, with optional boundary handling
146 $out = $source->indexND( $index, [$method] )
148 $source = 10*xvals(10,10) + yvals(10,10);
150 $index = pdl([[2,3],[4,5]],[[6,7],[8,9]]);
151 print $source->indexND( $index );
152 [
154 [23 45]
155 [67 89]
156 ]
157 IndexND collapses $index by lookup into $source. The 0th dimension of
159 $index is treated as coordinates in $source, and the return value has
160 the same dimensions as the rest of $index. The returned elements are
161 looked up from $source. Dataflow works -- propagated assignment flows
162 back into $source.
163 IndexND and IndexNDb were originally separate routines but they are
165 both now implemented as a call to range, and have identical syntax to
166 one another.
167 rangeb
169 Signature: (P(); C(); SV *index; SV *size; SV *boundary)
171 Engine for range
173 Same calling convention as range, but you must supply all parameters.
175 "rangeb" is marginally faster as it makes a direct PP call, avoiding
176 the perl argument-parsing step.
177 range
179 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 order up to N. Each row of
187 $index is treated as coordinates of a single value or chunk from
188 $source, 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 order higher than
197 the number of dimensions in $source, then $source is treated as though
198 it had trivial dummy dimensions of order 1, up to the required size to
199 be 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 order 1
201 on 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 sub‐
221 sequent 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 evalua‐
227 tion 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 val‐
249 ued.
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 ordi‐
287 nary thread dims, because adding more dims to $source just tacks extra
288 dims on the end of the output. Each source thread dim ranges over the
289 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 extrac‐
295 tion and selection of individual chunks. The last example shows how to
296 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 partic‐
359 ular, 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 ver‐
367 sion...)
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 order 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 order 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 (usually of low order) with
379 another index dim (perhaps of order 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 argu‐
403 ments.
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 -- modify‐
413 ing the appropriate dimincs in RedoDims ought to take care of it.
414 rld
416 Signature: (int a(n); b(n); [o]c(m))
418 Run-length decode a vector
420 Given a vector $a of the numbers of instances of values $b, run-length
422 decode to $c.
423 rld($a,$b,$c=null);
425 rle
427 Signature: (c(n); int [o]a(n); [o]b(n))
429 Run-length encode a vector
431 Given vector $c, generate a vector $a with the number of each element,
433 and a vector $b of the unique values. Only the elements up to the
434 first instance of 0 in $a should be considered.
435 rle($c,$a=null,$b=null);
437 xchg
439 Signature: (P(); C(); int n1; int n2)
441 exchange two dimensions
443 Negative dimension indices count from the end.
445 The command
447 $b = $a->xchg(2,3);
449 creates $b to be like $a except that the dimensions 2 and 3 are
451 exchanged with each other i.e.
452 $b->at(5,3,2,8) == $a->at(5,3,8,2)
454 reorder
456 Re-orders the dimensions of a PDL based on the supplied list.
458 Similar to the xchg method, this method re-orders the dimensions of a
460 PDL. While the xchg method swaps the position of two dimensions, the
461 reorder method can change the positions of many dimensions at once.
462 # Completely reverse the dimension order of a 6-Dim array.
464 $reOrderedPDL = $pdl->reorder(5,4,3,2,1,0);
465 The argument to reorder is an array representing where the current
467 dimensions should go in the new array. In the above usage, the argument
468 to reorder "(5,4,3,2,1,0)" indicates that the old dimensions ($pdl's
469 dims) should be re-arranged to make the new pdl ($reOrderPDL) according
470 to the following:
471 Old Position New Position
473 ------------ ------------
474 5 0
475 4 1
476 3 2
477 2 3
478 1 4
479 0 5
480 Example:
482 perldl> $a = sequence(5,3,2); # Create a 3-d Array
484 perldl> p $a
485 [
486 [
487 [ 0 1 2 3 4]
488 [ 5 6 7 8 9]
489 [10 11 12 13 14]
490 ]
491 [
492 [15 16 17 18 19]
493 [20 21 22 23 24]
494 [25 26 27 28 29]
495 ]
496 ]
497 perldl> p $a->reorder(2,1,0); # Reverse the order of the 3-D PDL
498 [
499 [
500 [ 0 15]
501 [ 5 20]
502 [10 25]
503 ]
504 [
505 [ 1 16]
506 [ 6 21]
507 [11 26]
508 ]
509 [
510 [ 2 17]
511 [ 7 22]
512 [12 27]
513 ]
514 [
515 [ 3 18]
516 [ 8 23]
517 [13 28]
518 ]
519 [
520 [ 4 19]
521 [ 9 24]
522 [14 29]
523 ]
524 ]
525 The above is a simple example that could be duplicated by calling
527 "$a->xchg(0,2)", but it demonstrates the basic functionality of
528 reorder.
529 As this is an index function, any modifications to the result PDL will
531 change the parent.
532 mv
534 Signature: (P(); C(); int n1; int n2)
536 move a dimension to another position
538 The command
540 $b = $a->mv(4,1);
542 creates $b to be like $a except that the dimension 4 is moved to the
544 place 1, so:
545 $b->at(1,2,3,4,5,6) == $a->at(1,5,2,3,4,6);
547 The other dimensions are moved accordingly. Negative dimension indices
549 count from the end.
550 oneslice
552 Signature: (P(); C(); int nth; int from; int step; int nsteps)
554 experimental function - not for public use
556 $a = oneslice();
558 This is not for public use currently. See the source if you have to.
560 This function can be used to accomplish run-time changing of transfor‐
561 mations i.e. changing the size of some piddle at run-time.
562 However, the mechanism is not yet finalized and this is just a demon‐
564 stration.
565 slice
567 Signature: (P(); C(); char* str)
569 Extract a rectangular slice of a piddle, from a string specifier.
571 "slice" was the original Swiss-army-knife PDL indexing routine, but is
573 largely superseded by the NiceSlice source prefilter and its associated
574 nslice method. It is still used as the basic underlying slicing engine
575 for nslice, and is especially useful in particular niche applications.
576 $a->slice('1:3'); # return the second to fourth elements of $a
578 $a->slice('3:1'); # reverse the above
579 $a->slice('-2:1'); # return last-but-one to second elements of $a
580 The argument string is a comma-separated list of what to do for each
582 dimension. The current formats include the following, where a, b and c
583 are integers and can take legal array index values (including -1 etc):
584 : takes the whole dimension intact.
586 '' (nothing) is a synonym for ":" (This means that
588 "$a->slice(':,3')" is equal to "$a->slice(',3')").
589 a slices only this value out of the corresponding dimension.
591 (a) means the same as "a" by itself except that the resulting
593 dimension of length one is deleted (so if $a has dims "(3,4,5)"
594 then "$a->slice(':,(2),:')" has dimensions "(3,5)" whereas
595 "$a->slice(':,2,:')" has dimensions "(3,1,5))".
596 a:b slices the range a to b inclusive out of the dimension.
598 a:b:c slices the range a to b, with step c (i.e. "3:7:2" gives the
600 indices "(3,5,7)"). This may be confusing to Matlab users but
601 several other packages already use this syntax.
602 '*' inserts an extra dimension of width 1 and
604 '*a' inserts an extra (dummy) dimension of width a.
606 An extension is planned for a later stage allowing
608 "$a->slice('(=1),(=1⎪5:8),3:6(=1),4:6')" to express a multidimensional
609 diagonal of $a.
610 Trivial out-of-bounds slicing is allowed: if you slice a source dimen‐
612 sion that doesn't exist, but only index the 0th element, then "slice"
613 treats the source as if there were a dummy dimension there. The fol‐
614 lowing are all equivalent:
615 xvals(5)->dummy(1,1)->slice('(2),0') # Add dummy dim, then slice
617 xvals(5)->slice('(2),0') # Out-of-bounds slice adds dim.
618 xvals(5)->slice((2),0) # NiceSlice syntax
619 xvals(5)->((2))->dummy(0,1) # NiceSlice syntax
620 This is an error:
622 xvals(5)->slice('(2),1') # nontrivial out-of-bounds slice dies
624 Because slicing doesn't directly manipulate the source and destination
626 pdl -- it just sets up a transformation between them -- indexing errors
627 often aren't reported until later. This is either a bug or a feature,
628 depending on whether you prefer error-reporting clarity or speed of
629 execution.
630 using
632 Returns array of column numbers requested
634 line $pdl->using(1,2);
636 Plot, as a line, column 1 of $pdl vs. column 2
638 perldl> $pdl = rcols("file");
640 perldl> line $pdl->using(1,2);
641 diagonalI
643 Signature: (P(); C(); SV *list)
645 Returns the multidimensional diagonal over the specified dimensions.
647 The diagonal is placed at the first (by number) dimension that is diag‐
649 onalized. The other diagonalized dimensions are removed. So if $a has
650 dimensions "(5,3,5,4,6,5)" then after
651 $b = $a->diagonal(0,2,5);
653 the piddle $b has dimensions "(5,3,4,6)" and "$b->at(2,1,0,1)" refers
655 to "$a->at(2,1,2,0,1,2)".
656 NOTE: diagonal doesn't handle threadids correctly. XXX FIX
658 lags
660 Signature: (P(); C(); int nthdim; int step; int n)
662 Returns a piddle of lags to parent.
664 Usage:
666 $lags = $a->lags($nthdim,$step,$nlags);
668 I.e. if $a contains
670 [0,1,2,3,4,5,6,7]
672 then
674 $b = $a->lags(0,2,2);
676 is a (5,2) matrix
678 [2,3,4,5,6,7]
680 [0,1,2,3,4,5]
681 This order of returned indices is kept because the function is called
683 "lags" i.e. the nth lag is n steps behind the original.
684 $step and $nlags must be positive. $nthdim can be negative and will
686 then be counted from the last dim backwards in the usual way (-1 = last
687 dim).
688 splitdim
690 Signature: (P(); C(); int nthdim; int nsp)
692 Splits a dimension in the parent piddle (opposite of clump)
694 After
696 $b = $a->splitdim(2,3);
698 the expression
700 $b->at(6,4,x,y,3,6) == $a->at(6,4,x+3*y)
702 is always true ("x" has to be less than 3).
704 rotate
706 Signature: (x(n); int shift(); [oca]y(n))
708 Shift vector elements along with wrap. Flows data back&forth.
710 threadI
712 Signature: (P(); C(); int id; SV *list)
714 internal
716 Put some dimensions to a threadid.
718 $b = $a->threadI(0,1,5); # thread over dims 1,5 in id 1
720 identvaff
722 Signature: (P(); C())
724 A vaffine identity transformation (includes thread_id copying).
726 Mainly for internal use.
728 unthread
730 Signature: (P(); C(); int atind)
732 All threaded dimensions are made real again.
734 See [TBD Doc] for details and examples.
736 dice
738 Dice rows/columns/planes out of a PDL using indexes for each dimension.
740 This function can be used to extract irregular subsets along many
742 dimension of a PDL, e.g. only certain rows in an image, or planes in a
743 cube. This can of course be done with the usual dimension tricks but
744 this saves having to figure it out each time!
745 This method is similar in functionality to the slice method, but slice
747 requires that contiguous ranges or ranges with constant offset be
748 extracted. ( i.e. slice requires ranges of the form "1,2,3,4,5" or
749 "2,4,6,8,10"). Because of this restriction, slice is more memory effi‐
750 cient and slightly faster than dice
751 $slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
753 The arguments to dice are arrays (or 1D PDLs) for each dimension in the
755 PDL. These arrays are used as indexes to which rows/columns/cubes,etc
756 to dice-out (or extract) from the $data PDL.
757 Use "X" to select all indices along a given dimension (compare also
759 mslice). As usual (in slicing methods) trailing dimensions can be omit‐
760 ted implying "X"'es for those.
761 perldl> $a = sequence(10,4)
763 perldl> p $a
764 [
765 [ 0 1 2 3 4 5 6 7 8 9]
766 [10 11 12 13 14 15 16 17 18 19]
767 [20 21 22 23 24 25 26 27 28 29]
768 [30 31 32 33 34 35 36 37 38 39]
769 ]
770 perldl> p $a->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3
771 [
772 [ 1 2]
773 [31 32]
774 ]
775 perldl> p $a->dice(X,[0,3])
776 [
777 [ 0 1 2 3 4 5 6 7 8 9]
778 [30 31 32 33 34 35 36 37 38 39]
779 ]
780 perldl> p $a->dice([0,2,5])
781 [
782 [ 0 2 5]
783 [10 12 15]
784 [20 22 25]
785 [30 32 35]
786 ]
787 As this is an index function, any modifications to the slice change the
789 parent (use the ".=" operator).
790 dice_axis
792 Dice rows/columns/planes from a single PDL axis (dimension) using index
794 along a specified axis
795 This function can be used to extract irregular subsets along any dimen‐
797 sion, e.g. only certain rows in an image, or planes in a cube. This can
798 of course be done with the usual dimension tricks but this saves having
799 to figure it out each time!
800 $slice = $data->dice_axis($axis,$index);
802 perldl> $a = sequence(10,4)
804 perldl> $idx = pdl(1,2)
805 perldl> p $a->dice_axis(0,$idx) # Select columns
806 [
807 [ 1 2]
808 [11 12]
809 [21 22]
810 [31 32]
811 ]
812 perldl> $t = $a->dice_axis(1,$idx) # Select rows
813 perldl> $t.=0
814 perldl> p $a
815 [
816 [ 0 1 2 3 4 5 6 7 8 9]
817 [ 0 0 0 0 0 0 0 0 0 0]
818 [ 0 0 0 0 0 0 0 0 0 0]
819 [30 31 32 33 34 35 36 37 38 39]
820 ]
821 The trick to using this is that the index selects elements along the
823 dimensions specified, so if you have a 2D image "axis=0" will select
824 certain "X" values - i.e. extract columns
825 As this is an index function, any modifications to the slice change the
827 parent.
828
830 Copyright (C) 1997 Tuomas J. Lukka. Contributions by Craig DeForest,
831 deforest@boulder.swri.edu. All rights reserved. There is no warranty.
832 You are allowed to redistribute this software / documentation under
833 certain conditions. For details, see the file COPYING in the PDL dis‐
834 tribution. If this file is separated from the PDL distribution, the
835 copyright notice should be included in the file.
836perl v5.8.8 2006-12-02 Slices(3)