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

NAME

6       PDL::Basic -- Basic utility functions for PDL
7

DESCRIPTION

9       This module contains basic utility functions for creating and
10       manipulating piddles. Most of these functions are simplified interfaces
11       to the more flexible functions in the modules PDL::Primitive and
12       PDL::Slices.
13

SYNOPSIS

15        use PDL::Basic;
16

FUNCTIONS

18   xvals
19       Fills a piddle with X index values.  Uses similar specifications to
20       "zeroes" and "new_from_specification".
21
22       CAVEAT:
23
24       If you use the single argument piddle form (top row in the usage table)
25       the output will have the same type as the input; this may give
26       surprising results if, e.g., you have a byte array with a dimension of
27       size greater than 256.  To force a type, use the third form.
28
29        $x = xvals($somearray);
30        $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
31        $x = xvals([OPTIONAL TYPE], $somarray->dims);
32
33       etc. see zeroes.
34
35         pdl> print xvals zeroes(5,10)
36         [
37          [0 1 2 3 4]
38          [0 1 2 3 4]
39          [0 1 2 3 4]
40          [0 1 2 3 4]
41          [0 1 2 3 4]
42          [0 1 2 3 4]
43          [0 1 2 3 4]
44          [0 1 2 3 4]
45          [0 1 2 3 4]
46          [0 1 2 3 4]
47         ]
48
49   yvals
50       Fills a piddle with Y index values.  See the CAVEAT for "xvals".
51
52        $x = yvals($somearray); yvals(inplace($somearray));
53        $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);
54
55       etc. see zeroes.
56
57        pdl> print yvals zeroes(5,10)
58        [
59         [0 0 0 0 0]
60         [1 1 1 1 1]
61         [2 2 2 2 2]
62         [3 3 3 3 3]
63         [4 4 4 4 4]
64         [5 5 5 5 5]
65         [6 6 6 6 6]
66         [7 7 7 7 7]
67         [8 8 8 8 8]
68         [9 9 9 9 9]
69        ]
70
71   zvals
72       Fills a piddle with Z index values.  See the CAVEAT for "xvals".
73
74        $x = zvals($somearray); zvals(inplace($somearray));
75        $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);
76
77       etc. see zeroes.
78
79        pdl> print zvals zeroes(3,4,2)
80        [
81         [
82          [0 0 0]
83          [0 0 0]
84          [0 0 0]
85          [0 0 0]
86         ]
87         [
88          [1 1 1]
89          [1 1 1]
90          [1 1 1]
91          [1 1 1]
92         ]
93        ]
94
95   xlinvals
96       X axis values between endpoints (see "xvals").
97
98        $w = zeroes(100,100);
99        $x = $w->xlinvals(0.5,1.5);
100        $y = $w->ylinvals(-2,-1);
101        # calculate Z for X between 0.5 and 1.5 and
102        # Y between -2 and -1.
103        $z = f($x,$y);
104
105       "xlinvals", "ylinvals" and "zlinvals" return a piddle with the same
106       shape as their first argument and linearly scaled values between the
107       two other arguments along the given axis.
108
109   ylinvals
110       Y axis values between endpoints (see "yvals").
111
112       See "xlinvals" for more information.
113
114   zlinvals
115       Z axis values between endpoints (see "zvals").
116
117       See "xlinvals" for more information.
118
119   xlogvals
120       X axis values logarithmically spaced between endpoints (see "xvals").
121
122        $w = zeroes(100,100);
123        $x = $w->xlogvals(1e-6,1e-3);
124        $y = $w->ylinvals(1e-4,1e3);
125        # calculate Z for X between 1e-6 and 1e-3 and
126        # Y between 1e-4 and 1e3.
127        $z = f($x,$y);
128
129       "xlogvals", "ylogvals" and "zlogvals" return a piddle with the same
130       shape as their first argument and logarithmically scaled values between
131       the two other arguments along the given axis.
132
133   ylogvals
134       Y axis values logarithmically spaced between endpoints (see "yvals").
135
136       See "xlogvals" for more information.
137
138   zlogvals
139       Z axis values logarithmically spaced between endpoints (see "zvals").
140
141       See "xlogvals" for more information.
142
143   allaxisvals
144       Synonym for "ndcoords" - enumerates all coordinates in a PDL or dim
145       list, adding an extra dim on the front to accommodate the vector
146       coordinate index (the form expected by "indexND", "range", and
147       "interpND").  See "ndcoords" for more detail.
148
149       $indices = allaxisvals($pdl); $indices = allaxisvals(@dimlist);
150       $indices = allaxisvals($type,@dimlist);
151
152   ndcoords
153       Enumerate pixel coordinates for an N-D piddle
154
155       Returns an enumerated list of coordinates suitable for use in indexND
156       or range: you feed in a dimension list and get out a piddle whose 0th
157       dimension runs over dimension index and whose 1st through Nth
158       dimensions are the dimensions given in the input.  If you feed in a
159       piddle instead of a perl list, then the dimension list is used, as in
160       "xvals" etc.
161
162       Unlike "xvals" etc., if you supply a piddle input, you get out a piddle
163       of the default piddle type: double.   This causes less surprises than
164       the previous default of keeping the data type of the input piddle since
165       that rarely made sense in most usages.
166
167       $indices = ndcoords($pdl); $indices = ndcoords(@dimlist); $indices =
168       ndcoords($type,@dimlist);
169
170         pdl> print ndcoords(2,3)
171
172         [
173          [
174           [0 0]
175           [1 0]
176          ]
177          [
178           [0 1]
179           [1 1]
180          ]
181          [
182           [0 2]
183           [1 2]
184          ]
185         ]
186
187         pdl> $w = zeroes(byte,2,3);        # $w is a 2x3 byte piddle
188         pdl> $y = ndcoords($w);            # $y inherits $w's type
189         pdl> $c = ndcoords(long,$w->dims); # $c is a long piddle, same dims as $y
190         pdl> help $y;
191         This variable is   Byte D [2,2,3]              P            0.01Kb
192         pdl> help $c;
193         This variable is   Long D [2,2,3]              P            0.05Kb
194
195   hist
196       Create histogram of a piddle
197
198        $hist = hist($data);
199        ($xvals,$hist) = hist($data);
200
201       or
202
203        $hist = hist($data,$min,$max,$step);
204        ($xvals,$hist) = hist($data,[$min,$max,$step]);
205
206       If "hist" is run in list context, $xvals gives the computed bin centres
207       as double values.
208
209       A nice idiom (with PDL::Graphics::PGPLOT) is
210
211        bin hist $data;  # Plot histogram
212
213        pdl> p $y
214        [13 10 13 10 9 13 9 12 11 10 10 13 7 6 8 10 11 7 12 9 11 11 12 6 12 7]
215        pdl> $h = hist $y,0,20,1; # hist with step 1, min 0 and 20 bins
216        pdl> p $h
217        [0 0 0 0 0 0 2 3 1 3 5 4 4 4 0 0 0 0 0 0]
218
219   whist
220       Create a weighted histogram of a piddle
221
222        $hist = whist($data, $wt, [$min,$max,$step]);
223        ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
224
225       If requested, $xvals gives the computed bin centres as type double
226       values.  $data and $wt should have the same dimensionality and extents.
227
228       A nice idiom (with PDL::Graphics::PGPLOT) is
229
230        bin whist $data, $wt;  # Plot histogram
231
232        pdl> p $y
233        [13 10 13 10 9 13 9 12 11 10 10 13 7 6 8 10 11 7 12 9 11 11 12 6 12 7]
234        pdl> $wt = grandom($y->nelem)
235        pdl> $h = whist $y, $wt, 0, 20, 1 # hist with step 1, min 0 and 20 bins
236        pdl> p $h
237        [0 0 0 0 0 0 -0.49552342  1.7987439 0.39450696  4.0073722 -2.6255299 -2.5084501  2.6458365  4.1671676 0 0 0 0 0 0]
238
239   sequence
240       Create array filled with a sequence of values
241
242        $w = sequence($y); $w = sequence [OPTIONAL TYPE], @dims;
243
244       etc. see zeroes.
245
246        pdl> p sequence(10)
247        [0 1 2 3 4 5 6 7 8 9]
248        pdl> p sequence(3,4)
249        [
250         [ 0  1  2]
251         [ 3  4  5]
252         [ 6  7  8]
253         [ 9 10 11]
254        ]
255
256   rvals
257       Fills a piddle with radial distance values from some centre.
258
259        $r = rvals $piddle,{OPTIONS};
260        $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
261
262        Options:
263
264        Centre => [$x,$y,$z...] # Specify centre
265        Center => [$x,$y.$z...] # synonym.
266
267        Squared => 1 # return distance squared (i.e., don't take the square root)
268
269        pdl> print rvals long,7,7,{Centre=>[2,2]}
270        [
271         [2 2 2 2 2 3 4]
272         [2 1 1 1 2 3 4]
273         [2 1 0 1 2 3 4]
274         [2 1 1 1 2 3 4]
275         [2 2 2 2 2 3 4]
276         [3 3 3 3 3 4 5]
277         [4 4 4 4 4 5 5]
278        ]
279
280       If "Center" is not specified, the midpoint for a given dimension of
281       size "N" is given by " int(N/2) " so that the midpoint always falls on
282       an exact pixel point in the data.  For dimensions of even size, that
283       means the midpoint is shifted by 1/2 pixel from the true center of that
284       dimension.
285
286       Also note that the calculation for "rvals" for integer values does not
287       promote the datatype so you will have wraparound when the value
288       calculated for " r**2 " is greater than the datatype can hold.  If you
289       need exact values, be sure to use large integer or floating point
290       datatypes.
291
292       For a more general metric, one can define, e.g.,
293
294        sub distance {
295          my ($w,$centre,$f) = @_;
296          my ($r) = $w->allaxisvals-$centre;
297          $f->($r);
298        }
299        sub l1 { sumover(abs($_[0])); }
300        sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); }
301        sub linfty { maximum(abs($_[0])); }
302
303       so now
304
305        distance($w, $centre, \&euclid);
306
307       will emulate rvals, while "\&l1" and "\&linfty" will generate other
308       well-known norms.
309
310   axisvals
311       Fills a piddle with index values on Nth dimension
312
313        $z = axisvals ($piddle, $nth);
314
315       This is the routine, for which "xvals", "yvals" etc are mere
316       shorthands. "axisvals" can be used to fill along any dimension, using a
317       parameter.
318
319       See also "allaxisvals", which generates all axis values simultaneously
320       in a form useful for "range", "interpND", "indexND", etc.
321
322       Note the 'from specification' style (see zeroes) is not available here,
323       for obvious reasons.
324
325   transpose
326       transpose rows and columns.
327
328        $y = transpose($w);
329
330        pdl> $w = sequence(3,2)
331        pdl> p $w
332        [
333         [0 1 2]
334         [3 4 5]
335        ]
336        pdl> p transpose( $w )
337        [
338         [0 3]
339         [1 4]
340         [2 5]
341        ]
342
343
344
345perl v5.32.1                      2021-02-15                          Basic(3)
Impressum