RFC: Correct-a-Cell

[srallen]

CSSI "Correct-a-Cell"

Context

Part of the desired set of features for Etch-a-Cell as part of the CSSI effort is to correct machine drawing outlines of the structures inside the cell. These outlines could be needing correction, so the idea is to present the outlines to the volunteer and then the volunteer could correct the outlines and resubmit these as new classifications. (Note: going forward these machine outlines will be referred to as machine generated freehand line marks).

This is similar conceptually to the transcription task's use of previous transcriptions. In that task, volunteers are presented from previous marks and transcriptions from other volunteers and have the opportunity to submit new transcriptions with corrections.

How to load previously created classifications

Caesar reductions

The transcription task is deeply coupled with Caesar functionality. It expects a set of extract and reduction rules to be defined. The initial set of classifications from volunteers are ingested downstream by Caesar, then is setup with an external extractor and a reducer using functionality defined in the aggregation-for-caesar service (transcription task example.

The front-end app is built to request from Caesar the resulting reductions and store them in a TranscriptionReductions model. When a workflow setup with the transcription task is loaded, the TranscriptionReductions model is instantiated and the reductions for Caesar is requested for. If there are reductions, then the data is processed and used to render the actual marks and associated previous transcriptions on the subject.

How to render the reductions on the subject

The SingleImageViewer subject viewer uses an interactive SVG layer to render drawing marks and to listen to events to interact with them. One of the layer's function is to conditionally render previous transcription marks if they exist. The TranscribedLines component renders the lines with the various possible states depending on the data of the reduction.

The reductions can result in two different lines: incomplete or complete. A complete line is considered to be retired with three transcriptions submitted by three different volunteers having reached consensus. This renders as a gray line which can only be interacted with to view what the transcription is, but with no other interactivity. An incomplete line is a transcription that has not reached consensus and needs possible correction to be able to reach consensus. The volunteer can select a previous transcription from a subtask pop up menu to get started with and then submit a new annotation consisting of a transcription line mark reusing the same x, y points as well as the new text transcription with correction.

Subject retirement

Since each reduced line has an individual consensus state indicating completeness, another mechanism needs to be used to determine overall retirement of the subject on Panoptes. The transcription task uses a second question task to ask if all of the transcription line marks have turned gray for all of the pages. If this the answer to this question receives yes from five different volunteers, then the subject itself is retired.

Decision

The transcription task functionality could be adapted or modeled from for the Etch-a-Cell use case.

Loading machine classifications from Caesar

Currently the function to be able to load machine produced extracts is being added to Caesar (zooniverse/caesar#1336). This functionality could be used in the correct-a-cell case where the machine produces a set of possible outlines and uses the same drawing classification JSON structure conventions to be ingested into Caesar as extracts. These extracts could then be reduced into a data format that the front-end app could load and render onto the subject.

Currently, the request to load Caesar reductions is coupled to the transcription task use case, so some possible changes will need to happen to the front-end app codebase:

• The first option would be to abstract out the async fetch request action from the TranscriptionReductions into its own generic CaesarReductions model. The request depends on a reducer key parameter that the TranscriptionReduction and other composed models could define for the request. The Etch-a-Cell use case would have its own reductions model composed from the generic CaesarReductions model to define any other functions it might need. Taking the time for abstraction will be more time up front now, but may be worth it if we anticipate other drawing task projects wanting this kind of functionality in the future.
• The second option would be to directly just create a model specific Etch-a-Cell use case and skip the abstraction. This option would be faster to build, but if another request for this type of functionality comes up for another drawing task project, then we would be faced with this same decision again of whether to abstract out commonality in to reusable code.

How to render reductions on the subject

Since the current reduction rendering functionality is coupled with the transcription task and mark, the Etch-a-Cell version will either need a generalized previous mark component that could possibly be reused by both the transcribed line mark and this new previous freehand line mark or build its own previous freehand line mark component specific to this use case. The decision to be made is similar to the above decision in spending the time now with abstraction or saving time now but maybe having more development time later if there may be more projects who want to do this.

User interaction and experience

One reason to possibly spend the time abstracting the component is to plan on using similar states and interactions to make the experience consistent and predictable for the volunteers. The following decisions need to be made about the correct-a-cell interaction:

• How will the previous mark be editable? Will it use the undo/redo functionality being added to the freehand line tool? Will it use some other edit mode or tools?
• How will the machine generated freehand line marks be distinguished visually from a new mark? Will it be distinguished by color state with tool tips like the transcription line marks?
• Will clicking on the machine generated freehand line mark result in a new mark reusing the same SVG path and coordinates like the previous transcribed line mark does? If so, then this action could possibly be abstracted and reused between both types.
• If clicking on the previous freehand line mark generates a new mark, then should the original machine mark be hidden from display?
• Will there be a consensus state displayed for previous marks like we do for transcribed marks?
• Will volunteers be editing multiple marks per subject?

How the volunteer interacts with the machine generated freehand line marks should have consistency with their interaction with new freehand line marks, so some of these questions should have proposed solutions now so that they can be incorporated into the work toward the freehand line tools.

Status

Proposed

Consequences

• Depending on the editing interaction the user makes on the machine generated freehand line mark, this will have impact on the current development on the freehand tool. This is because we want consistent and predictable user interaction with our drawing tools.
• The previous transcribed line marks are always visible even if a new mark is created starting from it. If we hide the machine generated marks once a new one is started in the correct-a-cell use case, then if any of the rendering logic is reused, then we'll need to make this configurable and conditional for the render.
• An overall decision should be made of how much can and should be abstracted from the transcription task use. This will impact development time invested in this now. This is predicated on if we think other drawing task type projects will want to be able to do this.

[srallen]

Once some more of the decisions are actually made, this can be converted into an actual ADR.

[eatyourgreens]

Now that we have the useCaesarReductions hook, each task can define a model for the reductions that will be returned by the hook.

Transcription tasks use a TranscriptionReductions model, and the Subject model has a generic CaesarReductions model which is a union of all available Reductions models. Other tasks can be added by adding new Reductions models to the union here:

front-end-monorepo/packages/lib-classifier/src/store/subjects/Subject/Subject.js

Line 8 in 9a1383e

const CaesarReductions = types.union(TranscriptionReductions)

[eatyourgreens]

So, for example, if we were to define a new FreehandReductions model and add it to that union, the rest of the classifier code should automatically request those reductions and inject them into the subject viewer. The only other change that would be needed is adding code to render those reductions in the viewer.

At the moment, transcription tasks have a useTranscriptionReductions hook which requests the Caesar reductions here:

front-end-monorepo/packages/lib-classifier/src/hooks/useTranscriptionReductions.js

Line 26 in 9a1383e

const { loaded, caesarReductions } = useCaesarReductions(workflow.caesarReducer)