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 ndarrays. Most of these functions are simplified
11       interfaces to the more flexible functions in the modules PDL::Primitive
12       and PDL::Slices.
13

SYNOPSIS

15        use PDL::Basic;
16

FUNCTIONS

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