PDL::FuncND - N dimensional version of functions
use PDL::FuncND;
This module provides multi-dimensional implementations of common functions.
Evaluate the multi-variate Cauchy function on an N-dimensional 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:
vectors
$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.
transform
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. The vectors option must also be set:
m
$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
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 ] ] } );
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 positive-definite matrix containing squared scales.
theta
Only for 2D! Applies a rotation (clockwise, e.g. +X rotates towards -Y) by the specified angle (specified in radians).
log
If true, return the logarithm of the function. Defaults to false.
Evaluate the sampled multi-dimensional Gaussian PDF on an N-dimensional 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:
$f = gaussND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
$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 );
$piddle = pdl( [2,1], [3,1], [4,2] ); $f = gaussND( $piddle, { vectors => 1 } );
This may take one of the following values:
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.
Evaluate the multi-dimensional Lorentz function on an N-dimensional 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 half-width at half-max (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 N-dimensional 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 one-dimensional Cauchy (aprt from, in this formulation, the normalization constant), this formulation of the multi-dimensional Lorentz function is not equivalent to the multi-dimensional Cauchy!
It can evaluate the function either on a grid or at discrete locations:
$f = lorentzND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
$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 );
$piddle = pdl( [2,1], [3,1], [4,2] ); $f = lorentzND( $piddle, { vectors => 1 } );
Evaluate the multi-dimensional Moffat distribution on an N-dimensional 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 n-dimensional 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 N-dimensional 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.
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.
$f = moffatND( [ OPTIONAL TYPE], $nx, $ny, ..., \%options );
$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 );
$piddle = pdl( [2,1], [3,1], [4,2] ); $f = moffatND( $piddle, { vectors => 1 } );
beta
The Moffat beta parameter. Required.
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( (v-u)T S^-1 (v-u) )
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.
$v
N
The input covariance matrix ($S) must have shape (N,N). It is not checked for validity.
$S
The available options are:
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.
PDL::Func.
Please report bugs to https://rt.cpan.org/Public/Dist/Display.html?Name=PDL-FuncND.
Copyright (c) 2010-2012 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/>.
Diab Jerius <djerius@cpan.org>
To install PDL::FuncND, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL::FuncND
CPAN shell
perl -MCPAN -e shell install PDL::FuncND
For more information on module installation, please visit the detailed CPAN module installation guide.