1NiceSlice(3)          User Contributed Perl Documentation         NiceSlice(3)
2
3
4

NAME

6       PDL::NiceSlice - toward a nicer slicing syntax for PDL
7

SYNOPSIS

9         use PDL::NiceSlice;
10
11         $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
15         $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
21         $y = $x(*3);              # Add dummy dimension of order 3
22
23         # 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

DESCRIPTION

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
39       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

Use in scripts and "perldl" or "pdl2" shell

47       The new slicing syntax can be switched on and off in scripts and perl
48       modules by using or unloading "PDL::NiceSlice".
49
50       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
56       Here is an example:
57
58         use PDL::NiceSlice;
59
60         # this code will be translated
61         # and you can use the new slicing syntax
62
63         no PDL::NiceSlice;
64
65         # this code won't
66         # and the new slicing syntax will raise errors!
67
68       See also Filter::Simple and example in this distribution for further
69       examples.
70
71       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
76          # start test0.pl
77          use PDL;
78          use PDL::NiceSlice;
79
80          $x = sequence 10;
81          print $x(0:4),"\n";
82
83          require 'test1.pl';
84          # end test0.pl
85
86       that "require"s a second file test1.pl
87
88          # begin test1.pl
89          $aa = sequence 11;
90          print $aa(0:7),"\n";
91          1;
92          # end test1.pl
93
94       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
100         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
105       This can be fixed by adding the line
106
107         use PDL::NiceSlice;
108
109       "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
112          # 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
119       Now things proceed more smoothly
120
121         perl test0.pl
122        [0 1 2 3 4]
123        [0 1 2 3 4 5 6 7]
124
125       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
130   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
134         $x = sequence 10;
135         eval << 'EOE';
136
137         use PDL::NiceSlice;
138         $y = $x(0:5);
139
140         EOE
141         print $y;
142
143       Instead say:
144
145         use PDL::NiceSlice;
146         $x = sequence 10;
147         eval << 'EOE';
148
149         $y = $x(0:5);
150
151         EOE
152         print $y;
153
154       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

