SYNOPSIS
If PDL is about arrays, PDL::Dims makes them into hashes.
What it provides is a framework for addressing data not by numbered indices in numbered dimensions but by meaningful names and values.
In PDL::Dims the user does not need to know the internal structure, i.e. order of dimensions. It renders calls to functions like mv, reshape, reorder, ... unnecessary.
use PDL::Dims;
my $data= .... # some way to load data
print $data->Info;
# PDL: Double D [256,256,20,8,30]
# Now name the first dim x, running from -12 to 12 cm
initdim ($data, 'x',unit=>'cm',dmin=>-12,dmax=>12);
initdim ($data,'y',pos=>1,size=>256, # these are not necessary but you can set them explicitely
dmin=>-12, dinc=>0.078125, unit=>'cm' # min -12 max 8
initdim ($data,'n',vals=[@list]); # 20 objects with names in @list
initdim ($data,'t',spacing=>0,unit=>'s', vals=>[10,15,25,40,90,120,240,480); # sampled at different time points
initdim ($data,'z',min=>30,max=>28,unit=>'mm'); yet another way
# x,y,z are equally spaced numeric, n is non-numeric, t is numeric but at arbitrary distances
...
# load or define $mask with dims x,y,z equal to that of data
$i=ncop($data,$mask,'mult',0); # multiply mask onto data.
# Since mask has only x,y,z, the dims of $data are unchanged.
# x,y,z, in $mask or $data must be either 1 or equal.
# Calculate the average over my region of interest:
$sum=nreduce($i,'avg','x','y','z');
...
Now you want to associate your images with other data recorded at each time point:
# $data2: PDL [8, 100] (t,pars)
$more_complex=ncop($data,$data2,'plus',0);
#This will produce a piddle of size [256,256,20,8,30,100]
# if you want to average over every second object between n = 6 - 12:
$avg=nagg(sln($data,n=>'6:12:2'),'average','n');DESCRIPTION
This module is an extension to PDL by giving the dimensions a meaningful name, values or ranges. The module also provides wrappers to perform most PDL operations based on named dimensions. Each dimension is supposed to have a unique name.
If you prefer methods over functions, say
bless $piddle, "PDL::Dims";Names of dims can be any string (x,y,z,t,city, country, lattitude, fruit,pet, ...)
Each dim has its own hash with several important keys;
pos - dimension index 0..ndims-1
dimnames - a string by which the dim is accessed
index - current position within a dim. PDL::Dims knows the concept of a current position within a piddle
dummy - if true, initdim creates a dim of size at pos
num - dimension has numeric properties; if false, no min/max/inc are calculated. E.g. a dim pet may have values for dog, cat, fish, rabbit, mouse, parrot, min/max don't make sense in this case.
spacing - if true, values are evenly spaced; inc is undef if false
vals - list all values along a dim, if not evenly spaced each value is stored. Can cause memory issues in very large dims
min/max - minimum and maximum of numeric dimensions
inc - step between two indices in equally spaced dimensions
unit - the unit of vals.
SUBROUTINES/METHODS
The module has two different types of functions.
First, there are several utitility functions to manipulate and retrieve the dimension info. Currently, they only work on the metadata, no operations on the piddle are performed. It is your responsibility to call the appropriate function whenever piddle dims change.
Then there are functions to perform most PDL operations based on named dimensions instead of numbered dims. Wrappers to slice (sln), reduce (nreduce) and other functions (nop, ncop) are implemented.
The following parameters are currently used by PDL::Dims. It is *strongly* discouraged to access them directly except during calls to initdim. Use the functions listed below to manipulate and retrieve values.
They are usually called like that:
func ($piddle , [$dim, [value]]);if no dim is given, an array reference to all values are returned.
Otherwise, it returns the given value for a particular $dim, setting it to $value if defined.
diminfo
$infostr = diminfo($piddle);An extended version of PDLs info, showing dimnames and sizes (from header).
dimsize
dimsize($piddle,[$dim,[$size]]);set/get dimension size of piddle by name.
dimname
dimname($piddle,[$position,[$name]]);set/get dimension size of piddle by name.
idx
idx($piddle,[$name,[$current]])set/get current index values by name
didx
didx($piddle,[$name,[$pos]]);get/set position of dims by their names
i2pos
pos2i
i2pso($piddle,$dim,[$index]);
pso2i($piddle,$dim,$value);Converts value from/to index. So you can say, for example, if you have a piddle counting stuff in different houses,
sln($house,pets=>pos2i($house,pets,'dog'),rooms=>pos2i(housee,rooms,'kitchen'));something more realistic: Imagine you have two images of the same object but with different scaling and resolution or orientation. You want to extract what's between y = 10 and 20 cm of both images
ya10=pos2i($a,'y',10);
ya20=pos2i($a,'y',20);
$slice=sln($a,y=>"$ya10:$ya20");or if you want to resample something, the index $yb in $b corresponds to the index $ya in $a:
$ya=pos2i($a,'y',i2pos($b,'y',$yb));dmin
dmin($piddle,[$dim,[$min]]);get/set minimum value for a dimension
dmax
dmax($piddle,[$name,[$max]]);get/set maximum value for a dimension
dinc
dinc($piddle,[$name,[$increment]]);get/set maximum value for a dimension
vals
vals($piddle,$dim,[$index ,[$val]| $array_ref])get/set values of an axis. As a third argument you can either supply an index, then you can access that element or a reference to an array of size dimsize supplying values for that dim.
Please take a look on i2pos, pos2i, spacing and dnumeric to better understand the behaviour.
unit
unit($piddle,[$dim,[$unit]]);get/set the unit parameter. In the future, each assignment or operation should be units-avare, e.g. converting autmatically from mm to km or feet, preventing you from adding apples to peas ...
spacing
spacing ($piddle,[$dim,[$spacing]]);if true, the spacing between indices is assumed to be equal.
dnumeric
dnumeric ($piddl,[$dim,[$bool]]);get/set the flag if the piddle dim has numeric or other units. This has influence on vals, dmin, dmax, dinc.
initdim
initializes a dimenson
usage: initdim($piddle,$dimname,[%args]);
Arguments are the fields listed above. This should be called repeatedly after piddle creation to match the structure.
If pos is not provided, the next free position is used. If you call
initidim ($piddle,$name)N times on an N-dimensional piddle, it will create N dimensions with sizes corresponding to the dim of the piddle.
rmdim
removes a dminenso
rmdim($piddle,$dim);copy_dim
copies the diminfo from one piddle to the next.
copy_dim($a,$b,[$dim,[$pos]]);calls initdim on $b with parameters from $a. You can supply a new position. If you call it with just two arguments, all dims are copied.
sln
sln ($piddle,%slices);This replaces slice and it's derivatives.
perform slicing based on names. Returns correct dimension info. Unspecified dims are returned fully. If you want to squeeze, use sln($piddle, $dim=>"($value)");
or nsqueeze on the result, if you want all squeezed. Both will do the necessary rmdim calls for you,
Example: $sl=sln($a,x=>'0:10:2',t=>'4:',);
You can omit dims; it parses each key-value pair and constructs a slice string, so what typically works for slice, works here.
nop
This is the way to perform non-aggregate operations on one piddle which work only on one dim, like e.g. rotate.
usage: $res=nop($a,$operation,[@args]);
ncop
This is the way to perform any operations involving two operands when using PDL::Dims.
operates on two piddles, combining them by names. Equally named dimensions have to obey the usual threding rules. For opertators like '+' use the named version and an additional argument of 0.
usage: $c=ncop($a,$b,$operation,[@args]);
nagg
Use to perform aggregate functions, that reduce the dim by 1.
nagg($piddle,$operation,$dim,[@args]);Use this to perform sumover, average, ...
nreduce
a wrapper around reduce (requires PDL::Reduce) calling with names instead.
nreduce($piddle,$operations,@dimnames);active_slice
A conveniance function, similar to sln, but it returns a slice at the current position (index).
useage
$slice=active_slice($piddle,@ignore);returns the current selection (as accessed by idx) as a slice. Returns full dims on supplied dim list.
Call nsqueeze afterwards if that is what you want.
nsqueeze
A wrapper to squeeze. It makes the appropriate header updates (i.e. calls to rmdim).
is_sane
A sanity check for piddles. This is your friend when working with PDL::Dims!
$err=is_sane($piddle)returns 0 upon success, otherwise the first inconsisteny found is returned. This may change in future releases.
AUTHOR
Ingo Schmid
LICENSE AND COPYRIGHT
Copyright 2014 Ingo Schmid.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.