NAME
PDL::FuncND  N dimensional version of functions
SYNOPSIS
use PDL::FuncND;
DESCRIPTION
This module provides multidimensional implementations of common functions.
FUNCTIONS
cauchyND
Evaluate the multivariate Cauchy function on an Ndimensional grid or at a set of locations.
$a = cauchyND( [OPTIONAL TYPE], $nx, $ny, ..., \%options );
$b = cauchyND( $a, \%options );
cauchyND( inplace $a, \%options );
$a>inplace>cauchyND( \%options );
cauchyND can evaluate the function either on a grid or at discrete locations:
evaluation on a grid
Either specify the output piddle dimensions explicitly,
$f = cauchyND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
or specify a template piddle without specifying the
vectors
option:$f = cauchyND( $piddle, \%options );
By default cauchyND will evaluate the function at the indices of the points in the input piddle. These may be mapped to other values by specifying a transform with the
transform
option. cauchyND is inplace aware, and will use $piddle as the output piddle if its inplace flag is set.cauchyND( inplace $f, \%options ); $f>inplace>cauchyND( \%options );
evaluation at a set of locations
The input piddle should represent a set of vectors and should have a shape of (N,m), where
m
is the number of vectors in the set. Thevectors
option must also be set:$piddle = pdl( [2,1], [3,1], [4,2] ); $f = cauchyND( $piddle, { vectors => 1 } );
The vectors may be transformed before use via the
transform
option.
The following options are available:
center
centre

The center of the distribution. If not specified it defaults to the origin.
This may take one of the following forms
A vector of shape (N).
The location of the center. This may be either a Perl arrayref or a one dimensional piddle. If the input coordinates are transformed, this is in the transformed space.
the string
auto
If the PDF is calculated on a grid, this will center the distribution on the grid. It is an error to use this for explicit locations.
An arrayref
The first element of the array is a string indicating the meaning of the rest of the array. The following are supported:
offset
The second element of the array is a piddle indicating an offset from an automatically generated center. This allows easily accumulating multiple offset offsets. For example:
$img = cauchyND( double, 32, 32, { %attr, center => 'auto' } ); $img += moffatND( $img, { %moffat_attr, center => [ offset => [ 5.24, 0.3 ] ] } );
transform

A PDL::Transform object to be applied to the input coordinates.
scale

The scale. If the input coordinates are transformed via the
transform
option, the units of scale are those in the transformed space. This may be specified as:a scalar (Perl or piddle)
This results in a symmetric distribution with the given scale along each coordinate.
a vector of shape (N) (piddle or Perl arrayref)
This results in a distribution with the specified scales for each coordinate.
a matrix (piddle of shape (N,N))
This should be a positivedefinite matrix containing squared scales.
theta
(Perl scalar)
Only for 2D! Applies a rotation (clockwise, e.g. +X rotates towards Y) by the specified angle (specified in radians).
log
(Boolean)
If true, return the logarithm of the function. Defaults to false.
gaussND
Evaluate the sampled multidimensional Gaussian PDF on an Ndimensional grid or at a set of locations.
$f = gaussND( [OPTIONAL TYPE], $nx, $ny, ..., \%options );
$f = gaussND( $piddle, \%options );
gaussND( inplace $piddle, \%options );
$a>inplace>gaussND( \%options );
gaussND can evaluate the function either on a grid or at discrete locations:
evaluation on a grid
Either specify the output piddle dimensions explicitly,
$f = gaussND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
or specify a template piddle without specifying the
vectors
option:$f = gaussND( $piddle, \%options );
By default gaussND will evaluate the function at the indices of the points in the input piddle. These may be mapped to other values by specifying a transform with the
transform
option. gaussND is inplace aware, and will use $piddle as the output piddle if its inplace flag is set.gaussND( inplace $f, \%options ); $f>inplace>gaussND( \%options );
evaluation at a set of locations
The input piddle should represent a set of vectors and should have a shape of (N,m), where
m
is the number of vectors in the set. Thevectors
option must also be set:$piddle = pdl( [2,1], [3,1], [4,2] ); $f = gaussND( $piddle, { vectors => 1 } );
The vectors may be transformed before use via the
transform
option.
The following options are available:
center
centre

The center of the distribution. If not specified it defaults to the origin.
This may take one of the following values:
A vector of shape (N).
The location of the center. This may be either a Perl arrayref or a one dimensional piddle. If the input coordinates are transformed, this is in the transformed space.
the string
auto
If the PDF is calculated on a grid, this will center the distribution on the grid. It is an error to use this for explicit locations.
transform

