| 1 | package PDL::Util; | ||||||||||||||||||||||||||||
| 2 | { | ||||||||||||||||||||||||||||
| 3 | 6 | $PDL::Util::VERSION = '0.010'; | |||||||||||||||||||||||||||
| 4 | } | ||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 6 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 7 | 6 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | =head1 NAME | ||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | PDL::Util | ||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | use PDL; | ||||||||||||||||||||||||||||
| 16 | use PDL::Util 'export2d'; | ||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | my $pdl = rvals(6,4); | ||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | open my $fh, '>', 'file.dat'; | ||||||||||||||||||||||||||||
| 21 | export2d($pdl, $fh); | ||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | Convenient utility functions/methods for use with PDL. | ||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||
| 27 | =cut | ||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||
| 29 | 6 | ▶ | use PDL; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 30 | 6 | ▶ | use Scalar::Util qw/openhandle blessed/; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||
| 32 | 6 | ▶ | use Carp; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||
| 34 | 6 | ▶ | use parent 'Exporter'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 35 | 6 | our %EXPORT_TAGS = ( | |||||||||||||||||||||||||||
| 36 | functions => [qw/add_pdl_method/], | ||||||||||||||||||||||||||||
| 37 | methods => [qw/unroll export2d/], | ||||||||||||||||||||||||||||
| 38 | ); | ||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | 6 | our @EXPORT_OK; | |||||||||||||||||||||||||||
| 41 | 6 | push @EXPORT_OK, @$_ for values %EXPORT_TAGS; | |||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||
| 43 | 6 | $EXPORT_TAGS{'all'} = \@EXPORT_OK; | |||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||
| 45 | =head1 IMPORT | ||||||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||||||
| 47 | use PDL:Util 'export2d', ['unroll'] | ||||||||||||||||||||||||||||
| 48 | # imports 'export2d', adds 'unroll' as a PDL method | ||||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||||
| 50 | L<PDL::Util> does not export anything by default. A list of symbols may be imported as usual. The exportable symbols come in two types, functions (tag C<:function>) and methods (tag C<:methods>). The word I<methods> here is a strange word. When importing symbols one does not import methods. In this context a 'method' is a function which expects a piddle as its first argument. However, there is a reason ... | ||||||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||||||
| 52 | If an array reference or hash reference is passed as the last item in the import list, the reference will be passed to the L<add_pdl_method> function below, in which case these functions are imported into the C<PDL> namespace and may be used as method calls. Note, when doing this for symbols from the L<PDL::Util> module, only those listed in the C<:methods> tag may be added as a method (this is the origin of the confusing terminology). Read about the L<add_pdl_method> function carefully before using this functionality. | ||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||
| 54 | =cut | ||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | 6 | ▶ | sub import { | ||||||||||||||||||||||||||
|
Subroutine
import: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||
| 57 | 6 | my $package = shift; | |||||||||||||||||||||||||||
| 58 | 6 | ▶ | return 1 unless @_; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||
| 60 | 5 | ▶ | my $ref_last = ref $_[-1] || ''; | ||||||||||||||||||||||||||
|
Condition100%2/2
ref $_[-1] || ''
MC/DC100%1/1
ref $_[-1] || ''
ref $_[-1]
Truth table100%2/2
A
A= ref $_[-1]
| |||||||||||||||||||||||||||||
| 61 | 5 | ▶ | my $method_spec = ( grep {$ref_last eq $_} qw/HASH ARRAY/ ) ? pop : 0; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||
| 63 | 5 | ▶ | add_pdl_method($method_spec) if ($method_spec); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||
| 65 | 5 | ▶ | __PACKAGE__->export_to_level(1, $package, @_) if @_; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 66 | } | ||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | =head1 TAG :functions | ||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||
| 70 | =head2 add_pdl_method | ||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||
| 72 | add_pdl_method({'my_method' => sub { my $self = shift; ... }); | ||||||||||||||||||||||||||||
| 73 | $pdl->my_method # calls the anonymous sub on $pdl | ||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||
| 75 | add_pdl_method(['export2d']); | ||||||||||||||||||||||||||||
| 76 | $pdl->export2d() # calls 'export2d' on $pdl | ||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||
| 78 | add_pdl_method({'my_unroll' => 'unroll'}); | ||||||||||||||||||||||||||||
| 79 | $pdl->my_unroll() # calls 'unroll' method on $pdl | ||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||
| 81 | C<add_pdl_method> pushes subroutines into the PDL namespace. It takes a single argument, a reference either an array or hash. The keys of the hash reference are the method name that will be used in the call (e.g. C<< $pdl->method_name >>, the values are either a reference to a subroutine or a string containing the name of a method provided by L<PDL::Util>. The array reference form can only take names of C<PDL::Util> methods. | ||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||
| 83 | When adding your own subroutine as a L<PDL> method, be aware that the first argument passed will be a self (i.e. C<$self>) reference, in the normal Perl OO manner. | ||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||
| 85 | =cut | ||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | 6 | ▶ | sub add_pdl_method { | ||||||||||||||||||||||||||
|
Subroutine
add_pdl_method: called CC=8 SCAR=21.0
Pod
documented
| |||||||||||||||||||||||||||||
| 88 | 6 | my $spec = shift; | |||||||||||||||||||||||||||
| 89 | croak 'make_pdl_method expects a hash or array reference as its argument' | ||||||||||||||||||||||||||||
| 90 | 6 | ▶ | unless grep {ref $spec eq $_} qw/HASH ARRAY/; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||||
| 92 | 6 | ▶ | if (ref $spec eq 'ARRAY') { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 93 | 2 | $spec = { map { $_ => $_ } @$spec }; | |||||||||||||||||||||||||||
| 94 | } | ||||||||||||||||||||||||||||
| 95 | |||||||||||||||||||||||||||||
| 96 | 6 | foreach my $method (keys %$spec) { | |||||||||||||||||||||||||||
| 97 | 8 | my $function = $spec->{$method}; | |||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||
| 99 | # Check to see if PDL already has a method by the same name | ||||||||||||||||||||||||||||
| 100 | 8 | ▶ | carp <<MESSAGE if PDL->can($method); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 101 | PDL already provides a method named '$method', read the PDL::Util documentation to learn to avoid this conflict. | ||||||||||||||||||||||||||||
| 102 | MESSAGE | ||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||
| 104 | 8 | ▶ | unless (ref $function && ref $function eq 'CODE') { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
ref $function and ref $function eq "CODE"
MC/DC50%1/2
ref $function and ref $function eq "CODE"
ref $function
ref $function eq "CODE"
Truth table66%2/3
A and B
A= ref $functionB= ref $function eq "CODE"
| |||||||||||||||||||||||||||||
| 105 | 7 | ▶ | if ( 1 == grep { $_ eq $function } @{ $EXPORT_TAGS{'methods'} } ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 106 | 6 | ▶ | no strict 'refs'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 107 | 7 | $function = \&{ 'PDL::Util::' . $function }; | |||||||||||||||||||||||||||
| 108 | } else { | ||||||||||||||||||||||||||||
| 109 | 0 | croak "value for $method must be either a code reference or the name of one of PDL::Util's exportable functions"; | |||||||||||||||||||||||||||
| 110 | } | ||||||||||||||||||||||||||||
| 111 | } | ||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||
| 113 | 6 | ▶ | no strict 'refs'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 114 | 8 | *{'PDL::'.$method} = $function; | |||||||||||||||||||||||||||
| 115 | } | ||||||||||||||||||||||||||||
| 116 | } | ||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | =head1 TAG :methods | ||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||
| 120 | Again, the I<functions> provided in the method tag are not automatically methods. They simply are function which are called with a PDL object (piddle) as their first argument. This function ARE available to be imported into the PDL namespace using the L<add_pdl_method> function describe above. | ||||||||||||||||||||||||||||
| 121 | |||||||||||||||||||||||||||||
| 122 | =head2 unroll | ||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | $AoA = unroll($pdl); | ||||||||||||||||||||||||||||
| 125 | -- or -- | ||||||||||||||||||||||||||||
| 126 | $AoA = $pdl->unroll(); | ||||||||||||||||||||||||||||
| 127 | |||||||||||||||||||||||||||||
| 128 | L<PDL> provides a function for constructing a PDL object (piddle) from a Perl nested array, however it does not provide a tool to convert a piddle to a nested array structure. The closest function is the C<list> function, which returns the elements of the piddle as a list, i.e. a 1D flattened array. C<unroll> converts piddles to a native Perl data structure; it can be thought of as the logical inverse of the C<pdl> function in that C<pdl(unroll($pdl))> should return the original data structure, although bad values and data types may be changed. | ||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||
| 130 | When called as a function C<unroll> takes a single argument (the piddle to unroll). When used as a method it takes no arguments. It returns a reference to an array containing the Perl equivalent data structure. | ||||||||||||||||||||||||||||
| 131 | |||||||||||||||||||||||||||||
| 132 | =cut | ||||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||
| 134 | 10 | ▶ | sub unroll { | ||||||||||||||||||||||||||
|
Subroutine
unroll: called CC=4 SCAR=14.8
Pod
documented
| |||||||||||||||||||||||||||||
| 135 | 10 | my $pdl = shift; | |||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||
| 137 | 10 | ▶ | if ( blessed($pdl) and $pdl->isa('PDL') ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
builtin::blessed($pdl) and $pdl->isa("PDL")
MC/DC0%0/2
builtin::blessed($pdl) and $pdl->isa("PDL")
builtin::blessed($pdl)
$pdl->isa("PDL")
Truth table33%1/3
A and B
A= builtin::blessed($pdl)B= $pdl->isa("PDL")
| |||||||||||||||||||||||||||||
| 138 | 10 | ▶ | if ($pdl->ndims > 1) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 139 | 4 | return [ map {unroll($_)} dog $pdl ]; | |||||||||||||||||||||||||||
| 140 | } else { | ||||||||||||||||||||||||||||
| 141 | 6 | return [list $pdl]; | |||||||||||||||||||||||||||
| 142 | } | ||||||||||||||||||||||||||||
| 143 | } else { | ||||||||||||||||||||||||||||
| 144 | 0 | croak "Attempted to unroll a non-PDL object"; | |||||||||||||||||||||||||||
| 145 | #return $pdl; | ||||||||||||||||||||||||||||
| 146 | } | ||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||
| 148 | } | ||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||
| 150 | =head2 export2d | ||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | export2d($pdl, $fh, ','); | ||||||||||||||||||||||||||||
| 153 | -- or -- | ||||||||||||||||||||||||||||
| 154 | $pdl->export2d($fh, ','); | ||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||
| 156 | C<export2d> may take up to 2 optional arguments (neglecting the object reference), a lexical filehandle (or globref, e.g. C<\*FILE>) to write to, and a string containing a column separator. The defaults, if arguments are not given are to print to STDOUT and use a single space as the column separator. The order does not matter, the method will determine whether an argument refers to a file or not. This is done so that one may call either | ||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||
| 158 | $pdl->export2d($fh); | ||||||||||||||||||||||||||||
| 159 | $pdl->export2d(','); | ||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||
| 161 | and it will do what you mean. Unfortunately this means that unlike C<wcols> one cannot use a filename rather than a filehandle; C<export2d> would interpret the string as the column separator! | ||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||
| 163 | The method returns the number of columns that were written. | ||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||
| 165 | =cut | ||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | 9 | ▶ | sub export2d { | ||||||||||||||||||||||||||
|
Subroutine
export2d: called CC=8 SCAR=21.0
Pod
documented
| |||||||||||||||||||||||||||||
| 168 | 9 | my ($pdl, $fh, $sep); | |||||||||||||||||||||||||||
| 169 | 9 | $pdl = shift; | |||||||||||||||||||||||||||
| 170 | 9 | ▶ | unless ( blessed($pdl) and $pdl->isa('PDL') ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
builtin::blessed($pdl) and $pdl->isa("PDL")
MC/DC0%0/2
builtin::blessed($pdl) and $pdl->isa("PDL")
builtin::blessed($pdl)
$pdl->isa("PDL")
Truth table33%1/3
A and B
A= builtin::blessed($pdl)B= $pdl->isa("PDL")
| |||||||||||||||||||||||||||||
| 171 | 0 | carp "cannot call export2d without a piddle input"; | |||||||||||||||||||||||||||
| 172 | 0 | return 0; | |||||||||||||||||||||||||||
| 173 | } | ||||||||||||||||||||||||||||
| 174 | 9 | ▶ | unless ($pdl->ndims == 2) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 175 | 2 | carp "export2d may only be called on a 2D piddle"; | |||||||||||||||||||||||||||
| 176 | 2 | return 0; | |||||||||||||||||||||||||||
| 177 | } | ||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||
| 179 | # Parse additional input parameters | ||||||||||||||||||||||||||||
| 180 | 7 | ▶ | while (@_) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 181 | 9 | my $param = shift; | |||||||||||||||||||||||||||
| 182 | 9 | ▶ | if (openhandle($param)) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 183 | 5 | $fh = $param; | |||||||||||||||||||||||||||
| 184 | } else { | ||||||||||||||||||||||||||||
| 185 | 4 | $sep = $param; | |||||||||||||||||||||||||||
| 186 | } | ||||||||||||||||||||||||||||
| 187 | } | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | # Extract columns from piddle | ||||||||||||||||||||||||||||
| 190 | 7 | my @params = map {$pdl->slice("($_),")} (0..$pdl->dim(0)-1); | |||||||||||||||||||||||||||
| 191 | 7 | my $num_cols = @params; | |||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||
| 193 | # Push additional parameters for wcols | ||||||||||||||||||||||||||||
| 194 | 7 | ▶ | push @params, $fh if (defined $fh); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 195 | 7 | ▶ | push @params, {Colsep => $sep} if (defined $sep); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||
| 197 | # Write columns | ||||||||||||||||||||||||||||
| 198 | 7 | wcols @params; | |||||||||||||||||||||||||||
| 199 | |||||||||||||||||||||||||||||
| 200 | 7 | return $num_cols; | |||||||||||||||||||||||||||
| 201 | } | ||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||
| 203 | 6 | 1; | |||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | =head1 SEE ALSO | ||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||
| 207 | L<PDL> | ||||||||||||||||||||||||||||
| 208 | L<Website|http://pdl.perl.org> | ||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | =head1 SOURCE REPOSITORY | ||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||
| 212 | L<http://github.com/jberger/PDL-Util> | ||||||||||||||||||||||||||||
| 213 | |||||||||||||||||||||||||||||
| 214 | =head1 AUTHOR | ||||||||||||||||||||||||||||
| 215 | |||||||||||||||||||||||||||||
| 216 | Joel Berger, E<lt>joel.a.berger@gmail.comE<gt> | ||||||||||||||||||||||||||||
| 217 | |||||||||||||||||||||||||||||
| 218 | =head1 COPYRIGHT AND LICENSE | ||||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||
| 220 | Copyright (C) 2011 by Joel Berger | ||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | This library is free software; you can redistribute it and/or modify | ||||||||||||||||||||||||||||
| 223 | it under the same terms as Perl itself. | ||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||