Audit Logging for Bounded Proofreading Decisions

Welcome back. You have now worked through the full safety loop for a proofreading decision: inspect the EM evidence, check the 3D morphology, make a bounded edit only when warranted, review its consequences, and stop rather than speculate when uncertainty remains.

This final lesson in the module turns those individual actions into an audit trail. Your objective is to produce a compact audit log for a small, bounded set of cases: perhaps three to five candidate errors from one focused session. Each entry must state what you decided, what you observed, what changed if you edited, and how another person could reopen the evidence. This is the bridge between careful individual proofreading and reproducible connectomics work.

---

Why an audit log is part of proofreading

A reconstruction edit changes shared scientific data. The visible neuron is only the current result; without a record, it can be difficult to tell:

• what problem was originally suspected;
• whether a change was a merge, a split, or merely a display action;
• which image evidence justified the decision;
• whether the reconstruction was reviewed after the edit;
• why an apparently suspicious region was deliberately left unchanged.

Think of the audit log as a small, case-oriented commit history. A source-control commit message such as “fix issue” is not useful six months later; a message that names the component, observed bug, scope, and verification is. The same standard applies here, except that the evidence is the EM imagery and neuronal morphology.

An audit log is not a diary of every click. It records decisions at a useful scientific resolution:

1. A case is a bounded candidate issue at a specified location.
2. A decision is one of: edited, reviewed without editing, unchanged, or escalated.
3. An evidence record says what was checked in 2D and 3D.
4. An outcome record captures the reconstruction state after an edit, or the reason no edit was made.

The “unchanged” category is essential. Leaving a reconstruction untouched can be the strongest decision when the apparent problem is a projection artifact, a legitimate nearby neurite, or an ambiguity that the available imagery cannot resolve.

---

Roots, edits, and why identifiers belong in the log

FlyWire segmentation is not a static collection of neuron IDs. A root ID represents a collection of atomic segmentation units, called supervoxels. A merge or split creates new root IDs, so a log that says only “edited neuron 123” can become ambiguous after subsequent work.

Read the relevant parts of the A primer on the FlyWire segmentation tutorial from the fafbseg documentation. It gives the technical basis for recording root IDs and later checking an edit history.

Two consequences follow.

First, always distinguish:

Identifier or reference	What it establishes	Why record it
Case ID	Your stable local label, such as PF-2025-01-C03	Lets you discuss the case even if FlyWire roots change
Location	Where the visual evidence was inspected	Lets a reviewer reopen the EM region
Root ID before decision	The segmentation state you inspected	Anchors the original object
Root ID after an edit	The resulting state	Makes the effect of the edit traceable
Operation ID, if available	A particular recorded merge or split	Links your note to platform history
Share link	A practical route back to the view	Preserves the review context better than an arbitrary browser URL

Second, edit history supports an audit record but does not prove an edit was correct. A history query can establish that an operation occurred at a time and changed particular roots. It cannot establish that membranes and cytoplasmic continuity justified the operation. Your log needs both forms of evidence.

---

Define a bounded case set before logging it

A log becomes manageable when its scope is explicit. Do not open a sprawling “all suspicious things in this neuron” case. Instead, define a case set such as:

“Four candidate reconstruction issues encountered while inspecting one selected neuron and its nearby branches during a single session.”

For every case, record the same minimum context before deciding whether to edit:

• Dataset and working context: dataset or segmentation layer, date, and any task or project context.
• Case location: the coordinates exactly as displayed in FlyWire. Do not silently convert coordinate systems or invent units.
• Target context: target root ID at inspection time, plus any neighboring root ID directly involved.
• Candidate classification: false split, false merge, missing branch, no defect found, or uncertain.
• Evidence window: how many adjacent image sections you inspected and in which direction.
• 3D check: the specific morphology question you checked, such as “does this branch create an implausible foreign side branch?” rather than simply “checked 3D.”