A PDL::Transform object to be applied to the input coordinates.
scale

The scale. If the input coordinates are transformed via the
transform
option, the units of scale are those in the transformed space. This may be specified as:a scalar (Perl or piddle)
This results in a symmetric distribution with the given scale along each coordinate.
a vector of shape (N) (piddle or Perl arrayref)
This results in a distribution with the specified scales for each coordinate.
the full covariance matrix (piddle of shape (N,N))
This results in a distribution with correlated scales. At present this matrix is not verified to be a legitimate covariance matrix.
theta
(Perl scalar)
Only for 2D! Applies a rotation (clockwise, e.g. +X rotates towards Y) by the specified angle (specified in radians).
log
(Boolean)
If true, return the logarithm of the function. Defaults to false.
lorentzND
Evaluate the multidimensional Lorentz function on an Ndimensional grid or at a set of locations.
$f = lorentzND( [OPTIONAL TYPE], $nx, $ny, ..., \%options );
$f = lorentzND( $piddle, \%options );
lorentzND( inplace $piddle, \%options );
$a>inplace>lorentzND( \%options );
The Lorentz function is usually defined in one dimension as.
2
g
f(x; x0, g) = 
2 2
(x  x0) + g
where g is the halfwidth at halfmax (HWHM). The two dimensional symmetric analogue (sometimes called the "radial Lorentz function") is
2
g
f(x, y; x0, y0, g) = 
2 2 2
(x  x0) + (y  y0) + g
One can extend this to an asymmetric form by writing it as
1
f(x; u, S) = 
T 1
(x  u) . S . (x  u) + 1
where x is now a vector, u is the expectation value of the distribution, and S is a matrix describing the Ndimensional scale of the distribution akin to (but not the same as!) a covariance matrix.
For example, a symmetric 2D Lorentz with HWHM of g has
[ 2 ]
[ g 0 ]
S = [ ]
[ 2 ]
[ 0 g ]
while an elliptical distribution elongated twice as much along the X axis as the Y axis would be:
[ 2 ]
[ (2*g) 0 ]
S = [ ]
[ 2 ]
[ 0 g ]
lorentzND extends the Lorentz function to N dimensions by treating x and u as vectors of length N, and S as an NxN matrix.
Please note! While the one dimensional Lorentz function is equivalent to the onedimensional Cauchy (aprt from, in this formulation, the normalization constant), this formulation of the multidimensional Lorentz function is not equivalent to the multidimensional Cauchy!
It can evaluate the function either on a grid or at discrete locations:
evaluation on a grid
Either specify the output piddle dimensions explicitly,
$f = lorentzND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
or specify a template piddle without specifying the
vectors
option:$f = lorentzND( $piddle, \%options );
By default lorentzND will evaluate the function at the indices of the points in the input piddle. These may be mapped to other values by specifying a transform with the
transform
option. lorentzND is inplace aware, and will use $piddle as the output piddle if its inplace flag is set.lorentzND( inplace $f, \%options ); $f>inplace>lorentzND( \%options );
evaluation at a set of locations
The input piddle should represent a set of vectors and should have a shape of (N,m), where
m
is the number of vectors in the set. Thevectors
option must also be set:$piddle = pdl( [2,1], [3,1], [4,2] ); $f = lorentzND( $piddle, { vectors => 1 } );
The vectors may be transformed before use via the
transform
option.
The following options are available:
center
centre

The center of the distribution. If not specified it defaults to the origin.
This may take one of the following values:
A vector of shape (N).
The location of the center. This may be either a Perl arrayref or a one dimensional piddle. If the input coordinates are transformed, this is in the transformed space.
the string
auto
If the PDF is calculated on a grid, this will center the distribution on the grid. It is an error to use this for explicit locations.
transform

A PDL::Transform object to be applied to the input coordinates.
scale

