1Slices(3) User Contributed Perl Documentation Slices(3)
2
6 PDL::Slices -- Indexing, slicing, and dicing
7
9 use PDL;
10 $x = ones(3,3);
11 $y = $x->slice('-1:0,(1)');
12 $c = $x->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 $x = zeroes(1000,1000);
21 $x->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 $y = $x->slice("1:3"); # Slice maintains a link between $x and $y.
37 $y += 5; # $x 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 $y = $x->slice("1:3")->copy;
43 $y += 5; # $x is not changed.
44 $y = $x->slice("1:3")->sever;
46 $y += 5; # $x 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 $y = $x->slice("1:3");
53 $c = $y->sever;
54 then the variables $y and $c point to the same object but with "->copy"
56 they would not.
57
59 s_identity
60 Signature: (P(); C())
61 Internal vaffine identity function.
63 s_identity processes bad values. It will set the bad-value flag of all
65 output ndarrays if the flag is set for any of the input ndarrays.
66 index
68 Signature: (a(n); indx ind(); [oca] c())
69 "index", "index1d", and "index2d" provide rudimentary index
71 indirection.
72 $c = index($source,$ind);
74 $c = index1d($source,$ind);
75 $c = index2d($source2,$ind1,$ind2);
76 use the $ind variables as indices to look up values in $source. The
78 three routines thread slightly differently.
79 • "index" uses direct threading for 1-D indexing across the 0 dim of
81 $source. It can thread over source thread dims or index thread
82 dims, but not (easily) both: If $source has more than 1 dimension
83 and $ind has more than 0 dimensions, they must agree in a threading
84 sense.
85 • "index1d" uses a single active dim in $ind to produce a list of
87 indexed values in the 0 dim of the output - it is useful for
88 collapsing $source by indexing with a single row of values along
89 $source's 0 dimension. The output has the same number of dims as
90 $source. The 0 dim of the output has size 1 if $ind is a scalar,
91 and the same size as the 0 dim of $ind if it is not. If $ind and
92 $source both have more than 1 dim, then all dims higher than 0 must
93 agree in a threading sense.
94 • "index2d" works like "index" but uses separate ndarrays for X and Y
96 coordinates. For more general N-dimensional indexing, see the
97 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
98 "indexND", and "range").
99 These functions are two-way, i.e. after
101 $c = $x->index(pdl[0,5,8]);
103 $c .= pdl [0,2,4];
104 the changes in $c will flow back to $x.
106 "index" provids simple threading: multiple-dimensioned arrays are
108 treated as collections of 1-D arrays, so that
109 $x = xvals(10,10)+10*yvals(10,10);
111 $y = $x->index(3);
112 $c = $x->index(9-xvals(10));
113 puts a single column from $x into $y, and puts a single element from
115 each column of $x into $c. If you want to extract multiple columns
116 from an array in one operation, see "dice" or "indexND".
117 index barfs if any of the index values are bad.
119 index1d
121 Signature: (a(n); indx ind(m); [oca] c(m))
122 "index", "index1d", and "index2d" provide rudimentary index
124 indirection.
125 $c = index($source,$ind);
127 $c = index1d($source,$ind);
128 $c = index2d($source2,$ind1,$ind2);
129 use the $ind variables as indices to look up values in $source. The
131 three routines thread slightly differently.
132 • "index" uses direct threading for 1-D indexing across the 0 dim of
134 $source. It can thread over source thread dims or index thread
135 dims, but not (easily) both: If $source has more than 1 dimension
136 and $ind has more than 0 dimensions, they must agree in a threading
137 sense.
138 • "index1d" uses a single active dim in $ind to produce a list of
140 indexed values in the 0 dim of the output - it is useful for
141 collapsing $source by indexing with a single row of values along
142 $source's 0 dimension. The output has the same number of dims as
143 $source. The 0 dim of the output has size 1 if $ind is a scalar,
144 and the same size as the 0 dim of $ind if it is not. If $ind and
145 $source both have more than 1 dim, then all dims higher than 0 must
146 agree in a threading sense.
147 • "index2d" works like "index" but uses separate ndarrays for X and Y
149 coordinates. For more general N-dimensional indexing, see the
150 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
151 "indexND", and "range").
152 These functions are two-way, i.e. after
154 $c = $x->index(pdl[0,5,8]);
156 $c .= pdl [0,2,4];
157 the changes in $c will flow back to $x.
159 "index" provids simple threading: multiple-dimensioned arrays are
161 treated as collections of 1-D arrays, so that
162 $x = xvals(10,10)+10*yvals(10,10);
164 $y = $x->index(3);
165 $c = $x->index(9-xvals(10));
166 puts a single column from $x into $y, and puts a single element from
168 each column of $x into $c. If you want to extract multiple columns
169 from an array in one operation, see "dice" or "indexND".
170 index1d propagates BAD index elements to the output variable.
172 index2d
174 Signature: (a(na,nb); indx inda(); indx indb(); [oca] c())
175 "index", "index1d", and "index2d" provide rudimentary index
177 indirection.
178 $c = index($source,$ind);
180 $c = index1d($source,$ind);
181 $c = index2d($source2,$ind1,$ind2);
182 use the $ind variables as indices to look up values in $source. The
184 three routines thread slightly differently.
185 • "index" uses direct threading for 1-D indexing across the 0 dim of
187 $source. It can thread over source thread dims or index thread
188 dims, but not (easily) both: If $source has more than 1 dimension
189 and $ind has more than 0 dimensions, they must agree in a threading
190 sense.
191 • "index1d" uses a single active dim in $ind to produce a list of
193 indexed values in the 0 dim of the output - it is useful for
194 collapsing $source by indexing with a single row of values along
195 $source's 0 dimension. The output has the same number of dims as
196 $source. The 0 dim of the output has size 1 if $ind is a scalar,
197 and the same size as the 0 dim of $ind if it is not. If $ind and
198 $source both have more than 1 dim, then all dims higher than 0 must
199 agree in a threading sense.
200 • "index2d" works like "index" but uses separate ndarrays for X and Y
202 coordinates. For more general N-dimensional indexing, see the
203 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
204 "indexND", and "range").
205 These functions are two-way, i.e. after
207 $c = $x->index(pdl[0,5,8]);
209 $c .= pdl [0,2,4];
210 the changes in $c will flow back to $x.
212 "index" provids simple threading: multiple-dimensioned arrays are
214 treated as collections of 1-D arrays, so that
215 $x = xvals(10,10)+10*yvals(10,10);
217 $y = $x->index(3);
218 $c = $x->index(9-xvals(10));
219 puts a single column from $x into $y, and puts a single element from
221 each column of $x into $c. If you want to extract multiple columns
222 from an array in one operation, see "dice" or "indexND".
223 index2d barfs if either of the index values are bad.
225 indexNDb
227 Backwards-compatibility alias for indexND
228 indexND
230 Find selected elements in an N-D ndarray, with optional boundary handling
231 $out = $source->indexND( $index, [$method] )
233 $source = 10*xvals(10,10) + yvals(10,10);
235 $index = pdl([[2,3],[4,5]],[[6,7],[8,9]]);
236 print $source->indexND( $index );
237 [
239 [23 45]
240 [67 89]
241 ]
242 IndexND collapses $index by lookup into $source. The 0th dimension of
244 $index is treated as coordinates in $source, and the return value has
245 the same dimensions as the rest of $index. The returned elements are
246 looked up from $source. Dataflow works -- propagated assignment flows
247 back into $source.
248 IndexND and IndexNDb were originally separate routines but they are
250 both now implemented as a call to "range", and have identical syntax to
251 one another.
252 rangeb
254 Signature: (P(); C(); SV *index; SV *size; SV *boundary)
255 Engine for "range"
257 Same calling convention as "range", but you must supply all parameters.
259 "rangeb" is marginally faster as it makes a direct PP call, avoiding
260 the perl argument-parsing step.
261 range
263 Extract selected chunks from a source ndarray, with boundary conditions
264 $out = $source->range($index,[$size,[$boundary]])
266 Returns elements or rectangular slices of the original ndarray, indexed
268 by the $index ndarray. $source is an N-dimensional ndarray, and $index
269 is an ndarray whose first dimension has size up to N. Each row of
270 $index is treated as coordinates of a single value or chunk from
271 $source, specifying the location(s) to extract.
272 If you specify a single index location, then range is essentially an
274 expensive slice, with controllable boundary conditions.
275 INPUTS
277 $index and $size can be ndarrays or array refs such as you would feed
279 to zeroes and its ilk. If $index's 0th dimension has size higher than
280 the number of dimensions in $source, then $source is treated as though
281 it had trivial dummy dimensions of size 1, up to the required size to
282 be indexed by $index -- so if your source array is 1-D and your index
283 array is a list of 3-vectors, you get two dummy dimensions of size 1 on
284 the end of your source array.
285 You can extract single elements or N-D rectangular ranges from $source,
287 by setting $size. If $size is undef or zero, then you get a single
288 sample for each row of $index. This behavior is similar to "indexNDb",
289 which is in fact implemented as a call to "range".
290 If $size is positive then you get a range of values from $source at
292 each location, and the output has extra dimensions allocated for them.
293 $size can be a scalar, in which case it applies to all dimensions, or
294 an N-vector, in which case each element is applied independently to the
295 corresponding dimension in $source. See below for details.
296 $boundary is a number, string, or list ref indicating the type of
298 boundary conditions to use when ranges reach the edge of $source. If
299 you specify no boundary conditions the default is to forbid boundary
300 violations on all axes. If you specify exactly one boundary condition,
301 it applies to all axes. If you specify more (as elements of a list
302 ref, or as a packed string, see below), then they apply to dimensions
303 in the order in which they appear, and the last one applies to all
304 subsequent dimensions. (This is less difficult than it sounds; see the
305 examples below).
306 0 (synonyms: 'f','forbid') (default)
308 Ranges are not allowed to cross the boundary of the original PDL.
309 Disallowed ranges throw an error. The errors are thrown at
310 evaluation time, not at the time of the range call (this is the same
311 behavior as "slice").
312 1 (synonyms: 't','truncate')
314 Values outside the original ndarray get BAD if you've got bad value
315 support compiled into your PDL and set the badflag for the source
316 PDL; or 0 if you haven't (you must set the badflag if you want BADs
317 for out of bound values, otherwise you get 0). Reverse dataflow
318 works OK for the portion of the child that is in-bounds. The out-
319 of-bounds part of the child is reset to (BAD|0) during each dataflow
320 operation, but execution continues.
321 2 (synonyms: 'e','x','extend')
323 Values that would be outside the original ndarray point instead to
324 the nearest allowed value within the ndarray. See the CAVEAT below
325 on mappings that are not single valued.
326 3 (synonyms: 'p','periodic')
328 Periodic boundary conditions apply: the numbers in $index are
329 applied, strict-modulo the corresponding dimensions of $source.
330 This is equivalent to duplicating the $source ndarray throughout N-D
331 space. See the CAVEAT below about mappings that are not single
332 valued.
333 4 (synonyms: 'm','mirror')
335 Mirror-reflection periodic boundary conditions apply. See the
336 CAVEAT below about mappings that are not single valued.
337 The boundary condition identifiers all begin with unique characters, so
339 you can feed in multiple boundary conditions as either a list ref or a
340 packed string. (The packed string is marginally faster to run). For
341 example, the four expressions [0,1], ['forbid','truncate'], ['f','t'],
342 and 'ft' all specify that violating the boundary in the 0th dimension
343 throws an error, and all other dimensions get truncated.
344 If you feed in a single string, it is interpreted as a packed boundary
346 array if all of its characters are valid boundary specifiers (e.g.
347 'pet'), but as a single word-style specifier if they are not (e.g.
348 'forbid').
349 OUTPUT
351 The output threads over both $index and $source. Because implicit
353 threading can happen in a couple of ways, a little thought is needed.
354 The returned dimension list is stacked up like this:
355 (index thread dims), (index dims (size)), (source thread dims)
357 The first few dims of the output correspond to the extra dims of $index
359 (beyond the 0 dim). They allow you to pick out individual ranges from a
360 large, threaded collection.
361 The middle few dims of the output correspond to the size dims specified
363 in $size, and contain the range of values that is extracted at each
364 location in $source. Every nonzero element of $size is copied to the
365 dimension list here, so that if you feed in (for example) "$size =
366 [2,0,1]" you get an index dim list of "(2,1)".
367 The last few dims of the output correspond to extra dims of $source
369 beyond the number of dims indexed by $index. These dims act like
370 ordinary thread dims, because adding more dims to $source just tacks
371 extra dims on the end of the output. Each source thread dim ranges
372 over the entire corresponding dim of $source.
373 Dataflow: Dataflow is bidirectional.
375 Examples: Here are basic examples of "range" operation, showing how to
377 get ranges out of a small matrix. The first few examples show
378 extraction and selection of individual chunks. The last example shows
379 how to mark loci in the original matrix (using dataflow).
380 pdl> $src = 10*xvals(10,5)+yvals(10,5)
382 pdl> print $src->range([2,3]) # Cut out a single element
383 23
384 pdl> print $src->range([2,3],1) # Cut out a single 1x1 block
385 [
386 [23]
387 ]
388 pdl> print $src->range([2,3], [2,1]) # Cut a 2x1 chunk
389 [
390 [23 33]
391 ]
392 pdl> print $src->range([[2,3]],[2,1]) # Trivial list of 1 chunk
393 [
394 [
395 [23]
396 [33]
397 ]
398 ]
399 pdl> print $src->range([[2,3],[0,1]], [2,1]) # two 2x1 chunks
400 [
401 [
402 [23 1]
403 [33 11]
404 ]
405 ]
406 pdl> # A 2x2 collection of 2x1 chunks
407 pdl> print $src->range([[[1,1],[2,2]],[[2,3],[0,1]]],[2,1])
408 [
409 [
410 [
411 [11 22]
412 [23 1]
413 ]
414 [
415 [21 32]
416 [33 11]
417 ]
418 ]
419 ]
420 pdl> $src = xvals(5,3)*10+yvals(5,3)
421 pdl> print $src->range(3,1) # Thread over y dimension in $src
422 [
423 [30]
424 [31]
425 [32]
426 ]
427 pdl> $src = zeroes(5,4);
429 pdl> $src->range(pdl([2,3],[0,1]),pdl(2,1)) .= xvals(2,2,1) + 1
430 pdl> print $src
431 [
432 [0 0 0 0 0]
433 [2 2 0 0 0]
434 [0 0 0 0 0]
435 [0 0 1 1 0]
436 ]
437 CAVEAT: It's quite possible to select multiple ranges that intersect.
439 In that case, modifying the ranges doesn't have a guaranteed result in
440 the original PDL -- the result is an arbitrary choice among the valid
441 values. For some things that's OK; but for others it's not. In
442 particular, this doesn't work:
443 pdl> $photon_list = new PDL::RandVar->sample(500)->reshape(2,250)*10
445 pdl> histogram = zeroes(10,10)
446 pdl> histogram->range($photon_list,1)++; #not what you wanted
447 The reason is that if two photons land in the same bin, then that bin
449 doesn't get incremented twice. (That may get fixed in a later
450 version...)
451 PERMISSIVE RANGING: If $index has too many dimensions compared to
453 $source, then $source is treated as though it had dummy dimensions of
454 size 1, up to the required number of dimensions. These virtual dummy
455 dimensions have the usual boundary conditions applied to them.
456 If the 0 dimension of $index is ludicrously large (if its size is more
458 than 5 greater than the number of dims in the source PDL) then range
459 will insist that you specify a size in every dimension, to make sure
460 that you know what you're doing. That catches a common error with
461 range usage: confusing the initial dim (which is usually small) with
462 another index dim (perhaps of size 1000).
463 If the index variable is Empty, then range() always returns the Empty
465 PDL. If the index variable is not Empty, indexing it always yields a
466 boundary violation. All non-barfing conditions are treated as
467 truncation, since there are no actual data to return.
468 EFFICIENCY: Because "range" isn't an affine transformation (it involves
470 lookup into a list of N-D indices), it is somewhat memory-inefficient
471 for long lists of ranges, and keeping dataflow open is much slower than
472 for affine transformations (which don't have to copy data around).
473 Doing operations on small subfields of a large range is inefficient
475 because the engine must flow the entire range back into the original
476 PDL with every atomic perl operation, even if you only touch a single
477 element. One way to speed up such code is to sever your range, so that
478 PDL doesn't have to copy the data with each operation, then copy the
479 elements explicitly at the end of your loop. Here's an example that
480 labels each region in a range sequentially, using many small operations
481 rather than a single xvals assignment:
482 ### How to make a collection of small ops run fast with range...
484 $x = $data->range($index, $sizes, $bound)->sever;
485 $aa = $data->range($index, $sizes, $bound);
486 map { $x($_ - 1) .= $_; } (1..$x->nelem); # Lots of little ops
487 $aa .= $x;
488 "range" is a perl front-end to a PP function, "rangeb". Calling
490 "rangeb" is marginally faster but requires that you include all
491 arguments.
492 DEVEL NOTES
494 * index thread dimensions are effectively clumped internally. This
496 makes it easier to loop over the index array but a little more brain-
497 bending to tease out the algorithm.
498 rangeb processes bad values. It will set the bad-value flag of all
500 output ndarrays if the flag is set for any of the input ndarrays.
501 rld
503 Signature: (indx a(n); b(n); [o]c(m))
504 Run-length decode a vector
506 Given a vector $x of the numbers of instances of values $y, run-length
508 decode to $c.
509 rld($x,$y,$c=null);
511 rld does not process bad values. It will set the bad-value flag of all
513 output ndarrays if the flag is set for any of the input ndarrays.
514 rle
516 Signature: (c(n); indx [o]a(m); [o]b(m))
517 Run-length encode a vector
519 Given vector $c, generate a vector $x with the number of each element,
521 and a vector $y of the unique values. New in PDL 2.017, only the
522 elements up to the first instance of 0 in $x are returned, which makes
523 the common use case of a 1-dimensional $c simpler. For threaded
524 operation, $x and $y will be large enough to hold the largest row of
525 $y, and only the elements up to the first instance of 0 in each row of
526 $x should be considered.
527 $c = floor(4*random(10));
529 rle($c,$x=null,$y=null);
530 #or
531 ($x,$y) = rle($c);
532 #for $c of shape [10, 4]:
534 $c = floor(4*random(10,4));
535 ($x,$y) = rle($c);
536 #to see the results of each row one at a time:
538 foreach (0..$c->dim(1)-1){
539 my ($as,$bs) = ($x(:,($_)),$y(:,($_)));
540 my ($ta,$tb) = where($as,$bs,$as!=0); #only the non-zero elements of $x
541 print $c(:,($_)) . " rle==> " , ($ta,$tb) , "\trld==> " . rld($ta,$tb) . "\n";
542 }
543 rle does not process bad values. It will set the bad-value flag of all
545 output ndarrays if the flag is set for any of the input ndarrays.
546 xchg
548 Signature: (P(); C(); PDL_Indx n1; PDL_Indx n2)
549 exchange two dimensions
551 Negative dimension indices count from the end.
553 The command
555 $y = $x->xchg(2,3);
557 creates $y to be like $x except that the dimensions 2 and 3 are
559 exchanged with each other i.e.
560 $y->at(5,3,2,8) == $x->at(5,3,8,2)
562 xchg does not process bad values. It will set the bad-value flag of
564 all output ndarrays if the flag is set for any of the input ndarrays.
565 reorder
567 Re-orders the dimensions of a PDL based on the supplied list.
568 Similar to the "xchg" method, this method re-orders the dimensions of a
570 PDL. While the "xchg" method swaps the position of two dimensions, the
571 reorder method can change the positions of many dimensions at once.
572 # Completely reverse the dimension order of a 6-Dim array.
574 $reOrderedPDL = $pdl->reorder(5,4,3,2,1,0);
575 The argument to reorder is an array representing where the current
577 dimensions should go in the new array. In the above usage, the argument
578 to reorder "(5,4,3,2,1,0)" indicates that the old dimensions ($pdl's
579 dims) should be re-arranged to make the new pdl ($reOrderPDL) according
580 to the following:
581 Old Position New Position
583 ------------ ------------
584 5 0
585 4 1
586 3 2
587 2 3
588 1 4
589 0 5
590 You do not need to specify all dimensions, only a complete set starting
592 at position 0. (Extra dimensions are left where they are). This
593 means, for example, that you can reorder() the X and Y dimensions of an
594 image, and not care whether it is an RGB image with a third dimension
595 running across color plane.
596 Example:
598 pdl> $x = sequence(5,3,2); # Create a 3-d Array
600 pdl> p $x
601 [
602 [
603 [ 0 1 2 3 4]
604 [ 5 6 7 8 9]
605 [10 11 12 13 14]
606 ]
607 [
608 [15 16 17 18 19]
609 [20 21 22 23 24]
610 [25 26 27 28 29]
611 ]
612 ]
613 pdl> p $x->reorder(2,1,0); # Reverse the order of the 3-D PDL
614 [
615 [
616 [ 0 15]
617 [ 5 20]
618 [10 25]
619 ]
620 [
621 [ 1 16]
622 [ 6 21]
623 [11 26]
624 ]
625 [
626 [ 2 17]
627 [ 7 22]
628 [12 27]
629 ]
630 [
631 [ 3 18]
632 [ 8 23]
633 [13 28]
634 ]
635 [
636 [ 4 19]
637 [ 9 24]
638 [14 29]
639 ]
640 ]
641 The above is a simple example that could be duplicated by calling
643 "$x->xchg(0,2)", but it demonstrates the basic functionality of
644 reorder.
645 As this is an index function, any modifications to the result PDL will
647 change the parent.
648 mv
650 Signature: (P(); C(); PDL_Indx n1; PDL_Indx n2)
651 move a dimension to another position
653 The command
655 $y = $x->mv(4,1);
657 creates $y to be like $x except that the dimension 4 is moved to the
659 place 1, so:
660 $y->at(1,2,3,4,5,6) == $x->at(1,5,2,3,4,6);
662 The other dimensions are moved accordingly. Negative dimension indices
664 count from the end.
665 mv does not process bad values. It will set the bad-value flag of all
667 output ndarrays if the flag is set for any of the input ndarrays.
668 oslice
670 Signature: (P(); C(); char* str)
671 DEPRECATED: 'oslice' is the original 'slice' routine in pre-2.006_006
673 versions of PDL. It is left here for reference but will disappear in
674 PDL 3.000
675 Extract a rectangular slice of an ndarray, from a string specifier.
677 "slice" was the original Swiss-army-knife PDL indexing routine, but is
679 largely superseded by the NiceSlice source prefilter and its associated
680 nslice method. It is still used as the basic underlying slicing engine
681 for nslice, and is especially useful in particular niche applications.
682 $x->slice('1:3'); # return the second to fourth elements of $x
684 $x->slice('3:1'); # reverse the above
685 $x->slice('-2:1'); # return last-but-one to second elements of $x
686 The argument string is a comma-separated list of what to do for each
688 dimension. The current formats include the following, where a, b and c
689 are integers and can take legal array index values (including -1 etc):
690 : takes the whole dimension intact.
692 '' (nothing) is a synonym for ":" (This means that
694 "$x->slice(':,3')" is equal to "$x->slice(',3')").
695 a slices only this value out of the corresponding dimension.
697 (a) means the same as "a" by itself except that the resulting
699 dimension of length one is deleted (so if $x has dims "(3,4,5)"
700 then "$x->slice(':,(2),:')" has dimensions "(3,5)" whereas
701 "$x->slice(':,2,:')" has dimensions "(3,1,5))".
702 a:b slices the range a to b inclusive out of the dimension.
704 a:b:c slices the range a to b, with step c (i.e. "3:7:2" gives the
706 indices "(3,5,7)"). This may be confusing to Matlab users but
707 several other packages already use this syntax.
708 '*' inserts an extra dimension of width 1 and
710 '*a' inserts an extra (dummy) dimension of width a.
712 An extension is planned for a later stage allowing
714 "$x->slice('(=1),(=1|5:8),3:6(=1),4:6')" to express a multidimensional
715 diagonal of $x.
716 Trivial out-of-bounds slicing is allowed: if you slice a source
718 dimension that doesn't exist, but only index the 0th element, then
719 "slice" treats the source as if there were a dummy dimension there.
720 The following are all equivalent:
721 xvals(5)->dummy(1,1)->slice('(2),0') # Add dummy dim, then slice
723 xvals(5)->slice('(2),0') # Out-of-bounds slice adds dim.
724 xvals(5)->slice((2),0) # NiceSlice syntax
725 xvals(5)->((2))->dummy(0,1) # NiceSlice syntax
726 This is an error:
728 xvals(5)->slice('(2),1') # nontrivial out-of-bounds slice dies
730 Because slicing doesn't directly manipulate the source and destination
732 pdl -- it just sets up a transformation between them -- indexing errors
733 often aren't reported until later. This is either a bug or a feature,
734 depending on whether you prefer error-reporting clarity or speed of
735 execution.
736 oslice does not process bad values. It will set the bad-value flag of
738 all output ndarrays if the flag is set for any of the input ndarrays.
739 using
741 Returns array of column numbers requested
742 line $pdl->using(1,2);
744 Plot, as a line, column 1 of $pdl vs. column 2
746 pdl> $pdl = rcols("file");
748 pdl> line $pdl->using(1,2);
749 diagonalI
751 Signature: (P(); C(); SV *list)
752 Returns the multidimensional diagonal over the specified dimensions.
754 The diagonal is placed at the first (by number) dimension that is
756 diagonalized. The other diagonalized dimensions are removed. So if $x
757 has dimensions "(5,3,5,4,6,5)" then after
758 $y = $x->diagonal(0,2,5);
760 the ndarray $y has dimensions "(5,3,4,6)" and "$y->at(2,1,0,1)" refers
762 to "$x->at(2,1,2,0,1,2)".
763 NOTE: diagonal doesn't handle threadids correctly. XXX FIX
765 diagonalI does not process bad values. It will set the bad-value flag
767 of all output ndarrays if the flag is set for any of the input
768 ndarrays.
769 lags
771 Signature: (P(); C(); PDL_Indx nthdim;PDL_Indx step;PDL_Indx n)
772 Returns an ndarray of lags to parent.
774 Usage:
776 $lags = $x->lags($nthdim,$step,$nlags);
778 I.e. if $x contains
780 [0,1,2,3,4,5,6,7]
782 then
784 $y = $x->lags(0,2,2);
786 is a (5,2) matrix
788 [2,3,4,5,6,7]
790 [0,1,2,3,4,5]
791 This order of returned indices is kept because the function is called
793 "lags" i.e. the nth lag is n steps behind the original.
794 $step and $nlags must be positive. $nthdim can be negative and will
796 then be counted from the last dim backwards in the usual way (-1 = last
797 dim).
798 lags does not process bad values. It will set the bad-value flag of
800 all output ndarrays if the flag is set for any of the input ndarrays.
801 splitdim
803 Signature: (P(); C(); PDL_Indx nthdim;PDL_Indx nsp)
804 Splits a dimension in the parent ndarray (opposite of clump)
806 After
808 $y = $x->splitdim(2,3);
810 the expression
812 $y->at(6,4,m,n,3,6) == $x->at(6,4,m+3*n)
814 is always true ("m" has to be less than 3).
816 splitdim does not process bad values. It will set the bad-value flag
818 of all output ndarrays if the flag is set for any of the input
819 ndarrays.
820 rotate
822 Signature: (x(n); indx shift(); [oca]y(n))
823 Shift vector elements along with wrap. Flows data back&forth.
825 rotate does not process bad values. It will set the bad-value flag of
827 all output ndarrays if the flag is set for any of the input ndarrays.
828 threadI
830 Signature: (P(); C(); PDL_Indx id; SV *list)
831 internal
833 Put some dimensions to a threadid.
835 $y = $x->threadI(0,1,5); # thread over dims 1,5 in id 1
837 threadI does not process bad values. It will set the bad-value flag of
839 all output ndarrays if the flag is set for any of the input ndarrays.
840 identvaff
842 Signature: (P(); C())
843 A vaffine identity transformation (includes thread_id copying).
845 Mainly for internal use.
847 identvaff does not process bad values. It will set the bad-value flag
849 of all output ndarrays if the flag is set for any of the input
850 ndarrays.
851 unthread
853 Signature: (P(); C(); int atind)
854 All threaded dimensions are made real again.
856 See [TBD Doc] for details and examples.
858 unthread does not process bad values. It will set the bad-value flag
860 of all output ndarrays if the flag is set for any of the input
861 ndarrays.
862 dice
864 Dice rows/columns/planes out of a PDL using indexes for each dimension.
865 This function can be used to extract irregular subsets along many
867 dimension of a PDL, e.g. only certain rows in an image, or planes in a
868 cube. This can of course be done with the usual dimension tricks but
869 this saves having to figure it out each time!
870 This method is similar in functionality to the "slice" method, but
872 "slice" requires that contiguous ranges or ranges with constant offset
873 be extracted. ( i.e. "slice" requires ranges of the form "1,2,3,4,5" or
874 "2,4,6,8,10"). Because of this restriction, "slice" is more memory
875 efficient and slightly faster than dice
876 $slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
878 The arguments to dice are arrays (or 1D PDLs) for each dimension in the
880 PDL. These arrays are used as indexes to which rows/columns/cubes,etc
881 to dice-out (or extract) from the $data PDL.
882 Use "X" to select all indices along a given dimension (compare also
884 mslice). As usual (in slicing methods) trailing dimensions can be
885 omitted implying "X"'es for those.
886 pdl> $x = sequence(10,4)
888 pdl> p $x
889 [
890 [ 0 1 2 3 4 5 6 7 8 9]
891 [10 11 12 13 14 15 16 17 18 19]
892 [20 21 22 23 24 25 26 27 28 29]
893 [30 31 32 33 34 35 36 37 38 39]
894 ]
895 pdl> p $x->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3
896 [
897 [ 1 2]
898 [31 32]
899 ]
900 pdl> p $x->dice(X,[0,3])
901 [
902 [ 0 1 2 3 4 5 6 7 8 9]
903 [30 31 32 33 34 35 36 37 38 39]
904 ]
905 pdl> p $x->dice([0,2,5])
906 [
907 [ 0 2 5]
908 [10 12 15]
909 [20 22 25]
910 [30 32 35]
911 ]
912 As this is an index function, any modifications to the slice will
914 change the parent (use the ".=" operator).
915 dice_axis
917 Dice rows/columns/planes from a single PDL axis (dimension) using index
918 along a specified axis
919 This function can be used to extract irregular subsets along any
921 dimension, e.g. only certain rows in an image, or planes in a cube.
922 This can of course be done with the usual dimension tricks but this
923 saves having to figure it out each time!
924 $slice = $data->dice_axis($axis,$index);
926 pdl> $x = sequence(10,4)
928 pdl> $idx = pdl(1,2)
929 pdl> p $x->dice_axis(0,$idx) # Select columns
930 [
931 [ 1 2]
932 [11 12]
933 [21 22]
934 [31 32]
935 ]
936 pdl> $t = $x->dice_axis(1,$idx) # Select rows
937 pdl> $t.=0
938 pdl> p $x
939 [
940 [ 0 1 2 3 4 5 6 7 8 9]
941 [ 0 0 0 0 0 0 0 0 0 0]
942 [ 0 0 0 0 0 0 0 0 0 0]
943 [30 31 32 33 34 35 36 37 38 39]
944 ]
945 The trick to using this is that the index selects elements along the
947 dimensions specified, so if you have a 2D image "axis=0" will select
948 certain "X" values - i.e. extract columns
949 As this is an index function, any modifications to the slice will
951 change the parent.
952 slice
954 $slice = $data->slice([2,3],'x',[2,2,0],"-1:1:-1", "*3");
955 Extract rectangular slices of an ndarray, from a string specifier, an
957 array ref specifier, or a combination.
958 "slice" is the main method for extracting regions of PDLs and
960 manipulating their dimensionality. You can call it directly or via he
961 NiceSlice source prefilter that extends Perl syntax to include array
962 slicing.
963 "slice" can extract regions along each dimension of a source PDL,
965 subsample or reverse those regions, dice each dimension by selecting a
966 list of locations along it, or basic PDL indexing routine. The
967 selected subfield remains connected to the original PDL via dataflow.
968 In most cases this neither allocates more memory nor slows down
969 subsequent operations on either of the two connected PDLs.
970 You pass in a list of arguments. Each term in the list controls the
972 disposition of one axis of the source PDL and/or returned PDL. Each
973 term can be a string-format cut specifier, a list ref that gives the
974 same information without recourse to string manipulation, or a PDL with
975 up to 1 dimension giving indices along that axis that should be
976 selected.
977 If you want to pass in a single string specifier for the entire
979 operation, you can pass in a comma-delimited list as the first
980 argument. "slice" detects this condition and splits the string into a
981 regular argument list. This calling style is fully backwards
982 compatible with "slice" calls from before PDL 2.006.
983 STRING SYNTAX
985 If a particular argument to "slice" is a string, it is parsed as a
987 selection, an affine slice, or a dummy dimension depending on the form.
988 Leading or trailing whitespace in any part of each specifier is ignored
989 (though it is not ignored within numbers).
990 '', ":", or "X" -- keep
992 The empty string, ":", or "X" cause the entire corresponding
993 dimension to be kept unchanged.
994 "<n>" -- selection
996 A single number alone causes a single index to be selected from the
997 corresponding dimension. The dimension is kept (and reduced to size
998 1) in the output.
999 "(<n>)" -- selection and collapse
1001 A single number in parenthesis causes a single index to be selected
1002 from the corresponding dimension. The dimension is discarded
1003 (completely eliminated) in the output.
1004 "<n>:<m>" -- select an inclusive range
1006 Two numbers separated by a colon selects a range of values from the
1007 corresponding axis, e.g. "3:4" selects elements 3 and 4 along the
1008 corresponding axis, and reduces that axis to size 2 in the output.
1009 Both numbers are regularized so that you can address the last
1010 element of the axis with an index of " -1 ". If, after
1011 regularization, the two numbers are the same, then exactly one
1012 element gets selected (just like the "<n>" case). If, after
1013 regulariation, the second number is lower than the first, then the
1014 resulting slice counts down rather than up -- e.g. "-1:0" will
1015 return the entire axis, in reversed order.
1016 "<n>:<m>:<s>" -- select a range with explicit step
1018 If you include a third parameter, it is the stride of the extracted
1019 range. For example, "0:-1:2" will sample every other element across
1020 the complete dimension. Specifying a stride of 1 prevents
1021 autoreversal -- so to ensure that your slice is *always* forward you
1022 can specify, e.g., "2:$n:1". In that case, an "impossible" slice
1023 gets an Empty PDL (with 0 elements along the corresponding
1024 dimension), so you can generate an Empty PDL with a slice of the
1025 form "2:1:1".
1026 "*<n>" -- insert a dummy dimension
1028 Dummy dimensions aren't present in the original source and are
1029 "mocked up" to match dimensional slots, by repeating the data in the
1030 original PDL some number of times. An asterisk followed by a number
1031 produces a dummy dimension in the output, for example *2 will
1032 generate a dimension of size 2 at the corresponding location in the
1033 output dim list. Omitting the number (and using just an asterisk)
1034 inserts a dummy dimension of size 1.
1035 ARRAY REF SYNTAX
1037 If you feed in an ARRAY ref as a slice term, then it can have 0-3
1039 elements. The first element is the start of the slice along the
1040 corresponding dim; the second is the end; and the third is the
1041 stepsize. Different combinations of inputs give the same flexibility
1042 as the string syntax.
1043 "[]" - keep dim intact
1045 An empty ARRAY ref keeps the entire corresponding dim
1046 "[ 'X' ]" - keep dim intact
1048 "[ '*',$n ]" - generate a dummy dim of size $n
1049 If $n is missing, you get a dummy dim of size 1.
1050 "[ $dex, , 0 ]" - collapse and discard dim
1052 $dex must be a single value. It is used to index the source, and
1053 the corresponding dimension is discarded.
1054 "[ $start, $end ]" - collect inclusive slice
1056 In the simple two-number case, you get a slice that runs up or down
1057 (as appropriate) to connect $start and $end.
1058 "[ $start, $end, $inc ]" - collect inclusive slice
1060 The three-number case works exactly like the three-number string
1061 case above.
1062 PDL args for dicing
1064 If you pass in a 0- or 1-D PDL as a slicing argument, the corresponding
1066 dimension is "diced" -- you get one position along the corresponding
1067 dim, per element of the indexing PDL, e.g. "$x->slice( pdl(3,4,9))"
1068 gives you elements 3, 4, and 9 along the 0 dim of $x.
1069 Because dicing is not an affine transformation, it is slower than
1071 direct slicing even though the syntax is convenient.
1072 $x->slice('1:3'); # return the second to fourth elements of $x
1074 $x->slice('3:1'); # reverse the above
1075 $x->slice('-2:1'); # return last-but-one to second elements of $x
1076 $x->slice([1,3]); # Same as above three calls, but using array ref syntax
1078 $x->slice([3,1]);
1079 $x->slice([-2,1]);
1080 sliceb
1082 Signature: (P(); C(); SV *args)
1083 info not available
1085 sliceb does not process bad values. It will set the bad-value flag of
1087 all output ndarrays if the flag is set for any of the input ndarrays.
1088
1090 For the moment, you can't slice one of the zero-length dims of an empty
1091 ndarray. It is not clear how to implement this in a way that makes
1092 sense.
1093 Many types of index errors are reported far from the indexing operation
1095 that caused them. This is caused by the underlying architecture:
1096 slice() sets up a mapping between variables, but that mapping isn't
1097 tested for correctness until it is used (potentially much later).
1098
1100 Copyright (C) 1997 Tuomas J. Lukka. Contributions by Craig DeForest,
1101 deforest@boulder.swri.edu. Documentation contributions by David
1102 Mertens. All rights reserved. There is no warranty. You are allowed to
1103 redistribute this software / documentation under certain conditions.
1104 For details, see the file COPYING in the PDL distribution. If this file
1105 is separated from the PDL distribution, the copyright notice should be
1106 included in the file.
1107perl v5.34.0 2021-08-16 Slices(3)