Skip to content

About

A web-based data entry form for World Bird Sanctuary's ethogram observations.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

358 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

WBS Ethogram Data Entry Form

CI codecov Node npm License: MIT PRs Welcome

A web-based data entry form for World Bird Sanctuary's ethogram observations. This tool helps citizen scientists record Sayyida's behaviors during live Twitch streams or when reviewing recorded videos (VODs).

🌐 Live Demo

Current deployment: https://wbs-ethogram-form.vercel.app/

✨ Features

For Observers

  • Live streams & recorded video: Record observations while watching the live Twitch stream or reviewing a recording (VOD).

Time Entry: Always use the timestamp displayed in the top-left corner of the video. The video shows WBS time (America/Chicago, Central Time).

  • Flexible Time Ranges: Observe for any duration from 5 minutes to 1 hour

    • Select any start and end time
    • Automatically generates 5-minute interval slots
    • Times displayed in friendly 12-hour format (e.g., "3:05 PM")
  • Autosave Protection: Your work is automatically saved

    • Form data saved to your browser as you type
    • Draft recovery if you accidentally close the tab
    • Clear draft button when you're done
  • Smart Validation: Catches errors before you submit

    • Inline error messages appear as you fill out the form
    • Auto-scrolls to first error on submit
    • Required fields clearly marked
    • Observer name validation supports Discord/Twitch usernames and full names
    • Copy-to-next validates before copying to prevent bad data
  • Structured Data Entry: Standardized options reduce errors

    • Autocomplete perch location dropdown (type to filter)
    • Interactive perch diagram map (click Map button to view)
    • Behavior-specific interaction dropdowns
    • "Other" text fields when you need them
    • Notes field for additional context
    • Copy-to-next button to duplicate observations across time slots
  • Easy Submission: Multiple ways to get your data to WBS

    • Automatic: Click submit and your observation is sent directly to WBS
    • Share via email: Send a copy to yourself or others after submission
    • Download Excel: Download a local copy for your records
    • Status tracking: Real-time feedback (submitting, success, or error)
    • Error recovery: Retry button for temporary failures, local download fallback

Interaction Sub-fields

When certain behaviors are selected, additional structured fields appear:

  • Interacting with Inanimate Object: Select object type from dropdown (newspaper, rope ball, plastic ball, rubber duck, wooden blocks, camera, plant, stump, perch, or other). If you select "other", a text field appears where you can type what the object is.

  • Interacting with Other Animal: Two dropdowns appear:

    • Animal type: Adult/juvenile aviary occupant, insect within aviary, potential prey animal within aviary, potential prey item outside aviary, same species outside aviary, potential predator outside aviary, or other
    • Interaction type: Watching, preening/grooming, feeding, playing, non-aggressive biting, non-aggressive foot grabbing, or other

    For both fields, selecting "other" reveals a text field where you can specify the custom value.

πŸ“ How to Use This Form

  1. Choose your observation mode: Are you watching the live stream or reviewing a recorded video?

  2. Enter your information:

    • Observer name (your Discord/Twitch username or full name)
    • Date of observation
    • Start and end times for your observation session
  3. Record behaviors: For each 5-minute time slot:

    • Select the behavior you observed
    • Add location if required (perch number or "Ground")
    • For object/animal interactions, select from the dropdown options
    • Add notes if needed
    • Use "Copy to next" to quickly duplicate observations across time slots
  4. Submit: Click the "Submit Observation" button

    • The form validates all required fields
    • Your observation is automatically sent to WBS
  5. After submission:

    • Success: Download a copy or share via email to yourself/others
    • Error: Retry the submission or download locally as a fallback

Your work is automatically saved as you type, so don't worry if you need to take a break!

πŸ”’ Privacy & Data

  • Before submission: Data is saved to your browser's localStorage as you type (autosave)
  • On submission: Observations are sent to the WBS backend API and stored securely
  • What's stored: Observer name, date, times, behaviors, locations, and notes
  • No account required: Anonymous submissions are supported
  • No tracking or analytics: We don't track your browsing behavior

πŸ“Š Data Output Example

The form outputs structured JSON data:

{
  "metadata": {
    "observerName": "YourDiscordName",
    "date": "2025-11-20",
    "startTime": "15:00",
    "endTime": "15:30",
    "aviary": "Sayyida's Cove",
    "patient": "Sayyida",
    "mode": "live"
  },
  "observations": {
    "15:00": {
      "behavior": "resting_alert",
      "location": "12",
      "notes": "",
      "object": "",
      "objectOther": "",
      "objectInteractionType": "",
      "objectInteractionTypeOther": "",
      "animal": "",
      "animalOther": "",
      "animalInteractionType": "",
      "animalInteractionTypeOther": "",
      "description": ""
    },
    "15:05": {
      "behavior": "interacting_object",
      "location": "12",
      "notes": "Playing with newspaper",
      "object": "newspaper",
      "objectOther": "",
      "objectInteractionType": "biting",
      "objectInteractionTypeOther": "",
      "animal": "",
      "animalOther": "",
      "animalInteractionType": "",
      "animalInteractionTypeOther": "",
      "description": ""
    }
  },
  "submittedAt": "2025-11-20T15:32:00.000Z"
}

The per-slot field list is defined canonically by createEmptyObservation() in src/services/formStateManager.js β€” the example above is illustrative.

πŸ› οΈ For Developers

Quick Start

# Clone the repository
git clone https://github.com/iboughtamouse/wbs-ethogram-form.git
cd wbs-ethogram-form

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env and set VITE_WBS_EMAIL to your test email

# Start development server
npm run dev

# Run tests
npm test

Environment Variables

The application requires the following environment variables:

  • VITE_WBS_EMAIL - Email address to receive observation submissions

    • Development: Set to your test email address
    • Production: Configure in Vercel with the WBS research email
  • VITE_API_BASE_URL - Backend API URL

    • Development: Point to local or deployed backend (e.g., http://localhost:3000 or https://your-app.up.railway.app)
    • Production: Configure in Vercel with the production API URL

Documentation

Interested in contributing or learning more? Check out:

πŸ—ΊοΈ Roadmap

Recently Completed:

  • Backend API integration βœ… (November 2025)
  • Email submission (auto-sends Excel to WBS) βœ… (November 2025)
  • Share observation via email βœ… (November 2025)
  • Copy-to-next validation βœ… (November 2025)
  • Excel file export βœ… (November 2025)
  • Accessible loading indicators βœ… (November 2025)

Upcoming Features:

  • Discord OAuth authentication
  • Extended observation periods (24+ hours)
  • Data aggregation & analysis tools
  • Inter-rater reliability calculations

πŸ“„ License

MIT License - Feel free to use and modify for your organization's needs.

πŸ™ Acknowledgments

Built for the World Bird Sanctuary community and the amazing citizen scientists who observe Sayyida!

About

A web-based data entry form for World Bird Sanctuary's ethogram observations.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages