RFC: PDL Cheat Sheet

[lin0]

Greetings Fellow Monks,

Motivated by BrowserUk reply to a node on PDL references and inspired by the Perl cheat sheet, I decided to put together this Perl Data Language (PDL) cheat sheet.

---

PDL 2.4.3 cheat sheet v2 by Lino Ramirez, Lino.M.Ramirez at gmail.com
NOTE:
Piddles are stored in (column, row) order

STARTING & QUITTING THE SHELL       GETTING HELP
perldl    exit    quit              help 'func'    ? 'func'
                                    apropos 'func' ?? 'func'
SHELL CONFIGURATION FILES           sig 'func'     
$HOME/.perldlrc                     usage 'func'
PDL/default.perldlrc                demo
local.perldlrc
                              USING AUTOLOADER
WRITING PERL SCRIPTS          use PDL::AutoLoader;
use PDL;                      # environment variable PDLLIB defines
                              # the search path for AUTOLOADER module
CREATING PIDDLES
new       pdl        topdl          TYPE CONVERSIONS
null      zeroes     ones           ushort    float    long  convert
identity  random     grandom        byte      double   short
randsym   sequence
xvals     yvals     zvals           FILE I/O
xlinvals  ylinvals  zlinvals        fits    wfits  rcols  wcols  rcube
rvals     axisvals  allaxisvals     rpic    wpic   rim    wim    rgrep

OPERATORS                           COPYING PIDDLES
+    -    *    /    **    >    <    $pnew = pdl( $pold );
>=   <=   ==   !=   <<    >>   &    $pnew = $pold->copy;
|    ^    +=   -=   *=    /=   %=
**=  >>=  <<=  &=   |=    ^=        EXTRACTING INFORMATION
<=>  !    %    ++   --              slice dice dice_axis diagonal

ADDITIONAL OPERATORS                LOCATING INFORMATION
.=    assignation                   index  index2d   indexND    where
x     matrix multiplication         which  whichND   which_both

GETTING PIDDLES' PROPERTIES         MODIFYING PIDDLES
? vars    PDL->px    info           list      listindices      one2nd
dims      getdim     getndim        set       clip   rotate    xchg
howbig    nelem      at             reshape   mv     reorder   dummy
                                    transpose clump  splitdim
COMBINING PIDDLES
append   glue   cat   dog           ELEMENTARY MATH FUNCTIONS
                                    abs  acos  acosh asin asinh
VECTOR FUNCTIONS                    atan atan2 atanh cos  cosh
inner    outer    uniq              sin  sinh  tan   tanh sqrt
in       setops   norm              ceil floor rint  exp  log log10

DATA ANALYSIS                       SPECIALIZED MATH FUNCTIONS
stats   statsover   qsort           bessj0  bessjn  bessy0  bessyn
sum     sumover     cumusumover     erf     erfc    erfi    intover
max     maximum     maximum_ind     lags    lgamma  pcoef   simplex 
avg     average     qsorti          fibonacci
min     minimum     minimum_ind     
minmax  minmaximum  median          DATA INTERPOLATION
medover oddmedian   oddmedover      fitgauss1d  fitgauss1dr  fitpoly1d
prod    prodover    cumuprodover    interpol    interpolate  ninterpol
hist    histogram   histogram2d     interpND    lmfit
and     and2        andover         polfit      pvalue       polycoef
or      or2         orover          polyfit     polyvalue

MATRIX OPERATIONS                   IMAGE PROCESSING
inv  matinv eigens_sym  eigens      cquant rgbtogr rot2d med2d conv2d
svd  eigsys determinant det simq    warp2d rebin   convolveND

TWO-DIMENSIONAL PLOTTING            THREE-DIMENSIONAL PLOTTING
use PDL::Graphics::PGPLOT;          use PDL::Graphics::TriD;
dev  env  line  points  errb  bin   imag3d imag3d_ns imagrgb points3d
cont ctab vect  poly    imag        line3d lattice3d mesh3d grabpic3d
circle  ellipse    rectangle text   keeptwiddling3d  nokeeptwiddlin3d
legend  draw_wedge release   hold   twiddle3d  hold3d  release3d

FOURIER TRANSFORM FUNCTIONS         COMPLEX NUMBERS FUNCTIONS
use PDL::FFT;                       Cabs Carg Cp2r Cr2p i2C r2C
fft  fftnd  realfft realifft        
ifft ifftnd cdiv    cmul            MISCELANEOUS FUNCTIONS
kernctr  fftconvolve                inplace  trace  thread
                                    band bandover bitnot bor borover
PDL MODULE DEPENDENCIES             all   any   isempty  zcheck
Perl 5.6.1+ (5.8.x recommended)
ExtUtils::MakeMaker (latest version)    LINKS
C-compiler   Fortran compiler           pdl.perl.org
PGPLOT libraries & C-binding (PGPLOT)   perlmonks.org
OpenGL or Mesa  (TriD)                  search.cpan.org/dist/PDL/
netpbm package (PDL::IO::Pic)           pdl.sourceforge.net/PDLdocs/

---

As always, any comment will be welcome

Cheers,

lin0

Updates:

1. Added the references suggested by zentara
2. Added FFT references and shuffled things around to make them fit

[zentara]

Here is an interesting tidbit for people just learning. You always want to print your piddles to see what you are doing wrong, but PDL has a limit set of 30000 elements, and if your piddles exceed that, you get the dreaded 'TOO LONG TO PRINT' error message. Fortunately the PDL modules have easy-to-override subs, so you can use this module to print any size piddle.

Include this somewhere in your PERL5LIB, and

use pdldump;

#  file   pdldump.pm
package PDL::Core;

my $max_elem = 10000000;  # set your max here

sub PDL::Core::string {
   my ( $self, $format ) = @_;
   if ( $PDL::_STRINGIZING ) {
      return "ALREADY_STRINGIZING_NO_LOOPS";
   }
   local $PDL::_STRINGIZING = 1;
   my $ndims = $self->getndims;
   if ( $self->nelem > $max_elem ) {
      return "TOO LONG TO PRINT";
   }
   if ( $ndims == 0 ) {
      if ( $self->badflag() and $self->isbad() ) {
         return "BAD";
      }
      else {
         my @x = $self->at();
         return ( $format ? sprintf( $format, $x[ 0 ] ) : "$x[0]" );
      }
   }
   return "Null"  if $self->isnull;
   return "Empty" if $self->isempty;    # Empty piddle

   local $PDL::Core::sep  = $PDL::use_commas ? "," : " ";
   local $PDL::Core::sep2 = $PDL::use_commas ? "," : "";
   if ( $ndims == 1 ) {
      return PDL::Core::str1D( $self, $format );
   }
   else {
      return PDL::Core::strND( $self, $format, 0 );
   }
}

1;

[BrowserUk]

This looks (after a minimal and superficial scan) extremely useful. Many thanks for producing this.

PDL is one of those modules that I have had several half hearted attempts at getting to grips with. A lack of a real need to do so, and many other interesting problems with which to occupy my mind that have less steep learning curves or more immediate satisfaction criteria mean that I have yet to make any real in roads to its possibilities.

This may just reduce the gradient of the learning curve, or facilitate such, that I actually use it to solve or progress one of the many stalled projects sitting on my back boiler.

[lin0]

Hi BrowserUk

I am glad you think you can use this "cheat sheet" :-)

I completely agree with you in that PDL has a steep learning curve. This is why, I am preparing a set of tutorials to help people getting started with it. So, please, keep an eye open that more tutorials are forthcoming :-)

Cheers,

lin0

[BrowserUk]

You know, looking back at some of my attempts at using PDL, a simple tie interface wrapper that allows you to treat piddles as normal arrays would greatly reduce the gradient?