The new slicing syntax

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
162         $pdl->slice(....);
163
164       calls, etc. Instead, "PDL::NiceSlice" introduces two ways in which to
165       slice ndarrays without too much typing:
166
167       • using parentheses directly following a scalar variable name, for
168         example
169
170            $c = $y(0:-3:4,(0));
171
172       • 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
177           $c = $b[0]->(0:-3:4,(0));
178
179       The format of the argument list is the same for both types of
180       invocation and will be explained in more detail below.
181
182   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
187         $x(1:4) .= 2;         # only use this syntax on ndarrays
188         $sum += $x(,(1));
189
190       However, if the variable name is immediately preceded by a "&", for
191       example
192
193         &$x(4,5);
194
195       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
199       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
208   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
213         $x->transpose->(($pos)) .= 0;
214
215       Note that this conflicts with the use of normal code references, since
216       you can write in plain Perl
217
218         $sub = sub { print join ',', @_ };
219         $sub->(1,'a');
220
221       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
228       This shouldn't be a major problem in practice; a simple workaround is
229       to use the "&"-way of calling subrefs, e.g.:
230
231         $sub = sub { print join ',', @_ };
232         &$sub(1,'a');
233
234   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
238         $x->xchg(0,1)(0);
239
240       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
243         $x->transpose->(0);
244
245       Similarly, if you have a list of ndarrays @pdls:
246
247         $y = $pdls[5]->(0:-1);
248
249   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
256         $x($pos-1:$end,myfunc(1,3)) .= 5;
257
258       There can even be other slicing commands in the arglist:
259
260         $x(0:-1:$pdl($step)) *= 2;
261
262       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
267         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
274       The simple fix is
275
276         $sl = $x(0:myfunc(1, 2));
277         print $sl;
278        [0 1 2 3 4 5 6 7]
279
280       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
284       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
289         $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
294       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
298   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
304           $pdl(<slice>;<modifier>)
305
306       Four modifiers are currently implemented:
307
308       •   "_" : flatten the ndarray before applying the slice expression.
309           Here is an example
310
311              $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
315           which is quite different from the same slice expression without the
316           modifier
317
318              print $y(0:-2);
319            [
320             [0 1]
321             [3 4]
322             [6 7]
323            ]
324
325       •   "|" : sever the link to the ndarray, e.g.
326
327              $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
334       •   "?" : short hand to indicate that this is really a where expression
335
336           As expressions like
337
338             $x->where($x>5)
339
340           are used very often you can write that shorter as
341
342             $x($x>5;?)
343
344           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
349             $x = sequence 10;
350             print $x(0:3;?);
351            syntax error at (eval 70) line 3, near "0:"
352
353           That's about all there is to know about this one.
354
355       •   "-" : 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
361             $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
366           It also provides a unique opportunity to have smileys in your code!
367           Yes, PDL gives new meaning to smileys.
368
369   Combining modifiers
370       Several modifiers can be used in the same expression, e.g.
371
372         $c = $x(0;-|); # squeeze and sever
373
374       Other combinations are just as useful, e.g. ";_|" to flatten and sever.
375       The sequence in which modifiers are specified is not important.
376
377       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
381       Repeating any modifier will raise an error:
382
383         $c = $x(-1:1;|-|); # will cause error
384        NiceSlice error: modifier | used twice or more
385
386       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
393   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
398       • ranges
399
400         You can access ranges using the usual ":" separated format:
401
402           $x($start:$stop:$step) *= 4;
403
404         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
410           $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
413         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
418           print $x(-2:0:2);
419          [8 6 4 2 0]
420
421         A single index just selects the given index in the slice
422
423           print $x(5);
424          [5]
425
426         Note, however, that the corresponding dimension is not removed from
427         the resulting ndarray but rather reduced to size 1:
428
429           print $x(5)->info
430          PDL: Double D [1]
431
432         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
435           print $x((5));
436          5
437
438         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
441           print $x((0,4));  # will work but not in the intended way
442           print $x((0:4));  # compile time error
443
444         An empty argument selects the whole dimension, in this example all of
445         the first dimension:
446
447           print $x(,(0));
448
449         Alternative ways to select a whole dimension are
450
451           $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
457         Arguments for trailing dimensions can be omitted. In that case these
458         dimensions will be fully kept in the sliced ndarray:
459
460           $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
470       • dummy dimensions
471
472         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
477       • ndarray index lists
478
479         The second way to select indices from a dimension is via 1D ndarrays
480         of indices. A simple example:
481
482           $x = random 10;
483           $idx = long 3,4,7,0;
484           $y = $x($idx);
485
486         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
491           $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
496         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
503       As you might have expected ranges and index ndarrays can be freely
504       mixed in slicing expressions:
505
506         $x = random 5, 5;
507         $y = $x(-1:2,pdl(3,0,1));
508
509   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
516         $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
528       The next one raises an error
529
530         print $x($rg+1,:$rg(0:1));
531        multielement ndarray where only one allowed at XXX/Core.pm line 1170.
532
533       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

IMPLEMENTATION

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

BUGS

551   Conditional operator
552       The conditional operator can't be used in slice expressions (see
553       above).
554
555   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
563   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
573           # use with Inline modules
574         use PDL;
575         use PDL::NiceSlice;
576         use Inline Pdlpp;
577
578         $x = sequence(10);
579         print $x(0:5);
580
581         __END__
582
583         __Pdlpp__
584
585         ... inline stuff
586
587       Otherwise switch "PDL::NiceSlice" explicitly off around the
588       Inline::Pdlpp code:
589
590         use PDL::NiceSlice;
591
592         $x = sequence 10;
593         $x(0:3)++;
594         $x->inc;
595
596         no PDL::NiceSlice; # switch off before Pdlpp code
597         use Inline Pdlpp => "Pdlpp source code";
598
599       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
604   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>).
614
615
616
617perl v5.38.0                      2023-07-21                      NiceSlice(3)
Impressum