NAME
PDL::Dims - work on named dimensions and meaningful ranges
VERSION
Version 0.01
SYNOPSIS
use PDL::Dims;
initdim ($piddle,'x',pos=>0);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.
Each dim has its own hash with several important keys; names can be set (x,y,z,t, ...)
dimpos - hash of index names and their position (i.e. x=>0, z=>2, t=>3, y=>1 ...)
dimnames - the opposite of 'dimpos'; an array naming the indices
dims - hash of index sizes (by name)
index - hash of current values of each index (by name)
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.
dimsize - set/get dimension size of piddle by name
dimname - get/set dimension name of piddle by index
idx - set/get current index values by name
didx - get/set dimension names by index
dmin/dmax/dinc - get/set min/max/increment values in appropriate units (mm/s/ms...)
unit - NOT YET IMPLEMENTED. 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 ...
Use the following for creating/deleting dimensions (meta data).
initdim -
initializes a dimenson
usage: initdim($piddle,$dimname,%args);
Arguments are the fields listed above.
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.
ncop
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 0.
usage: $c=ncop($a,$b,'operation',@args);
nreduce
wrapper around reduce calling with names instead.
sln
sln ($piddle,%slices);perform slicing based on names.
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
perform non-aggregate function on a dimension.
usage: $res=nop($a,$operation,@args);
active_slice
A conveniance function,
useage
$slice=active_slice($piddle,@ignore);returns the current selection (as accessed by idx) as a slice. Returns full dims on supplied dim list
nsqueeze
A wrapper to squeeze. It makes the appropriate header updates (i.e. calls to rmdim).
TODO
Documentation! This is a quick release because several things did not work.
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.