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

SYNOPSIS

15        use PDL::Basic;
16

FUNCTIONS

18       xvals
19
20       Fills a piddle with X index values
21
22        $x = xvals($somearray);
23        $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
24
25       etc. see zeroes.
26
27         perldl> print xvals zeroes(5,10)
28         [
29          [0 1 2 3 4]
30          [0 1 2 3 4]
31          [0 1 2 3 4]
32          [0 1 2 3 4]
33          [0 1 2 3 4]
34          [0 1 2 3 4]
35          [0 1 2 3 4]
36          [0 1 2 3 4]
37          [0 1 2 3 4]
38          [0 1 2 3 4]
39         ]
40
41       yvals
42
43       Fills a piddle with Y index values
44
45        $x = yvals($somearray); yvals(inplace($somearray));
46        $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);
47
48       etc. see zeroes.
49
50        perldl> print yvals zeroes(5,10)
51        [
52         [0 0 0 0 0]
53         [1 1 1 1 1]
54         [2 2 2 2 2]
55         [3 3 3 3 3]
56         [4 4 4 4 4]
57         [5 5 5 5 5]
58         [6 6 6 6 6]
59         [7 7 7 7 7]
60         [8 8 8 8 8]
61         [9 9 9 9 9]
62        ]
63
64       zvals
65
66       Fills a piddle with Z index values
67
68        $x = zvals($somearray); zvals(inplace($somearray));
69        $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);
70
71       etc. see zeroes.
72
73        perldl> print zvals zeroes(3,4,2)
74        [
75         [
76          [0 0 0]
77          [0 0 0]
78          [0 0 0]
79          [0 0 0]
80         ]
81         [
82          [1 1 1]
83          [1 1 1]
84          [1 1 1]
85          [1 1 1]
86         ]
87        ]
88
89       xlinvals
90
91       X axis values between endpoints (see xvals).
92
93        $a = zeroes(100,100);
94        $x = $a->xlinvals(0.5,1.5);
95        $y = $a->ylinvals(-2,-1);
96        # calculate Z for X between 0.5 and 1.5 and
97        # Y between -2 and -1.
98        $z = f($x,$y);
99
100       "xlinvals", "ylinvals" and "zlinvals" return a piddle with the same
101       shape as their first argument and linearly scaled values between the
102       two other arguments along the given axis.
103
104       ylinvals
105
106       Y axis values between endpoints (see yvals).
107
108       See xlinvals for more information.
109
110       zlinvals
111
112       Z axis values between endpoints (see zvals).
113
114       See xlinvals for more information.
115
116       xlogvals
117
118       X axis values logarithmicly spaced between endpoints (see xvals).
119
120        $a = zeroes(100,100);
121        $x = $a->xlogvals(1e-6,1e-3);
122        $y = $a->ylinvals(1e-4,1e3);
123        # calculate Z for X between 1e-6 and 1e-3 and
124        # Y between 1e-4 and 1e3.
125        $z = f($x,$y);
126
127       "xlogvals", "ylogvals" and "zlogvals" return a piddle with the same
128       shape as their first argument and logarithmicly scaled values between
129       the two other arguments along the given axis.
130
131       ylogvals
132
133       Y axis values logarithmicly spaced between endpoints (see yvals).
134
135       See xlogvals for more information.
136
137       zlogvals
138
139       Z axis values logarithmicly spaced between endpoints (see zvals).
140
141       See xlogvals for more information.
142
143       ndcoords
144
145       Enumerate pixel coordinates for an N-D piddle
146
147       $indices = ndcoords($pdl) $indices = ndcoords(@dimlist)
148
149       Returns an enumerated list of coordinates suitable for use in indexND
150       or range: you feed in a dimension list and get out a piddle whose 0th
151       dimension runs over dimension index and whose 1st through Nth dimen‐
152       sions are the dimensions given in the input.  If you feed in a piddle
153       instead of a perl list, then the dimension list is used, as in xvals
154       etc.
155
156         perldl> print ndcoords(2,3)
157         [
158          [
159           [0 0]
160           [1 0]
161           [2 0]
162          ]
163          [
164           [0 1]
165           [1 1]
166           [2 1]
167          ]
168         ]
169
170       hist
171
172       Create histogram of a piddle
173
174        $hist = hist($data,[$min,$max,$step]);
175        ($xvals,$hist) = hist($data,[$min,$max,$step]);
176
177       If requested, $xvals gives the computed bin centres
178
179       A nice idiom (with PDL::Graphics::PGPLOT) is
180
181        bin hist $data;  # Plot histogram
182
183        perldl> p $y
184        [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]
185        perldl> $h = hist $y,0,20,1; # hist with step 1, min 0 and 20 bins
186        perldl> p $h
187        [0 0 0 0 0 0 2 3 1 3 5 4 4 4 0 0 0 0 0 0]
188
189       whist
190
191       Create a weighted histogram of a piddle
192
193        $hist = whist($data, $wt, [$min,$max,$step]);
194        ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
195
196       If requested, $xvals gives the computed bin centres.  $data and $wt
197       should have the same dimensionality and extents.
198
199       A nice idiom (with PDL::Graphics::PGPLOT) is
200
201        bin whist $data, $wt;  # Plot histogram
202
203        perldl> p $y
204        [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]
205        perldl> $wt = grandom($y->nelem)
206        perldl> $h = whist $y, $wt, 0, 20, 1 # hist with step 1, min 0 and 20 bins
207        perldl> p $h
208        [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]
209
210       sequence
211
212       Create array filled with a sequence of values
213
214        $a = sequence($b); $a = sequence [OPTIONAL TYPE], @dims;
215
216       etc. see zeroes.
217
218        perldl> p sequence(10)
219        [0 1 2 3 4 5 6 7 8 9]
220        perldl> p sequence(3,4)
221        [
222         [ 0  1  2]
223         [ 3  4  5]
224         [ 6  7  8]
225         [ 9 10 11]
226        ]
227
228       rvals
229
230       Fills a piddle with radial distance values from some centre.
231
232        $r = rvals $piddle,{OPTIONS};
233        $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
234
235        Options:
236
237        Centre => [$x,$y,$z...] # Specify centre
238        Center => [$x,$y.$z...] # synonym.
239
240        Squared => 1 # return distance squared (i.e., don't take the square root)
241
242        perldl> print rvals long,7,7,{Centre=>[2,2]}
243        [
244         [2 2 2 2 2 3 4]
245         [2 1 1 1 2 3 4]
246         [2 1 0 1 2 3 4]
247         [2 1 1 1 2 3 4]
248         [2 2 2 2 2 3 4]
249         [3 3 3 3 3 4 5]
250         [4 4 4 4 4 5 5]
251        ]
252
253       For a more general metric, one can define, e.g.,
254
255        sub distance {
256          my ($a,$centre,$f) = @_;
257          my ($r) = $a->allaxisvals-$centre;
258          $f->($r);
259        }
260        sub l1 { sumover(abs($_[0])); }
261        sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); }
262        sub linfty { maximum(abs($_[0])); }
263
264       so now
265
266        distance($a, $centre, \&euclid);
267
268       will emulate rvals, while "\&l1" and "\&linfty" will generate other
269       well-known norms.
270
271       axisvals
272
273       Fills a piddle with index values on Nth dimension
274
275        $z = axisvals ($piddle, $nth);
276
277       This is the routine, for which xvals, yvals etc are mere shorthands.
278       "axisvals" can be used to fill along any dimension.
279
280       Note the 'from specification' style (see zeroes) is not available here,
281       for obvious reasons.
282
283       allaxisvals
284
285       Generates a piddle with index values
286
287        $z = allaxisvals ($piddle);
288
289       "allaxisvals" produces an array with axis values along each dimension,
290       adding an extra dimension at the start.
291
292       "allaxisvals($piddle)->slice("($nth)")" will produce the same result as
293       "axisvals($piddle,$nth)" (although with extra work and not inplace).
294
295       It's useful when all the values will be required, as in the example
296       given of a generalized rvals.
297
298       transpose
299
300       transpose rows and columns.
301
302        $b = transpose($a); $b = ~$a;
303
304       Also bound to the "~" unary operator in PDL::Matrix.
305
306        perldl> $a = sequence(3,2)
307        perldl> p $a
308        [
309         [0 1 2]
310         [3 4 5]
311        ]
312        perldl> p transpose( $a )
313        [
314         [0 3]
315         [1 4]
316         [2 5]
317        ]
318
319
320
321perl v5.8.8                       2002-05-21                          Basic(3)