.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Basic 3pm"
.TH Basic 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Basic \-\- Basic utility functions for PDL
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module contains basic utility functions for
creating and manipulating ndarrays. Most of these functions
are simplified interfaces to the more flexible functions in
the modules
PDL::Primitive
and
PDL::Slices.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PDL::Basic;
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "xvals"
.IX Subsection "xvals"
Fills an ndarray with X index values.  Uses similar specifications to
\&\*(L"zeroes\*(R" and \*(L"new_from_specification\*(R", except that as of 2.064,
the returned ndarray will be at least type \f(CW\*(C`double\*(C'\fR.
.PP
\&\s-1CAVEAT:\s0
.PP
If you use the single argument ndarray 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.
.PP
.Vb 3
\& $x = xvals($somearray);
\& $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
\& $x = xvals([OPTIONAL TYPE], $somarray\->dims);
.Ve
.PP
etc. see zeroes.
.PP
.Vb 10
\&  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]
\&  ]
.Ve
.SS "yvals"
.IX Subsection "yvals"
Fills an ndarray with Y index values.  See the \s-1CAVEAT\s0 for \*(L"xvals\*(R".
.PP
.Vb 2
\& $x = yvals($somearray); yvals(inplace($somearray));
\& $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);
.Ve
.PP
etc. see zeroes.
.PP
.Vb 10
\& 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]
\& ]
.Ve
.SS "zvals"
.IX Subsection "zvals"
Fills an ndarray with Z index values.  See the \s-1CAVEAT\s0 for \*(L"xvals\*(R".
.PP
.Vb 2
\& $x = zvals($somearray); zvals(inplace($somearray));
\& $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);
.Ve
.PP
etc. see zeroes.
.PP
.Vb 10
\& 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]
\&  ]
\& ]
.Ve
.SS "xlinvals"
.IX Subsection "xlinvals"
X axis values between endpoints (see \*(L"xvals\*(R").
.PP
.Vb 6
\& $w = zeroes(100,100);
\& $x = $w\->xlinvals(0.5,1.5);
\& $y = $w\->ylinvals(\-2,\-1);
\& # calculate Z for X between 0.5 and 1.5 and
\& # Y between \-2 and \-1.
\& $z = f($x,$y);
.Ve
.PP
\&\f(CW\*(C`xlinvals\*(C'\fR, \f(CW\*(C`ylinvals\*(C'\fR and \f(CW\*(C`zlinvals\*(C'\fR return an ndarray with the same shape
as their first argument and linearly scaled values between the two other
arguments along the given axis.
.SS "ylinvals"
.IX Subsection "ylinvals"
Y axis values between endpoints (see \*(L"yvals\*(R").
.PP
See \*(L"xlinvals\*(R" for more information.
.SS "zlinvals"
.IX Subsection "zlinvals"
Z axis values between endpoints (see \*(L"zvals\*(R").
.PP
See \*(L"xlinvals\*(R" for more information.
.SS "xlogvals"
.IX Subsection "xlogvals"
X axis values logarithmically spaced between endpoints (see \*(L"xvals\*(R").
.PP
.Vb 6
\& $w = zeroes(100,100);
\& $x = $w\->xlogvals(1e\-6,1e\-3);
\& $y = $w\->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);
.Ve
.PP
\&\f(CW\*(C`xlogvals\*(C'\fR, \f(CW\*(C`ylogvals\*(C'\fR and \f(CW\*(C`zlogvals\*(C'\fR return an ndarray with the same shape
as their first argument and logarithmically scaled values between the two other
arguments along the given axis.
.SS "ylogvals"
.IX Subsection "ylogvals"
Y axis values logarithmically spaced between endpoints (see \*(L"yvals\*(R").
.PP
See \*(L"xlogvals\*(R" for more information.
.SS "zlogvals"
.IX Subsection "zlogvals"
Z axis values logarithmically spaced between endpoints (see \*(L"zvals\*(R").
.PP
See \*(L"xlogvals\*(R" for more information.
.SS "allaxisvals"
.IX Subsection "allaxisvals"
Synonym for \*(L"ndcoords\*(R" \- enumerates all coordinates in a
\&\s-1PDL\s0 or dim list, adding an extra dim on the front to accommodate
the vector coordinate index (the form expected by \*(L"indexND\*(R",
\&\*(L"range\*(R", and \*(L"interpND\*(R").  See \*(L"ndcoords\*(R" for more detail.
.PP
.Vb 3
\&  $indices = allaxisvals($pdl);
\&  $indices = allaxisvals(@dimlist);
\&  $indices = allaxisvals($type,@dimlist);
.Ve
.SS "ndcoords"
.IX Subsection "ndcoords"
Enumerate pixel coordinates for an N\-D ndarray
.PP
Returns an enumerated list of coordinates suitable for use in
indexND or range: you feed
in a dimension list and get out an ndarray whose 0th dimension runs over
dimension index and whose 1st through Nth dimensions are the
dimensions given in the input.  If you feed in an ndarray instead of a
perl list, then the dimension list is used, as in \*(L"xvals\*(R" etc.
.PP
Unlike \*(L"xvals\*(R" etc., if you supply an ndarray input, you get
out an ndarray of the default ndarray type: double.   This causes less
surprises than the previous default of keeping the data type of
the input ndarray since that rarely made sense in most usages.
.PP
.Vb 3
\&  $indices = ndcoords($pdl);
\&  $indices = ndcoords(@dimlist);
\&  $indices = ndcoords($type,@dimlist);
.Ve
.PP
.Vb 1
\&  pdl> print ndcoords(2,3)
\&
\&  [
\&   [
\&    [0 0]
\&    [1 0]
\&   ]
\&   [
\&    [0 1]
\&    [1 1]
\&   ]
\&   [
\&    [0 2]
\&    [1 2]
\&   ]
\&  ]
\&
\&  pdl> $w = zeroes(byte,2,3);        # $w is a 2x3 byte ndarray
\&  pdl> $y = ndcoords($w);            # $y inherits $w\*(Aqs type
\&  pdl> $c = ndcoords(long,$w\->dims); # $c is a long ndarray, same dims as $y
\&  pdl> help $y;
\&  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
.Ve
.SS "hist"
.IX Subsection "hist"
Create histogram of an ndarray
.PP
.Vb 2
\& $hist = hist($data);
\& ($xvals,$hist) = hist($data);
.Ve
.PP
or
.PP
.Vb 2
\& $hist = hist($data,$min,$max,$step);
\& ($xvals,$hist) = hist($data,[$min,$max,$step]);
.Ve
.PP
If \f(CW\*(C`hist\*(C'\fR is run in list context, \f(CW$xvals\fR gives the
computed bin centres as double values.
.PP
A nice idiom (with
PDL::Graphics::PGPLOT) is
.PP
.Vb 1
\& bin hist $data;  # Plot histogram
.Ve
.PP
.Vb 5
\& 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]
.Ve
.SS "whist"
.IX Subsection "whist"
Create a weighted histogram of an ndarray
.PP
.Vb 2
\& $hist = whist($data, $wt, [$min,$max,$step]);
\& ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);
.Ve
.PP
If requested, \f(CW$xvals\fR gives the computed bin centres
as type double values.  \f(CW$data\fR and \f(CW$wt\fR should have
the same dimensionality and extents.
.PP
A nice idiom (with
PDL::Graphics::PGPLOT) is
.PP
.Vb 1
\& bin whist $data, $wt;  # Plot histogram
.Ve
.PP
.Vb 6
\& 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]
.Ve
.SS "sequence"
.IX Subsection "sequence"
Create array filled with a sequence of values
.PP
.Vb 1
\& $w = sequence($y); $w = sequence [OPTIONAL TYPE], @dims;
.Ve
.PP
etc. see zeroes.
.PP
.Vb 9
\& 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]
\& ]
.Ve
.SS "rvals"
.IX Subsection "rvals"
Fills an ndarray with radial distance values from some centre.
.PP
.Vb 2
\& $r = rvals $ndarray,{OPTIONS};
\& $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};
.Ve
.PP
.Vb 1
\& Options:
\&
\& Centre => [$x,$y,$z...] # Specify centre
\& Center => [$x,$y.$z...] # synonym.
\&
\& Squared => 1 # return distance squared (i.e., don\*(Aqt take the square root)
.Ve
.PP
.Vb 10
\& 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]
\& ]
.Ve
.PP
If \f(CW\*(C`Center\*(C'\fR is not specified, the midpoint for a given dimension of
size \f(CW\*(C`N\*(C'\fR is given by \f(CW\*(C` int(N/2) \*(C'\fR 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.
.PP
Also note that the calculation for \f(CW\*(C`rvals\*(C'\fR for integer values
does not promote the datatype so you will have wraparound when
the value calculated for \f(CW\*(C` r**2 \*(C'\fR is greater than the datatype
can hold.  If you need exact values, be sure to use large integer
or floating point datatypes.
.PP
For a more general metric, one can define, e.g.,
.PP
.Vb 8
\& sub distance {
\&   my ($w,$centre,$f) = @_;
\&   my ($r) = $w\->allaxisvals\-$centre;
\&   $f\->($r);
\& }
\& sub l1 { sumover(abs($_[0])); }
\& sub euclid { use PDL::Math \*(Aqpow\*(Aq; pow(sumover(pow($_[0],2)),0.5); }
\& sub linfty { maximum(abs($_[0])); }
.Ve
.PP
so now
.PP
.Vb 1
\& distance($w, $centre, \e&euclid);
.Ve
.PP
will emulate rvals, while \f(CW\*(C`\e&l1\*(C'\fR and \f(CW\*(C`\e&linfty\*(C'\fR will generate other
well-known norms.
.SS "axisvals"
.IX Subsection "axisvals"
Fills an ndarray with index values on Nth dimension
.PP
.Vb 1
\& $z = axisvals ($ndarray, $nth);
.Ve
.PP
This is the routine, for which \*(L"xvals\*(R", \*(L"yvals\*(R" etc
are mere shorthands. \f(CW\*(C`axisvals\*(C'\fR can be used to fill along any dimension,
using a parameter.
.PP
See also \*(L"allaxisvals\*(R", which generates all axis values
simultaneously in a form useful for \*(L"range\*(R", \*(L"interpND\*(R",
\&\*(L"indexND\*(R", etc.
.PP
Note the 'from specification' style (see zeroes) is
not available here, for obvious reasons.
.SS "transpose"
.IX Subsection "transpose"
transpose rows and columns.
.PP
.Vb 1
\& $y = transpose($w);
.Ve
.PP
.Vb 12
\& pdl> $w = sequence(3,2)
\& pdl> p $w
\& [
\&  [0 1 2]
\&  [3 4 5]
\& ]
\& pdl> p transpose( $w )
\& [
\&  [0 3]
\&  [1 4]
\&  [2 5]
\& ]
.Ve