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 perldl> 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 perldl> 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 perldl> 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 $a = zeroes(100,100);
99 $x = $a->xlinvals(0.5,1.5);
100 $y = $a->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 logarithmicly spaced between endpoints (see xvals).
121 $a = zeroes(100,100);
123 $x = $a->xlogvals(1e-6,1e-3);
124 $y = $a->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 logarithmicly scaled values between
131 the two other arguments along the given axis.
132 ylogvals
134 Y axis values logarithmicly spaced between endpoints (see yvals).
135 See xlogvals for more information.
137 zlogvals
139 Z axis values logarithmicly 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 list,
145 adding an extra dim on the front to accomodate the vector coordinate
146 index (the form expected by indexND, range, and interpND). See
147 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 As with xvals etc., if you supply a piddle input, you get out a piddle
163 of the same type. This could yield surprising results if you feed in
164 (e.g.) a byte array with a dimension of size greater than 256. To
165 force a type, you should always fall back on the ($type,@dimlist) form;
166 see the example below.
167 $indices = ndcoords($pdl); $indices = ndcoords(@dimlist); $indices =
169 ndcoords($type,@dimlist);
170 perldl> print ndcoords(2,3)
172 [
173 [
174 [0 0]
175 [1 0]
176 [2 0]
177 ]
178 [
179 [0 1]
180 [1 1]
181 [2 1]
182 ]
183 ]
184 perldl> $a = zeroes(byte,2,3); # $a is a 2x3 byte piddle
185 perldl> $b = ndcoords($a); # $b inherits $a's type
186 perldl> $c = ndcoords(long,$a->dims); # $c is a long piddle, same dims as $b
187 perldl> help $b;
188 This variable is Byte D [2,2,3] P 0.01Kb
189 perldl> help $c;
190 This variable is Long D [2,2,3] P 0.05Kb
191 hist
193 Create histogram of a piddle
194 $hist = hist($data,[$min,$max,$step]);
196 ($xvals,$hist) = hist($data,[$min,$max,$step]);
197 If requested, $xvals gives the computed bin centres
199 A nice idiom (with PDL::Graphics::PGPLOT) is
201 bin hist $data; # Plot histogram
203 perldl> p $y
205 [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]
206 perldl> $h = hist $y,0,20,1; # hist with step 1, min 0 and 20 bins
207 perldl> p $h
208 [0 0 0 0 0 0 2 3 1 3 5 4 4 4 0 0 0 0 0 0]
209 whist
211 Create a weighted histogram of a piddle
212 $hist = whist($data, $wt, [$min,$max,$step]);
214 ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
215 If requested, $xvals gives the computed bin centres. $data and $wt
217 should have the same dimensionality and extents.
218 A nice idiom (with PDL::Graphics::PGPLOT) is
220 bin whist $data, $wt; # Plot histogram
222 perldl> p $y
224 [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]
225 perldl> $wt = grandom($y->nelem)
226 perldl> $h = whist $y, $wt, 0, 20, 1 # hist with step 1, min 0 and 20 bins
227 perldl> p $h
228 [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]
229 sequence
231 Create array filled with a sequence of values
232 $a = sequence($b); $a = sequence [OPTIONAL TYPE], @dims;
234 etc. see zeroes.
236 perldl> p sequence(10)
238 [0 1 2 3 4 5 6 7 8 9]
239 perldl> p sequence(3,4)
240 [
241 [ 0 1 2]
242 [ 3 4 5]
243 [ 6 7 8]
244 [ 9 10 11]
245 ]
246 rvals
248 Fills a piddle with radial distance values from some centre.
249 $r = rvals $piddle,{OPTIONS};
251 $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
252 Options:
254 Centre => [$x,$y,$z...] # Specify centre
256 Center => [$x,$y.$z...] # synonym.
257 Squared => 1 # return distance squared (i.e., don't take the square root)
259 perldl> print rvals long,7,7,{Centre=>[2,2]}
261 [
262 [2 2 2 2 2 3 4]
263 [2 1 1 1 2 3 4]
264 [2 1 0 1 2 3 4]
265 [2 1 1 1 2 3 4]
266 [2 2 2 2 2 3 4]
267 [3 3 3 3 3 4 5]
268 [4 4 4 4 4 5 5]
269 ]
270 For a more general metric, one can define, e.g.,
272 sub distance {
274 my ($a,$centre,$f) = @_;
275 my ($r) = $a->allaxisvals-$centre;
276 $f->($r);
277 }
278 sub l1 { sumover(abs($_[0])); }
279 sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); }
280 sub linfty { maximum(abs($_[0])); }
281 so now
283 distance($a, $centre, \&euclid);
285 will emulate rvals, while "\&l1" and "\&linfty" will generate other
287 well-known norms.
288 axisvals
290 Fills a piddle with index values on Nth dimension
291 $z = axisvals ($piddle, $nth);
293 This is the routine, for which xvals, yvals etc are mere shorthands.
295 "axisvals" can be used to fill along any dimension, using a parameter.
296 See also allaxisvals, which generates all axis values simultaneously in
298 a form useful for range, interpND, indexND, etc.
299 Note the 'from specification' style (see zeroes) is not available here,
301 for obvious reasons.
302 transpose
304 transpose rows and columns.
305 $b = transpose($a);
307 perldl> $a = sequence(3,2)
309 perldl> p $a
310 [
311 [0 1 2]
312 [3 4 5]
313 ]
314 perldl> p transpose( $a )
315 [
316 [0 3]
317 [1 4]
318 [2 5]
319 ]
320perl v5.12.3 2009-10-24 Basic(3)