.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Reduce 3pm"
.TH Reduce 3pm 2024-05-12 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PDL::Reduce \-\- a "reduce" function for PDL
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Many languages have a \f(CW\*(C`reduce\*(C'\fR function used to reduce
the rank of an N\-D array by one. It works by applying a selected
operation along a specified dimension. This module implements
such a function for PDL by providing a simplified interface
to the existing projection functions (e.g. \f(CW\*(C`sumover\*(C'\fR,
\&\f(CW\*(C`maximum\*(C'\fR, \f(CW\*(C`average\*(C'\fR, etc).
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 6
\& use PDL::Reduce;
\& $x = sequence 5,5;
\& # reduce by adding all
\& # elements along 2nd dimension
\& $y = $x\->reduce(\*(Aqadd\*(Aq,1);
\& @ops = $x\->canreduce; # return a list of all allowed operations
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS reduce
.IX Subsection "reduce"
reduce dimension of ndarray by one by applying an operation
along the specified dimension
.PP
.Vb 6
\& $x = sequence 5,5;
\& # reduce by adding all
\& # elements along 2nd dimension
\& $y = $x\->reduce(\*(Aqadd\*(Aq,1);
\& $y = $x\->reduce(\*(Aqplus\*(Aq,1);
\& $y = $x\->reduce(\*(Aq+\*(Aq,1);     # three ways to do the same thing
.Ve
.PP
[ As an aside: if you are familiar with broadcasting you will see that
this is actually the same as
.PP
.Vb 1
\& $y = $x\->mv(1,0)\->sumover
.Ve
.PP
]
.PP
NOTE: You should quote the name of the operation (1st arg) that
you want \f(CW\*(C`reduce\*(C'\fR to perform. This is important since some of the
names are identical to the names of the actual PDL functions
which might be imported into your namespace. And you definitely
want a string as argument, not a function invocation! For example,
this will probably fail:
.PP
.Vb 1
\&  $y = $x\->reduce(avg,1); # gives an error from invocation of \*(Aqavg\*(Aq
.Ve
.PP
Rather use
.PP
.Vb 1
\&  $y = $x\->reduce(\*(Aqavg\*(Aq,1);
.Ve
.PP
\&\f(CW\*(C`reduce\*(C'\fR provides a simple and unified interface to the
\&\fIprojection\fR functions and makes people coming from other
data/array languages hopefully feel more at home.
.PP
.Vb 1
\& $result = $pdl\->reduce($operation [,@dims]);
.Ve
.PP
\&\f(CW\*(C`reduce\*(C'\fR applies the named operation along the specified
dimension(s) reducing the input ndarray dimension by as many
dimensions as supplied as arguments. If the
dimension(s) argument is omitted the operation is applied along the first
dimension. To get a list of valid operations see "canreduce".
.PP
NOTE \- new power user feature: you can now supply a code
reference as operation to reduce with.
.PP
.Vb 2
\&  # reduce by summing over dims 0 and 2
\&  $result = $pdl\->reduce(\e&sumover, 0, 2);
.Ve
.PP
It is your responsibility to ensure that this is indeed a
PDL projection operation that turns vectors into scalars!
You have been warned.
.SS canreduce
.IX Subsection "canreduce"
return list of valid named \f(CW\*(C`reduce\*(C'\fR operations
Some common operations can be accessed using a
number of names, e.g. \f(CW\*(Aq+\*(Aq\fR, \f(CW\*(C`add\*(C'\fR and \f(CW\*(C`plus\*(C'\fR
all sum the elements along the chosen dimension.
.PP
.Vb 1
\&  @ops = PDL\->canreduce;
.Ve
.PP
This list is useful if you want to make sure which
operations can be used with \f(CW\*(C`reduce\*(C'\fR.
.SH AUTHOR
.IX Header "AUTHOR"
Copyright (C) 2000 Christian Soeller (c.soeller@auckland.ac.nz). All
rights reserved. There is no warranty. You are allowed to redistribute
this software / documentation under certain conditions. For details,
see the file COPYING in the PDL distribution. If this file is
separated from the PDL distribution, the copyright notice should be
included in the file.