I realise that it probably wouldn't be as efficient, but it might allow an easier start and once you get stuff going, it should be fairly 'algorithmic' to convert it back to native calls to squeeze out that last ounze of performance.

Anyway, I'll keep my eyes open for the tutorials. Thanks again.

[zentara]

One other comment pertaining to the cheetsheet, maybe you should at least mention the ~.perldlrc file and the ~/PDLLIB directory.

[lin0]

Hi zentara,

Thank you very much for your comments. I just updated the sheet to include your suggestions. Below is a sample 'perldlrc' file for those interested

Cheers,

lin0

# $HOME/.perldlrc
#
# startup file for perldl shell
# 
# This file must be placed in your home directory.
# perldl will look for it during start-up to load
# default modules, set shell variables, etc.
# If this file is not present, perldl will look for
# PDL/default.perldlrc.
# The advantage of using .perldlrc, is that you can 
# choose which modules to load by default
# 
# Note: local defaults can be set using a file named
#       local.perldlrc
#
# For more information, please, have a look at:
# http://pdl.sourceforge.net/PDLdocs/perldl.html
#

# Commands from the default startup for perldl shell.
use PDL;
use PDL::Dbg;  # Enable useful commands

# PDL waffle options (and pacify -w)
BEGIN{
   $PDL::debug = $PDL::debug = 0;
   $PDL::verbose = $PDL::verbose = 1;
}

use PDL::Doc::Perldl; # online docs module

#
# Some modules to load by default.
# Feel free to add or delete modules from the list
#
use PDL::Graphics::PGPLOT;  ## use 2D plotting package
use PDL::Graphics::PGPLOT::Window;
use PDL::Graphics::TriD;    ## use 3D plotting package
use PDL::Image2D;

#
# Loading the AutoLoader module that implements a MatLab
# style AutoLoader for PDL. If a unknown function 'func()'
# is called then a file 'func.pdl' is searched for and if
# found is read in to define 'func()' which is then executed.
# The environment variable PDLLIB defines the search path
# used when looking for the file 'func.pdl'
# e.g. in bash:
#              export PDLLIB=/home/lmr/pdllib:/local/pdllib
#      in csh:
#              setenv PDLLIB "/home/lmr/pdllib:/local/pdllib"
#
use PDL::AutoLoader;
$PDL::AutoLoader::Rescan = 1;  # Rescan .pdl files each time a prompt 
+goes out


#
# Set up perldl shell special variables
#
$PERLDL::MULTI = 1;   # Accept multi-line perl blocks
$PERLDL::NO_EOF = 1;  # Prevent from accidentally exiting perldl by ty
+ping ^D

#
# Greeting...
#
print "\nWelcome back!\n";
print "\nType 'help' or '?' for basic help.\n";

1; # Successful completion

[toma]

The cheat sheet looks great!

It includes all the PDL functions that I have used except for PDL::FFTW.

I evaluated PDL for audio signal processing, but ended up using C++ to create real-time low-latency audio applications using the Jack Audio Connection Kit.

[lin0]

Hi toma,

Thank you very much for your comments. I will add some of the functions of PDL::FFTW in a day or two. Do you know about other functions that should be in the cheat sheet?

I am trying to prioritize the information to include, in the cheat sheet, only information that people need to know and information that people should know. I am doing that to have a cheat sheet that is both useful and concise.

Cheers,

lin0

[lin0]

Hi toma,

I decided to include, first, functions from the PDL::FFT. I will include functions from PDL::FFTW as soon as I can make up my mind of other set of functions I could add to keep the formating of the cheat sheet.

Cheers,

lin0

[syphilis]

I will include functions from PDL::FFTW ...

PDL::FFTW only works with an outdated version of the FFTW library. If someone intelligent (that's my escape clause) likes to rewrite PDL::FFTW so that it works with the latest version of the FFTW library, that would be a most welcome improvement to PDL. (This has been on the PDL 'todo' list for quite some time.)

Btw, ++ to you, lin0 for what you've provided in this thread.

Cheers,
Rob