Studies, questions and responses - QutEcoacoustics/baw-server GitHub Wiki

This gives the ability to present one or more questions about items in a dataset to a user and store the responses. This would be appropriate in a citizen science setting, where users may be answering questions about what kinds of sounds are present in a dataset item, or in a setting where a researcher wants to have volunteers verify a set of annotations. It consists of three entities - Studies, Questions and Responses - which work in association with Datasets and Dataset Items.

Study relates one or more questions to a dataset.

Question

  • contains the wording of the question that the user will be answering.
  • Is associated with one or more studies (many to many). Questions may be reused by different studies (i.e. applied to different datasets), and there might be more than one question per study.
  • has a ‘data’ field that will contain JSON-encoded information that is used to present the question to users. This ‘data’ may include
    • any labels that could be applied to a dataset item,
    • example annotations (library items) that could assist the user
    • Images that should be shown alongside the question or examples
  • Has a “text” which is designed to store the wording of the question

Response contains the answer to a question for a particular dataset item.

  • Each response will be associated with a question record.
  • The data of the response will be stored as a json blob.
    • The JSON blob should make sense in the context of the question, however this is not validated by the rails app and is the responsibility of the client.
    • We will define a JSON schema for responses that we validate against. This doesn’t validate that the response answers its question, only that it conforms to a certain structure.
      • todo: define this schema
  • Each response will be associated with a study.
    • There is a direct association to a study record, since, because questions may be associated with many studies, there is no way to know which study an answer belongs to via the question association.
    • It allows filtering responses for a particular study.
    • A response's question must be associated with the response's study.

Routes

  • Studies
    • index: GET studies/
    • view: GET studies/{id}
    • new: GET studies/new
    • filter GET or POST studies/filter
    • create POST studies
    • update PUT studies/{id}
    • destroy DELETE studies/{id}
  • Questions
    • index:
      • GET questions/
      • GET studies/{study_id}/questions
    • view: GET questions/{id}
    • new: GET questions/new
    • filter GET or POST questions/filter
    • create POST questions
    • update PUT questions/{id}
    • destroy DELETE questions/{id}
  • Responses
    • index:
      • GET responses/
      • GET studies/{study_id}/responses
    • view: GET responses/{id}
    • new: GET responses
    • filter GET or POST responses/filter
    • create
      • POST responses
      • POST studies/{study_id}/questions/{question_id}/responses
    • destroy DELETE responses/{id}

Notes:

  • Standard CRUD routes for all three models.
  • We also allow listing questions via nesting under studies, as it will be rare to list questions for more than one study at once (similar to projects/{project_id}/sites).
  • Likewise, responses can be listed for a particular study via nesting under studies for the same reason.

Permissions

  • Studies
    • NEW, INDEX, FILTER, VIEW all users including guest
    • CREATE, UPDATE, DESTROY admin only (for now)
  • Questions
    • NEW everyone
    • CREATE, UPDATE, DESTROY admin only (for now)
    • INDEX, FILTER, VIEW logged in users only
  • Responses
    • NEW everyone
    • CREATE only logged in user and must have read permission on the audio recording (via dataset item). Although a recording might be publicly available to guests as reader, the user must be logged in to create a response.
    • INDEX, FILTER, VIEW admin or users who are creator
    • DESTROY admin only

Notes:

  • Under normal conditions, responses are not modifiable or deletable after they are created. However, admin can access these routes for maintenance.
  • Since only logged in users will be able to participate in citizen science tasks, the GET actions for questions and responses are limited to logged in users. Study GET requests can be made by anonymous users, as they might need to view information before signing up.
  • In the future there might be need for non-admin users to create and edit studies and questions, however initially this will be limited to admins.