1NiceSlice(3) User Contributed Perl Documentation NiceSlice(3)
2
6 PDL::NiceSlice - toward a nicer slicing syntax for PDL
7
9 use PDL::NiceSlice;
10 $x(1:4) .= 2; # concise syntax for ranges
12 print $y((0),1:$end); # use variables in the slice expression
13 $x->transpose->(($pos-1)) .= 0; # default method syntax
14 $idx = long 1, 7, 3, 0; # an ndarray of indices
16 $x(-3:2:2,$idx) += 3; # mix explicit indexing and ranges
17 $x->clump(1,2)->(0:30); # 'default method' syntax
18 $x(myfunc(0,$var),1:4)++; # when using functions in slice expressions
19 # use parentheses around args!
20 $y = $x(*3); # Add dummy dimension of order 3
22 # modifiers are specified in a ;-separated trailing block
24 $x($x!=3;?)++; # short for $x->where($x!=3)++
25 $x(0:1114;_) .= 0; # short for $x->flat->(0:1114)
26 $y = $x(0:-1:3;|); # short for $x(0:-1:3)->sever
27 $n = sequence 3,1,4,1;
28 $y = $n(;-); # drop all dimensions of size 1 (AKA squeeze)
29 $y = $n(0,0;-|); # squeeze *and* sever
30 $c = $x(0,3,0;-); # more compact way of saying $x((0),(3),(0))
31
33 Slicing is a basic, extremely common operation, and PDL's "slice" in
34 PDL::Slices method would be cumbersome to use in many cases.
35 "PDL::NiceSlice" rectifies that by incorporating new slicing syntax
36 directly into the language via a perl source filter (see perlfilter).
37 NiceSlice adds no new functionality, only convenient syntax.
38 NiceSlice is loaded automatically in the perldl or pdl2 shell, but (to
40 avoid conflicts with other modules) must be loaded explicitly in
41 standalone perl/PDL scripts (see below). If you prefer not to use a
42 prefilter on your standalone scripts, you can use the "slice" in
43 PDL::Slices method in those scripts, rather than the more compact
44 NiceSlice constructs.
45
47 The new slicing syntax can be switched on and off in scripts and perl
48 modules by using or unloading "PDL::NiceSlice".
49 But now back to scripts and modules. Everything after "use
51 PDL::NiceSlice" will be translated and you can use the new slicing
52 syntax. Source filtering will continue until the end of the file is
53 encountered. You can stop sourcefiltering before the end of the file
54 by issuing a "no PDL::NiceSlice" statement.
55 Here is an example:
57 use PDL::NiceSlice;
59 # this code will be translated
61 # and you can use the new slicing syntax
62 no PDL::NiceSlice;
64 # this code won't
66 # and the new slicing syntax will raise errors!
67 See also Filter::Simple and example in this distribution for further
69 examples.
70 NOTE: Unlike "normal" modules you need to include a "use
72 PDL::NiceSlice" call in each and every file that contains code that
73 uses the new slicing syntax. Imagine the following situation: a file
74 test0.pl
75 # start test0.pl
77 use PDL;
78 use PDL::NiceSlice;
79 $x = sequence 10;
81 print $x(0:4),"\n";
82 require 'test1.pl';
84 # end test0.pl
85 that "require"s a second file test1.pl
87 # begin test1.pl
89 $aa = sequence 11;
90 print $aa(0:7),"\n";
91 1;
92 # end test1.pl
93 Following conventional perl wisdom everything should be alright since
95 we "use"d "PDL" and "PDL::NiceSlice" already from within test0.pl and
96 by the time test1.pl is "require"d things should be defined and
97 imported, etc. A quick test run will, however, produce something like
98 the following:
99 perl test0.pl
101 [0 1 2 3 4]
102 syntax error at test1.pl line 3, near "0:"
103 Compilation failed in require at test0.pl line 7.
104 This can be fixed by adding the line
106 use PDL::NiceSlice;
108 "before" the code in test1.pl that uses the new slicing syntax (to play
110 safe just include the line near the top of the file), e.g.
111 # begin corrected test1.pl
113 use PDL::NiceSlice;
114 $aa = sequence 11;
115 print $aa(0:7),"\n";
116 1;
117 # end test1.pl
118 Now things proceed more smoothly
120 perl test0.pl
122 [0 1 2 3 4]
123 [0 1 2 3 4 5 6 7]
124 Note that we don't need to issue "use PDL" again. "PDL::NiceSlice" is
126 a somewhat funny module in that respect. It is a consequence of the way
127 source filtering works in Perl (see also the IMPLEMENTATION section
128 below).
129 evals and "PDL::NiceSlice"
131 Due to "PDL::NiceSlice" being a source filter it won't work in the
132 usual way within evals. The following will not do what you want:
133 $x = sequence 10;
135 eval << 'EOE';
136 use PDL::NiceSlice;
138 $y = $x(0:5);
139 EOE
141 print $y;
142 Instead say:
144 use PDL::NiceSlice;
146 $x = sequence 10;
147 eval << 'EOE';
148 $y = $x(0:5);
150 EOE
152 print $y;
153 Source filters must be executed at compile time to be effective. And
155 "PDL::NiceSlice" is just a source filter (although it is not
156 necessarily obvious for the casual user).
157
159 Using "PDL::NiceSlice" slicing ndarrays becomes so much easier since,
160 first of all, you don't need to make explicit method calls. No
161 $pdl->slice(....);
163 calls, etc. Instead, "PDL::NiceSlice" introduces two ways in which to
165 slice ndarrays without too much typing:
166 • using parentheses directly following a scalar variable name, for
168 example
169 $c = $y(0:-3:4,(0));
171 • using the so called default method invocation in which the ndarray
173 object is treated as if it were a reference to a subroutine (see also
174 perlref). Take this example that slices an ndarray that is part of a
175 perl list @b:
176 $c = $b[0]->(0:-3:4,(0));
178 The format of the argument list is the same for both types of
180 invocation and will be explained in more detail below.
181 Parentheses following a scalar variable name
183 An arglist in parentheses following directly after a scalar variable
184 name that is not preceded by "&" will be resolved as a slicing command,
185 e.g.
186 $x(1:4) .= 2; # only use this syntax on ndarrays
188 $sum += $x(,(1));
189 However, if the variable name is immediately preceded by a "&", for
191 example
192 &$x(4,5);
194 it will not be interpreted as a slicing expression. Rather, to avoid
196 interfering with the current subref syntax, it will be treated as an
197 invocation of the code reference $x with argumentlist "(4,5)".
198 The $x(ARGS) syntax collides in a minor way with the perl syntax. In
200 particular, ``foreach $var(LIST)'' appears like a PDL slicing call.
201 NiceSlice avoids translating the ``for $var(LIST)'' and ``foreach
202 $var(LIST)'' constructs for this reason. Since you can't use just any
203 old lvalue expression in the 'foreach' 'for' constructs -- only a real
204 perl scalar will do -- there's no functionality lost. If later
205 versions of perl accept ``foreach <lvalue-expr> (LIST)'', then you can
206 use the code ref syntax, below, to get what you want.
207 The default method syntax
209 The second syntax that will be recognized is what I called the default
210 method syntax. It is the method arrow "->" directly followed by an open
211 parenthesis, e.g.
212 $x->transpose->(($pos)) .= 0;
214 Note that this conflicts with the use of normal code references, since
216 you can write in plain Perl
217 $sub = sub { print join ',', @_ };
219 $sub->(1,'a');
220 NOTE: Once "use PDL::NiceSlice" is in effect (you can always switch it
222 off with a line "no PDL::NiceSlice;" anywhere in the script) the source
223 filter will incorrectly replace the above call to $sub with an
224 invocation of the slicing method. This is one of the pitfalls of using
225 a source filter that doesn't know anything about the runtime type of a
226 variable (cf. the Implementation section).
227 This shouldn't be a major problem in practice; a simple workaround is
229 to use the "&"-way of calling subrefs, e.g.:
230 $sub = sub { print join ',', @_ };
232 &$sub(1,'a');
233 When to use which syntax?
235 Why are there two different ways to invoke slicing? The first syntax
236 $x(args) doesn't work with chained method calls. E.g.
237 $x->xchg(0,1)(0);
239 won't work. It can only be used directly following a valid perl
241 variable name. Instead, use the default method syntax in such cases:
242 $x->transpose->(0);
244 Similarly, if you have a list of ndarrays @pdls:
246 $y = $pdls[5]->(0:-1);
248 The argument list
250 The argument list is a comma separated list. Each argument specifies
251 how the corresponding dimension in the ndarray is sliced. In contrast
252 to usage of the "slice" in PDL::Slices method the arguments should not
253 be quoted. Rather freely mix literals (1,3,etc), perl variables and
254 function invocations, e.g.
255 $x($pos-1:$end,myfunc(1,3)) .= 5;
257 There can even be other slicing commands in the arglist:
259 $x(0:-1:$pdl($step)) *= 2;
261 NOTE: If you use function calls in the arglist make sure that you use
263 parentheses around their argument lists. Otherwise the source filter
264 will get confused since it splits the argument list on commas that are
265 not protected by parentheses. Take the following example:
266 sub myfunc { return 5*$_[0]+$_[1] }
268 $x = sequence 10;
269 $sl = $x(0:myfunc 1, 2);
270 print $sl;
271 PDL barfed: Error in slice:Too many dims in slice
272 Caught at file /usr/local/bin/perldl, line 232, pkg main
273 The simple fix is
275 $sl = $x(0:myfunc(1, 2));
277 print $sl;
278 [0 1 2 3 4 5 6 7]
279 Note that using prototypes in the definition of myfunc does not help.
281 At this stage the source filter is simply not intelligent enough to
282 make use of this information. So beware of this subtlety.
283 Another pitfall to be aware of: currently, you can't use the
285 conditional operator in slice expressions (i.e., "?:", since the parser
286 confuses them with ranges). For example, the following will cause an
287 error:
288 $x = sequence 10;
290 $y = rand > 0.5 ? 0 : 1; # this one is ok
291 print $x($y ? 1 : 2); # error !
292 syntax error at (eval 59) line 3, near "1,
293 For the moment, just try to stay clear of the conditional operator in
295 slice expressions (or provide us with a patch to the parser to resolve
296 this issue ;).
297 Modifiers
299 Following a suggestion originally put forward by Karl Glazebrook the
300 latest versions of "PDL::NiceSlice" implement modifiers in slice
301 expressions. Modifiers are convenient shorthands for common variations
302 on PDL slicing. The general syntax is
303 $pdl(<slice>;<modifier>)
305 Four modifiers are currently implemented:
307 • "_" : flatten the ndarray before applying the slice expression.
309 Here is an example
310 $y = sequence 3, 3;
312 print $y(0:-2;_); # same as $y->flat->(0:-2)
313 [0 1 2 3 4 5 6 7]
314 which is quite different from the same slice expression without the
316 modifier
317 print $y(0:-2);
319 [
320 [0 1]
321 [3 4]
322 [6 7]
323 ]
324 • "|" : sever the link to the ndarray, e.g.
326 $x = sequence 10;
328 $y = $x(0:2;|)++; # same as $x(0:2)->sever++
329 print $y;
330 [1 2 3]
331 print $x; # check if $x has been modified
332 [0 1 2 3 4 5 6 7 8 9]
333 • "?" : short hand to indicate that this is really a where expression
335 As expressions like
337 $x->where($x>5)
339 are used very often you can write that shorter as
341 $x($x>5;?)
343 With the "?"-modifier the expression preceding the modifier is not
345 really a slice expression (e.g. ranges are not allowed) but rather
346 an expression as required by the where method. For example, the
347 following code will raise an error:
348 $x = sequence 10;
350 print $x(0:3;?);
351 syntax error at (eval 70) line 3, near "0:"
352 That's about all there is to know about this one.
354 • "-" : squeeze out any singleton dimensions. In less technical
356 terms: reduce the number of dimensions (potentially) by deleting
357 all dims of size 1. It is equivalent to doing a reshape(-1). That
358 can be very handy if you want to simplify the results of slicing
359 operations:
360 $x = ones 3, 4, 5;
362 $y = $x(1,0;-); # easier to type than $x((1),(0))
363 print $y->info;
364 PDL: Double D [5]
365 It also provides a unique opportunity to have smileys in your code!
367 Yes, PDL gives new meaning to smileys.
368 Combining modifiers
370 Several modifiers can be used in the same expression, e.g.
371 $c = $x(0;-|); # squeeze and sever
373 Other combinations are just as useful, e.g. ";_|" to flatten and sever.
375 The sequence in which modifiers are specified is not important.
376 A notable exception is the "where" modifier ("?") which must not be
378 combined with other flags (let me know if you see a good reason to
379 relax this rule).
380 Repeating any modifier will raise an error:
382 $c = $x(-1:1;|-|); # will cause error
384 NiceSlice error: modifier | used twice or more
385 Modifiers are still a new and experimental feature of "PDL::NiceSlice".
387 I am not sure how many of you are actively using them. Please do so and
388 experiment with the syntax. I think modifiers are very useful and make
389 life a lot easier. Feedback is welcome as usual. The modifier syntax
390 will likely be further tuned in the future but we will attempt to
391 ensure backwards compatibility whenever possible.
392 Argument formats
394 In slice expressions you can use ranges and secondly, ndarrays as 1D
395 index lists (although compare the description of the "?"-modifier above
396 for an exception).
397 • ranges
399 You can access ranges using the usual ":" separated format:
401 $x($start:$stop:$step) *= 4;
403 Note that you can omit the trailing step which then defaults to 1.
405 Double colons ("::") are not allowed to avoid clashes with Perl's
406 namespace syntax. So if you want to use steps different from the
407 default you have to also at least specify the stop position.
408 Examples:
409 $x(::2); # this won't work (in the way you probably intended)
411 $x(:-1:2); # this will select every 2nd element in the 1st dim
412 Just as with "slice" in PDL::Slices negative indices count from the
414 end of the dimension backwards with -1 being the last element. If the
415 start index is larger than the stop index the resulting ndarray will
416 have the elements in reverse order between these limits:
417 print $x(-2:0:2);
419 [8 6 4 2 0]
420 A single index just selects the given index in the slice
422 print $x(5);
424 [5]
425 Note, however, that the corresponding dimension is not removed from
427 the resulting ndarray but rather reduced to size 1:
428 print $x(5)->info
430 PDL: Double D [1]
431 If you want to get completely rid of that dimension enclose the index
433 in parentheses (again similar to the "slice" in PDL::Slices syntax):
434 print $x((5));
436 5
437 In this particular example a 0D ndarray results. Note that this
439 syntax is only allowed with a single index. All these will be errors:
440 print $x((0,4)); # will work but not in the intended way
442 print $x((0:4)); # compile time error
443 An empty argument selects the whole dimension, in this example all of
445 the first dimension:
446 print $x(,(0));
448 Alternative ways to select a whole dimension are
450 $x = sequence 5, 5;
452 print $x(:,(0));
453 print $x(0:-1,(0));
454 print $x(:-1,(0));
455 print $x(0:,(0));
456 Arguments for trailing dimensions can be omitted. In that case these
458 dimensions will be fully kept in the sliced ndarray:
459 $x = random 3,4,5;
461 print $x->info;
462 PDL: Double D [3,4,5]
463 print $x((0))->info;
464 PDL: Double D [4,5]
465 print $x((0),:,:)->info; # a more explicit way
466 PDL: Double D [4,5]
467 print $x((0),,)->info; # similar
468 PDL: Double D [4,5]
469 • dummy dimensions
471 As in "slice" in PDL::Slices, you can insert a dummy dimension by
473 preceding a single index argument with '*'. A lone '*' inserts a
474 dummy dimension of order 1; a '*' followed by a number inserts a
475 dummy dimension of that order.
476 • ndarray index lists
478 The second way to select indices from a dimension is via 1D ndarrays
480 of indices. A simple example:
481 $x = random 10;
483 $idx = long 3,4,7,0;
484 $y = $x($idx);
485 This way of selecting indices was previously only possible using
487 "dice" in PDL::Slices ("PDL::NiceSlice" attempts to unify the "slice"
488 and "dice" interfaces). Note that the indexing ndarrays must be 1D or
489 0D. Higher dimensional ndarrays as indices will raise an error:
490 $x = sequence 5, 5;
492 $idx2 = ones 2,2;
493 $sum = $x($idx2)->sum;
494 ndarray must be <= 1D at /home/XXXX/.perldlrc line 93
495 Note that using index ndarrays is not as efficient as using ranges.
497 If you can represent the indices you want to select using a range use
498 that rather than an equivalent index ndarray. In particular, memory
499 requirements are increased with index ndarrays (and execution time
500 may be longer). That said, if an index ndarray is the way to go use
501 it!
502 As you might have expected ranges and index ndarrays can be freely
504 mixed in slicing expressions:
505 $x = random 5, 5;
507 $y = $x(-1:2,pdl(3,0,1));
508 ndarrays as indices in ranges
510 You can use ndarrays to specify indices in ranges. No need to turn them
511 into proper perl scalars with the new slicing syntax. However, make
512 sure they contain not more than one element! Otherwise a runtime error
513 will be triggered. First a couple of examples that illustrate proper
514 usage:
515 $x = sequence 5, 5;
517 $rg = pdl(1,-1,3);
518 print $x($rg(0):$rg(1):$rg(2),2);
519 [
520 [11 14]
521 ]
522 print $x($rg+1,:$rg(0));
523 [
524 [2 0 4]
525 [7 5 9]
526 ]
527 The next one raises an error
529 print $x($rg+1,:$rg(0:1));
531 multielement ndarray where only one allowed at XXX/Core.pm line 1170.
532 The problem is caused by using the 2-element ndarray $rg(0:1) as the
534 stop index in the second argument ":$rg(0:1)" that is interpreted as a
535 range by "PDL::NiceSlice". You can use multielement ndarrays as index
536 ndarrays as described above but not in ranges. And "PDL::NiceSlice"
537 treats any expression with unprotected ":"'s as a range. Unprotected
538 means as usual "not occurring between matched parentheses".
539
541 "PDL::NiceSlice" exploits the ability of Perl to use source filtering
542 (see also perlfilter). A source filter basically filters (or rewrites)
543 your perl code before it is seen by the compiler. "PDL::NiceSlice"
544 searches through your Perl source code and when it finds the new
545 slicing syntax it rewrites the argument list appropriately and splices
546 a call to the "slice" method using the modified arg list into your perl
547 code. You can see how this works in the perldl or pdl2 shells by
548 switching on reporting (see above how to do that).
549
551 Conditional operator
552 The conditional operator can't be used in slice expressions (see
553 above).
554 The "DATA" file handle
556 Note: To avoid clobbering the "DATA" filehandle "PDL::NiceSlice"
557 switches itself off when encountering the "__END__" or "__DATA__"
558 tokens. This should not be a problem for you unless you use
559 "SelfLoader" to load PDL code including the new slicing from that
560 section. It is even desirable when working with Inline::Pdlpp, see
561 below.
562 Possible interaction with Inline::Pdlpp
564 There is currently an undesired interaction between "PDL::NiceSlice"
565 and Inline::Pdlpp. Since PP code generally contains expressions of the
566 type $var() (to access ndarrays, etc) "PDL::NiceSlice" recognizes those
567 incorrectly as slice expressions and does its substitutions. This is
568 not a problem if you use the "DATA" section for your Pdlpp code -- the
569 recommended place for Inline code anyway. In that case "PDL::NiceSlice"
570 will have switched itself off before encountering any Pdlpp code (see
571 above):
572 # use with Inline modules
574 use PDL;
575 use PDL::NiceSlice;
576 use Inline Pdlpp;
577 $x = sequence(10);
579 print $x(0:5);
580 __END__
582 __Pdlpp__
584 ... inline stuff
586 Otherwise switch "PDL::NiceSlice" explicitly off around the
588 Inline::Pdlpp code:
589 use PDL::NiceSlice;
591 $x = sequence 10;
593 $x(0:3)++;
594 $x->inc;
595 no PDL::NiceSlice; # switch off before Pdlpp code
597 use Inline Pdlpp => "Pdlpp source code";
598 The cleaner solution is to always stick with the "DATA" way of
600 including your "Inline" code as in the first example. That way you keep
601 your nice Perl code at the top and all the ugly Pdlpp stuff etc at the
602 bottom.
603 Bug reports
605 Feedback and bug reports are welcome. Please include an example that
606 demonstrates the problem. Log bug reports in the PDL issues tracker at
607 <https://github.com/PDLPorters/pdl/issues> or send them to the pdl-
608 devel mailing list (see <http://pdl.perl.org/?page=mailing-lists>).
609
611 Copyright (c) 2001, 2002 Christian Soeller. All Rights Reserved. This
612 module is free software. It may be used, redistributed and/or modified
613 under the same terms as PDL itself (see <http://pdl.perl.org>).
614perl v5.38.0 2023-07-21 NiceSlice(3)