Understanding Sow and Reap documentation

Question

Both in Sow and in Reap documentation there is the example:

Reap[Sow[a]; b; Sow[c]; Sow[d]; e]

which gives the result {e,{{a,c,d}}}. What happens to b?

Answer 1

I'll be totally honest with you and admit that I had no idea how these functions worked (or what the point of them was) for a long time, so you're not alone in your struggle trying to understand the documentation here. This is one of those things where you first need to build the right mental picture of the language before you can start making sense of the code you're seeing here.

In this situation, it's very important that you understand the difference between a returned value and a side effect. I'll take a rather large detour here before I get back to Sow and Reap, so please bear with me.

Every time an expression is evaluated, it produces a return value. So, for example, the expression 1 simply returns 1 and 1 + 1 returns 2. There is, however, also a special return value called Null which indicates that "nothing" was returned. In particular, if Null is returned from an evaluation, no output cell will be printed in the notebook. The most well-known way to suppress any return value and turn it into Null, is by finishing your input with ;.

If you type the expression in a notebook cell, the return value will get printed in a new cell below the input except if the returned values is Null. You can still test that the returned value really is Null:

In[1]:= (1 + 1;) === Null

Out[1]= True

So what happens when you enter multiple expressions separated by semicolons? This is what is known in Mathematica as a CompoundExpression. You can verify this with Hold and FullForm:

In[2]:= Hold[
    1 + 1;
    3
  ] // FullForm

Out[2]= Hold[CompoundExpression[1 + 1, 3]]

A compound expression simply evaluates each argument in turn and then returns the last result. You'll notice that if you finish the last expression with a semicolon as well, a Null will be tagged on the end:

In[3]:= Hold[1 + 1; 3;] // FullForm

Out[3]= Hold[CompoundExpression[1 + 1, 3, Null]]

In this example, the 1 + 1 expression is really quite meaningless: it gets evaluated (if you remove the Hold, of course), but the result is never returned: it is simply forgotten about.

So is there any value in using CompoundExpression to chain expressions together? Yes, there is, but typically only when the expressions that don't get returned have side effects. The term "side effect" is basically an expensive-sounding term for things like variable/function assignment. If the evaluation of an expression changes how other expressions evaluate in the future, we say that we have produced a side effect. For example, if we evaluate x, we simply get x back:

In[4]:= x

Out[4]= x

However, if we Set a value to x by evaluating

In[5]:= x = 1 

Out[5]= 1

(or equivalently Set[x, 1]), 2 things happen:

1. x is assigned a value (an OwnValue, to be precise).
2. The value that was assigned to x is returned.

So Set produces a side effect AND a return value. The the side effect is obvious, since the same input in cell 4 now produces a different output:

In[6]:= x

Out[6]= 1

To put everything together: when you chain up a compound expression like this:

expr1; 
expr2; 
expr3;
...
finalExpression

the idea is that all expressions expr1, expr2, ... etc. build up side effects that get used in the evaluation of finalExpression.

Ok, so what does this mean for the example from the documentation?

In[7]:= Reap[Sow[a]; b; Sow[c]; Sow[d]; e]

Out[7]= {e, {{a, c, d}}}

We have seen that the inner expression is just

CompoundExpression[Sow[a], b, Sow[c], Sow[d], e]

and the return value of this is obvious: just the last argument e. This is the value you see in as the first element in the list returned by Reap.

The second element of the list returned by Reap represents side effects from Sow. All that Sow does, is:

1. Evaluate its argument
2. Store the result (let's call it value) in some internal data structure (which is a side effect). In a sense, it just does something similar to AppendTo[reapList, value], but more efficiently.
3. return value as a return value

The job of Reap is to collect all values stored inside of the internal data structure and spit it out in the second element of the list it returns.

Hopefully you now understand enough of the example to work out for yourself to read the rest of the Sow/Reap documentation to figure out how the tags work. It's a good exercise ;).