diff --git a/docs/requirements.txt b/docs/requirements.txt index bfd35db9..2c7b27f6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -10,7 +10,7 @@ docutils==0.21.2 h11==0.14.0 idna==3.10 imagesize==1.4.1 -Jinja2==3.1.4 +Jinja2==3.1.6 MarkupSafe==3.0.2 packaging==24.2 Pygments==2.18.0 diff --git a/docs/source/_static/img/individual_responses_table_filtered.png b/docs/source/_static/img/individual_responses_table_filtered.png new file mode 100644 index 00000000..a3fbc7e9 Binary files /dev/null and b/docs/source/_static/img/individual_responses_table_filtered.png differ diff --git a/docs/source/_static/img/individual_responses_table_sorted.png b/docs/source/_static/img/individual_responses_table_sorted.png new file mode 100644 index 00000000..678aa59c Binary files /dev/null and b/docs/source/_static/img/individual_responses_table_sorted.png differ diff --git a/docs/source/_static/img/responses.png b/docs/source/_static/img/responses.png deleted file mode 100644 index 3321d47d..00000000 Binary files a/docs/source/_static/img/responses.png and /dev/null differ diff --git a/docs/source/_static/img/tutorial/after_clicking_message_this_family.png b/docs/source/_static/img/tutorial/after_clicking_message_this_family.png new file mode 100644 index 00000000..742858cd Binary files /dev/null and b/docs/source/_static/img/tutorial/after_clicking_message_this_family.png differ diff --git a/docs/source/_static/img/tutorial/existing_feedback.png b/docs/source/_static/img/tutorial/existing_feedback.png index 96feedd3..d33d4208 100644 Binary files a/docs/source/_static/img/tutorial/existing_feedback.png and b/docs/source/_static/img/tutorial/existing_feedback.png differ diff --git a/docs/source/_static/img/tutorial/feedback.png b/docs/source/_static/img/tutorial/feedback.png index 995196cb..8782b159 100644 Binary files a/docs/source/_static/img/tutorial/feedback.png and b/docs/source/_static/img/tutorial/feedback.png differ diff --git a/docs/source/_static/img/tutorial/individual_responses.png b/docs/source/_static/img/tutorial/individual_responses.png deleted file mode 100644 index 68f0d009..00000000 Binary files a/docs/source/_static/img/tutorial/individual_responses.png and /dev/null differ diff --git a/docs/source/_static/img/tutorial/individual_responses_1.png b/docs/source/_static/img/tutorial/individual_responses_1.png new file mode 100644 index 00000000..8205f063 Binary files /dev/null and b/docs/source/_static/img/tutorial/individual_responses_1.png differ diff --git a/docs/source/_static/img/tutorial/individual_responses_2.png b/docs/source/_static/img/tutorial/individual_responses_2.png new file mode 100644 index 00000000..85b6578d Binary files /dev/null and b/docs/source/_static/img/tutorial/individual_responses_2.png differ diff --git a/docs/source/_static/img/tutorial/response_message_family.png b/docs/source/_static/img/tutorial/response_message_family.png new file mode 100644 index 00000000..9acacdf6 Binary files /dev/null and b/docs/source/_static/img/tutorial/response_message_family.png differ diff --git a/docs/source/_static/img/tutorial/response_parent_id.png b/docs/source/_static/img/tutorial/response_parent_id.png deleted file mode 100644 index 2405c6bb..00000000 Binary files a/docs/source/_static/img/tutorial/response_parent_id.png and /dev/null differ diff --git a/docs/source/_static/img/tutorial/transactional.png b/docs/source/_static/img/tutorial/transactional.png index 00fd85c8..2fa79342 100644 Binary files a/docs/source/_static/img/tutorial/transactional.png and b/docs/source/_static/img/tutorial/transactional.png differ diff --git a/docs/source/_static/img/tutorial/user_opted_out_of_emails.png b/docs/source/_static/img/tutorial/user_opted_out_of_emails.png new file mode 100644 index 00000000..9a06a2df Binary files /dev/null and b/docs/source/_static/img/tutorial/user_opted_out_of_emails.png differ diff --git a/docs/source/_static/img/view_individual_responses_1.png b/docs/source/_static/img/view_individual_responses_1.png new file mode 100644 index 00000000..51c197ba Binary files /dev/null and b/docs/source/_static/img/view_individual_responses_1.png differ diff --git a/docs/source/_static/img/view_individual_responses_2.png b/docs/source/_static/img/view_individual_responses_2.png new file mode 100644 index 00000000..b4731ec0 Binary files /dev/null and b/docs/source/_static/img/view_individual_responses_2.png differ diff --git a/docs/source/_static/img/view_individual_responses_3.png b/docs/source/_static/img/view_individual_responses_3.png new file mode 100644 index 00000000..49738586 Binary files /dev/null and b/docs/source/_static/img/view_individual_responses_3.png differ diff --git a/docs/source/community-participant-recruitment.rst b/docs/source/community-participant-recruitment.rst index 6df3dcd4..5cda6fd1 100644 --- a/docs/source/community-participant-recruitment.rst +++ b/docs/source/community-participant-recruitment.rst @@ -122,7 +122,7 @@ Here are the most important points: - If you have already posted a study on CHS, you can advertise your study directly with a link to your study's page on the CHS website. This way, parents can not only participate in your study but also help science by participating in other studies on CHS. - Use the study link on your study details page (see screenshot below). Even if the family needs to create a CHS account, they'll be redirected back to your study page after registering! - .. image:: ../_static/img/study_link.png + .. image:: _static/img/study_link.png :alt: Study link on study details page - When you advertise your study and the website, consider using our slogan “Fun for families, serious for science”. Both parts of that are good messages: we hope families enjoy these activities, and families should know that they are making a difference to developmental science! @@ -139,10 +139,10 @@ If you have a study on CHS, here are examples of how you might post about it: **Sample Twitter/X Post** -.. image:: ../_static/img/sample_twitter_post.png +.. image:: _static/img/sample_twitter_post.png :alt: Sample Twitter/X post for a CHS study **Sample Facebook Post** -.. image:: ../_static/img/sample_facebook_post.png +.. image:: _static/img/sample_facebook_post.png :alt: Sample Facebook post for a CHS study \ No newline at end of file diff --git a/docs/source/researchers-experiment-data.rst b/docs/source/researchers-experiment-data.rst index c3b7a62f..dff8d74a 100644 --- a/docs/source/researchers-experiment-data.rst +++ b/docs/source/researchers-experiment-data.rst @@ -178,17 +178,73 @@ If the participant repeats a frame (e.g. by navigating using a "previous" button Viewing individual study responses ----------------------------------- -To inspect single responses to your study, navigate to your study and click 'View Responses,' then 'Individual responses'. You must have permission to view this study's responses, which means you must have a Study admin, researcher, or analysis role. (If you can view preview responses, you will be able to access this same page, but only preview data will be included.) +To inspect single responses to your study, navigate to your study and click 'View Responses,' then click the 'Individual Responses' tab. You must have permission to view this study's responses, which means you must have a Study admin, researcher, or analysis role. (If you can view preview responses, you will be able to access this same page, but only preview data will be included.) Responses only show up in this view once you have confirmed that the participant provided informed consent to participate using the Consent Manager. Both preview and real responses will show up here (depending on your permissions), but preview responses are marked with a "P" and say "PREVIEW" in the background of the row. -On the left, you have a list responses to your study, with the child ID, response ID, the study's completion status, and the date they started the study. When you click on a response, the data from that response is shown on the right. You can -download the data from that response in one of several formats: JSON (JavaScript Object Notation, a structured text format); a CSV summary (a "wide format" overview with basic information about the participant and response, such as condition assignment); or CSV frame data (a "long format" detailed list of data collected in each frame during this response, complementary to the CSV summary). +At the top left of the page, you will see information about the number of responses that are available (approved consent), with rejected consent, and that are pending consent judgement. There is also a link to the :ref:`Consent Manager page ` for your study. -.. image:: _static/img/responses.png - :alt: View responses +.. image:: _static/img/view_individual_responses_1.png + :alt: View individual responses (top of page). -Beneath the CSV/JSON response data are any individual videos that are linked to that participant's response. +The table contains information about all responses to your study. The box at the top-right of the page lets you know which response is currently selected. This box shows you any feedback left by the parent during the exit frame (internal studies only). It also contains a link to easily send the family a message about this response (opens the :ref:`Contact Participants page ` in a new browser tab). + +.. image:: _static/img/view_individual_responses_2.png + :alt: View individual responses table. + +.. _box_above_ind_resp_table: +When you click on a response row in the table, details about that response are updated in the box above the table as well as in the "Response details" box at the bottom-right of the page. The bottom-left the page contains options for downloading video and data from this particular response, and for viewing/creating feedback for the family (see section :ref:`"Leaving feedback" `). + +.. image:: _static/img/view_individual_responses_3.png + :alt: View individual responses table. + +Any videos linked to this response will be shown in the "Download videos" box. + +The "Download response" box allows you to download the data from that particular response in one of several formats: + +- **JSON**: JavaScript Object Notation, a structured text format. +- **CSV summary**: a "wide format" overview with basic information about the participant and response, such as condition assignment. +- **CSV frame data**: a "long format" detailed list of data collected in each frame during this response, complementary to the CSV summary. + +.. _using_the_ind_responses_table: + +Using the Individual Responses table +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The table contains the following information about each response: + +- **Child ID**: Child's hashed (study-specific) ID and first name. +- **Response ID** +- **Date**: The date/time when the response was first created, in Coordinated Universal Time (UTC). +- **Time Elapsed**: Time passed since the response was first created. +- **Exit Frame Status**: Whether or not the participant completed the exit frame during this session. Possible values are "Complete" and "Incomplete". Note that this only applies to Internal studies - for external studies it will always be "Incomplete". +- **Payment Status**: Optional, researcher-editable field for tracking the payment status for each session. The possible values are (blank), "Needs review", "To pay", "Do not pay", and "Paid". +- **Session Status**: Optional, researcher-editable field for tracking the session status. The possible values are (blank), "To schedule", "Scheduled", "Session attended", "Session complete", "Follow up", "Communication complete", "Withdrawn or closed". +- **Star**: Optional, researcher-editable field for flagging responses. The stars toggle between an "on" (yellow) and "off" (gray) state. + +**Researcher-editable fields** + +The last three columns in the list above ("Payment Status", "Session Status", "Star") are researcher-editable and completely optional. These columns are meant to help researchers manage the various states of their responses throughout data collection. You can filter/sort/search the table for these values, and they will appear in the response data downloads. These column values do not have any effect on other parts of the platform (e.g. what the participant sees about their response, whether the child is :ref:`counted as "having participated"` in your study). Feel free to use these columns however makes sense for your study and work flow, or just ignore them! + +**Search, filter, and sort** + +The "Search" bar at the top-right of the table will search *all* of the text values in the table, including dates/times and drop-down values, and display any rows that contain a match. The search is case-insensitive and will match partial strings. For example, searching for "john" will match "John", "john", "Johnson", etc. + +You may want to narrow down your search to a specific column. For most columns, you can filter the responses for specific values using the input boxes at the bottom of the column. For "Child ID", "Response ID", and "Time Elapsed", you can start typing and the responses will be filtered based on any partial matches. For "Date", you can click on the empty box to bring up the built-in date range options, or enter a custom date range (select the "None" option to remove the filter). For "Exit Frame Status", "Payment Status", and "Session Status", you can filter using the drop-down options (select the first empty option in the drop-down to remove the filter). + +You can combine multiple search/filters, and they will continue to be applied until you delete or un-select them. The text below the table that tells you your total number of responses will also remind you whenever you are searching/filtering your responses. + +.. image:: _static/img/individual_responses_table_filtered.png + :alt: Text beneath the individual responses table that says "Showing 1 to 8 of 8 entries (filtered from 40 total entries)." + +Similarly, the :ref:`box above the table ` will remind you which response is currently selected. This is useful since the selected response might not be visible if you have searched/filtered the responses. + +There is no way to search on or filter for Preview status or Star column values. However, you can sort the table according to these column values to get e.g. all of the Starred or preview responses at the top of the table. + +.. image:: _static/img/individual_responses_table_sorted.png + :alt: Individual responses table sorting on the preview and star columns. + +Click on the column header to sort the table by that column. Clicking once will sort in ascending order, clicking again will sort in descending order, and clicking a third time will un-sort. The column that is currently sorted will have a small arrow next to the column name. .. _leaving_feedback: diff --git a/docs/source/researchers-start-here.rst b/docs/source/researchers-start-here.rst index 54824195..34699828 100644 --- a/docs/source/researchers-start-here.rst +++ b/docs/source/researchers-start-here.rst @@ -49,7 +49,7 @@ Overview - 15 minute to your first study! ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ An institutional agreement is required to use our online testing platform. Over 100 institutions have already signed agreements. -a) Check whether your institution is listed `here `__. +a) Check whether your institution is listed `here `__. b) Send an email to the CHS team (childrenhelpingscience@gmail.com) to be added to an existing agreement. diff --git a/docs/source/tutorial-contributing.rst b/docs/source/tutorial-contributing.rst index 509b3482..afd36b35 100644 --- a/docs/source/tutorial-contributing.rst +++ b/docs/source/tutorial-contributing.rst @@ -69,6 +69,7 @@ List of tutorial participants .. rst-class:: tutorial-participants +- Fiona DeBernardi (University of Oregon) - Sara Yilmaz (Rutgers University-Newark) - Mohanad Abdelhakem (Minerva University) - Katie Nguyen (Univeristy of Maryland) @@ -355,6 +356,10 @@ List of tutorial participants - Meghan Callahan (Rutgers University - Newark) - Melanie Luximon (Harvard University) - Sana Kulkarni (The University of Texas at Dallas) +- Ian Ferrucci (University of California, Santa Cruz) +- Vanessa Lazaro (University of Chicago) +- Samarrann Sivaloganathan (University of Toronto) +- Denisse Lopez (Harvard University) Checking for and creating issues on Github ------------------------------------------- diff --git a/docs/source/tutorial-manage-data.rst b/docs/source/tutorial-manage-data.rst index dc45264e..7d1d040f 100644 --- a/docs/source/tutorial-manage-data.rst +++ b/docs/source/tutorial-manage-data.rst @@ -160,16 +160,19 @@ This will take you to the "All Responses" page. You will see some other tabs tow On the Individual Responses page, you will see a table where each row represents a single response session. The top (most recent) response will be selected automatically when the page loads. You can click on other rows to view and download information about each response. -Your own response will probably be the top one. To check, with the top row selected, find the "**Response details**" box, and look at the "Parent name" and "Child name" values. This "Response details" box contains various other IDs and some key information taken from the exit survey. Try clicking on other rows in the table to see how the response details change. +.. image:: _static/img/tutorial/individual_responses_1.png + :alt: Individual responses view - top of page. -.. image:: _static/img/tutorial/individual_responses.png - :alt: Individual responses view +Your own response will probably be the top one. To check, with the top row selected, scroll down to the "**Response details**" box below the table, and look at the "Parent name" and "Child name" values. This "Response details" box contains various other IDs and some key information taken from the exit survey. Try clicking on other rows in the table to see how the response details change. + +.. image:: _static/img/tutorial/individual_responses_2.png + :alt: Individual responses view - bottom of page. The "**Download response**" box allows you to download the data from the selected response in JSON or CSV format. -The "**Videos**" box allows you to view and download any videos associated with the selected response. +The "**Download videos**" box allows you to view and download any videos associated with the selected response. -There's also a "**Feedback**" box where you can leave new feedback to the participant and any view existing feedback about this session. The feedback gets displayed to that specific participant on their "Past Studies" page. It's a good place to leave a short but personal thank-you message that shows a human has seen and appreciates their videos. Try it out! Leave a feedback message on your own video. +There's also a "**Give new feedback**" box where you can leave new feedback to the participant and any view existing feedback about this session. The feedback gets displayed to that specific participant on their "Past Studies" page. It's a good place to leave a short but personal thank-you message that shows a human has seen and appreciates their videos. Try it out! Leave a feedback message on your own video. .. image:: _static/img/tutorial/feedback.png :alt: Feedback box @@ -270,18 +273,37 @@ Contact a participant with a gift card code Second, let's imagine that you're compensating participants with gift cards. (You'll want to take a look at the Terms of Use and :ref:`compensation info here ` as you make more detailed plans, but essentially, for now researchers are responsible for handling any compensation by messaging participants.) -From your study details page, click the "Study Responses" button from the menu on the right, then click on the "Individual Responses" tab. Find your response again. Copy the Parent ID from the "Response details" box: +From your study details page, click the "Study Responses" button from the menu on the right, then click on the "Individual Responses" tab. Find your response in the table. With your own response selected, in the box to the top-right of the table, you will see a link that says "Send a message to this family": + +.. image:: _static/img/tutorial/response_message_family.png + :alt: Send message to this family link above the Individual Responses table. + + +.. admonition:: Or copy/paste the Parent ID + + Alternatively, you can copy the Parent ID, go to your study's "Contact Particpants" page, and paste the ID into the Recipients field. The Parent ID can be found in the "Response details" box and in the response data. If you download the data as a JSON file, it's under "participant": "hashed_id", and if you download the data as a CSV file, it's called "participant__hashed_id". -.. image:: _static/img/tutorial/response_parent_id.png - :alt: Parent ID in the Response Details box +Clicking the "Send a message to this family" link will open the "Contact Participants" page in a new tab, with this family as the recipient for a new email. -This same Parent ID can be found in the response data. If you download the data as a JSON file, it's under "participant": "hashed_id", and if you download the data as a CSV file, it's called "participant__hashed_id". +.. image:: _static/img/tutorial/after_clicking_message_this_family.png + :alt: Contact Participants page after clicking "Send message to this family". -Returning to the "Contact Participants" page, let's create another email. This time, you can select the "transactional" button (yellow), which allows you to reach even people who have opted out of email; this is because you sending the compensation is the completion of a "transaction" they agreed to. You will see a warning when you select this option, reminding you that this option is ONLY for completing a transaction. +By default, the message type that is selected is for sending **questions about their response**. This message type should be used if you need to follow up about a technical problem or clarify something about their response. + +.. admonition:: Why did I get this warning when I clicked "Send a message to this family"? + + If the family account that you're trying to contact has opted out of the default message type (questions about their response), then when you click the "Send a message to this family" link, the website will not be able to add that family as a recipient. Instead, you will see a message at the top of the screen letting you know that they have opted out of this message type. + + .. image:: _static/img/tutorial/user_opted_out_of_emails.png + :alt: Warning message when user has opted out of the default email type. + + If you want to send a different message type, then select the appropriate type with the recipients filter buttons and try pasting the Parent ID into the "Recipients" field. You can read more about the message types in the :ref:`"Sending a message" ` section. -Like before, paste in your ID, write your message, send it, and make sure you receive it. (Don't actually send yourself a gift card. Unless you really want to.) +However, because we are sending a gift card, you can select the **transactional** message type (yellow button), which allows you to reach even people who have opted out of email; this is because you sending the compensation is the completion of a "transaction" they agreed to. You will see a warning when you select this option, reminding you that this option is ONLY for completing a transaction. .. image:: _static/img/tutorial/transactional.png :alt: Transactional email +Like before, write your message, send it, and make sure you receive it. (Don't actually send yourself a gift card. Unless you really want to.) + Congratulations! We've covered all the basic functionality you'll need to manage your studies. Finally, we'll wrap up by briefly noting some of the advanced features you might want to use later and revisiting :ref:`Github issues` now that you may have some feature requests or bug reports.