The scale. If the input coordinates are transformed via the
transform
option, the units of scale are those in the transformed space. This may be specified as:a scalar (Perl or piddle)
This results in a symmetric distribution with the given scale along each coordinate.
a vector of shape (N) (piddle or Perl arrayref)
This results in a distribution with the specified scales for each coordinate.
a matrix (piddle of shape (N,N))
This should be a positivedefinite matrix containing squared scales.
theta
(Perl scalar)
Only for 2D! Applies a rotation (clockwise, e.g. +X rotates towards Y) by the specified angle (specified in radians).
moffatND
Evaluate the multidimensional Moffat distribution on an Ndimensional grid or at a set of locations.
$f = moffatND( [OPTIONAL TYPE], $nx, $ny, ..., \%options );
$f = moffatND( $piddle, \%options );
moffatND( inplace $piddle, \%options );
$a>inplace>moffatND( \%options );
The Moffat distribution is usually defined in two dimensions as.
2 2
2 1 x + y beta
f(x, y, alpha, beta) := (beta  1) (pi alpha ) (a + )
2
alpha
In astronomy this is also known (confusingly) as the beta function, and is often expressed in radial form:
2
2 r (beta  1) r beta
fr(r, alpha, beta) :=  (1 + )
2 2
alpha alpha
One can extend the Cartesion expression to an ndimensional asymmetric form by writing it as
fn(x, u, S, alpha, beta) :=
gamma(beta) n/2 1/2 1 T 1 beta
 ( pi S ) (1 + (x  u) . S . (x  u))
2 beta  n
gamma()
2
where n is the number of dimensions, x is now a vector, u is the expectation value of the distribution, and S is a matrix describing the Ndimensional scale of the distribution akin to (but not the same as!) a covariance matrix.
Note that the integral of the distribution diverges for beta <= n/2
.
moffatND extends the Moffat function to N dimensions by treating x and u as vectors of length N, and S as an NxN matrix.
It can evaluate the function either on a grid or at discrete locations:
evaluation on a grid
Either specify the output piddle dimensions explicitly,
$f = moffatND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
or specify a template piddle without specifying the
vectors
option:$f = moffatND( $piddle, \%options );
By default moffatND will evaluate the function at the indices of the points in the input piddle. These may be mapped to other values by specifying a transform with the
transform
option. moffatND is inplace aware, and will use $piddle as the output piddle if its inplace flag is set.moffatND( inplace $f, \%options ); $f>inplace>moffatND( \%options );
evaluation at a set of locations
The input piddle should represent a set of vectors and should have a shape of (N,m), where
m
is the number of vectors in the set. Thevectors
option must also be set:$piddle = pdl( [2,1], [3,1], [4,2] ); $f = moffatND( $piddle, { vectors => 1 } );
The vectors may be transformed before use via the
transform
option.
The following options are available:
beta

The Moffat beta parameter. Required.
center
centre

The center of the distribution. If not specified it defaults to the origin.
This may take one of the following values:
A vector of shape (N).
The location of the center. This may be either a Perl arrayref or a one dimensional piddle. If the input coordinates are transformed, this is in the transformed space.
the string
auto
If the PDF is calculated on a grid, this will center the distribution on the grid. It is an error to use this for explicit locations.
transform

A PDL::Transform object to be applied to the input coordinates.
scale

The scale. If the input coordinates are transformed via the
transform
option, the units of scale are those in the transformed space. This may be specified as:a scalar (Perl or piddle)
This results in a symmetric distribution with the given scale along each coordinate.
a vector of shape (N) (piddle or Perl arrayref)
This results in a distribution with the specified scales for each coordinate.
a matrix (piddle of shape (N,N))
This should be a positivedefinite matrix containing squared scales.
theta
(Perl scalar)
Only for 2D! Applies a rotation (clockwise, e.g. +X rotates towards Y) by the specified angle (specified in radians).
mahalanobis
Calculate the Mahalanobis distance for one or more vectors
Signature: ( x(n,m), s(n,n), [o]d(m), \%options )
$d = mahalanobis( $v, $S, \%options );
mahalanobis( $v, $S, $d, \%options );
The Mahalanobis distance of a multivariate vector (v) from a location (u) with a covariance matrix (S) is defined as
dm(x,u) = sqrt( (vu)T S^1 (vu) )
The input piddle representing the vectors ($v
) must have shape (N,m), where N
is the dimension of the vector space and m
is the number of vectors.
The input covariance matrix ($S
) must have shape (N,N). It is not checked for validity.
The available options are:
center
centre

The vector from which the distance is to be calculated. It must have shape (N). It defaults to the origin.
inverted

If true, the input matrix is the inverse of the covariance matrix. Defaults to false.
squared

if true, the returned values are the distances squared.
SEE ALSO
PDL::Func.
BUGS
Please report bugs to https://rt.cpan.org/Public/Dist/Display.html?Name=PDLFuncND.
LICENSE AND COPYRIGHT
Copyright (c) 20102012 The Smithsonian Astrophysical Observatory
PDL::FuncND is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
AUTHOR
Diab Jerius <djerius@cpan.org>