The FlyWire interface keeps the 2D imagery, 3D segmentation, and annotation controls in one working environment. A Share link captures the navigable context, while your written evidence explains what that context means.

A practical boundary rule is: one case, one principal decision. If inspecting a false merge reveals a separate possible false split nearby, create a second case ID. This prevents one vague note from concealing several independent claims.

---

A log format that is compact but reviewable

For a small case set, use a simple Markdown table, CSV file, or notebook DataFrame. The format matters less than preserving the same fields for every case. Keep a concise case register and put longer observations in an accompanying evidence note.

1. Case register

Use this as the top-level table.

Case ID	Coordinates	Candidate issue	Decision	Edit or disposition	Before roots	After roots	Evidence note
PF-01	x, y, z as displayed	Likely false split	Edited	Added disconnected target piece after review	root A, root B	new root C	PF-01
PF-02	x, y, z as displayed	Possible false merge	Reviewed, no edit	Escalated: boundary remains ambiguous	root D, root E	Not applicable	PF-02
PF-03	x, y, z as displayed	Apparent missing branch	Unchanged	No defect found after stack review	root F	Unchanged	PF-03

The decision field should communicate the result immediately:

• Edited: a merge or split was submitted.
• Reviewed, no edit: a real concern remains, but evidence was insufficient or the case was escalated.
• Unchanged: investigation found that no reconstruction change was needed.
• Corrective edit: a prior incorrect edit was repaired under the appropriate authorization and evidence standard.

Avoid writing “fixed” as the entire disposition. State the action: added disconnected segment, removed incorrectly attached material, or no edit because the objects remain separate across the inspected stack.

2. Evidence note template

For each row, add a short structured note. This is the scientific content of the audit log.

Case ID:
Inspection context:
Share link:
Target root(s) at inspection:
Candidate classification:

2D evidence:
- Adjacent sections inspected:
- Continuity or boundary observed:
- What distinguishes the target from the neighbor:

3D evidence:
- Local morphology checked:
- Whole-cell consequence checked:

Decision:
- Edited / reviewed without edit / unchanged / escalated
- Exact action or reason for no action:

Post-decision verification:
- If edited: target, other output or attached material, and whole morphology reviewed
- If unchanged: why no reconstruction change is justified

Resulting root(s) and operation ID, if available:
Uncertainty and follow-up:

This form does not require lengthy prose. It requires testable statements. Compare these two versions:

Weak note	Auditable note
“Looked like a split, merged it.”	“Candidate false split at recorded location. The two selected pieces show continuous cytoplasm across three sections before and two after the gap; no membrane boundary is visible. In 3D, the detached piece forms a continuation of the target’s distal branch. Added the disconnected piece, then inspected both the joined target and the former detached output. No new foreign branch observed.”
“Probably a merge, did nothing.”	“Possible false merge. A narrow boundary is visible in two sections, but membrane contrast is lost in the adjacent sections and 3D ownership cannot be assigned confidently. No edit made; Share link and both roots recorded for review.”

The second notes make it possible to disagree with the interpretation while still understanding exactly what was seen and done.

---

The audit workflow: record evidence before action

The most reliable audit log is built while you proofread, not reconstructed from memory at the end of a session. Use this sequence for each case.

1. Open the case record before editing

Assign the case ID, copy the displayed coordinates and Share link, and record the roots currently selected. If you later edit, this preserves the pre-edit state that may otherwise disappear behind new root IDs.

2. Separate observation from interpretation

Write the visual observation first:

• “Target-colored segmentation terminates while a nearby component begins.”
• “A membrane boundary appears between the target and attached process.”
• “Continuity is visible in two sections but obscured in the next three.”

Then state your interpretation separately:

• “Likely false split.”
• “Likely false merge.”
• “Uncertain due to image ambiguity.”

This separation makes the note much easier to review fairly. A future reviewer may challenge the interpretation but still benefit from the underlying observation.

