isabella232 / timed-grid-test

Provides an adaptive grid to display items for timed educational assessments such as EGRA and EGMA.

Timed grid test

Description

This field plug-in is designed to help execute timed tests and assessments, where buttons are arranged in grid format. In particular, timed-grid-test is optimal for executing educational assessments like the Early Grade Reading Assessment (EGRA) and the Early Grade Mathematics Assessment (EGMA) on SurveyCTO. See features for a list of supported tests.

Features

The timed-grid-test field plug-in has the following features:

• Appropriate choice list arrangement into a grid or text passage.
• Adaptive button layouts and pagination, depending on screen size.
• A built-in timer for limiting the duration of assessed activities.
• Prompt to prematurely end the test after X number of incorrect answers in line/row 1 of assessed text.
• Prompt to stop the test once the time runs out.
• Prompt to pick the last attempted item for the purpose of scoring.
• Stores sentence progress in the oral reading test.
• Allows completing the test before allotted time has elapsed using the “Finish” button.

For EGRA, the following subtasks are possible:

• Letter identification
• Familiar word reading
• Nonword reading
• Oral reading fluency with comprehension

For details on these tests, please consult the USAID EGRA Toolkit. Also see the Support Center Guide to EGRA on SurveyCTO.

In the case of EGMA, this field plug-in can be used for these subtasks:

• Number identification
• Addition Level 1
• Subtraction Level 1

For details on these tests, please consult the USAID EGMA Toolkit. Also see the Support Center Guide to EGMA on SurveyCTO.

The timed-field-list field plug-in is also useful for certain EGRA and EGMA subtasks.

Data format

This field plug-in supports the select_multiple field type. The field stores the list of items selected, representing items marked incorrect, whilst other test data is stored in the field plug-in's metadata. The metadata is stored in a pipe-separated (|) list. For example:

16714 0 16700|7 14 16|true|17|88|3|85|No|12|1 2 3|18 19 20|0

You can retrieve the specific values with the plug-in-metadata() function in your form design to return the following from these positions in the metadata:

• 0 to 2 - Reserved for internal processing and can safely be ignored. Check this wiki if you are interested in the more technical aspects.
• 3 - Amount of time remaining in seconds.
• 4 - Total number of items attempted.
• 5 - Number of incorrect items.
• 6 - Number of correct items.
• 7 - Whether the firstline was all incorrect.
• 8 - The number of sentence end marks (e.g. periods) passed, as indicated by the last attempted item when using the oral reading test type.
• 9 - The list of correct items.
• 10 - The list of items not attempted/answered.
• 11 - The total number of punctuation marks.

See the use of the plug-in-metadata() function in the sample form for details.

How to use

1. Download the sample form from this repo and upload it to your SurveyCTO server.
2. Download the timed-grid-test.fieldplugin.zip file from this repo, and attach it to the test form on your SurveyCTO server.
3. Make sure to provide the correct parameters (see below).

Parameters

Key	Value
type (required)	Used to specify the kind of test the field plug-in is being used for. This determines the screen layout. You can specify any one of these values: letters - for the EGRA letter reading test. Creates 10 columns. words - for the EGRA nonword or familiar word reading test. Creates 5 columns. reading - for the EGRA reading/comprehension test. Arranges choice list in passage with variable button widths according to the size of words. numbers - for the EGMA number identification test. Creates 5 columns. arithmetic - for the EGMA addition/subtraction level 1 tests. Creates 2 columns. It can also take an integer value which determines the number of columns to display on a screen. This is useful for screens that can accomodate more or fewer columns than the standard tests, as well as cases where the width of items would be better presented in a grid with fewer columns. Simply assign the type an integer value, for example: type = 8.
all-answered (recommended)	Used to define a value to be stored as the fields answer if all the items are correct. This is important because in both EGRA and EGMA subtasks, selections indicate incorrect answers. The all-answered value must also be included in the choice list. If you do not supply an all-answered value, the failsafe behavior is to store the first item in the choice list, but this can be misleading.
page-rows (optional)	Used to specify the number of rows to display on a screen. Like type with an integer value which manages the number of columns, this gives flexibilty on the number of rows that can be displayed on the screen. If more rows are available, paging will automatically be activated. Simply assign the type an integer value, for example: page-rows = 8. Default is 4 rows per page.
duration (optional)	Used to specify the length of the test in seconds. Default is 60 seconds. Enter a custom value as required to override the default as required.
end-after (optional)	Used to specify a limit on the number of consecutive incorrect items that can be marked from the start before being prompted to end the test early. The default is 10 items for the EGRA letter reading test and 5 for the EGRA nonword or familiar reading test, but you can specify a custom value, including 0 to disable. By default, a pop-up is presented to the user, and they can select whether to end the test there, or to continue. If they choose to end the test, they will then be prompted to select the last attempted item, and then they can move forward. A more strict mode is available when the strict parameter is set to 1; in this strict mode, the user is notified with a pop-up saying that the test is ending early, and on acknowledging the popup, they are immediately advanced to the next field.
strict (optional)	Enable to enforce strict adherence to the time limit specified in duration. When strict is enabled (strict = 1), when the timer runs out, no more selections are possible. When strict is off (the default behavior) the user can continue to make selections once time runs out. This will allow slower users to catch up according to what they heard just before time ran out. strict does not prevent the last attempted item from being revised. strict also governs the behavior of end-after (read more above).
finish (optional)	Used to customize the behavior of the finish button. It can take three values: 1 (the default) means the user will be asked to confirm that the subtask is over, and to pick the last attempted item. The user must manually advance to the next screen. 2 means the user will be asked to confirm the subtask is over, and on confirmation, assumes the last attempted item to be the last item in the list. Confirming that the subtask is over automatically advances to the next field. 3 skips the confirmation altogether, assuming the last item attempted to be the last item in the list, and automatically progresses to the next field.
pause (optional)	The default behavior is to not allow pausing a timed EGRA test. However, if you would like the user to be allowed to pause the test, specify pause = 1.

Examples

To create an EGRA letter reading test that stores 99 if all items were correct, allowing 30 seconds, with a strictly observed time limit, and ends if the respondent gets the first 10 letters incorrect, the following would be placed in the appearance column of the spreadsheet form definition:

custom-timed-grid-test(type='letters', all-answered=99, duration=30, strict=1)

If you're using the online form designer, you could simply add the following to the Plug-in parameters properties box:

type='letters', all-answered=99, duration=30, strict=1

Similarly, an EGMA addition level 1 test that stores 99 if all items were correct, and allows 50 seconds would have the following in its appearance column of a spreadsheet form design:

custom-timed-grid-test(type='arithmetic', all-answered=99, duration = 50)

More resources

• Sample form
  You can find a form definition in this repo here:
  extras/sample_form.
• Developer documentation
  More instructions for developing and using field plug-ins can be found here:
  https://github.com/surveycto/Field-plug-in-resources
• User documentation
  How to get started using field plug-ins in your SurveyCTO form.
  https://docs.surveycto.com/02-designing-forms/03-advanced-topics/06.using-field-plug-ins.html
• Support Center guide to EGRA
  How to administer the Early Grade Reading Assessment (EGRA) using SurveyCTO.
  https://support.surveycto.com/hc/en-us/articles/360052796233
• Support Center guide to EGMA
  How to administer the Early Grade Mathematics Assessment (EGMA) using SurveyCTO.
  https://support.surveycto.com/hc/en-us/articles/360052750634