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 piddles. Most of these functions are simplified interfaces
11 to the more flexible functions in the modules PDL::Primitive and
12 PDL::Slices.
13
15 use PDL::Basic;
16
18 xvals
19 Fills a piddle with X index values. Uses similar specifications to
20 "zeroes" and "new_from_specification".
21 CAVEAT:
23 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 $x = xvals($somearray);
30 $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
31 $x = xvals([OPTIONAL TYPE], $somarray->dims);
32 etc. see zeroes.
34 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 yvals
50 Fills a piddle with Y index values. See the CAVEAT for "xvals".
51 $x = yvals($somearray); yvals(inplace($somearray));
53 $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);
54 etc. see zeroes.
56 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 zvals
72 Fills a piddle with Z index values. See the CAVEAT for "xvals".
73 $x = zvals($somearray); zvals(inplace($somearray));
75 $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);
76 etc. see zeroes.
78 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 xlinvals
96 X axis values between endpoints (see "xvals").
97 $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 "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 ylinvals
110 Y axis values between endpoints (see "yvals").
111 See "xlinvals" for more information.
113 zlinvals
115 Z axis values between endpoints (see "zvals").
116 See "xlinvals" for more information.
118 xlogvals
120 X axis values logarithmically spaced between endpoints (see "xvals").
121 $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 "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 ylogvals
134 Y axis values logarithmically spaced between endpoints (see "yvals").
135 See "xlogvals" for more information.
137 zlogvals
139 Z axis values logarithmically spaced between endpoints (see "zvals").
140 See "xlogvals" for more information.
142 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 $indices = allaxisvals($pdl); $indices = allaxisvals(@dimlist);
150 $indices = allaxisvals($type,@dimlist);
151 ndcoords
153 Enumerate pixel coordinates for an N-D piddle
154 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 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 $indices = ndcoords($pdl); $indices = ndcoords(@dimlist); $indices =
168 ndcoords($type,@dimlist);
169 pdl> print ndcoords(2,3)
171 [
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 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 hist
196 Create histogram of a piddle
197 $hist = hist($data);
199 ($xvals,$hist) = hist($data);
200 or
202 $hist = hist($data,$min,$max,$step);
204 ($xvals,$hist) = hist($data,[$min,$max,$step]);
205 If "hist" is run in list context, $xvals gives the computed bin centres
207 as double values.
208 A nice idiom (with PDL::Graphics::PGPLOT) is
210 bin hist $data; # Plot histogram
212 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 whist
220 Create a weighted histogram of a piddle
221 $hist = whist($data, $wt, [$min,$max,$step]);
223 ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
224 If requested, $xvals gives the computed bin centres as type double
226 values. $data and $wt should have the same dimensionality and extents.
227 A nice idiom (with PDL::Graphics::PGPLOT) is
229 bin whist $data, $wt; # Plot histogram
231 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 sequence
240 Create array filled with a sequence of values
241 $w = sequence($y); $w = sequence [OPTIONAL TYPE], @dims;
243 etc. see zeroes.
245 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 rvals
257 Fills a piddle with radial distance values from some centre.
258 $r = rvals $piddle,{OPTIONS};
260 $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
261 Options:
263 Centre => [$x,$y,$z...] # Specify centre
265 Center => [$x,$y.$z...] # synonym.
266 Squared => 1 # return distance squared (i.e., don't take the square root)
268 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 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 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 For a more general metric, one can define, e.g.,
293 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 so now
304 distance($w, $centre, \&euclid);
306 will emulate rvals, while "\&l1" and "\&linfty" will generate other
308 well-known norms.
309 axisvals
311 Fills a piddle with index values on Nth dimension
312 $z = axisvals ($piddle, $nth);
314 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 See also "allaxisvals", which generates all axis values simultaneously
320 in a form useful for "range", "interpND", "indexND", etc.
321 Note the 'from specification' style (see zeroes) is not available here,
323 for obvious reasons.
324 transpose
326 transpose rows and columns.
327 $y = transpose($w);
329 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 ]
342perl v5.32.1 2021-02-15 Basic(3)