3. State the decision and its scope

If you edit, name the operation and the material affected. If you do not edit, say why:

• insufficient membrane visibility;
• unclear identity of the neighboring process;
• potential path-swap-like complexity;
• visual inspection shows the suspected defect is not actually present;
• review requested from the project’s supported workflow.

“No edit” is a complete decision only when paired with a reason and evidence reference.

4. Verify, then append rather than overwrite

After an edit, conduct the post-edit review already established in the previous lessons:

1. inspect the edit site across adjacent EM sections;
2. inspect the local 3D reconstruction;
3. inspect the wider target morphology;
4. inspect the other split output or newly attached material.

Then append the outcome to the case note. Do not erase the original suspicion or replace “likely false split” with “resolved.” The useful history is:

• what you suspected;
• what you changed;
• what you verified afterward;
• what uncertainty remains.

This append-only habit is especially important when a correction becomes necessary. A corrective operation should appear as a new event in the same case record, with its own evidence and post-edit review.

---

Interpreting effort and accuracy responsibly

Proofreading is iterative. Later review rounds often require fewer edits because the most obvious segmentation errors have already been addressed, while reconstruction-quality scores can improve sharply from the automated starting point.

Do not use edit count as a productivity metric by itself. A lower number of edits can mean that a case set is cleaner, that proofreaders are working more selectively, or that they are missing errors. The audit log gives edit counts their context:

• an edited case records the evidence and result;
• a reviewed, no-edit case records unresolved uncertainty;
• an unchanged case records why an apparent error was rejected.

That distinction prevents a misleading conclusion such as “more edits means better proofreading.”

---

A completed miniature audit example

Here is what a bounded three-case set could look like after one session. The IDs and coordinates are deliberately placeholders; use values from your own FlyWire session.

Case ID	Candidate	Decision	Supporting evidence	Outcome
PF-01	False split	Edited	Target and detached component display cytoplasmic continuity through five inspected sections. The detached component continues the target’s branch in 3D.	Addition submitted. New root and any operation ID recorded. Post-edit inspection found continuous morphology and no detached target-like stump.
PF-02	False merge	Reviewed, no edit	A possible membrane boundary is visible locally, but contrast degrades in neighboring sections. The 3D branch assignment remains ambiguous.	No edit. Both roots, coordinates, Share link, and escalation note recorded.
PF-03	Missing branch	Unchanged	What appeared as a missing branch in one section is visible as a neighboring neurite in adjacent sections. In 3D, it does not connect to the target’s trusted arbor.	No defect found. Target root remains unchanged; no follow-up required unless new evidence emerges.

Notice that each case ends in a meaningful outcome, even though only one produced an edit. That is what a complete audit log looks like: it represents evidence-based decisions, not merely operations.

Before closing the session, do a final consistency pass:

• Every case has a location and a Share link.
• Every edit has before and after root information where available.
• Every decision has both 2D and 3D evidence, or explicitly states why one could not be resolved.
• Every no-edit decision says whether it is unchanged or escalated.
• Every edited case includes a post-edit morphology review.
• The scope of the case set is written at the top of the log.

---

Key takeaways

An audit log makes proofreading reviewable and scientifically useful:

• Define a small, explicit case set rather than collecting vague observations.
• Give each candidate issue a stable local case ID, location, Share link, and root context.
• Separate visual observations from interpretations and decisions.
• Record edited, reviewed without edit, and unchanged outcomes with equal care.
• Treat root IDs as time-dependent references: splits and merges create new roots, so preserve before and after identifiers when possible.
• Use edit history as a cross-check for what occurred, not as evidence that the operation was visually justified.
• Append post-edit verification and later corrections rather than overwriting the original record.

You have now completed the practical proofreading module. The next module shifts to reproducible programmatic analysis: you will configure an authenticated Python notebook and record the FlyWire release, materialization version, and coordinate system that make later queries interpretable.