annotation_task: Set up a face annotation task

View source: R/annotation.R

annotation_taskR Documentation

Set up a face annotation task

Description

Turns detected faces into a coding task: each face is an item that coders see outlined in its picture, with a close-up, and answer questions about, such as whether it is a face at all and which emotion it shows. Start the coding page with annotate_faces, then read the answers with read_annotations.

Usage

annotation_task(
  faces = NULL,
  classes = NULL,
  questions = NULL,
  coders = "C01",
  overlap = 1,
  dir,
  seed = 1,
  title = NULL,
  instructions = NULL,
  max_side = 1280,
  task_id = NULL,
  items = NULL,
  frames = 4,
  play = TRUE,
  blind = TRUE
)

Arguments

faces

A data frame returned by detect_faces or select_faces: one item per row. Or NULL, with items.

classes

The emotions coders choose from, for example the classes passed to face_scores. Needed by the "emotion" question.

questions

The questions, from annotation_questions. Default: annotation_questions() for faces; annotation_questions(c("emotion", "why")) for items with a label and a prediction, else "emotion".

coders

Coder ids: letters, digits, dots, dashes or underscores.

overlap

Share of the items that every coder codes, for agreement. The rest are split between the coders. Default is 1: every coder codes every item.

dir

A new or empty folder for the task.

seed

Seed for the order of the items. Each coder gets their own order. Your own random numbers are left as they were.

title

Title shown on the page.

instructions

Text shown to coders before the first item.

max_side

Longest side, in pixels, of the picture copies.

task_id

An id for the task. Coders' progress in the browser is kept under it. Default is made from the time.

items

Instead of faces: a data frame with one row per item and the columns media (path of a video or image file) and/or text, and optionally id, label (the reference label, returned as reference), prediction (the model's top class) and one column of model scores per class.

frames

For items: the number of frames shown per video clip, spread over the clip as video_scores(uniform = TRUE) samples them.

play

For items: put the clips themselves in the page, with their sound, when a browser can play them (MP4, WebM, MOV).

blind

For items: show the label, prediction and scores only after the questions without reveal are answered.

Details

With items instead of faces, each item is a video clip, an image or a text, for example the clips a model got wrong. Coders see sampled frames of the clip with its face boxes (the largest face, the one video_scores scores by default, drawn solid), the clip itself with its sound, and the item's text. When the items have a reference label and a model prediction, the page shows them with the model's scores once the coder has answered (blind = TRUE), then asks what explains the result (annotation_questions("why")). Unlike a face task, such a page holds the texts, labels and scores.

The task is a folder:

page/

The coding page: small copies of the images or video frames, under names that say nothing about the files, and the questions. It holds no file names, scores, or other coders' answers.

items.csv

Which face each item is: its file, frame, face number, track and person. For you, not for coders.

task.json

The questions, items and each coder's list.

results/

The answers, one file per coder.

Value

The task, invisibly: a list with its folder (dir), task_id, questions, coders and items (the contents of items.csv).

See Also

annotate_faces, read_annotations, annotation_agreement, consensus_labels

Examples

## Not run: 
faces <- detect_faces(system.file("extdata", "two-people.mp4", package = "transforEmotion"),
                      nframes = 20)
task <- annotation_task(faces, classes = c("happy", "sad", "angry", "neutral"),
                        coders = c("C01", "C02"), dir = "annotation-round-1")
annotate_faces(task)

# A model's errors on video clips, with their descriptions
emotions <- c("angry", "fearful", "happy", "sad")
items <- data.frame(id = errors$clip, media = errors$path, text = errors$description,
                    label = errors$label, prediction = errors$predicted, errors[, emotions])
review <- annotation_task(items = items, classes = emotions, dir = "error-review")
annotate_faces(review)
answers <- read_annotations(review)
table(answers$value[answers$question == "why"])

## End(Not run)


transforEmotion documentation built on Oct. 26, 2026, 5:07 p.m.