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 index
60 Signature: (a(n); indx ind(); [oca] c())
61 "index", "index1d", and "index2d" provide rudimentary index
63 indirection.
64 $c = index($source,$ind);
66 $c = index1d($source,$ind);
67 $c = index2d($source2,$ind1,$ind2);
68 use the $ind variables as indices to look up values in $source. The
70 three routines broadcast slightly differently.
71 • "index" uses direct broadcasting for 1-D indexing across the 0 dim
73 of $source. It can broadcast over source broadcast dims or index
74 broadcast dims, but not (easily) both: If $source has more than 1
75 dimension and $ind has more than 0 dimensions, they must agree in a
76 broadcasting sense.
77 • "index1d" uses a single active dim in $ind to produce a list of
79 indexed values in the 0 dim of the output - it is useful for
80 collapsing $source by indexing with a single row of values along
81 $source's 0 dimension. The output has the same number of dims as
82 $source. The 0 dim of the output has size 1 if $ind is a scalar,
83 and the same size as the 0 dim of $ind if it is not. If $ind and
84 $source both have more than 1 dim, then all dims higher than 0 must
85 agree in a broadcasting sense.
86 • "index2d" works like "index" but uses separate ndarrays for X and Y
88 coordinates. For more general N-dimensional indexing, see the
89 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
90 "indexND", and "range").
91 These functions are two-way, i.e. after
93 $c = $x->index(pdl[0,5,8]);
95 $c .= pdl [0,2,4];
96 the changes in $c will flow back to $x.
98 "index" provids simple broadcasting: multiple-dimensioned arrays are
100 treated as collections of 1-D arrays, so that
101 $x = xvals(10,10)+10*yvals(10,10);
103 $y = $x->index(3);
104 $c = $x->index(9-xvals(10));
105 puts a single column from $x into $y, and puts a single element from
107 each column of $x into $c. If you want to extract multiple columns
108 from an array in one operation, see "dice" or "indexND".
109 index barfs if any of the index values are bad.
111 index1d
113 Signature: (a(n); indx ind(m); [oca] c(m))
114 "index", "index1d", and "index2d" provide rudimentary index
116 indirection.
117 $c = index($source,$ind);
119 $c = index1d($source,$ind);
120 $c = index2d($source2,$ind1,$ind2);
121 use the $ind variables as indices to look up values in $source. The
123 three routines broadcast slightly differently.
124 • "index" uses direct broadcasting for 1-D indexing across the 0 dim
126 of $source. It can broadcast over source broadcast dims or index
127 broadcast dims, but not (easily) both: If $source has more than 1
128 dimension and $ind has more than 0 dimensions, they must agree in a
129 broadcasting sense.
130 • "index1d" uses a single active dim in $ind to produce a list of
132 indexed values in the 0 dim of the output - it is useful for
133 collapsing $source by indexing with a single row of values along
134 $source's 0 dimension. The output has the same number of dims as
135 $source. The 0 dim of the output has size 1 if $ind is a scalar,
136 and the same size as the 0 dim of $ind if it is not. If $ind and
137 $source both have more than 1 dim, then all dims higher than 0 must
138 agree in a broadcasting sense.
139 • "index2d" works like "index" but uses separate ndarrays for X and Y
141 coordinates. For more general N-dimensional indexing, see the
142 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
143 "indexND", and "range").
144 These functions are two-way, i.e. after
146 $c = $x->index(pdl[0,5,8]);
148 $c .= pdl [0,2,4];
149 the changes in $c will flow back to $x.
151 "index" provids simple broadcasting: multiple-dimensioned arrays are
153 treated as collections of 1-D arrays, so that
154 $x = xvals(10,10)+10*yvals(10,10);
156 $y = $x->index(3);
157 $c = $x->index(9-xvals(10));
158 puts a single column from $x into $y, and puts a single element from
160 each column of $x into $c. If you want to extract multiple columns
161 from an array in one operation, see "dice" or "indexND".
162 index1d propagates BAD index elements to the output variable.
164 index2d
166 Signature: (a(na,nb); indx inda(); indx indb(); [oca] c())
167 "index", "index1d", and "index2d" provide rudimentary index
169 indirection.
170 $c = index($source,$ind);
172 $c = index1d($source,$ind);
173 $c = index2d($source2,$ind1,$ind2);
174 use the $ind variables as indices to look up values in $source. The
176 three routines broadcast slightly differently.
177 • "index" uses direct broadcasting for 1-D indexing across the 0 dim
179 of $source. It can broadcast over source broadcast dims or index
180 broadcast dims, but not (easily) both: If $source has more than 1
181 dimension and $ind has more than 0 dimensions, they must agree in a
182 broadcasting sense.
183 • "index1d" uses a single active dim in $ind to produce a list of
185 indexed values in the 0 dim of the output - it is useful for
186 collapsing $source by indexing with a single row of values along
187 $source's 0 dimension. The output has the same number of dims as
188 $source. The 0 dim of the output has size 1 if $ind is a scalar,
189 and the same size as the 0 dim of $ind if it is not. If $ind and
190 $source both have more than 1 dim, then all dims higher than 0 must
191 agree in a broadcasting sense.
192 • "index2d" works like "index" but uses separate ndarrays for X and Y
194 coordinates. For more general N-dimensional indexing, see the
195 PDL::NiceSlice syntax or PDL::Slices (in particular "slice",
196 "indexND", and "range").
197 These functions are two-way, i.e. after
199 $c = $x->index(pdl[0,5,8]);
201 $c .= pdl [0,2,4];
202 the changes in $c will flow back to $x.
204 "index" provids simple broadcasting: multiple-dimensioned arrays are
206 treated as collections of 1-D arrays, so that
207 $x = xvals(10,10)+10*yvals(10,10);
209 $y = $x->index(3);
210 $c = $x->index(9-xvals(10));
211 puts a single column from $x into $y, and puts a single element from
213 each column of $x into $c. If you want to extract multiple columns
214 from an array in one operation, see "dice" or "indexND".
215 index2d barfs if either of the index values are bad.
217 indexNDb
219 Backwards-compatibility alias for indexND
220 indexND
222 Find selected elements in an N-D ndarray, with optional boundary handling
223 $out = $source->indexND( $index, [$method] )
225 $source = 10*xvals(10,10) + yvals(10,10);
227 $index = pdl([[2,3],[4,5]],[[6,7],[8,9]]);
228 print $source->indexND( $index );
229 [
231 [23 45]
232 [67 89]
233 ]
234 IndexND collapses $index by lookup into $source. The 0th dimension of
236 $index is treated as coordinates in $source, and the return value has
237 the same dimensions as the rest of $index. The returned elements are
238 looked up from $source. Dataflow works -- propagated assignment flows
239 back into $source.
240 IndexND and IndexNDb were originally separate routines but they are
242 both now implemented as a call to "range", and have identical syntax to
243 one another.
244 SEE ALSO:
246 "whichND" in PDL::Primitive returns N-D indices into a multidimensional
248 PDL, suitable for feeding to this.
249 rangeb
251 Signature: (P(); C(); pdl *ind_pdl; SV *size; SV *boundary_sv)
252 Engine for "range"
254 Same calling convention as "range", but you must supply all parameters.
256 "rangeb" is marginally faster as it makes a direct PP call, avoiding
257 the perl argument-parsing step.
258 range
260 Extract selected chunks from a source ndarray, with boundary conditions
261 $out = $source->range($index,[$size,[$boundary]])
263 Returns elements or rectangular slices of the original ndarray, indexed
265 by the $index ndarray. $source is an N-dimensional ndarray, and $index
266 is an ndarray whose first dimension has size up to N. Each row of
267 $index is treated as coordinates of a single value or chunk from
268 $source, specifying the location(s) to extract.
269 If you specify a single index location, then range is essentially an
271 expensive slice, with controllable boundary conditions.
272 INPUTS
274 $index and $size can be ndarrays or array refs such as you would feed
276 to zeroes and its ilk. If $index's 0th dimension has size higher than
277 the number of dimensions in $source, then $source is treated as though
278 it had trivial dummy dimensions of size 1, up to the required size to
279 be indexed by $index -- so if your source array is 1-D and your index
280 array is a list of 3-vectors, you get two dummy dimensions of size 1 on
281 the end of your source array.
282 You can extract single elements or N-D rectangular ranges from $source,
284 by setting $size. If $size is undef or zero, then you get a single
285 sample for each row of $index. This behavior is similar to "indexNDb",
286 which is in fact implemented as a call to "range".
287 If $size is positive then you get a range of values from $source at
289 each location, and the output has extra dimensions allocated for them.
290 $size can be a scalar, in which case it applies to all dimensions, or
291 an N-vector, in which case each element is applied independently to the
292 corresponding dimension in $source. See below for details.
293 $boundary is a number, string, or list ref indicating the type of
295 boundary conditions to use when ranges reach the edge of $source. If
296 you specify no boundary conditions the default is to forbid boundary
297 violations on all axes. If you specify exactly one boundary condition,
298 it applies to all axes. If you specify more (as elements of a list
299 ref, or as a packed string, see below), then they apply to dimensions
300 in the order in which they appear, and the last one applies to all
301 subsequent dimensions. (This is less difficult than it sounds; see the
302 examples below).
303 0 (synonyms: 'f','forbid') (default)
305 Ranges are not allowed to cross the boundary of the original PDL.
306 Disallowed ranges throw an error. The errors are thrown at
307 evaluation time, not at the time of the range call (this is the same
308 behavior as "slice").
309 1 (synonyms: 't','truncate')
311 Values outside the original ndarray get BAD if you've got bad value
312 support compiled into your PDL and set the badflag for the source
313 PDL; or 0 if you haven't (you must set the badflag if you want BADs
314 for out of bound values, otherwise you get 0). Reverse dataflow
315 works OK for the portion of the child that is in-bounds. The out-
316 of-bounds part of the child is reset to (BAD|0) during each dataflow
317 operation, but execution continues.
318 2 (synonyms: 'e','x','extend')
320 Values that would be outside the original ndarray point instead to
321 the nearest allowed value within the ndarray. See the CAVEAT below
322 on mappings that are not single valued.
323 3 (synonyms: 'p','periodic')
325 Periodic boundary conditions apply: the numbers in $index are
326 applied, strict-modulo the corresponding dimensions of $source.
327 This is equivalent to duplicating the $source ndarray throughout N-D
328 space. See the CAVEAT below about mappings that are not single
329 valued.
330 4 (synonyms: 'm','mirror')
332 Mirror-reflection periodic boundary conditions apply. See the
333 CAVEAT below about mappings that are not single valued.
334 The boundary condition identifiers all begin with unique characters, so
336 you can feed in multiple boundary conditions as either a list ref or a
337 packed string. (The packed string is marginally faster to run). For
338 example, the four expressions [0,1], ['forbid','truncate'], ['f','t'],
339 and 'ft' all specify that violating the boundary in the 0th dimension
340 throws an error, and all other dimensions get truncated.
341 If you feed in a single string, it is interpreted as a packed boundary
343 array if all of its characters are valid boundary specifiers (e.g.
344 'pet'), but as a single word-style specifier if they are not (e.g.
345 'forbid').
346 OUTPUT
348 The output broadcasts over both $index and $source. Because implicit
350 broadcasting can happen in a couple of ways, a little thought is
351 needed. The returned dimension list is stacked up like this:
352 (index broadcast dims), (index dims (size)), (source broadcast dims)
354 The first few dims of the output correspond to the extra dims of $index
356 (beyond the 0 dim). They allow you to pick out individual ranges from a
357 large, broadcasted collection.
358 The middle few dims of the output correspond to the size dims specified
360 in $size, and contain the range of values that is extracted at each
361 location in $source. Every nonzero element of $size is copied to the
362 dimension list here, so that if you feed in (for example) "$size =
363 [2,0,1]" you get an index dim list of "(2,1)".
364 The last few dims of the output correspond to extra dims of $source
366 beyond the number of dims indexed by $index. These dims act like
367 ordinary broadcast dims, because adding more dims to $source just tacks
368 extra dims on the end of the output. Each source broadcast dim ranges
369 over the entire corresponding dim of $source.
370 Dataflow: Dataflow is bidirectional.
372 Examples: Here are basic examples of "range" operation, showing how to
374 get ranges out of a small matrix. The first few examples show
375 extraction and selection of individual chunks. The last example shows
376 how to mark loci in the original matrix (using dataflow).
377 pdl> $src = 10*xvals(10,5)+yvals(10,5)
379 pdl> print $src->range([2,3]) # Cut out a single element
380 23
381 pdl> print $src->range([2,3],1) # Cut out a single 1x1 block
382 [
383 [23]
384 ]
385 pdl> print $src->range([2,3], [2,1]) # Cut a 2x1 chunk
386 [
387 [23 33]
388 ]
389 pdl> print $src->range([[2,3]],[2,1]) # Trivial list of 1 chunk
390 [
391 [
392 [23]
393 [33]
394 ]
395 ]
396 pdl> print $src->range([[2,3],[0,1]], [2,1]) # two 2x1 chunks
397 [
398 [
399 [23 1]
400 [33 11]
401 ]
402 ]
403 pdl> # A 2x2 collection of 2x1 chunks
404 pdl> print $src->range([[[1,1],[2,2]],[[2,3],[0,1]]],[2,1])
405 [
406 [
407 [
408 [11 22]
409 [23 1]
410 ]
411 [
412 [21 32]
413 [33 11]
414 ]
415 ]
416 ]
417 pdl> $src = xvals(5,3)*10+yvals(5,3)
418 pdl> print $src->range(3,1) # Broadcast over y dimension in $src
419 [
420 [30]
421 [31]
422 [32]
423 ]
424 pdl> $src = zeroes(5,4);
426 pdl> $src->range(pdl([2,3],[0,1]),pdl(2,1)) .= xvals(2,2,1) + 1
427 pdl> print $src
428 [
429 [0 0 0 0 0]
430 [2 2 0 0 0]
431 [0 0 0 0 0]
432 [0 0 1 1 0]
433 ]
434 CAVEAT: It's quite possible to select multiple ranges that intersect.
436 In that case, modifying the ranges doesn't have a guaranteed result in
437 the original PDL -- the result is an arbitrary choice among the valid
438 values. For some things that's OK; but for others it's not. In
439 particular, this doesn't work:
440 pdl> $photon_list = new PDL::RandVar->sample(500)->reshape(2,250)*10
442 pdl> $histogram = zeroes(10,10)
443 pdl> $histogram->range($photon_list,1)++; #not what you wanted
444 The reason is that if two photons land in the same bin, then that bin
446 doesn't get incremented twice. (That may get fixed in a later
447 version...)
448 PERMISSIVE RANGING: If $index has too many dimensions compared to
450 $source, then $source is treated as though it had dummy dimensions of
451 size 1, up to the required number of dimensions. These virtual dummy
452 dimensions have the usual boundary conditions applied to them.
453 If the 0 dimension of $index is ludicrously large (if its size is more
455 than 5 greater than the number of dims in the source PDL) then range
456 will insist that you specify a size in every dimension, to make sure
457 that you know what you're doing. That catches a common error with
458 range usage: confusing the initial dim (which is usually small) with
459 another index dim (perhaps of size 1000).
460 If the index variable is Empty, then range() always returns the Empty
462 PDL. If the index variable is not Empty, indexing it always yields a
463 boundary violation. All non-barfing conditions are treated as
464 truncation, since there are no actual data to return.
465 EFFICIENCY: Because "range" isn't an affine transformation (it involves
467 lookup into a list of N-D indices), it is somewhat memory-inefficient
468 for long lists of ranges, and keeping dataflow open is much slower than
469 for affine transformations (which don't have to copy data around).
470 Doing operations on small subfields of a large range is inefficient
472 because the engine must flow the entire range back into the original
473 PDL with every atomic perl operation, even if you only touch a single
474 element. One way to speed up such code is to sever your range, so that
475 PDL doesn't have to copy the data with each operation, then copy the
476 elements explicitly at the end of your loop. Here's an example that
477 labels each region in a range sequentially, using many small operations
478 rather than a single xvals assignment:
479 ### How to make a collection of small ops run fast with range...
481 $x = $data->range($index, $sizes, $bound)->sever;
482 $aa = $data->range($index, $sizes, $bound);
483 $x($_ - 1) .= $_ for 1..$x->nelem; # Lots of little ops
484 $aa .= $x;
485 "range" is a perl front-end to a PP function, "rangeb". Calling
487 "rangeb" is marginally faster but requires that you include all
488 arguments.
489 DEVEL NOTES
491 * index broadcast dimensions are effectively clumped internally. This
493 makes it easier to loop over the index array but a little more brain-
494 bending to tease out the algorithm.
495 rangeb processes bad values. It will set the bad-value flag of all
497 output ndarrays if the flag is set for any of the input ndarrays.
498 rld
500 Signature: (indx a(n); b(n); [o]c(m))
501 Run-length decode a vector
503 Given a vector $x of the numbers of instances of values $y, run-length
505 decode to $c.
506 rld($x,$y,$c=null);
508 rld does not process bad values. It will set the bad-value flag of all
510 output ndarrays if the flag is set for any of the input ndarrays.
511 rle
513 Signature: (c(n); indx [o]a(m); [o]b(m))
514 Run-length encode a vector
516 Given vector $c, generate a vector $x with the number of each element,
518 and a vector $y of the unique values. New in PDL 2.017, only the
519 elements up to the first instance of 0 in $x are returned, which makes
520 the common use case of a 1-dimensional $c simpler. For broadcast
521 operation, $x and $y will be large enough to hold the largest row of
522 $y, and only the elements up to the first instance of 0 in each row of
523 $x should be considered.
524 $c = floor(4*random(10));
526 rle($c,$x=null,$y=null);
527 #or
528 ($x,$y) = rle($c);
529 #for $c of shape [10, 4]:
531 $c = floor(4*random(10,4));
532 ($x,$y) = rle($c);
533 #to see the results of each row one at a time:
535 foreach (0..$c->dim(1)-1){
536 my ($as,$bs) = ($x(:,($_)),$y(:,($_)));
537 my ($ta,$tb) = where($as,$bs,$as!=0); #only the non-zero elements of $x
538 print $c(:,($_)) . " rle==> " , ($ta,$tb) , "\trld==> " . rld($ta,$tb) . "\n";
539 }
540 # the inverse of (chance of all 6 3d6 rolls being >= each possible sum)
542 ($nrolls, $ndice, $dmax) = (6, 3, 6);
543 ($x, $x1) = (allaxisvals(($dmax) x $ndice)+1)->sumover->flat->qsort->rle;
544 $y = $x->cumusumover;
545 $yprob1x = $y->slice('-1:0')->double / $y->slice('(-1)');
546 $z = cat($x1, 1 / $yprob1x**$nrolls)->transpose;
547 rle does not process bad values. It will set the bad-value flag of all
549 output ndarrays if the flag is set for any of the input ndarrays.
550 rlevec
552 Signature: (c(M,N); indx [o]a(N); [o]b(M,N))
553 Run-length encode a set of vectors.
555 Higher-order rle(), for use with qsortvec().
557 Given set of vectors $c, generate a vector $a with the number of
559 occurrences of each element (where an "element" is a vector of length
560 $M occurring in $c), and a set of vectors $b containing the unique
561 values. As for rle(), only the elements up to the first instance of 0
562 in $a should be considered.
563 Can be used together with clump() to run-length encode "values" of
565 arbitrary dimensions. Can be used together with rotate(), cat(),
566 append(), and qsortvec() to count N-grams over a 1d PDL.
567 See also: "rle", "qsortvec" in PDL::Ufunc, "uniqvec" in PDL::Primitive
569 Contributed by Bryan Jurish <moocow@cpan.org>.
570 rlevec does not process bad values. It will set the bad-value flag of
572 all output ndarrays if the flag is set for any of the input ndarrays.
573 rldvec
575 Signature: (indx a(N); b(M,N); [o]c(M,N))
576 Run-length decode a set of vectors, akin to a higher-order rld().
578 Given a vector $a() of the number of occurrences of each row, and a set
580 $c() of row-vectors each of length $M, run-length decode to $c().
581 Can be used together with clump() to run-length decode "values" of
583 arbitrary dimensions.
584 See also: "rld". Contributed by Bryan Jurish <moocow@cpan.org>.
586 rldvec does not process bad values. It will set the bad-value flag of
588 all output ndarrays if the flag is set for any of the input ndarrays.
589 rleseq
591 Signature: (c(N); indx [o]a(N); [o]b(N))
592 Run-length encode a vector of subsequences.
594 Given a vector of $c() of concatenated variable-length, variable-offset
596 subsequences, generate a vector $a containing the length of each
597 subsequence and a vector $b containing the subsequence offsets. As for
598 rle(), only the elements up to the first instance of 0 in $a should be
599 considered.
600 See also "rle". Contributed by Bryan Jurish <moocow@cpan.org>.
602 rleseq does not process bad values. It will set the bad-value flag of
604 all output ndarrays if the flag is set for any of the input ndarrays.
605 rldseq
607 Signature: (indx a(N); b(N); [o]c(M))
608 Run-length decode a subsequence vector.
610 Given a vector $a() of sequence lengths and a vector $b() of
612 corresponding offsets, decode concatenation of subsequences to $c(), as
613 for:
614 $c = null;
616 $c = $c->append($b($_)+sequence($a->type,$a($_))) foreach (0..($N-1));
617 See also: "rld". Contributed by Bryan Jurish <moocow@cpan.org>.
619 rldseq does not process bad values. It will set the bad-value flag of
621 all output ndarrays if the flag is set for any of the input ndarrays.
622 rleND
624 Signature: (data(@vdims,N); int [o]counts(N); [o]elts(@vdims,N))
625 Run-length encode a set of (sorted) n-dimensional values.
627 Generalization of rle() and vv_rlevec(): given set of values $data,
629 generate a vector $counts with the number of occurrences of each
630 element (where an "element" is a matrix of dimensions @vdims occurring
631 as a sequential run over the final dimension in $data), and a set of
632 vectors $elts containing the elements which begin a run. Really just a
633 wrapper for clump() and rlevec().
634 See also: "rle", "rlevec". Contributed by Bryan Jurish
636 <moocow@cpan.org>.
637 rldND
639 Signature: (int counts(N); elts(@vdims,N); [o]data(@vdims,N);)
640 Run-length decode a set of (sorted) n-dimensional values.
642 Generalization of rld() and rldvec(): given a vector $counts() of the
644 number of occurrences of each @vdims-dimensioned element, and a set
645 $elts() of @vdims-dimensioned elements, run-length decode to $data().
646 Really just a wrapper for clump() and rldvec().
648 See also: "rld", "rldvec". Contributed by Bryan Jurish
650 <moocow@cpan.org>.
651 xchg
653 Signature: (P(); C(); PDL_Indx n1; PDL_Indx n2)
654 exchange two dimensions
656 Negative dimension indices count from the end.
658 The command
660 $y = $x->xchg(2,3);
662 creates $y to be like $x except that the dimensions 2 and 3 are
664 exchanged with each other i.e.
665 $y->at(5,3,2,8) == $x->at(5,3,8,2)
667 xchg does not process bad values. It will set the bad-value flag of
669 all output ndarrays if the flag is set for any of the input ndarrays.
670 reorder
672 Re-orders the dimensions of a PDL based on the supplied list.
673 Similar to the "xchg" method, this method re-orders the dimensions of a
675 PDL. While the "xchg" method swaps the position of two dimensions, the
676 reorder method can change the positions of many dimensions at once.
677 # Completely reverse the dimension order of a 6-Dim array.
679 $reOrderedPDL = $pdl->reorder(5,4,3,2,1,0);
680 The argument to reorder is an array representing where the current
682 dimensions should go in the new array. In the above usage, the argument
683 to reorder "(5,4,3,2,1,0)" indicates that the old dimensions ($pdl's
684 dims) should be re-arranged to make the new pdl ($reOrderPDL) according
685 to the following:
686 Old Position New Position
688 ------------ ------------
689 5 0
690 4 1
691 3 2
692 2 3
693 1 4
694 0 5
695 You do not need to specify all dimensions, only a complete set starting
697 at position 0. (Extra dimensions are left where they are). This
698 means, for example, that you can reorder() the X and Y dimensions of an
699 image, and not care whether it is an RGB image with a third dimension
700 running across color plane.
701 Example:
703 pdl> $x = sequence(5,3,2); # Create a 3-d Array
705 pdl> p $x
706 [
707 [
708 [ 0 1 2 3 4]
709 [ 5 6 7 8 9]
710 [10 11 12 13 14]
711 ]
712 [
713 [15 16 17 18 19]
714 [20 21 22 23 24]
715 [25 26 27 28 29]
716 ]
717 ]
718 pdl> p $x->reorder(2,1,0); # Reverse the order of the 3-D PDL
719 [
720 [
721 [ 0 15]
722 [ 5 20]
723 [10 25]
724 ]
725 [
726 [ 1 16]
727 [ 6 21]
728 [11 26]
729 ]
730 [
731 [ 2 17]
732 [ 7 22]
733 [12 27]
734 ]
735 [
736 [ 3 18]
737 [ 8 23]
738 [13 28]
739 ]
740 [
741 [ 4 19]
742 [ 9 24]
743 [14 29]
744 ]
745 ]
746 The above is a simple example that could be duplicated by calling
748 "$x->xchg(0,2)", but it demonstrates the basic functionality of
749 reorder.
750 As this is an index function, any modifications to the result PDL will
752 change the parent.
753 mv
755 Signature: (P(); C(); PDL_Indx n1; PDL_Indx n2)
756 move a dimension to another position
758 The command
760 $y = $x->mv(4,1);
762 creates $y to be like $x except that the dimension 4 is moved to the
764 place 1, so:
765 $y->at(1,2,3,4,5,6) == $x->at(1,5,2,3,4,6);
767 The other dimensions are moved accordingly. Negative dimension indices
769 count from the end.
770 mv does not process bad values. It will set the bad-value flag of all
772 output ndarrays if the flag is set for any of the input ndarrays.
773 using
775 Returns array of column numbers requested
776 line $pdl->using(1,2);
778 Plot, as a line, column 1 of $pdl vs. column 2
780 pdl> $pdl = rcols("file");
782 pdl> line $pdl->using(1,2);
783 diagonal
785 Signature: (P(); C(); PDL_Indx whichdims[])
786 Returns the multidimensional diagonal over the specified dimensions.
788 The diagonal is placed at the first (by number) dimension that is
790 diagonalized. The other diagonalized dimensions are removed. So if $x
791 has dimensions "(5,3,5,4,6,5)" then after
792 $d = $x->diagonal(dim1, dim2,...)
794 $y = $x->diagonal(0,2,5);
796 the ndarray $y has dimensions "(5,3,4,6)" and "$y->at(2,1,0,1)" refers
798 to "$x->at(2,1,2,0,1,2)".
799 NOTE: diagonal doesn't handle broadcastids correctly. XXX FIX
801 pdl> $x = zeroes(3,3,3);
803 pdl> ($y = $x->diagonal(0,1))++;
804 pdl> p $x
805 [
806 [
807 [1 0 0]
808 [0 1 0]
809 [0 0 1]
810 ]
811 [
812 [1 0 0]
813 [0 1 0]
814 [0 0 1]
815 ]
816 [
817 [1 0 0]
818 [0 1 0]
819 [0 0 1]
820 ]
821 ]
822 diagonal does not process bad values. It will set the bad-value flag
824 of all output ndarrays if the flag is set for any of the input
825 ndarrays.
826 lags
828 Signature: (P(); C(); PDL_Indx nthdim;PDL_Indx step;PDL_Indx n)
829 Returns an ndarray of lags to parent.
831 Usage:
833 $lags = $x->lags($nthdim,$step,$nlags);
835 I.e. if $x contains
837 [0,1,2,3,4,5,6,7]
839 then
841 $y = $x->lags(0,2,2);
843 is a (5,2) matrix
845 [2,3,4,5,6,7]
847 [0,1,2,3,4,5]
848 This order of returned indices is kept because the function is called
850 "lags" i.e. the nth lag is n steps behind the original.
851 $step and $nlags must be positive. $nthdim can be negative and will
853 then be counted from the last dim backwards in the usual way (-1 = last
854 dim).
855 lags does not process bad values. It will set the bad-value flag of
857 all output ndarrays if the flag is set for any of the input ndarrays.
858 splitdim
860 Signature: (P(); C(); PDL_Indx nthdim;PDL_Indx nsp)
861 Splits a dimension in the parent ndarray (opposite of clump). As of
863 2.076, throws exception if non-divisible "nsp" given, and can give
864 negative "nthdim" which then counts backwards.
865 After
867 $y = $x->splitdim(2,3);
869 the expression
871 $y->at(6,4,m,n,3,6) == $x->at(6,4,m+3*n)
873 is always true ("m" has to be less than 3).
875 splitdim does not process bad values. It will set the bad-value flag
877 of all output ndarrays if the flag is set for any of the input
878 ndarrays.
879 rotate
881 Signature: (x(n); indx shift(); [oca]y(n))
882 Shift vector elements along with wrap. Flows data back&forth.
884 rotate does not process bad values. It will set the bad-value flag of
886 all output ndarrays if the flag is set for any of the input ndarrays.
887 broadcastI
889 Signature: (P(); C(); PDL_Indx id; PDL_Indx whichdims[])
890 internal
892 Put some dimensions to a broadcastid.
894 $y = $x->broadcastI(0,1,5); # broadcast over dims 1,5 in id 1
896 broadcastI does not process bad values. It will set the bad-value flag
898 of all output ndarrays if the flag is set for any of the input
899 ndarrays.
900 unbroadcast
902 Signature: (P(); C(); PDL_Indx atind)
903 All broadcasted dimensions are made real again.
905 See [TBD Doc] for details and examples.
907 unbroadcast does not process bad values. It will set the bad-value
909 flag of all output ndarrays if the flag is set for any of the input
910 ndarrays.
911 dice
913 Dice rows/columns/planes out of a PDL using indexes for each dimension.
914 This function can be used to extract irregular subsets along many
916 dimension of a PDL, e.g. only certain rows in an image, or planes in a
917 cube. This can of course be done with the usual dimension tricks but
918 this saves having to figure it out each time!
919 This method is similar in functionality to the "slice" method, but
921 "slice" requires that contiguous ranges or ranges with constant offset
922 be extracted. ( i.e. "slice" requires ranges of the form "1,2,3,4,5" or
923 "2,4,6,8,10"). Because of this restriction, "slice" is more memory
924 efficient and slightly faster than dice
925 $slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
927 The arguments to dice are arrays (or 1D PDLs) for each dimension in the
929 PDL. These arrays are used as indexes to which rows/columns/cubes,etc
930 to dice-out (or extract) from the $data PDL.
931 Use "X" to select all indices along a given dimension (compare also
933 mslice). As usual (in slicing methods) trailing dimensions can be
934 omitted implying "X"'es for those.
935 pdl> $x = sequence(10,4)
937 pdl> p $x
938 [
939 [ 0 1 2 3 4 5 6 7 8 9]
940 [10 11 12 13 14 15 16 17 18 19]
941 [20 21 22 23 24 25 26 27 28 29]
942 [30 31 32 33 34 35 36 37 38 39]
943 ]
944 pdl> p $x->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3
945 [
946 [ 1 2]
947 [31 32]
948 ]
949 pdl> p $x->dice(X,[0,3])
950 [
951 [ 0 1 2 3 4 5 6 7 8 9]
952 [30 31 32 33 34 35 36 37 38 39]
953 ]
954 pdl> p $x->dice([0,2,5])
955 [
956 [ 0 2 5]
957 [10 12 15]
958 [20 22 25]
959 [30 32 35]
960 ]
961 As this is an index function, any modifications to the slice will
963 change the parent (use the ".=" operator).
964 dice_axis
966 Dice rows/columns/planes from a single PDL axis (dimension) using index
967 along a specified axis
968 This function can be used to extract irregular subsets along any
970 dimension, e.g. only certain rows in an image, or planes in a cube.
971 This can of course be done with the usual dimension tricks but this
972 saves having to figure it out each time!
973 $slice = $data->dice_axis($axis,$index);
975 pdl> $x = sequence(10,4)
977 pdl> $idx = pdl(1,2)
978 pdl> p $x->dice_axis(0,$idx) # Select columns
979 [
980 [ 1 2]
981 [11 12]
982 [21 22]
983 [31 32]
984 ]
985 pdl> $t = $x->dice_axis(1,$idx) # Select rows
986 pdl> $t.=0
987 pdl> p $x
988 [
989 [ 0 1 2 3 4 5 6 7 8 9]
990 [ 0 0 0 0 0 0 0 0 0 0]
991 [ 0 0 0 0 0 0 0 0 0 0]
992 [30 31 32 33 34 35 36 37 38 39]
993 ]
994 The trick to using this is that the index selects elements along the
996 dimensions specified, so if you have a 2D image "axis=0" will select
997 certain "X" values - i.e. extract columns
998 As this is an index function, any modifications to the slice will
1000 change the parent.
1001 slice
1003 Signature: (P(); C(); pdl_slice_args *arglist)
1004 $slice = $data->slice([2,3],'x',[2,2,0],"-1:1:-1", "*3");
1006 Extract rectangular slices of an ndarray, from a string specifier, an
1008 array ref specifier, or a combination.
1009 "slice" is the main method for extracting regions of PDLs and
1011 manipulating their dimensionality. You can call it directly or via the
1012 NiceSlice source prefilter that extends Perl syntax to include array
1013 slicing.
1014 "slice" can extract regions along each dimension of a source PDL,
1016 subsample or reverse those regions, dice each dimension by selecting a
1017 list of locations along it, or basic PDL indexing routine. The
1018 selected subfield remains connected to the original PDL via dataflow.
1019 In most cases this neither allocates more memory nor slows down
1020 subsequent operations on either of the two connected PDLs.
1021 You pass in a list of arguments. Each term in the list controls the
1023 disposition of one axis of the source PDL and/or returned PDL. Each
1024 term can be a string-format cut specifier, a list ref that gives the
1025 same information without recourse to string manipulation, or a PDL with
1026 up to 1 dimension giving indices along that axis that should be
1027 selected.
1028 If you want to pass in a single string specifier for the entire
1030 operation, you can pass in a comma-delimited list as the first
1031 argument. "slice" detects this condition and splits the string into a
1032 regular argument list. This calling style is fully backwards
1033 compatible with "slice" calls from before PDL 2.006.
1034 STRING SYNTAX
1036 If a particular argument to "slice" is a string, it is parsed as a
1038 selection, an affine slice, or a dummy dimension depending on the form.
1039 Leading or trailing whitespace in any part of each specifier is ignored
1040 (though it is not ignored within numbers).
1041 '', ":", or "X" -- keep
1043 The empty string, ":", or "X" cause the entire corresponding
1044 dimension to be kept unchanged.
1045 "<n>" -- selection
1047 A single number alone causes a single index to be selected from the
1048 corresponding dimension. The dimension is kept (and reduced to size
1049 1) in the output.
1050 "(<n>)" -- selection and collapse
1052 A single number in parenthesis causes a single index to be selected
1053 from the corresponding dimension. The dimension is discarded
1054 (completely eliminated) in the output.
1055 "<n>:<m>" -- select an inclusive range
1057 Two numbers separated by a colon selects a range of values from the
1058 corresponding axis, e.g. "3:4" selects elements 3 and 4 along the
1059 corresponding axis, and reduces that axis to size 2 in the output.
1060 Both numbers are regularized so that you can address the last
1061 element of the axis with an index of -1 . If, after
1062 regularization, the two numbers are the same, then exactly one
1063 element gets selected (just like the "<n>" case). If, after
1064 regulariation, the second number is lower than the first, then the
1065 resulting slice counts down rather than up -- e.g. "-1:0" will
1066 return the entire axis, in reversed order.
1067 "<n>:<m>:<s>" -- select a range with explicit step
1069 If you include a third parameter, it is the stride of the extracted
1070 range. For example, "0:-1:2" will sample every other element across
1071 the complete dimension. Specifying a stride of 1 prevents
1072 autoreversal -- so to ensure that your slice is *always* forward you
1073 can specify, e.g., "2:$n:1". In that case, an "impossible" slice
1074 gets an Empty PDL (with 0 elements along the corresponding
1075 dimension), so you can generate an Empty PDL with a slice of the
1076 form "2:1:1".
1077 "*<n>" -- insert a dummy dimension
1079 Dummy dimensions aren't present in the original source and are
1080 "mocked up" to match dimensional slots, by repeating the data in the
1081 original PDL some number of times. An asterisk followed by a number
1082 produces a dummy dimension in the output, for example *2 will
1083 generate a dimension of size 2 at the corresponding location in the
1084 output dim list. Omitting the number (and using just an asterisk)
1085 inserts a dummy dimension of size 1.
1086 ARRAY REF SYNTAX
1088 If you feed in an ARRAY ref as a slice term, then it can have 0-3
1090 elements. The first element is the start of the slice along the
1091 corresponding dim; the second is the end; and the third is the
1092 stepsize. Different combinations of inputs give the same flexibility
1093 as the string syntax.
1094 "[]" - keep dim intact
1096 An empty ARRAY ref keeps the entire corresponding dim
1097 "[ 'X' ]" - keep dim intact
1099 "[ '*',$n ]" - generate a dummy dim of size $n
1100 If $n is missing, you get a dummy dim of size 1.
1101 "[ $dex, , 0 ]" - collapse and discard dim
1103 $dex must be a single value. It is used to index the source, and
1104 the corresponding dimension is discarded.
1105 "[ $start, $end ]" - collect inclusive slice
1107 In the simple two-number case, you get a slice that runs up or down
1108 (as appropriate) to connect $start and $end.
1109 "[ $start, $end, $inc ]" - collect inclusive slice
1111 The three-number case works exactly like the three-number string
1112 case above.
1113 PDL args for dicing
1115 If you pass in a 0- or 1-D PDL as a slicing argument, the corresponding
1117 dimension is "diced" -- you get one position along the corresponding
1118 dim, per element of the indexing PDL, e.g. "$x->slice( pdl(3,4,9))"
1119 gives you elements 3, 4, and 9 along the 0 dim of $x.
1120 Because dicing is not an affine transformation, it is slower than
1122 direct slicing even though the syntax is convenient.
1123 $x->slice('1:3'); # return the second to fourth elements of $x
1125 $x->slice('3:1'); # reverse the above
1126 $x->slice('-2:1'); # return last-but-one to second elements of $x
1127 $x->slice([1,3]); # Same as above three calls, but using array ref syntax
1129 $x->slice([3,1]);
1130 $x->slice([-2,1]);
1131 slice does not process bad values. It will set the bad-value flag of
1133 all output ndarrays if the flag is set for any of the input ndarrays.
1134
1136 For the moment, you can't slice one of the zero-length dims of an empty
1137 ndarray. It is not clear how to implement this in a way that makes
1138 sense.
1139 Many types of index errors are reported far from the indexing operation
1141 that caused them. This is caused by the underlying architecture:
1142 slice() sets up a mapping between variables, but that mapping isn't
1143 tested for correctness until it is used (potentially much later).
1144
1146 Copyright (C) 1997 Tuomas J. Lukka. Contributions by Craig DeForest,
1147 deforest@boulder.swri.edu. Documentation contributions by David
1148 Mertens. All rights reserved. There is no warranty. You are allowed to
1149 redistribute this software / documentation under certain conditions.
1150 For details, see the file COPYING in the PDL distribution. If this file
1151 is separated from the PDL distribution, the copyright notice should be
1152 included in the file.
1153perl v5.36.0 2023-01-20 Slices(3)