[frames] | no frames]

# Module red

source code

`red -r [BINARY_FUNCTION ...]`

Aggregates (reduces) objects from the input stream in a simpler but less general way than the `agg` command.

A `BINARY_FUNCTION` takes two inputs and produces one output. Binary operators and user-defined functions can be used as `BINARY_FUNCTION`s. Given a sequence of inputs such as `(1,), (2,), (3,)`, `red` can be used to find the sum:

```   ... ^ red +
```

yields `(6,)`. If each input sequence contains multiple values, then multiple `BINARY_FUNCTION`s can be provided. For example, to find the sums of the first 10 integers, the sum of their squares, and the sum of their cubes:

```   osh gen 10 ^ f 'x: (x, x**2, x**3)' ^ red + + + \$
```

which yields the output `(45, 285, 2025)`.

If `.` is provided as one of the `BINARY_FUNCTION`s, then that value is not aggregated. Instead, aggregation is done for the groups defined by the indicated elements. For example, suppose the input sequence is:

```   (1, 10, 5, 100)
(1, 10, 6, 200)
(1, 11, 4, 100)
(1, 11, 3, 200)
(2, 20, 8, 100)
(2, 20, 9, 200)
(2, 20, 10, 300)
(3, 30, 5, 100)
```

If this sequence is piped to this invocation of `red`:

```   red . . + +
```

Then the output sequence would be:

```   (1, 10, 11, 300)
(1, 11, 7, 300)
(2, 20, 17, 300)
(3, 30, 5, 100)
```

The two `.`s, in the first two positions, mean that the groups used for aggregation are `(1, 10)`, ```(1, 11)```, `(2, 20)`, and `(3, 30)`. The ```(1, 10)``` group has two rows, `(1, 10, 5, 100)`, and `(1, 10, 6, 200)`. The two `+`s mean that the items in the last two fields should be summed. Adding the items in the third position, 5 + 6 = 11; and in the last position, 100 + 200 = 300.

If the `-r` flag is specified, then one output object is generated for each input object; the output object contains the current accumulated values. The accumulator appears in the output row before the inputs. For example, if the input stream contains ```(1,), (2,), (3,)```, then the running total can be computed as follows:

```   ... ^ red -r + ^ ...
```

The output stream would be `(1, 1), (3, 2), (6, 3)`. In the last output object, `6` is the sum of the current input (`3`) and all preceding inputs (`1, 2`).

The `-r` flag can also be used with grouping. For example, if the input objects are ```('a', 1), ('a', 2), ('b', 3), ('b', 4)```, then the running totals for the strings would be computed as follows:

```   ... ^ red -r -g 'x, y: x' 0 'sum, x, y: sum + y' ^ ...
```

The output stream would be ```(1, 'a', 1), (3, 'a', 2), (3, 'b', 3), (7, 'b', 4)```.

Functions

 red(binary_functions, running=False) `binary_functions` is a sequence. source code
 Function Details

### red(binary_functions, running=False)

source code

`binary_functions` is a sequence. Each element of `binary_functions` is either None or a binary function. If no elements are `None`, then the binary function in position `i` is used to reduce the values in element `i` of the input sequences. If there are `None` values, then these are used to define groups of inputs, partitioning by the values in the indicated columns. The remaining binary functions then compute reductions within each group. If `running` is `False` then there is one output tuple in the absence of grouping; otherwise there is one tuple output per group. If `running` is {True}, then the aggregate value computed so far is written out for each input, i.e., the output contains "running totals". In this case, the aggregate value appears before the input values.

 Generated by Epydoc 3.0.1 on Sun Oct 3 15:23:48 2010 http://epydoc.sourceforge.net