Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Basic(3)	      User Contributed Perl Documentation	      Basic(3)

NAME
       PDL::Basic -- Basic utility functions for PDL

DESCRIPTION
       This module contains basic utility functions for	creating and
       manipulating piddles. Most of these functions are simplified interfaces
       to the more flexible functions in the modules PDL::Primitive and
       PDL::Slices.

SYNOPSIS
	use PDL::Basic;

FUNCTIONS
   xvals
       Fills a piddle with X index values.  Uses similar specifications	to
       zeroes and new_from_specification.

       CAVEAT:

       If you use the single argument piddle form (top row in the usage	table)
       the output will have the	same type as the input;	this may give
       surprising results if, e.g., you	have a byte array with a dimension of
       size greater than 256.  To force	a type,	use the	third form.

	$x = xvals($somearray);
	$x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
	$x = xvals([OPTIONAL TYPE], $somarray->dims);

       etc. see	zeroes.

	 pdl> print xvals zeroes(5,10)
	 [
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	  [0 1 2 3 4]
	 ]

   yvals
       Fills a piddle with Y index values.  See	the CAVEAT for xvals.

	$x = yvals($somearray);	yvals(inplace($somearray));
	$x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);

       etc. see	zeroes.

	pdl> print yvals zeroes(5,10)
	[
	 [0 0 0	0 0]
	 [1 1 1	1 1]
	 [2 2 2	2 2]
	 [3 3 3	3 3]
	 [4 4 4	4 4]
	 [5 5 5	5 5]
	 [6 6 6	6 6]
	 [7 7 7	7 7]
	 [8 8 8	8 8]
	 [9 9 9	9 9]
	]

   zvals
       Fills a piddle with Z index values.  See	the CAVEAT for xvals.

	$x = zvals($somearray);	zvals(inplace($somearray));
	$x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);

       etc. see	zeroes.

	pdl> print zvals zeroes(3,4,2)
	[
	 [
	  [0 0 0]
	  [0 0 0]
	  [0 0 0]
	  [0 0 0]
	 ]
	 [
	  [1 1 1]
	  [1 1 1]
	  [1 1 1]
	  [1 1 1]
	 ]
	]

   xlinvals
       X axis values between endpoints (see xvals).

	$a = zeroes(100,100);
	$x = $a->xlinvals(0.5,1.5);
	$y = $a->ylinvals(-2,-1);
	# calculate Z for X between 0.5	and 1.5	and
	# Y between -2 and -1.
	$z = f($x,$y);

       "xlinvals", "ylinvals" and "zlinvals" return a piddle with the same
       shape as	their first argument and linearly scaled values	between	the
       two other arguments along the given axis.

   ylinvals
       Y axis values between endpoints (see yvals).

       See xlinvals for	more information.

   zlinvals
       Z axis values between endpoints (see zvals).

       See xlinvals for	more information.

   xlogvals
       X axis values logarithmically spaced between endpoints (see xvals).

	$a = zeroes(100,100);
	$x = $a->xlogvals(1e-6,1e-3);
	$y = $a->ylinvals(1e-4,1e3);
	# calculate Z for X between 1e-6 and 1e-3 and
	# Y between 1e-4 and 1e3.
	$z = f($x,$y);

       "xlogvals", "ylogvals" and "zlogvals" return a piddle with the same
       shape as	their first argument and logarithmically scaled	values between
       the two other arguments along the given axis.

   ylogvals
       Y axis values logarithmically spaced between endpoints (see yvals).

       See xlogvals for	more information.

   zlogvals
       Z axis values logarithmically spaced between endpoints (see zvals).

       See xlogvals for	more information.

   allaxisvals
       Synonym for ndcoords - enumerates all coordinates in a PDL or dim list,
       adding an extra dim on the front	to accommodate the vector coordinate
       index (the form expected	by indexND, range, and interpND).  See
       ndcoords	for more detail.

       $indices	= allaxisvals($pdl); $indices =	allaxisvals(@dimlist);
       $indices	= allaxisvals($type,@dimlist);

   ndcoords
       Enumerate pixel coordinates for an N-D piddle

       Returns an enumerated list of coordinates suitable for use in indexND
       or range: you feed in a dimension list and get out a piddle whose 0th
       dimension runs over dimension index and whose 1st through Nth
       dimensions are the dimensions given in the input.  If you feed in a
       piddle instead of a perl	list, then the dimension list is used, as in
       xvals etc.

       Unlike xvals etc., if you supply	a piddle input,	you get	out a piddle
       of the default piddle type: double.   This causes less surprises	than
       the previous default of keeping the data	type of	the input piddle since
       that rarely made	sense in most usages.

       $indices	= ndcoords($pdl); $indices = ndcoords(@dimlist); $indices =
       ndcoords($type,@dimlist);

	 pdl> print ndcoords(2,3)

	 [
	  [
	   [0 0]
	   [1 0]
	  ]
	  [
	   [0 1]
	   [1 1]
	  ]
	  [
	   [0 2]
	   [1 2]
	  ]
	 ]

	 pdl> $a = zeroes(byte,2,3);	    # $a is a 2x3 byte piddle
	 pdl> $b = ndcoords($a);	    # $b inherits $a's type
	 pdl> $c = ndcoords(long,$a->dims); # $c is a long piddle, same	dims as	$b
	 pdl> help $b;
	 This variable is   Byte D [2,2,3]		P	     0.01Kb
	 pdl> help $c;
	 This variable is   Long D [2,2,3]		P	     0.05Kb

   hist
       Create histogram	of a piddle

	$hist =	hist($data);
	($xvals,$hist) = hist($data);

       or

	$hist =	hist($data,$min,$max,$step);
	($xvals,$hist) = hist($data,[$min,$max,$step]);

       If "hist" is run	in list	context, $xvals	gives the computed bin centres
       as double values.

       A nice idiom (with PDL::Graphics::PGPLOT) is

	bin hist $data;	 # Plot	histogram

	pdl> p $y
	[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]
	pdl> $h	= hist $y,0,20,1; # hist with step 1, min 0 and	20 bins
	pdl> p $h
	[0 0 0 0 0 0 2 3 1 3 5 4 4 4 0 0 0 0 0 0]

   whist
       Create a	weighted histogram of a	piddle

	$hist =	whist($data, $wt, [$min,$max,$step]);
	($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);

       If requested, $xvals gives the computed bin centres as type double
       values.	$data and $wt should have the same dimensionality and extents.

       A nice idiom (with PDL::Graphics::PGPLOT) is

	bin whist $data, $wt;  # Plot histogram

	pdl> p $y
	[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]
	pdl> $wt = grandom($y->nelem)
	pdl> $h	= whist	$y, $wt, 0, 20,	1 # hist with step 1, min 0 and	20 bins
	pdl> p $h
	[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]

   sequence
       Create array filled with	a sequence of values

	$a = sequence($b); $a =	sequence [OPTIONAL TYPE], @dims;

       etc. see	zeroes.

	pdl> p sequence(10)
	[0 1 2 3 4 5 6 7 8 9]
	pdl> p sequence(3,4)
	[
	 [ 0  1	 2]
	 [ 3  4	 5]
	 [ 6  7	 8]
	 [ 9 10	11]
	]

   rvals
       Fills a piddle with radial distance values from some centre.

	$r = rvals $piddle,{OPTIONS};
	$r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};

	Options:

	Centre => [$x,$y,$z...]	# Specify centre
	Center => [$x,$y.$z...]	# synonym.

	Squared	=> 1 # return distance squared (i.e., don't take the square root)

	pdl> print rvals long,7,7,{Centre=>[2,2]}
	[
	 [2 2 2	2 2 3 4]
	 [2 1 1	1 2 3 4]
	 [2 1 0	1 2 3 4]
	 [2 1 1	1 2 3 4]
	 [2 2 2	2 2 3 4]
	 [3 3 3	3 3 4 5]
	 [4 4 4	4 4 5 5]
	]

       If "Center" is not specified, the midpoint for a	given dimension	of
       size "N"	is given by " int(N/2) " so that the midpoint always falls on
       an exact	pixel point in the data.  For dimensions of even size, that
       means the midpoint is shifted by	1/2 pixel from the true	center of that
       dimension.

       Also note that the calculation for "rvals" for integer values does not
       promote the datatype so you will	have wraparound	when the value
       calculated for "	r**2 " is greater than the datatype can	hold.  If you
       need exact values, be sure to use large integer or floating point
       datatypes.

       For a more general metric, one can define, e.g.,

	sub distance {
	  my ($a,$centre,$f) = @_;
	  my ($r) = $a->allaxisvals-$centre;
	  $f->($r);
	}
	sub l1 { sumover(abs($_[0])); }
	sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); }
	sub linfty { maximum(abs($_[0])); }

       so now

	distance($a, $centre, \&euclid);

       will emulate rvals, while "\&l1"	and "\&linfty" will generate other
       well-known norms.

   axisvals
       Fills a piddle with index values	on Nth dimension

	$z = axisvals ($piddle,	$nth);

       This is the routine, for	which xvals, yvals etc are mere	shorthands.
       "axisvals" can be used to fill along any	dimension, using a parameter.

       See also	allaxisvals, which generates all axis values simultaneously in
       a form useful for range,	interpND, indexND, etc.

       Note the	'from specification' style (see	zeroes)	is not available here,
       for obvious reasons.

   transpose
       transpose rows and columns.

	$b = transpose($a);

	pdl> $a	= sequence(3,2)
	pdl> p $a
	[
	 [0 1 2]
	 [3 4 5]
	]
	pdl> p transpose( $a )
	[
	 [0 3]
	 [1 4]
	 [2 5]
	]

perl v5.32.1			  2018-05-05			      Basic(3)

NAME | DESCRIPTION | SYNOPSIS | FUNCTIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDL::Basic&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help