Encoding an exact couple as a module for a ring
An exact couple is a pair of R-modules E and A together with maps A --> E --> A and A --> A with the conditions that
im(A --> E) = ker(E --> A)
im(E --> A) = ker(A --> A)
im(A --> A) = ker(A --> E).
In this package, exact couples are encoded by an action of R[e,f] on the direct sum $M = A \oplus E$, where e acts by the maps A --> E --> A, f acts on A by the map A --> A, and on E by 0. A ring of the form R[e,f] form is called a 'couple ring' and the degrees of its variables must satisfy the conditions in expectCoupleRing.
The module E is the "page" and the module A is the "auxiliary". Typically, E and A occupy disjoint sets of degrees, termed "even" and "odd". The terms of the spectral sequence live in even degrees, since they come from the page. The auxiliary data lives in odd degree.
Constructing exact couples
Exact couples arise in algebra any time a chain complex $C=(C,d)$ carries a self map $f : C \to C$. Setting $A = H_* C$ to be the homology of $C$, and $E=H_* C(f)$ to be the homology of the mapping cone of $f$, we have a long exact sequence
... —-> A —-> E —-> A --f--> A —-> ...
defining the maps in the exact couple.
The all-purpose method exactCouple accepts as input C considered as an $R[d,f]/d^2$ module. Note that the action of $d$ and $f$ is encoded by the ring action.
To build exact couples by hand, use declareCouple, and check your work with isHomogeneous and expectExactCouple. For the usual long exact sequence induced by a map of complexes, use longExactSequence. Once you have an exact couple, derivedCouple produces another, as we now explain.
Derived couples
Every exact couple determines a new exact couple by the formulas $A' = im(f)$ and $E' = ker(e^2)/im(e^2)$. The maps $A' \to E' \to A'$ are induced by $e$, and the map $A' \to A'$ is induced by $f$. There is a wrinkle, however: the map $A' \to E'$ factors $A' \to A / ker(f) \to E'$, making use of the first isomorphism theorem. Some degree confusion can result. Indeed, the inclusion $A' \subseteq A$, which is induced by the identity, is a degree 0 map; in contrast, the projection $A / (ker f) \to A'$, which is induced by $f$, has the same degree as $f$ itself. This forces the inverse map $A' \to A / ker(f)$ to have degree $-deg(f)$.
If we had taken A' to be the coimage of f instead of the image, this would have resulted in different degrees. So either of these conventions would have an asymmetry: an unjustified preference for image or coimage.
We use neither convention. Instead, we place A' exactly halfway between (image f) and (coimage f). This has the effect of giving the comparison maps $A \to A' \to A$ the same degree, namely, $(degree f)/2$. (This division-by-two accounts for the requirement in expectCoupleRing that the degree of $f$ be even.)
The new degrees can be expressed in terms of the old:
$ degree f' = degree f$
$ degree e' = (degree e) - (degree f) / 2$.
The resulting ring $R[e',f']$ is the derived couple ring of $R[e,f]$; it acts on the derived couple, and can be obtained using derivedCoupleRing.
How to determine $deg(e)$ and $deg(f)$ in your example
Suppose you have in mind a particular spectral sequence of $R$-modules, starting on page k, and you want to program its exact couple. What degrees should you use for the couple ring $R[e_k,f_k]$?
Think about the degree of $D_k$, the differential on the starting page. This tells you the degree of $e_k$:
$deg(e_k) = deg(D_k)$.
Now think about the degree of $D_{k+1}$, the differential on the next page. This lets you compute the degree of $f_k$:
$deg(f_k) = 2 * deg(D_k) - 2 * deg(D_{k+1})$.