1Basic(3) User Contributed Perl Documentation Basic(3)
2
6 PDL::Basic -- Basic utility functions for PDL
7
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
15 use PDL::Basic;
16
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 CAVEAT:
24 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 $x = xvals($somearray);
31 $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
32 $x = xvals([OPTIONAL TYPE], $somarray->dims);
33 etc. see zeroes.
35 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 yvals
51 Fills an ndarray with Y index values. See the CAVEAT for "xvals".
52 $x = yvals($somearray); yvals(inplace($somearray));
54 $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);
55 etc. see zeroes.
57 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 zvals
73 Fills an ndarray with Z index values. See the CAVEAT for "xvals".
74 $x = zvals($somearray); zvals(inplace($somearray));
76 $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);
77 etc. see zeroes.
79 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 xlinvals
97 X axis values between endpoints (see "xvals").
98 $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 "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 ylinvals
111 Y axis values between endpoints (see "yvals").
112 See "xlinvals" for more information.
114 zlinvals
116 Z axis values between endpoints (see "zvals").
117 See "xlinvals" for more information.
119 xlogvals
121 X axis values logarithmically spaced between endpoints (see "xvals").
122 $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 "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 ylogvals
135 Y axis values logarithmically spaced between endpoints (see "yvals").
136 See "xlogvals" for more information.
138 zlogvals
140 Z axis values logarithmically spaced between endpoints (see "zvals").
141 See "xlogvals" for more information.
143 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 $indices = allaxisvals($pdl);
151 $indices = allaxisvals(@dimlist);
152 $indices = allaxisvals($type,@dimlist);
153 ndcoords
155 Enumerate pixel coordinates for an N-D ndarray
156 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 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 $indices = ndcoords($pdl);
170 $indices = ndcoords(@dimlist);
171 $indices = ndcoords($type,@dimlist);
172 pdl> print ndcoords(2,3)
174 [
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 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 hist
199 Create histogram of an ndarray
200 $hist = hist($data);
202 ($xvals,$hist) = hist($data);
203 or
205 $hist = hist($data,$min,$max,$step);
207 ($xvals,$hist) = hist($data,[$min,$max,$step]);
208 If "hist" is run in list context, $xvals gives the computed bin centres
210 as double values.
211 A nice idiom (with PDL::Graphics::PGPLOT) is
213 bin hist $data; # Plot histogram
215 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 whist
223 Create a weighted histogram of an ndarray
224 $hist = whist($data, $wt, [$min,$max,$step]);
226 ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
227 If requested, $xvals gives the computed bin centres as type double
229 values. $data and $wt should have the same dimensionality and extents.
230 A nice idiom (with PDL::Graphics::PGPLOT) is
232 bin whist $data, $wt; # Plot histogram
234 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 sequence
243 Create array filled with a sequence of values
244 $w = sequence($y); $w = sequence [OPTIONAL TYPE], @dims;
246 etc. see zeroes.
248 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 rvals
260 Fills an ndarray with radial distance values from some centre.
261 $r = rvals $ndarray,{OPTIONS};
263 $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
264 Options:
266 Centre => [$x,$y,$z...] # Specify centre
268 Center => [$x,$y.$z...] # synonym.
269 Squared => 1 # return distance squared (i.e., don't take the square root)
271 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 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 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 For a more general metric, one can define, e.g.,
296 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 so now
307 distance($w, $centre, \&euclid);
309 will emulate rvals, while "\&l1" and "\&linfty" will generate other
311 well-known norms.
312 axisvals
314 Fills an ndarray with index values on Nth dimension
315 $z = axisvals ($ndarray, $nth);
317 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 See also "allaxisvals", which generates all axis values simultaneously
323 in a form useful for "range", "interpND", "indexND", etc.
324 Note the 'from specification' style (see zeroes) is not available here,
326 for obvious reasons.
327 transpose
329 transpose rows and columns.
330 $y = transpose($w);
332 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 ]
345perl v5.36.0 2022-07-22 Basic(3)