Instrument Coding Guide

HOME > SETUP > INSTRUMENT CODING GUIDE

---

• Code the instrument in PHP
• Generate the MySQL table
• Populate instrument metadata tables
• Register any Examiners
• Testing your instrument
• Update bug tracker

---

A clinical/psychometric/behavioural instrument should likely be coded manually in PHP if it involves:

• dependencies between fields (rules)
• special data formats or restricted types
• special scoring
• look-up tables (t-scores etc)
• age-dependencies in administering the instrument

1. Code the instrument in PHP

   As an example: follow along with NDB_BVL_Instrument_TEMPLATE.class.inc or NDB_BVL_Instrument_mri_parameter_form.class.inc from docs/instruments/ directory. An example of an uploader instrument can be found in the docs/instruments directory.

   1. For a single page, include all questions in main() and delete functions _page[1-9]{}. If the instrument is "paged", add QuickForm elements inside functions _page[1-9].

   2. Wrappers are included in NDB_BVL_Instrument.class.inc e.g. addTextElement(), addYesNoElement(), addTextAreaElement(). See http://pear.php.net/ for Quickform documentation. Many wrappers also use XinRegisterRule.

   3. Element names must be lowercase and fewer than 64 characters (e.g. q07_mother_maiden_name). Never use hyphens - confused with MySQL minus sign. Element names "_status" are reserved for select boxes accompanying text fields

   4. Use addDateElement wrapper for dates. Modify dateTimeFields array to include all date elements for proper conversion to database date/timestamp format.

   5. For multiple-select elements, use _selectMultipleElements array

   6. To ensure instrument completeness for all pages, modify _requiredElements() array to include 'Examiner' field and first question of each page, e.g. $this->_requiredElements=array('Examiner', 'q1', 'q19', 'q37', 'q55')); Array items must be entered to mark instrument as 'Complete'

   7. It may be desirable to exclude certain instrument columns from the Conflict Resolver module, such as Comment fields. These fields should be added to the instrument class array _doubleDataEntryDiffIgnoreColumns within the instrument php file. By default, the base class already excludes the following fields: CommentID, UserID, Testdate, Window_Difference, Candidate_Age, Data_entry_completion_status

2. Generate the MySQL table

   Caveat: this will overwrite the staging file tools/ip_output.txt - this file is also typically used to generate the Data Dictionary.

cd /var/www/$projectname/tools find ../project/instruments/NDB_BVL_Instrument_$TESTNAME.class.inc | php quickform_parser.php

find ../project/instruments/NDB_BVL_Instrument_$TESTNAME.class.inc | php generate_tables_sql.php

In MySQL, source the file that was generated above in project/tables_sql:

```bash
cd /var/www/$projectname/project/tables_sql/ 
log into the mysql database back-end, then:
> source tables_sql/$TESTNAME.sql

Your table is now loaded into the LORIS database schema.

3. Populate instrument metadata tables

   1. Test names:

      INSERT INTO test_names (Test_name, Full_name, Sub_group) VALUES ('$test', '$name', '1');
      

   2. Test subgroups: Tests are organized into one or more Test Subgroups.

      INSERT INTO test_subgroups (ID,Subgroup_name) VALUES (1,'Subgroup_name');
      

   3. Instrument subtests: For pagination of large forms, Subtest_name field must match the page name as defined in the instrument php code (inside case statement for '$this->page').

      INSERT INTO instrument_subtests(Test_name, Subtest_name, Description, Order_number) VALUES ('$test', '$test_page1', '$Test_name', 1);
      

   4. Test battery: Insert a record to define the test battery for any given candidate:

      INSERT INTO test_battery (Test_name, AgeMinDays, AgeMaxDays, Active, Stage, SubprojectID, Visit_label, CenterID) VALUES ('$test', '1', '99999', 'Y', 'Visit', '1', '2', NULL);
      

      Note: In the test_battery table, CenterID and VisitLabel can be unspecified e.g. CenterID = NULL if test is administered across all sites. Each instrument must have (minimum) one entry per Subproject/cohort.

4. Register any Examiners

   See the populate examiners table section.

5. Testing your instrument

   Register or select a DCC candidate whose timepoint/age/cohort will match the instrument test battery criteria.

   If a new timepoint is created for this purpose, the instrument should appear automatically.

   For pre-existing timepoints, see the guide to run the assign_missing_instruments script which will update the populated instruments.

   When testing the instrument, enter sample data of different kinds, test each field and logic constraints.

   In general, for troubleshooting php code, the flag in config.xml can be toggled to '1' or '0' to show or hide MySQL queries. This is never advised for production instances, but can be very useful for debugging on a sandbox installation.

6. Update bug tracker

   It is recommended to add a category to your bug tracker utility (e.g. Mantis) for reports on this instrument.