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".
21 CAVEAT:
23 If you use the single argument ndarray form (top row in the usage
25 table) 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 an ndarray 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 an ndarray 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 an ndarray 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 an ndarray 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 ndarray
154 Returns an enumerated list of coordinates suitable for use in indexND
156 or range: you feed in a dimension list and get out an ndarray 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 an
159 ndarray instead of a perl list, then the dimension list is used, as in
160 "xvals" etc.
161 Unlike "xvals" etc., if you supply an ndarray input, you get out an
163 ndarray of the default ndarray type: double. This causes less
164 surprises than the previous default of keeping the data type of the
165 input ndarray since 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 ndarray
188 pdl> $y = ndcoords($w); # $y inherits $w's type
189 pdl> $c = ndcoords(long,$w->dims); # $c is a long ndarray, 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 an ndarray
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 an ndarray
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 an ndarray with radial distance values from some centre.
258 $r = rvals $ndarray,{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 an ndarray with index values on Nth dimension
312 $z = axisvals ($ndarray, $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.34.0 2021-08-16 Basic(3)