Cavity-Nesting Bird Freelists from Rural Children

# Free-listing native cavity-nesting birds, after Bonaparte et al. 2024
#
# Dataset: Bonaparte, Ibarra, Liefländer, Sosa, and Cockle (2024). "Rural
#   children know cavity-nesting birds of the Atlantic Forest but may
#   underappreciate their critical habitat." Dryad dataset, version 5.
#   DOI: 10.5061/dryad.kkwh70sd8
#   https://datadryad.org/dataset/doi:10.5061/dryad.kkwh70sd8
#   Licence: CC0 1.0 (DataCite rights record "Creative Commons Zero v1.0
#   Universal").
# Paper: Bonaparte, E. B., Ibarra, J. T., Liefländer, A. K., Sosa, M. H., and
#   Cockle, K. L. (2024). Ornithological Applications 127. Oxford University
#   Press. DOI: 10.1093/ornithapp/duae052
#   https://doi.org/10.1093/ornithapp/duae052
#
# What the study did (Methods text as given on the Dryad dataset page; the
#   article itself could not be fetched, so these quotes are not checked
#   against the OUP article):
#   Each child received "a sheet of paper with spaces to write their name, age,
#   and grade, followed by ten numbered rows to write the names of bird
#   species." The children were instructed "to write down the ten species of
#   native birds they knew that lived in the wild on farms that first came to
#   mind." Children who knew fewer than ten "could write down as many as they
#   could", and children who knew more "had the option to continue writing on
#   the back of the paper." Afterward each child received a highlighter and was
#   asked "to highlight only the species on their lists that they considered
#   to nest in tree cavities." The abstract reports 235 children from 19 rural
#   schools; the Methods text on the Dryad page says 236 students aged 10 to 13.
#
# Analysis the list format supports: the paper computes the salience of each
#   item as (n + 1 - k) / n, where n is the number of birds listed and k is
#   the rank at which an item was listed, then Smith salience across lists.
#   The free_list scheme keeps the order each item was typed in, which is the
#   data that formula needs. Potato's cultural_domain export computes salience
#   from the stored lists:
#     python -m potato.export --config <this file> --format cultural_domain \
#         --output out/cultural-domain
#
# Adaptations (the original protocol was pencil on paper at schools):
#   - The prompt below is the paper's reported instruction put into second
#     person. The children's actual wording on the day is not in the paper,
#     which is written in English, and the dataset README was not readable
#     when this design was built.
#   - The original sheet had ten numbered rows and let children write more.
#     Here min_items is 1 and no maximum is set, which matches "as many as
#     they could" and the option to keep writing.
#   - Typing replaces handwriting. normalize: true lowercases and trims items
#     in the export only; the stored list is what the participant typed.
#   - The highlighting step (marking which listed birds nest in tree
#     cavities) is left out. Potato has no scheme that shows a participant
#     their own free list for a follow-up marking pass.
#   - Sample items are respondent slots, not real respondents. The raw
#     free lists in the Dryad deposit (freelist_rawdata.csv) are CC0 but the
#     file could not be downloaded without Dryad API credentials, so no real
#     responses are shown here.
#   - The paper's drawing activity and its comparison with field data on
#     trees and nests are not reproduced. The dataset's trees_dissimilarity
#     file is a Morisita dissimilarity between tree-taxon groups, not a triad
#     task, so no triad_test is included.
#
# No model_training block. Potato has no trainer that consumes free_list
# answers, so this design collects lists and exports them for salience
# analysis and does not train anything.

annotation_task_name: "Free-Listing Native Cavity-Nesting Birds (Atlantic Forest)"
task_dir: "."

data_files:
  - sample-data.json

item_properties:
  id_key: "id"
  text_key: "text"

output_annotation_dir: "annotation_output/"
export_annotation_format: "jsonl"

port: 8000

annotation_schemes:
  - annotation_type: free_list
    name: native_birds
    description: "Write down the native birds you know that live in the wild on farms, the ones that first come to mind."
    instructions: >-
      Type one bird name, then press Enter. Write the birds in the order they
      come to mind, because the order is part of the answer. If you know fewer
      than ten, write as many as you can. If you know more than ten, keep
      going.
    min_items: 1
    normalize: true
    label_requirement:
      required: true

user_config:
  allow_all_users: true
  users: []

annotation_instructions: |
  This is a free-listing task. You will see a respondent slot and one list box. Write the native birds you know that live in the wild on farms, in the order they come to mind. There are no right or wrong answers, and nobody is scored on the list.